Security#

This file describes the functions necessary to manage security for a regular device. These are the three major modes for security and applications, which should link in the appropriate library:

  • Residential security uses only network keys. This is the only supported option for ZigBee 2006 devices.

  • Standard security uses network keys with optional link keys. Ember strongly recommends using Link Keys. It is possible for 2006 devices to run on a network that uses Standard Security.

See security.h for source code.

This file describes the functions for performing an AES-MMO hash on a block of data. The block of data may be small and contiguous, in which case the sl_zigbee_aes_hash_simple() routine can be used. Or large and discontiguous (such as a file stored in EEPROM), in which case the application must pass chunks to sl_zigbee_aes_mmo_hash_update() routine and use sl_zigbee_aes_mmo_hash_final() on the last chunk.

This file describes routines for getting pseudo- and strong-random numbers.

Modules#

Trust Center

Functions#

sl_status_t
sl_zigbee_set_initial_security_state(sl_zigbee_initial_security_state_t *state)

Set the initial security state that will be used by the device when it forms or joins a network. If security is enabled, this function must be called prior to forming or joining the network. It must also be called if the device left the network and wishes to form or join another network.

sl_status_t
sl_zigbee_set_extended_security_bitmask(sl_zigbee_extended_security_bitmask_t mask)

Set the extended initial security bitmask.

sl_status_t
sl_zigbee_get_extended_security_bitmask(sl_zigbee_extended_security_bitmask_t *mask)

Get the extended security bitmask that is used by a device.

sl_status_t
sl_zigbee_get_current_security_state(sl_zigbee_current_security_state_t *state)

Get the security state that is used by a device joined into the Network. We can still get current security state by calling this function and the return value can be SL_STATUS_NOT_JOINED or SL_STATUS_OK.

sl_status_t
sl_zigbee_generate_random_key(sl_zigbee_key_data_t *keyAddress)

Generate a Random Key (link, network, or master) and returns the result.

void
sl_zigbee_switch_network_key_handler(uint8_t sequenceNumber)

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.

sl_status_t
sl_zigbee_request_link_key(sl_802154_long_addr_t partner)

Request a Link Key from the Trust Center with another device device on the Network (which could be the Trust Center). A Link Key with the Trust Center is possible but the requesting device can't be the Trust Center. Link Keys are optional in ZigBee Standard Security. Therefore, the stack can't know whether the other device supports them.

sl_status_t
sl_zigbee_update_tc_link_key(uint8_t maxAttempts)

Request a new link 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.

void
sl_zigbee_zigbee_key_establishment_handler(sl_802154_long_addr_t partner, sl_zigbee_key_status_t status)

Notify the application about the status of the request for a Link Key. The application should define SL_ZIGBEE_APPLICATION_HAS_ZIGBEE_KEY_ESTABLISHMENT_HANDLER to implement its own handler.

uint8_t
sl_zigbee_find_key_table_entry(sl_802154_long_addr_t address, bool linkKey)

Search the key table to find an entry matching the specified IEEE address and key type.

sl_status_t

Clear a single entry in the key table.

sl_status_t

Clear the key table of the current network.

sl_status_t

Suppress normal write operations of the stack tokens. This is only done in rare circumstances when the device already has network parameters but needs to conditionally rejoin a network in order to perform a security message exchange (i.e., key establishment). If the network is not authenticated properly, it needs to forget any stack data it used and return to the old network. By suppressing writing of the stack tokens the device will not have stored any persistent data about the network and a reboot will clear the RAM copies. The Smart Energy profile feature Trust Center Swap-out uses this to securely replace the Trust Center and re-authenticate to it.

sl_status_t

Immediately write the value of stack tokens and then resume normal network operation by writing the stack tokens at appropriate intervals or changes in state. It has no effect unless a previous call was made to sl_zigbee_stop_writing_stack_tokens().

bool

Determine whether stack tokens will be written to persistent storage when they change. By default, it is set to true meaning the stack will update its internal tokens via HAL calls when the associated RAM values change.

sl_status_t
sl_zigbee_aps_crypt_message(bool encrypt, uint8_t length, const uint8_t *message, uint8_t apsHeaderEndIndex, sl_802154_long_addr_t remoteEui64)

Perform APS encryption/decryption of messages directly. Normally, the stack handles all APS encryption/decryption automatically and there is no need to call this function. If APS data is sent or received via some other means (such as over interpan), APS encryption/decryption must be done manually. If the decryption is performed, the Auxiliary security header and MIC will be removed from the message. If encrypting, the auxiliary header and MIC will be added to the message.

sl_status_t
sl_zigbee_get_mfg_security_config(sl_zigbee_mfg_security_struct_t *settings)

Retrieve the security configuration stored in manufacturing tokens. It is only available on the 35x series. See sl_zigbee_set_mfg_security_config() for more details.

sl_status_t
sl_zigbee_set_mfg_security_config(uint32_t magicNumber, const sl_zigbee_mfg_security_struct_t *settings)

Set the security configuration to be stored in manufacturing tokens. It is only available on the 35x series. This API must be called with care. Once set, a manufacturing token CANNOT BE UNSET without using the ISA3 tools and connecting the chip via JTAG. Additionally, a chip with read protection enabled cannot have its configuration changed without a full chip erase. Therefore, this provides a way to disallow access to the keys at runtime that cannot be undone.

sl_status_t

Set the NWK layer outgoing frame counter (intended for device restoration purposes). Caveats:

sl_status_t

Set the APS layer outgoing frame counter for Trust Center Link Key (intended for device restoration purposes). Caveats:

void

Clear all transient link keys from RAM.

uint16_t

The length of time, in seconds, that a trust center will store a transient link key that a device can use to join its network. A transient key is added with a call to sl_zigbee_sec_man_import_transient_key. After the transient key is added, it will be removed once this amount of time has passed. A joining device will not be able to use that key to join until it is added again on the trust center. The default value is 300 seconds, i.e., 5 minutes.

void
sl_zigbee_set_rejoin_mode(sl_zigbee_aps_rejoin_mode_t mode)
void
sl_zigbee_aes_mmo_hash_init(sl_zigbee_aes_mmo_hash_context_t *context)

This routine clears the passed context so that a new hash calculation can be performed.

sl_status_t
sl_zigbee_aes_mmo_hash_update(sl_zigbee_aes_mmo_hash_context_t *context, uint32_t length, const uint8_t *data)

This routine processes the passed chunk of data and updates the hash calculation based on it. The data passed in MUST have a length that is a multiple of 16.

sl_status_t
sl_zigbee_aes_mmo_hash_final(sl_zigbee_aes_mmo_hash_context_t *context, uint32_t length, const uint8_t *finalData)

This routine processes the passed chunk of data (if non-NULL) and update the hash context that is passed in. In then performs the final calculations on the hash and returns the final answer in the result parameter of the sl_zigbee_aes_mmo_hash_context_t structure. The length of the data passed in may be any value, it does not have to be a multiple of 16.

sl_status_t
sl_zigbee_aes_hash_simple(uint8_t totalLength, const uint8_t *data, uint8_t *result)

This is a convenience method when the hash data is less than 255 bytes. It inits, updates, and finalizes the hash in one function call.

uint16_t

Wrapper for the HAL API to generate pseudo-random numbers.

sl_status_t
sl_zigbee_get_strong_random_number_array(uint16_t *randomNumber, uint8_t count)

Get ::count number of true random numbers. The method of obtaining and quality of the random varies by chip family and the configuration used. For high security applications, please verify that that the generator's properties match your needs.

Return the entropy source used for true random number generation.

Macros#

#define

The block size in bytes of the encryption cypher (AES-MMO-128).

#define

A non-trust center device configuration bitmask example. There is no Preconfigured Link Key, so the NWK key is expected to be sent in-the-clear. The device will request a Trust Center Link key after getting the Network Key.

#define

A non-trust center device configuration bitmask example. The device has a Preconfigured Link Key and expects to receive a NWK Key encrypted at the APS Layer. A NWK key sent in-the-clear will be rejected.

#define
#define

Generate one true random number. For more info check sl_zigbee_get_strong_random_number_array.

#define

Function Documentation#

sl_zigbee_set_initial_security_state#

sl_status_t sl_zigbee_set_initial_security_state (sl_zigbee_initial_security_state_t * state)

Set the initial security state that will be used by the device when it forms or joins a network. If security is enabled, this function must be called prior to forming or joining the network. It must also be called if the device left the network and wishes to form or join another network.

Parameters
N/Astate

The security configuration to be set.

This call should not be used when restoring prior network operation from saved state via sl_zigbee_network_init because this will cause saved security settings and keys table from the prior network to be erased, resulting in improper keys and/or frame counter values being used, which will prevent proper communication with other devices in the network. Calling sl_zigbee_network_init is sufficient to restore all saved security settings after a reboot and re-enter the network.

The call may be used by either the Trust Center or non Trust Center devices, the options that are set are different depending on which role the device will assume. See the sl_zigbee_initial_security_state_t structure for more explanation about the various security settings.

The function will return ::SL_STATUS_INVALID_CONFIGURATION in the following cases:

  • Distributed Trust Center Mode was enabled with Hashed Link Keys.

Returns

  • An ::sl_status_t value. ::SL_STATUS_OK if the security state has been set successfully. ::SL_STATUS_INVALID_STATE if the device is not in the SL_ZIGBEE_NO_NETWORK state. The value ::SL_STATUS_INVALID_CONFIGURATION is returned if the combination of security parameters is not valid. ::SL_STATUS_INVALID_KEY is returned if a reserved or invalid key value was passed in the key structure for one of the keys.


Definition at line 80 of file stack/include/security.h

sl_zigbee_set_extended_security_bitmask#

sl_status_t sl_zigbee_set_extended_security_bitmask (sl_zigbee_extended_security_bitmask_t mask)

Set the extended initial security bitmask.

Parameters
N/Amask

An object of type sl_zigbee_extended_security_bitmask_t that indicates what the extended security bitmask should be set to.

Returns

  • ::SL_STATUS_OK if the security settings were successfully retrieved. ::SL_STATUS_INVALID_STATE otherwise.


Definition at line 90 of file stack/include/security.h

sl_zigbee_get_extended_security_bitmask#

sl_status_t sl_zigbee_get_extended_security_bitmask (sl_zigbee_extended_security_bitmask_t * mask)

Get the extended security bitmask that is used by a device.

Parameters
N/Amask

A pointer to an sl_zigbee_extended_security_bitmask_t value into which the extended security bitmask will be copied.

Returns

  • ::SL_STATUS_OK if the security settings were successfully retrieved. ::SL_STATUS_INVALID_STATE otherwise.


Definition at line 102 of file stack/include/security.h

sl_zigbee_get_current_security_state#

sl_status_t sl_zigbee_get_current_security_state (sl_zigbee_current_security_state_t * state)

Get the security state that is used by a device joined into the Network. We can still get current security state by calling this function and the return value can be SL_STATUS_NOT_JOINED or SL_STATUS_OK.

Parameters
N/Astate

A pointer to an sl_zigbee_current_security_state_t value into which the security configuration will be copied.

Returns

  • ::SL_STATUS_OK if the security settings were successfully retrieved. ::SL_STATUS_NOT_JOINED if the device is not currently joined in the network.


Definition at line 137 of file stack/include/security.h

sl_zigbee_generate_random_key#

sl_status_t sl_zigbee_generate_random_key (sl_zigbee_key_data_t * keyAddress)

Generate a Random Key (link, network, or master) and returns the result.

Parameters
N/AkeyAddress

A pointer to the location in which to copy the generated key.

It copies the key into the array that result points to. This is an time-expensive operation as it needs to obtain truly random numbers.

Returns

  • ::SL_STATUS_OK on success, ::SL_STATUS_ZIGBEE_INSUFFICIENT_RANDOM_DATA on failure.


Definition at line 158 of file stack/include/security.h

sl_zigbee_switch_network_key_handler#

void sl_zigbee_switch_network_key_handler (uint8_t sequenceNumber)

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.

Parameters
N/AsequenceNumber

The sequence number of the new network key.


Definition at line 167 of file stack/include/security.h

sl_zigbee_request_link_key#

sl_status_t sl_zigbee_request_link_key (sl_802154_long_addr_t partner)

Request a Link Key from the Trust Center with another device device on the Network (which could be the Trust Center). A Link Key with the Trust Center is possible but the requesting device can't be the Trust Center. Link Keys are optional in ZigBee Standard Security. Therefore, the stack can't know whether the other device supports them.

Parameters
N/Apartner

The IEEE address of the partner device. If NULL is passed in, the Trust Center IEEE Address is assumed.

If the partner device is the Trust Center, only that device needs to request the key. The Trust Center will immediately respond to those requests and send the key back to the device.

If the partner device is not the Trust Center, both devices must request an Application Link Key with each other. The requests will be sent to the Trust Center for it to answer. The Trust Center will store the first request and wait SL_ZIGBEE_REQUEST_KEY_TIMEOUT for the second request to be received. The Trust Center only supports one outstanding Application key request at a time and therefore will ignore other requests that are not associated with the first request.

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

Returns

  • SL_STATUS_OK if the call succeeds, or SL_STATUS_ALLOCATION_FAILED.


Definition at line 198 of file stack/include/security.h

sl_zigbee_update_tc_link_key#

sl_status_t sl_zigbee_update_tc_link_key (uint8_t maxAttempts)

Request a new link 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.

Parameters
N/AmaxAttempts

The maximum number of attempts a node should make when sending the Node Decriptor, 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).

Returns

  • SL_STATUS_FAIL is the Security Core Library is not included. SL_STATUS_INVALID_STATE if already requesting a key from TC, not on network, or if local node is Trust Center. SL_STATUS_INVALID_CONFIGURATION if the Trust Center's EUI is unknown. Otherwise, the return status from sending the initial Node Descriptor is returned.


Definition at line 218 of file stack/include/security.h

sl_zigbee_zigbee_key_establishment_handler#

void sl_zigbee_zigbee_key_establishment_handler (sl_802154_long_addr_t partner, sl_zigbee_key_status_t status)

Notify the application about the status of the request for a Link Key. The application should define SL_ZIGBEE_APPLICATION_HAS_ZIGBEE_KEY_ESTABLISHMENT_HANDLER to implement its own handler.

Parameters
N/Apartner

The IEEE address of the partner device or all zeros if the Key establishment failed.

N/Astatus

The status of the key establishment.


Definition at line 229 of file stack/include/security.h

sl_zigbee_find_key_table_entry#

uint8_t sl_zigbee_find_key_table_entry (sl_802154_long_addr_t address, bool linkKey)

Search the key table to find an entry matching the specified IEEE address and key type.

Parameters
N/Aaddress

The IEEE Address of the partner device that shares the key. To find the first empty entry, pass in an address of all zeros.

N/AlinkKey

A bool indicating whether to search for an entry containing a Link or Master Key.

Returns

  • The index that matches the search criteria, or 0xFF if no matching entry was found.


Definition at line 242 of file stack/include/security.h

sl_zigbee_erase_key_table_entry#

sl_status_t sl_zigbee_erase_key_table_entry (uint8_t index)

Clear a single entry in the key table.

Parameters
N/Aindex

The index in the key table of the entry to erase.

Returns

  • ::SL_STATUS_OK if the index is valid and the key data was erased. ::SL_STATUS_INVALID_KEY if the index is out of range for the size of the key table.


Definition at line 253 of file stack/include/security.h

sl_zigbee_clear_key_table#

sl_status_t sl_zigbee_clear_key_table (void )

Clear the key table of the current network.

Parameters
N/A

Returns

  • ::SL_STATUS_OK if the key table was successfully cleared. ::SL_STATUS_INVALID_STATE otherwise.


Definition at line 261 of file stack/include/security.h

sl_zigbee_stop_writing_stack_tokens#

sl_status_t sl_zigbee_stop_writing_stack_tokens (void )

Suppress normal write operations of the stack tokens. This is only done in rare circumstances when the device already has network parameters but needs to conditionally rejoin a network in order to perform a security message exchange (i.e., key establishment). If the network is not authenticated properly, it needs to forget any stack data it used and return to the old network. By suppressing writing of the stack tokens the device will not have stored any persistent data about the network and a reboot will clear the RAM copies. The Smart Energy profile feature Trust Center Swap-out uses this to securely replace the Trust Center and re-authenticate to it.

Parameters
N/A

Returns

  • ::SL_STATUS_OK if it could allocate temporary buffers to store network information. ::SL_STATUS_ALLOCATION_FAILED otherwise.


Definition at line 277 of file stack/include/security.h

sl_zigbee_start_writing_stack_tokens#

sl_status_t sl_zigbee_start_writing_stack_tokens (void )

Immediately write the value of stack tokens and then resume normal network operation by writing the stack tokens at appropriate intervals or changes in state. It has no effect unless a previous call was made to sl_zigbee_stop_writing_stack_tokens().

Parameters
N/A

Returns


Definition at line 289 of file stack/include/security.h

sl_zigbee_writing_stack_tokens_enabled#

bool sl_zigbee_writing_stack_tokens_enabled (void )

Determine whether stack tokens will be written to persistent storage when they change. By default, it is set to true meaning the stack will update its internal tokens via HAL calls when the associated RAM values change.

Parameters
N/A

Returns

  • True if the device will update the persistent storage for tokens when values in RAM change. False otherwise.


Definition at line 299 of file stack/include/security.h

sl_zigbee_aps_crypt_message#

sl_status_t sl_zigbee_aps_crypt_message (bool encrypt, uint8_t length, const uint8_t * message, uint8_t apsHeaderEndIndex, sl_802154_long_addr_t remoteEui64)

Perform APS encryption/decryption of messages directly. Normally, the stack handles all APS encryption/decryption automatically and there is no need to call this function. If APS data is sent or received via some other means (such as over interpan), APS encryption/decryption must be done manually. If the decryption is performed, the Auxiliary security header and MIC will be removed from the message. If encrypting, the auxiliary header and MIC will be added to the message.

Parameters
N/Aencrypt

A bool indicating whether perform encryption (true) or decryption (false).

N/Alength

(Pointer to the) length of the array being used to store message. This must be large enough to include the auxiliary header and MIC, regardless of the value of encrypt.

N/Amessage

A pointer to a ::uint8_t array containing the APS frame to decrypt or encrypt.

N/AapsHeaderEndIndex

The index in the buffer where the APS header ends. If encryption is being performed, this should point to the APS payload, where an Auxiliary header will be inserted. If decryption is being performed, this should point to the start of the Auxiliary header frame.

N/AremoteEui64

the ::sl_802154_long_addr_t of the remote device the message was received from (decryption) or being sent to (encryption).

Returns

  • ::SL_STATUS_OK if encryption/decryption was performed successfully. An appropriate ::sl_status_t code on failure.


Definition at line 333 of file stack/include/security.h

sl_zigbee_get_mfg_security_config#

sl_status_t sl_zigbee_get_mfg_security_config (sl_zigbee_mfg_security_struct_t * settings)

Retrieve the security configuration stored in manufacturing tokens. It is only available on the 35x series. See sl_zigbee_set_mfg_security_config() for more details.

Parameters
N/Asettings

A pointer to the sl_zigbee_mfg_security_struct_t variable that will contain the returned data.

Returns

  • ::SL_STATUS_OK if the tokens were successfully read. ::sl_status_t error code otherwise.


Definition at line 351 of file stack/include/security.h

sl_zigbee_set_mfg_security_config#

sl_status_t sl_zigbee_set_mfg_security_config (uint32_t magicNumber, const sl_zigbee_mfg_security_struct_t * settings)

Set the security configuration to be stored in manufacturing tokens. It is only available on the 35x series. This API must be called with care. Once set, a manufacturing token CANNOT BE UNSET without using the ISA3 tools and connecting the chip via JTAG. Additionally, a chip with read protection enabled cannot have its configuration changed without a full chip erase. Therefore, this provides a way to disallow access to the keys at runtime that cannot be undone.

Parameters
N/AmagicNumber

A 32-bit value that must correspond to SL_LEGACY_SECURITY_CONFIG_MAGIC_NUMBER, otherwise ::SL_STATUS_INVALID_STATE will be returned.

N/Asettings

The security settings that are intended to be set by the application and written to manufacturing token.

To call this API, the magic number must be passed in corresponding to SL_LEGACY_SECURITY_CONFIG_MAGIC_NUMBER. This prevents accidental calls to this function when sl_zigbee_get_mfg_security_config() was actually intended.

This function will disable external access to the actual key data used for decryption/encryption outside the stack. Attempts to export the key will return the metadata if applicable (e.g., sequence number, associated EUI64, frame counters) but the key value may be modified, see below.

The stack always has access to the actual key data.

If the sl_zigbee_key_settings_t within the sl_zigbee_mfg_security_struct_t are set to SL_ZIGBEE_KEY_PERMISSIONS_NONE, the key value will be set to zero when sl_zigbee_sec_man_export_key() or similar functions are called. If the sl_zigbee_key_settings_t within the sl_zigbee_mfg_security_struct_t are set to SL_ZIGBEE_KEY_PERMISSIONS_HASHING_ALLOWED, the AES-MMO hash of the key will replace the actual key data when calls to functions like sl_zigbee_sec_man_export_key() are made. If the sl_zigbee_key_settings_t within the sl_zigbee_mfg_security_struct_t are set to SL_ZIGBEE_KEY_PERMISSIONS_READING_ALLOWED, the actual key data is returned. This is the default value of the token.

Returns

  • ::SL_STATUS_INVALID_PARAMETER if the passed magic number is invalid. ::SL_STATUS_INVALID_STATE if the chip does not support writing MFG tokens ::SL_STATUS_INVALID_CONFIGURATION if there was an attempt to write an unerased manufacturing token (i.e., the token has already been set).


Definition at line 397 of file stack/include/security.h

sl_zigbee_set_outgoing_nwk_frame_counter#

sl_status_t sl_zigbee_set_outgoing_nwk_frame_counter (uint32_t desiredValue)

Set the NWK layer outgoing frame counter (intended for device restoration purposes). Caveats:

Parameters
N/AdesiredValue

The desired outgoing NWK frame counter value. This needs to be less than MAX_INT32U_VALUE to ensure that rollover does not occur on the next encrypted transmission.

Returns

  • ::SL_STATUS_OK if calling context is valid (sl_zigbee_network_state() == SL_ZIGBEE_NO_NETWORK) and desiredValue < MAX_INT32U_VALUE. Otherwise, ::SL_STATUS_INVALID_STATE.


Definition at line 418 of file stack/include/security.h

sl_zigbee_set_outgoing_aps_frame_counter#

sl_status_t sl_zigbee_set_outgoing_aps_frame_counter (uint32_t desiredValue)

Set the APS layer outgoing frame counter for Trust Center Link Key (intended for device restoration purposes). Caveats:

Parameters
N/AdesiredValue

The desired outgoing APS frame counter value. This needs to be less than MAX_INT32U_VALUE to ensure that rollover does not occur on the next encrypted transmission.

Returns

  • ::SL_STATUS_OK if calling context is valid (sl_zigbee_network_state() == SL_ZIGBEE_NO_NETWORK) and desiredValue < MAX_INT32U_VALUE. Otherwise, ::SL_STATUS_INVALID_STATE.


Definition at line 438 of file stack/include/security.h

sl_zigbee_clear_transient_link_keys#

void sl_zigbee_clear_transient_link_keys (void )

Clear all transient link keys from RAM.

Parameters
N/A

Definition at line 441 of file stack/include/security.h

sl_zigbee_get_transient_key_timeout_s#

uint16_t sl_zigbee_get_transient_key_timeout_s (void )

The length of time, in seconds, that a trust center will store a transient link key that a device can use to join its network. A transient key is added with a call to sl_zigbee_sec_man_import_transient_key. After the transient key is added, it will be removed once this amount of time has passed. A joining device will not be able to use that key to join until it is added again on the trust center. The default value is 300 seconds, i.e., 5 minutes.

Parameters
N/A

Definition at line 451 of file stack/include/security.h

sl_zigbee_set_transient_key_timeout_s#

void sl_zigbee_set_transient_key_timeout_s (uint16_t seconds)
Parameters
N/Aseconds

Definition at line 452 of file stack/include/security.h

sl_zigbee_get_rejoin_mode#

sl_zigbee_aps_rejoin_mode_t sl_zigbee_get_rejoin_mode (void )
Parameters
N/A

Definition at line 461 of file stack/include/security.h

sl_zigbee_set_rejoin_mode#

void sl_zigbee_set_rejoin_mode (sl_zigbee_aps_rejoin_mode_t mode)
Parameters
N/Amode

Definition at line 472 of file stack/include/security.h

sl_zigbee_get_security_frame_counter#

uint32_t sl_zigbee_get_security_frame_counter (void )
Parameters
N/A

Definition at line 475 of file stack/include/security.h

sl_zigbee_get_aps_frame_counter#

uint32_t sl_zigbee_get_aps_frame_counter (void )
Parameters
N/A

Definition at line 476 of file stack/include/security.h

sl_zigbee_get_incoming_tc_link_key_frame_counter#

uint32_t sl_zigbee_get_incoming_tc_link_key_frame_counter (void )
Parameters
N/A

Definition at line 477 of file stack/include/security.h

sl_zigbee_set_incoming_tc_link_key_frame_counter#

void sl_zigbee_set_incoming_tc_link_key_frame_counter (uint32_t frameCounter)
Parameters
N/AframeCounter

Definition at line 478 of file stack/include/security.h

sl_zigbee_aes_mmo_hash_init#

void sl_zigbee_aes_mmo_hash_init (sl_zigbee_aes_mmo_hash_context_t * context)

This routine clears the passed context so that a new hash calculation can be performed.

Parameters
N/Acontext

A pointer to the location of hash context to clear.


Definition at line 43 of file stack/include/aes-mmo.h

sl_zigbee_aes_mmo_hash_update#

sl_status_t sl_zigbee_aes_mmo_hash_update (sl_zigbee_aes_mmo_hash_context_t * context, uint32_t length, const uint8_t * data)

This routine processes the passed chunk of data and updates the hash calculation based on it. The data passed in MUST have a length that is a multiple of 16.

Parameters
N/Acontext

A pointer to the location of the hash context to update.

N/Alength

The length of the passed data.

N/Adata

A pointer to the location of the data to hash.

Returns

  • An ::sl_status_t value indicating SL_STATUS_OK if the hash was calculated successfully. SL_STATUS_INVALID_STATE if the block size is not a multiple of 16 bytes, and SL_STATUS_INVALID_INDEX is returned when the data exceeds the maximum limits of the hash function.


Definition at line 61 of file stack/include/aes-mmo.h

sl_zigbee_aes_mmo_hash_final#

sl_status_t sl_zigbee_aes_mmo_hash_final (sl_zigbee_aes_mmo_hash_context_t * context, uint32_t length, const uint8_t * finalData)

This routine processes the passed chunk of data (if non-NULL) and update the hash context that is passed in. In then performs the final calculations on the hash and returns the final answer in the result parameter of the sl_zigbee_aes_mmo_hash_context_t structure. The length of the data passed in may be any value, it does not have to be a multiple of 16.

Parameters
N/Acontext

A pointer to the location of the hash context to finalize.

N/Alength

The length of the finalData parameter.

N/AfinalData

A pointer to the location of data to hash. May be NULL.

Returns

  • An ::sl_status_t value indicating SL_STATUS_OK if the hash was calculated successfully. SL_STATUS_INVALID_STATE if the block size is not a multiple of 16 bytes, and SL_STATUS_INVALID_INDEX is returned when the data exceeds the maximum limits of the hash function.


Definition at line 84 of file stack/include/aes-mmo.h

sl_zigbee_aes_hash_simple#

sl_status_t sl_zigbee_aes_hash_simple (uint8_t totalLength, const uint8_t * data, uint8_t * result)

This is a convenience method when the hash data is less than 255 bytes. It inits, updates, and finalizes the hash in one function call.

Parameters
N/AtotalLength

The length of the data.

N/Adata

The data to hash.

N/Aresult

The location where the result of the hash will be written.

Returns

  • An ::sl_status_t value indicating SL_STATUS_OK if the hash was calculated successfully. SL_STATUS_INVALID_STATE if the block size is not a multiple of 16 bytes, and SL_STATUS_INVALID_INDEX is returned when the data exceeds the maximum limits of the hash function.


Definition at line 104 of file stack/include/aes-mmo.h

sl_zigbee_get_pseudo_random_number#

uint16_t sl_zigbee_get_pseudo_random_number (void )

Wrapper for the HAL API to generate pseudo-random numbers.

Parameters
N/A

Returns

  • uint16_t pseudo random number


Definition at line 35 of file stack/include/sl_zigbee_random_api.h

sl_zigbee_get_strong_random_number_array#

sl_status_t sl_zigbee_get_strong_random_number_array (uint16_t * randomNumber, uint8_t count)

Get ::count number of true random numbers. The method of obtaining and quality of the random varies by chip family and the configuration used. For high security applications, please verify that that the generator's properties match your needs.

Parameters
N/ArandomNumber
N/Acount

Returns

  • An ::sl_status_t value.

    • ::SL_STATUS_OK If success.

    • ::SL_STATUS_ZIGBEE_INSUFFICIENT_RANDOM_DATA In case of any error.


Definition at line 48 of file stack/include/sl_zigbee_random_api.h

sl_zigbee_get_strong_random_entropy_source#

sl_zigbee_entropy_source_t sl_zigbee_get_strong_random_entropy_source (void )

Return the entropy source used for true random number generation.

Parameters
N/A

Returns


Definition at line 76 of file stack/include/sl_zigbee_random_api.h

Macro Definition Documentation#

SECURITY_BLOCK_SIZE#

#define SECURITY_BLOCK_SIZE
Value:
16

The block size in bytes of the encryption cypher (AES-MMO-128).


Definition at line 43 of file stack/include/security.h

SL_ZIGBEE_JOIN_NO_PRECONFIG_KEY_BITMASK#

#define SL_ZIGBEE_JOIN_NO_PRECONFIG_KEY_BITMASK
Value:
(SL_ZIGBEE_STANDARD_SECURITY_MODE \
| SL_ZIGBEE_GET_LINK_KEY_WHEN_JOINING)

A non-trust center device configuration bitmask example. There is no Preconfigured Link Key, so the NWK key is expected to be sent in-the-clear. The device will request a Trust Center Link key after getting the Network Key.


Definition at line 110 of file stack/include/security.h

SL_ZIGBEE_JOIN_PRECONFIG_KEY_BITMASK#

#define SL_ZIGBEE_JOIN_PRECONFIG_KEY_BITMASK
Value:
(SL_ZIGBEE_STANDARD_SECURITY_MODE \
| SL_ZIGBEE_HAVE_PRECONFIGURED_KEY \
| SL_ZIGBEE_REQUIRE_ENCRYPTED_KEY)

A non-trust center device configuration bitmask example. The device has a Preconfigured Link Key and expects to receive a NWK Key encrypted at the APS Layer. A NWK key sent in-the-clear will be rejected.


Definition at line 120 of file stack/include/security.h

sl_zigbee_get_true_random_number_array#

#define sl_zigbee_get_true_random_number_array
Value:
(randomNumber, count)

Definition at line 51 of file stack/include/sl_zigbee_random_api.h

sl_zigbee_get_strong_random_number#

#define sl_zigbee_get_strong_random_number
Value:
(randomNumber)

Generate one true random number. For more info check sl_zigbee_get_strong_random_number_array.


Definition at line 57 of file stack/include/sl_zigbee_random_api.h

sl_zigbee_get_true_random_number#

#define sl_zigbee_get_true_random_number
Value:
(randomNumber)

Definition at line 60 of file stack/include/sl_zigbee_random_api.h

sl_zigbee_get_true_random_entropy_source#

#define sl_zigbee_get_true_random_entropy_source
Value:
()

Definition at line 81 of file stack/include/sl_zigbee_random_api.h