-
Notifications
You must be signed in to change notification settings - Fork 0
Messaging protocol
All frames begin with a Common Header of 5 bytes. The interpretation of the subsequent bytes depends on the IsEncrypted flag.
Used by all frame types. These 5 bytes act as the AAD (Additional Authenticated Data) for encrypted frames.
| Offset | Field | Size | Description |
|---|---|---|---|
| 0 | Header | 1 | Magic Byte (e.g., 0xAA) |
| 1 | Version | 1 | Protocol version (e.g., 0x01) |
| 2 | IsEncrypted | 1 |
0x00: Plaintext/Handshake; 0x01: AES-GCM |
| 3 | DeviceID | 1 | ID of sender/target (0xFF reserved for System/Handshake) |
| 4 | Length (L) | 1 | Size of the Payload (Plaintext) or Ciphertext (Encrypted) |
Used for Discovery, Handshake, and unencrypted commands. Plaintext
+--------+---------+-------------+----------+--------+-------------+-------+
| Header | Version | IsEncrypted | DeviceID | Length | Payload | CRC8 |
| (1b) | (1b) | (0x00) | (1b) | (1b) | (L bytes) | (1b) |
+--------+---------+-------------+----------+--------+-------------+-------+
^--- (Up to 255 bytes) ---^
Total Size:
Used for all secure communication after the handshake. The Header is authenticated via AAD, but only the Payload is secret. Plaintext
+-----------------------+--------------+------------------+--------------+
| Common Header | Nonce | Ciphertext | Tag |
| (5 Bytes) | (12 Bytes) | (L Bytes) | (16 Bytes) |
+-----------------------+--------------+------------------+--------------+
| M | V | 0x01 | ID | L | <--- IV ---> | <--- Secret ---> | <--- MAC --->|
+---+---+------+----+---+--------------+------------------+--------------+
Total Size:
-
Maximum Transmission Unit (MTU): For UDP, ensure total size stays below 508 bytes to avoid IP fragmentation.
-
Maximum Payload:
$255$ bytes (governed by the 1-byte Length field). -
Nonce Uniqueness: The 12-byte Nonce must be unique for every packet sent under the same AES key to prevent cryptographic failure.