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
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
emAfPluginKeyEstablishmentGenerateCbkeKeysHandler emberAfGenerateCbkeKeysCallback
#define
emAfPluginKeyEstablishmentCalculateSmacsHandler emberAfCalculateSmacsCallback
#define
emAfPluginKeyEstablishmentGenerateCbkeKeysHandler283k1 emberAfGenerateCbkeKeysHandler283k1Callback
#define
emAfPluginKeyEstablishmentCalculateSmacsHandler283k1 emberAfCalculateSmacsHandler283k1Callback
#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
TypeDirectionArgument NameDescription
uint8_t *N/Aissuer

cleanupAndStopWithDelay#

void cleanupAndStopWithDelay (EmberAfKeyEstablishmentNotifyMessage message, uint8_t delayInSec)
Parameters
TypeDirectionArgument NameDescription
EmberAfKeyEstablishmentNotifyMessageN/Amessage
uint8_tN/AdelayInSec

sendCertificate#

EmberAfKeyEstablishmentNotifyMessage sendCertificate (void )
Parameters
TypeDirectionArgument NameDescription
voidN/A

sendNextKeyEstablishMessage#

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

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

Typedef Documentation#

KeyEstablishMessage#

typedef uint8_t KeyEstablishMessage

Variable Documentation#

emAfKeyEstablishMessageToDataSize#

const uint8_t emAfKeyEstablishMessageToDataSize[]

emAfAvailableCbkeSuite#

EmberAfCbkeKeyEstablishmentSuite emAfAvailableCbkeSuite

emAfCurrentCbkeSuite#

EmberAfCbkeKeyEstablishmentSuite emAfCurrentCbkeSuite