Zigbee 3.0 Security

Zigbee security protects network traffic using 128-bit AES cryptography techniques. A standard security model is defined for supporting authentication and key management Security is a very important factor in designing a mesh network. Digi makes it easy to find the right level of security for your specific application. This ranges from a completely open and unencrypted network to a high security model with out-of-band device registration.

Enabling encryption will also enable source routing with the coordinator acting as a high RAM concentrator by default. For smaller networks (less than 40 nodes) and low-throughput applications, this will not have a significant impact to the network, as source routing will be automatically handled by the XBee application. If deploying a larger network, a full source routing implementation with the coordinator configured as a low RAM concentrator will likely be needed.

Network Key

The network key is used at the network layer for encrypting and decrypting over the air messages. When encryption is enabled, each node on the network is required to have the network key to communicate with other nodes. The network key is shared by every device on the network and only needs to be set on the network coordinator. The NK parameter is used to set a user-defined network key, this parameter is only applicable to a coordinator (CE=1). In most situations the network key should be randomly generated (NK=0) and managed by the network.

If running a centralized trust center, the NK parameter on the trust center can be changed which will propagate to the rest of the network a few seconds later. This is useful for high-security applications where regular network key rotation may be desired. In a distributed trust center, the key is defined when the network is formed and cannot be changed without reforming the network.

Optionally, network keys can be sent and received in-the-clear by setting EO bit 1 (EO=1) on the forming and joining nodes. This is highly discouraged, since it could allow unauthorized devices to obtain a copy of the network key.

Link Key

Link keys are used at the APS layer to provide an extra level of encryption for end-to-end security. The XBee3 zigbee application uses global link keys for both joining and APS-encrypted transmissions. When joining a network with encryption enabled, the network key is is securely exchanged by encrypting it with the link key.

When using a centralized trust center, the link key used to join will be exchanged with a more secure key that is randomly generated by the trust center.

Types of link keys:

Preconfigured link key - Moderate security

Using a preconfigured global link key provides a very simple way to secure a network, this is accomplished by configuring the same write-only KY value on every node on the network. Defining a link key in this manner provides a moderate level of security while allowing for easy network deployment. The security configuration can be done during manufacturing rather than at deployment.

If the joining node has a preconfigured link key that the trust center is not aware of, then it must be registered using an out-of-band method. This is done by issuing a 0x24 registration frame on the trust center, which contains the link key and serial number of the joining device.

Well-known default link key - Low security

The Zigbee alliance specifies a well-known default link key; this is a link key that can be used to allow unsecure devices to easily join a secured network. By default, the XBee3 will reject any device that attempts to join using this well-known key; to allow these devices to join, EO bit 4 (EO=0x10) must bet set on the centralized trust center.

If a joining device has KY=0 (the default) then it will attempt to use the well-known default link key to join.

Install code derived link key - High security

Every device supporting Zigbee 3.0 is required to have an install code. The install code can be read by querying the I? command and it consists of a 16-byte install code + 2 byte CRC. The install code must be read from the joining node and entered to the trust center through an out-of-band method. Typically, the user would read an install code from some type of display or application on the joining node (it cannot be printed on label or physical unit). The user then provides the joiner's install code and serial number to the trust center using a locally issued 0x24 registration API frame and setting bit 0 of the options field.

Using install codes for generating link keys is the most secure method, as it allows the user to clearly identify the joining node to the trust center and it guarantees that each joining device has a random link key.

In order for a joining device to use an install code, DC bit 0 (DC=1) must be set on the joining device. This generates a link key based on the install code and the KY parameter will be ignored.

Join Window

Zigbee imposes a limited window of time in which a network can permit joining; the maximum joining window allowed by the Zigbee specifications is 254 seconds (NJ=0xFE). Whenever the join window is opened, the NJ value of the device that opens the window will be used; this timeout value is not shared by the rest of the network.

The following conditions will cause the network join window to open for NJ seconds:

• A network is formed.
• A router joins the network (this will use the router's NJ value to open the window)
• The commissioning button is enabled (D0=1) and is physically pressed twice on a router or coordinator on the network.
• A CB2 command is issued to a router or coordinator on the network.
• A device is successfully registered to the trust center via 0x24 API frame.

When the join window is opened, a broadcast is sent to the rest of the network. The joining device does not need to be adjacent to the device that opened the joining window.

If NJ is set to 0, then the join window will remain closed unless explicitly opened via commissioning button or CB command. In this scenario, the join window will open for a fixed 60 second period when opened. For a highly-secured network, it's recommended to set NJ to 0 on every device so that the join window is not inadvertently opened.

An always-open join window is permitted (NJ=0xFF), but this will cause the network to operate outside of the zigbee specifications. This option is provided for ease of development and should not be used on the finished product.

Key management

Zigbee defines two security models for key management: centralized security model and distributed security model.

Centralized Security

A centralized trust center network is defined as a zigbee network where one node acts as the centralized key athority. This centralized trust center defines the network key and manages its distribution, determines when and if nodes can join the network, and issues application link keys. Upon formation of the network, the network coordinator assumes the role of the trust center. The trust center will have a reserved address of 0 on the network, any traffic sent to this address will be routed to the trust center.

When a node attempts to join, it first establishes a MAC association with a router on the network. The router than sends a request to the trust center, indicating the node wants to join. The trust center decides if the node can join based on the current join policy (Open join window + EO options). If the trust center approves the attempt to join, the network key is encrypted using a trust center link key and sent to the joining node. The joining node must have a copy of the link key in order to decrypt the network key and successfully join the network.

If the joining node does not have a link key that matches the network or has an install code derived link key, then it must be registered to the trust center. Registration is the means by which a link key is given to the trust center using an out-of-band method. Registration requires the trust center operate in API mode (AP=1 or 2) and cannot be performed in command or transparent mode. 

Distributed Security

A distributed trust center does not have a node designated as a coordinator; all routers in the network have a copy of the network key and are able to authorize joining devices, meaning every router on the network is a trust center. The network key is set at the time the network is formed and cannot change. The network will be formed on the device that has CE=1, and there will be no coordinator on the network (the device forms the network as a router.) This means that any traffic directed to a 0 address will fail.

When a node joins a distributed trust center network, an adjacent router shares a copy of the network key to the joining device. The network key is protected by encrypting the exchange with the joining device with a global link key. The network key can optionally be sent in-the-clear by setting EO bit 1 on every device on the network; this is highly discouraged since it allows un-secure devices access the network key.

Device registration can be performed on a distributed trust center, but the 0x24 registration frame must be issued on a router that is adjacent to the joining device since registration information is not shared with the rest of the network.

Device Registration

When a device attempts to join a secure network, it must obtain a copy of the network key in order to successfully communicate.

The network key can be sent in the clear, but in most situations it will be encrypted with a link key. If the link key is not pre-configured on both devices, then the trust center must be told what link key the joining device will be using to join. Digi calls this process "registration" and is the method by which a link key and serial number of the joining device is securely given to the trust center through the physical serial interface. Because the registration information is not provided over-the-air, this is considered out-of-band registration and provides the highest level of security since the credentials cannot be extracted through RF channels.

Registration is performed using a 0x24 frame and is issued to the trust center (either centralized or distributed). The registration frame is used to register a link key, register an install code derived link key, or remove a previously registered device.

On a centralized trust center (EO=2), registration is transient, meaning that the registered device will only be authorized to join for a fixed period of time. This period is separate from the network join window and is defined by the KT parameter on the centralized trust center. By default, a registered device will be authorized to join for a period of 5 minutes. If the device fails to join within this period, it will need to be re-registered. After joining, it will securely rejoin and does not need to be registered again unless the device is explicitly removed from the network using an NR command or leave request. The 0x24 registration frame must be issued to the centralized trust center in this scenario, routers that are adjacent to the joining device will route the join request to the trust center. The key table entries on a centralized trust center is stored in RAM and is not preserved across a power cycle.

On a distributed trust center (EO=0), registration is persistent, meaning that the registered device will always be authorized to join as long as the join window is open. Registration information is not shared to the rest of the network, so the 0x24 registration frame must be issued to a router that is adjacent to the joining device. Because the link key table has a limited number of entries, you will need to explicitly remove key table entries by de-registering devices using a 0x24 frame after they successfully join in order to add subsequent devices. The key table on a distributed trust center is stored in flash and will persist across a power cycle.

Once a device joins the network and obtains a copy of the network key, it will retain information about the network and perform a secure rejoin if power cycled. If a network parameter is changed on the device, the device receives a leave request, or secure rejoin fails after 3 tries, the device will need to join the network via association which will require registration.

Example: Forming a secure network

The following example will show how to form a secure Zigbee 3.0 network. This is the recommended configuration for most networks, it allows for ease of deployment while also maintaining a moderate level of security.

• Configure an XBee3 device with the following parameters:
  • CE = 1
    • This indicates that the device will attempt to form a network rather than join an existing one.
  • EE = 1
    
    • This enabled encryption for the network.
  • EO = 2
    • This will form the network as a centralized trust center. If a distributed trust center is desired, set this parameter to 0.
    • Any joining device must have the same value set to properly handle any key exchanges that occur.
  • KY = non-zero
    • This will define a pre-configured link key for the network.
    • This key can be configured on joining devices as a pre-configured global link key.
    • If joining devices do not use the pre-configured link key, they will need to be registered to the trust center before joining.
  • NK = 0
    • Using a zero NK value is preferred, as the XBee will generate a random network key that cannot be read.
    • If acting as a centralized trust center, this parameter can be changed after network formation to update the network key for all devices on the network.
  • NJ < 0xFF
    • Define the amount of time you wish to allow devices to join when the join window is opened. This can be modified after the network is formed.

If you wish to increase the level of security for this network, set KY=0 on the forming node. This will generate a random link key that cannot be read and will require every joining device be individually registered. This configuration guarantees that only authorized devices can join the network, as the global link key is obfuscated and cannot be read.

Example: Joining a secure network using a pre-configured link key

The following example will show how to join an existing network that has security enabled, has a pre-configured link key, that was configured on known network. Using this example, it is very easy to deploy a secure network, since each device will be pre-configured to join the network. An installer only needs to worry about opening the join window for new devices.

• Configure a joining XBee3 device with the following parameters:
  • EE = 1
    • The joining node must have the same encryption settings as the network it will be joining.
  • EO = 2
    • If joining a centralized trust center, EO bit 1 must be set so that the joining device is aware that a link key exchange is needed.
    • If joining a distributed trust center, clear EO bit 1.
  • KY = KY from trust center
    • Because the KY value is known, it should be pre-configured on the joining device. As long as the KY values match, it will be able to obtain the network key and join.
  • NJ < 0xFF
    • You should consider the join time that is configured on joining devices... If the device successfully joins the network as a router (SM=0), then it will immediately open the join window for NJ seconds, effectively refreshing it. If you do not wish to reopen the join window like this, then set NJ=0 on all joining devices.

To join the device to the network, the above configuration should be written to flash with a WR command, then brought within RF range of the network.

To open the join window, the commissioning button can be pressed twice on a network router or the trust center. If the push-button is not available, a CB2 command can be issued.

Joining devices will continuously attempt to join a network (unless explicitly told not to via DJ=0 command). However, if you wish to have the module immediately attempt to join, you can press the commissioning button once (or issuing a CB1 command) on the joining node.

Example: Registration of a joining node without preconfigured link key

Using the above example for joining a network... if the joining node is not aware of the link key on the trust center (either is is obfuscated (KY=0) or otherwise unknown to the joining device) then it must be registered to the trust center.

Configure a joining XBee3 device with the following parameters:

• EE = 1
  • The joining node must have the same encryption settings as the network it will be joining.
• EO = 2
  • If joining a centralized trust center, EO bit 1 must be set so that the joining device is aware that a link key exchange is needed.
  • If joining a distributed trust center, clear EO bit 1.
• KY = non-zero value
  • Configure a known link key value for this particular joining device. This value must be known by the installer, since it will need to be passed to the trust center out-of-band.

On the trust center, you must register this device using an API frame. Generate a 0x24 frame that contains the following information:

• The link key (KY) of the joining device
• The serial number of the joining device

When the registration succeeds, the join window is automatically opened for NJ seconds (or 60 seconds if NJ=0).

If the trust center is centralized then this registered key table entry is transient and will expire after KT seconds. In a distributed trust center, it will persist until explicitly cleared.

Example: Registration of a joining node using an install code

In order to provide the highest level of security, using install codes to register devices is recommended. Install codes are randomly assigned to each Zigbee 3.0 device at the factory for the purpose of securely joining a network. The process to register a device using an install code is similar to registering a link key, but with some additional steps...

Configure a joining XBee3 device with the following parameters:

• EE = 1
  • The joining node must have the same encryption settings as the network it will be joining.
• EO = 2
  • If joining a centralized trust center, EO bit 1 must be set so that the joining device is aware that a link key exchange is needed.
  • If joining a distributed trust center, clear EO bit 1.
• DC = 1
  • This tells the joining device to generate a link key from the install code of the device. If this bit is enabled, then the KY parameter is ignored and not used.

On the trust center, you must register this device using an API frame. Generate a 0x24 frame that contains the following information:

• The install code (I?) of the joining device
• The serial number of the joining device

When the registration succeeds, the join window is automatically opened for NJ seconds (or 60 seconds if NJ=0).

If the trust center is centralized then this registered key table entry is transient and will expire after KT seconds. In a distributed trust center, it will persist until explicitly cleared.

Example: De-registering a previously registered device

This is only needed in a distributed trust center as the key table entries are persistent and stored in flash. Because there are only a limited number of entries available, proper management of the key table is required if more than 10 devices will be joining using registration.

To de-register a device, you must issue a 0x24 registration frame on the trust center with the serial number of the registered device and a null (blank) key.

Registration scenario:

It's possible to combine some of the above security features to maintain a high level of security with simplified deployment while also providing a means for authorized devices to securely join via registration.

For example... An established Zigbee network with a centralized trust center is exhibiting some issues that require analysis by a network engineer. Due to the nature of the deployment, the end user does not want to disclose any of the security credentials to the contracted network engineer.

To allow the network engineer onto the network, she must be authorized to join via registration. The network administrator sets the KT parameter on the centralized trust center to 0x7080, which sets the registration timeout to 8 hours. Because the network engineer is not yet on-site, the NJ parameter is set to 0xFF to allow open joining.

A 0x24 frame is issued to the trust center that contains the serial number of the network engineer's device and a one-time-use link key. The network engineer can then use this link key to join the network and perform whatever work is needed.

After the analysis has been performed and the network engineer has left the site, the network administrator closes the join window by setting NJ to 0. Additionally, the network key (NK) on the trust center is updated, which then propagates to the rest of the network further securing the network. De-registration is not needed, as this is a centralized trust center; the temporary link key will expire after KT seconds.