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.
-
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
requiredwill not request key from the ZigBee coordinator. The ZigBee coordinator withoutrequiredallows 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_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
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_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
-
enumerator EZB_SECUR_SECLEVEL_NONE
-
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_MAX_NR
Unknown type
-
enumerator EZB_SECUR_IC_TYPE_48