Use these functions if your system does not use an ATCADevice as a host but implements the host in firmware. The functions provide host-side cryptographic functionality for an ATECC client device. They are intended to accompany the CryptoAuthLib functions. They can be called directly from an application, or integrated into an API.
More...
|
ATCA_STATUS | atcah_nonce (struct atca_nonce_in_out *param) |
| This function calculates host side nonce with the parameters passed. More...
|
|
ATCA_STATUS | atcah_mac (struct atca_mac_in_out *param) |
| This function generates an SHA-256 digest (MAC) of a key, challenge, and other information. More...
|
|
ATCA_STATUS | atcah_check_mac (struct atca_check_mac_in_out *param) |
| This function performs the checkmac operation to generate client response on the host side . More...
|
|
ATCA_STATUS | atcah_hmac (struct atca_hmac_in_out *param) |
| This function generates an HMAC / SHA-256 hash of a key and other information. More...
|
|
ATCA_STATUS | atcah_gen_dig (struct atca_gen_dig_in_out *param) |
| This function combines the current TempKey with a stored value. More...
|
|
ATCA_STATUS | atcah_gen_mac (struct atca_gen_dig_in_out *param) |
| This function generates mac with session key with a plain text. More...
|
|
ATCA_STATUS | atcah_write_auth_mac (struct atca_write_mac_in_out *param) |
| This function calculates the input MAC for the Write command. More...
|
|
ATCA_STATUS | atcah_privwrite_auth_mac (struct atca_write_mac_in_out *param) |
| This function calculates the input MAC for the PrivWrite command. More...
|
|
ATCA_STATUS | atcah_derive_key (struct atca_derive_key_in_out *param) |
| This function derives a key with a key and TempKey. More...
|
|
ATCA_STATUS | atcah_derive_key_mac (struct atca_derive_key_mac_in_out *param) |
| This function calculates the input MAC for a DeriveKey command. More...
|
|
ATCA_STATUS | atcah_decrypt (struct atca_decrypt_in_out *param) |
| This function decrypts 32-byte encrypted data received with the Read command. More...
|
|
ATCA_STATUS | atcah_sha256 (int32_t len, const uint8_t *message, uint8_t *digest) |
| This function creates a SHA256 digest on a little-endian system. More...
|
|
uint8_t * | atcah_include_data (struct atca_include_data_in_out *param) |
| This function copies otp and sn data into a command buffer. More...
|
|
ATCA_STATUS | atcah_gen_key_msg (struct atca_gen_key_in_out *param) |
| Calculate the PubKey digest created by GenKey and saved to TempKey. More...
|
|
ATCA_STATUS | atcah_config_to_sign_internal (ATCADeviceType device_type, struct atca_sign_internal_in_out *param, const uint8_t *config) |
| Populate the slot_config, key_config, and is_slot_locked fields in the atca_sign_internal_in_out structure from the provided config zone. More...
|
|
ATCA_STATUS | atcah_sign_internal_msg (ATCADeviceType device_type, struct atca_sign_internal_in_out *param) |
| Builds the full message that would be signed by the Sign(Internal) command. More...
|
|
ATCA_STATUS | atcah_verify_mac (atca_verify_mac_in_out_t *param) |
| Calculate the expected MAC on the host side for the Verify command. More...
|
|
ATCA_STATUS | atcah_secureboot_enc (atca_secureboot_enc_in_out_t *param) |
| Encrypts the digest for the SecureBoot command when using the encrypted digest / validating mac option. More...
|
|
ATCA_STATUS | atcah_secureboot_mac (atca_secureboot_mac_in_out_t *param) |
| Calculates the expected MAC returned from the SecureBoot command when verification is a success. More...
|
|
ATCA_STATUS | atcah_encode_counter_match (uint32_t counter, uint8_t *counter_match) |
| Builds the counter match value that needs to be stored in a slot. More...
|
|
ATCA_STATUS | atcah_io_decrypt (struct atca_io_decrypt_in_out *param) |
| Decrypt data that's been encrypted by the IO protection key. The ECDH and KDF commands on the ATECC608A are the only ones that support this operation. More...
|
|
|
uint8_t * | p_temp |
| [out] pointer to output buffer More...
|
|
const uint8_t * | otp |
| [in] pointer to one-time-programming data More...
|
|
const uint8_t * | sn |
| [in] pointer to serial number data More...
|
|
uint8_t | mode |
| [in] Mode parameter used in Nonce command (Param1). More...
|
|
uint16_t | zero |
| [in] Zero parameter used in Nonce command (Param2). More...
|
|
const uint8_t * | num_in |
| [in] Pointer to 20-byte NumIn data used in Nonce command. More...
|
|
const uint8_t * | rand_out |
| [in] Pointer to 32-byte RandOut data from Nonce command. More...
|
|
struct atca_temp_key * | temp_key |
| [in,out] Pointer to TempKey structure. More...
|
|
uint8_t | mode |
| [in] Mode parameter used in MAC command (Param1). More...
|
|
uint16_t | key_id |
| [in] KeyID parameter used in MAC command (Param2). More...
|
|
const uint8_t * | challenge |
| [in] Pointer to 32-byte Challenge data used in MAC command, depending on mode. More...
|
|
const uint8_t * | key |
| [in] Pointer to 32-byte key used to generate MAC digest. More...
|
|
const uint8_t * | otp |
| [in] Pointer to 11-byte OTP, optionally included in MAC digest, depending on mode. More...
|
|
const uint8_t * | sn |
| [in] Pointer to 9-byte SN, optionally included in MAC digest, depending on mode. More...
|
|
uint8_t * | response |
| [out] Pointer to 32-byte SHA-256 digest (MAC). More...
|
|
struct atca_temp_key * | temp_key |
| [in,out] Pointer to TempKey structure. More...
|
|
uint8_t | mode |
| [in] Mode parameter used in HMAC command (Param1). More...
|
|
uint16_t | key_id |
| [in] KeyID parameter used in HMAC command (Param2). More...
|
|
const uint8_t * | key |
| [in] Pointer to 32-byte key used to generate HMAC digest. More...
|
|
const uint8_t * | otp |
| [in] Pointer to 11-byte OTP, optionally included in HMAC digest, depending on mode. More...
|
|
const uint8_t * | sn |
| [in] Pointer to 9-byte SN, optionally included in HMAC digest, depending on mode. More...
|
|
uint8_t * | response |
| [out] Pointer to 32-byte SHA-256 HMAC digest. More...
|
|
struct atca_temp_key * | temp_key |
| [in,out] Pointer to TempKey structure. More...
|
|
uint8_t * | crypto_data |
| [in,out] Pointer to 32-byte data. Input encrypted data from Read command (Contents field), output decrypted. More...
|
|
struct atca_temp_key * | temp_key |
| [in,out] Pointer to TempKey structure. More...
|
|
uint16_t | curve_type |
| [in] Curve type used in Verify command (Param2). More...
|
|
const uint8_t * | signature |
| [in] Pointer to ECDSA signature to be verified More...
|
|
const uint8_t * | public_key |
| [in] Pointer to the public key to be used for verification More...
|
|
struct atca_temp_key * | temp_key |
| [in,out] Pointer to TempKey structure. More...
|
|
Use these functions if your system does not use an ATCADevice as a host but implements the host in firmware. The functions provide host-side cryptographic functionality for an ATECC client device. They are intended to accompany the CryptoAuthLib functions. They can be called directly from an application, or integrated into an API.
Modern compilers can garbage-collect unused functions. If your compiler does not support this feature, you can just discard this module from your project if you do use an ATECC as a host. Or, if you don't, delete the functions you do not use.
◆ ATCA_COMMAND_HEADER_SIZE
#define ATCA_COMMAND_HEADER_SIZE ( 4) |
◆ ATCA_DERIVE_KEY_ZEROS_SIZE
#define ATCA_DERIVE_KEY_ZEROS_SIZE (25) |
◆ ATCA_GENDIG_ZEROS_SIZE
#define ATCA_GENDIG_ZEROS_SIZE (25) |
◆ ATCA_MSG_SIZE_DERIVE_KEY
#define ATCA_MSG_SIZE_DERIVE_KEY (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2} || 0{25} || TempKey{32}.
◆ ATCA_MSG_SIZE_DERIVE_KEY_MAC
#define ATCA_MSG_SIZE_DERIVE_KEY_MAC (39) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2}.
◆ ATCA_MSG_SIZE_ENCRYPT_MAC
#define ATCA_MSG_SIZE_ENCRYPT_MAC (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2}|| SN8{1} || SN0_1{2} || 0{25} || TempKey{32}.
◆ ATCA_MSG_SIZE_GEN_DIG
#define ATCA_MSG_SIZE_GEN_DIG (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2} || 0{25} || TempKey{32}.
◆ ATCA_MSG_SIZE_HMAC
#define ATCA_MSG_SIZE_HMAC (88) |
◆ ATCA_MSG_SIZE_MAC
#define ATCA_MSG_SIZE_MAC (88) |
(Key or TempKey){32} || (Challenge or TempKey){32} || OpCode{1} || Mode{1} || Param2{2} || (OTP0_7 or 0){8} || (OTP8_10 or 0){3} || SN8{1} || (SN4_7 or 0){4} || SN0_1{2} || (SN2_3 or 0){2}
◆ ATCA_MSG_SIZE_NONCE
#define ATCA_MSG_SIZE_NONCE (55) |
RandOut{32} || NumIn{20} || OpCode{1} || Mode{1} || LSB of Param2{1}.
◆ ATCA_MSG_SIZE_PRIVWRITE_MAC
#define ATCA_MSG_SIZE_PRIVWRITE_MAC (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2}|| SN8{1} || SN0_1{2} || 0{21} || PlainText{36}.
◆ ATCA_PRIVWRITE_MAC_ZEROS_SIZE
#define ATCA_PRIVWRITE_MAC_ZEROS_SIZE (21) |
◆ ATCA_PRIVWRITE_PLAIN_TEXT_SIZE
#define ATCA_PRIVWRITE_PLAIN_TEXT_SIZE (36) |
◆ ATCA_SN_0_DEF
#define ATCA_SN_0_DEF (0x01) |
◆ ATCA_SN_1_DEF
#define ATCA_SN_1_DEF (0x23) |
◆ ATCA_SN_8_DEF
#define ATCA_SN_8_DEF (0xEE) |
◆ ATCA_WRITE_MAC_ZEROS_SIZE
#define ATCA_WRITE_MAC_ZEROS_SIZE (25) |
◆ ENCRYPTION_KEY_SIZE
#define ENCRYPTION_KEY_SIZE (64) |
◆ HMAC_BLOCK_SIZE
#define HMAC_BLOCK_SIZE (64) |
◆ MAC_MODE_USE_TEMPKEY_MASK
#define MAC_MODE_USE_TEMPKEY_MASK ((uint8_t)0x03) |
mode mask for MAC command when using TempKey
◆ atca_check_mac_in_out_t
◆ atca_gen_dig_in_out_t
◆ atca_gen_key_in_out_t
Input/output parameters for calculating the PubKey digest put into TempKey by the GenKey command with the atcah_gen_key_msg() function.
◆ atca_io_decrypt_in_out_t
◆ atca_mac_in_out_t
◆ atca_nonce_in_out_t
◆ atca_secureboot_enc_in_out_t
◆ atca_secureboot_mac_in_out_t
◆ atca_sign_internal_in_out_t
Input/output parameters for calculating the message and digest used by the Sign(internal) command. Used with the atcah_sign_internal_msg() function.
◆ atca_temp_key_t
Structure to hold TempKey fields.
◆ atca_verify_in_out_t
◆ atca_verify_mac_in_out_t
◆ atca_write_mac_in_out_t
◆ atcah_check_mac()
This function performs the checkmac operation to generate client response on the host side .
- Parameters
-
[in,out] | param | Input and output parameters |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_config_to_sign_internal()
Populate the slot_config, key_config, and is_slot_locked fields in the atca_sign_internal_in_out structure from the provided config zone.
The atca_sign_internal_in_out structure has a number of fields (slot_config, key_config, is_slot_locked) that can be determined automatically from the current state of TempKey and the full config zone.
- Parameters
-
[in,out] | param | Sign(Internal) parameters to be filled out. Only slot_config, key_config, and is_slot_locked will be set. |
[in] | device_type | The type of the device. |
[in] | config | Full 128 byte config zone for the device. |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_decrypt()
This function decrypts 32-byte encrypted data received with the Read command.
To use this function, first the nonce must be valid and synchronized between device and application. The application sends a GenDig command to the Device, using a key specified by SlotConfig.ReadKey. The device updates its TempKey. The application then updates its own TempKey using the GenDig calculation function, using the same key. The application sends a Read command to the device for a user zone configured with EncryptRead. The device encrypts 32-byte zone content, and outputs it to the host. The application passes these encrypted data to this decryption function. The function decrypts the data and returns them. TempKey must be updated by GenDig using a ParentKey as specified by SlotConfig.ReadKey before executing this function. The decryption function does not check whether the TempKey has been generated by a correct ParentKey for the corresponding zone. Therefore to get a correct result, the application has to make sure that prior GenDig calculation was done using correct ParentKey.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_derive_key()
This function derives a key with a key and TempKey.
Used in conjunction with DeriveKey command, the key derived by this function will match the key in the device. Two kinds of operation are supported:
-
Roll Key operation: target_key and parent_key parameters should be set to point to the same location (TargetKey).
-
Create Key operation: target_key should be set to point to TargetKey, parent_key should be set to point to ParentKey.
After executing this function, the initial value of target_key will be overwritten with the derived key. The TempKey should be valid (temp_key.valid = 1) before executing this function.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_derive_key_mac()
This function calculates the input MAC for a DeriveKey command.
The DeriveKey command will need an input MAC if SlotConfig[TargetKey].Bit15 is set.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_encode_counter_match()
ATCA_STATUS atcah_encode_counter_match |
( |
uint32_t |
counter_value, |
|
|
uint8_t * |
counter_match_value |
|
) |
| |
Builds the counter match value that needs to be stored in a slot.
- Parameters
-
[in] | counter_value | Counter value to be used for the counter match. This must be a multiple of 32. |
[out] | counter_match_value | Data to be stored in the beginning of a counter match slot will be returned here (8 bytes). |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_gen_dig()
This function combines the current TempKey with a stored value.
The stored value can be a data slot, OTP page, configuration zone, or hardware transport key. The TempKey generated by this function will match with the TempKey in the device generated when executing a GenDig command. The TempKey should be valid (temp_key.valid = 1) before executing this function. To use this function, an application first sends a GenDig command with a chosen stored value to the device. This stored value must be known by the application and is passed to this GenDig calculation function. The function calculates a new TempKey and returns it.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_gen_key_msg()
Calculate the PubKey digest created by GenKey and saved to TempKey.
- Parameters
-
[in,out] | param | GenKey parameters required to calculate the PubKey digest. Digest is return in the temp_key parameter. |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_gen_mac()
This function generates mac with session key with a plain text.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_hmac()
This function generates an HMAC / SHA-256 hash of a key and other information.
The resulting hash will match with the one generated in the device by an HMAC command. The TempKey has to be valid (temp_key.valid = 1) before executing this function.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_include_data()
This function copies otp and sn data into a command buffer.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- pointer to command buffer byte that was copied last
◆ atcah_io_decrypt()
Decrypt data that's been encrypted by the IO protection key. The ECDH and KDF commands on the ATECC608A are the only ones that support this operation.
- Parameters
-
[in,out] | param | Parameters required to perform the operation. |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_mac()
This function generates an SHA-256 digest (MAC) of a key, challenge, and other information.
The resulting digest will match with the one generated by the device when executing a MAC command. The TempKey (if used) should be valid (temp_key.valid = 1) before executing this function.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_nonce()
This function calculates host side nonce with the parameters passed.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_privwrite_auth_mac()
This function calculates the input MAC for the PrivWrite command.
The PrivWrite command will need an input MAC if SlotConfig.WriteConfig.Encrypt is set.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_secureboot_enc()
Encrypts the digest for the SecureBoot command when using the encrypted digest / validating mac option.
- Parameters
-
[in,out] | param | Data required to perform the operation. |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_secureboot_mac()
Calculates the expected MAC returned from the SecureBoot command when verification is a success.
The result of this function (param->mac) should be compared with the actual MAC returned to validate the response.
- Parameters
-
[in,out] | param | Data required to perform the operation. |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_sha256()
ATCA_STATUS atcah_sha256 |
( |
int32_t |
len, |
|
|
const uint8_t * |
message, |
|
|
uint8_t * |
digest |
|
) |
| |
This function creates a SHA256 digest on a little-endian system.
- Parameters
-
[in] | len | byte length of message |
[in] | message | pointer to message |
[out] | digest | SHA256 of message |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_sign_internal_msg()
Builds the full message that would be signed by the Sign(Internal) command.
Additionally, the function will optionally output the OtherData data required by the Verify(In/Validate) command as well as the SHA256 digest of the full message.
- Parameters
-
[out] | device_type | Device type to perform the calculation for. |
[out] | param | Input data and output buffers required. |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_verify_mac()
Calculate the expected MAC on the host side for the Verify command.
- Parameters
-
[in,out] | param | Data required to perform the operation. |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ atcah_write_auth_mac()
This function calculates the input MAC for the Write command.
The Write command will need an input MAC if SlotConfig.WriteConfig.Encrypt is set.
- Parameters
-
[in,out] | param | pointer to parameter structure |
- Returns
- ATCA_SUCCESS on success, otherwise an error code.
◆ challenge
[in] Pointer to 32-byte Challenge data used in MAC command, depending on mode.
◆ crypto_data
[in,out] Pointer to 32-byte data. Input encrypted data from Read command (Contents field), output decrypted.
◆ curve_type
[in] Curve type used in Verify command (Param2).
◆ key [1/2]
[in] Pointer to 32-byte key used to generate MAC digest.
◆ key [2/2]
[in] Pointer to 32-byte key used to generate HMAC digest.
◆ key_id [1/2]
[in] KeyID parameter used in MAC command (Param2).
◆ key_id [2/2]
[in] KeyID parameter used in HMAC command (Param2).
◆ mode [1/3]
[in] Mode parameter used in Nonce command (Param1).
◆ mode [2/3]
[in] Mode parameter used in MAC command (Param1).
◆ mode [3/3]
[in] Mode parameter used in HMAC command (Param1).
◆ num_in
[in] Pointer to 20-byte NumIn data used in Nonce command.
◆ otp [1/3]
[in] pointer to one-time-programming data
◆ otp [2/3]
[in] Pointer to 11-byte OTP, optionally included in MAC digest, depending on mode.
◆ otp [3/3]
[in] Pointer to 11-byte OTP, optionally included in HMAC digest, depending on mode.
◆ p_temp
[out] pointer to output buffer
◆ public_key
[in] Pointer to the public key to be used for verification
◆ rand_out
[in] Pointer to 32-byte RandOut data from Nonce command.
◆ response [1/2]
[out] Pointer to 32-byte SHA-256 digest (MAC).
◆ response [2/2]
[out] Pointer to 32-byte SHA-256 HMAC digest.
◆ signature
[in] Pointer to ECDSA signature to be verified
◆ sn [1/3]
[in] pointer to serial number data
◆ sn [2/3]
[in] Pointer to 9-byte SN, optionally included in MAC digest, depending on mode.
◆ sn [3/3]
[in] Pointer to 9-byte SN, optionally included in HMAC digest, depending on mode.
◆ temp_key [1/5]
[in,out] Pointer to TempKey structure.
◆ temp_key [2/5]
[in,out] Pointer to TempKey structure.
◆ temp_key [3/5]
[in,out] Pointer to TempKey structure.
◆ temp_key [4/5]
[in,out] Pointer to TempKey structure.
◆ temp_key [5/5]
[in,out] Pointer to TempKey structure.
◆ zero
[in] Zero parameter used in Nonce command (Param2).