Introduction to Zigbee R23#

Background#

Zigbee Compliant Platform Revision 23 is a milestone release for the Zigbee specification, and is a step forward towards the next generation of security, reliability, and usability for Zigbee devices. This new release extends the core Zigbee stack with new functionality to enable a more secure network connection and provides more tools for the operation and configuration of centralized networks. R23 represents a long-term effort to incorporate the best features of existing application profiles and aims to align them on top of the latest features and extensions to the core mechanisms of the Zigbee stack.

What's New#

Disclaimer#

While R23 is certifiable at the Zigbee Compliant Platform as of March 2023, at the time of writing (May 2023) Zigbee Base Device Behavior and Application Profiles are in the process of adopting the changes and opening Certification of devices operating on an R23 stack. R23 features will not become widely available for deployment in end products until BDB certifications open with an updated test plan. Our stack offering supports the core R23 features as well as all other optional functionality, and will be available to begin development ahead of the new certification. Devices using R23 will remain totally compatible with existing stacks.

Feature Breakdown#

TLV Payloads#

Revision 23 introduces a new pattern for frame formats with extensible payloads. Some messages may come with 0 or more data elements encoded in Tag-Length-Value format. TLVs are used as a way to encode payload data in a future-compatible format that lets stacks parse what they know and silently pass on encountering unfamiliar data. This means that Zigbee payloads are far more flexible and dynamic.

TLV data is encoded with a 1-byte tag ID to differentiate data formats, 1-byte length, and a variable length value field.

typedef struct {
  /// tag byte
  uint8_t tag_id;
  /// length value (encodes number of value bytes -1)
  uint8_t length;
  /// variable length data field
  uint8_t value[];
} sl_Zigbee_tlv_t;

Zigbee specifies that tags 0-64 are designated "local" and are interpreted based on the message context. Some TLVs are generically used in multiple places and are considered "global". These TLVs are defined in the range 64-254.

The Length byte encodes the number of bytes in the value field -1. This means that a TLV with length field of 3 is expected to contain 4 bytes of data in the value field. When working with TLV structs, using the macros defined in sl_Zigbee_tlv_core.h will perform the -1 offset for you, with the exception of sl_Zigbee_(get|set)_length_raw.

When several TLVs are concatenated together to form a chain, they can be easily traversed by following the length values to the beginning of the subsequent TLV.

Network Commissioning and Joining#

One use of TLVs is to advertise additional data about the network in beacons. This can be used to inform joiners about the capabilities of potential parents and the Trust Center, allowing devices to make more intelligent decisions during the joining process. Using this information a device joining a network with R23 support will initiate the joining process using new Network Commissioning frames. These new commissioning frames support both Joining and Rejoining, and are used to facilitate the new Dynamic Commissioning join flow.

Security And Management ZDO Clusters#

R23 introduces several new clusters to the Zigbee Device Object endpoint. These clusters enable new security features and improve the overall control of devices in Centralized networks.

Beacon Survey#

Issues a request to devices on the network to have them perform an exploratory scan across several channels. During this scan the device will record results and make note of surrounding networks and routers in range that may be candidate targets for joining. This feature is largely based on the existing "survey beacons" command used by some application profiles, with some slight modifications for usability. If you are already using the emberSurveyBeacons API, note that the function signatures have slightly changed for both the entrypoint API and the EmberNetworkFoundCallback callback type supplied to the stack API. For compatibility with the existing APIs use a channelMask argument of 0 when calling emberSurveyBeacons to indicate "only scan the current channel." EmberNetworkFoundCallback callbacks have changed to take an EmberBeaconData structure as an argument, which contains fields for each of the parameters that it replaced (rssi, lqi, senderNodeId, parentPriority).

Get and Set Configuration#

Allows for device configurations and stack metrics to be queried and modified via two new ZDO requests. Get Configuration allows for a device to request the current values for any Global TLVs. Set Configuration allows for remote devices to update several parameters exposed via TLVs. Importantly, the Set Configuration request can toggle a restricted mode, which limits the extent to which the device state can be modified by un-encrypted traffic.

Decommission Device and Clear All Bindings#

In the operation of a Centralized network, when a device is intentionally removed from the network it may be desirable to forcibly clear stale data related to the device from the network. This can help prevent stale data and credentials from being utilized in an unintended way. In these instances, the Trust Center may send a Decommission Device request to have a remote device remove all Link Keys and Bindings referring to a given EUI64.

Similarly a device can be requested to clear Binding Table entries, either per EUI64 or to clear all Binding entries.

Dynamic Link Key Negotiation#

R23 adds new methods for establishing secure Link Keys, utilizing modern Elliptic Curve Cryptography techniques. Utilizing Secured Passphrase Ephemeral Key Exchange with Curve25519, secure link keys can be negotiated with relatively compact, low-footprint public/private key pairs and hashing functions.

These techniques are also used to power the encryption of traffic over Zigbee Direct connections.

Dynamic Link Key Negotiation can be combined with Install Codes, the new Authentication Token, or variable length passphrases as methods of authenticating devices and negotiating Link Keys.

Device Interview#

When Joining using Network Commissioning frames in a Centralized network, if both Trust Center and joining device support Dynamic Link Key (DLK) exchange, a new link key can be securely established before the device is fully joined on the network and sent the Network Key. At minimum this provides protection against passive attacks, listening for network keys sent with known keys, since key values are generated during commissioning and are unique to each negotiation session.

However, after DLK exchange is completed, the Trust Center may choose to delay sending the network key and 'interview' the device by sending sending arbitrary data requests downstream to the joining device, to determine more about its capabilities and characteristics before deciding whether to authorize it.

PAN ID Conflict Detection Changes#

PAN ID conflict detection behavior has been modified to prevent unnecessary network disruption. PAN ID conflicts will no longer initiate unsolicited PAN ID changes across the network. While R23 devices will continue to detect and monitor PAN ID conflicts, a conflict will no longer lead to broadcast Network Reports and Trust Centers will not respond to Network Reports with automatic PAN ID changes. Trust Center applications can still initiate PAN ID changes, and network health can be determined by querying devices with Get Configuration and Survey Beacon Requests.

Link Quality Enhancements#

The Zigbee specification is taking long-term steps towards improving the overall quality and interoperability of routing in Zigbee Mesh Networks. The first steps to this are to begin standardizing around routing metrics and how they are utilized. While the majority of these changes are still under development and are slated to come in future revisions, the Silicon Labs stack offering has begun the process of tuning Ad hoc On-Demand Distance Vector (AODV) routing. Stacks without R23 enabled will see no change in routing.

R23 introduces tweaks to the metrics used to determine the strength and quality of connections on the network. The filtering of Link Quality measurements was adjusted to be more responsive to changes in signal quality.

APS Duplicate Message Rejection#

The Zigbee specification defines a mechanism for dropping duplicate packets at the APS layer to mitigate the availability of various kinds of replay attacks. While this has been a part of the standard for some time, it has been an optional feature and was not provided in the Silicon Labs Zigbee stack. Starting with R23 the APS Duplicate Rejection table has become a mandatory feature, and is now integrated with the main stack libraries. As such the Application Support layer will now begin rejecting incoming unicast packets as duplicates based on a simple CRC checksum. Entries are phased out as new ones come in, dropping the least recently used entry. The number of entries can be configured by modifying the following define SL_ZIGBEE_APS_DUPLICATE_REJECTION_MAX_ENTRIES.

Enabling the R23 Stack for Applications#

While the R23 feature set is available for use in applications, until the BDB certification program opens the use of these features in end-user products is optional and should be reserved for provisional use. Basic support for the new stack features listed above can be enabled through the R23 support component, with Dynamic Link Key and Device Interview support being added via Dynamic Commissioning component.

After enabling the components, behavior can be customized by overriding the application-level callbacks that are defined in sl_zigbee_r23_app_stubs.c

NOTE: The following is not a comprehensive list but offers a view of the kinds of callbacks that can be customized.

/// to enable special handling of the Authentication Token, and Beacon Survey ZDO responses
/**
 * @brief called on reception of a Retrieve Authentication Token response
 */
void sl_zigbee_zdo_retrieve_authentication_token_complete_callback(sl_status_t status);

/**
 * @brief called on reception of a Beacon Survey response.  Arguments contain the results
 * of the survey, including various counters and a list of potential parents to (re)join to
 */
void sl_zigbee_beacon_survey_complete_callback(EmberZdoStatus status,
                                                    sl_zigbee_beacon_survey_results_t *survey_results,
                                                    uint8_t potential_parent_count,
                                                    sl_zigbee_potential_parent_t *potential_parents,
                                                    uint16_t pan_id_conflicts);

/// when enabling Dynamic Commissioning (on Trust Center applications)
/**
 * @brief implements the selection logic when handling requests to negotiate dynamic link keys
 * provides information about the requester, including their supported parameters for key negotiation.
 */
sl_status_t sl_zigbee_zdo_dlk_select_negotiation_parameters(sl_zigbee_address_info *partner,
                                                                 uint8_t their_supported_methods,
                                                                 uint8_t their_supported_secrets,
                                                                 uint8_t *selected_method,
                                                                 uint8_t *selected_secret);