Security Frames#
Name: setInitialSecurityState | ID: 0x0068 |
|---|---|
Description: Sets the security state that will be used by the device when it forms or joins the network. This call should not be used when restoring saved network state via networkInit as this will result in a loss of security data and will cause communication problems when the device re-enters the network. | |
Command Parameters: | |
sl_zigbee_initial_security_state_t state | The security configuration to be set. |
Response Parameters: | |
sl_status_t success | The success or failure code of the operation. |
Name: getCurrentSecurityState | ID: 0x0069 |
|---|---|
Description: Gets the current security state that is being used by a device that is joined in the network. | |
Command Parameters: None | |
Response Parameters: | |
sl_status_t status | The success or failure code of the operation. |
sl_zigbee_current_security_state_t state | The security configuration in use by the stack. |
Name: secManExportKey | ID: 0x0114 |
|---|---|
Description: Exports a key from security manager based on passed context. | |
Command Parameters: | |
sl_zigbee_sec_man_context_t context | Metadata to identify the requested key. |
Response Parameters: | |
sl_status_t status | The success or failure code of the operation. |
sl_zigbee_sec_man_key_t key | Data to store the exported key in. |
Name: secManImportKey | ID: 0x0115 |
|---|---|
Description: Imports a key into security manager based on passed context. | |
Command Parameters: | |
sl_zigbee_sec_man_context_t context | Metadata to identify where the imported key should be stored. |
sl_zigbee_sec_man_key_t key | The key to be imported. |
Response Parameters: | |
sl_status_t status | The success or failure code of the operation. |
Name: switchNetworkKeyHandler | ID: 0x006e |
|---|---|
Description: A callback to inform the application that the Network Key has been updated and the node has been switched over to use the new key. The actual key being used is not passed up, but the sequence number is. This frame is a response to the callback command. | |
Response Parameters: | |
uint8_t sequenceNumber | The sequence number of the new network key. |
Name: findKeyTableEntry | ID: 0x0075 |
|---|---|
Description: This function searches through the Key Table and tries to find the entry that matches the passed search criteria. | |
Command Parameters: | |
sl_802154_long_addr_t address | The address to search for. Alternatively, all zeros may be passed in to search for the first empty entry. |
bool linkKey | This indicates whether to search for an entry that contains a link key or a master key. true means to search for an entry with a Link Key. |
Response Parameters: | |
uint8_t index | This indicates the index of the entry that matches the search criteria. A value of 0x00FF is returned if not matching entry is found. |
Name: sendTrustCenterLinkKey | ID: 0x0067 |
|---|---|
Description: This function sends an APS TransportKey command containing the current trust center link key. The node to which the command is sent is specified via the short and long address arguments. | |
Command Parameters: | |
sl_802154_short_addr_t destinationNodeId | The short address of the node to which this command will be sent |
sl_802154_long_addr_t destinationEui64 | The long address of the node to which this command will be sent |
Response Parameters: | |
sl_status_t status | An sl_status_t value indicating success of failure of the operation |
Name: eraseKeyTableEntry | ID: 0x0076 |
|---|---|
Description: This function erases the data in the key table entry at the specified index. If the index is invalid, false is returned. | |
Command Parameters: | |
uint8_t index | This indicates the index of entry to erase. |
Response Parameters: | |
sl_status_t status | The success or failure of the operation. |
Name: clearKeyTable | ID: 0x00B1 |
|---|---|
Description: This function clears the key table of the current network. | |
Command Parameters: None | |
Response Parameters: | |
sl_status_t status | The success or failure of the operation. |
Name: requestLinkKey | ID: 0x0014 |
|---|---|
Description: A function to request a Link Key from the Trust Center with another device on the Network (which could be the Trust Center). A Link Key with the Trust Center is possible but the requesting device cannot be the Trust Center. Link Keys are optional in ZigBee Standard Security and thus the stack cannot know whether the other device supports them. If SL_ZIGBEE_REQUEST_KEY_TIMEOUT is non-zero on the Trust Center and the partner device is not the Trust Center, both devices must request keys with their partner device within the time period. The Trust Center only supports one outstanding key request at a time and therefore will ignore other requests. If the timeout is zero then the Trust Center will immediately respond and not wait for the second request. The Trust Center will always immediately respond to requests for a Link Key with it. Sleepy devices should poll at a higher rate until a response is received or the request times out. The success or failure of the request is returned via sl_zigbee_ezsp_zigbee_key_establishment_handler(...) | |
Command Parameters: | |
sl_802154_long_addr_t partner | This is the IEEE address of the partner device that will share the link key. |
Response Parameters: | |
sl_status_t status | The success or failure of sending the request. This is not the final result of the attempt. ezspZigbeeKeyEstablishmentHandler(...) will return that. |
Name: updateTcLinkKey | ID: 0x006C |
|---|---|
Description: Requests a new link key from the Trust Center. This function starts by sending a Node Descriptor request to the Trust Center to verify its R21+ stack version compliance. A Request Key message will then be sent, followed by a Verify Key Confirm message. | |
Command Parameters: | |
uint8_t maxAttempts | The maximum number of attempts a node should make when sending the Node Descriptor, Request Key, and Verify Key Confirm messages. The number of attempts resets for each message type sent (e.g., if maxAttempts is 3, up to 3 Node Descriptors are sent, up to 3 Request Keys, and up to 3 Verify Key Confirm messages are sent). |
Response Parameters: | |
sl_status_t status | The success or failure of sending the request. If the Node Descriptor is successfully transmitted, sl_zigbee_ezsp_zigbee_key_establishment_handler(...) will be called at a later time with a final status result. |
Name: zigbeeKeyEstablishmentHandler | ID: 0x009B |
|---|---|
Description: This is a callback that indicates the success or failure of an attempt to establish a key with a partner device. This frame is a response to the callback command. | |
Response Parameters: | |
sl_802154_long_addr_t partner | This is the IEEE address of the partner that the device successfully established a key with. This value is all zeros on a failure. |
sl_zigbee_key_status_t status | This is the status indicating what was established or why the key establishment failed. |
Name: clearTransientLinkKeys | ID: 0x006B |
|---|---|
Description: Clear all of the transient link keys from RAM. | |
Command Parameters: None | |
Response Parameters: None | |
Name: secManGetNetworkKeyInfo | ID: 0x0116 |
|---|---|
Description: Retrieve information about the current and alternate network key, excluding their contents. | |
Command Parameters: None | |
Response Parameters: | |
sl_status_t status | Success or failure of retrieving network key info. |
sl_zigbee_sec_man_network_key_info_t t network_key_info | Information about current and alternate network keys. |
Name: secManGetApsKeyInfo | ID: 0x010C |
|---|---|
Description: Retrieve metadata about an APS link key. Does not retrieve contents. | |
Command Parameters: | |
sl_zigbee_sec_man_context_t context_in | Context used to input information about key. |
Response Parameters: | |
sl_status_t status | Status of metadata retrieval operation. |
sl_zigbee_sec_man_aps_key_metadata_t key_data | Metadata about the referenced key. |
Name: secManImportLinkKey | ID: 0x010E |
|---|---|
Description: Import an application link key into the key table. | |
Command Parameters: | |
uint8_t index | Index where this key is to be imported to. |
sl_802154_long_addr_t address | EUI64 this key is associated with. |
sl_zigbee_sec_man_key_t plaintext_key | The key data to be imported. |
Response Parameters: | |
sl_status_t status | Status of key import operation. |
Name: secManExportLinkKeyByIndex | ID: 0x010F |
|---|---|
Description: Export the link key at given index from the key table. | |
Command Parameters: | |
uint8_t index | Index of key to export. |
Response Parameters: | |
sl_status_t status | Status of key export operation. |
sl_zigbee_sec_man_context_t context | Context referencing the exported key. Contains information like the EUI64 address it is associated with. |
sl_zigbee_sec_man_key_t plaintext_key | The exported key. |
sl_zigbee_sec_man_aps_key_metadata_t key_data | Metadata about the key. |
Name: secManExportLinkKeyByEui | ID: 0x010D |
|---|---|
Description: Export the link key associated with the given EUI from the key table. | |
Command Parameters: | |
sl_802154_long_addr_t eui | EUI64 associated with the key to export. |
Response Parameters: | |
sl_status_t status | Status of key export operation. |
sl_zigbee_sec_man_context_t context | Context referring to the exported key, containing the table index that this key is located in. |
sl_zigbee_sec_man_key_t plaintext_key | The exported key. |
sl_zigbee_sec_man_aps_key_metadata_t key_data | Metadata about the key. |
Name: secManCheckKeyContext | ID: 0x0110 |
|---|---|
Description: Check whether a key context can be used to load a valid key. | |
Command Parameters: | |
sl_zigbee_sec_man_context_t context | Context struct to check the validity of. |
Response Parameters: | |
sl_status_t status | Validity of the checked context. |
Name: secManImportTransientKey | ID: 0x0111 |
|---|---|
Description: Import a transient link key. | |
Command Parameters: | |
sl_802154_long_addr_t eui64 | EUI64 associated with this transient key. |
sl_zigbee_sec_man_key_t plaintext_key | The key to import. |
Response Parameters: | |
sl_status_t status | Status of key import operation. |
Name: secManExportTransientKeyByIndex | ID: 0x0112 |
|---|---|
Description: Export a transient link key from a given table index. | |
Command Parameters: | |
uint8_t index | Index to export from. |
Response Parameters: | |
sl_status_t status | Status of key export operation. |
sl_zigbee_sec_man_context_t context | Context struct for export operation. |
sl_zigbee_sec_man_key_t plaintext_key | The exported key. |
sl_zigbee_sec_man_aps_key_metadata_t key_data | Metadata about the key. |
Name: secManExportTransientKeyByEui | ID: 0x0113 |
|---|---|
Description: Export a transient link key associated with a given EUI64. | |
Command Parameters: | |
sl_802154_long_addr_t eui | Index to export from. |
Response Parameters: | |
sl_status_t status | Status of key export operation. |
sl_zigbee_sec_man_context_t context | Context struct for export operation. |
sl_zigbee_sec_man_key_t plaintext_key | The exported key. |
sl_zigbee_sec_man_aps_key_metadata_t key_data | Metadata about the key. |
Name: setIncomingTcLinkKeyFrameCounter | ID: 0x0128 |
|---|---|
Description: Set the incoming TC link key frame counter to desired value. | |
Command Parameters: | |
uint32_t frameCounter | Value to set the frame counter to. |
Response Parameters: None | |
Name: apsCryptMessage | ID: 0x0129 |
|---|---|
Description: Encrypt/decrypt a message in-place using APS. | |
Command Parameters: | |
bool encrypt | Encrypt (true) or decrypt (false) the message. |
uint8_t length_combined_arg | Length of the array containing message, needs to be long enough to include the auxiliary header and MIC. |
uint8_t[] message | The message to be en/de-crypted. |
uint8_t apsHeaderEndIndex | Index just past the APS frame. |
sl_802154_long_addr_t remoteEui64 | IEEE address of the device this message is associated with. |
Response Parameters: | |
sl_status_t status | Status of the encryption/decryption call. |