CryptoAuthLib
Atmel CryptoAuthentication Library
|
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...
Data Structures | |
struct | atca_temp_key |
Structure to hold TempKey fields. More... | |
struct | atca_include_data_in_out |
Input / output parameters for function atca_include_data(). More... | |
struct | atca_nonce_in_out |
Input/output parameters for function atca_nonce(). More... | |
struct | atca_mac_in_out |
Input/output parameters for function atca_mac(). More... | |
struct | atca_hmac_in_out |
Input/output parameters for function atca_hmac(). More... | |
struct | atca_gen_dig_in_out |
Input/output parameters for function atca_gen_dig(). More... | |
struct | atca_write_mac_in_out |
Input/output parameters for function atca_auth_mac(). More... | |
struct | atca_derive_key_in_out |
Input/output parameters for function atca_derive_key(). More... | |
struct | atca_derive_key_mac_in_out |
Input/output parameters for function atca_derive_key_mac(). More... | |
struct | atca_encrypt_in_out |
Input/output parameters for function atca_encrypt(). More... | |
struct | atca_decrypt_in_out |
Input/output parameters for function atca_decrypt(). More... | |
struct | atca_check_mac_in_out |
Input/output parameters for function atca_check_mac(). More... | |
struct | atca_verify_in_out |
Input/output parameters for function atca_verify(). More... | |
Macros | |
#define | ATAC_STANDARD_KEY_SIZE 32 |
Typedefs | |
typedef struct atca_temp_key | atca_temp_key_t |
typedef struct atca_nonce_in_out | atca_nonce_in_out_t |
typedef struct atca_gen_dig_in_out | atca_gen_dig_in_out_t |
typedef struct atca_write_mac_in_out | atca_write_mac_in_out_t |
Functions | |
ATCA_STATUS | atcah_nonce (struct atca_nonce_in_out *param) |
This function calculates a 32-byte nonce based on a 20-byte input value (param->num_in) and 32-byte random number (param->rand_out). 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 calculates a SHA-256 digest (MAC) of a password and other information, to be verified using the CheckMac device command. 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 combines the 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 PrivWrite 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 combines a key with the 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_encrypt (struct atca_encrypt_in_out *param) |
This function encrypts 32-byte plain text data to be written using Write opcode, and optionally calculates input MAC. 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... | |
Variables | |
uint8_t | value [ATAC_STANDARD_KEY_SIZE] |
The value of TempKey. Nonce (from nonce command) or Digest (from GenDig command) More... | |
unsigned int | key_id: 4 |
If TempKey was generated by GenDig (see the GenData and CheckFlag bits), these bits indicate which key was used in its computation. More... | |
unsigned int | source_flag: 1 |
The source of the randomness in TempKey: 0=Rand, 1=Input. More... | |
unsigned int | gen_data: 1 |
Indicates if TempKey has been generated by GenDig using Data zone. More... | |
unsigned int | check_flag: 1 |
Not used in the library. More... | |
unsigned int | valid: 1 |
Indicates if the information in TempKey is valid. 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... | |
const uint8_t * | num_in |
[in] Pointer to 20-byte NumIn data used in Nonce command. More... | |
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 | zone |
[in] Zone parameter used in GenDig command (Param1). More... | |
uint16_t | key_id |
[in] KeyID parameter used in GenDig command (Param2). More... | |
const uint8_t * | stored_value |
[in] Pointer to 32-byte stored value, can be a data slot, OTP page, configuration zone, or hardware transport key. More... | |
struct atca_temp_key * | temp_key |
[in,out] Pointer to TempKey structure. More... | |
uint8_t | zone |
[in] Zone parameter used in PrivWrite command (Param1). More... | |
uint16_t | key_id |
[in] KeyID parameter used in PrivWrite command (Param2). More... | |
const uint8_t * | encryption_key |
[in] Pointer to 32-byte key. More... | |
const uint8_t * | input_data |
[in] Pointer to 36-byte data value, Input cleartext data. More... | |
uint8_t * | encrypted_data |
[out] Pointer to 32-byte data. Output encrypted data to MAC command. More... | |
uint8_t * | auth_mac |
[out] Pointer to 32-byte Mac. More... | |
struct atca_temp_key * | temp_key |
[in,out] Pointer to TempKey structure. More... | |
uint8_t | random |
[in] Random parameter used in DeriveKey command (Param1). More... | |
uint16_t | target_key_id |
[in] KeyID to be derived, TargetKey parameter used in DeriveKey command (Param2). More... | |
const uint8_t * | parent_key |
[in] Pointer to 32-byte ParentKey. Set equal to target_key if Roll Key operation is intended. More... | |
uint8_t * | target_key |
[out] Pointer to 32-byte TargetKey. More... | |
struct atca_temp_key * | temp_key |
[in,out] Pointer to TempKey structure. More... | |
uint8_t | random |
[in] Random parameter used in DeriveKey command (Param1). More... | |
uint16_t | target_key_id |
[in] KeyID to be derived, TargetKey parameter used in DeriveKey command (Param2). More... | |
const uint8_t * | parent_key |
[in] Pointer to 32-byte ParentKey. ParentKey here is always SlotConfig[TargetKey].WriteKey, regardless whether the operation is Roll or Create. More... | |
uint8_t * | mac |
[out] Pointer to 32-byte Mac. More... | |
uint8_t | zone |
[in] Zone parameter used in Write (Param1). More... | |
uint16_t | address |
[in] Address parameter used in Write command (Param2). More... | |
uint8_t * | crypto_data |
[in,out] Pointer to 32-byte data. Input cleartext data, output encrypted data to Write command (Value field). More... | |
uint8_t * | mac |
[out] Pointer to 32-byte Mac. Can be set to NULL if input MAC is not required by the Write command (write to OTP, unlocked user zone). 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... | |
uint8_t | mode |
[in] Mode parameter used in CheckMac command (Param1). More... | |
const uint8_t * | password |
[in] Pointer to 32-byte password that will be verified against Key[KeyID] in the Device. More... | |
const uint8_t * | other_data |
[in] Pointer to 13-byte OtherData that will be used in CheckMac command. More... | |
const uint8_t * | otp |
[in] Pointer to 11-byte OTP. OTP[0:7] is included in the calculation if Mode bit 5 is one. More... | |
const uint8_t * | target_key |
[in] Pointer to 32-byte TargetKey that will be copied to TempKey. More... | |
uint8_t * | client_resp |
[out] Pointer to 32-byte ClientResp to be used in CheckMac command. 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... | |
Definitions for ATECC Message Sizes to Calculate a SHA256 Hash | |
"||" is the concatenation operator. The number in braces is the length of the hash input value in bytes. | |
#define | ATCA_MSG_SIZE_NONCE (55) |
RandOut{32} || NumIn{20} || OpCode{1} || Mode{1} || LSB of Param2{1}. More... | |
#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} More... | |
#define | ATCA_MSG_SIZE_HMAC_INNER (152) |
HMAC = sha(HMAC outer || HMAC inner) HMAC inner = sha((zero-padded key ^ ipad) || message) = sha256( (Key{32} || 0x36{32}) || 0{32} || Key{32} || OpCode{1} || Mode{1} || KeyId{2} || OTP0_7{8} || OTP8_10{3} || SN8{1} || SN4_7{4} || SN0_1{2} || SN2_3{2} ){32}. More... | |
#define | ATCA_MSG_SIZE_HMAC (96) |
HMAC = sha(HMAC outer || HMAC inner) = sha256((Key{32} || 0x5C{32}) || HMAC inner{32}) More... | |
#define | ATCA_MSG_SIZE_GEN_DIG (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2} || 0{25} || TempKey{32}. More... | |
#define | ATCA_MSG_SIZE_DERIVE_KEY (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2} || 0{25} || TempKey{32}. More... | |
#define | ATCA_MSG_SIZE_DERIVE_KEY_MAC (39) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2}. More... | |
#define | ATCA_MSG_SIZE_ENCRYPT_MAC (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2}|| SN8{1} || SN0_1{2} || 0{25} || TempKey{32}. More... | |
#define | ATCA_MSG_SIZE_PRIVWRITE_MAC (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2}|| SN8{1} || SN0_1{2} || 0{21} || PlainText{36}. More... | |
#define | ATCA_COMMAND_HEADER_SIZE ( 4) |
#define | ATCA_GENDIG_ZEROS_SIZE (25) |
#define | ATCA_PRIVWRITE_MAC_ZEROS_SIZE (21) |
#define | ATCA_PLAIN_TEXT_SIZE (36) |
#define | ATCA_DERIVE_KEY_ZEROS_SIZE (25) |
#define | ATCA_OTP_SIZE_8 ( 8) |
#define | ATCA_OTP_SIZE_3 ( 3) |
#define | ATCA_SN_SIZE_4 ( 4) |
#define | ATCA_SN_SIZE_2 ( 2) |
#define | ATCA_OTHER_DATA_SIZE_2 ( 2) |
#define | ATCA_OTHER_DATA_SIZE_3 ( 3) |
#define | ATCA_OTHER_DATA_SIZE_4 ( 4) |
#define | HMAC_BLOCK_SIZE (64) |
Fixed Byte Values of Serial Number (SN[0:1] and SN[8]) | |
#define | ATCA_SN_0 (0x01) |
#define | ATCA_SN_1 (0x23) |
#define | ATCA_SN_8 (0xEE) |
Definition for TempKey Mode | |
#define | MAC_MODE_USE_TEMPKEY_MASK ((uint8_t)0x03) |
mode mask for MAC command when using TempKey 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.
#define ATAC_STANDARD_KEY_SIZE 32 |
#define ATCA_COMMAND_HEADER_SIZE ( 4) |
#define ATCA_DERIVE_KEY_ZEROS_SIZE (25) |
#define ATCA_GENDIG_ZEROS_SIZE (25) |
#define ATCA_MSG_SIZE_DERIVE_KEY (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2} || 0{25} || TempKey{32}.
#define ATCA_MSG_SIZE_DERIVE_KEY_MAC (39) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2}.
#define ATCA_MSG_SIZE_ENCRYPT_MAC (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2}|| SN8{1} || SN0_1{2} || 0{25} || TempKey{32}.
#define ATCA_MSG_SIZE_GEN_DIG (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2} || 0{25} || TempKey{32}.
#define ATCA_MSG_SIZE_HMAC (96) |
HMAC = sha(HMAC outer || HMAC inner) = sha256((Key{32} || 0x5C{32}) || HMAC inner{32})
#define ATCA_MSG_SIZE_HMAC_INNER (152) |
HMAC = sha(HMAC outer || HMAC inner) HMAC inner = sha((zero-padded key ^ ipad) || message) = sha256( (Key{32} || 0x36{32}) || 0{32} || Key{32} || OpCode{1} || Mode{1} || KeyId{2} || OTP0_7{8} || OTP8_10{3} || SN8{1} || SN4_7{4} || SN0_1{2} || SN2_3{2} ){32}.
#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}
#define ATCA_MSG_SIZE_NONCE (55) |
RandOut{32} || NumIn{20} || OpCode{1} || Mode{1} || LSB of Param2{1}.
#define ATCA_MSG_SIZE_PRIVWRITE_MAC (96) |
KeyId{32} || OpCode{1} || Param1{1} || Param2{2}|| SN8{1} || SN0_1{2} || 0{21} || PlainText{36}.
#define ATCA_OTHER_DATA_SIZE_2 ( 2) |
#define ATCA_OTHER_DATA_SIZE_3 ( 3) |
#define ATCA_OTHER_DATA_SIZE_4 ( 4) |
#define ATCA_OTP_SIZE_3 ( 3) |
#define ATCA_OTP_SIZE_8 ( 8) |
#define ATCA_PLAIN_TEXT_SIZE (36) |
#define ATCA_PRIVWRITE_MAC_ZEROS_SIZE (21) |
#define ATCA_SN_0 (0x01) |
#define ATCA_SN_1 (0x23) |
#define ATCA_SN_8 (0xEE) |
#define ATCA_SN_SIZE_2 ( 2) |
#define ATCA_SN_SIZE_4 ( 4) |
#define HMAC_BLOCK_SIZE (64) |
#define MAC_MODE_USE_TEMPKEY_MASK ((uint8_t)0x03) |
mode mask for MAC command when using TempKey
typedef struct atca_gen_dig_in_out atca_gen_dig_in_out_t |
typedef struct atca_nonce_in_out atca_nonce_in_out_t |
typedef struct atca_temp_key atca_temp_key_t |
typedef struct atca_write_mac_in_out atca_write_mac_in_out_t |
ATCA_STATUS atcah_check_mac | ( | struct atca_check_mac_in_out * | param | ) |
This function calculates a SHA-256 digest (MAC) of a password and other information, to be verified using the CheckMac device command.
This password checking operation is described in Atmel ATSHA204 [DATASHEET]. Before performing password checking operation, TempKey should contain a randomly generated nonce. The TempKey in the device has to match the one in the application. A user enters the password to be verified by an application. The application passes this password to the CheckMac calculation function, along with 13 bytes of OtherData, a 32-byte target key, and optionally 11 bytes of OTP. The function calculates a 32-byte ClientResp, returns it to Application. The function also replaces the current TempKey value with the target key. The application passes the calculated ClientResp along with OtherData inside a CheckMac command to the device. The device validates ClientResp, and copies the target slot to its TempKey.
If the password is stored in an odd numbered slot, the target slot is the password slot itself, so the target_key parameter should point to the password being checked. If the password is stored in an even numbered slot, the target slot is the next odd numbered slot (KeyID + 1), so the target_key parameter should point to a key that is equal to the target slot in the device.
Note that the function does not check the result of the password checking operation. Regardless of whether the CheckMac command returns success or not, the TempKey variable of the application will hold the value of the target key. Therefore the application has to make sure that password checking operation succeeds before using the TempKey for subsequent operations.
[in,out] | param | pointer to parameter structure |
ATCA_STATUS atcah_decrypt | ( | struct atca_decrypt_in_out * | param | ) |
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.
[in,out] | param | pointer to parameter structure |
ATCA_STATUS atcah_derive_key | ( | struct atca_derive_key_in_out * | param | ) |
This function combines a key with the 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:
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.
[in,out] | param | pointer to parameter structure |
ATCA_STATUS atcah_derive_key_mac | ( | struct atca_derive_key_mac_in_out * | param | ) |
This function calculates the input MAC for a DeriveKey command.
The DeriveKey command will need an input MAC if SlotConfig[TargetKey].Bit15 is set.
[in,out] | param | pointer to parameter structure |
ATCA_STATUS atcah_encrypt | ( | struct atca_encrypt_in_out * | param | ) |
This function encrypts 32-byte plain text data to be written using Write opcode, and optionally calculates input MAC.
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 parent key. If the Data zone has been locked, this is specified by SlotConfig.WriteKey. The device updates its TempKey when executing the command. The application then updates its own TempKey using the GenDig calculation function, using the same key. The application passes the plain text data to the encryption function.
If input MAC is needed the application must pass a valid pointer to buffer in the "mac" command parameter. If input MAC is not needed the application can pass a NULL pointer in the "mac" command parameter. The function encrypts the data and optionally calculates the input MAC, and returns it to the application. Using these encrypted data and the input MAC, the application sends a Write command to the Device. The device validates the MAC, then decrypts and writes the data.
The encryption function does not check whether the TempKey has been generated by the correct ParentKey for the corresponding zone. Therefore, to get a correct result after the Data and OTP zones have been locked, the application has to make sure that prior GenDig calculation was done using the correct ParentKey.
[in,out] | param | pointer to parameter structure |
ATCA_STATUS atcah_gen_dig | ( | struct atca_gen_dig_in_out * | param | ) |
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.
[in,out] | param | pointer to parameter structure |
ATCA_STATUS atcah_gen_mac | ( | struct atca_gen_dig_in_out * | param | ) |
This function combines the session key with a plain text.
[in,out] | param | pointer to parameter structure |
ATCA_STATUS atcah_hmac | ( | struct atca_hmac_in_out * | param | ) |
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.
[in,out] | param | pointer to parameter structure |
uint8_t* atcah_include_data | ( | struct atca_include_data_in_out * | param | ) |
This function copies otp and sn data into a command buffer.
[in,out] | param | pointer to parameter structure |
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.
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.
[in,out] | param | pointer to parameter structure |
ATCA_STATUS atcah_nonce | ( | struct atca_nonce_in_out * | param | ) |
This function calculates a 32-byte nonce based on a 20-byte input value (param->num_in) and 32-byte random number (param->rand_out).
This nonce will match with the nonce generated in the device when executing a Nonce command. To use this function, an application first sends a Nonce command with a chosen param->num_in to the device. Nonce Mode parameter must be set to use random nonce (mode 0 or 1).
The device generates a nonce, stores it in its TempKey, and outputs the random number param->rand_out it used in the hash calculation to the host. The values of param->rand_out and param->num_in are passed to this nonce calculation function. The function calculates the nonce and returns it. This function can also be used to fill in the nonce directly to TempKey (pass-through mode). The flags will automatically be set according to the mode used.
[in,out] | param | pointer to parameter structure |
ATCA_STATUS atcah_privwrite_auth_mac | ( | struct atca_write_mac_in_out * | param | ) |
This function calculates the input MAC for the PrivWrite command.
The PrivWrite command will need an input MAC if SlotConfig.WriteConfig.Encrypt is set.
[in,out] | param | pointer to parameter structure |
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.
Limitations: This function was implemented with the ATSHA204 CryptoAuth device in mind. It will therefore only work for length values of len % 64 < 62.
[in] | len | byte length of message |
[in] | message | pointer to message |
[out] | digest | SHA256 of message |
ATCA_STATUS atcah_write_auth_mac | ( | struct atca_write_mac_in_out * | param | ) |
This function calculates the input MAC for the PrivWrite command.
The PrivWrite command will need an input MAC if SlotConfig.WriteConfig.Encrypt is set.
[in,out] | param | pointer to parameter structure |
address |
[in] Address parameter used in Write command (Param2).
auth_mac |
[out] Pointer to 32-byte Mac.
challenge |
[in] Pointer to 32-byte Challenge data used in MAC command, depending on mode.
check_flag |
Not used in the library.
client_resp |
[out] Pointer to 32-byte ClientResp to be used in CheckMac command.
crypto_data |
[in,out] Pointer to 32-byte data. Input cleartext data, output encrypted data to Write command (Value field).
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).
encrypted_data |
[out] Pointer to 32-byte data. Output encrypted data to MAC command.
encryption_key |
[in] Pointer to 32-byte key.
gen_data |
Indicates if TempKey has been generated by GenDig using Data zone.
input_data |
[in] Pointer to 36-byte data value, Input cleartext data.
key |
[in] Pointer to 32-byte key used to generate MAC digest.
key |
[in] Pointer to 32-byte key used to generate HMAC digest.
key_id |
If TempKey was generated by GenDig (see the GenData and CheckFlag bits), these bits indicate which key was used in its computation.
key_id |
[in] KeyID parameter used in MAC command (Param2).
key_id |
[in] KeyID parameter used in HMAC command (Param2).
key_id |
[in] KeyID parameter used in GenDig command (Param2).
key_id |
[in] KeyID parameter used in PrivWrite command (Param2).
mac |
[out] Pointer to 32-byte Mac.
mac |
[out] Pointer to 32-byte Mac. Can be set to NULL if input MAC is not required by the Write command (write to OTP, unlocked user zone).
mode |
[in] Mode parameter used in Nonce command (Param1).
mode |
[in] Mode parameter used in MAC command (Param1).
mode |
[in] Mode parameter used in HMAC command (Param1).
mode |
[in] Mode parameter used in CheckMac command (Param1).
num_in |
[in] Pointer to 20-byte NumIn data used in Nonce command.
other_data |
[in] Pointer to 13-byte OtherData that will be used in CheckMac command.
otp |
[in] pointer to one-time-programming data
otp |
[in] Pointer to 11-byte OTP, optionally included in MAC digest, depending on mode.
otp |
[in] Pointer to 11-byte OTP, optionally included in HMAC digest, depending on mode.
otp |
[in] Pointer to 11-byte OTP. OTP[0:7] is included in the calculation if Mode bit 5 is one.
p_temp |
[out] pointer to output buffer
parent_key |
[in] Pointer to 32-byte ParentKey. Set equal to target_key if Roll Key operation is intended.
parent_key |
[in] Pointer to 32-byte ParentKey. ParentKey here is always SlotConfig[TargetKey].WriteKey, regardless whether the operation is Roll or Create.
password |
[in] Pointer to 32-byte password that will be verified against Key[KeyID] in the Device.
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.
random |
[in] Random parameter used in DeriveKey command (Param1).
random |
[in] Random parameter used in DeriveKey command (Param1).
response |
[out] Pointer to 32-byte SHA-256 digest (MAC).
response |
[out] Pointer to 32-byte SHA-256 HMAC digest.
signature |
[in] Pointer to ECDSA signature to be verified
sn |
[in] pointer to serial number data
sn |
[in] Pointer to 9-byte SN, optionally included in MAC digest, depending on mode.
sn |
[in] Pointer to 9-byte SN, optionally included in HMAC digest, depending on mode.
source_flag |
The source of the randomness in TempKey: 0=Rand, 1=Input.
stored_value |
[in] Pointer to 32-byte stored value, can be a data slot, OTP page, configuration zone, or hardware transport key.
target_key |
[out] Pointer to 32-byte TargetKey.
target_key |
[in] Pointer to 32-byte TargetKey that will be copied to TempKey.
target_key_id |
[in] KeyID to be derived, TargetKey parameter used in DeriveKey command (Param2).
target_key_id |
[in] KeyID to be derived, TargetKey parameter used in DeriveKey command (Param2).
temp_key |
[in,out] Pointer to TempKey structure.
temp_key |
[in,out] Pointer to TempKey structure.
temp_key |
[in,out] Pointer to TempKey structure.
temp_key |
[in,out] Pointer to TempKey structure.
temp_key |
[in,out] Pointer to TempKey structure.
temp_key |
[in,out] Pointer to TempKey structure.
temp_key |
[in,out] Pointer to TempKey structure.
temp_key |
[in,out] Pointer to TempKey structure.
temp_key |
[in,out] Pointer to TempKey structure.
temp_key |
[in,out] Pointer to TempKey structure.
valid |
Indicates if the information in TempKey is valid.
value |
The value of TempKey. Nonce (from nonce command) or Digest (from GenDig command)
zone |
[in] Zone parameter used in GenDig command (Param1).
zone |
[in] Zone parameter used in PrivWrite command (Param1).
zone |
[in] Zone parameter used in Write (Param1).