Message structure: Single Packet

Single Packets contain standard IoTize data and/or commands, and also authentication and decryption information to execute these commands or read this data outside a classic session (Login, session key, etc.)

Single Packets are normally used in classic sessions in these cases:

Data Logging: current values of the data grouped into a bundle can be stored into encrypted packets in the IoTize Non-volatile Memory.
Firmware update: the firmware can be updated by a new release from IoTize (with the agreement of the administrator).
Delayed Relay: when a relay (smartphone, potentially malicious) acts as a relay without being able to connect simultaneously to IoTize and the client (cloud), it is necessary to communicate through encrypted Single Packets.
Token: when a TokenServer is used to grant temporary accreditations to users, the Token must be encapsulated in a Single Packet

There are other possible uses for Single Packets. Potentially, they could completely replace the classic session. However, their size and encryption method make them more expensive in terms of computing time, memory and bandwidth. They should therefore only be used when necessary, and preferred in session mode (standard) when possible.

The messages all have the same structure:

SendTime
Header1
Header2
Data
CRC

Any encryption excludes SendTime and header1, but includes everything else.

SendTime

Field	Size	Description
SendTime	4 bytes	Date/Time of sending in relative number of seconds.

SendTime is NOT buffered, and is NOT used for CRC, crypto or other. It is added to the package at the time of shipment, and will be different if re-shipped. A second Time can be included in the data (for example LogTime for DataLogging).

Header1

Header1 consists of 12 unencrypted binary bytes, 32 ASCII-Hex characters:

Field	Size	Description
PacketLength	2 bytes	Total packet size in bytes, NOT including SendTime (but including PacketLength and the rest of the header)
PacketId	2 bytes	Identifier. Counter that is incremented for each DATALOG packet. This reference will be used, among other things, to acknowledge receipt in order to destroy the packets sent.
ConfigVersion	4 bytes	Version of the configuration as specified in the design document[Design - KEOLink.odt - 5.4.1 Object Interface - Resource ID 1024//10]. It is used by the server to ensure data consistency in case of configuration changes.
PacketType	1 byte	Message status: partially consistent with the Settings resource of the DataLogging object. Bit 0 : 1 if it requires an acknowledge. Bit 1: 1 if the data is encrypted. Bit 2: available. Bit 3: available. Bit 4...6: Message type : 0 = reserved 1 = DATALOG 2 = ORDER 3 = CODEEXECUTE(TAP_FW_UPDATE) 4 = prohibited (CONF_UPDATE) 5 = prohibited (SECURITY TOKEN) 6 = EVENT 7 : reserved Bit 7: available.
UserId	1 byte	Information about the sender of the package. Will distinguish a packet issued by the Token Server from a packet issued by the Cloud Server or other, in order to derive the (de)encryption key and access rights.
Salt	2 bytes	Random number

UserId is 1 byte but GroupID lwm2m is 2 bytes. Their relationship is:

UserID < 0x80 => GroupID = UserID
UserID > 0x80 => GroupID = 0xFF00 + UserID
UserID = 0 => Packet not encrypted, without rights (but extended if bit1 of type is 1)
UserID = 0x80 => Error ! (code reserved for future use, prohibited at this time)

Header1 is always in plain text and allows:

To determine the key that is used to code the content (salt, config,...).
Check that a message is not replayed (counter, time,...)
Check if it needs to be subject to special upstream processing (Acknowledge)

The rest of the package (Header2 + Data + CRC) can be encrypted.

Note: Following encryption, the length of the encrypted area may vary (typically, 16-byte alignment). Therefore, the difference between PacketLength and Datasize is unpredictable, contrary to what the tables above might suggest. In the case of an unencrypted packet, the difference between these two lengths is fixed.

Header2

Header2 consists of 6 binary bytes or 12 ASCII-Hex characters:

Field	Size	Description
LogTime	4 bytes	Date/Time of the recording in relative seconds.
Datasize	2 bytes	Message size (Data)

Unlike Header1, Header2 can be encrypted.

Note: Following encryption, the length of the encrypted area may vary (typically, 16-byte alignment). Therefore, the difference between PacketLength and Datasize is unpredictable, contrary to what the above table might suggest. In the case of an unencrypted packet, the difference between these two lengths is fixed.

Note: Like PacketLength, DataSize can be a number of bytes (unencrypted data) or a number of 16-byte blocks (encrypted data) depending on the value of bit-1 of the packet type.

Note: other types of packages have other Header2 formats.

Data

This depends on the type of package (DataLog, Event, Command,...).

CRC

Placed at the end of the package before encryption

Field	Size	Description
Pad	Round ( DataSize + 10) - (DataSize + 10)	Bytes of insignificant content, potentially necessary to align the size of the encrypted area with a multiple of 16 (if encrypted) or 4 (if unencrypted).
CRC	4 bytes	CRC or HMAC of the complete package except SendTime, PacketLength, CRC

Pad: Encryption requires the encrypted area to be a multiple of 16 bytes (128 bit). The CRC operates in multiples of 4 bytes, so it is possible to add up to 15 bytes of padding to make the encrypted area size a multiple of 16 bytes. The content of the padding is not significant,and is not interpreted upon receipt, but it participates in the verification of the packet by being included in the CRC. It may be useful for the transmitter to fill it with random values, to hinder attackers, it could also be filled with constants (all at 0 or all at FF). However, it should not be filled with "stack remnants", or other potentially significant information, that will be seen by the receiver and could provide safety-compromising information.

Sizeof(Pad) = Round16 ( DataSize + sizeof(header2) + sizeof(CRC)) = Round16 ( DataSize + 10)

CRC: The CRC is a 32-bit field. By default, CRC32-Ethernet is used (polynomial = 0x4C11DB7).

Encryption

Everything is encrypted except SendTime and PacketLength (a key is derived from the common master-key + salting). In the descending direction, it is a POST command in lwM2M format that will be reinjected.

The algorithm is the default AES-128.

See the following paragraph for the construction of the encryption key.

Encryption key: SinglePacketKey

SinglePacketKey is the result of hashing the password stored in the configuration file for the Profile referenced by'UserId').

//Todo : hash algorithm to be described.....

Complete unencrypted single packet

Field	Element	Size	Description
SendTime	SendTime	4 bytes	Date/Time of sending in relative number of seconds.
Header1	PacketLength	2 bytes	Total packet size in bytes, NOT including SendTime. The CRC/HMAC starts here.
Header1	PacketId	2 bytes	Packet identifier.
Header1	ConfigVersion	4 bytes	Configuration version.
Header1	PacketType	1 byte	Message type
Header1	SenderId	1 byte	Identifier of the issuer
Header1	Salt	2 bytes	To salt a random number.
Header2	LogTime	4 bytes	Date/Time of the recording in relative seconds.
Header2	Datasize	2 bytes	Message size (Data)
Data	Data	DataSize bytes
Depends on the type of package
CRC	Pad	Round4 ( DataSize + 10) - (DataSize + 10)	Bytes of insignificant content, potentially necessary to align the size of the area verified by CRC with a multiple of 4.
CRC	CRC	4 bytes	CRC of the complete package except SendTime, PacketLength, CRC and Pad

Complete encrypted single packet


Field	SendTime	Header1						Header2		Data	CRC
	SendTime	PacketLength	PacketId	ConfigVersion	PacketType	SenderId	Salt	LogTime	Datasize	Data	Pad	CRC
Size (bytes)	4	2	2	4	1	1	2	4	2	?		4
Used by hashkey (h)		h	h	h	h	h	h
Used by encryption (e)								e	e	e	e	e
Used by CRC (c)			c	c	c	c	c	c	c	c	c

The key (hashage) uses the Header1 fields.

The encrypted area is the Header2 + Data + CRC fields.

The CRC uses fields PacketId throught to Pad inclusive.