Overview
Wireless devices in the network communicate using this custom RF protocol layer. It guarantees reliable transmission of variable size packets to end devices, while being optimized to allow end devices to use as little power as possible. All the while, it ensures that the network remains secure at all times.
It’s primarily designed to work on Silicon Labs chips, atop the RAIL radio abstraction layer; but it should be supported on other devices as well.
General Operation
End devices can be either regular (powered,) which can receive data at any time; and sleepy devices, which turn off their radio receivers to save power. Sleepy devices work like regular device nodes, but may perform more aggressive power saving. This means the coordinator is responsible for buffering packets destined for the device until its next check-in period.
All packets sent over the air are encrypted using an unique session key, which is negotiated when a device associates to the network. Additionally, multicast and broadcast packets are encrypted as well with a shared network key, which is automatically re-generated during the lifetime of the network.
Topology
The network operates as a standard star topology; that is, all devices communicate directly with the coordinator, which sits at the center of the network.
In the future, the network may support a tree-like structure, with powered repeater nodes that forward packets to the central network coordinator.
Radio configuration
Operate in the 915MHz frequency band. The PHY has a single fixed operating mode, intended to be useful for all network configurations:
- Modulation scheme: 2GFSK, 250kbps data rate
- DSSS: Code length 32, spreading factor 8 (4 bits/chip), chip base ????
- TODO: calculate a good base value (take from 802.15.4?)
- Data whitening: Bit 4, PN9 polynomial, seed 0xffff
- Preamble: 32 bits, 01 pattern
- Sync word: ??
- TODO: can this be used as address filtering for devices?
- Forward error correction: None
- Checksum: CCITT_16, seed 0xffff, includes packet header
It’s designed to operate with a high speed crystal frequency of 39MHz.
Each packet will automatically be acknowledged by the stack on reception.
MAC header
Each packet contains a 8 byte header, used by the MAC layer to understand and parse the contents of the packet. This header contains the source and destination addresses (2 bytes each,) a packet type indicator, various flags, and a packet payload length.
Message payloads may be up to 256 bytes in length. Empty packets are not allowed.
Beacons
Coordinators regularly broadcast beacons, which indicate the availability of the network. Networks are identified by a unique 16 byte quantity (such as a UUID) which is programmed into nodes. The beacon in turn contains the short address of the coordinator, and information about supported features in the network.
Additionally, beacons contain notification flags (similar to 802.11 DTIM) for buffered packets for devices in deep sleep mode.
By default, the coordinator emits a beacon every 2.5 seconds.
Security
All messages passed over the network, with the exception of beacon frames, are encrypted. Unicast messages use per node keys, whereas multicast and broadcast keys use per network keys.
All coordinators are provisioned with a public/private keypair. When a device is provisioned onto the network, it receives hashes of all public keys in use by coordinators on the network, which is used so that the device may authenticate the coordinator (which provides its public key) before commencing with the key exchange.
When a node associates to a network, the coordinator and node perform key exchange to derive a unique session key for the node/coordinator. From this session key, separate keys are derived for packets sent from the coordinator to the node, and from the node to the coordinator. Additionally, random data is exchanged for use as an initialization vector for subsequently encrypted packets. Once these keys are collected, secure communication can take place over the network.
In addition to the unicast message keys, the coordinator will share the key used to encrypt multicast/broadcast packets. The coordinator can re-issue this key periodically (called the rekey interval) to improve the network’s security.
Likewise, the node or coordinator can perform a new key exchange at any point during the association.
TODO: Investigate https://github.com/jedisct1/libhydrogen performance
Association
Nodes must associate with (join) a network before they’re able to pass traffic. This is done in several stages:
- Locate best coordinator
The node will scan all supported channels for beacons from coordinators. Beacons from all coordinators with matching network IDs will be stored, and sorted according to their received signal strength.
- Connect to coordinator
Tune to the channel of the coordinator node that was declared “best” earlier, and wait to receive another beacon frame. If this times out, return to step 1.
Otherwise, send an association request (containing our node address and supported protocol version and security modes) to the coordinator, and wait for a response.
- Begin Key Exchange
Coordinator provides its public key, random data, and more network information. The public key is hashed and compared against the allowed list, and if it is allowed, the association continues. Otherwise, it’s aborted, an error is logged, and another coordinator is attempted.
This message also contains information about the network’s authentication mode. If no authentication is implemented, skip to (5).
- Authenticate to network
If the network has security (as indicated by the coordinator’s info message) the appropriate authentication is performed. This will consist of one or more round trips to the coordinator to complete some sort of challenge/response protocol.
Currently, the SCRAM hash-based protocol is supported. In the future, various hardware security backed modes may also be supported.
Once the authentication process is complete, the coordinator will send to the node either an “auth success” or “auth failure” message. On success, go to (5) to continue association; otherwise restart at (1).
- Complete Association
When both sides have exchanged session encryption keys, secure communication can commence. The coordinator will respond to the client’s key exchange message with an encrypted acceptance message, which provides the client information such as its client id, supported power saving modes, and so forth.
The client then responds with an acknowledgement, and requests for any power saving options such as request buffering.
At this stage, the node is considered associated to the network, even if any additional requests from the node are still outstanding (or fail down the line.) Devices remain associated for some time period N after the last successful packet exchange between the coordinator and node. If no packet is received from the node after a period of N, the coordinator will consider the node dead and forcibly disassociate it.
The interval N is configurable, and can vary per device, based on their desired power state.
Once associated, either the coordinator or end node may send a disassociation packet to terminate the session cleanly. Immediately after the disassociation is acknowledged by the coordinator (or device, for a coordinator-initiated disassociation) the disassociation is processed.
When a disassociation takes place, any encryption keys are zeroed and discarded, as well as any buffers and other information is also flushed. This means that packets destined for a sleeping node that missed its check-in window will be lost.