Smart Energy Security#

This file describes functionality for Certificate Based Key Exchange (CBKE). This is used by Smart Energy devices to generate and store ephemeral ECC keys, derive the SMACs for the Key establishment protocol, and sign messages using their private key for the Demand Response Load Control client cluster.

See cbke-crypto-engine.h for source code.

Functions#

emberGetCertificate(EmberCertificateData *result)

Retrieve the implicit certificate stored in the MFG tokens of the device.

Begin the process of generating an ephemeral public/private ECC key pair.

emberCalculateSmacs(bool amInitiator, EmberCertificateData *partnerCert, EmberPublicKeyData *partnerEphemeralPublicKey)

Begin the process of generating the shared secret, the new link key, and the Secured Message Authentication Code (SMAC).

Call when all CBKE operations are done. Any temporary data created during calls to emberGenerateCbkeKeys() or emberCalculateSmacs() is wiped out. If the local device has validated that the partner device has generated the same SMACS as itself, it should set 'storeLinkKey' to true. Otherwise it should pass in false.

emberDsaSign(EmberMessageBuffer messageToSign)
void
emberGenerateCbkeKeysHandler(EmberStatus status, EmberPublicKeyData *ephemeralPublicKey)
void
emberCalculateSmacsHandler(EmberStatus status, EmberSmacData *initiatorSmac, EmberSmacData *responderSmac)
void
emberDsaSignHandler(EmberStatus status, EmberMessageBuffer signedMessage)
emberSetPreinstalledCbkeData(EmberPublicKeyData *caPublic, EmberCertificateData *myCert, EmberPrivateKeyData *myKey)
bool
emberGetStackCertificateEui64(EmberEUI64 certEui64)
emberDsaVerify(EmberMessageDigest *digest, EmberCertificateData *signerCertificate, EmberSignatureData *receivedSig)
void
emberDsaVerifyHandler(EmberStatus status)
emberGetCertificate283k1(EmberCertificate283k1Data *result)

Retrieves the implicit certificate stored in the MFG tokens of the device.

Begin the process of generating an ephemeral public/private ECC key pair.

emberCalculateSmacs283k1(bool amInitiator, EmberCertificate283k1Data *partnerCert, EmberPublicKey283k1Data *partnerEphemeralPublicKey)

Begin the process of generating the shared secret, the new link key, and the Secured Message Authentication Code (SMAC).

Call when all CBKE 283k1 operations are done. Any temporary data created during calls to emberGenerateCbkeKeys283k1() or emberCalculateSmacs283k1() is wiped out. If the local device has validated that the partner device has generated the same SMACS as itself, it should set 'storeLinkKey' to true. Otherwise it should pass in false.

void
emberGenerateCbkeKeysHandler283k1(EmberStatus status, EmberPublicKey283k1Data *ephemeralPublicKey)
void
emberCalculateSmacsHandler283k1(EmberStatus status, EmberSmacData *initiatorSmac, EmberSmacData *responderSmac)
emberSetPreinstalledCbkeData283k1(EmberPublicKey283k1Data *caPublic, EmberCertificate283k1Data *myCert, EmberPrivateKey283k1Data *myKey)
emberDsaVerify283k1(EmberMessageDigest *digest, EmberCertificate283k1Data *signerCertificate, EmberSignature283k1Data *receivedSig)

Function Documentation#

emberGetCertificate#

EmberStatus emberGetCertificate (EmberCertificateData * result)

Retrieve the implicit certificate stored in the MFG tokens of the device.

Parameters
N/Aresult

A pointer to an EmberCertificateData structure where the retrieved certificate will be stored.

Returns


Definition at line 43 of file stack/include/cbke-crypto-engine.h

emberGenerateCbkeKeys#

EmberStatus emberGenerateCbkeKeys (void )

Begin the process of generating an ephemeral public/private ECC key pair.

Parameters
N/A

If no other ECC operation is going on, it will immediately return with EMBER_OPERATION_IN_PROGRESS. It will delay a period of time to let APS retries take place, but then it will shutdown the radio and consume the CPU processing until the key generation is complete. This may take up to 1 second.

The generated results of the key generation is returned via emberGenerateCbkeKeysHandler().

Returns


Definition at line 60 of file stack/include/cbke-crypto-engine.h

emberCalculateSmacs#

EmberStatus emberCalculateSmacs (bool amInitiator, EmberCertificateData * partnerCert, EmberPublicKeyData * partnerEphemeralPublicKey)

Begin the process of generating the shared secret, the new link key, and the Secured Message Authentication Code (SMAC).

Parameters
N/AamInitiator

This bool indicates whether or not the device is the one that initiated the CBKE with the remote device, or whether it was the responder to the exchange.

N/ApartnerCert

A pointer to an EmberCertificateData structure that contains the CBKE partner's implicit certificate.

N/ApartnerEphemeralPublicKey

A pointer to an EmberPublicKeyData structure that contains the CBKE partner's ephemeral public key.

If no other ECC operation is going on, it will immediately return with EMBER_OPERATION_IN_PROGRESS. It will delay a period of time to let APS retries take place, but then it will shutdown the radio and consume the CPU processing until SMACs calculations are complete. This may take up to 3.5 seconds.

The calculated SMACS are returned via emberCalculateSmacsHandler().

Returns


Definition at line 84 of file stack/include/cbke-crypto-engine.h

emberClearTemporaryDataMaybeStoreLinkKey#

EmberStatus emberClearTemporaryDataMaybeStoreLinkKey (bool storeLinkKey)

Call when all CBKE operations are done. Any temporary data created during calls to emberGenerateCbkeKeys() or emberCalculateSmacs() is wiped out. If the local device has validated that the partner device has generated the same SMACS as itself, it should set 'storeLinkKey' to true. Otherwise it should pass in false.

Parameters
N/AstoreLinkKey

This tells the stack whether to store the newly generated link key, or discard it.

Returns

  • If storeLinkkey is false, this function returns EMBER_ERR_FATAL always. If storeLinkKey is true, then this function returns the results of whether or not the link key was stored. EMBER_SUCCESS is returned when key was stored successfully.


Definition at line 102 of file stack/include/cbke-crypto-engine.h

emberDsaSign#

EmberStatus emberDsaSign (EmberMessageBuffer messageToSign)
Parameters
N/AmessageToSign

Definition at line 142 of file stack/include/cbke-crypto-engine.h

emberGenerateCbkeKeysHandler#

void emberGenerateCbkeKeysHandler (EmberStatus status, EmberPublicKeyData * ephemeralPublicKey)
Parameters
N/Astatus
N/AephemeralPublicKey

Definition at line 156 of file stack/include/cbke-crypto-engine.h

emberCalculateSmacsHandler#

void emberCalculateSmacsHandler (EmberStatus status, EmberSmacData * initiatorSmac, EmberSmacData * responderSmac)
Parameters
N/Astatus
N/AinitiatorSmac
N/AresponderSmac

Definition at line 173 of file stack/include/cbke-crypto-engine.h

emberDsaSignHandler#

void emberDsaSignHandler (EmberStatus status, EmberMessageBuffer signedMessage)
Parameters
N/Astatus
N/AsignedMessage

Definition at line 194 of file stack/include/cbke-crypto-engine.h

emberSetPreinstalledCbkeData#

EmberStatus emberSetPreinstalledCbkeData (EmberPublicKeyData * caPublic, EmberCertificateData * myCert, EmberPrivateKeyData * myKey)
Parameters
N/AcaPublic
N/AmyCert
N/AmyKey

Definition at line 247 of file stack/include/cbke-crypto-engine.h

emberGetStackCertificateEui64#

bool emberGetStackCertificateEui64 (EmberEUI64 certEui64)
Parameters
N/AcertEui64

Definition at line 262 of file stack/include/cbke-crypto-engine.h

emberDsaVerify#

EmberStatus emberDsaVerify (EmberMessageDigest * digest, EmberCertificateData * signerCertificate, EmberSignatureData * receivedSig)
Parameters
N/Adigest
N/AsignerCertificate
N/AreceivedSig

Definition at line 270 of file stack/include/cbke-crypto-engine.h

emberDsaVerifyHandler#

void emberDsaVerifyHandler (EmberStatus status)
Parameters
N/Astatus

Definition at line 280 of file stack/include/cbke-crypto-engine.h

emberGetCertificate283k1#

EmberStatus emberGetCertificate283k1 (EmberCertificate283k1Data * result)

Retrieves the implicit certificate stored in the MFG tokens of the device.

Parameters
N/Aresult

A pointer to an EmberCertificate283k1Data structure where the retrieved certificate will be stored.

Returns


Definition at line 293 of file stack/include/cbke-crypto-engine.h

emberGenerateCbkeKeys283k1#

EmberStatus emberGenerateCbkeKeys283k1 (void )

Begin the process of generating an ephemeral public/private ECC key pair.

Parameters
N/A

If no other ECC operation is going on, it will immediately return with EMBER_OPERATION_IN_PROGRESS. It will delay a period of time to let APS retries take place, but then it will shutdown the radio and consume the CPU processing until the key generation is complete. This may take up to 1 second.

The generated results of the key generation is returned via emberGenerateCbkeKeysHandler283k1().

Returns


Definition at line 310 of file stack/include/cbke-crypto-engine.h

emberCalculateSmacs283k1#

EmberStatus emberCalculateSmacs283k1 (bool amInitiator, EmberCertificate283k1Data * partnerCert, EmberPublicKey283k1Data * partnerEphemeralPublicKey)

Begin the process of generating the shared secret, the new link key, and the Secured Message Authentication Code (SMAC).

Parameters
N/AamInitiator

This bool indicates whether or not the device is the one that initiated the CBKE with the remote device, or whether it was the responder to the exchange.

N/ApartnerCert

A pointer to an EmberCertificate283k1Data structure that contains the CBKE partner's implicit certificate.

N/ApartnerEphemeralPublicKey

A pointer to an EmberPublicKey283k1Data structure that contains the CBKE partner's ephemeral public key.

If no other ECC operation is going on, it will immediately return with EMBER_OPERATION_IN_PROGRESS. It will delay a period of time to let APS retries take place, but then it will shutdown the radio and consume the CPU processing until SMACs calculations are complete. This may take up to 3.5 seconds.

The calculated SMACS are returned via emberCalculateSmacsHandler().

Returns


Definition at line 334 of file stack/include/cbke-crypto-engine.h

emberClearTemporaryDataMaybeStoreLinkKey283k1#

EmberStatus emberClearTemporaryDataMaybeStoreLinkKey283k1 (bool storeLinkKey)

Call when all CBKE 283k1 operations are done. Any temporary data created during calls to emberGenerateCbkeKeys283k1() or emberCalculateSmacs283k1() is wiped out. If the local device has validated that the partner device has generated the same SMACS as itself, it should set 'storeLinkKey' to true. Otherwise it should pass in false.

Parameters
N/AstoreLinkKey

This tells the stack whether to store the newly generated link key, or discard it.

Returns

  • If storeLinkkey is false, this function returns EMBER_ERR_FATAL always. If storeLinkKey is true, then this function returns the results of whether or not the link key was stored. EMBER_SUCCESS is returned when key was stored successfully.


Definition at line 352 of file stack/include/cbke-crypto-engine.h

emberGenerateCbkeKeysHandler283k1#

void emberGenerateCbkeKeysHandler283k1 (EmberStatus status, EmberPublicKey283k1Data * ephemeralPublicKey)
Parameters
N/Astatus
N/AephemeralPublicKey

Definition at line 366 of file stack/include/cbke-crypto-engine.h

emberCalculateSmacsHandler283k1#

void emberCalculateSmacsHandler283k1 (EmberStatus status, EmberSmacData * initiatorSmac, EmberSmacData * responderSmac)
Parameters
N/Astatus
N/AinitiatorSmac
N/AresponderSmac

Definition at line 383 of file stack/include/cbke-crypto-engine.h

emberSetPreinstalledCbkeData283k1#

EmberStatus emberSetPreinstalledCbkeData283k1 (EmberPublicKey283k1Data * caPublic, EmberCertificate283k1Data * myCert, EmberPrivateKey283k1Data * myKey)
Parameters
N/AcaPublic
N/AmyCert
N/AmyKey

Definition at line 415 of file stack/include/cbke-crypto-engine.h

emberDsaVerify283k1#

EmberStatus emberDsaVerify283k1 (EmberMessageDigest * digest, EmberCertificate283k1Data * signerCertificate, EmberSignature283k1Data * receivedSig)
Parameters
N/Adigest
N/AsignerCertificate
N/AreceivedSig

Definition at line 425 of file stack/include/cbke-crypto-engine.h