Implementing ZigBee security

The NXP ZigBee PRO APIs allow ZigBee security to be implemented, which applies key-based encryption to communications between network nodes. The message frame content generated at the NWK layer and higher is encrypted using 128-bit AES-based encryption (see Section 2.10). The NWK payload of the frame is encrypted, and the NWK header and payload are integrity-protected with a 32-bit Message Integrity Code (MIC).

This section describes security in a network with centralized security that is managed by a single Trust Centre, which is usually the Coordinator node. A distributed security scheme can alternatively be used and this is described in Section 6.10.2.

The sub-sections below deal with the following topics:

Security levels

Two types or levels of security can be applied in a ZigBee network:

  • Network-level security: This uses a ‘network key’ which is common throughout the network and is used to encrypt/decrypt all communications between all nodes. The network key is randomly generated by the Trust Centre before any nodes join the network. Setting up network-level security is described in Section 5.8.3.1.

  • Application-level security: This uses an application ‘link key’ which is used (in addition to the network key) to encrypt/decrypt communications between a pair of nodes. This link key may be unique for a pair of nodes. Setting up application-level security is described in Section 5.8.3.2.

The encryption keys for these security levels are described in Section 5.8.2.

Parent topic:Implementing ZigBee security

Security key types

The different ZigBee security keys are summarized in the Table, Table 1 and described in more detail below.

When a node joins the network, the Trust Centre must pass the network key to the joining node, so that the node can participate in network-level encrypted communications with existing network nodes. The network key must itself be protected by encryption when it is passed to the joining node. For this encryption, a pre-configured link key is used, which is known by both the Trust Centre and the joining node. This can be a global link key or a unique link key:

  • Pre-configured global link key: This link key is the same for all nodes in the network. It may be ZigBee-defined key or manufacturer-defined:

    • The ZigBee-defined key (known as the ZigBee “09” key) allows nodes from different manufacturers to join the network.

    • A manufacturer-defined key allows only nodes from the specific manufacturer to join the network.

  • Pre-configured unique link key: This link key is an exclusive key for the Trust Centre and joining node. In this case, every node has a different link key.

The pre-configured link key must be pre-programmed into the relevant nodes either in the factory or during commissioning.

The network-level security set-up process is described in Section 6.8.3.1. The active network key can subsequently be changed at any time, as described in Section 6.8.4.

Once network-level security is set up, application-level security can be set up for more secure communications - this level of security is applied on top of network-level security. If application-level security is required between two nodes then a link key must be established for the nodes. This key can be any of the following:

  • Pre-configured global link key (as detailed above): This is for communications between the Trust Centre and all other nodes

  • Pre-configured unique link key (as detailed above): This is for communications between the Trust Centre and one other node

  • Trust Centre Link Key (TCLK): This is for communications between the Trust Centre and one other node. It is randomly generated by the Trust Centre and passed to the relevant node, for which it is encrypted with the network key and, if it exists, the pre-configured unique link key for the node. The TCLK is then used to encrypt all subsequent communications with the Trust Centre, replacing any pre-configured link key. The application should hold on to the pre- configured key, in case it needs to be reinstated in the future (for example, for a re-join).

  • Application link key: This is for communications between a pair of nodes that does not include the Trust Centre. It is requested from the Trust Centre by one of the two nodes. The Trust Centre randomly generates the key and associates it with the IEEE/MAC addresses of the two nodes. The Trust Centre passes the key to each node, for which it is encrypted with the network key and, if it exists, the pre-configured unique link key for the node.

The application-level security set-up process is described in Section 6.8.3.2.

ZigBee security key summary

Security Key

Description

Network-level Security

Network key

- Essential key used to encrypt communications between all nodes of the network
- Randomly generated by the Trust Centre
- Distributed to joining nodes, encrypted with a pre-configured link key (see below)

Application-level Security

Global link key (pre-configured)

- Used between the Trust Centre and all other nodes
- Pre-configured in all nodes (unless a unique link key is pre-configured - see below)
- Also used in joining to encrypt network key transported from Trust Centre to joining node
- If ZigBee-defined, allows nodes from all manufacturers to join the network
- If manufacturer-defined, allows only nodes from one manufacturer to join the network
- Touchlink Pre-configured Link Key is a key of this type
- Distributed Security Global Link Key is a key of this type

Unique link key

Optional key used to encrypt communications between a pair of nodes - may be one of the below categories:

Pre-configured unique link key

- Used between the Trust Centre and one other node
- Pre-configured in Trust Centre and relevant node
- Also used in joining to encrypt network key transported from Trust Centre to joining node
- Install Code-derived Pre-configured Link Key is a key of this type

Trust Centre Link Key (TCLK)

- Used between the Trust Centre and one other node
- Randomly generated by the Trust Centre
- Distributed to node encrypted with network key and pre- configured link key (if any)
- Replaces pre-configured link key (if any) but application must retain the pre-configured key in case it needs to be reinstated

Application link key

- Used between a pair of nodes, not including the Trust Centre
- Randomly generated by the Trust Centre
- Distributed to each node encrypted with network key and pre-configured link key (if any)

Note:

  1. A pre-configured unique link key for a node can be derived from an install code on the Trust Centre using thezps_eAplZdoAddReplaceInstallCodes()function. Install codes are described in the ZigBee 3.0 Devices User Guide (JNUG3131).

  2. In order to use a pre-configured link key in a ZigBee 3.0 application that uses the ZigBee Base Device (see Section 3.4.4, “Device types”), the Base Device attribute bbdbJoinUsesInstallCodeKey must be enabled and set to TRUE. For more information, refer to the ZigBee 3.0 Devices User Guide (JNUG3131).

Parent topic:Implementing ZigBee security

Setting up ZigBee security

This section describes how to set up ZigBee security in your application code. Note that if security is enabled in a ZigBee network then network-level security is always used, while application-level security is optional.

Security is enabled on a node via the device parameter Security Enabledin the ZPS Configuration Editor. Enabling security also enables many-to-one routing toward the Trust Centre, which becomes a network concentrator (see Section 3.5.3).

A Trust Centre must be nominated (see Section 2.8) using the ZPS Configuration Editor. The Coordinator is normally chosen as the Trust Centre. The maximum number of nodes that will require the services of the Trust Centre must be set on the nominated node using the network parameter Route Record Table Sizein the ZPS Configuration Editor (the default number is 4).

Security can be set up in the application code using the function zps_vAplSecSetInitialSecurityState(), which must be called before zps_eAplAfInit() and zps_eAplZdoStartStack() - see Section 6.1.

Note: As an alternative to using the function zps_vAplSecSetInitialSecurityState() in the application code, ZigBee security can be set up in the ZPS Configuration Editor (see Section 6.8.3.1).

Once zps_vAplSecSetInitialSecurityState() has been called and the stack has been started, the stack will automatically manage the subsequent network-level security set-up and implementation.

Network-level security set-up and application-level security set-up are further described in Section 6.8.3.1 and Section 6.8.3.2 respectively.

Note: Certain functionality on the Trust Centre can be disabled using the zps_vSetTCLockDownOverride() function. For more information, refer to the function description.

Network-level security set-up

The function zps_vAplSecSetInitialSecurityState(), described above, initiates the set-up process for network-level security and requires the type of initial security key to be specified as one of:

  • Pre-configured global link key

  • Pre-configured unique link key

These keys are described in Section 5.8.2. They are used to encrypt the network key when it is transported to a joining node.

The Trust Centre and other nodes must be pre-programmed with the relevant pre- configured link key(s). This key can be specified in the application code for the node and referenced by zps_vAplSecSetInitialSecurityState() or can be set through the Key Descriptor parameter Keyin the ZPS Configuration Editor on both the Trust Centre and other node(s). In the case of a unique link key, the IEEE/MAC address of the node must also be pre-programmed into the Trust Centre along with the link key. For the Key Descriptor parameters, refer to Section 11.7.9.

Note: Pre-configured link keys entered via the ZPS Configuration Editor are held in a Key Descriptor Table on the Trust Centre, with one entry for each node/key. The key for a node with a given IEEE/MAC address can be obtained (locally) from this table using the function zps_psGetActiveKey().

The Trust Centre generates a random network key to be used in network-level communications between all nodes. When a new node joins the network, the Trust Centre transports this network key, encrypted using the appropriate pre-configured link key, to the newly joined node.

Note:

  1. The application on the Trust Centre can take control (from the stack) of whether a node is allowed to join the network (possibly using its pre-configured link key) through a user-defined callback function. If required, this callback function must be registered using the function zps_vTCSetCallback(). For more details, refer to the function description.

  2. When a device joins a ZigBee network and requires authentication which involves transporting a network key to it, the parent opens an authentication interval during which the joining device must announce itself to the network. This interval begins from the transmission of a rejoin response (if the device joins through a NWK layer rejoin) or an association response (if it joins through an IEEE 802.15.4 association). If the device fails to announce itself during this interval, the parent removes the Neighbor table entry for the joining device to ensure that the child capacity of the parent is maintained. This authentication interval must be set on all potential parent nodes via the network parameter APS Security Timeout Period (see Section 11.7), which is 1 second by default but 6 seconds is a more reasonable setting.

Parent topic:Setting up ZigBee security

Application-level security set-up

Once network-level security has been set up (as described in Section 6.8.3.1), application-level security can be set up, if required. In application-level security, the communications between two nodes are encrypted/decrypted using a link key which may be global or unique:

  • Global link key: This is shared between all nodes on the network and is pre- configured in all the nodes. Frame counters are not checked for freshness when using a global link key.

  • Unique link key: This is exclusive to a pair of nodes that need to communicate privately. It may be a pre-configured unique link key, Trust Centre Link Key (TCLK) or application link key. Frame counters are checked for freshness to prevent rogue nodes replaying stale messages. This provides the most secure method of application security.

The different types of link key are described in Section 6.8.2 and summarized in Table 4.

In order to set up application-level security with a unique link key between two nodes, the function zps_eAplZdoRequestKeyReq() must be called on one of the nodes to request a link key from the Trust Centre. There are two possibilities:

  • To request a Trust Centre Link Key (TCLK) for communication between the local node and the Trust Centre - the Trust Centre will respond with the requested link key

  • To request an application link key for communication with another node that is not the Trust Centre (in this case, the IEEE/MAC address of the other node must be supplied in the function call) - the Trust Centre will send the requested link key to both nodes

The Trust Centre will ignore the request if the node is not permitted to send APS secured data. The Trust Centre responses are encrypted as follows:

  • If a link key exists for communications between the Trust Centre and the target node (for example, a pre-configured link key), this key and the network key are both used to encrypt the requested link key.

  • Otherwise, only the network key is used to encrypt the requested link key.

On receiving the link key, the ZigBee stack on the node will automatically save the key. The event zps_EVENT_ZDO_LINK_KEY is generated to indicate that the link key is available. Any subsequent unicast or bound data transfer between these two nodes can opt to use this key (zps_E_APL_AF_SECURE_APL).

Note: An application link key can be introduced directly by the application using the function zps_eAplZdoAddReplaceLinkKey().

Note:

  1. When a link key is used to encrypt a data packet, the packet payload is encrypted at the application level using the link key and then the packet is encrypted at the ZigBee stack NWK layer using the network key (therefore, both keys are used).

  2. When application-level security is used in sending data, the IEEE/MAC address and network address of the target node must be available through the local Address Map table - see Section 6.2.3.

Parent topic:Setting up ZigBee security

Parent topic:Implementing ZigBee security

Security key modification

The network key and an application link key can be changed while the network is operating, as described below.

Network key modification

It is possible to store more than one network key on a node, although only one key can be active at any one time. Each network key is identified by means of a unique ‘key sequence number’ assigned by the Trust Centre application.

A new network key can be installed in a node in one of two ways:

  • Distributed by the Trust Centre to one or multiple nodes of the network using the function zps_eAplZdoTransportNwkKey(), which requires the associated key sequence number to be specified

  • Requested from the Trust Centre by calling the function

zps_eAplZdoRequestKeyReq() on the node that needs the network key

On reaching its destination(s), the transported key is automatically saved but not activated. A stored network key can be adopted as the active key using the function zps_eAplZdoSwitchKeyReq(), which is called on the Trust Centre and which identifies the required key by means of its unique sequence number.

Parent topic:Security key modification