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#
Retrieves the implicit certificate stored in the MFG tokens of the device.
This function begins the process of generating an ephemeral public/private ECC key pair.
This function will begin the process of generating the shared secret, the new link key, and the Secured Message Authentication Code (SMAC).
This function should be called 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.
This function begins the process of generating an ephemeral public/private ECC key pair.
This function will begin the process of generating the shared secret, the new link key, and the Secured Message Authentication Code (SMAC).
This function should be called 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)
Retrieves 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.
43 of file stack/include/cbke-crypto-engine.hemberGenerateCbkeKeys#
EmberStatus emberGenerateCbkeKeys (void )
This function begins 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.
60 of file stack/include/cbke-crypto-engine.hemberCalculateSmacs#
EmberStatus emberCalculateSmacs (bool amInitiator, EmberCertificateData * partnerCert, EmberPublicKeyData * partnerEphemeralPublicKey)
This function will 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.
84 of file stack/include/cbke-crypto-engine.hemberClearTemporaryDataMaybeStoreLinkKey#
EmberStatus emberClearTemporaryDataMaybeStoreLinkKey (bool storeLinkKey)
This function should be called 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.
102 of file stack/include/cbke-crypto-engine.hemberDsaSign#
EmberStatus emberDsaSign (EmberMessageBuffer messageToSign)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberMessageBuffer | N/A | messageToSign |
142 of file stack/include/cbke-crypto-engine.hemberGenerateCbkeKeysHandler#
void emberGenerateCbkeKeysHandler (EmberStatus status, EmberPublicKeyData * ephemeralPublicKey)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status | |
| EmberPublicKeyData * | N/A | ephemeralPublicKey |
156 of file stack/include/cbke-crypto-engine.hemberCalculateSmacsHandler#
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 |
173 of file stack/include/cbke-crypto-engine.hemberDsaSignHandler#
void emberDsaSignHandler (EmberStatus status, EmberMessageBuffer signedMessage)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status | |
| EmberMessageBuffer | N/A | signedMessage |
194 of file stack/include/cbke-crypto-engine.hemberSetPreinstalledCbkeData#
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 |
247 of file stack/include/cbke-crypto-engine.hemberGetStackCertificateEui64#
bool emberGetStackCertificateEui64 (EmberEUI64 certEui64)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberEUI64 | N/A | certEui64 |
262 of file stack/include/cbke-crypto-engine.hemberDsaVerify#
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 |
270 of file stack/include/cbke-crypto-engine.hemberDsaVerifyHandler#
void emberDsaVerifyHandler (EmberStatus status)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status |
280 of file stack/include/cbke-crypto-engine.hemberGetCertificate283k1#
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.
293 of file stack/include/cbke-crypto-engine.hemberGenerateCbkeKeys283k1#
EmberStatus emberGenerateCbkeKeys283k1 (void )
This function begins 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.
310 of file stack/include/cbke-crypto-engine.hemberCalculateSmacs283k1#
EmberStatus emberCalculateSmacs283k1 (bool amInitiator, EmberCertificate283k1Data * partnerCert, EmberPublicKey283k1Data * partnerEphemeralPublicKey)
This function will 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.
334 of file stack/include/cbke-crypto-engine.hemberClearTemporaryDataMaybeStoreLinkKey283k1#
EmberStatus emberClearTemporaryDataMaybeStoreLinkKey283k1 (bool storeLinkKey)
This function should be called 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.
352 of file stack/include/cbke-crypto-engine.hemberGenerateCbkeKeysHandler283k1#
void emberGenerateCbkeKeysHandler283k1 (EmberStatus status, EmberPublicKey283k1Data * ephemeralPublicKey)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| EmberStatus | N/A | status | |
| EmberPublicKey283k1Data * | N/A | ephemeralPublicKey |
366 of file stack/include/cbke-crypto-engine.hemberCalculateSmacsHandler283k1#
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 |
383 of file stack/include/cbke-crypto-engine.hemberSetPreinstalledCbkeData283k1#
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 |
415 of file stack/include/cbke-crypto-engine.hemberDsaVerify283k1#
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 |
425 of file stack/include/cbke-crypto-engine.h