Security API

Security related APIs for ESP Zigbee SDK.

API Reference

Header File

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