CryptoAuthLib v3.7.6
Microchip CryptoAuthentication Library
 
Loading...
Searching...
No Matches
Host side crypto methods (atcah_)

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_io_decrypt_in_out
 
struct  atca_verify_mac
 
struct  atca_secureboot_enc_in_out
 
struct  atca_secureboot_mac_in_out
 
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 atcah_gen_dig(). More...
 
struct  atca_diversified_key_in_out
 Input/output parameters for function atcah_gendivkey(). More...
 
struct  atca_write_mac_in_out
 Input/output parameters for function atcah_write_auth_mac() and atcah_privwrite_auth_mac(). More...
 
struct  atca_derive_key_in_out
 Input/output parameters for function atcah_derive_key(). More...
 
struct  atca_derive_key_mac_in_out
 Input/output parameters for function atcah_derive_key_mac(). 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 atcah_check_mac(). More...
 
struct  atca_resp_mac_in_out
 Input/Output parameters for calculating the output response mac in SHA105 device. Used with the atcah_gen_output_resp_mac() function. More...
 
struct  atca_verify_in_out
 Input/output parameters for function atcah_verify(). More...
 
struct  atca_gen_key_in_out
 Input/output parameters for calculating the PubKey digest put into TempKey by the GenKey command with the atcah_gen_key_msg() function. More...
 
struct  atca_sign_internal_in_out
 Input/output parameters for calculating the message and digest used by the Sign(internal) command. Used with the atcah_sign_internal_msg() function. More...
 
struct  atca_session_key_in_out
 Input/Output paramters for calculating the session key by the nonce command. Used with the atcah_gen_session_key() function. More...
 
struct  atca_delete_in_out
 Input/Output paramters for calculating the mac.Used with Delete command. More...
 

Typedefs

typedef struct atca_temp_key atca_temp_key_t
 Structure to hold TempKey fields.
 
typedef struct atca_nonce_in_out atca_nonce_in_out_t
 
typedef struct atca_io_decrypt_in_out atca_io_decrypt_in_out_t
 
typedef struct atca_verify_mac atca_verify_mac_in_out_t
 
typedef struct atca_secureboot_enc_in_out atca_secureboot_enc_in_out_t
 
typedef struct atca_secureboot_mac_in_out atca_secureboot_mac_in_out_t
 
typedef struct atca_mac_in_out atca_mac_in_out_t
 
typedef struct atca_gen_dig_in_out atca_gen_dig_in_out_t
 Input/output parameters for function atcah_gen_dig().
 
typedef struct atca_diversified_key_in_out atca_diversified_key_in_out_t
 Input/output parameters for function atcah_gendivkey().
 
typedef struct atca_write_mac_in_out atca_write_mac_in_out_t
 Input/output parameters for function atcah_write_auth_mac() and atcah_privwrite_auth_mac().
 
typedef struct atca_check_mac_in_out atca_check_mac_in_out_t
 Input/output parameters for function atcah_check_mac().
 
typedef struct atca_resp_mac_in_out atca_resp_mac_in_out_t
 Input/Output parameters for calculating the output response mac in SHA105 device. Used with the atcah_gen_output_resp_mac() function.
 
typedef struct atca_verify_in_out atca_verify_in_out_t
 
typedef struct atca_gen_key_in_out 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.
 
typedef struct atca_sign_internal_in_out 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.
 
typedef struct atca_session_key_in_out atca_session_key_in_out_t
 Input/Output paramters for calculating the session key by the nonce command. Used with the atcah_gen_session_key() function.
 
typedef struct atca_delete_in_out atca_delete_in_out_t
 Input/Output paramters for calculating the mac.Used with Delete command.
 

Functions

ATCA_STATUS atcah_nonce (struct atca_nonce_in_out *param)
 
ATCA_STATUS atcah_mac (struct atca_mac_in_out *param)
 
ATCA_STATUS atcah_check_mac (struct atca_check_mac_in_out *param)
 
ATCA_STATUS atcah_hmac (struct atca_hmac_in_out *param)
 
ATCA_STATUS atcah_gen_dig (struct atca_gen_dig_in_out *param)
 
ATCA_STATUS atcah_gendivkey (struct atca_diversified_key_in_out *param)
 
ATCA_STATUS atcah_gen_mac (struct atca_gen_dig_in_out *param)
 
ATCA_STATUS atcah_write_auth_mac (struct atca_write_mac_in_out *param)
 
ATCA_STATUS atcah_privwrite_auth_mac (struct atca_write_mac_in_out *param)
 
ATCA_STATUS atcah_derive_key (struct atca_derive_key_in_out *param)
 
ATCA_STATUS atcah_derive_key_mac (struct atca_derive_key_mac_in_out *param)
 
ATCA_STATUS atcah_decrypt (struct atca_decrypt_in_out *param)
 
ATCA_STATUS atcah_sha256 (uint32_t len, const uint8_t *message, uint8_t *digest)
 
uint8_t * atcah_include_data (struct atca_include_data_in_out *param)
 
ATCA_STATUS atcah_gen_key_msg (struct atca_gen_key_in_out *param)
 
ATCA_STATUS atcah_config_to_sign_internal (ATCADeviceType device_type, struct atca_sign_internal_in_out *param, const uint8_t *config)
 
ATCA_STATUS atcah_sign_internal_msg (ATCADeviceType device_type, struct atca_sign_internal_in_out *param)
 
ATCA_STATUS atcah_verify_mac (atca_verify_mac_in_out_t *param)
 
ATCA_STATUS atcah_secureboot_enc (atca_secureboot_enc_in_out_t *param)
 
ATCA_STATUS atcah_secureboot_mac (atca_secureboot_mac_in_out_t *param)
 
ATCA_STATUS atcah_encode_counter_match (uint32_t counter_value, uint8_t *counter_match_value)
 
ATCA_STATUS atcah_io_decrypt (struct atca_io_decrypt_in_out *param)
 
ATCA_STATUS atcah_ecc204_write_auth_mac (struct atca_write_mac_in_out *param)
 
ATCA_STATUS atcah_gen_session_key (atca_session_key_in_out_t *param)
 
ATCA_STATUS atcah_gen_output_resp_mac (struct atca_resp_mac_in_out *param)
 

Variables

uint8_t * atca_include_data_in_out::p_temp
 [out] pointer to output buffer
 
const uint8_t * atca_include_data_in_out::otp
 [in] pointer to one-time-programming data
 
const uint8_t * atca_include_data_in_out::sn
 [in] pointer to serial number data
 
uint8_t atca_nonce_in_out::mode
 [in] Mode parameter used in Nonce command (Param1).
 
uint16_t atca_nonce_in_out::zero
 [in] Zero parameter used in Nonce command (Param2).
 
const uint8_t * atca_nonce_in_out::num_in
 [in] Pointer to 20-byte NumIn data used in Nonce command.
 
const uint8_t * atca_nonce_in_out::rand_out
 [in] Pointer to 32-byte RandOut data from Nonce command.
 
struct atca_temp_keyatca_nonce_in_out::temp_key
 [in,out] Pointer to TempKey structure.
 
uint8_t atca_mac_in_out::mode
 [in] Mode parameter used in MAC command (Param1).
 
uint16_t atca_mac_in_out::key_id
 [in] KeyID parameter used in MAC command (Param2).
 
const uint8_t * atca_mac_in_out::challenge
 [in] Pointer to 32-byte Challenge data used in MAC command, depending on mode.
 
const uint8_t * atca_mac_in_out::key
 [in] Pointer to 32-byte key used to generate MAC digest.
 
const uint8_t * atca_mac_in_out::otp
 [in] Pointer to 11-byte OTP, optionally included in MAC digest, depending on mode.
 
const uint8_t * atca_mac_in_out::sn
 [in] Pointer to 9-byte SN, optionally included in MAC digest, depending on mode.
 
uint8_t * atca_mac_in_out::response
 [out] Pointer to 32-byte SHA-256 digest (MAC).
 
struct atca_temp_keyatca_mac_in_out::temp_key
 [in,out] Pointer to TempKey structure.
 
uint8_t atca_hmac_in_out::mode
 [in] Mode parameter used in HMAC command (Param1).
 
uint16_t atca_hmac_in_out::key_id
 [in] KeyID parameter used in HMAC command (Param2).
 
const uint8_t * atca_hmac_in_out::key
 [in] Pointer to 32-byte key used to generate HMAC digest.
 
const uint8_t * atca_hmac_in_out::otp
 [in] Pointer to 11-byte OTP, optionally included in HMAC digest, depending on mode.
 
const uint8_t * atca_hmac_in_out::sn
 [in] Pointer to 9-byte SN, optionally included in HMAC digest, depending on mode.
 
uint8_t * atca_hmac_in_out::response
 [out] Pointer to 32-byte SHA-256 HMAC digest.
 
struct atca_temp_keyatca_hmac_in_out::temp_key
 [in,out] Pointer to TempKey structure.
 
uint8_t * atca_decrypt_in_out::crypto_data
 [in,out] Pointer to 32-byte data. Input encrypted data from Read command (Contents field), output decrypted.
 
struct atca_temp_keyatca_decrypt_in_out::temp_key
 [in,out] Pointer to TempKey structure.
 
uint16_t atca_verify_in_out::curve_type
 [in] Curve type used in Verify command (Param2).
 
const uint8_t * atca_verify_in_out::signature
 [in] Pointer to ECDSA signature to be verified
 
const uint8_t * atca_verify_in_out::public_key
 [in] Pointer to the public key to be used for verification
 
struct atca_temp_keyatca_verify_in_out::temp_key
 [in,out] Pointer to TempKey structure.
 

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}.
 
#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_HMAC   (88u)
 
#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_DIVERSIFIED_KEY   (96)
 ParentKey{32} || OtherData{4} || SN8{1} || SN0_1{2} || 0{25} || InputData{32}.
 
#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_SESSION_KEY   (96)
 TransportKey{32} || 0x15{1} || 0x00{1} || KeyId{2} || SN8{1} || SN0_1{2} || 0{25} || Nonce{32}.
 
#define ATCA_MSG_SIZE_DELETE_MAC   (96)
 Hmac/SecretKey{32} || 0x13{1} || 0x00{1} || 0x0000{2} || SN8{1} || SN0_1{2} || 0{25} || Nonce{32}.
 
#define ATCA_MSG_SIZE_RESPONSE_MAC   (97)
 SlotKey{32} || Opcode{1} || Param1{1} || Param2{2} || SN8{1} || SN0_1{2} || 0{25} || client_Resp{32} || checkmac_result{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_COMMAND_HEADER_SIZE   ( 4)
 
#define ATCA_GENDIG_ZEROS_SIZE   (25)
 
#define ATCA_GENDIVKEY_ZEROS_SIZE   (25)
 
#define ATCA_WRITE_MAC_ZEROS_SIZE   (25)
 
#define ATCA_DELETE_MAC_ZEROS_SIZE   (25)
 
#define ATCA_RESP_MAC_ZEROS_SIZE   (25)
 
#define ATCA_PRIVWRITE_MAC_ZEROS_SIZE   (21)
 
#define ATCA_PRIVWRITE_PLAIN_TEXT_SIZE   (36)
 
#define ATCA_DERIVE_KEY_ZEROS_SIZE   (25)
 
#define ATCA_HMAC_BLOCK_SIZE   (64u)
 
#define ATCA_ENCRYPTION_KEY_SIZE   (64)
 

Definition for TempKey Mode

#define MAC_MODE_USE_TEMPKEY_MASK   ((uint8_t)0x03)
 mode mask for MAC command when using TempKey
 

Detailed Description

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.