Key Establishment Client/Server#

API and Callbacks for the Key Establishment Cluster Client/Server Component.

Silicon Labs implementation of the Smart Energy Key Establishment cluster. The key establishment cluster is used by the Smart Energy profile to perform Certificate-Based Key Establishment (CBKE), which performs mutual authentication and establishes a symmetric APS link key. Direct CBKE between any two non-TC devices is supported after the two devices have completed partner link key exchange via Trust Center. This component defaults to using CBKE functions with the 163k ECC curve support, but users can also choose the 283k1 ECC curve by selecting the 'CBKE 283k1' component.

API#

bool

checkIssuer(uint8_t *issuer)

void

cleanupAndStopWithDelay(sl_zigbee_af_key_establishment_notify_message_t message, uint8_t delayInSec)

sl_zigbee_af_key_establishment_notify_message_t

sendCertificate(void)

void

sendNextKeyEstablishMessage(sli_zigbee_key_establish_message_t message, uint8_t *data)

Enumerations#

enum

sli_zigbee_key_establish_event_t {

NO_KEY_ESTABLISHMENT_EVENT = 0

CHECK_SUPPORTED_CURVES = 1

BEGIN_KEY_ESTABLISHMENT = 2

GENERATE_KEYS = 3

SEND_EPHEMERAL_DATA_MESSAGE = 4

GENERATE_SHARED_SECRET = 5

SEND_CONFIRM_KEY_MESSAGE = 6

INITIATOR_RECEIVED_CONFIRM_KEY = 7

}

Typedefs#

typedef uint8_t

sli_zigbee_key_establish_message_t

Variables#

const uint8_t

sli_zigbee_af_key_establish_message_to_data_size

sl_zigbee_af_cbke_key_establishment_suite_t

sli_zigbee_af_available_cbke_suite

sl_zigbee_af_cbke_key_establishment_suite_t

sli_zigbee_af_current_cbke_suite

sl_zigbee_af_event_t

sl_zigbee_af_key_establishment_aps_duplicate_detection_event

Macros#

#define

EM_AF_KE_INITIATE_SIZE (2 + 1 + 1 + SL_ZIGBEE_CERTIFICATE_SIZE)

Init - bytes: suite (2), key gen time (1), derive secret time (1), cert (48)

#define

EM_AF_KE_INITIATE_SIZE_283K1 (2 + 1 + 1 + SL_ZIGBEE_CERTIFICATE_283K1_SIZE)

#define

EM_AF_KE_EPHEMERAL_SIZE SL_ZIGBEE_PUBLIC_KEY_SIZE

#define

EM_AF_KE_EPHEMERAL_SIZE_283K1 SL_ZIGBEE_PUBLIC_KEY_283K1_SIZE

#define

EM_AF_KE_SMAC_SIZE SL_ZIGBEE_SMAC_SIZE

#define

EM_AF_KE_TERMINATE_SIZE (1 + 1 + 2)

Terminate - bytes: status (1), wait time (1), suite (2)

#define

APS_ACK_TIMEOUT_SECONDS 1

#define

KEY_ESTABLISHMENT_APS_DUPLICATE_DETECTION_TIMEOUT_SEC 5

#define

CERT_SUBJECT_OFFSET 22

The offset within the 163k1 curve certificate struct where the issuer field lives. 22-bytes for Public Key Reconstruction data, and 8-bytes for subject.

#define

CERT_ISSUER_OFFSET (CERT_SUBJECT_OFFSET + 8)

#define

CERT_ISSUER_SIZE 8

#define

CERT_SUBJECT_OFFSET_283K1 (1 + 8 + 1 + 1 + 8 + 5 + 4)

The offset within the 283k1 curve certificate struct where the issuer field lives. 22-bytes for Public Key Reconstruction data, and 8-bytes for subject.

#define

CERT_ISSUER_OFFSET_283K1 (1 + 8 + 1 + 1)

#define

DEFAULT_EPHEMERAL_DATA_GENERATE_TIME_SECONDS (10 + APS_ACK_TIMEOUT_SECONDS)

These values reported to the remote device as to how long the local device takes to execute these operations.

#define

DEFAULT_GENERATE_SHARED_SECRET_TIME_SECONDS (15 + APS_ACK_TIMEOUT_SECONDS)

#define

sli_zigbee_af_key_establishment_generate_cbke_keys_handler sli_zigbee_af_generate_cbke_keys_callback

#define

sli_zigbee_af_key_establishment_calculate_smacs_handler sli_zigbee_af_calculate_smacs_callback

#define

sli_zigbee_af_key_establishment_generate_cbke_keys_handler283k1 sli_zigbee_af_generate_cbke_keys_callback_283k1

#define

sli_zigbee_af_key_establishment_calculate_smacs_handler283k1 sli_zigbee_af_calculate_smacs_callback_283k1

#define

TERMINATE_STATUS_STRINGS undefined

#define

UNKNOWN_TERMINATE_STATUS 7

#define

isCbkeKeyEstablishmentSuiteValid ()

#define

isCbkeKeyEstablishmentSuite163k1 ()

#define

isCbkeKeyEstablishmentSuite283k1 ()

#define

cleanupAndStop (message)

API Documentation#

checkIssuer#

bool checkIssuer (uint8_t * issuer)

Parameters

Type	Direction	Argument Name	Description
uint8_t *	N/A	issuer

cleanupAndStopWithDelay#

void cleanupAndStopWithDelay (sl_zigbee_af_key_establishment_notify_message_t message, uint8_t delayInSec)

Parameters

Type	Direction	Argument Name	Description
sl_zigbee_af_key_establishment_notify_message_t	N/A	message
uint8_t	N/A	delayInSec

sendCertificate#

sl_zigbee_af_key_establishment_notify_message_t sendCertificate (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

sendNextKeyEstablishMessage#

void sendNextKeyEstablishMessage (sli_zigbee_key_establish_message_t message, uint8_t * data)

Parameters

Type	Direction	Argument Name	Description
sli_zigbee_key_establish_message_t	N/A	message
uint8_t *	N/A	data

Enumeration Documentation#

sli_zigbee_key_establish_event_t#

sli_zigbee_key_establish_event_t

Enumerator
NO_KEY_ESTABLISHMENT_EVENT
CHECK_SUPPORTED_CURVES
BEGIN_KEY_ESTABLISHMENT
GENERATE_KEYS
SEND_EPHEMERAL_DATA_MESSAGE
GENERATE_SHARED_SECRET
SEND_CONFIRM_KEY_MESSAGE
INITIATOR_RECEIVED_CONFIRM_KEY

Typedef Documentation#

sli_zigbee_key_establish_message_t#

typedef uint8_t sli_zigbee_key_establish_message_t

Variable Documentation#

sli_zigbee_af_key_establish_message_to_data_size#

const uint8_t sli_zigbee_af_key_establish_message_to_data_size[]

sli_zigbee_af_available_cbke_suite#

sl_zigbee_af_cbke_key_establishment_suite_t sli_zigbee_af_available_cbke_suite

sli_zigbee_af_current_cbke_suite#

sl_zigbee_af_cbke_key_establishment_suite_t sli_zigbee_af_current_cbke_suite

sl_zigbee_af_key_establishment_aps_duplicate_detection_event#

sl_zigbee_af_event_t sl_zigbee_af_key_establishment_aps_duplicate_detection_event

Macro Definition Documentation#

EM_AF_KE_INITIATE_SIZE#

#define EM_AF_KE_INITIATE_SIZE

Value:

(2 + 1 + 1 + SL_ZIGBEE_CERTIFICATE_SIZE)

Init - bytes: suite (2), key gen time (1), derive secret time (1), cert (48)

EM_AF_KE_INITIATE_SIZE_283K1#

#define EM_AF_KE_INITIATE_SIZE_283K1

Value:

(2 + 1 + 1 + SL_ZIGBEE_CERTIFICATE_283K1_SIZE)

EM_AF_KE_EPHEMERAL_SIZE#

#define EM_AF_KE_EPHEMERAL_SIZE

Value:

SL_ZIGBEE_PUBLIC_KEY_SIZE

EM_AF_KE_EPHEMERAL_SIZE_283K1#

#define EM_AF_KE_EPHEMERAL_SIZE_283K1

Value:

SL_ZIGBEE_PUBLIC_KEY_283K1_SIZE

EM_AF_KE_SMAC_SIZE#

#define EM_AF_KE_SMAC_SIZE

Value:

SL_ZIGBEE_SMAC_SIZE

EM_AF_KE_TERMINATE_SIZE#

#define EM_AF_KE_TERMINATE_SIZE

Value:

(1 + 1 + 2)

Terminate - bytes: status (1), wait time (1), suite (2)

APS_ACK_TIMEOUT_SECONDS#

#define APS_ACK_TIMEOUT_SECONDS

Value:

KEY_ESTABLISHMENT_APS_DUPLICATE_DETECTION_TIMEOUT_SEC#

#define KEY_ESTABLISHMENT_APS_DUPLICATE_DETECTION_TIMEOUT_SEC

Value:

CERT_SUBJECT_OFFSET#

#define CERT_SUBJECT_OFFSET

Value:

The offset within the 163k1 curve certificate struct where the issuer field lives. 22-bytes for Public Key Reconstruction data, and 8-bytes for subject.

CERT_ISSUER_OFFSET#

#define CERT_ISSUER_OFFSET

Value:

(CERT_SUBJECT_OFFSET + 8)

CERT_ISSUER_SIZE#

#define CERT_ISSUER_SIZE

Value:

CERT_SUBJECT_OFFSET_283K1#

#define CERT_SUBJECT_OFFSET_283K1

Value:

(1 + 8 + 1 + 1 + 8 + 5 + 4)

The offset within the 283k1 curve certificate struct where the issuer field lives. 22-bytes for Public Key Reconstruction data, and 8-bytes for subject.

CERT_ISSUER_OFFSET_283K1#

#define CERT_ISSUER_OFFSET_283K1

Value:

(1 + 8 + 1 + 1)

DEFAULT_EPHEMERAL_DATA_GENERATE_TIME_SECONDS#

#define DEFAULT_EPHEMERAL_DATA_GENERATE_TIME_SECONDS

Value:

(10 + APS_ACK_TIMEOUT_SECONDS)

These values reported to the remote device as to how long the local device takes to execute these operations.

DEFAULT_GENERATE_SHARED_SECRET_TIME_SECONDS#

#define DEFAULT_GENERATE_SHARED_SECRET_TIME_SECONDS

Value:

(15 + APS_ACK_TIMEOUT_SECONDS)

sli_zigbee_af_key_establishment_generate_cbke_keys_handler#

#define sli_zigbee_af_key_establishment_generate_cbke_keys_handler

Value:

sli_zigbee_af_generate_cbke_keys_callback

sli_zigbee_af_key_establishment_calculate_smacs_handler#

#define sli_zigbee_af_key_establishment_calculate_smacs_handler

Value:

sli_zigbee_af_calculate_smacs_callback

sli_zigbee_af_key_establishment_generate_cbke_keys_handler283k1#

#define sli_zigbee_af_key_establishment_generate_cbke_keys_handler283k1

Value:

sli_zigbee_af_generate_cbke_keys_callback_283k1

sli_zigbee_af_key_establishment_calculate_smacs_handler283k1#

#define sli_zigbee_af_key_establishment_calculate_smacs_handler283k1

Value:

sli_zigbee_af_calculate_smacs_callback_283k1

TERMINATE_STATUS_STRINGS#

#define TERMINATE_STATUS_STRINGS

Value:

{ \

"Success", \

"Unknown Issuer", \

"Bad Key Confirm", \

"Bad Message", \

"No resources", \

"Unsupported suite", \

"Invalid certificate", \

"???", \

}

UNKNOWN_TERMINATE_STATUS#

#define UNKNOWN_TERMINATE_STATUS

Value:

isCbkeKeyEstablishmentSuiteValid#

#define isCbkeKeyEstablishmentSuiteValid

Value:

()

isCbkeKeyEstablishmentSuite163k1#

#define isCbkeKeyEstablishmentSuite163k1

Value:

(sli_zigbee_af_current_cbke_suite \

== SL_ZIGBEE_AF_CBKE_KEY_ESTABLISHMENT_SUITE_163K1)

isCbkeKeyEstablishmentSuite283k1#

#define isCbkeKeyEstablishmentSuite283k1

Value:

(sli_zigbee_af_current_cbke_suite \

== SL_ZIGBEE_AF_CBKE_KEY_ESTABLISHMENT_SUITE_283K1)

cleanupAndStop#

#define cleanupAndStop

Value:

(message)