-
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 and Acknowledgement Request bit are 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 IEEE 802.15.4 defines two address types: an Extended 64-bit address and a Short 16-bit address.
The extended address for each device never changes and is preprogrammed. It must be an EUI-64 for commercial devices, but can be anything for DIY devices.
The short address is assigned by the hub (PAN Coordinator) to the device during the association process and is only valid until the device remains in the PAN. No two devices can be assigned the same short address.
The short address 0x0000 is reserved for the hub, 0xffff is the broadcast address and 0xfffe is reserved in the IEEE 802.15.4 specifications.
Then PAN identifier 0x0000 is reserved for devices that do not yet belong to a PAN, and 0xffff is the PAN-broadcast address, not used in OSNP but still reserved.
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.
Once the channel and the PAN ID has been selected, the hub has successfully created a PAN and is ready to discover and pair with devices.
Devices not yet associated to a hub must set their PAN ID to 0x0000, which is reserved for devices waiting for association. They scan channels, passively waiting at least 500ms up to 1000ms on each channel for a Device Discovery command. During this period, the radio is always on.
Devices not yet associated can always be in this discovery state. Alternatively, this modus can be made selectable by the user (for example, pressing a button which enables discovery for a period of time, or activating a switch on and off, etc).
The Hub can, periodically or at the command of the user, scan for new devices. The procedure is as follow
- The hub sends, with interval of 250-500ms, Device Discovery commands to the broadcast's address (0xffff) of PAN 0x0000.
- A device receiving this command, must reply with the same Device Discovery command addressed to the Hub and containing its Extended Address as source address. The device can reply multiple times and the hub must be able to handle duplicates. The responding device must stop scanning channels for a period of at least 5s after responding to this command. The hub is allowed to keep sending this command to stop the device from scanning channels again.
- The hub sends, to each responding device, a Data Frame containing the OSNP Get Device Info command packet using the received Extended Address as destination address. The devices must respond to this command with a response packet as defined in the OSNP Application Layer. This is the only Data Frame the device is allowed to respond to before being associated to a PAN. Reception of this command stops channel scanning on the device for at least another 5 seconds.
After device discovery is complete, the hub can, possibly at the user request, start association with one or more of the discovered devices.
After a device has been discovered, it can be associated to the PAN. To do this, the hub must send an Association Request command, secured using the device's association key. How the hub obtains this key is outside the scope of the specifications, however a few implementation ideas are provided for completeness.
Assuming the hub has a user-facing interface, the key could be entered directly be the user in its hexadecimal string representation. The user can find this key either:
- if the device has a screen, it can be generated dynamically and be displayed on the screen;
- if the device has no screen, it can be print on the device or the user manual. Non-security related devices might have the same key for all devices using the same firmware (which simplifies manufacturing). More sensitive devices should have an unique key for each unit.
The Association Request command contains a pair of newly generated AES-128 keys which will be used for further communication with the device. The hub is in charge of generating these using a secure random number generator. The command also contains the short address assigned to the device by the hub.
The device responds with an Association Response command, which confirms that the association was successful. This command also tells the hub whether the device is always receiving or if it poll based. Additionally, the supported security level is included. In the current version, this always indicates the AES-CCM-128 bit suite, which has ID 0x03.
After the association is complete (request/response sent), the device must:
- stop scanning channels
- set its short address to the received one
- start using the received keys to secure future frames
- set the transmission frame counter to 1
- set the reception frame counter to 0
After association, the hub must:
- store the associated device, mapping its extended address to the assigned short address
- start using the received keys to secure future frames
- set the transmission frame counter to 1
- set the reception frame counter to 0
The disassociation procedure can be either explicitly initiated by the hub, sending a Disassociation Notification command or can be silently happened at the device side. The hub must either detect that a device is missing, or allow the user to forcefully remove devices from the list of associated devices without sending a Disassociation Notification command, or at least without expecting an Ack from the device to confirm the removal.
The device can provide several ways to disassociate itself from the PAN. The most basic, is storing association-related information in volatile memory. Another alternative is through a user interface (reset button, menu item, etc). In case of DIY projects this can simply be done by reprogramming device. It is strongly recommended that the device provides a way to disassociate itself from the PAN but keeping in mind eventual security aspects of this action.
Data frames can only be exchanged between the hub and its associated devices (with exception of the Get Device Info command defined in the OSNP Application Layer specifications). All data frames must have the Security Enabled bit set and must provide the source address in its extended form. The destination address is encoded in its short form when the command is sent from the hub to a device and is absent when sent from the device to the hub.
The hub must be always listening on its radio interface, so the device is always allowed to send OSNP Notifications packets (for example). The device can either operate in "always receiving" mode or in "polling" mode. The mode of operation is declared in the Association Response command.
The data frames come from the upper layer of the protocol.
In case of data frames containing a OSNP Command Packet, an OSNP Response Packet will always be sent by the device. The hub cannot send other commands to the device until this response is received. A command can be considered not responded to if the response does not come within a command-specific period of time, which should be no shorter than 500ms. After this timeout expires, the command is considered without response and can be either rescheduled, or an error can be reported to the upper layer. If the device responds, this response is sent to the upper layers for processing. Either the reception of the response or expiry of the timeout, allow the hub to send the next command to that specific device.
The device instead, can send OSNP Notification Packets at any time, the hub will forward them to the upper layer.
When a device is always receiving, the hub can send data frames or MAC commands at any time and expect the device to process them. The device's radio never sleeps and is always ready to receive frames. This mode, although the easiest to implement, is only recommended for devices where response time is very important and for those not powered from batteries.
When a device works in poll mode, the hub cannot send frames as soon as it receives them from the upper layer. It must instead buffer the outgoing frames in a queue. The device operating in polling mode will periodically send Data Request commands. The hub must respond to this command with an Acknowledgment Frame with the Frame Pending bit set in case it has commands in the queue, and with the Frame Pending bit cleared in case no command is in the queue.
When the device receives an ACK with the Frame Pending bit cleared, it can return sleep immediately. When the Frame Pending bit is set, it must remain in the receiving state for at least 500ms.
If the hub has frames to send and indicated this in the ACK, it can start sending the Data or MAC frame in the queue. This frame will also have the Frame Pending bit set if there are more commands waiting to be transmitted in the queue. The device must remaining in the receiving state for at least 500ms after responding to a frame with the Frame Pending bit set.
How often the device sends Data Request commands is outside the scope of these specifications and should be determined as a balance on the power budget of the devices and the requirement for fast response time. Devices which are mainly notification based might very sparingly send Data Request commands while others might need to do it more often to provide good user experience.
The acknowledgment frame confirm the mere reception of a frame. They must be sent whenever a frame is received and its header indicates an ACK is requested. The format of these frames is defined in IEEE 802.15.4. They should be handled by the transceiver hardware directly, with the option of setting/reading the "Frame Pending" bit.
In OSNP, security is mandatory for all data frames, with the exception on the Get Device Info command before the device is associated to a PAN, and for most MAC commands with the exception of PAN Discovery, Device Discovery and Data Request.
-- to be continued --