SSGSCP Version 0.1
Overview
The Sensor Seal Gateway-Server Communication Protocol (SSGSCP) is an application-layer protocol designed to run on top of UDP, utilizing port 1818 by default. It aims to fit within a single minimum-MTU IP packet to avoid fragmentation and increase efficiency.
Security
SSGSCP employs AES-256 CTR for packet encryption using a 256-bit pre-shared key (PSK). Each packet has a 4-byte integrity check value and 8-byte initialization vector (IV). While SSGSCP is secure for most use cases, despite strong encryption, it is possible for an attacker with sufficient time and resources to
replay
messages. For this reason, SSGSCP is being depracated in favor of WebSocket over TLS in second-generation gateways.
Initiating a Connection
To initiate an SSGSCP session, the client must transmit a
CONN
packet to the server. This packet must be partially encrypted using the Pre-Shared Key (PSK) and Initialization Vector (IV). The Packet ID must be set to 0, the Gateway UID must be the unique identifier of the client's gateway, and the payload must be empty. Concurrently, the client must activate its Retransmission Timer (RTTR).
Accepting a Connection Request
Upon the server's receipt of a
CONN
packet, it must perform decryption on the encrypted segment of the packet, which comprises the concatenated bytes of the Packet Type, Encryption Authentication Code (EAC), Packet ID, Payload Length, and Payload. The EAC is preliminarily set to {0, 1, 2, 3}
and is encrypted along with the subsequent payload bytes. Successful decryption is contingent upon a matching Pre-Shared Key (PSK); the authenticity of decryption is confirmed by the presence of the EAC sequence {0, 1, 2, 3}
in the decrypted block. Should this sequence be verified and the Gateway Unique Identifier (UID) be recognized as authorized against the server's register, the server must transmit a CONNACPT
packet to the client. This packet must have its Packet ID set to zero (0x0000) and contain an empty payload.
The server must operate under the presumption that the
CONNACPT
packet is received by the client unless the client re-initiates authentication, which would occur after its Retransmission Timer (RTTR) surpasses the Retransmission Timeout (RTO). Independently, the server must generate and retain a state machine for the connection in question, uniquely indexed by either the Gateway UID or the pair of the client's remote IP address and source port, to facilitate future packet handling and verification.
Connection Failure
Should the server detect a discrepancy within the decrypted Encryption Authentication Code (EAC) of a
CONN
or MSG-
prefixed packet, specifically if the EAC does not precisely correspond to the byte sequence {0, 1, 2, 3}
, or if the provided Gateway Unique Identifier (UID) does not match any known valid UIDs, the server must respond by dispatching a CONNFAIL
packet. The Packet ID for a CONNFAIL
packet must always be zero (0x0000) and it must carry an empty payload.
The emission of a
CONNFAIL
packet serves as an explicit indication of an authentication failure, where the most common cause is presumed to be a mismatch of the Pre-Shared Key (PSK). In the event that a client, previously authenticated, receives a CONNFAIL
packet, it must disregard said packet. This stipulation is instituted to mitigate against potential deauthentication attacks, where an adversary may attempt to compromise the session by spoofing CONNFAIL
packets.
Conversely, should a client, which has not concluded the authentication process (having not received a
CONNACPT
packet), receive a CONNFAIL
packet, it must mandate a waiting period before recommencing session initiation. This obliges a cooldown interval designed to protect against repeated and rapid connection attempts following an initial failed authentication.
Message Transmission
The protocol defines two distinct message packet types:
MSGCONF
and MSGSTATUS
. MSGCONF
packets are intended for communication from the server to the gateway. Conversely, MSGSTATUS
packets facilitate the transmission of messages from the gateway to the server. For each new message issued by either entity, the Packet ID must be incremented by one. Upon reaching the maximal value of 65535, the Packet ID must reset to zero (0x0000).
To mitigate the risk of processing duplicated messages, which may occur in scenarios where an
RCPTOK
acknowledgement fails to reach the message sender, prompting an unnecessary retransmission, it is recommended that a First-In-First-Out (FIFO) queue or a comparable data structure be employed. This will maintain a record of the most recent message IDs, effectively enabling the receiver to discern and disregard any redundant messages.
Message Acknowledgement
Upon a device's (either client or server) reception of an
MSG-
prefixed packet that bears a properly validated SSGSCP Encryption Authentication Code (EAC), the device must issue a corresponding RCPTOK
packet. The Packet ID within the RCPTOK
packet must be set to match the Packet ID of the received MSG-
packet, thus signaling an acknowledgment of successful message receipt.
Message Retransmission
When a device sends a
CONN
packet or any packet with the Retransmission Timer (RTTR) activated, and the RTTR surpasses the Retransmission Timeout (RTO) without an acknowledgment response (e.g., RCPTOK
with the correct Packet ID for MSG-
packets or CONNACPT
for the CONN
packet), the device must initiate retransmission of that specific packet.
Packet Format
| Offset (B) | Length (B) | Field Name | Field Description |
|---|---|---|---|
| 0 | 6 | Packet Identifier | ASCII characters SSGSCP , designating the packet type. |
| 6 | 8 | Initialization Vector (IV) | Partial (8-byte) IV for AES-256 CTR encryption/decryption. |
| 14 | 4 | Gateway UID | A unique identifier assigned to the gateway. |
| 18 | 1 | Packet Type | Enumeration defining the SSGSCP packet variety. |
| 19 | 4 | Encryption Authentication Code (EAC) | Sequence {0, 1, 2, 3} serving as an integrity check value. |
| 23 | 2 | Packet ID | Sequential identifier employed for acknowledging packets. |
| 25 | 1 | Payload Length | Number of bytes in the packet's payload. |
| 26 | Variable | Packet Payload | Encapsulated data pertinent to the specific Packet Type. |
Note:
- All integer fields within the packet are to be encoded in big-endian format.
- Encryption shall commence from the 18th byte offset using AES-256 CTR mode. The packet's encrypted segment includes the plaintext that follows the predefined byte structure, padded to conform to a 32-bit boundary.
- The Initialization Vector (IV) for AES-256 encryption requires a 16-byte sequence. Within the packet, space is allocated for only the first 8 bytes of this sequence. These bytes contain the necessary entropy and are randomized for each packet. The latter 8 bytes of the IV are fixed to zero and are implicitly known to both sender and receiver, ensuring IV consistency during encryption and decryption processes. Only the randomized 8 bytes are stored in the IV field of the packet.
Packet Types
| Packet Type Name | Packet Type Value | Description | Packet ID | Payload | Start RTTR after Sending? |
|---|---|---|---|---|---|
CONN | 1 | Initiates connection from client. | Fixed at 0. | Empty. | Yes. |
CONNACPT | 2 | Acknowledges connection initiation from server. | Fixed at 0. | Empty. | No. |
CONNFAIL | 3 | Communicates decryption failure by server, suggests PSK mismatch. | Fixed at 0. | Empty. | No. |
RCPTOK | 10 | Acknowledgement of message receipt from client or server. | Matching received message ID. | Empty. | No. |
MSGCONF | 20 | Server to gateway communication. | Sequentially incremented. | Begins with 1-byte message subtype, followed by data. | Yes. |
MSGSTATUS | 21 | Gateway to server communication, may include a status update from a Sensor Seal. | Sequentially incremented. | Begins with 1-byte message subtype, followed by data. | Yes. |