Zigbee Security Manager APIs#

This file describes functionality for Zigbee security features. This includes storing and fetching various keys, as well as invoking crypto operations.

See zigbee_security_manager.h for source code.

Functions#

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

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.

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

bool

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.

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.

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.

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.

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

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

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.

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.

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.

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

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

uint8_t

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

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

Imports the symmetric passphrase to the Link Key Table.

sl_status_t
sl_zb_sec_man_export_symmetric_passphrase(EmberEUI64 address, EmberKeyData *key_data)

Exports the symmetric passphrase from the Link Key Table.

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.

bool

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

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.

Macros#

#define

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.

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

#define

Returns whether a Symmetric Passphrase can be stored.

Function Documentation#

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.

Parameters
N/Acontext

Definition at line 50 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Acontext

[IN] The context to set. The context dictates which key type to save, key_index (if applicable) into the relevant key storage, eui64 (if applicable), etc.

N/Aplaintext_key

[IN] The key to import.

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.


Definition at line 85 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aindex

[IN] The index to set or overwrite in the key table for keys of type SL_ZB_SEC_MAN_KEY_TYPE_APP_LINK. If index is set to 0xFF (255), then the key will either overwrite whichever key table entry has an EUI of address (if one exists) or write to the first available key table entry. The index that the key was placed into will not be returned by this API.

N/Aaddress

[IN] The EUI belonging to the key.

N/Aplaintext_key

[IN] A pointer to the key to import.

Returns

  • SL_STATUS_OK upon success, a valid error code otherwise.


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

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.

Parameters
N/Aindex
N/Acontext
N/Aplaintext_key
N/Akey_data

Definition at line 109 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aeui
N/Acontext
N/Aplaintext_key
N/Akey_data

Definition at line 122 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aeui

The long address of some other device in the network.

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.


Definition at line 138 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aeui64

[IN] The EUI to search for.

N/Acontext

[OUT] The context about the key, filled in upon success.

N/Aplaintext_key

[OUT] If the security configuration allows for it, filled in with the key contents upon success.

N/Akey_data

[OUT] Filled in with metadata about the key upon success.

Returns

  • sl_status_t SL_STATUS_OK upon success, SL_STATUS_NOT_FOUND otherwise.


Definition at line 168 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aindex

[IN] The key_index to fetch.

N/Acontext

[OUT] The context about the key, filled in upon success.

N/Aplaintext_key

[OUT] If the security configuration allows for it, filled in with the key contents upon success.

N/Akey_data

[OUT] Filled in with metadata about the key upon success.

Returns

  • sl_status_t SL_STATUS_OK upon success, SL_STATUS_NOT_FOUND otherwise.


Definition at line 185 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Acontext

[IN/OUT] The context to set. The context dictates which key type to export, which key_index (if applicable) into the relevant key storage, which eui64 (if applicable), etc.

N/Aplaintext_key

[OUT] The key to export.

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.


Definition at line 224 of file stack/include/zigbee-security-manager.h

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

Parameters
N/Acontext

[IN] The context to use to look up a key entry. If the ZB_SEC_MAN_FLAG_EUI_IS_VALID flag is set in context->flags, then the context->eui field is used to search for and delete the key. If the ZB_SEC_MAN_FLAG_KEY_INDEX_IS_VALID flag is set in context->flags, then the context->key_index field is used to search for and delete the key.

Returns

  • sl_status_t SL_STATUS_OK upon success, an error code otherwise.


Definition at line 241 of file stack/include/zigbee-security-manager.h

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

Parameters
N/Acontext

[IN] The context to use to look up a key entry. If the ZB_SEC_MAN_FLAG_EUI_IS_VALID flag is set in context->flags, then the context->eui field is used to search for and delete the key. If the ZB_SEC_MAN_FLAG_KEY_INDEX_IS_VALID flag is set in context->flags, then the context->key_index field is used to search for and delete the key.

Returns

  • sl_status_t SL_STATUS_OK upon success, an error code otherwise.


Definition at line 257 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Acontext

[IN] The context to check for validity. The fields that must be set depend on the key type set in the context, as enough information is needed to identify the key.

Returns

  • sl_status_t SL_STATUS_OK upon success, SL_STATUS_NOT_FOUND otherwise.


Definition at line 268 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Anetwork_key_info

[OUT] The network key info struct used to store network key metadata, containing information about whether the current and next network keys are set, and the sequence numbers associated with each key.

Returns

  • sl_status_t SL_STATUS_OK


Definition at line 281 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Acontext

[IN/OUT] The context to use to look up a key entry. If the user calls this function with the ::ZB_SEC_MAN_FLAG_KEY_INDEX_IS_VALID bit set in the context->flag field, then the key_index field in the context argument dictates which entry to retrieve. For keys with timeout and application link keys, the key_index retrieves the indexed entry into the respective table. Upon success, the eui64 field in the context is updated. If the user calls this function with the ::ZB_SEC_MAN_FLAG_EUI_IS_VALID bit set in the context->flag field, then the eui64 field in the context argument dictates which entry to retrieve. If the context->core_key_type argument is set to SL_ZB_SEC_MAN_KEY_TYPE_NETWORK, an error is returned as network keys are not tied to any specific EUI. If neither the ::ZB_SEC_MAN_FLAG_KEY_INDEX_IS_VALID bit nor the ::ZB_SEC_MAN_FLAG_EUI_IS_VALID bit is set in context->flags, then an error will be returned by this function. Upon success in fetching a key, the other fields in this argument are updated (e.g. a successful search by key_index will update the euii64 field).

N/Akey_data

[OUT] Metadata to fill in.

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


Definition at line 317 of file stack/include/zigbee-security-manager.h

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

Parameters
N/Acontext

[IN] The context to use to look up a key.

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


Definition at line 344 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Acontext

[IN] The context to use to look up which key to load. If the derived key type is not SL_ZB_SEC_MAN_DERIVED_KEY_TYPE_NONE, then an appropriate key derivation scheme is applied to the key fetched according to the context supplied.

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.


Definition at line 363 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Ainput

[IN] Data to be hashed. The keyed part of the keyed hash comes from the previously loaded context, so only data is input here.

N/Adata_length

[IN] Length of the data to be hashed.

N/Aoutput

[OUT] Hashed data.


Definition at line 378 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Anonce

[IN] Length of the MIC to output. Currently supported MIC lengths are 4 bytes and 8 bytes.

N/Aencrypt
N/Ainput
N/Aencryption_start_index
N/Alength
N/Amic_length
N/Aoutput

Definition at line 389 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aencrypt

[IN] true if encrypting, else decrypt

N/Ainput

[IN] Input, expected to be 16 bytes long.

N/Aoutput

[OUT] Output of the AES-128 encryption operation.


Definition at line 434 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aaddress

EUI64 of device

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.


Definition at line 450 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aindex

whether to erase the key at the given index with matching address

N/Aaddress

Link Key Table index to store symmetric passphrase

N/Akey_data

device EUI64

N/Akey_data

pointer to symmetric passphrase memory

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.


Definition at line 465 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aaddress

device EUI64

N/Akey_data

pointer to symmetric passphrase memory

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.


Definition at line 480 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aold_eui64

Old device address

N/Anew_eui64

New device address

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


Definition at line 495 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Aeui64

device address

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


Definition at line 518 of file stack/include/zigbee-security-manager.h

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.

Parameters
N/Acontext

Reference to the key being checked

N/Atest_key

Value to test for

Returns

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


Definition at line 530 of file stack/include/zigbee-security-manager.h

Macro Definition Documentation#

sl_zb_sec_man_import_transient_key#

#define sl_zb_sec_man_import_transient_key
Value:
(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.


Definition at line 154 of file stack/include/zigbee-security-manager.h

sl_zb_sec_man_aes_ccm#

#define sl_zb_sec_man_aes_ccm
Value:
(nonce, encrypt, input, encryption_start_index, length, output)

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


Definition at line 421 of file stack/include/zigbee-security-manager.h

sl_zb_sec_man_symmetric_passphrase_update_allowed#

#define sl_zb_sec_man_symmetric_passphrase_update_allowed
Value:
(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


Definition at line 507 of file stack/include/zigbee-security-manager.h