5.2.3. Security

This section provides the security related APIs and defines of ESP Zigbee Core.

5.2.3.1. API Reference

5.2.3.1.1. Header File

5.2.3.1.2. Functions

ezb_err_t ezb_secur_set_ic_required(bool required)

Enable Trust Center to require install code for joining.

Parameters:

required -- [in] A boolean indicating whether the install code is required for joining.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

ezb_err_t ezb_secur_ic_add(const ezb_extaddr_t *address, ezb_secur_ic_type_t ic_type, const uint8_t *ic)

Trust Center: Add the install code for remote device with type.

Parameters:

  • address -- [in] The pointer to the 64-bit extended address of the remote device.

  • ic_type -- [in] The install code type, ezb_secur_ic_type_e.

  • ic -- [in] The pointer to the data of install code.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

ezb_err_t ezb_secur_ic_remove(const ezb_extaddr_t *address)

Trust Center: Remove the install code of a remote device.

Parameters:

address -- [in] The pointer to the 64-bit extended address of the remote device.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

ezb_err_t ezb_secur_ic_remove_all(void)

Trust Center: Remove the install code of all joiner devices.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

ezb_err_t ezb_secur_ic_set(ezb_secur_ic_type_t ic_type, const uint8_t *ic)

Joiner: Set the install code for joining.

Parameters:

  • ic_type -- [in] The install code type ezb_secur_ic_type_e

  • ic -- [in] The pointer to the data of install code.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

ezb_err_t ezb_secur_ic_get(uint8_t *ic, ezb_secur_ic_type_t *ic_type)

Joiner: Get current install code.

Parameters:

  • ic -- [out] The pointer to the data of install code.

  • ic_type -- [out] The pointer to install code type.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

void ezb_secur_set_kn_method_enabled(ezb_secur_kn_method_t method, bool enabled)

Enable/Disable the key negotiation method for the ZigBee network.

Parameters:

  • method -- [in] The key negotiation method, ezb_secur_kn_method_e.

  • enabled -- [in] True - Enable the key negotiation method; False - Disable the key negotiation method.

bool ezb_secur_get_kn_method_enabled(ezb_secur_kn_method_t method)

Check if the key negotiation method is enabled.

Parameters:

method -- [in] The key negotiation method, ezb_secur_kn_method_e.

Returns:

- True: if the key negotiation method is enabled; false otherwise.

void ezb_secur_set_kn_secret_enabled(ezb_secur_kn_secret_t secret, bool enabled)

Enable/Disable the key negotiation secret (PSK) for the ZigBee network.

Parameters:

  • secret -- [in] The key negotiation secret, ezb_secur_kn_secret_e.

  • enabled -- [in] True - Enable the key negotiation secret; False - Disable the key negotiation secret.

bool ezb_secur_get_kn_secret_enabled(ezb_secur_kn_secret_t secret)

Check if the key negotiation secret (PSK) is enabled.

Parameters:

secret -- [in] The key negotiation secret, ezb_secur_kn_secret_e.

Returns:

- True: if the key negotiation secret is enabled; false otherwise.

ezb_err_t ezb_secur_set_tclk_exchange_required(bool required)

Set if the TC-link key exchange is required for joining.

Note

The ZigBee router/end device without required will not request key from the ZigBee coordinator. The ZigBee coordinator without required allows the router/end device to stay in network without a TC-link key exchange.

Parameters:

required -- [in] A boolean indicating whether the link key exchange is required for joining.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

void ezb_secur_set_global_link_key(const uint8_t *key)

Set the global link key for the ZigBee network.

Parameters:

key -- [in] A pointer to the global link key.

ezb_err_t ezb_secur_set_security_level(ezb_secur_seclevel_t level)

Set the security level for the ZigBee network.

Parameters:

level -- [in] The security level, ezb_secur_seclevel_e. Default is EZB_SECUR_SECLEVEL_ENC_MIC32.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

ezb_secur_seclevel_t ezb_secur_get_security_level(void)

Get the current security level for the ZigBee network.

Returns:

The security level, ezb_secur_seclevel_e

ezb_err_t ezb_secur_set_network_key(const uint8_t *key)

Set the current network key of the ZigBee network.

Parameters:

key -- [in] The pointer to the key data.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

ezb_err_t ezb_secur_get_network_key(uint8_t *key)

Get the current network key of the ZigBee network.

Returns:

- EZB_ERR_NONE: on success; failed otherwise.

ezb_err_t ezb_secur_switch_network_key(const uint8_t *key, uint8_t key_seq)

Switch the network key of current Zigbee network used by local device.

Parameters:

  • key -- [in] A 16-byte security network key to be switched.

  • key_seq -- [in] The sequence number associated with the network key.

Returns:

  • EZB_ERR_NONE: Success

  • Otherwise: Failure

ezb_err_t ezb_secur_broadcast_network_key(const uint8_t *key, uint8_t key_seq)

Broadcast a new network key to the network.

Parameters:

  • key -- [in] A 16-byte security network key to be broadcast.

  • key_seq -- [in] The sequence number associated with the network key.

Returns:

  • EZB_ERR_NONE: Success

  • EZB_ERR_NO_MEM: Insufficient memory to process the request

  • EZB_ERR_NOT_SUPPORTED: The current Zigbee role does not support sending this command

  • EZB_ERR_INV_ARG: The provided key value is invalid

  • Otherwise: Failure

ezb_err_t ezb_secur_broadcast_switch_network_key(uint8_t key_seq)

Broadcast the network requesting to switch to a new network key.

Parameters:

key_seq -- [in] The sequence number associated with the network key.

Returns:

  • EZB_ERR_NONE: Success

  • EZB_ERR_NO_MEM: Insufficient memory to process the request

  • EZB_ERR_NOT_SUPPORTED: The current Zigbee role does not support sending this command

  • Otherwise: Failure

void ezb_secur_tcpol_set_allow_rejoins_with_well_known_key(bool allow)

Set whether rejoins using the well-known key are allowed on the Zigbee network.

Parameters:

allow -- [in] True to allow rejoins using the well-known key, false to disallow them.

bool ezb_secur_tcpol_get_allow_rejoins_with_well_known_key(void)

Get whether rejoins using the well-known key are allowed on the Zigbee network.

Returns:

- True: if rejoins using the well-known key are allowed; false otherwise.

void ezb_secur_tcpol_set_no_link_key_join(bool enable)

Enable/Disable APS-encryption of TransportKey command for initial join.

Some devices may require unencrypted TransportKey command for initial join. When the policy is enabled, the TransportKey command will not be protected by the link key.

Parameters:

enable -- [in] True to enable, false to disable it.

bool ezb_secur_tcpol_get_no_link_key_join(void)

Get if APS-encryption of TransportKey command is disabled for initial join.

Returns:

True if enabled; false otherwise.

5.2.3.1.3. Macros

ESP_ZIGBEE_SECUR_H

5.2.3.1.4. Type Definitions

typedef uint8_t ezb_secur_seclevel_t

Represents the Zigbee security level, ezb_secur_seclevel_e.

typedef uint8_t ezb_secur_kn_method_t

Represents the Zigbee key negotiation method, ezb_secur_kn_method_e.

typedef uint8_t ezb_secur_kn_secret_t

Represents the Zigbee key negotiation secret, ezb_secur_kn_secret_e.

typedef uint8_t ezb_secur_ic_type_t

Represents the Zigbee install code type, ezb_secur_ic_type_e.

5.2.3.1.5. Enumerations

enum ezb_secur_seclevel_e

Enum of the Zigbee Security Level .

Values:

enumerator EZB_SECUR_SECLEVEL_NONE

No security

enumerator EZB_SECUR_SECLEVEL_MIC32

32-bit MIC

enumerator EZB_SECUR_SECLEVEL_MIC64

64-bit MIC

enumerator EZB_SECUR_SECLEVEL_MIC128

128-bit MIC

enumerator EZB_SECUR_SECLEVEL_ENC_ONLY

Only encryption

enumerator EZB_SECUR_SECLEVEL_ENC_MIC32

32-bit MIC + encryption

enumerator EZB_SECUR_SECLEVEL_ENC_MIC64

64-bit MIC + encryption

enumerator EZB_SECUR_SECLEVEL_ENC_MIC128

128-bit MIC + encryption

enumerator EZB_SECUR_SECLEVEL_MAX_NR

Unknown security level

enum ezb_secur_ic_type_e

Enum of the Zigbee install code type .

Note

The format of the install code compliant with BDB specification, which is 48/64/96/128 bits number + 16 bits CRC (CCITT-16: x^16 + x^12 + x^5 + 1).

Values:

enumerator EZB_SECUR_IC_TYPE_48

Install code total of 8 bytes length

enumerator EZB_SECUR_IC_TYPE_64

Install code total of 10 bytes length

enumerator EZB_SECUR_IC_TYPE_96

Install code total of 14 bytes length

enumerator EZB_SECUR_IC_TYPE_128

Install code total of 18 bytes length

enumerator EZB_SECUR_IC_TYPE_PASSCODE

Passcode

enumerator EZB_SECUR_IC_TYPE_MAX_NR

Unknown type

enum ezb_secur_kn_method_e

Enum of the Zigbee key negotiation method .

Values:

enumerator EZB_SECUR_KN_METHOD_STATIC_REQUEST_KEY

Static request key

enumerator EZB_SECUR_KN_METHOD_ECSPEKE_CURVE25519_AESMMO

ECSPEKE Curve25519 AESMMO

enumerator EZB_SECUR_KN_METHOD_ECSPEKE_CURVE25519_SHA256

ECSPEKE Curve25519 SHA256

enum ezb_secur_kn_secret_e

Enum of the Zigbee key negotiation secret (PSK) .

Values:

enumerator EZB_SECUR_KN_SECRET_SYMM_AUTH_TOKEN

Symmetric authentication token

enumerator EZB_SECUR_KN_SECRET_INSTALL_CODE_KEY

Install code key

enumerator EZB_SECUR_KN_SECRET_PASSCODE_KEY

Passcode key