SE security subsystem

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 this device. More...
zb_bool_t	zb_se_has_valid_key_by_ieee (zb_ieee_addr_t addr)
zb_ret_t	zb_se_debug_get_link_key (zb_uint16_t addr, zb_uint8_t link_key[ZB_CCM_KEY_SIZE])
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])
zb_ret_t	zb_se_debug_get_nwk_key (zb_uint8_t key[ZB_CCM_KEY_SIZE])
void	zb_debug_bcast_key (zb_uint8_t *peer_addr, zb_uint8_t key[ZB_CCM_KEY_SIZE])
zb_ret_t	zb_se_debug_get_ic_key (zb_uint8_t key[ZB_CCM_KEY_SIZE])
void	zb_se_start_aps_key_establishment (zb_uint8_t param, zb_uint16_t addr)
	Starts procedure of partner APS Link key establishment with specified device. More...

Detailed Description

Function Documentation

zb_debug_bcast_key()

void zb_debug_bcast_key	(	zb_uint8_t *	peer_addr,
		zb_uint8_t	key[ZB_CCM_KEY_SIZE]
	)

Broadcast a key using non-standard NWK report (command id 6).

To be used for debug purposes only.

Parameters

peer_addr	- address of remote device, or NULL
key	- APS or NWK key

zb_se_debug_get_ic_key()

zb_ret_t zb_se_debug_get_ic_key

(

zb_uint8_t

key[ZB_CCM_KEY_SIZE]

)

Get APS key generated from the current installcode. To be used mainly for debug purposes.

Parameters

key	- buffer for the key

Returns

RET_OK or error code

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]
	)

Get APS link key or TCLK for remote device. To be used mainly for debug purposes. Check key availability using zb_se_has_valid_key() before this call.

Parameters

addr	- short address of remote device
link_key	- buffer for the key

Returns

RET_OK or error code

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]
	)

Get APS link key or TCLK for remote device by its long address. To be used mainly for debug purposes.

Parameters

ieee	- long address of remote device
link_key	- buffer for the key

Returns

RET_OK or error code

zb_se_debug_get_nwk_key()

zb_ret_t zb_se_debug_get_nwk_key

(

zb_uint8_t

key[ZB_CCM_KEY_SIZE]

)

Get current NWK key, To be used mainly for debug purposes.

Parameters

key	- buffer for the key

Returns

RET_OK or error code

zb_se_erase_ecc_cert()

zb_uint8_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.

Parameters

[in]	suite_no	- CryptoSuite #
[in]	issuer	- buffer with certificate's issuer
[in]	subject	- buffer MAC address (IEEE 802.15.4)

Note

This function is designed mainly for Trust Center devices as for purpose of erasing certificates from NVRAM by suite, issuer and subject(MAC address).

zb_se_has_valid_key()

zb_bool_t zb_se_has_valid_key

(

zb_uint16_t

addr

)

Checks availability of valid keypair for this device.

Parameters

[in]

addr

- short address of the remote device

Returns

ZB_TRUE if valid key exists, ZB_FALSE otherwise.

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

Example

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 - start APS partner link key establishment

zb_se_load_ecc_cert()

zb_uint8_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.

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

Note

This function is designed mainly for Trust Center devices as an additional method of adding certificates from several CAs.

Example

#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

zb_se_retry_cbke_with_tc

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
	)

Starts procedure of partner APS Link key establishment with specified device.

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

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 this signals if needed.

See also

ZB_SE_SIGNAL_APS_KEY_READY - signal description

ZB_SE_SIGNAL_APS_KEY_FAIL - signal description

ZB_SE_SIGNAL_CBKE_OK - example code of signal handling

zb_se_has_valid_key - check if there is a valid APS key with the device