Logo
Developing with ZBOSS for Zigbee
Functions
SE security subsystem
Zigbee stack API » SE API

Functions

zb_ret_t zb_se_load_ecc_cert (zb_uint16_t suite, zb_uint8_t *ca_public_key, zb_uint8_t *certificate, zb_uint8_t *private_key)
 Loads device's certificate to NVRAM. More...
 
zb_ret_t zb_se_erase_ecc_cert (zb_uint8_t suite_no, zb_uint8_t *issuer, zb_uint8_t *subject)
 Erases device's certificate from NVRAM. More...
 
zb_bool_t zb_se_has_valid_key (zb_uint16_t addr)
 Checks availability of valid keypair for the specified remote device using its short address. More...
 
zb_bool_t zb_se_has_valid_key_by_ieee (zb_ieee_addr_t addr)
 Checks availability of valid keypair for the specified remote device using its address as a keypair established between a pair of devices. More...
 
zb_ret_t zb_se_debug_get_link_key (zb_uint16_t addr, zb_uint8_t link_key[ZB_CCM_KEY_SIZE])
 Retrieves APS link key or TCLK for the remote device. More...
 
zb_ret_t zb_se_debug_get_link_key_by_long (zb_ieee_addr_t ieee, zb_uint8_t link_key[ZB_CCM_KEY_SIZE])
 Retrieves APS link key or TCLK for the remote device using it's long address. More...
 
zb_ret_t zb_se_debug_get_nwk_key (zb_uint8_t key[ZB_CCM_KEY_SIZE])
 Retrieves current NWK key. More...
 
zb_ret_t zb_se_debug_get_ic_key (zb_uint8_t key[ZB_CCM_KEY_SIZE])
 Retrieves APS link key generated from the current installcode. More...
 
void zb_se_start_aps_key_establishment (zb_uint8_t param, zb_uint16_t addr)
 Starts procedure of partner APS link key establishment with the specified device. More...
 

Detailed Description

Function Documentation

§ zb_se_debug_get_ic_key()

zb_ret_t zb_se_debug_get_ic_key ( zb_uint8_t  key[ZB_CCM_KEY_SIZE])

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_se.h>

Retrieves APS link key generated from the current installcode.

Parameters
[out]key- buffer for the key
Return values
RET_OK- on success
RET_NOT_FOUND- no installcode found
RET_PROTOCOL_ERROR- bad CRC in installcode
Attention
To be used mainly for debug purposes.

§ zb_se_debug_get_link_key()

zb_ret_t zb_se_debug_get_link_key ( zb_uint16_t  addr,
zb_uint8_t  link_key[ZB_CCM_KEY_SIZE] 
)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_se.h>

Retrieves APS link key or TCLK for the remote device.

Parameters
[in]addr- short address of the remote device
[out]link_key- buffer for the key
Return values
RET_OK- on success
RET_NOT_FOUND- link key wasn't found
Attention
To be used mainly for debug purposes. Key availability should be verified using zb_se_has_valid_key() before making this call.
See also
zb_se_debug_get_link_key_by_long()

§ zb_se_debug_get_link_key_by_long()

zb_ret_t zb_se_debug_get_link_key_by_long ( zb_ieee_addr_t  ieee,
zb_uint8_t  link_key[ZB_CCM_KEY_SIZE] 
)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_se.h>

Retrieves APS link key or TCLK for the remote device using it's long address.

Parameters
[in]ieee- long address of the remote device
[out]link_key- buffer for the key
Return values
RET_OK- on success
RET_NOT_FOUND- link key wasn't found
Attention
To be used mainly for debug purposes.
See also
zb_se_debug_get_link_key()

§ zb_se_debug_get_nwk_key()

zb_ret_t zb_se_debug_get_nwk_key ( zb_uint8_t  key[ZB_CCM_KEY_SIZE])

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_se.h>

Retrieves current NWK key.

Parameters
[out]key- buffer for the key
Return values
RET_OK- on success
RET_NOT_FOUND- NWK key wasn't found
Attention
To be used mainly for debug purposes.

§ zb_se_erase_ecc_cert()

zb_ret_t zb_se_erase_ecc_cert ( zb_uint8_t  suite_no,
zb_uint8_t *  issuer,
zb_uint8_t *  subject 
)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_se.h>

Erases device's certificate from NVRAM.

Parameters
[in]suite_no- CryptoSuite number
[in]issuer- buffer with certificate's issuer
[in]subject- buffer MAC address (IEEE 802.15.4)
Return values
RET_OK- entry was found and successfully deleted
RET_NOT_FOUND- there was no such entry
Note
This function is designed primarily for Trust Center devices to erase certificates from NVRAM by suite, issuer and subject (MAC address).
Error codes might originate from NVRAM operations.
See also
zb_se_load_ecc_cert()

§ zb_se_has_valid_key()

zb_bool_t zb_se_has_valid_key ( zb_uint16_t  addr)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_se.h>

Checks availability of valid keypair for the specified remote device using its short address.

Valid key is either a TCLK to TC established by CBKE procedure or a partner APS link key established using partner link keys establishment procedure.

Parameters
[in]addr- short address of the remote device
Return values
ZB_TRUE- valid key exists
ZB_FALSE- no valid key exists
Example
If there is no valid keypair, then the key establishment is initiated:
if (dev_addr != 0 && !zb_se_has_valid_key(dev_addr)
{
ZB_SCHEDULE_CALLBACK2(zb_se_start_aps_key_establishment, param, dev_addr);
}
See also
zb_se_start_aps_key_establishment()
zb_se_has_valid_key_by_ieee()

§ zb_se_has_valid_key_by_ieee()

zb_bool_t zb_se_has_valid_key_by_ieee ( zb_ieee_addr_t  addr)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_se.h>

Checks availability of valid keypair for the specified remote device using its address as a keypair established between a pair of devices.

Valid key definition is in the zb_se_has_valid_key().

Parameters
[in]addr- long address of the remote device
Return values
ZB_TRUE- valid key exists
ZB_FALSE- no valid key exists
See also
zb_se_start_aps_key_establishment()
zb_se_has_valid_key()

§ zb_se_load_ecc_cert()

zb_ret_t zb_se_load_ecc_cert ( zb_uint16_t  suite,
zb_uint8_t *  ca_public_key,
zb_uint8_t *  certificate,
zb_uint8_t *  private_key 
)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_se.h>

Loads device's certificate to NVRAM.

This function is used to store a private key and a digital certificate, which is signed by a Certificate Authority (CA).

Parameters
[in]suite- CryptoSuite ID (kec_key_suite)
[in]ca_public_key- buffer with Certification Authority's public key
[in]certificate- buffer with device's certificate
[in]private_key- buffer with device's private key
Return values
RET_OK- on success
RET_CONVERSION_ERROR- invalid certificate for the issuer
Note
This function is designed mainly for Trust Center devices as an additional method of adding certificates from several CAs.
Example
Loading certificates into NVRAM with both CryptoSuites:
#ifdef SE_CRYPTOSUITE_1
zb_se_load_ecc_cert(KEC_CS1, ca_public_key_cs1, esi_certificate_cs1, esi_private_key_cs1);
#endif
#ifdef SE_CRYPTOSUITE_2
zb_se_load_ecc_cert(KEC_CS2, ca_public_key_cs2, esi_certificate_cs2, esi_private_key_cs2);
#endif
See also
Certificate-Based Key Establishment 10.7.6.2 (ZCL8)
ZB_SE_SIGNAL_CBKE_FAILED

§ zb_se_start_aps_key_establishment()

void zb_se_start_aps_key_establishment ( zb_uint8_t  param,
zb_uint16_t  addr 
)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_se.h>

Starts procedure of partner APS link key establishment with the specified device.

ZBOSS indicates completion status of this procedure by passing ZB_SE_SIGNAL_APS_KEY_READY and ZB_SE_SIGNAL_APS_KEY_FAIL signals to the application's signal handler. Application should process these signals if needed.

Parameters
[in]param- reference to the buffer, which will be used for outgoing Match Descriptor Request command
[in]addr- short address of the remote device
See also
ZB_SE_SIGNAL_APS_KEY_READY
ZB_SE_SIGNAL_APS_KEY_FAIL
ZB_SE_SIGNAL_CBKE_OK
zb_se_has_valid_key()
Copyright (c) 2012-2022 DSR Corporation, Golden CO, USA. http://www.dsr-zboss.com http://www.dsr-corporation.com
ZBOSS documentation. Wed Oct 29 2025.