Versions Compared

Old Version 18

changes.mady.by.user Luke Tutty

Saved on

compared with

New Version 19

changes.mady.by.user Luke Tutty

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This section describes commands that set and report on security keys.


Panel
titleSecondary Headers

Table of Contents
maxLevel2
minLevel2



Panel
titlePrimary Headers

Page Tree
rootFrame Payload Definitions
spacesSPRC2

Section Column
width100%

( PH:0x02, SH:0x00 ) - Preconfigured Key Option Write Command

Overview

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

Byte Index

Field Name

Notes

0

Joining Key Option

0x00 = Join using Preconfigured Link Key
0x01 = Join using Installation Code

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

Network Down.

Sent By Host/Module

Host.

Section
Column
width100%

( PH:0x02, SH:0x01 ) - Preconfigured Key Option Request Command

Overview

The Preconfigured Key Option Request is sent by the Host to the Module to query the current application Preconfigured Key Option.

Payload

This command has no payload.

Effect on Receipt

The Module will respond with a Preconfigured Key Option Response.

Allowed Context

All Contexts.

Sent By Host/Module

Host.

Section Column
width100%

( PH:0x02, SH:0x02 ) - Preconfigured Key Option Response Command

Overview

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 Writecommand.

Payload

Byte Index

Field Name

Notes

0

Joining Key Option

0x00 = Join using Preconfigured Link Key
0x01 = Join using Installation Code

Effect on Receipt

None.

Allowed Context

Same context as request.

Sent By Host/Module

Module.







Section


Column
width60%

( 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.



Section


Column
width60%

( 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.








Section


Column
width60%

( 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.



Section


Column
width60%

( 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.



Section


Column
width100%

( 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.








Section


Column
width100%

( 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.



Section


Column
width100%

( 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.



Section


Column
width100%

( 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.








Section


Column
width100%

( PH:0x02, SH:0x0B ) - Security Profile Write Command

Overview

Note: This feature will be 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

0Security Profile

0 = HA (default),

1 = SE (will use CBKE)

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.



Section


Column
width100%

( PH:0x02, SH:0x0C ) - Security Profile Request Command

Overview

Note: This feature will be 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.



Section


Column
width100%

( PH:0x02, SH:0x0D ) - Security Profile Response Command

Overview

Note: This feature will be 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 IndexField NameNotes
0Security Profile

0 = HA (default),

1 = SE (will use CBKE)

0xFF = no security (not recommended)

Effect on Receipt

No action is expected by the Host. 

Allowed Context

All Context.

Sent By Host/Module

Host.








Section


Column
width100%

( 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.

Payload

Byte IndexField NameNotes

0..7

EUI64 Address

EUI64 of the device, which the install code belongs to, LSB First

8Install Code Size

The size in bytes n of the Installation Code, including the two-byte CRC, where n can be any of 8, 10, 14, or 18

9..8+nInstall CodeMSB First

Effect on Receipt

Module shall send Status Response with the following list of possible status

Status ResponseEnumDescription

Success

0x00

Install code successfully added

Invalid Data0x02Install code is invalid (e.g. invalid length, invalid CRC)
Storage Full0x04Exceeding max number of device install codes that can be added

Allowed Context

Network Up.

Sent By Host/Module

Host.



Section


Column
width60%

( 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.



Section


Column
width100%

( 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.



Section


Column
width100%

( 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 IndexField NameNotes

0

Max Count

Max number of install codes that can be stored in the trust center

Effect on Receipt

None.


Allowed Context

Same context as request.

Sent By Host/Module

Module.








Section


Column
width60%

( 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 IndexField NameNotes

0

Require Join By Install Code

Sets the value of the bdbJoinUsesInstallCodeKey parameter as per the Zigbee Base Device specification.

0x00 = False (Default) 
0x01 = True

1Require Key Exchange

Sets the value of the bdbTrustCenterRequireKeyExchange parameter as per the Zigbee Base Device specification.

0x00 = False (Default)
0x01 = True

Effect on Receipt

Module shall send Status Response with the following list of possible status

Status ResponseEnumDescription

Success

0x00

Security policies written successfully

Invalid Data0x02data values are invalid
Incorrect Length0x07Requires a payload of at least 2 bytes

Allowed Context

All contexts.

Sent By Host/Module

Host.




Section


Column
width60%

( 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.



Section


Column
width60%

( 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 IndexField NameNotes

0

Require Join By Install Code

0x00 = False
0x01 = True

1Require Key Exchange

0x00 = False
0x01 = True

Effect on Receipt

None.

Allowed Context

Same context as the request.

Sent By Host/Module

Module.








Section


Column
width60%

( 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

  1. A device that just joined the network(TC) and/or
  2. 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 IndexField NameNotes

0..1

Device Node ID


2..9Device EUI64


10Key Exchange Status

See Key Exchange Status Enumerations

Key Exchange Status Enumerations

EnumNameFailure StatusTC / Requester
0x00EMBER KEY STATUS NONENoRequester
0x01EMBER APP LINK KEY ESTABLISHEDNoRequester
0x03EMBER TRUST CENTER LINK KEY ESTABLISHEDNoRequester
0x04EMBER KEY ESTABLISHMENT TIMEOUTYesRequester
0x05EMBER KEY TABLE FULLYesRequester
0x06EMBER TC RESPONDED TO KEY REQUESTNoTC
0x07EMBER TC APP KEY SENT TO REQUESTERNoTC
0x08EMBER TC RESPONSE TO KEY REQUEST FAILEDYesTC
0x09EMBER TC REQUEST KEY TYPE NOT SUPPORTEDYesTC
0x0AEMBER TC NO LINK KEY FOR REQUESTERYesTC
0x0BEMBER TC REQUESTER EUI64 UNKNOWNYesTC
0x0CEMBER TC RECEIVED FIRST APP KEY REQUESTYesTC
0x0DEMBER TC TIMEOUT WAITING FOR SECOND APP KEY REQUESTYesTC
0x0EEMBER TC NON MATCHING APP KEY REQUEST RECEIVEDYesTC
0x0FEMBER TC FAILED TO SEND APP KEYSYesTC
0x10EMBER TC FAILED TO STORE APP KEY REQUESTYesTC
0x11EMBER TC REJECTED APP KEY REQUESTYesTC
0x12EMBER TC FAILED TO GENERATE NEW KEYYesTC
0x13EMBER TC FAILED TO SEND TC KEYYesTC
0x1EEMBER TRUST CENTER IS PRE R21NoRequester
0x32EMBER TC REQUESTER VERIFY KEY TIMEOUTYesTC
0x33EMBER TC REQUESTER VERIFY KEY FAILUREYesTC
0x34EMBER TC REQUESTER VERIFY KEY SUCCESSNoTC
0x64EMBER VERIFY LINK KEY FAILUREYesRequester
0x65EMBER VERIFY LINK KEY SUCCESSNoRequester

Effect on Receipt

None.

Allowed Context

Network Up.

Sent By Host/Module

Module.




Style
{style}
.panel, #content .panel {
-moz-border-radius: 5px;
-webkit-border-radius: 5px;
border-radius: 5px;
}

table.confluenceTable th.confluenceTh, table.confluenceTable td.highlight {
	background-color: #7AB800 !important;
}

.sectionColumnWrapper{
margin-bottom:20px;
padding: 15px;
background-color: #f9f9f9 !important;
border-style: solid;
border-width: 1px;
-moz-border-radius: 5px;
-webkit-border-top: 5px;
-webkit-border: 5px;
border-radius: 5px;

}
.panel .panelHeader {
text-align: left;
line-height: 1em;
padding: 10px 10px 5px;
margin-bottom: 0;
background-color: #7AB800;
-moz-border-radius-topleft: 5px;
-moz-border-radius-topright: 5px;
-webkit-border-top-right-radius: 5px;
-webkit-border-top-left-radius: 5px;
border-top-right-radius: 5px;
border-top-left-radius: 5px;
}
{style}