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.

Section Column
width50%
PanelborderStylesolid

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


Panel
titleSecondary Headers
excerpt

Table of Contents
maxLevel2
minLevel2

column



Panel
width
title
20%
Primary Headers
column

Page Tree

width

root

30% Page TreerootFrame Payload DefinitionsspacesSPRC2

Frame Payload Definitions

Panel
borderStylesolid
titleIn This Space

spacesSPRC2








Section


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.

Host

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.

Column
width60%

( PH:0x02, SH:

0x00

0x03 ) -

 Preconfigured Key Option Write CommandThe Preconfigured Key Option Write command

 Install Code Request Command

Overview

The Install Code Request frame 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
0x01 = Join using Installation Code

Column
width10%
Column
width30%
Allowed ContextSent By Host/Module
Network Down



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.









Module

Host.

Section


Column
width60%

( PH:0x02, SH:

0x01

0x05 ) -

 Preconfigured

 Link Key

Option Request

Write Command

Overview

The

Preconfigured

Link Key

Option Request

Write command is sent by the Host to the Module in order to

query

set the

current

application Preconfigured Link Key

Option

. The

Module will respond with a Preconfigured Key Option Response. The command has no payload.
Column
width10%
Column
width30%
Allowed ContextSent By Host/Module
All ContextsHost
Section
0x00 = Join using
Column
width60%

( 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 Writecommand.Payload for Preconfigured Key Option Response Command

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

Joining Key Option

..15

Preconfigured Link Key

0x01 = Join using Installation Code
Column
width10%
Column
width30%
Allowed Context

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

-



Section


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.

Column
width60%

( PH:0x02, SH:

0x03

0x06 ) -

 Install Code

Link Key Request Command

Overview

The

Install Code

Link Key Request

frame

is sent by the Host to the Module to

query

request the current application

Installation Code

Link Key. The Module responds with

an Install Code

a Link Key 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.
Column
width10%
Column
width30%
Allowed ContextSent By Host/Module
All ContextsHost



Section


Column
width60%100%

( PH:0x02, SH:

0x04

0x07 ) -

 Install Code

Link Key Response Command

Overview

The

Install Code

Link Key Response

frame

is sent by the Module to the Host when queried with

an Install Code Request. Payload for Install Code Response Command

a Link Key Request. The command has the same payload as the Link Key Write command.

Payload

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

Column
width10%
Column
width30%
Allowed Context

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


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.

Column
width60%100%

( PH:0x02, SH:

0x05

0x08 ) -

 Link

 Network Key Write Command

Overview

The

Link

Network Key Write command is sent by the Host to the Module in order to set the application Preconfigured

Link

Network Key. The Host may only set the

Preconfigured Link

Network Key while the application is in the Network Down state

.If

, after which the key will be automatically randomized.

The Network Key is only applied 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

. If serving as a router or end device, the

key will be applied as the Joining Key

application will receive a Network Key from the network Trust Center.

The

Preconfigured Link

Network Key is not stored in non-volatile

memory and

memory and must therefore be set prior to forming

or joining a

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

generate a random value for it upon forming a network.

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”

Column
width10%
Column
width30%
Allowed ContextSent By Host/Module
Network DownHost
Section
Column
width60%

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:

0x06

0x09 ) -

Link

 Network Key Request Command

Overview

The

Link

Network Key Request command is sent by the Host to the Module to

request

query the

current

application

Link

Network Key. The Module

responds

will respond with a

Link

Network 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

If the application has not formed a network,

it

the response will

return

convey the Preconfigured

Link

Network Key

and likewise, when joined to a network, it returns the current Trust Center Link Key assigned to it. The

. Otherwise, the response will convey the current Network Key. 

Payload

This command has no payload.

Column
width10%
Column
width30%
Allowed Context

Effect on Receipt

The Module will respond with a Network Key Response

Allowed Context

All Contexts.

Sent By Host/Module

All Contexts

Host.



Module.

Section


Column
width60%100%

( PH:0x02, SH:

0x07

0x0A ) -

Link

 Network Key Response Command

Overview

The

Link

Network Key Response command is sent by the Module to the Host when queried with a

Link

Network Key Request. The command has the same payload as

the Link

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

Column
width10%
Column
width30%
Allowed Context

Network Key


Effect on Receipt

None.

Allowed Context

All Contexts.

Sent By Host/Module

-









Section


Column
width60%100%

( PH:0x02, SH:

0x08

0x0B ) -

 Network Key

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


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

Byte Index

Field Name

Notes

0
..15

Network Key

Column
width10%
Column
width30%
Allowed Context
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

Network Down

Host.



Section


Host

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.

Column
width60%100%

( PH:0x02, SH:

0x09

0x0C ) -

 Network Key Request CommandThe Network Key

 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

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.  
Column
width10%
Column
width30%
Allowed ContextSent By Host/Module
All Contexts



Section


Module

Host.

Column
width60%100%
Column
width30%

( PH:0x02, SH:

0x0A

0x0D ) -

 Network Key

 Security Profile Response Command

The Network Key

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

when queried with a Network Key

in response to the command Security Profile Request. The command

has the same payload as Network Key Write command.Payload for Network Key Response 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
0
..15

Network Key

Column
width10%
Sent
Allowed ContextSecurity 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

-









Section


Effect on Receipt

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

(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%100%

( 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 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
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
Column
width10%
Column
width30%
Allowed ContextSent By Host/Module
Network UpHost
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

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


30%
Column
width60%
Column
width

( 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

After clearing

Module clears all

device

install codes

, the Module shall send Status Response with status of Success

.

 
Column
width10%

Allowed Context

All Contexts.

Sent By Host/Module

All Contexts

Host.



Section


columnModule

Module.

Column
width60%100%

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

Column
width30%

width10%

Allowed Context

All Contexts.

Sent By Host/Module

All Contexts



Section


30%
Column
width60%100%
Column
width

( 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

Column
width10%

(Default size of 3)

Effect on Receipt

None.


Allowed Context

Same context as request.

Sent By Host/Module

-

Module.









Section


column

Host.

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
Column
width10%
width30%

Allowed Context

All contexts.

Sent By Host/Module

All Contexts




Section


30%
Column
width60%
Column
width

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

Column
width10%

Allowed Context

All contexts.

Sent By Host/Module

All Contexts

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

Column
width10%
Column
width30%
Allowed Context

Effect on Receipt

None.

Allowed Context

Same context as the request.

Sent By Host/Module

-

Module.









Section


30%
Column
width60%
Column
width

( 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

  1. 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
  1. (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
Column
width10%

Effect on Receipt

None.

Allowed Context

Network Up.

Sent By Host/Module

Network Up

Module.

Module




Style
Style
{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-radius: 5px;
border-radius: 5px;
}

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

.sectionColumnWrapper{
margin-bottom:20px;
}
.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}