Certificate-Based Key Exchange (CBKE) Frames#

Description: This call starts the generation of the ECC Ephemeral Public/Private key pair. When complete it stores the private key. The results are returned via sl_zigbee_ezsp_generate_cbke_keys_handler().

Command Parameters: None

Response Parameters:

sl_status_t status

Description: A callback by the Crypto Engine indicating that a new ephemeral public/private key pair has been generated. The public/private key pair is stored on the NCP, but only the associated public key is returned to the host. The node's associated certificate is also returned.

This frame is a response to the callback command.

Response Parameters:

sl_status_t status

The result of the CBKE operation.

sl_zigbee_public_key_data_t ephemeralPublicKey

The generated ephemeral public key.

Description: Calculates the SMAC verification keys for both the initiator and responder roles of CBKE using the passed parameters and the stored public/private key pair previously generated with ezspGenerateKeysRetrieveCert(). It also stores the unverified link key data in temporary storage on the NCP until the key establishment is complete.

Command Parameters:

bool amInitiator

The role of this device in the Key Establishment protocol.

sl_zigbee_certificate_data_t partnerCertificate

The key establishment partner's implicit certificate.

sl_zigbee_public_key_data_t partnerEphemeralPublicKey

The key establishment partner's ephemeral public key.

Response Parameters:

sl_status_t status

Description: A callback to indicate that the NCP has finished calculating the Secure Message Authentication Codes (SMAC) for both the initiator and responder. The associated link key is kept in temporary storage until the host tells the NCP to store or discard the key via sli_zigbee_stack_clear_temporary_data_maybe_store_link_key().

This frame is a response to the callback command.

Response Parameters:

sl_status_t status

The Result of the CBKE operation.

sl_zigbee_smac_data_t initiatorSmac

The calculated value of the initiator's SMAC

sl_zigbee_smac_data_t responderSmac

The calculated value of the responder's SMAC

Description: This call starts the generation of the ECC 283k1 curve Ephemeral Public/Private key pair. When complete it stores the private key. The results are returned via sl_zigbee_ezsp_generate_cbke_keys_283k1_handler().

Command Parameters: None

Response Parameters:

sl_status_t status

Description: A callback by the Crypto Engine indicating that a new 283k1 ephemeral public/private key pair has been generated. The public/private key pair is stored on the NCP, but only the associated public key is returned to the host. The node's associated certificate is also returned. This frame is a response to the callback command.

Response Parameters:

sl_status_t status

The result of the CBKE operation.

sl_zigbee_public_key_283k1_data_t ephemeralPublicKey

The generated ephemeral public key.

Description: Calculates the SMAC verification keys for both the initiator and responder roles of CBKE for the 283k1 ECC curve using the passed parameters and the stored public/private key pair previously generated with sl_zigbee_ezsp_generate_keys_retrieve_cert_283k1(). It also stores the unverified link key data in temporary storage on the NCP until the key establishment is complete.

Command Parameters:

bool amInitiator

The role of this device in the Key Establishment protocol.

sl_zigbee_certificate_283k1_data_t partnerCertificate

The key establishment partner's implicit certificate.

sl_zigbee_public_key_283k1_data_t partnerEphemeralPublicKey

The key establishment partner's ephemeral public key

Response Parameters:

sl_status_t status

Description: A callback to indicate that the NCP has finished calculating the Secure Message Authentication Codes (SMAC) for both the initiator and responder for the CBKE 283k1 Library. The associated link key is kept in temporary storage until the host tells the NCP to store or discard the key via sli_zigbee_stack_clear_temporary_data_maybe_store_link_key().

This frame is a response to the callback command.

Response Parameters:

sl_status_t status

The Result of the CBKE operation.

sl_zigbee_smac_data_t initiatorSmac

The calculated value of the initiator's SMAC

sl_zigbee_smac_data_t responderSmac

The calculated value of the responder's SMAC

Description: Clears the temporary data associated with CBKE and the key establishment, most notably the ephemeral public/private key pair. If storeLinKey is true it moves the unverified link key stored in temporary storage into the link key table. Otherwise it discards the key.

Command Parameters:

bool storeLinkKey

A bool indicating whether to store (true) or discard (false) the unverified link key derived when ezspCalculateSmacs() was previously called.

Response Parameters:

sl_status_t status

Description: Clears the temporary data associated with CBKE and the key establishment, most notably the ephemeral public/private key pair. If storeLinKey is true it moves the unverified link key stored in temporary storage into the link key table. Otherwise it discards the key.

Command Parameters:

bool storeLinkKey

A bool indicating whether to store (true) or discard (false) the unverified link key derived when ezspCalculateSmacs() was previously called.

Response Parameters:

sl_status_t status

Description: Retrieves the certificate installed on the NCP.

Command Parameters: None

Response Parameters:

sl_status_t status

sl_zigbee_certificate_data_t localCert

The locally installed certificate.

Description: Retrieves the 283k certificate installed on the NCP.

Command Parameters: None

Response Parameters:

sl_status_t status

sl_zigbee_certificate_283k1_data_t localCert

The locally installed certificate.

Description: LEGACY FUNCTION: This functionality has been replaced by a single bit in the sl_zigbee_aps_frame_t, SL_ZIGBEE_APS_OPTION_DSA_SIGN. Devices wishing to send signed messages should use that as it requires fewer function calls and message buffering. The dsaSignHandler response is still called when SL_ZIGBEE_APS_OPTION_DSA_SIGN is used. However, this function is still supported. This function begins the process of signing the passed message contained within the messageContents array. If no other ECC operation is going on, it will immediately return with SL_STATUS_IN_PROGRESS to indicate the start of ECC operation. It will delay a period of time to let APS retries take place, but then it will shut down the radio and consume the CPU processing until the signing is complete. This may take up to 1 second. The signed message will be returned in the dsaSignHandler response. Note that the last byte of the messageContents passed to this function has special significance. As the typical use case for DSA signing is to sign the ZCL payload of a DRLC Report Event Status message in SE 1.0, there is often both a signed portion (ZCL payload) and an unsigned portion (ZCL header). The last byte in the content of messageToSign is therefore used as a special indicator to signify how many bytes of leading data in the array should be excluded from consideration during the signing process. If the signature needs to cover the entire array (all bytes except last one), the caller should ensure that the last byte of messageContents is 0x00. When the signature operation is complete, this final byte will be replaced by the signature type indicator (0x01 for ECDSA signatures), and the actual signature will be appended to the original contents after this byte.

Command Parameters:

uint8_t messageLength

The length of the messageContents parameter in bytes.

uint8_t[] messageContents

The message contents for which to create a signature. Per above notes, this may include a leading portion of data not included in the signature, in which case the last byte of this array should be set to the index of the first byte to be considered for signing. Otherwise, the last byte of messageContents should be 0x00 to indicate that a signature should occur across the entire contents.

Response Parameters:

sl_status_t status

SL_STATUS_IN_PROGRESS if the stack has queued up the operation for execution. SL_STATUS_INVALID_STATE if the operation can't be performed in this context, possibly because another ECC operation is pending.

Description: The handler that returns the results of the signing operation. On success, the signature will be appended to the original message (including the signature type indicator that replaced the startIndex field for the signing) and both are returned via this callback.

This frame is a response to the callback command.

Response Parameters:

sl_status_t status

The result of the DSA signing operation.

uint8_t messageLength

The length of the messageContents parameter in bytes.

uint8_t[] messageContents

The message and attached which includes the original message and the appended signature.

Description: Verify that signature of the associated message digest was signed by the private key of the associated certificate.

Command Parameters:

sl_zigbee_message_digest_t digest

The AES-MMO message digest of the signed data. If dsaSign command was used to generate the signature for this data, the final byte (replaced by signature type of 0x01) in the messageContents array passed to dsaSign is included in the hash context used for the digest calculation.

sl_zigbee_certificate_data_t signerCertificate

The certificate of the signer. Note that the signer's certificate and the verifier's certificate must both be issued by the same Certificate Authority, so they should share the same CA Public Key.

sl_zigbee_signature_data_t receivedSig

The signature of the signed data.

Response Parameters:

sl_status_t status

Description: This callback is executed by the stack when the DSA verification has completed and has a result. If the result is SL_STATUS_OK, the signature is valid. If the result is SL_STATUS_ZIGBEE_SIGNATURE_VERIFY_FAILURE then the signature is invalid. If the result is anything else then the signature verify operation failed and the validity is unknown. This frame is a response to the callback command.

Response Parameters:

sl_status_t status

The result of the DSA verification operation.

Description: Verify that signature of the associated message digest was signed by the private key of the associated certificate.

Command Parameters:

sl_zigbee_message_digest_t digest

The AES-MMO message digest of the signed data. If dsaSign command was used to generate the signature for this data, the final byte (replaced by signature type of 0x01) in the messageContents array passed to dsaSign is included in the hash context used for the digest calculation.

sl_zigbee_certificate_283k1_data_t signerCertificate

The certificate of the signer. Note that the signer's certificate and the verifier's certificate must both be issued by the same Certificate Authority, so they should share the same CA Public Key.

sl_zigbee_signature_283k1_data_t received- Sig

The signature of the signed data.

Response Parameters:

sl_status_t status

Description: Sets the device's CA public key, local certificate, and static private key on the NCP associated with this node.

Command Parameters:

sl_zigbee_public_key_data_t caPublic

The Certificate Authority's public key.

sl_zigbee_certificate_data_t myCert

The node's new certificate signed by the CA.

sl_zigbee_private_key_data_t myKey

The node's new static private key.

Response Parameters:

sl_status_t status

Description: Sets the device's 283k1 curve CA public key, local certificate, and static private key on the NCP associated with this node.

Command Parameters: None

Response Parameters:

sl_status_t status