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#
Retrieve the implicit certificate stored in the MFG tokens of the device.
Begin the process of generating an ephemeral public/private ECC key pair.
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.
Retrieves the implicit certificate stored in the MFG tokens of the device.
Begin the process of generating an ephemeral public/private ECC key pair.
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.
Function Documentation#
emberGetCertificate#
EmberStatus emberGetCertificate (EmberCertificateData * result)
Retrieve the implicit certificate stored in the MFG tokens of the device.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberCertificateData * | N/A | result | A pointer to an EmberCertificateData structure where the retrieved certificate will be stored. |
Returns
EMBER_SUCCESS if the certificate was successfully retrieved. EMBER_ERR_FATAL if the token contains uninitialized data.
emberGenerateCbkeKeys#
EmberStatus emberGenerateCbkeKeys (void )
Begin the process of generating an ephemeral public/private ECC key pair.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | 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
EMBER_OPERATION_IN_PROGRESS if the stack has queued up the operation for execution.
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).
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| bool | N/A | amInitiator | 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. |
| EmberCertificateData * | N/A | partnerCert | A pointer to an EmberCertificateData structure that contains the CBKE partner's implicit certificate. |
| EmberPublicKeyData * | N/A | partnerEphemeralPublicKey | 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
EMBER_OPERATION_IN_PROGRESS if the stack has queued up the operation for execution.
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| bool | N/A | storeLinkKey | 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.
emberDsaSign#
EmberStatus emberDsaSign (EmberMessageBuffer messageToSign)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberMessageBuffer | N/A | messageToSign |
emberGenerateCbkeKeysHandler#
void emberGenerateCbkeKeysHandler (EmberStatus status, EmberPublicKeyData * ephemeralPublicKey)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status | |
| EmberPublicKeyData * | N/A | ephemeralPublicKey |
emberCalculateSmacsHandler#
void emberCalculateSmacsHandler (EmberStatus status, EmberSmacData * initiatorSmac, EmberSmacData * responderSmac)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status | |
| EmberSmacData * | N/A | initiatorSmac | |
| EmberSmacData * | N/A | responderSmac |
emberDsaSignHandler#
void emberDsaSignHandler (EmberStatus status, EmberMessageBuffer signedMessage)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status | |
| EmberMessageBuffer | N/A | signedMessage |
emberSetPreinstalledCbkeData#
EmberStatus emberSetPreinstalledCbkeData (EmberPublicKeyData * caPublic, EmberCertificateData * myCert, EmberPrivateKeyData * myKey)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberPublicKeyData * | N/A | caPublic | |
| EmberCertificateData * | N/A | myCert | |
| EmberPrivateKeyData * | N/A | myKey |
emberGetStackCertificateEui64#
bool emberGetStackCertificateEui64 (EmberEUI64 certEui64)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberEUI64 | N/A | certEui64 |
emberDsaVerify#
EmberStatus emberDsaVerify (EmberMessageDigest * digest, EmberCertificateData * signerCertificate, EmberSignatureData * receivedSig)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberMessageDigest * | N/A | digest | |
| EmberCertificateData * | N/A | signerCertificate | |
| EmberSignatureData * | N/A | receivedSig |
emberDsaVerifyHandler#
void emberDsaVerifyHandler (EmberStatus status)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status |
emberGetCertificate283k1#
EmberStatus emberGetCertificate283k1 (EmberCertificate283k1Data * result)
Retrieves the implicit certificate stored in the MFG tokens of the device.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberCertificate283k1Data * | N/A | result | A pointer to an EmberCertificate283k1Data structure where the retrieved certificate will be stored. |
Returns
EMBER_SUCCESS if the certificate was successfully retrieved. EMBER_ERR_FATAL if the token contains uninitialized data.
emberGenerateCbkeKeys283k1#
EmberStatus emberGenerateCbkeKeys283k1 (void )
Begin the process of generating an ephemeral public/private ECC key pair.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | 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
EMBER_OPERATION_IN_PROGRESS if the stack has queued up the operation for execution.
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).
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| bool | N/A | amInitiator | 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. |
| EmberCertificate283k1Data * | N/A | partnerCert | A pointer to an EmberCertificate283k1Data structure that contains the CBKE partner's implicit certificate. |
| EmberPublicKey283k1Data * | N/A | partnerEphemeralPublicKey | 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
EMBER_OPERATION_IN_PROGRESS if the stack has queued up the operation for execution.
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| bool | N/A | storeLinkKey | 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.
emberGenerateCbkeKeysHandler283k1#
void emberGenerateCbkeKeysHandler283k1 (EmberStatus status, EmberPublicKey283k1Data * ephemeralPublicKey)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status | |
| EmberPublicKey283k1Data * | N/A | ephemeralPublicKey |
emberCalculateSmacsHandler283k1#
void emberCalculateSmacsHandler283k1 (EmberStatus status, EmberSmacData * initiatorSmac, EmberSmacData * responderSmac)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status | |
| EmberSmacData * | N/A | initiatorSmac | |
| EmberSmacData * | N/A | responderSmac |
emberSetPreinstalledCbkeData283k1#
EmberStatus emberSetPreinstalledCbkeData283k1 (EmberPublicKey283k1Data * caPublic, EmberCertificate283k1Data * myCert, EmberPrivateKey283k1Data * myKey)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberPublicKey283k1Data * | N/A | caPublic | |
| EmberCertificate283k1Data * | N/A | myCert | |
| EmberPrivateKey283k1Data * | N/A | myKey |
emberDsaVerify283k1#
EmberStatus emberDsaVerify283k1 (EmberMessageDigest * digest, EmberCertificate283k1Data * signerCertificate, EmberSignature283k1Data * receivedSig)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberMessageDigest * | N/A | digest | |
| EmberCertificate283k1Data * | N/A | signerCertificate | |
| EmberSignature283k1Data * | N/A | receivedSig |