Security API

Security related APIs for ESP Zigbee SDK.

API Reference

Header File

components/esp-zigbee-lib/include/esp_zigbee_secur.h

Functions

uint8_t *esp_zb_secur_ic_get(uint8_t *ic_type)

Get the Zigbee install code from storage.

Note

Called only after esp_zb_start(), otherwise no install code has been set from production config refer to tools/mfg_tool

Warning

Only for the non-Trust Center device (non Zigbee coordinator)!

Parameters: ic_type – [out] A pointer of install code type esp_zb_secur_ic_type_t
Returns: A pointer to the install code

esp_err_t esp_zb_secur_ic_str_add(esp_zb_ieee_addr_t address, char *ic_str)

Add the Zigbee install code from remote device.

Warning

Only for the Trust Center device (Zigbee coordinator)!

Parameters

address – [in] A 64-bit ieee address of the remote device composed by array of zb_uint8_t
ic_str – [in] A string of the install code

Returns

-ESP_OK on success

esp_err_t esp_zb_secur_ic_str_set(char *ic_str)

Set the Zigbee install code from character string.

Note

if user wants to manually set install code instead of from production config refer to esp-zigbee-sdk/tools/mfg_tool

Warning

Only for the non-Trust Center device (non Zigbee coordinator)!

Parameters: ic_str – [in] A string of the install code
Returns: - ESP_OK on success

esp_err_t esp_zb_secur_ic_add(esp_zb_ieee_addr_t address, uint8_t ic_type, uint8_t *ic)

Add the Zigbee install code of a remote device with type.

Warning

Only for the Trust Center device (Zigbee coordinator)!

Parameters

address – [in] A 64-bit ieee address of the remote device composed by array of zb_uint8_t
ic_type – [in] A install code type esp_zb_secur_ic_type_t
ic – [in] A pointer of data array for install code

esp_err_t esp_zb_secur_ic_set(uint8_t ic_type, uint8_t *ic)

Set the Zigbee install code for a Zigbee device with type.

Note

if user wants to set install code with type manually instead of from production config check esp-zigbee-sdk/tools/mfg_tool

Warning

Only for the non-Trust Center device (non Zigbee coordinator)!

Parameters

ic_type – [in] A install code type esp_zb_secur_ic_type_t
ic – [in] A pointer of data array for install code

Returns

- ESP_OK on success

esp_err_t esp_zb_secur_ic_remove_req(esp_zb_ieee_addr_t address)

remove the Zigbee install code of a specific device

Warning

Only for the Trust Center device (Zigbee coordinator)!

Parameters: address – [in] device ieee addressing to remove ic
Returns: - ESP_OK on success

esp_err_t esp_zb_secur_ic_remove_all_req(void)

remove the Zigbee ALL install code

Warning

Only for the Trust Center device (Zigbee coordinator)!

Returns: - ESP_OK on success

void esp_zb_secur_TC_standard_distributed_key_set(uint8_t *key)

Set the Trust Center standard distributed key.

Parameters: key – A pointer to standard distributed key of Trust Center that will be set to

void esp_zb_secur_TC_standard_preconfigure_key_set(uint8_t *key)

Set the Trust Center pre-configured security key.

Parameters: key – A pointer to the pre-configured key of Trust Center that will be set to

void esp_zb_secur_link_key_exchange_required_set(bool enable)

Set the link key exchange requirement for a ZigBee node.

Note

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

Parameters: enable – [in] Enable or Disable

esp_err_t esp_zb_secur_network_security_enable(bool enabled)

Enable/Disable the network layer security.

Parameters

enabled – [in] A boolean indicating whether network layer security will be enabled

Returns

ESP_OK: On success
ESP_ERR_INVALID_STATE: Invalid setting when the device is in network state
Otherwise: On failure

bool esp_zb_secur_network_security_is_enabled(void)

Get the network security enabled state.

Returns: Whether the network layer security is enabled or not

esp_err_t esp_zb_secur_primary_network_key_get(uint8_t *key)

Get the primary security network key.

Note

The network key can only be obtained after the Zigbee device is the joined state.

Parameters

key – [out] The 16-byte network key

Returns

ESP_OK: on success
ESP_ERR_INVALID_STATE: invalid network state.

esp_err_t esp_zb_secur_network_key_set(uint8_t *key)

Set the Zigbee security network key.

Parameters

key – A 16-byte security network key that will be used

Returns

ESP_OK: on success
ESP_ERR_INVALID_STATE: invalid network state.

uint8_t esp_zb_secur_network_min_join_lqi_get(void)

Get the minimum LQI values for device joining the network.

Returns: The minimum LQI values

void esp_zb_secur_network_min_join_lqi_set(uint8_t lqi)

Set the minimum LQI value for device joining the network.

Parameters: lqi – [in] The LQI values

esp_err_t esp_zb_secur_multi_TC_standard_preconfigure_key_add(uint8_t *key)

Add the specified pre-configured TC standard link key for the device.

Parameters

key – [in] A pointer to 16-byte pre-configured link key to be set

Returns

ESP_OK: Preconfigured TC standard link key added successfully
ESP_FAIL: Failed to add preconfigured TC standard link key

esp_err_t esp_zb_secur_multi_TC_standard_preconfigure_key_remove(uint8_t *key)

Remove the specified pre-configured TC standard link key from the device.

Parameters

key – [in] A pointer to 16-byte the pre-configured link key to be removed

Returns

ESP_OK: Preconfigured TC standard link key removed successfully
ESP_FAIL: Failed to remove preconfigured TC standard link key

esp_err_t esp_zb_secur_multi_standard_distributed_key_add(uint8_t *key)

Add the specified pre-configured distributed link key for the device.

Parameters

key – [in] A pointer to 16-byte pre-configured distributed link key to be set

Returns

ESP_OK: Preconfigured distributed link key added successfully
ESP_FAIL: Failed to add preconfigured distributed link key

esp_err_t esp_zb_secur_multi_standard_distributed_key_remove(uint8_t *key)

Remove the specified pre-configured distributed link key from the device.

Parameters

key – [in] A pointer to 16-byte pre-configured distributed link key to be removed

Returns

ESP_OK: Preconfigured distributed link key removed successfully
ESP_FAIL: Failed to remove preconfigured distributed link key

Enumerations

enum esp_zb_secur_ic_type_t

Enum of the Zigbee secure install code type

Note

It is formed with 6/8/12/16 bytes IC (install code) + 2 bytes of CRC

Values:

enumerator ESP_ZB_IC_TYPE_48: Install code total of 8 bytes length

enumerator ESP_ZB_IC_TYPE_64: Install code total of 10 bytes length

enumerator ESP_ZB_IC_TYPE_96: Install code total of 14 bytes length

enumerator ESP_ZB_IC_TYPE_128: Install code total of 18 bytes length

enumerator ESP_ZB_IC_TYPE_MAX: Unknown type