(0x02) Security Configuration Frames
- Luke Tutty (Unlicensed)
- Tracy W (Deactivated)
- Doug Alguire (Deactivated)
This section describes commands that set and report on security keys.
( PH:0x02, SH:0x03 ) - Install Code Request Command
Overview
The Install Code Request frame is sent by the Host to the Module to query the application Installation Code. It should be noted that the Installation Code is assigned to the Module at production time and cannot be modified.
Payload
This command has no payload.
Effect on Receipt
The Module responds with an Install Code Response
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x04 ) - Install Code Response Command
Overview
The Install Code Response frame is sent by the Module to the Host when queried with an Install Code Request.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0 | Installation Code Length | 8, 10, 14, or 18 as defined by the Zigbee Smart Energy Specification + 2 due to inclusion of CRC |
1..n | Installation Code | MSB First |
Effect on Receipt
None.
Allowed Context
Same context as request.
Sent By Host/Module
Module.
( PH:0x02, SH:0x05 ) - Link Key Write Command
Overview
The Link Key Write command is sent by the Host to the Module in order to set the application Preconfigured Link Key. The Host may only set the Preconfigured Link Key while the application is in the Network Down state.
If the Host subsequently forms a network as a coordinator, the key will be applied as the Global Trust Center Link Key. Otherwise, if the Host joins a network as either a router or end device, the key will be applied as the Joining Key.
The Preconfigured Link Key is not stored in non-volatile memory and must therefore be set prior to forming or joining a network subsequent to a Reset or power-cycle. If the Host does not manually set the key, the application will use the default Preconfigured Link Key specified by the Zigbee Home Automation Specification.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0..15 | Preconfigured Link Key | Default = {0x5A, 0x69, 0x67, 0x42, 0x65, 0x65, 0x41, 0x6C, 0x6C, 0x69, 0x61, 0x6E, 0x63, 0x65, 0x30, 0x39} = “ZigbeeAlliance09” |
Effect on Receipt
The Module will apply this Preconfigured Link Key when it either forms or joins a network, the latter when the Joining Key Option corresponds to Preconfigured Link Key.
Allowed Context
Network Down.
Sent By Host/Module
Host.
( PH:0x02, SH:0x06 ) - Link Key Request Command
Overview
The Link Key Request is sent by the Host to the Module to request the current application Link Key. The Module responds with a Link Key Response. When the Module is configured as a coordinator, it will return the Global Trust Center Link Key. When the Module is otherwise configured and not joined to a network, it will return the Preconfigured Link Key and likewise, when joined to a network, it returns the current Trust Center Link Key assigned to it.
Payload
This command has no payload.
Effect on Receipt
The Module will apply this Preconfigured Link Key when it either forms or joins a network, the latter when the Joining Key Option corresponds to Preconfigured Link Key.
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x07 ) - Link Key Response Command
Overview
The Link Key Response is sent by the Module to the Host when queried with a Link Key Request. The command has the same payload as the Link Key Write command.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0..15 | Preconfigured Link Key | Default = {0x5A, 0x69, 0x67, 0x42, 0x65, 0x65, 0x41, 0x6C, 0x6C, 0x69, 0x61, 0x6E, 0x63, 0x65, 0x30, 0x39} = “ZigbeeAlliance09” |
Effect on Receipt
None.
Allowed Context
Same context as request.
Sent By Host/Module
Module.
( PH:0x02, SH:0x08 ) - Network Key Write Command
Overview
The Network Key Write command is sent by the Host to the Module in order to set the application Preconfigured Network Key. The Host may only set the Network Key while the application is in the Network Down state, after which the key will be automatically randomized.
The Network Key is only applied if the Host subsequently forms a network as a coordinator. If serving as a router or end device, the application will receive a Network Key from the network Trust Center.
The Network Key is not stored in non-volatile memory and must therefore be set prior to forming a network subsequent to a Reset or power-cycle. If the Host does not manually set the key, the application will generate a random value for it upon forming a network.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0..15 | Network Key |
Effect on Receipt
Preconfigured Network Key is set, but is only applied if the Host subsequently forms a network as a coordinator.
Allowed Context
Network Down.
Sent By Host/Module
Host.
( PH:0x02, SH:0x09 ) - Network Key Request Command
Overview
The Network Key Request command is sent by the Host to the Module to query the application Network Key. The Module will respond with a Network Key Response. If the application has not formed a network, the response will convey the Preconfigured Network Key. Otherwise, the response will convey the current Network Key.
Payload
This command has no payload.
Effect on Receipt
The Module will respond with a Network Key Response
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x0A ) - Network Key Response Command
Overview
The Network Key Response command is sent by the Module to the Host when queried with a Network Key Request. The command has the same payload as Network Key Write command.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
0..15 | Network Key |
Effect on Receipt
None.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x02, SH:0x0B ) - Security Profile Write Command
Use at your own risk!
This command can be used to disable the security mechanism that is required for Zigbee 3.0 compliance, specifically for encryption of application-level messages. MMB does not endorse, and accepts no responsibility for, device implementations that opt to use this lower level of security.
Overview
Note: This feature is available in RapidConnect 3.4.x and above.
The Network Security Profile Write command is sent by the Host to the Module to set the security level of the network. The security level must be set before forming or joining the network.
Payload
Byte Index | Field Name | Notes |
|---|---|---|
| 0 | Security Profile | 0 = Zigbee 3.0 (default), 0xFF = no security (not recommended) |
Effect on Receipt
In a multi-network operation, this command sets the security level of the current network context. Each network can be set to a different security profile..
Allowed Context
Network Down.
Sent By Host/Module
Host.
( PH:0x02, SH:0x0C ) - Security Profile Request Command
Overview
Note: This feature is available in RapidConnect 3.4.x and above.
The Security Profile Request command is sent by the Host to the Module to request the security profile.
Payload
This command has no payload.
Effect on Receipt
The Module should respond with the Security Profile Response Command
Allowed Context
All Context.
Sent By Host/Module
Host.
( PH:0x02, SH:0x0D ) - Security Profile Response Command
Overview
Note: This feature is available in RapidConnect 3.4.x and above.
The Security Profile Response command is sent by the Module to the Host in response to the command Security Profile Request. The command conveys the security profile of the network.
In a multi-network operation, this refers to the security level of the current network context.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
| 0 | Security Profile | 0 = Zigbee 3.0 (default), 0xFF = no security (not recommended) |
Effect on Receipt
No action is expected by the Host.
Allowed Context
All Context.
Sent By Host/Module
Host.
( PH:0x02, SH:0x20 ) - Trust Center Install Code Add
Overview
The Trust Center Install Code Add command is sent by the Host to the Module to commission a new device to the network with that install code. This is used in the scenario when Module is configured as a coordinator (trust center) and trying to commission other devices onto the network. Module will use a link key derived from the install code to authenticate the joining device.
Host must add the install codes before opening the permit join window for devices to join.
The install codes are cleared when Module leaves the network, or loses power, or receives the command Clear Trust Center Install Codes.
The maximum number of device install codes that can be added is indicated by Trust Center Install Code Max Count Response(Default size of 3).
NOTE: The Maximum number of devices that can be added by install code at once is 3. Once devices have been commissioned onto the network, the Install Codes should be cleared by sending the 'Clear Trust Center Install Codes' command or waiting 5 minutes for the Install Code table to clear. Once new Install Codes are added using this command, the user should initiate network steering to commission the new devices. Users implementing their own Host application should consider how users will commissioning devices using Install Codes and provide the required interfaces.
NOTE: If a device that joins a network by install code, subsequently leaves the network, the user must re-add the device install code in order for it to join the network by install code again.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
0..7 | EUI64 Address | EUI64 of the device, which the install code belongs to, LSB First |
| 8 | Install Code Size | The size in bytes n of the Installation Code, including the two-byte CRC, where n can be any of |
| 9..8+n | Install Code | MSB First |
Effect on Receipt
Module shall send Status Response with the following list of possible status
| Status Response | Enum | Description |
|---|---|---|
Success | 0x00 | Install code successfully added |
| Invalid Data | 0x02 | Install code is invalid (e.g. invalid length, invalid CRC) |
| Storage Full | 0x04 | Exceeding max number of device install codes that can be added |
Allowed Context
Network Up.
Sent By Host/Module
Host.
( PH:0x02, SH:0x23 ) - Clear Trust Center Install Codes
Overview
The Clear Trust Center Install Codes command is sent by Host to Module to clear all device install codes stored on the Module.
Payload
The command has no payload.
Effect on Receipt
Module clears all install codes.
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x24 ) - Trust Center Install Code Max Count Request
Overview
The Trust Center Install Code Max Count Request command is sent by Host to Module to query the maximum number of install codes that can be stored in the trust center.
Payload
The command has no payload.
Effect on Receipt
Module shall send Trust Center Install Code Max Count Response.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x02, SH:0x25 ) - Trust Center Install Code Max Count Response
Overview
The Trust Center Install Code Max Count Response command is sent by Module to Host in response to Trust Center Install Code Max Count Response.
The payload indicates the maximum number of device install codes that can be stored on the Module.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
0 | Max Count | Max number of install codes that can be stored in the trust center (Default size of 3) |
Effect on Receipt
None.
Allowed Context
Same context as request.
Sent By Host/Module
Module.
( PH:0x02, SH:0x26 ) - Trust Center Security Policy Write
Overview
The Trust Center Security Policy Write command is sent by the Host to the Module to write the Trust Center security policy. The security policies are not saved by Module in non-volatile memory, so it is recommended for the Host to write them during startup configuration after every power-up.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
0 | Require Join By Install Code | Sets the value of the bdbJoinUsesInstallCodeKey parameter as per the Zigbee Base Device specification. 0x00 = False (Default) |
| 1 | Require Key Exchange | Sets the value of the bdbTrustCenterRequireKeyExchange parameter as per the Zigbee Base Device specification. 0x00 = False (Default) |
Effect on Receipt
Module shall send Status Response with the following list of possible status
| Status Response | Enum | Description |
|---|---|---|
Success | 0x00 | Security policies written successfully |
| Invalid Data | 0x02 | data values are invalid |
| Incorrect Length | 0x07 | Requires a payload of at least 2 bytes |
Allowed Context
All contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x27 ) - Trust Center Security Policy Request
Overview
The Trust Center Security Policy Request is sent by the Host to the Module to request for the current Trust Center security policy.
Payload
The command has no payload.
Effect on Receipt
Module shall respond with Trust Center Security Policy Response.
Allowed Context
All contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x28 ) - Trust Center Security Policy Response
Overview
The Trust Center Security Policy Response frame is sent by the Module to the Host in response to Trust Center Security Policy Request.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
0 | Require Join By Install Code | 0x00 = False |
| 1 | Require Key Exchange | 0x00 = False |
Effect on Receipt
None.
Allowed Context
Same context as the request.
Sent By Host/Module
Module.
( PH:0x02, SH:0x29 ) - Trust Center Key Exchange Status Update
Overview
The Trust Center Key Exchange Status Update is sent by the Module to the Host to report the status of key exchange for
- A device that just joined the network(TC) and/or
- A device joining to the network(Device).
At the end of a successful key exchange, the device establishes a unique link key with the TC.
Payload
| Byte Index | Field Name | Notes |
|---|---|---|
0..1 | Device Node ID | |
| 2..9 | Device EUI64 | |
| 10 | Key Exchange Status | See Key Exchange Status Enumerations |
Key Exchange Status Enumerations
| Enum | Name | Failure Status | TC / Requester |
|---|---|---|---|
| 0x00 | EMBER KEY STATUS NONE | No | Requester |
| 0x01 | EMBER APP LINK KEY ESTABLISHED | No | Requester |
| 0x03 | EMBER TRUST CENTER LINK KEY ESTABLISHED | No | Requester |
| 0x04 | EMBER KEY ESTABLISHMENT TIMEOUT | Yes | Requester |
| 0x05 | EMBER KEY TABLE FULL | Yes | Requester |
| 0x06 | EMBER TC RESPONDED TO KEY REQUEST | No | TC |
| 0x07 | EMBER TC APP KEY SENT TO REQUESTER | No | TC |
| 0x08 | EMBER TC RESPONSE TO KEY REQUEST FAILED | Yes | TC |
| 0x09 | EMBER TC REQUEST KEY TYPE NOT SUPPORTED | Yes | TC |
| 0x0A | EMBER TC NO LINK KEY FOR REQUESTER | Yes | TC |
| 0x0B | EMBER TC REQUESTER EUI64 UNKNOWN | Yes | TC |
| 0x0C | EMBER TC RECEIVED FIRST APP KEY REQUEST | Yes | TC |
| 0x0D | EMBER TC TIMEOUT WAITING FOR SECOND APP KEY REQUEST | Yes | TC |
| 0x0E | EMBER TC NON MATCHING APP KEY REQUEST RECEIVED | Yes | TC |
| 0x0F | EMBER TC FAILED TO SEND APP KEYS | Yes | TC |
| 0x10 | EMBER TC FAILED TO STORE APP KEY REQUEST | Yes | TC |
| 0x11 | EMBER TC REJECTED APP KEY REQUEST | Yes | TC |
| 0x12 | EMBER TC FAILED TO GENERATE NEW KEY | Yes | TC |
| 0x13 | EMBER TC FAILED TO SEND TC KEY | Yes | TC |
| 0x1E | EMBER TRUST CENTER IS PRE R21 | No | Requester |
| 0x32 | EMBER TC REQUESTER VERIFY KEY TIMEOUT | Yes | TC |
| 0x33 | EMBER TC REQUESTER VERIFY KEY FAILURE | Yes | TC |
| 0x34 | EMBER TC REQUESTER VERIFY KEY SUCCESS | No | TC |
| 0x64 | EMBER VERIFY LINK KEY FAILURE | Yes | Requester |
| 0x65 | EMBER VERIFY LINK KEY SUCCESS | No | Requester |
Effect on Receipt
None.
Allowed Context
Network Up.
Sent By Host/Module
Module.
Legal Notices
Copyright © 2020 MMB Networks, Inc. All rights reserved.
Confidential materials prepared and delivered by MMB Networks for receipt and review only by any partner subject to a valid and enforceable MMB Networks confidentiality agreement. Any receipt, review, or misuse of any of the content exchanged hereunder by any party not a party to this confidential exchange shall be subject to any and all rights available under the law. All rights, title and interest to the materials shall remain with MMB Networks.
Any suggestions provided to MMB Networks with respect to MMB Networks' products or services shall be collectively deemed “Feedback.” You, on behalf of yourself, or if you are providing Feedback on behalf of your employer or another entity, represent and warrant that you have full legal authority to bind such entity to these terms, agree to grant and hereby grant to MMB Networks a nonexclusive, perpetual, irrevocable, royalty free, worldwide license to use and otherwise exploit such Feedback within any MMB Networks products and services.