Developing with ZBOSS for Zigbee
Data Structures | Typedefs | Functions
Install code usage
Zigbee stack API » Security subsystem API

Data Structures

struct  zb_secur_ic_get_list_req_s
 Request for zb_secur_ic_get_list_req. More...
 
struct  zb_secur_ic_get_list_resp_s
 Response for zb_secur_ic_get_list_req. More...
 
struct  zb_secur_ic_entry_s
 IC entry type zb_secur_ic_get_list_req. More...
 
struct  zb_secur_ic_get_by_idx_req_s
 Request for zb_secur_ic_get_by_idx_req. More...
 
struct  zb_secur_ic_get_by_idx_resp_s
 Response for zb_secur_ic_get_by_idx_req. More...
 
struct  zb_secur_ic_remove_req_s
 Request for zb_secur_ic_remove_req. More...
 
struct  zb_secur_ic_remove_resp_s
 Response for zb_secur_ic_remove_req. More...
 
struct  zb_secur_ic_remove_all_req_s
 Request for zb_secur_ic_remove_all_req. More...
 
struct  zb_secur_ic_remove_all_resp_s
 Response for zb_secur_ic_remove_all_req. More...
 

Typedefs

typedef zb_uint8_t zb_ic_types_t
 Type for IC types. More...
 
typedef void(* zb_secur_ic_add_cb_t) (zb_ret_t status)
 
typedef struct zb_secur_ic_get_list_req_s zb_secur_ic_get_list_req_t
 Request for zb_secur_ic_get_list_req.
 
typedef struct zb_secur_ic_get_list_resp_s zb_secur_ic_get_list_resp_t
 Response for zb_secur_ic_get_list_req.
 
typedef struct zb_secur_ic_entry_s zb_secur_ic_entry_t
 IC entry type zb_secur_ic_get_list_req.
 
typedef struct zb_secur_ic_get_by_idx_req_s zb_secur_ic_get_by_idx_req_t
 Request for zb_secur_ic_get_by_idx_req.
 
typedef struct zb_secur_ic_get_by_idx_resp_s zb_secur_ic_get_by_idx_resp_t
 Response for zb_secur_ic_get_by_idx_req.
 
typedef struct zb_secur_ic_remove_req_s zb_secur_ic_remove_req_t
 Request for zb_secur_ic_remove_req.
 
typedef struct zb_secur_ic_remove_resp_s zb_secur_ic_remove_resp_t
 Response for zb_secur_ic_remove_req.
 
typedef struct zb_secur_ic_remove_all_req_s zb_secur_ic_remove_all_req_t
 Request for zb_secur_ic_remove_all_req.
 
typedef struct zb_secur_ic_remove_all_resp_s zb_secur_ic_remove_all_resp_t
 Response for zb_secur_ic_remove_all_req.
 

Functions

void zb_secur_ic_add (const zb_ieee_addr_t address, zb_uint8_t ic_type, zb_uint8_t const *ic, zb_secur_ic_add_cb_t cb)
 Add install code for the device with specified long address. More...
 
zb_ret_t zb_secur_ic_set (zb_uint8_t ic_type, const zb_uint8_t *ic)
 Set install code for the device. More...
 
void zb_secur_ic_get_list_req (zb_uint8_t param)
 Get list of the install codes. It is valid only for the TC (ZC). More...
 
void zb_secur_ic_get_by_idx_req (zb_uint8_t param)
 Get the install code by index. It is valid only for the TC (ZC). More...
 
void zb_secur_ic_remove_req (zb_uint8_t param)
 Remove the install code for the device with specified long address. It is valid only for the TC (ZC). More...
 
void zb_secur_ic_remove_all_req (zb_uint8_t param)
 
zb_ret_t zb_secur_ic_str_set (char *ic_str)
 Set install code for the device from character string. More...
 
void zb_secur_ic_str_add (zb_ieee_addr_t address, char *ic_str, zb_secur_ic_add_cb_t cb)
 Add install code for the device from character string. More...
 
void zb_set_installcode_policy (zb_bool_t allow_ic_only)
 

IC types

/* Set passcode for joiner */
zb_secur_ic_set(ZB_IC_TYPE_PASSCODE, g_r23_zed_passcode);
#define ZB_IC_TYPE_48   0U
 
#define ZB_IC_TYPE_64   1U
 
#define ZB_IC_TYPE_96   2U
 
#define ZB_IC_TYPE_128   3U
 
#define ZB_IC_TYPE_PASSCODE   4U /*<! Not an Installcode indeed, but r23 passcode (4 bytes) - extends to 128bit */
 
#define ZB_IC_TYPE_128_HASHED
 
#define ZB_IC_TYPE_MAX   6U
 

The Key Negotiation Protocols Bitmask Table I.5.1-4-54

The Key Negotiation Protocols Bitmask Table I.5.1-4-54 (merged with Zigbee Direct 6.5.2.1. Zigbee Direct Key Negotiation Method TLV)

/* The application can also change key negotiation methods and PSK secrets.
* For example, we disable ZB_TLV_KEY_ECDHE_KEY_REQUEST_ZB_30.
* It means that ZC will not accept r23+ devices without DLK support */
zb_disable_key_neg_method(ZB_TLV_KEY_ECDHE_KEY_REQUEST_ZB_30);
/* That call is just for a demo here. That method is already enabled by
* zboss_use_r23_behavior() call. */
zb_enable_key_neg_method(ZB_TLV_KEY_ECDHE_CURVE_25519_HASH_SHA256);

Note: These values were members of zb_tlv_key_negotiation_methods_t enum zb_tlv_key_negotiation_methods_e type but were converted to a set of macros due to MISRA violations.

typedef zb_uint8_t zb_tlv_key_negotiation_methods_t
 
#define ZB_TLV_KEY_ECDHE_KEY_REQUEST_ZB_30   0x00U /*<! Static Key Update Request */
 
#define ZB_TLV_DIRECT_KEY_ECDHE_RESERVED_MIN   0x00U /*<! 0 is reserved in zigbee direct */
 
#define ZB_TLV_KEY_ECDHE_CURVE_25519_HASH_AESMMO128   0x01U /*<! DLK with curve 25519 and hash AESMMO128 */
 
#define ZB_TLV_KEY_ECDHE_CURVE_25519_HASH_SHA256   0x02U /*<! DLK with curve 25519 and hash SHA256 */
 
#define ZB_TLV_KEY_ECDHE_RESERVED_MAX   0x03U /*<! 3-15 is reserved in r23 */
 
#define ZB_TLV_KEY_ECDHE_CURVE_P256_HASH_SHA256   0x03U /*<! ZB Direct only: curve P256, hash SHA256 */
 
#define ZB_TLV_DIRECT_KEY_ECDHE_RESERVED_MAX   0x04U /*<! reserved value for Direct */
 

bitmask for support_secrets, value for selected secret

/* Rewrite supported PSK secrets bit mask. Just to demonstrate the API */
{
zb_uint8_t supported_secrets_mask = 0;
ZB_TLV_PSK_SECRET_ENABLE(supported_secrets_mask, ZB_TLV_PSK_SECRET_AUTH_TOKEN);
ZB_TLV_PSK_SECRET_ENABLE(supported_secrets_mask, ZB_TLV_PSK_SECRET_INSTALL_CODE);
ZB_TLV_PSK_SECRET_ENABLE(supported_secrets_mask, ZB_TLV_PSK_SECRET_PAKE_PASSCODE);
zb_set_supported_psk_secrets(supported_secrets_mask);
}

Note: These values were members of zb_tlv_psk_secrets_t enum zb_tlv_psk_secrets_e type but were converted to a set of macros due to MISRA violations.

typedef zb_uint8_t zb_tlv_psk_secrets_t
 
#define ZB_TLV_PSK_SECRET_AUTH_TOKEN   0x00U
 
#define ZB_TLV_PSK_SECRET_INSTALL_CODE   0x01U
 
#define ZB_TLV_PSK_SECRET_PAKE_PASSCODE   0x02U
 
#define ZB_TLV_PSK_SECRET_BASIC_ACCESS_KEY   0x03U
 
#define ZB_TLV_PSK_SECRET_ADMINISTRATIVE_ACCESS_KEY   0x04U
 
#define ZB_TLV_PSK_SECRET_RESERVED_MAX   0x05U /* 6-7 is reserved */
 
#define ZB_TLV_PSK_SECRET_WELL_KNOWN_KEY   0xFFU
 

Detailed Description

Macro Definition Documentation

◆ ZB_IC_TYPE_128_HASHED

#define ZB_IC_TYPE_128_HASHED
Value:
5U /*<! Hashed installcode, allows to prepare and
add Link Key via zb_secur_ic_add() from
the application side */

Typedef Documentation

◆ zb_ic_types_t

typedef zb_uint8_t zb_ic_types_t

Type for IC types.

Holds one of ic_types. Kept only for backward compatibility as ic_types were declared previously as enum. Can be removed in future releases.

◆ zb_secur_ic_add_cb_t

typedef void(* zb_secur_ic_add_cb_t) (zb_ret_t status)

Declares application callback that is called after installcode addition.

Parameters
status- status of installcode addition

Function Documentation

◆ zb_secur_ic_add()

void zb_secur_ic_add ( const zb_ieee_addr_t  address,
zb_uint8_t  ic_type,
zb_uint8_t const *  ic,
zb_secur_ic_add_cb_t  cb 
)

Add install code for the device with specified long address.

Parameters
[in]address- long address of the device to add the install code
[in]ic_type- install code type as enumerated in ic_types
[in]cb- callback that will be called after installcode addition
[in]ic- pointer to the install code buffer

This call allows to add install codes for several devices into NVRAM. It makes sense for Trust Center/Coordinator devices only as usual device doesn't need to have someone's else install codes.

Note
This call is valid only for the TC (ZC)!
Example
zb_ieee_addr_t g_zr1_addr = IC_ZR1_IEEE_ADDR;
static zb_uint8_t g_ic1[16+2] = {0x83, 0xFE, 0xD3, 0x40, 0x7A, 0x93, 0x97, 0x23,
0xA5, 0xC6, 0x39, 0xB2, 0x69, 0x16, 0xD5, 0x05,
/* CRC */ 0xC3, 0xB5};
zb_secur_ic_add(g_zr1_addr, ZB_IC_TYPE_128, g_ic1, NULL);

◆ zb_secur_ic_get_by_idx_req()

void zb_secur_ic_get_by_idx_req ( zb_uint8_t  param)

Get the install code by index. It is valid only for the TC (ZC).

Parameters
parambuffer with request parameters, will be also used to store response.
zb_secur_ic_get_by_idx_req_t *req_param;
TRACE_MSG(TRACE_APP1, ">> ic_get_by_idx, param %hd", (FMT__H, param));
TRACE_MSG(TRACE_APP1, " ic_get_by_idx: ic_index %hd", (FMT__H, ic_index));
req_param = ZB_BUF_GET_PARAM(param, zb_secur_ic_get_by_idx_req_t);
req_param->response_cb = ic_get_by_idx_cb;
req_param->ic_index = ic_index;
zb_secur_ic_get_by_idx_req(param);

◆ zb_secur_ic_get_list_req()

void zb_secur_ic_get_list_req ( zb_uint8_t  param)

Get list of the install codes. It is valid only for the TC (ZC).

Parameters
parambuffer with request parameters, will be also used to store response.
zb_secur_ic_get_list_req_t *req;
TRACE_MSG(TRACE_APP1, ">> ic_list_get, param %hd", (FMT__H, param));
TRACE_MSG(TRACE_APP1, " ic_list_get: start_idx %hd", (FMT__H, start_index));
req= ZB_BUF_GET_PARAM(param, zb_secur_ic_get_list_req_t);
req->response_cb = ic_list_get_cb;
req->start_index = start_index;
zb_secur_ic_get_list_req(param);
TRACE_MSG(TRACE_APP1, "<< ic_list_get", (FMT__0));

◆ zb_secur_ic_remove_all_req()

void zb_secur_ic_remove_all_req ( zb_uint8_t  param)

Remove the install code for all devices. It is valid only for the TC (ZC).

Parameters
parambuffer with request parameters, will be also used to store response.
zb_secur_ic_remove_all_req_t *req_param;
TRACE_MSG(TRACE_APP1, ">> ic_remove_all, param %hd", (FMT__H, param));
req_param = ZB_BUF_GET_PARAM(param, zb_secur_ic_remove_all_req_t);
req_param->response_cb = ic_remove_all_cb;
zb_secur_ic_remove_all_req(param);
TRACE_MSG(TRACE_APP1, "<< ic_remove_all", (FMT__0));

◆ zb_secur_ic_remove_req()

void zb_secur_ic_remove_req ( zb_uint8_t  param)

Remove the install code for the device with specified long address. It is valid only for the TC (ZC).

Parameters
parambuffer with request parameters, will be also used to store response.
zb_secur_ic_remove_req_t *req_param;
TRACE_MSG(TRACE_APP1, ">> ic_remove_by_device_idx, param %hd", (FMT__H, param));
req_param = ZB_BUF_GET_PARAM(param, zb_secur_ic_remove_req_t);
req_param->response_cb = ic_remove_by_device_idx_cb;
ZB_IEEE_ADDR_COPY(req_param->device_address, g_zr1_addr);
zb_secur_ic_remove_req(param);
TRACE_MSG(TRACE_APP1, "<< ic_remove_by_device_idx", (FMT__0));

◆ zb_secur_ic_set()

zb_ret_t zb_secur_ic_set ( zb_uint8_t  ic_type,
const zb_uint8_t *  ic 
)

Set install code for the device.

Parameters
[in]ic_type- install code type as enumerated in ic_types
[in]ic- pointer to the install code buffer

This call allows to set the install code for the current device. It is assumed that device can have only one install code.

Note
This function is to be run at client side (not at TC).
Returns
RET_OK on success or RET_CONVERSION_ERROR on error in install code
zb_secur_ic_set(ZB_IC_TYPE_128, g_ic1);
/* Set passcode for joiner */
zb_secur_ic_set(ZB_IC_TYPE_PASSCODE, g_r23_zed_passcode);

◆ zb_secur_ic_str_add()

void zb_secur_ic_str_add ( zb_ieee_addr_t  address,
char *  ic_str,
zb_secur_ic_add_cb_t  cb 
)

Add install code for the device from character string.

Parameters
[in]address- long address of the device to add the install code for
[in]ic_str- install code text string
[in]cb- callback that will be called after installcode addition

This call allows to add install codes for several devices into NVRAM. It makes sense for Trust Center/Coordinator devices only as usual device doesn't need to have someone's else install codes.

Note
This call is valid only for the TC (ZC)!
zb_secur_ic_str_add(g_zr2_addr, IC_ZR2_INSTALL_CODE_STR, NULL);

◆ zb_secur_ic_str_set()

zb_ret_t zb_secur_ic_str_set ( char *  ic_str)

Set install code for the device from character string.

Parameters
[in]ic_str- install code text string

This call allows to set the install code for the current device. It is assumed that device can have only one install code.

Note
This function is to be run at client side (not at TC).
Returns
RET_OK on success.
char* g_ic_zr2_install_code = IC_ZR2_INSTALL_CODE_STR;
zb_secur_ic_str_set(g_ic_zr2_install_code);

◆ zb_set_installcode_policy()

void zb_set_installcode_policy ( zb_bool_t  allow_ic_only)

Set installcode policy flag.

Parameters
allow_ic_only- use ZB_TRUE value to check installcodes
zb_set_installcode_policy(ZB_TRUE);
zb_uint8_t
unsigned char zb_uint8_t
Project-local 1-byte unsigned int type.
Definition: zb_types.h:147
TRACE_MSG
#define TRACE_MSG(lm, fmts, args)
Put trace output.
Definition: zb_trace.h:369
zb_secur_ic_remove_all_req_s
Request for zb_secur_ic_remove_all_req.
Definition: zboss_api.h:318
zb_secur_ic_remove_all_req_s::response_cb
zb_callback_t response_cb
Definition: zboss_api.h:320
zb_secur_ic_get_by_idx_req_s::response_cb
zb_callback_t response_cb
Definition: zboss_api.h:279
zb_secur_ic_get_by_idx_req_s
Request for zb_secur_ic_get_by_idx_req.
Definition: zboss_api.h:275
zb_set_installcode_policy
void zb_set_installcode_policy(zb_bool_t allow_ic_only)
zb_secur_ic_remove_req_s::device_address
zb_ieee_addr_t device_address
Definition: zboss_api.h:301
zb_secur_ic_get_list_req_s
Request for zb_secur_ic_get_list_req.
Definition: zboss_api.h:242
ZB_BUF_GET_PARAM
#define ZB_BUF_GET_PARAM(buf, type)
Definition: zboss_api_buf.h:457
ZB_TRUE
#define ZB_TRUE
Definition: zb_types.h:350
zb_secur_ic_get_list_req_s::start_index
zb_uint8_t start_index
Definition: zboss_api.h:244
zb_set_supported_psk_secrets
void zb_set_supported_psk_secrets(zb_uint8_t secret_mask)
zb_secur_ic_str_set
zb_ret_t zb_secur_ic_str_set(char *ic_str)
Set install code for the device from character string.
zb_enable_key_neg_method
void zb_enable_key_neg_method(zb_uint8_t method)
zb_secur_ic_get_by_idx_req_s::ic_index
zb_uint8_t ic_index
Definition: zboss_api.h:277
zb_secur_ic_add
void zb_secur_ic_add(const zb_ieee_addr_t address, zb_uint8_t ic_type, zb_uint8_t const *ic, zb_secur_ic_add_cb_t cb)
Add install code for the device with specified long address.
zb_disable_key_neg_method
void zb_disable_key_neg_method(zb_uint8_t method)
zb_secur_ic_remove_req_s::response_cb
zb_callback_t response_cb
Definition: zboss_api.h:302
zb_ieee_addr_t
zb_64bit_addr_t zb_ieee_addr_t
Long (64-bit) device address.
Definition: zb_types.h:535
ZB_TLV_PSK_SECRET_ENABLE
#define ZB_TLV_PSK_SECRET_ENABLE(var, secret)
Definition: zboss_api.h:1161
zb_secur_ic_str_add
void zb_secur_ic_str_add(zb_ieee_addr_t address, char *ic_str, zb_secur_ic_add_cb_t cb)
Add install code for the device from character string.
zb_secur_ic_remove_all_req
void zb_secur_ic_remove_all_req(zb_uint8_t param)
zb_secur_ic_get_list_req
void zb_secur_ic_get_list_req(zb_uint8_t param)
Get list of the install codes. It is valid only for the TC (ZC).
zb_secur_ic_set
zb_ret_t zb_secur_ic_set(zb_uint8_t ic_type, const zb_uint8_t *ic)
Set install code for the device.
zb_secur_ic_remove_req
void zb_secur_ic_remove_req(zb_uint8_t param)
Remove the install code for the device with specified long address. It is valid only for the TC (ZC).
zb_secur_ic_remove_req_s
Request for zb_secur_ic_remove_req.
Definition: zboss_api.h:299
zb_secur_ic_get_by_idx_req
void zb_secur_ic_get_by_idx_req(zb_uint8_t param)
Get the install code by index. It is valid only for the TC (ZC).
zb_secur_ic_get_list_req_s::response_cb
zb_callback_t response_cb
Definition: zboss_api.h:246