Silicon Labs AN1089 Installation Manual
AN1089: Using Installation Codes with
Zigbee Devices
This application note provides an overview of using installation
codes with Zigbee devices. It also explains (with the help of examples) how to use Simplicity Commander to check, write, verify,
and erase installation codes on Silicon Labs Wireless Gecko
(EFR32™) devices. Finally, it provides a complete example of
how to join a Z3 network with an installation code-derived link
key.
Silicon Labs recommends that you be familiar with creating example applications and
using the Network Analyzer, as described in QSG106: Zigbee EmberZNet PRO Quick
Start Guide.
KEY POINTS
• Concepts of the Zigbee installation code
• Programming examples for installation
codes on EFR32 devices
• Checking, writing, verifying, and erasing
installation codes on target devices
• Joining a Z3 network with an installation
code-derived link key
silabs.com | Building a more connected world. Rev. 0.5
AN1089: Using Installation Codes with Zigbee Devices
Installation Code Overview
1. Installation Code Overview
1.1 What Is an Installation Code?
Zigbee installation codes, sometimes also referred to as “install codes,” are provided as a means for a device to join a Zigbee network
in a reasonably secure fashion. The installation code itself is a random value installed on the joining device at manufacturing time, and
is used to encrypt the initial network key transport from the Zigbee network’s centralized Trust Center device (the coordinator) to the
joining device. With the creation of the Zigbee 3.0 standard in late 2016, all Zigbee devices capable of joining networks (as opposed to
forming them) must support the use of installation codes during joining, as this is a requirement for Zigbee 3.0 compliance.
The installation code can be thought of as similar to the PIN code on Bluetooth devices when two devices are paired. The PIN code is
provided as an authorization code for the parent device so that the joining device knows it is receiving information securely, such as
when a hands-free headset is paired to a smartphone.
The installation code is typically printed on the case or packaging of the device, either as a hexadecimal string or in an encoded fashion
such as a barcode or QR code, and provided through an out-of-band mechanism to the Trust Center device or its associated web/cloud
interface, along with the 64-bit IEEE MAC address (“EUI64”) of the device. If this device-specific data is stored on a remote web server
or cloud-based system, that remote system then securely transports that information to the Trust Center to establish security credentials for the joining device in advance of the in-band joining process.
1.2 Caveats for Zigbee Smart Energy (ZSE) Devices
The Trust Center and the joining device use the installation code as a shared key to establish an initial bond of trust allowing the new
device to join the Zigbee network. Once the device has successfully joined the network for which it is authorized, Zigbee requires that
the node negotiate a new Trust Center link key for future secure exchanges with the Trust Center. In standard Zigbee 3.0 networks, this
occurs through a key request directly to the Trust Center. However, in Zigbee Smart Energy networks, which behave differently from
standard Zigbee 3.0 networks, the new Trust Center link key is derived through a special process known as Certificate-Based Key Establishment (CBKE). For more information about the CBKE process, refer to UG103.05: IoT Endpoint Security Fundamentals. Note that
the CBKE process requires installing CBKE data certificates signed by Certicom during the manufacturing process. Refer to AN708:
Setting Smart Energy Certificates for Zigbee Devices for details about how to set these certificate data. Also consult AN714: Smart
Energy ECC-Enabled Device Setup Process for more information about the requirements for preparing Zigbee smart energy (ZSE) de-
vices to be able to join a network and for troubleshooting this process.
This document outlines common practices relating to installation codes for either a standard Zigbee 3.0 device or a ZSE device.
silabs.com | Building a more connected world. Rev. 0.5 | 2
AN1089: Using Installation Codes with Zigbee Devices
Security Use
2. Security Use
An installation code is used to create a preconfigured, link key. The installation code is transformed into a link key by use on an AESMMO hash algorithm. For more information and sample code, consult the Install Codes section of the Security chapter of the Zigbee
Alliance’s Base Device Behavior Specification (Zigbee document #13-0402).
The installation code, while not exactly a secret, cannot be easily guessed by a malicious device that hears the initial exchange between the joining device and the Trust Center. Without knowledge of the installation code and thus the key, the malicious device cannot
decrypt the messages.
The derived Zigbee link key will be known only by the Trust Center and the joining device. The Trust Center uses that key to securely
transport the Zigbee network key to the device. Once the device has the network key, it can communicate at the network layer to the
Zigbee network. It has the ability to perform service discovery and begin the application’s initialization process. In Zigbee 3.0 (non-ZSE)
networks, having the network key is often enough for standard messaging across various clusters. However, ZSE networks have additional restrictions as discussed below. See 7. Example: Joining a Z3 Light to a Z3 Gateway Using an Installation Code-Derived Link Key
for a step-by-step procedure to use an installation code-generated link key for network joining.
The initial link key derived from the installation code does not have full access privileges on a ZSE network. Attempts to use it for Smart
Energy messaging are not allowed and will be ignored by other ZSE devices. Shortly after joining a network, a device must use the Key
Establishment cluster to establish a new link key with the Trust Center via the CBKE process. Only when key establishment completes
successfully will a device have full privileges on the network and be able send and receive certain ZSE messages.
silabs.com | Building a more connected world. Rev. 0.5 | 3
AN1089: Using Installation Codes with Zigbee Devices
Installation Code Format
3. Installation Code Format
While Zigbee smart energy networks allow the installation code to be comprised of either 6-, 8-, 12-, or 16-byte random, hexadecimal
number with a 2-byte CRC appended to the end, Zigbee 3.0 (Z3) networks specifically require 16-byte hexadecimal installation codes,
also accompanied by a 2-byte CRC. Note that the CRC16 should be delivered to the user in little endian byte order, as this is what is
expected when the code is entered into the device that performs the AES-MMO hash algorithm. As far as the user is concerned, the
CRC is part of the installation code and they do not need to know that it is there or why. Therefore, from the user’s point of view, the
length of the install code is 18 bytes (with potentially 8-, 10-, or 14-byte variants possible in ZSE devices).
Manufacturing and managing the list of installation codes will play a part in choosing the size, security, and user experience in installing
the device. A larger installation code size will mean less of a chance of an attacker “guessing” the installation code and eavesdropping
on the initial join. However, smaller installation code is much easier for a user to read off the device during installation.
Note: The Zigbee 3.0 Base Device Behavior Specification requires that you only use a 16-byte installation code. While this may be
more difficult to enter, it provides sufficient strength against an attacker from guessing the installation code and gaining unauthorized
access to network or device.
silabs.com | Building a more connected world. Rev. 0.5 | 4
Loading...