Versions Compared

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


Allowed Context

Network Up
Column
width100%

(

 PH

PH:0x02, SH:

0x20

0x0B ) -

 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.

 Security Profile Write Command


Warning
titleUse 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

..7

Byte Index

Field Name

Notes

0

EUI64 Address

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

8Install Code Size

The size in bytes 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
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.



Section


Column
width100%

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



Section


Column
width60%100%

(

 PH

PH:0x02, SH:

0x23

0x0D ) -

 Clear Trust Center Install Codes

 Security Profile Response Command

Overview

The Clear Trust Center Install Codes 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 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%
(

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









Section


Column
width100%

( PH:0x02, SH:

0x24

0x20 ) - Trust Center Install Code

Max Count Request

Add

Overview

The Trust Center Install Code Max Count Request Add command is sent by the Host to the 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

Effect on Receipt

None.

Allowed Context

Same context as request.

Sent By Host/Module

Module.

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 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 stored on the Module. 

Payload

Byte IndexField NameNotes

0

Max Count

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

Section

Effect on Receipt

Module shall send 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

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

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

Security policies written Install code successfully added

Invalid Data0x02data values are invalidIncorrect Length0x07Requires a payload of at least 2 bytesInstall code is invalid (e.g. invalid length, invalid CRC)
Storage Full0x04Exceeding max number of device install codes that can be added

Allowed Context

All contextsNetwork Up.

Sent By Host/Module

Host.



Section


Column
width60%

( PH:0x02, SH:

0x27

0x23 ) -

 Trust Center Security Policy Request

 Clear Trust Center Install Codes

Overview

The Clear Trust Center Security Policy Request Install Codes command is sent by the Host to the Module to request for the current Trust Center security policy.Module to clear all device install codes stored on the Module. 

Payload

The command has no payload. 

Effect on Receipt

Module shall respond with Trust Center Security Policy Responseclears all install codes.

Allowed Context

All contextsContexts.

Sent By Host/Module

Host.



Section


Effect on Receipt

None.

Allowed Context

Same context as the request.

Sent By Host/Module

Module.

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.

Column
width60%100%

( PH:0x02, SH:

0x28

0x24 ) - Trust Center

Security Policy Response

Install Code Max Count Request

Overview

The Trust Center Security Policy Response frame Install Code Max Count Request command is sent by the Host to Module to the Host in response to Trust Center Security Policy Requestquery the maximum number of install codes that can be stored in the trust center.

Payload

Byte IndexField NameNotes

0

Require Join By Install Code

0x00 = False
0x01 = True

1Require Key Exchange

0x00 = False
0x01 = True



Key Exchange Status Enumerations

Effect on Receipt

None.

Allowed Context

Network Up.

Sent By Host/Module

Module.

Section


{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; Field

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

Column
width60%100%

( PH:0x02, SH:

0x29

0x25 ) - Trust

Center Key Exchange Status Update

Center Install Code Max Count Response

Overview

The Trust Center Key Exchange Status Update Install Code Max Count Response command 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 Index
Byte IndexField NameNotes

0

..1

Device Node ID

2..9Device EUI64
10Key Exchange Status

See 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
Style

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.









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}
.wiki-content h1 { 
font-family: 'Helvetica Neue', sans-serif; font-size: 30px; font-weight: bold; color: #20b6e1; letter-spacing: 1px; line-height: 1; text-align: left;
#border-bottom: 1px solid #98bddd !important; 
}
.wiki-content h2 { 
font-family: 'Helvetica Neue', sans-serif; font-size: 20px; font-weight: normal; color: #00517f; letter-spacing: 1px; line-height: 1; text-align: left;
}
.wiki-content h3 { 
font-family: 'Helvetica Neue', sans-serif; font-size: 15px; font-weight: bold; color: #00517f; letter-spacing: 1px; line-height: 1; text-align: left;
}
.wiki-content h4 { 
font-family: 'Helvetica Neue', sans-serif; font-size: 15px; font-weight: normal; font-style:italic; color:#00517f; letter-spacing: 1px; line-height: 1; text-align: left;
}
#title-text{
font-family: 'Helvetica Neue', sans-serif; font-size: 40px; font-weight: 500; letter-spacing: 1px; line-height: 1; text-align: left;
}

.panel, #content .panel {
-moz-border-radius: 5px;
-webkit-border-top: 5px;
-webkit-borderradius: 5px;
border-radius: 5px;
}
}
.panel .panelHeader {
text-align: left;
color: #FFFFFF;
line-height: 1em;
padding: 10px 10px 5px;
margin-bottom: 0;
background-color: #7AB800#00517f;
-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}