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(EmberAfKeyEstablishmentNotifyMessage message, uint8_t delayInSec)
void
sendNextKeyEstablishMessage(KeyEstablishMessage message, uint8_t *data)

Enumerations#

enum
KeyEstablishEvent {
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
KeyEstablishMessage

Variables#

Macros#

#define
EM_AF_KE_INITIATE_SIZE (2 + 1 + 1 + EMBER_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 + EMBER_CERTIFICATE_283K1_SIZE)
#define
EM_AF_KE_EPHEMERAL_SIZE EMBER_PUBLIC_KEY_SIZE
#define
EM_AF_KE_EPHEMERAL_SIZE_283K1 EMBER_PUBLIC_KEY_283K1_SIZE
#define
EM_AF_KE_SMAC_SIZE EMBER_SMAC_SIZE
#define
EM_AF_KE_TERMINATE_SIZE (1 + 1 + 2)

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

#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_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
cleanupAndStop (message)

API Documentation#

checkIssuer#

bool checkIssuer (uint8_t *issuer)
Parameters
N/Aissuer

Definition at line 140 of file app/framework/plugin/key-establishment/key-establishment.h

cleanupAndStopWithDelay#

void cleanupAndStopWithDelay (EmberAfKeyEstablishmentNotifyMessage message, uint8_t delayInSec)
Parameters
N/Amessage
N/AdelayInSec

Definition at line 141 of file app/framework/plugin/key-establishment/key-establishment.h

sendCertificate#

EmberAfKeyEstablishmentNotifyMessage sendCertificate (void)
Parameters
N/A

Definition at line 143 of file app/framework/plugin/key-establishment/key-establishment.h

sendNextKeyEstablishMessage#

void sendNextKeyEstablishMessage (KeyEstablishMessage message, uint8_t *data)
Parameters
N/Amessage
N/Adata

Definition at line 144 of file app/framework/plugin/key-establishment/key-establishment.h

Enumeration Documentation#

KeyEstablishEvent#

KeyEstablishEvent
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

Definition at line 103 of file app/framework/plugin/key-establishment/key-establishment.h

Typedef Documentation#

KeyEstablishMessage#

typedef uint8_t KeyEstablishMessage

Definition at line 117 of file app/framework/plugin/key-establishment/key-establishment.h

Variable Documentation#

sli_zigbee_af_key_establish_message_to_data_size#

const uint8_t sli_zigbee_af_key_establish_message_to_data_size[]

Definition at line 84 of file app/framework/plugin/key-establishment/key-establishment.h

sli_zigbee_af_available_cbke_suite#

EmberAfCbkeKeyEstablishmentSuite sli_zigbee_af_available_cbke_suite

Definition at line 119 of file app/framework/plugin/key-establishment/key-establishment.h

sli_zigbee_af_current_cbke_suite#

EmberAfCbkeKeyEstablishmentSuite sli_zigbee_af_current_cbke_suite

Definition at line 120 of file app/framework/plugin/key-establishment/key-establishment.h

emberAfPluginKeyEstablishmentApsDuplicateDetectionEvent#

sl_zigbee_event_t emberAfPluginKeyEstablishmentApsDuplicateDetectionEvent

Definition at line 121 of file app/framework/plugin/key-establishment/key-establishment.h

Macro Definition Documentation#

EM_AF_KE_INITIATE_SIZE#

#define EM_AF_KE_INITIATE_SIZE
Value:
(2 + 1 + 1 + EMBER_CERTIFICATE_SIZE)

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


Definition at line 51 of file app/framework/plugin/key-establishment/key-establishment.h

EM_AF_KE_INITIATE_SIZE_283K1#

#define EM_AF_KE_INITIATE_SIZE_283K1
Value:
(2 + 1 + 1 + EMBER_CERTIFICATE_283K1_SIZE)

Definition at line 52 of file app/framework/plugin/key-establishment/key-establishment.h

EM_AF_KE_EPHEMERAL_SIZE#

#define EM_AF_KE_EPHEMERAL_SIZE
Value:
EMBER_PUBLIC_KEY_SIZE

Definition at line 53 of file app/framework/plugin/key-establishment/key-establishment.h

EM_AF_KE_EPHEMERAL_SIZE_283K1#

#define EM_AF_KE_EPHEMERAL_SIZE_283K1
Value:
EMBER_PUBLIC_KEY_283K1_SIZE

Definition at line 54 of file app/framework/plugin/key-establishment/key-establishment.h

EM_AF_KE_SMAC_SIZE#

#define EM_AF_KE_SMAC_SIZE
Value:
EMBER_SMAC_SIZE

Definition at line 55 of file app/framework/plugin/key-establishment/key-establishment.h

EM_AF_KE_TERMINATE_SIZE#

#define EM_AF_KE_TERMINATE_SIZE
Value:
(1 + 1 + 2)

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


Definition at line 59 of file app/framework/plugin/key-establishment/key-establishment.h

APS_ACK_TIMEOUT_SECONDS#

#define APS_ACK_TIMEOUT_SECONDS
Value:
1

Definition at line 61 of file app/framework/plugin/key-establishment/key-establishment.h

KEY_ESTABLISHMENT_APS_DUPLICATE_DETECTION_TIMEOUT_SEC#

#define KEY_ESTABLISHMENT_APS_DUPLICATE_DETECTION_TIMEOUT_SEC
Value:
5

Definition at line 63 of file app/framework/plugin/key-establishment/key-establishment.h

CERT_SUBJECT_OFFSET#

#define CERT_SUBJECT_OFFSET
Value:
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.


Definition at line 68 of file app/framework/plugin/key-establishment/key-establishment.h

CERT_ISSUER_OFFSET#

#define CERT_ISSUER_OFFSET
Value:
(CERT_SUBJECT_OFFSET + 8)

Definition at line 69 of file app/framework/plugin/key-establishment/key-establishment.h

CERT_ISSUER_SIZE#

#define CERT_ISSUER_SIZE
Value:
8

Definition at line 70 of file app/framework/plugin/key-establishment/key-establishment.h

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.


Definition at line 75 of file app/framework/plugin/key-establishment/key-establishment.h

CERT_ISSUER_OFFSET_283K1#

#define CERT_ISSUER_OFFSET_283K1
Value:
(1 + 8 + 1 + 1)

Definition at line 76 of file app/framework/plugin/key-establishment/key-establishment.h

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.


Definition at line 81 of file app/framework/plugin/key-establishment/key-establishment.h

DEFAULT_GENERATE_SHARED_SECRET_TIME_SECONDS#

#define DEFAULT_GENERATE_SHARED_SECRET_TIME_SECONDS
Value:
(15 + APS_ACK_TIMEOUT_SECONDS)

Definition at line 82 of file app/framework/plugin/key-establishment/key-establishment.h

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

Definition at line 86 of file app/framework/plugin/key-establishment/key-establishment.h

sli_zigbee_af_key_establishment_calculate_smacs_handler#

#define sli_zigbee_af_key_establishment_calculate_smacs_handler
Value:
sli_zigbee_af_calculate_smacs_callback

Definition at line 87 of file app/framework/plugin/key-establishment/key-establishment.h

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

Definition at line 88 of file app/framework/plugin/key-establishment/key-establishment.h

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

Definition at line 89 of file app/framework/plugin/key-establishment/key-establishment.h

TERMINATE_STATUS_STRINGS#

#define TERMINATE_STATUS_STRINGS
Value:
{ \
"Success", \
"Unknown Issuer", \
"Bad Key Confirm", \
"Bad Message", \
"No resources", \
"Unsupported suite", \
"Invalid certificate", \
"???", \
}

Definition at line 91 of file app/framework/plugin/key-establishment/key-establishment.h

UNKNOWN_TERMINATE_STATUS#

#define UNKNOWN_TERMINATE_STATUS
Value:
7

Definition at line 101 of file app/framework/plugin/key-establishment/key-establishment.h

isCbkeKeyEstablishmentSuiteValid#

#define isCbkeKeyEstablishmentSuiteValid
Value:
()

Definition at line 122 of file app/framework/plugin/key-establishment/key-establishment.h

isCbkeKeyEstablishmentSuite163k1#

#define isCbkeKeyEstablishmentSuite163k1
Value:
(sli_zigbee_af_current_cbke_suite \
== EMBER_AF_CBKE_KEY_ESTABLISHMENT_SUITE_163K1)

Definition at line 125 of file app/framework/plugin/key-establishment/key-establishment.h

isCbkeKeyEstablishmentSuite283k1#

#define isCbkeKeyEstablishmentSuite283k1
Value:
(sli_zigbee_af_current_cbke_suite \
== EMBER_AF_CBKE_KEY_ESTABLISHMENT_SUITE_283K1)

Definition at line 129 of file app/framework/plugin/key-establishment/key-establishment.h

cleanupAndStop#

#define cleanupAndStop
Value:
(message)

Definition at line 133 of file app/framework/plugin/key-establishment/key-establishment.h