This section describes commands that set and report on security keys.
( PH:0x02, SH:0x00 ) - Preconfigured Key Option Write Command
The Preconfigured Key Option Write command is sent by the Host to the Module and serves to dictate which key the application will use when attempting to join a network; either the Preconfigured Link Key or the key derived from Installation Code.
The application default is to join with the Preconfigured Link Key. This configuration is not stored in non-volatile memory and should therefore be set prior to initiating any Scan and Join activity (i.e., while in the Network Down state) and subsequent to a reset or power-cycle.
Payload for Preconfigured Key Option Write Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Joining Key Option | 0x00 = Join using Preconfigured Link Key |
Effect on Receipt
The Module will apply the chosen key the next time it attempts to join a network. This command only has an effect while Module is in the Network Down state and therefore prior to initiating any scan and join activity.
Allowed Context | Sent By Host/Module |
---|---|
Network Down | Host |
( PH:0x02, SH:0x01 ) - Preconfigured Key Option Request Command
The Preconfigured Key Option Request is sent by the Host to the Module to query the current application Preconfigured Key Option. The Module will respond with a Preconfigured Key Option Response. The command has no payload.
Allowed Context | Sent By Host/Module |
---|---|
All Contexts | Host |
( PH:0x02, SH:0x02 ) - Preconfigured Key Option Response Command
The Preconfigured Key Option Response is sent by the Module to the Host when queried with a Preconfigured Key Option Request. The command has the same payload as the Preconfigured Key Option Write command.
Payload for Preconfigured Key Option Response Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Joining Key Option | 0x00 = Join using Preconfigured Link Key |
Allowed Context | Sent By Host/Module |
---|---|
- | Module |
( PH:0x02, SH:0x03 ) - Install Code Request Command
The Install Code Request frame is sent by the Host to the Module to query the application Installation Code. The Module responds with an Install Code Response. It should be noted that the Installation Code is assigned to the Module at production time and cannot be modified. The command has no payload.
Allowed Context | Sent By Host/Module |
---|---|
All Contexts | Host |
( PH:0x02, SH:0x04 ) - Install Code Response Command
The Install Code Response frame is sent by the Module to the Host when queried with an Install Code Request.
Payload for Install Code Response Command
Byte Index | Field Name | Notes |
---|---|---|
0 | Installation Code Length | 8, 10, 14, or 18 as defined by the Zigbee Smart Energy Specification |
1..n | Installation Code | MSB First |
Allowed Context | Sent By Host/Module |
---|---|
- | Module |
( PH:0x02, SH:0x05 ) - Link Key Write Command
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 for Link Key Write Command
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 | Sent By Host/Module |
---|---|
Network Down | Host |
( PH:0x02, SH:0x06 ) - Link Key Request Command
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. The command has no payload.
Allowed Context | Sent By Host/Module |
---|---|
All Contexts | Host |
( PH:0x02, SH:0x07 ) - Link Key Response Command
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 for Link Key Response Command
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” |
Allowed Context | Sent By Host/Module |
---|---|
- | Module |
( PH:0x02, SH:0x08 ) - Network Key Write Command
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 for Network Key Write Command
Byte Index | Field Name | Notes |
---|---|---|
0..15 | Network Key |
Allowed Context | Sent By Host/Module |
---|---|
Network Down | Host |
( PH:0x02, SH:0x09 ) - Network Key Request Command
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. The command has no payload.
Allowed Context | Sent By Host/Module |
---|---|
All Contexts | Host |
( PH:0x02, SH:0x0A ) - Network Key Response Command
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 for Network Key Response Command
Byte Index | Field Name | Notes |
---|---|---|
0..15 | Network Key |
Allowed Context | Sent By Host/Module |
---|---|
- | Module |
( PH:0x02, SH:0x20 ) - Trust Center Install Code Add
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.
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 | Sent By Host/Module |
---|---|
Network Up | Host |
( PH:0x02, SH:0x23 ) - Clear Trust Center Install Codes
The Clear Trust Center Install Codes command is sent by Host to Module to clear all device install codes stored on the Module.
The command has no payload.
Effect on Receipt
After clearing all device install codes, the Module shall send Status Response with status of Success.
Allowed Context | Sent By Host/Module |
---|---|
All Contexts | Host |
( PH:0x02, SH:0x24 ) - Trust Center Install Code Max Count Request
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.
The command has no payload.
Effect on Receipt
Module shall send Trust Center Install Code Max Count Response.
Allowed Context | Sent By Host/Module |
---|---|
All Contexts | Module |
( PH:0x02, SH:0x25 ) - Trust Center Install Code Max Count Response
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 |
Allowed Context | Sent By Host/Module |
---|---|
- | Module |
( PH:0x02, SH:0x26 ) - Trust Center Security Policy Write
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 | Sent By Host/Module |
---|---|
All Contexts | Host |
( PH:0x02, SH:0x27 ) - Trust Center Security Policy Request
The Trust Center Security Policy Request is sent by the Host to the Module to request for the current Trust Center security policy.
The command has no payload.
Effect on Receipt
Module shall respond with Trust Center Security Policy Response.
Allowed Context | Sent By Host/Module |
---|---|
All Contexts | Host |
( PH:0x02, SH:0x28 ) - Trust Center Security Policy Response
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 |
Allowed Context | Sent By Host/Module |
---|---|
- | Module |
( PH:0x02, SH:0x29 ) - Trust Center Key Exchange Status Update
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. This is only applicable when Module is configured as a coordinator of the network (i.e. as the Trust Center, or TC).
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 |
Allowed Context | Sent By Host/Module |
---|---|
Network Up | Module |