-
Notifications
You must be signed in to change notification settings - Fork 2
OSNP over IEEE 802.15.4
OSNP over IEEE 802.15.4 is designed for embedded and possibly battery powered devices. It provides a way to exchange OSNP Application Layer messages over an IEEE 802.15.4-2003 interface.
The protocol is designed to work with any IEEE 802.15.4-2003 (or above) transceiver, and maintains its frame structure, although it redefines some of its MAC Commands to better fit the needs of an OSNP network.
Security is defined according the IEEE 802.15.4-2003 standard, with additional commands meant to make session persistence resistant to sudden power losses or other events.
If you are not familiar with OSNP yet, please read the OSNP Application Layer specifications first. If you are not familiar with IEEE 802.15.4-2003 standard, I suggest you read that first, but most concepts will be repeated here.
In a 802.15.4 network a device must assume the role of PAN (Personal Area Network) coordinator, which controls communication between all other devices and allocates short addresses. In an OSNP network, this role is performed by the Hub. The Hub always starts a non-beacon enabled PAN. This allows battery powered devices to save power by determining their own duty cycle independently.
Each PAN has its own 2-bytes identifier, which must be unique in the radio range of the hub and its associated devices.
Devices communicate with the hub by exchanging frames.
Unlike most network protocols, the IEEE 802.15.4 header fields are encoded using little-endian.
The frame structure is according the IEEE 802.15.4-2003 standard. This was a practical choice, since many compatible transceiver supporting this frame format exist on the market. In the 2006 version of the standard the security header has been redefined. Since most 802.15.4-2003 transceiver offer hardware encryption/decryption support and many support only the older header format, we decided to use that.
The frame structure is as follow:
| Octets: 2 | 1 | 0/2 | 0/2/8 | 0/2 | 0/2/8 | variable | 2 |
|---|---|---|---|---|---|---|---|
| Frame control | Sequence Number | Destination PAN | Destination Address | Source PAN | Source Address | Payload | FCS |
The frame control is composed of two bytes. For easy of reading, we'll look at them individually, in the same order in which they are encoded in the frame. All reserved bits must be set to 0
| Bit: 0-2 | 3 | 4 | 5 | 6 | 7 |
|---|---|---|---|---|---|
| Frame type | Security Enabled | Frame pending | Ack request | Intra-PAN | Reserved |
OSNP uses 3 of the defined frame types. Their values are
| Value | Type |
|---|---|
| 0x01 | Data |
| 0x02 | Acknowledgment |
| 0x03 | MAC Command |
This bit indicates whether this frame is secured or not
This bit indicates whether the hub has pending frames for the device.
This bit indicates whether an Ack is requested for this frame or not. In OSNP this bit is always set except for commands sent to the broadcast address 0xffff.
This bit is set when the source PAN is equal to the destination PAN and is thus omitted in the header.
| Bit: 0-1 | 2-3 | 4-5 | 6-7 |
|---|---|---|---|
| Reserved | Destination addressing mode | Reserved | Source addressing mode |
Both fields have the same encoding and they indicate how the destination and source addresses, respectively, are written in the header. Their value can be as follows:
| Value | Type |
|---|---|
| 0x00 | PAN and address not present |
| 0x02 | Short address (16-bit) |
| 0x03 | Extended address (64-bit) |
The sequence number is a number incremented by one for each frame sent. It is used to as a reference number to acknowledge frames. This counter is allowed to roll over (i.e. after 255 it will be 0 again)
This is the destination PAN identifier. It is only present if the Destination Addressing Mode is not set to "Address not present"
This is the destination address. It can be either the extended address (8 bytes) or the assigned short address (2 bytes). If the Destination Addressing Mode is set to "Address not present" this field is omitted.
This field is the source PAN identifier. It is only present if the Source Addressing Mode is not set to "Address not present" and the Intra-PAN bit of the Frame Control field is not set.
This is the source address. It can be either the extended address (8 bytes) or the assigned short address (2 bytes). If the Source Addressing Mode is set to "Address not present" this field is omitted.
The payload contains the actual data to be sent. This field has the following format
| Octets: 0/4 | 0/1 | variable | 0/4/8/16 |
|---|---|---|---|
| Frame counter | Key Counter | Data | MIC |
The frame counter is a 32-bit counter and provides protection against replay attacks. It must be incremented at least by one after each sent frame. The hub and the device both have their own counter. This counter is not allowed to roll-over.
This field is only present if the Security Enabled bit of the Frame Control bit is set.
The key counter is one byte and should be set at "0x01" for frames sent from a device to the hub and at "0x10" for frame going from the hub to the device. Any other value is reserved for future use.
This field is only present if the Security Enabled bit of the Frame Control bit is set.
This is the (possibly encrypted) data of the frame. In case of a Data frame, this contains an OSNP packet (command, response or notification). In case of a MAC Command frame, the data depends on the specific command.
This is the Message Integrity code. This field is only present if the Security Enabled bit of the Frame Control bit is set. Its length depends on the security level supported by the device. In this revision only one security level is officially defined and supported, with an 8-byte MIC.
This field is a 2-byte checksum. It is usually appended/verified by the transceiver. It is defined in the IEEE 802.15.4 specifications.
The MAC commands for OSNP are different from the standard IEEE 802.15.4 ones. Although some commands are similar, they are not compatible. This should not be a problem when using standard IEEE 802.15.4 transceiver, since they do not handle these commands directly in their firmware.
MAC command frames have the general frame format, but the first byte of the payload (following eventual security headers) is the command type.
| Command type | Description |
|---|---|
| 0x01 | Association Request |
| 0x02 | Association Response |
| 0x03 | Disassociation Notification |
| 0x04 | Data request |
| 0x05 | PAN Discovery |
| 0x07 | Device Discovery |
| 0x80 | Key update request |
| 0x81 | Key update response |
| 0x82 | Frame counter alignment |
This command is sent from the hub (PAN Coordinator) to the device, usually at the request of the user. This frame must always be secured (Security Enabled bit is set) using the Master Key of the device (which is normally provided directly or indirectly by the user). Addressing mode is set to "Extended Address" for both destination and source address. The frame counter is set to 0.
The command has the following format:
| Octets: 1 | 16 | 16 | 2 |
|---|---|---|---|
| Cmd type (0x01) | Transmission key | Reception key | Assigned short address |
These are randomly generated AES-128 keys, which will be used to secure the next frames. The transmission key of the hub will be used as reception key for the device and the reception key sent by the hub will be used as transmission key by the device.
This is the short address assigned by the hub to the device. It should be unique in the PAN, and cannot be 0xfffe and 0xffff which are reserved.
This command is sent from the device to the hub as response to an association request command to confirm that the association was successful. This command is always sent with the Security Enabled bit set and is the first one sent using the new keys. Addressing mode is set to "No address" for the destination and "Extended address" for the source. The frame counter is 0.
The format of this command is as follows:
| Octets: 1 | 1 | 1 |
|---|---|---|
| Cmd type (0x02) | Device capabilities | Security Level |
This byte currently indicates if the device's radio is always listening or if the communication is poll-driven.
| Bits: 0 | 1-7 |
|---|---|
| RX Always on | Reserved |
The difference between always on and poll driven communication is explained later in the specifications
This byte indicates the security level supported by the device. The only defined in this revision is encoded 0x03 and means AES-CCM-128. This provides AES encryption and an 8-byte long MIC.
This command is sent from the hub (PAN Coordinator) to the device, usually at the request of the user. The Security Enabled bit and Intra-PAN bits are always set. Addressing mode is set to "Short address" for the destination and to "Extended Address" for the source address. This command has no data, so it has the following format:
| Octets: 1 |
|---|
| Cmd type (0x03) |
The device only sends an ACK, which confirms receptions of the command.
This command is sent by poll-driven devices to the hub to inform the hub that the device is ready to receive frames. The Security Enabled bit is not set. Addressing mode is set to "No address" for the destination and to "Short Address" for the source address. This command has no data, so it has the following format
| Octets: 1 |
|---|
| Cmd type (0x04) |
The hub only sends an ACK, either with the Frame Pending bit set indicating that the hub has frames to send or with the Frame Pending bit cleared, which indicates that there is no data.
This command is sent by the hub to check if there is another PAN coordinator using the selected PAN ID. The Security Enabled bit is not set. Addressing mode is set to "Short Address" for both the destination and the source. This command has no data, so it has the following format:
| Octets: 1 |
|---|
| Cmd type (0x05) |
If a hub in the vicinity uses the same PAN ID, it should send an ACK to indicate its presence (which signals the hub originating this command that this PAN ID is busy).
The hub sends this command to the special short PAN ID's (0x0000) broadcast address (0xffff). All devices belonging to PAN 0x0000 respond sending this same command. The Security Enabled bit is not set. Addressing mode is set to "Short Address" for both the destination and the source when the command is sent by the hub. The device will respond using the "Extended Address" mode for the source field. This command has no data, so it has the following format:
| Octets: 1 |
|---|
| Cmd type (0x07) |
This command is sent by the hub to a device to replace the session transmission and reception keys. The hub can send this at any time, usually because the frame counter approaches its limit or because the keys are considered to be compromised. The Security Enabled bit and Intra-PAN bits are always set. Addressing mode is set to "Short address" for the destination and to "Extended Address" for the source address. The format of this command is:
| Octets: 1 | 16 | 16 |
|---|---|---|
| Cmd type (0x80) | Transmission key | Reception key |
The rules about the key usage described for the Association Request command also apply here. The frame counter of the next secured frame will be 1 (not 0).
This command is sent from the device to the hub as response to key update command to confirm that the keys were update. This command is always sent with the Security Enabled bit set and is the first one sent using the new keys. Addressing mode is set to "No address" for the destination and "Extended address" for the source. The frame counter is 0.
The format of this command is as follows:
| Octets: 1 |
|---|
| Cmd type (0x81) |
This command can be sent by either party (hub or device) when it receives a command with a lower frame counter than expected, and tells the other party the expected frame counter. This command is always sent with the Security Enabled bit. Addressing mode is sent to "Short address" for the destination and "Extended address" for the source when the command comes from the hub and to "No address" for the destination and "Extended address" for the source when it comes from a device. The command has the following format:
| Octets: 1 | 4 |
|---|---|
| Cmd type (0x82) | Expected frame counter |
The receiving party shall only accept the new frame counter if it is higher than its own (i.e. the counter can only be incremented, never decremented).
The hub is responsible for creating a new PAN, to which the devices will then be associated. The hub can choose any of the available channels defined in the IEEE 802.15.4 standard. It is advisable that the hub performs an energy detection scan of all channel and choose the one with less interference.
The extended address of a hub should be an EUI-64. For non-commercial implementations which do not need to be distributed (i.e. for personal/home/office use), a random number can be chosen.
The short address of the hub is always 0x0000.
The hub is also responsible of choosing a PAN Identifier. The PAN Identifiers 0x0000 and 0xffff have a special meaning and cannot be used as PAN Identifier.
The hub can use any criteria to choose the PAN Identifier, but it should first check that this identifier is not already in use by another PAN Coordinator.
To do this, the hub does the following:
- sets its own PAN Identifier to 0x0000.
- sends 2 or more PAN Discovery commands, spaced by at least a 500ms interval, to the PAN coordinator of the selected PAN.
- if no acknowledgment is received, the PAN identifier can be considered free and is assigned. Otherwise a different PAN ID should be selected and the procedure should restart from point 1.
--- to be continued ---