# Transport layer specification
The transport layer defines how messages are transported between devices. All data are named entities and any device on the network can request data using its name. All data carries a frame sequence number and there can only one data-producer per Content Name. The Message Authtication Code field (MAC) is used to verify that the data has not been altered. Bytes are sent in big-endian (network format). Devices MAY implement the Z-Mesh Device Management protocol and SHOULD implement Clear-Channel Assessment (CCA) before transmitting.
Physical layer mapping can be found in this specification.
# Intelligent re-transmits
Devices MUST only re-transmit messages if the TTL (time-to-live) counter is greater that zero. Wireless devices SHOULD only re-broadcast packets with a weak signal strength (RSSI), this minimizes the risk of collisions.
# Frame formats
# Interest and Content frames
Z-Mesh Interest and Content frames has the following format:
| FHDR | Net ID | Content-Name | FCTRL | FSEQ | Payload | MAC |
|---|---|---|---|---|---|---|
| 1 byte | 0/4 bytes | 6 bytes | 1 byte | 3 bytes | 0-N bytes | 4 bytes |
# Frame Header (FHDR)
The frame header specifies:
- Protocol version
- Network ID
- ProxyMe
- Time-to-live
The byte is composed as follows:
| Version | Net ID | ProxyMe | RFU | TTL |
|---|---|---|---|---|
| 7:6 | 5 | 4 | 3 | 2:0 |
The FHDR field and Net ID field (if present) are not included in the MAC calculation. There are two reasons for this: 1) It allows each hop in the mesh to decrement the TTL counter, without recalculating the MAC. And 2) It allows for the replacement of the FHDR with a new header that includes a prefix network address, for routing between networks on the Internet.
# Net ID
If set (to 1), this field indicates that the frame contains the Network Identifier field (Net ID). When this field zero (0), the Net ID field is not present in the frame and indicates that the frame is destined for the local network.
# ProxyMe
A device that goes into sleep can set this bit to indicate to the nearest Content Store, that the nearest Content Store should answer on behalf of the Device. The Content Store MUST then answer authoritatively for queries to this Content Name.
The bit is only valid for Content frames.
# Version
The version field specifies the Z-Mesh message format version.
| Method | Description |
|---|---|
| 0 | Version 0 |
| 1-3 | RFU |
# TTL (Time To Live)
TTL is a 3-bit value specifying how many times this packet may be retransmitted. Every time a device retransmits the packet, this value is decremented. When TTL = 0 the packet MUST not be retransmitted.
# Network Identifier (Net ID)
The 4-byte Network indentifier is obtained from the Z-Mesh alliance. If only used internally, the private range of NetID's can be used. Network IDs can be obtained using this link.
The Net ID define groups of Devices that are allowed to send and receive data. They all share the same Network Key (MAC) key and is therefore allowed to request-, send- or forward data.
The Net ID field is used by Z-Mesh devices when requesting content outside the local network, when communication with a shared Device Management Server.
When a Z-Mesh Device requests content from a different Net ID, a Forwarder will either resolve the physical address (eg. IP address) or the Forwarder will already have the link and foreign MAC-key configured. When forwarding to other Z-Mesh networks, Forwarders will recalculate the MAC using the foreign MAC-key.
Combined with the Content Name, it allows the Content to be uniquely identified:
https://hq-sensornet.my-corp.com/location/cph/floor/1/temp
|------ Hostname ------||--------- Path ---------|
|------- Net ID -------||----- Content Name -----|
Using the URL as equivalent, the Net ID is the hostname part and the Content Name is the Path part. Here the scheme is https, but it could be anything like MQTT or COAP, depending on what the Forwarder supports.
This Net ID field is not included in the MAC calculation.
# Content Name
This field identifies the Interest or Content. Together with the FSEQ, it uniquely identifies the data.
Content Name is fixed lenth (6 bytes) and SHOULD contain the hashed version that the resource identifies. A common scenario is to use an MQTT topic string as data-identifier and then use the hashed version as Content Name.
The Content Name is generated using the hash function Fowler-Noll-Vo hash function (opens new window) FNV-1a 64-bit. The lowest 48 bits of the output hash is used as Content Name. As hashing is one-way, there is no way to determine the readable string version of the topic from Content Name (the hashed version of the topic), this can be seen as a security feature.
An example of a hashed topic could be a temperature sensor that wants to publish a reading to the topic location/cph/floor/1/temp. Here the topic hash bytes becomes dca2e72012e4 in hexadecimal format.
# FCTRL
The Frame Control field (FCTRL) controls:
- The Network key Id (NwkKeyId) used to generate the MAC
- Packet type - Interest, Content or interest return
| NwkKeyId | RFU | Packet type |
|---|---|---|
| 7:6 | 5:4 | 2:0 |
# Network Key Id (NwkKeyId)
The Network Key Id identifies the 128-bit network key used to generate the MAC. Devices MAY store multiple network keys in the event that a new key is rolled out.
There are no requirements to the order in which the numbers are used.
# Packet type
The packet type indicates to the receiver if the payload is a request for content (interest), is content (Content) or is a reply to an interest request (interest return).
| Method | Description | Payload (Arguments) |
|---|---|---|
| 0 | Interest | Timestamp, Interest lifetime |
| 1 | Content | The payload data |
| 2 | Interest return | Type of errror Interest Return below) |
| 3 | Content Announcement | Timestamp |
| 5-7 | RFU |
# Interest message
An Interest message is a request for a Content Object with the name and FSEQ specified in the frame header. If the FSEQ = 0 it is a request for the latest Content Object.
When a device sends an interest packet, the PIT in the Content Stores MUST only note the Content Name and not the FSEQ. If the request is for a future FSEQ (eg. Last FSEQ + 1), it is left to the responding device (content producer) or it's Proxy to determine how to respond to the request:
| FSEQ | Description |
|---|---|
| 0 | Only the Authoritative Content Producer MUST answer this request |
| 1 to Last | Any Content Store MAY respond to this request |
| Last+1 + N | It is up to the Content Producer how to respond |
| 0xFFFFFF (max) | Subscribe to future content |
As an example, say a consuming device is interested in the latest "door" event (open or closed), then the request must be with FSEQ=0 and the Content Producer MAY get then respond with the Last produced (FSEQ=Last) or it MAY produce a new FSEQ (Last+1). If a request is made to Last+1+N, it is left to the implementation of the Content Producing device how to respond. It MAY respond with an Interest return, it MAY also respond with the latest Content object (FSEQ=Last) or it MAY respond with a new Content Object (FSEQ=Last+1).
Only the Content Producer or it's proxy MUST answer Interest requests with FSEQ=0 or with FSEQ=Last+1+N
# Interest message payload
The interest message payload contains a timestamp and an expiration time in seconds, expressed as a 2 byte value.
| Timestamp 6 bytes | Lifetime 2 bytes |
|---|
In order to be resistant to replay attacks, an Interest message contains a Timestamp in milliconds since EPOC. Content Stores MUST only respond to or forward Interest packets that are no more than a few seconds old. The Lifetime value determines how long time the interest is valid. Content Stores MUST keep the Interest in their PIT until Interest has expired. A value of 0 is not valid.
# Content Object
A Content Object is a data object sent in response to an Interest request. A content object MAY be broadcasted without any device requesting it, however it will not be forwarded in the network. Battery driven sensors typically wakes up and broadcast a value or event, listening devices that are within range, need not send an interest packet.
# Interest Return
An Interest return packet MAY be returned by the network. The return code is in the payload field and contains a byte defined as in RFC 8609 section 4.2 (opens new window):
| Type | Description |
|---|---|
| 0x00 | Reserved |
| 0x01 | T_RETURN_NO_ROUTE |
| 0x02 | T_RETURN_LIMIT_EXCEEDED |
| 0x03 | T_RETURN_NO_RESOURCES |
| 0x04 | T_RETURN_PATH_ERROR |
| 0x05 | T_RETURN_PROHIBITED |
| 0x06 | T_RETURN_CONGESTED |
| 0x07 | T_RETURN_MTU_TOO_LARGE |
| 0x08 | T_RETURN_UNSUPPORTED_HASH_RESTRICTION |
| 0x09 | T_RETURN_MALFORMED_INTEREST |
# Content Announcement
Content Announcement make the Z-Mesh network aware of where content is located. Sending out a Content Announcement message, will cause Content Stores (Forwarders) on the Z-Mesh network, to store the (inter)face on which the Content Name is available.
The Payload of the Content Announcement message contains a timestamp in milliconds since EPOC and an expiration time in seconds. As Content Announcement messages are used to update routing tables (FIB), timestamp+expire MUST be checked for validity.
# Frame Sequence number (FSEQ)
The Frame Sequence number field contains a 24-bit number that uniquely identifies the frame sent to a particular Content Name. Sequence numbers are therefore Content-Name specific. FSEQ is used by network devices to detect retransmissions or missing frames. Combined with the message authentication code (MAC) it guards against replay-attacks.
The 24-bit sequence number is large enough for a device to transmit once every second for 194 days before wrapping around (to zero). This allows a network operator at least 6 month to change the Encryption Key, before the devices listening to the topic becomes vulnerable for replay attacks.
# Payload
The Payload is an array of bytes limited in length by the physical layer.
# Message Authentication Code (MAC)
Devices append the message authentication code (MAC) to the frame. MAC is calculated over all fields in the packet, except the frame header (FHDR) and the Net ID field, and attached to the end of the packet. When used, receiving devices SHOULD validate the authenticity and integrity of the data.
The Network key ID (NwkKeyId) set in the FCTRL field specifies which key to use for the MAC calculation. The KeyID and Key itself is provisioned by the Management Server or set manually. The possible options are for MAC calculation options are:
| ID | MAC method | Description |
|---|---|---|
| 0 | AES-128-CMAC-PUBLIC | Publicly known key. Acts as checksum |
| 1 | AES-128-CMAC | Standard AES-128-CMAC calculation |
The 4 bytes MAC are the lowest 32 bits of the 128 bit output.
The public CMAC key is, in hex:
0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88,0x99,0x00,0xAA,0xBB,0xCC,0xDD,0xEE,0xFF
# Payload encryption
The transport layer specification does not specify how payload encryption is done. This is left to the device management specification to define. When used, the FSEQ field MUST be used as part of the IV.