Zigbee Security Manager APIs#

sl_zb_sec_man_init_context#

void sl_zb_sec_man_init_context (sl_zb_sec_man_context_t * context)

This routine will initialize a Security Manager context correctly for use in subsequent function calls.

sl_zb_sec_man_import_key#

sl_status_t sl_zb_sec_man_import_key (sl_zb_sec_man_context_t * context, sl_zb_sec_man_key_t * plaintext_key)

Import a key into storage. Certain keys are indexed, while others are not, as described here.
If context->core_key_type is..
..SL_ZB_SEC_MAN_KEY_TYPE_NETWORK, then context->key_index dictates whether to import the current (active) network key (index 0) or the alternate network key (index 1).
..SL_ZB_SEC_MAN_KEY_TYPE_TC_LINK_WITH_TIMEOUT, then context->eui64 must be set. context->key_index is unused.
..SL_ZB_SEC_MAN_KEY_TYPE_APP_LINK, then context->key_index determines which index in the persisted key table that the entry should be stored to. context->eui64 must also be set. If context->key_index is 0xFF, a suitable key index will be found (either one storing an existing key with address of context->eui64, or an open entry), and context->key_index will be updated with where the entry was stored.
..SL_ZB_SEC_MAN_KEY_TYPE_GREEN_POWER_PROXY_TABLE_KEY or SL_ZB_SEC_MAN_KEY_TYPE_GREEN_POWER_SINK_TABLE_KEY, then context->key_index dictates which key entry to import. These Green Power keys are indexed keys, and there are EMBER_GP_PROXY_TABLE_SIZE/EMBER_GP_SINK_TABLE_SIZE many of them.

For all other key types, both context->key_index and context->eui64 are not used.

Note

• The context->derived_type must be SL_ZB_SEC_MAN_DERIVED_KEY_TYPE_NONE, else, an error will be thrown. Key derivations, which are used in crypto operations, are performed using the sl_zb_sec_man_load_key_context routine.

Returns

• SL_STATUS_OK upon success, a valid error code otherwise.

sl_zb_sec_man_import_link_key#

sl_status_t sl_zb_sec_man_import_link_key (uint8_t index, EmberEUI64 address, sl_zb_sec_man_key_t * plaintext_key)

Import a link key, or SL_ZB_SEC_MAN_KEY_TYPE_APP_LINK key, into storage.

Returns

• SL_STATUS_OK upon success, a valid error code otherwise.

sl_zb_sec_man_export_link_key_by_index#

sl_status_t sl_zb_sec_man_export_link_key_by_index (uint8_t index, sl_zb_sec_man_context_t * context, sl_zb_sec_man_key_t * plaintext_key, sl_zb_sec_man_aps_key_metadata_t * key_data)

Export an APS link key by index.

sl_zb_sec_man_export_link_key_by_eui#

sl_status_t sl_zb_sec_man_export_link_key_by_eui (EmberEUI64 eui, sl_zb_sec_man_context_t * context, sl_zb_sec_man_key_t * plaintext_key, sl_zb_sec_man_aps_key_metadata_t * key_data)

Search through the Key table to find an entry that has the same EUI address as the passed value. If NULL is passed in for the address then it finds the first unused entry and sets the index in the context. It is valid to pass in NULL to plaintext_key or key_data in case the index of the referenced key is desired but not its value or other metadata.

sl_zb_sec_man_have_link_key#

bool sl_zb_sec_man_have_link_key (EmberEUI64 eui)

Return true if a link key is available for securing messages sent to the remote device. This function simply checks for the existence of a key, it doesn't care if the key is authorized or not. This function searches in a few different places, and it may always return true if certain bits/policies are set. E.g: On trust center, this function always returns true if hashed link keys are used (EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY), or if EMBER_TRUST_CENTER_GLOBAL_LINK_KEY is set.

Returns

• bool Returns true if a link key can be retrieved/computed for securing messages sent to the remote EUI passed as argument. Returns false if a link key is not available for that EUI.

sl_zb_sec_man_export_transient_key_by_eui#

sl_status_t sl_zb_sec_man_export_transient_key_by_eui (EmberEUI64 eui64, sl_zb_sec_man_context_t * context, sl_zb_sec_man_key_t * plaintext_key, sl_zb_sec_man_aps_key_metadata_t * key_data)

Search for a transient, or temporary, key entry from key storage by EUI.

Returns

• sl_status_t SL_STATUS_OK upon success, SL_STATUS_NOT_FOUND otherwise.

sl_zb_sec_man_export_transient_key_by_index#

sl_status_t sl_zb_sec_man_export_transient_key_by_index (uint8_t index, sl_zb_sec_man_context_t * context, sl_zb_sec_man_key_t * plaintext_key, sl_zb_sec_man_aps_key_metadata_t * key_data)

Search for a transient, or temporary, key entry from key storage by key index.

Returns

• sl_status_t SL_STATUS_OK upon success, SL_STATUS_NOT_FOUND otherwise.

sl_zb_sec_man_export_key#

sl_status_t sl_zb_sec_man_export_key (sl_zb_sec_man_context_t * context, sl_zb_sec_man_key_t * plaintext_key)

Export a key from storage. Certain keys are indexed, while others are not, as described here.
If context->core_key_type is..
..SL_ZB_SEC_MAN_KEY_TYPE_NETWORK, then context->key_index dictates whether to export the current (active) network key (index 0) or the alternate network key (index 1).
..SL_ZB_SEC_MAN_KEY_TYPE_TC_LINK, then context->eui64 is checked if context->flags is set to ZB_SEC_MAN_FLAG_EUI_IS_VALID. If the EUI supplied does not match the TC EUI stored on the local device (if it is known), then an error is thrown.
..SL_ZB_SEC_MAN_KEY_TYPE_TC_LINK_WITH_TIMEOUT, then keys may be searched by context->eui64 or context->key_index. context->flags determines how to search (see ::sl_zigbee_sec_man_flags_t).
..SL_ZB_SEC_MAN_KEY_TYPE_APP_LINK, then keys may be searched by context->eui64 or context->key_index. context->flags determines how to search (see ::sl_zigbee_sec_man_flags_t).
..SL_ZB_SEC_MAN_KEY_TYPE_GREEN_POWER_PROXY_TABLE_KEY or SL_ZB_SEC_MAN_KEY_TYPE_GREEN_POWER_SINK_TABLE_KEY, then context->key_index dictates which key entry to export. These Green Power keys are indexed keys, and there are EMBER_GP_PROXY_TABLE_SIZE/EMBER_GP_SINK_TABLE_SIZE many of them.

For all other key types, both context->key_index and context->eui64 are not used.

Note

• The context->derived_type must be SL_ZB_SEC_MAN_DERIVED_KEY_TYPE_NONE. Other values are ignored.

Returns

• SL_STATUS_OK upon success, a valid error code otherwise.

sl_zb_sec_man_delete_transient_key#

sl_status_t sl_zb_sec_man_delete_transient_key (sl_zb_sec_man_context_t * context)

Search for a transient, or temporary, key and deletes it from key storage. Keys can be searched by EUI or key_index based on context->flags (see ::ZB_SEC_MAN_FLAG_EUI_IS_VALID and ::ZB_SEC_MAN_FLAG_KEY_INDEX_IS_VALID).

Returns

• sl_status_t SL_STATUS_OK upon success, an error code otherwise.

sl_zb_sec_man_delete_key_table_key#

sl_status_t sl_zb_sec_man_delete_key_table_key (sl_zb_sec_man_context_t * context)

Delete the key table entry, or a key of type SL_ZB_SEC_MAN_KEY_TYPE_APP_LINK, from storage. Keys can be searched by EUI or key_index based on context->flags (see ::ZB_SEC_MAN_FLAG_EUI_IS_VALID and ::ZB_SEC_MAN_FLAG_KEY_INDEX_IS_VALID).

Returns

• sl_status_t SL_STATUS_OK upon success, an error code otherwise.

sl_zb_sec_man_check_key_context#

sl_status_t sl_zb_sec_man_check_key_context (sl_zb_sec_man_context_t * context)

Check that the passed key exists and can be successfully loaded. This function does not actually load the context, but only checks that it can be loaded.

Returns

• sl_status_t SL_STATUS_OK upon success, SL_STATUS_NOT_FOUND otherwise.

sl_zb_sec_man_get_network_key_info#

sl_status_t sl_zb_sec_man_get_network_key_info (sl_zb_sec_man_network_key_info_t * network_key_info)

Retrieve information about the network key and alternate network key. It will not retrieve the actual network key contents.

Returns

• sl_status_t SL_STATUS_OK

sl_zb_sec_man_get_aps_key_info#

sl_status_t sl_zb_sec_man_get_aps_key_info (sl_zb_sec_man_context_t * context, sl_zb_sec_man_aps_key_metadata_t * key_data)

Retrieve metadata about an APS key. It does not retrieve the actual key contents.

Returns

• SL_STATUS_OK if successful, SL_STATUS_NOT_FOUND if the key_index or eui64 does not result in a found entry, SL_STATUS_INVALID_TYPE if the core key type is not an APS layer key (e.g. SL_ZB_SEC_MAN_KEY_TYPE_NETWORK), or SL_STATUS_INVALID_MODE if core_key_type is SL_ZB_SEC_MAN_KEY_TYPE_TC_LINK and the initial security state does not indicate the a preconfigured key has been set (that is, both EMBER_HAVE_PRECONFIGURED_KEY and EMBER_GET_PRECONFIGURED_KEY_FROM_INSTALL_CODE have not been set in the initial security state).

sl_zb_sec_man_delete_key#

sl_status_t sl_zb_sec_man_delete_key (sl_zb_sec_man_context_t * context)

Delete a key from storage. Certain keys are indexed, while others are not, as described here.
If context->core_key_type is..
..SL_ZB_SEC_MAN_KEY_TYPE_NETWORK, then context->key_index dictates whether to delete the current (active) network key (index 0) or the alternate network key (index 1).
..SL_ZB_SEC_MAN_KEY_TYPE_TC_LINK_WITH_TIMEOUT, then keys may be searched by context->eui64 or context->key_index. context->flags determines how to search (see ::sl_zigbee_sec_man_flags_t).
..SL_ZB_SEC_MAN_KEY_TYPE_APP_LINK, then keys may be searched by context->eui64 or context->key_index. context->flags determines how to search (see ::sl_zigbee_sec_man_flags_t).

• ..SL_ZB_SEC_MAN_KEY_TYPE_GREEN_POWER_PROXY_TABLE_KEY or SL_ZB_SEC_MAN_KEY_TYPE_GREEN_POWER_SINK_TABLE_KEY, then context->key_index dictates which key entry to delete. These Green Power keys are indexed keys, and there are EMBER_GP_PROXY_TABLE_SIZE/EMBER_GP_SINK_TABLE_SIZE many of them.
  
  For all other key types, both context->key_index and context->eui64 are not used.
  
  Returns

  • sl_status_t SL_STATUS_OK upon success, an error code otherwise.

sl_zb_sec_man_load_key_context#

sl_status_t sl_zb_sec_man_load_key_context (sl_zb_sec_man_context_t * context)

Load the specified key into the Security Manager's internal context. Any subsequent crypto operations will be done with that loaded context.

Note

• Enough information must be passed into context to properly identify the requested key, which is dependent on the key type requested. See sl_zb_sec_man_export_key for the requirements of the context argument based on core_key_type.

Returns

• SL_STATUS_OK upon success, an error code otherwise.

sl_zb_sec_man_hmac_aes_mmo#

void sl_zb_sec_man_hmac_aes_mmo (const uint8_t * input, const uint8_t data_length, uint8_t * output)

Using a previously set key context, the Security Manager will perform an HMAC (keyed hash) using AES-MMO as the hashing algorithm, and AES-128 for the underlying block encryption.

sl_zb_sec_man_aes_ccm_extended#

sl_status_t sl_zb_sec_man_aes_ccm_extended (uint8_t * nonce, bool encrypt, const uint8_t * input, uint8_t encryption_start_index, uint8_t length, uint8_t mic_length, uint8_t * output)

Encrypt the specified data using AES-CCM with AES-128 and a MIC of the requested length (in * bytes). See documentation for sl_zb_sec_ * man_aes_ccm for information on parameters besides mic_length.

sl_zb_sec_man_aes_128_crypt_block#

sl_status_t sl_zb_sec_man_aes_128_crypt_block (bool encrypt, const uint8_t * input, uint8_t * output)

Perform AES-128 crypto on the specified 16-byte block using a previously loaded context.

sl_zb_sec_man_find_symmetric_passphrase_key_table_index#

uint8_t sl_zb_sec_man_find_symmetric_passphrase_key_table_index (EmberEUI64 address)

Finds the Link Key Table index of the symmetric passphase of the given device EUI64.

This function will return the Link Key Table index of the symmetric passphase of the given device EUI64, and will return 0xFF if no matching symmetric passphrase is found.

Returns

• An uint8_t value that indicates the index of the stored symmetric passphrase in the link key table.

sl_zb_sec_man_import_symmetric_passphrase#

sl_status_t sl_zb_sec_man_import_symmetric_passphrase (uint8_t index, EmberEUI64 address, EmberKeyData * key_data, key_data)

Imports the symmetric passphrase to the Link Key Table.

This function will use Security Manager methods to store the given symmetric passphrase in the Link Key Table at the given index with matching EUI64.

Returns

• An EmberStatus value that indicates the success or failure of importing the symmetric passphrase into the Link Key Table.

sl_zb_sec_man_export_symmetric_passphrase#

sl_status_t sl_zb_sec_man_export_symmetric_passphrase (EmberEUI64 address, EmberKeyData * key_data)

Exports the symmetric passphrase from the Link Key Table.

This function will use Security Manager methods to export the given symmetric passphrase from the Link Key Table matching EUI64.

Returns

• An EmberStatus value that indicates the success or failure of exporting the symmetric passphrase into the Link Key Table.

sl_zb_sec_man_update_symmetric_passphrase_eui#

sl_status_t sl_zb_sec_man_update_symmetric_passphrase_eui (EmberEUI64 old_eui64, EmberEUI64 new_eui64)

Updates the device address of a symmetric passphrase entry.

This function will update the device address of a symmetric passphrase entry in the Link Key Table that matches the given old device address with the new device address.

Returns

• An EmberStatus value that indicates the success or failure of updating the Link Key Table entry's device EUI64

sl_zigbee_sec_man_link_key_slot_available#

bool sl_zigbee_sec_man_link_key_slot_available (EmberEUI64 eui64)

Checks whether a new link key with a device can be stored.

Returns

• True if a new link key could be stored (there is either an existing entry with this device's EUI64 or a free entry for a new device), false if not (table is full).

sl_zb_sec_man_compare_key_to_value#

bool sl_zb_sec_man_compare_key_to_value (sl_zb_sec_man_context_t * context, const sl_zb_sec_man_key_t * test_key)

Check whether the key referenced by a given context has a specified value. This API is only compatible with keys that permit the standard Zigbee encryption algorithm and have a core key type that is not SL_ZB_SEC_MAN_KEY_TYPE_INTERNAL.

Returns

• True if the key referenced by context has the value test_key, false otherwise.

sl_zb_sec_man_import_transient_key#

#define sl_zb_sec_man_import_transient_key

(eui64, key)

Add a transient or temporary key entry to key storage. A key entry added with this API is timed out after EMBER_TRANSIENT_KEY_TIMEOUT_S seconds, unless the key entry was added using the Network Creator Security component, in which case the key will time out after the longer between ::EMBER_AF_PLUGIN_NETWORK_CREATOR_SECURITY_NETWORK_OPEN_TIME_S seconds and EMBER_TRANSIENT_KEY_TIMEOUT_S seconds.

Returns

• See ::zb_sec_man_import_transient_key for return information.

sl_zb_sec_man_aes_ccm#

#define sl_zb_sec_man_aes_ccm

(nonce, encrypt, input, encryption_start_index, length, output)

Encrypt the specified data using AES-CCM with AES-128 and a 4-byte MIC.

sl_zb_sec_man_symmetric_passphrase_update_allowed#

#define sl_zb_sec_man_symmetric_passphrase_update_allowed

(address)

Returns whether a Symmetric Passphrase can be stored.

The determination of whether a new Symmetric Passphrase can be stored is made by checking if one already exists inside the key table with the same EUI64

Returns

• a boolean representing whether a Symmetric Passphrase can be stored