CryptoAuthLib
Microchip CryptoAuthentication Library
Basic Crypto API methods (atcab_)

These methods provide the most convenient, simple API to CryptoAuth chips. More...

Data Structures

struct  atca_aes_cbc_ctx
 
struct  atca_aes_cmac_ctx
 
struct  atca_aes_ctr_ctx
 
struct  atca_sha256_ctx
 

Macros

#define BLOCK_NUMBER(a)   (a / 32)
 
#define WORD_OFFSET(a)   ((a % 32) / 4)
 
#define ATCA_AES_GCM_IV_STD_LENGTH   12
 

Typedefs

typedef struct atca_aes_cbc_ctx atca_aes_cbc_ctx_t
 
typedef struct atca_aes_cmac_ctx atca_aes_cmac_ctx_t
 
typedef struct atca_aes_ctr_ctx atca_aes_ctr_ctx_t
 
typedef struct atca_sha256_ctx atca_sha256_ctx_t
 
typedef atca_sha256_ctx_t atca_hmac_sha256_ctx_t
 

Functions

ATCA_STATUS atcab_version (char *ver_str)
 basic API methods are all prefixed with atcab_ (CryptoAuthLib Basic) the fundamental premise of the basic API is it is based on a single interface instance and that instance is global, so all basic API commands assume that one global device is the one to operate on. More...
 
ATCA_STATUS atcab_init (ATCAIfaceCfg *cfg)
 Creates a global ATCADevice object used by Basic API. More...
 
ATCA_STATUS atcab_init_device (ATCADevice ca_device)
 Initialize the global ATCADevice object to point to one of your choosing for use with all the atcab_ basic API. More...
 
ATCA_STATUS atcab_release (void)
 release (free) the global ATCADevice instance. This must be called in order to release or free up the interface. More...
 
ATCADevice atcab_get_device (void)
 Get the global device object. More...
 
ATCADeviceType atcab_get_device_type (void)
 Get the current device type. More...
 
ATCA_STATUS _atcab_exit (void)
 common cleanup code which idles the device after any operation More...
 
ATCA_STATUS atcab_wakeup (void)
 wakeup the CryptoAuth device More...
 
ATCA_STATUS atcab_idle (void)
 idle the CryptoAuth device More...
 
ATCA_STATUS atcab_sleep (void)
 invoke sleep on the CryptoAuth device More...
 
ATCA_STATUS atcab_cfg_discover (ATCAIfaceCfg cfg_array[], int max)
 auto discovery of crypto auth devices More...
 
ATCA_STATUS atcab_get_addr (uint8_t zone, uint16_t slot, uint8_t block, uint8_t offset, uint16_t *addr)
 Compute the address given the zone, slot, block, and offset. More...
 
ATCA_STATUS atcab_get_zone_size (uint8_t zone, uint16_t slot, size_t *size)
 Gets the size of the specified zone in bytes. More...
 
ATCA_STATUS atcab_aes (uint8_t mode, uint16_t key_id, const uint8_t *aes_in, uint8_t *aes_out)
 Compute the AES-128 encrypt, decrypt, or GFM calculation. More...
 
ATCA_STATUS atcab_aes_encrypt (uint16_t key_id, uint8_t key_block, const uint8_t *plaintext, uint8_t *ciphertext)
 Perform an AES-128 encrypt operation with a key in the device. More...
 
ATCA_STATUS atcab_aes_decrypt (uint16_t key_id, uint8_t key_block, const uint8_t *ciphertext, uint8_t *plaintext)
 Perform an AES-128 decrypt operation with a key in the device. More...
 
ATCA_STATUS atcab_aes_gfm (const uint8_t *h, const uint8_t *input, uint8_t *output)
 Perform a Galois Field Multiply (GFM) operation. More...
 
ATCA_STATUS atcab_aes_cbc_init (atca_aes_cbc_ctx_t *ctx, uint16_t key_id, uint8_t key_block, const uint8_t *iv)
 Initialize context for AES CBC operation. More...
 
ATCA_STATUS atcab_aes_cbc_encrypt_block (atca_aes_cbc_ctx_t *ctx, const uint8_t *plaintext, uint8_t *ciphertext)
 Encrypt a block of data using CBC mode and a key within the ATECC608A. atcab_aes_cbc_init() should be called before the first use of this function. More...
 
ATCA_STATUS atcab_aes_cbc_decrypt_block (atca_aes_cbc_ctx_t *ctx, const uint8_t *ciphertext, uint8_t *plaintext)
 Decrypt a block of data using CBC mode and a key within the ATECC608A. atcab_aes_cbc_init() should be called before the first use of this function. More...
 
ATCA_STATUS atcab_aes_cmac_init (atca_aes_cmac_ctx_t *ctx, uint16_t key_id, uint8_t key_block)
 Initialize a CMAC calculation using an AES-128 key in the ATECC608A. More...
 
ATCA_STATUS atcab_aes_cmac_update (atca_aes_cmac_ctx_t *ctx, const uint8_t *data, uint32_t data_size)
 Add data to an initialized CMAC calculation. More...
 
ATCA_STATUS atcab_aes_cmac_finish (atca_aes_cmac_ctx_t *ctx, uint8_t *cmac, uint32_t cmac_size)
 Finish a CMAC operation returning the CMAC value. More...
 
ATCA_STATUS atcab_aes_ctr_init (atca_aes_ctr_ctx_t *ctx, uint16_t key_id, uint8_t key_block, uint8_t counter_size, const uint8_t *iv)
 Initialize context for AES CTR operation with an existing IV, which is common when start a decrypt operation. More...
 
ATCA_STATUS atcab_aes_ctr_init_rand (atca_aes_ctr_ctx_t *ctx, uint16_t key_id, uint8_t key_block, uint8_t counter_size, uint8_t *iv)
 Initialize context for AES CTR operation with a random nonce and counter set to 0 as the IV, which is common when starting an encrypt operation. More...
 
ATCA_STATUS atcab_aes_ctr_block (atca_aes_ctr_ctx_t *ctx, const uint8_t *input, uint8_t *output)
 Process a block of data using CTR mode and a key within the ATECC608A device. atcab_aes_ctr_init() or atcab_aes_ctr_init_rand() should be called before the first use of this function. More...
 
ATCA_STATUS atcab_aes_ctr_encrypt_block (atca_aes_ctr_ctx_t *ctx, const uint8_t *plaintext, uint8_t *ciphertext)
 Encrypt a block of data using CTR mode and a key within the ATECC608A device. atcab_aes_ctr_init() or atcab_aes_ctr_init_rand() should be called before the first use of this function. More...
 
ATCA_STATUS atcab_aes_ctr_decrypt_block (atca_aes_ctr_ctx_t *ctx, const uint8_t *ciphertext, uint8_t *plaintext)
 Decrypt a block of data using CTR mode and a key within the ATECC608A device. atcab_aes_ctr_init() or atcab_aes_ctr_init_rand() should be called before the first use of this function. More...
 
ATCA_STATUS atcab_aes_ctr_increment (atca_aes_ctr_ctx_t *ctx)
 Increments AES CTR counter value. More...
 
ATCA_STATUS atcab_checkmac (uint8_t mode, uint16_t key_id, const uint8_t *challenge, const uint8_t *response, const uint8_t *other_data)
 Compares a MAC response with input values. More...
 
ATCA_STATUS atcab_counter (uint8_t mode, uint16_t counter_id, uint32_t *counter_value)
 Compute the Counter functions. More...
 
ATCA_STATUS atcab_counter_increment (uint16_t counter_id, uint32_t *counter_value)
 Increments one of the device's monotonic counters. More...
 
ATCA_STATUS atcab_counter_read (uint16_t counter_id, uint32_t *counter_value)
 Read one of the device's monotonic counters. More...
 
ATCA_STATUS atcab_derivekey (uint8_t mode, uint16_t key_id, const uint8_t *mac)
 Executes the DeviveKey command for deriving a new key from a nonce (TempKey) and an existing key. More...
 
ATCA_STATUS atcab_ecdh_base (uint8_t mode, uint16_t key_id, const uint8_t *public_key, uint8_t *pms, uint8_t *out_nonce)
 Base function for generating premaster secret key using ECDH. More...
 
ATCA_STATUS atcab_ecdh (uint16_t key_id, const uint8_t *public_key, uint8_t *pms)
 ECDH command with a private key in a slot and the premaster secret is returned in the clear. More...
 
ATCA_STATUS atcab_ecdh_enc (uint16_t key_id, const uint8_t *public_key, uint8_t *pms, const uint8_t *read_key, uint16_t read_key_id)
 ECDH command with a private key in a slot and the premaster secret is read from the next slot. More...
 
ATCA_STATUS atcab_ecdh_ioenc (uint16_t key_id, const uint8_t *public_key, uint8_t *pms, const uint8_t *io_key)
 ECDH command with a private key in a slot and the premaster secret is returned encrypted using the IO protection key. More...
 
ATCA_STATUS atcab_ecdh_tempkey (const uint8_t *public_key, uint8_t *pms)
 ECDH command with a private key in TempKey and the premaster secret is returned in the clear. More...
 
ATCA_STATUS atcab_ecdh_tempkey_ioenc (const uint8_t *public_key, uint8_t *pms, const uint8_t *io_key)
 ECDH command with a private key in TempKey and the premaster secret is returned encrypted using the IO protection key. More...
 
ATCA_STATUS atcab_gendig (uint8_t zone, uint16_t key_id, const uint8_t *other_data, uint8_t other_data_size)
 Issues a GenDig command, which performs a SHA256 hash on the source data indicated by zone with the contents of TempKey. See the CryptoAuth datasheet for your chip to see what the values of zone correspond to. More...
 
ATCA_STATUS atcab_genkey_base (uint8_t mode, uint16_t key_id, const uint8_t *other_data, uint8_t *public_key)
 Issues GenKey command, which can generate a private key, compute a public key, nd/or compute a digest of a public key. More...
 
ATCA_STATUS atcab_genkey (uint16_t key_id, uint8_t *public_key)
 Issues GenKey command, which generates a new random private key in slot and returns the public key. More...
 
ATCA_STATUS atcab_get_pubkey (uint16_t key_id, uint8_t *public_key)
 Uses GenKey command to calculate the public key from an existing private key in a slot. More...
 
ATCA_STATUS atcab_hmac (uint8_t mode, uint16_t key_id, uint8_t *digest)
 Issues a HMAC command, which computes an HMAC/SHA-256 digest of a key stored in the device, a challenge, and other information on the device. More...
 
ATCA_STATUS atcab_info_base (uint8_t mode, uint16_t param2, uint8_t *out_data)
 Issues an Info command, which return internal device information and can control GPIO and the persistent latch. More...
 
ATCA_STATUS atcab_info (uint8_t *revision)
 Use the Info command to get the device revision (DevRev). More...
 
ATCA_STATUS atcab_info_set_latch (bool state)
 Use the Info command to set the persistent latch state for an ATECC608A device. More...
 
ATCA_STATUS atcab_info_get_latch (bool *state)
 Use the Info command to get the persistent latch current state for an ATECC608A device. More...
 
ATCA_STATUS atcab_kdf (uint8_t mode, uint16_t key_id, const uint32_t details, const uint8_t *message, uint8_t *out_data, uint8_t *out_nonce)
 Executes the KDF command, which derives a new key in PRF, AES, or HKDF modes. More...
 
ATCA_STATUS atcab_lock (uint8_t mode, uint16_t summary_crc)
 The Lock command prevents future modifications of the Configuration and/or Data and OTP zones. If the device is so configured, then this command can be used to lock individual data slots. This command fails if the designated area is already locked. More...
 
ATCA_STATUS atcab_lock_config_zone (void)
 Unconditionally (no CRC required) lock the config zone. More...
 
ATCA_STATUS atcab_lock_config_zone_crc (uint16_t summary_crc)
 Lock the config zone with summary CRC. More...
 
ATCA_STATUS atcab_lock_data_zone (void)
 Unconditionally (no CRC required) lock the data zone (slots and OTP). More...
 
ATCA_STATUS atcab_lock_data_zone_crc (uint16_t summary_crc)
 Lock the data zone (slots and OTP) with summary CRC. More...
 
ATCA_STATUS atcab_lock_data_slot (uint16_t slot)
 Lock an individual slot in the data zone on an ATECC device. Not available for ATSHA devices. Slot must be configured to be slot lockable (KeyConfig.Lockable=1). More...
 
ATCA_STATUS atcab_mac (uint8_t mode, uint16_t key_id, const uint8_t *challenge, uint8_t *digest)
 Executes MAC command, which computes a SHA-256 digest of a key stored in the device, a challenge, and other information on the device. More...
 
ATCA_STATUS atcab_nonce_base (uint8_t mode, uint16_t zero, const uint8_t *num_in, uint8_t *rand_out)
 Executes Nonce command, which loads a random or fixed nonce/data into the device for use by subsequent commands. More...
 
ATCA_STATUS atcab_nonce (const uint8_t *num_in)
 Execute a Nonce command in pass-through mode to initialize TempKey to a specified value. More...
 
ATCA_STATUS atcab_nonce_load (uint8_t target, const uint8_t *num_in, uint16_t num_in_size)
 Execute a Nonce command in pass-through mode to load one of the device's internal buffers with a fixed value. More...
 
ATCA_STATUS atcab_nonce_rand (const uint8_t *num_in, uint8_t *rand_out)
 Execute a Nonce command to generate a random nonce combining a host nonce (num_in) and a device random number. More...
 
ATCA_STATUS atcab_challenge (const uint8_t *num_in)
 Execute a Nonce command in pass-through mode to initialize TempKey to a specified value. More...
 
ATCA_STATUS atcab_challenge_seed_update (const uint8_t *num_in, uint8_t *rand_out)
 Execute a Nonce command to generate a random challenge combining a host nonce (num_in) and a device random number. More...
 
ATCA_STATUS atcab_priv_write (uint16_t key_id, const uint8_t priv_key[36], uint16_t write_key_id, const uint8_t write_key[32])
 Executes PrivWrite command, to write externally generated ECC private keys into the device. More...
 
ATCA_STATUS atcab_random (uint8_t *rand_out)
 Executes Random command, which generates a 32 byte random number from the CryptoAuth device. More...
 
ATCA_STATUS atcab_read_zone (uint8_t zone, uint16_t slot, uint8_t block, uint8_t offset, uint8_t *data, uint8_t len)
 Executes Read command, which reads either 4 or 32 bytes of data from a given slot, configuration zone, or the OTP zone. More...
 
ATCA_STATUS atcab_is_locked (uint8_t zone, bool *is_locked)
 Executes Read command, which reads the configuration zone to see if the specified zone is locked. More...
 
ATCA_STATUS atcab_is_slot_locked (uint16_t slot, bool *is_locked)
 Executes Read command, which reads the configuration zone to see if the specified slot is locked. More...
 
ATCA_STATUS atcab_read_bytes_zone (uint8_t zone, uint16_t slot, size_t offset, uint8_t *data, size_t length)
 Used to read an arbitrary number of bytes from any zone configured for clear reads. More...
 
ATCA_STATUS atcab_read_serial_number (uint8_t *serial_number)
 Executes Read command, which reads the 9 byte serial number of the device from the config zone. More...
 
ATCA_STATUS atcab_read_pubkey (uint16_t slot, uint8_t *public_key)
 Executes Read command to read an ECC P256 public key from a slot configured for clear reads. More...
 
ATCA_STATUS atcab_read_sig (uint16_t slot, uint8_t *sig)
 Executes Read command to read a 64 byte ECDSA P256 signature from a slot configured for clear reads. More...
 
ATCA_STATUS atcab_read_config_zone (uint8_t *config_data)
 Executes Read command to read the complete device configuration zone. More...
 
ATCA_STATUS atcab_cmp_config_zone (uint8_t *config_data, bool *same_config)
 Compares a specified configuration zone with the configuration zone currently on the device. More...
 
ATCA_STATUS atcab_read_enc (uint16_t key_id, uint8_t block, uint8_t *data, const uint8_t *enc_key, const uint16_t enc_key_id)
 Executes Read command on a slot configured for encrypted reads and decrypts the data to return it as plaintext. More...
 
ATCA_STATUS atcab_secureboot (uint8_t mode, uint16_t param2, const uint8_t *digest, const uint8_t *signature, uint8_t *mac)
 Executes Secure Boot command, which provides support for secure boot of an external MCU or MPU. More...
 
ATCA_STATUS atcab_secureboot_mac (uint8_t mode, const uint8_t *digest, const uint8_t *signature, const uint8_t *num_in, const uint8_t *io_key, bool *is_verified)
 Executes Secure Boot command with encrypted digest and validated MAC response using the IO protection key. More...
 
ATCA_STATUS atcab_selftest (uint8_t mode, uint16_t param2, uint8_t *result)
 Executes the SelfTest command, which performs a test of one or more of the cryptographic engines within the ATECC608A chip. More...
 
ATCA_STATUS atcab_sha_base (uint8_t mode, uint16_t length, const uint8_t *data_in, uint8_t *data_out, uint16_t *data_out_size)
 Executes SHA command, which computes a SHA-256 or HMAC/SHA-256 digest for general purpose use by the host system. More...
 
ATCA_STATUS atcab_sha_start (void)
 Executes SHA command to initialize SHA-256 calculation engine. More...
 
ATCA_STATUS atcab_sha_update (const uint8_t *message)
 Executes SHA command to add 64 bytes of message data to the current context. More...
 
ATCA_STATUS atcab_sha_end (uint8_t *digest, uint16_t length, const uint8_t *message)
 Executes SHA command to complete SHA-256 or HMAC/SHA-256 operation. More...
 
ATCA_STATUS atcab_sha_read_context (uint8_t *context, uint16_t *context_size)
 Executes SHA command to read the SHA-256 context back. Only for ATECC608A with SHA-256 contexts. HMAC not supported. More...
 
ATCA_STATUS atcab_sha_write_context (const uint8_t *context, uint16_t context_size)
 Executes SHA command to write (restore) a SHA-256 context into the the device. Only supported for ATECC608A with SHA-256 contexts. More...
 
ATCA_STATUS atcab_sha (uint16_t length, const uint8_t *message, uint8_t *digest)
 Use the SHA command to compute a SHA-256 digest. More...
 
ATCA_STATUS atcab_hw_sha2_256 (const uint8_t *data, size_t data_size, uint8_t *digest)
 Use the SHA command to compute a SHA-256 digest. More...
 
ATCA_STATUS atcab_hw_sha2_256_init (atca_sha256_ctx_t *ctx)
 Initialize a SHA context for performing a hardware SHA-256 operation on a device. Note that only one SHA operation can be run at a time. More...
 
ATCA_STATUS atcab_hw_sha2_256_update (atca_sha256_ctx_t *ctx, const uint8_t *data, size_t data_size)
 Add message data to a SHA context for performing a hardware SHA-256 operation on a device. More...
 
ATCA_STATUS atcab_hw_sha2_256_finish (atca_sha256_ctx_t *ctx, uint8_t *digest)
 Finish SHA-256 digest for a SHA context for performing a hardware SHA-256 operation on a device. More...
 
ATCA_STATUS atcab_sha_hmac_init (atca_hmac_sha256_ctx_t *ctx, uint16_t key_slot)
 Executes SHA command to start an HMAC/SHA-256 operation. More...
 
ATCA_STATUS atcab_sha_hmac_update (atca_hmac_sha256_ctx_t *ctx, const uint8_t *data, size_t data_size)
 Executes SHA command to add an arbitrary amount of message data to a HMAC/SHA-256 operation. More...
 
ATCA_STATUS atcab_sha_hmac_finish (atca_hmac_sha256_ctx_t *ctx, uint8_t *digest, uint8_t target)
 Executes SHA command to complete a HMAC/SHA-256 operation. More...
 
ATCA_STATUS atcab_sha_hmac (const uint8_t *data, size_t data_size, uint16_t key_slot, uint8_t *digest, uint8_t target)
 Use the SHA command to compute an HMAC/SHA-256 operation. More...
 
ATCA_STATUS atcab_sign_base (uint8_t mode, uint16_t key_id, uint8_t *signature)
 Executes the Sign command, which generates a signature using the ECDSA algorithm. More...
 
ATCA_STATUS atcab_sign (uint16_t key_id, const uint8_t *msg, uint8_t *signature)
 Executes Sign command, to sign a 32-byte external message using the private key in the specified slot. The message to be signed will be loaded into the Message Digest Buffer to the ATECC608A device or TempKey for other devices. More...
 
ATCA_STATUS atcab_sign_internal (uint16_t key_id, bool is_invalidate, bool is_full_sn, uint8_t *signature)
 Executes Sign command to sign an internally generated message. More...
 
ATCA_STATUS atcab_updateextra (uint8_t mode, uint16_t new_value)
 Executes UpdateExtra command to update the values of the two extra bytes within the Configuration zone (bytes 84 and 85). More...
 
ATCA_STATUS atcab_verify (uint8_t mode, uint16_t key_id, const uint8_t *signature, const uint8_t *public_key, const uint8_t *other_data, uint8_t *mac)
 Executes the Verify command, which takes an ECDSA [R,S] signature and verifies that it is correctly generated from a given message and public key. In all cases, the signature is an input to the command. More...
 
ATCA_STATUS atcab_verify_extern (const uint8_t *message, const uint8_t *signature, const uint8_t *public_key, bool *is_verified)
 Executes the Verify command, which verifies a signature (ECDSA verify operation) with all components (message, signature, and public key) supplied. The message to be signed will be loaded into the Message Digest Buffer to the ATECC608A device or TempKey for other devices. More...
 
ATCA_STATUS atcab_verify_extern_mac (const uint8_t *message, const uint8_t *signature, const uint8_t *public_key, const uint8_t *num_in, const uint8_t *io_key, bool *is_verified)
 Executes the Verify command with verification MAC, which verifies a signature (ECDSA verify operation) with all components (message, signature, and public key) supplied. This function is only available on the ATECC608A. More...
 
ATCA_STATUS atcab_verify_stored (const uint8_t *message, const uint8_t *signature, uint16_t key_id, bool *is_verified)
 Executes the Verify command, which verifies a signature (ECDSA verify operation) with a public key stored in the device. The message to be signed will be loaded into the Message Digest Buffer to the ATECC608A device or TempKey for other devices. More...
 
ATCA_STATUS atcab_verify_stored_mac (const uint8_t *message, const uint8_t *signature, uint16_t key_id, const uint8_t *num_in, const uint8_t *io_key, bool *is_verified)
 Executes the Verify command with verification MAC, which verifies a signature (ECDSA verify operation) with a public key stored in the device. This function is only available on the ATECC608A. More...
 
ATCA_STATUS atcab_verify_validate (uint16_t key_id, const uint8_t *signature, const uint8_t *other_data, bool *is_verified)
 Executes the Verify command in Validate mode to validate a public key stored in a slot. More...
 
ATCA_STATUS atcab_verify_invalidate (uint16_t key_id, const uint8_t *signature, const uint8_t *other_data, bool *is_verified)
 Executes the Verify command in Invalidate mode which invalidates a previously validated public key stored in a slot. More...
 
ATCA_STATUS atcab_write (uint8_t zone, uint16_t address, const uint8_t *value, const uint8_t *mac)
 Executes the Write command, which writes either one four byte word or a 32-byte block to one of the EEPROM zones on the device. Depending upon the value of the WriteConfig byte for this slot, the data may be required to be encrypted by the system prior to being sent to the device. This command cannot be used to write slots configured as ECC private keys. More...
 
ATCA_STATUS atcab_write_zone (uint8_t zone, uint16_t slot, uint8_t block, uint8_t offset, const uint8_t *data, uint8_t len)
 Executes the Write command, which writes either 4 or 32 bytes of data into a device zone. More...
 
ATCA_STATUS atcab_write_bytes_zone (uint8_t zone, uint16_t slot, size_t offset_bytes, const uint8_t *data, size_t length)
 Executes the Write command, which writes data into the configuration, otp, or data zones with a given byte offset and length. Offset and length must be multiples of a word (4 bytes). More...
 
ATCA_STATUS atcab_write_pubkey (uint16_t slot, const uint8_t *public_key)
 Executes the Write command, which writes a public key to a data slot in the device format. More...
 
ATCA_STATUS atcab_write_config_zone (const uint8_t *config_data)
 Executes the Write command, which writes the configuration zone. More...
 
ATCA_STATUS atcab_write_enc (uint16_t key_id, uint8_t block, const uint8_t *data, const uint8_t *enc_key, const uint16_t enc_key_id)
 Executes the Write command, which performs an encrypted write of a 32 byte block into given slot. More...
 
ATCA_STATUS atcab_write_config_counter (uint16_t counter_id, uint32_t counter_value)
 Initialize one of the monotonic counters in device with a specific value. More...
 
ATCA_STATUS atcab_printbin (uint8_t *binary, size_t bin_len, bool add_space)
 
ATCA_STATUS atcab_bin2hex (const uint8_t *bin, size_t bin_size, char *hex, size_t *hex_size)
 Convert a binary buffer to a hex string for easy reading. More...
 
ATCA_STATUS atcab_bin2hex_ (const uint8_t *bin, size_t bin_size, char *hex, size_t *hex_size, bool is_pretty)
 Function that converts a binary buffer to a hex string suitable for easy reading. More...
 
ATCA_STATUS atcab_hex2bin (const char *ascii_hex, size_t ascii_hex_len, uint8_t *binary, size_t *bin_len)
 Function that converts a hex string to binary buffer. More...
 
ATCA_STATUS atcab_printbin_sp (uint8_t *binary, size_t bin_len)
 
ATCA_STATUS atcab_printbin_label (const char *label, uint8_t *binary, size_t bin_len)
 
ATCA_STATUS packHex (const char *ascii_hex, size_t ascii_hex_len, char *packed_hex, size_t *packed_len)
 Remove white space from a ASCII hex string. More...
 
bool isDigit (char c)
 Checks to see if a character is an ASCII representation of a digit ((c ge '0') and (c le '9')) More...
 
bool isWhiteSpace (char c)
 Checks to see if a character is whitespace. More...
 
bool isAlpha (char c)
 Checks to see if a character is an ASCII representation of hex ((c >= 'A') and (c <= 'F')) || ((c >= 'a') and (c <= 'f')) More...
 
bool isHexAlpha (char c)
 Checks to see if a character is an ASCII representation of hex ((c >= 'A') and (c <= 'F')) || ((c >= 'a') and (c <= 'f')) More...
 
bool isHex (char c)
 Returns true if this character is a valid hex character or if this is whitespace (The character can be included in a valid hexstring). More...
 
bool isHexDigit (char c)
 Returns true if this character is a valid hex character. More...
 
bool isBase64 (char c, const uint8_t *rules)
 Returns true if this character is a valid base 64 character or if this is whitespace (A character can be included in a valid base 64 string). More...
 
bool isBase64Digit (char c, const uint8_t *rules)
 Returns true if this character is a valid base 64 character. More...
 
uint8_t base64Index (char c, const uint8_t *rules)
 Returns the base 64 index of the given character. More...
 
char base64Char (uint8_t id, const uint8_t *rules)
 Returns the base 64 character of the given index. More...
 
ATCA_STATUS atcab_base64decode_ (const char *encoded, size_t encoded_size, uint8_t *data, size_t *data_size, const uint8_t *rules)
 Decode base64 string to data with ruleset option. More...
 
ATCA_STATUS atcab_base64decode (const char *encoded, size_t encoded_size, uint8_t *data, size_t *data_size)
 Decode base64 string to data. More...
 
ATCA_STATUS atcab_base64encode_ (const uint8_t *data, size_t data_size, char *encoded, size_t *encoded_size, const uint8_t *rules)
 Encode data as base64 string with ruleset option. More...
 
ATCA_STATUS atcab_base64encode (const uint8_t *data, size_t data_size, char *encoded, size_t *encoded_size)
 Encode data as base64 string. More...
 

Variables

ATCADevice _gDevice
 
uint8_t atcab_b64rules_default [4]
 
uint8_t atcab_b64rules_mime [4]
 
uint8_t atcab_b64rules_urlsafe [4]
 

Detailed Description

These methods provide the most convenient, simple API to CryptoAuth chips.

Macro Definition Documentation

◆ ATCA_AES_GCM_IV_STD_LENGTH

#define ATCA_AES_GCM_IV_STD_LENGTH   12

◆ BLOCK_NUMBER

#define BLOCK_NUMBER (   a)    (a / 32)

◆ WORD_OFFSET

#define WORD_OFFSET (   a)    ((a % 32) / 4)

Typedef Documentation

◆ atca_aes_cbc_ctx_t

◆ atca_aes_cmac_ctx_t

◆ atca_aes_ctr_ctx_t

◆ atca_hmac_sha256_ctx_t

◆ atca_sha256_ctx_t

Function Documentation

◆ _atcab_exit()

ATCA_STATUS _atcab_exit ( void  )

common cleanup code which idles the device after any operation

Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes()

ATCA_STATUS atcab_aes ( uint8_t  mode,
uint16_t  key_id,
const uint8_t *  aes_in,
uint8_t *  aes_out 
)

Compute the AES-128 encrypt, decrypt, or GFM calculation.

Parameters
[in]modeThe mode for the AES command.
[in]key_idKey location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]aes_inInput data to the AES command (16 bytes).
[out]aes_outOutput data from the AES command is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_cbc_decrypt_block()

ATCA_STATUS atcab_aes_cbc_decrypt_block ( atca_aes_cbc_ctx_t ctx,
const uint8_t *  ciphertext,
uint8_t *  plaintext 
)

Decrypt a block of data using CBC mode and a key within the ATECC608A. atcab_aes_cbc_init() should be called before the first use of this function.

Parameters
[in]ctxAES CBC context.
[in]ciphertextCiphertext to be decrypted (16 bytes).
[out]plaintextDecrypted data is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_cbc_encrypt_block()

ATCA_STATUS atcab_aes_cbc_encrypt_block ( atca_aes_cbc_ctx_t ctx,
const uint8_t *  plaintext,
uint8_t *  ciphertext 
)

Encrypt a block of data using CBC mode and a key within the ATECC608A. atcab_aes_cbc_init() should be called before the first use of this function.

Parameters
[in]ctxAES CBC context.
[in]plaintextPlaintext to be encrypted (16 bytes).
[out]ciphertextEncrypted data is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_cbc_init()

ATCA_STATUS atcab_aes_cbc_init ( atca_aes_cbc_ctx_t ctx,
uint16_t  key_id,
uint8_t  key_block,
const uint8_t *  iv 
)

Initialize context for AES CBC operation.

Parameters
[in]ctxAES CBC context to be initialized
[in]key_idKey location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]key_blockIndex of the 16-byte block to use within the key location for the actual key.
[in]ivInitialization vector (16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_cmac_finish()

ATCA_STATUS atcab_aes_cmac_finish ( atca_aes_cmac_ctx_t ctx,
uint8_t *  cmac,
uint32_t  cmac_size 
)

Finish a CMAC operation returning the CMAC value.

Parameters
[in]ctxAES-128 CMAC context.
[out]cmacCMAC is returned here.
[in]cmac_sizeSize of CMAC requested in bytes (max 16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_cmac_init()

ATCA_STATUS atcab_aes_cmac_init ( atca_aes_cmac_ctx_t ctx,
uint16_t  key_id,
uint8_t  key_block 
)

Initialize a CMAC calculation using an AES-128 key in the ATECC608A.

Parameters
[in]ctxAES-128 CMAC context.
[in]key_idKey location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]key_blockIndex of the 16-byte block to use within the key location for the actual key.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_cmac_update()

ATCA_STATUS atcab_aes_cmac_update ( atca_aes_cmac_ctx_t ctx,
const uint8_t *  data,
uint32_t  data_size 
)

Add data to an initialized CMAC calculation.

Parameters
[in]ctxAES-128 CMAC context.
[in]dataData to be added.
[in]data_sizeSize of the data to be added in bytes.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_ctr_block()

ATCA_STATUS atcab_aes_ctr_block ( atca_aes_ctr_ctx_t ctx,
const uint8_t *  input,
uint8_t *  output 
)

Process a block of data using CTR mode and a key within the ATECC608A device. atcab_aes_ctr_init() or atcab_aes_ctr_init_rand() should be called before the first use of this function.

Parameters
[in]ctxAES CTR context structure.
[in]inputInput data to be processed (16 bytes).
[out]outputOutput data is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, ATCA_INVALID_SIZE on counter overflow, otherwise an error code.

◆ atcab_aes_ctr_decrypt_block()

ATCA_STATUS atcab_aes_ctr_decrypt_block ( atca_aes_ctr_ctx_t ctx,
const uint8_t *  ciphertext,
uint8_t *  plaintext 
)

Decrypt a block of data using CTR mode and a key within the ATECC608A device. atcab_aes_ctr_init() or atcab_aes_ctr_init_rand() should be called before the first use of this function.

Parameters
[in]ctxAES CTR context structure.
[in]ciphertextCiphertext to be decrypted (16 bytes).
[out]plaintextDecrypted data is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, ATCA_INVALID_SIZE on counter overflow, otherwise an error code.

◆ atcab_aes_ctr_encrypt_block()

ATCA_STATUS atcab_aes_ctr_encrypt_block ( atca_aes_ctr_ctx_t ctx,
const uint8_t *  plaintext,
uint8_t *  ciphertext 
)

Encrypt a block of data using CTR mode and a key within the ATECC608A device. atcab_aes_ctr_init() or atcab_aes_ctr_init_rand() should be called before the first use of this function.

Parameters
[in]ctxAES CTR context structure.
[in]plaintextPlaintext to be encrypted (16 bytes).
[out]ciphertextEncrypted data is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, ATCA_INVALID_SIZE on counter overflow, otherwise an error code.

◆ atcab_aes_ctr_increment()

ATCA_STATUS atcab_aes_ctr_increment ( atca_aes_ctr_ctx_t ctx)

Increments AES CTR counter value.

Parameters
[in,out]ctxAES CTR context
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_ctr_init()

ATCA_STATUS atcab_aes_ctr_init ( atca_aes_ctr_ctx_t ctx,
uint16_t  key_id,
uint8_t  key_block,
uint8_t  counter_size,
const uint8_t *  iv 
)

Initialize context for AES CTR operation with an existing IV, which is common when start a decrypt operation.

The IV is a combination of nonce (left-field) and big-endian counter (right-field). The counter_size field sets the size of the counter and the remaining bytes are assumed to be the nonce.

Parameters
[in]ctxAES CTR context to be initialized.
[in]key_idKey location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]key_blockIndex of the 16-byte block to use within the key location for the actual key.
[in]counter_sizeSize of counter in IV in bytes. 4 bytes is a common size.
[in]ivInitialization vector (concatenation of nonce and counter) 16 bytes.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_ctr_init_rand()

ATCA_STATUS atcab_aes_ctr_init_rand ( atca_aes_ctr_ctx_t ctx,
uint16_t  key_id,
uint8_t  key_block,
uint8_t  counter_size,
uint8_t *  iv 
)

Initialize context for AES CTR operation with a random nonce and counter set to 0 as the IV, which is common when starting an encrypt operation.

The IV is a combination of nonce (left-field) and big-endian counter (right-field). The counter_size field sets the size of the counter and the remaining bytes are assumed to be the nonce.

Parameters
[in]ctxAES CTR context to be initialized.
[in]key_idKey location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]key_blockIndex of the 16-byte block to use within the key location for the actual key.
[in]counter_sizeSize of counter in IV in bytes. 4 bytes is a common size.
[out]ivInitialization vector (concatenation of nonce and counter) is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_decrypt()

ATCA_STATUS atcab_aes_decrypt ( uint16_t  key_id,
uint8_t  key_block,
const uint8_t *  ciphertext,
uint8_t *  plaintext 
)

Perform an AES-128 decrypt operation with a key in the device.

Parameters
[in]key_idKey location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]key_blockIndex of the 16-byte block to use within the key location for the actual key.
[in]ciphertextInput ciphertext to be decrypted (16 bytes).
[out]plaintextOutput plaintext is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_encrypt()

ATCA_STATUS atcab_aes_encrypt ( uint16_t  key_id,
uint8_t  key_block,
const uint8_t *  plaintext,
uint8_t *  ciphertext 
)

Perform an AES-128 encrypt operation with a key in the device.

Parameters
[in]key_idKey location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]key_blockIndex of the 16-byte block to use within the key location for the actual key.
[in]plaintextInput plaintext to be encrypted (16 bytes).
[out]ciphertextOutput ciphertext is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_gfm()

ATCA_STATUS atcab_aes_gfm ( const uint8_t *  h,
const uint8_t *  input,
uint8_t *  output 
)

Perform a Galois Field Multiply (GFM) operation.

Parameters
[in]hFirst input value (16 bytes).
[in]inputSecond input value (16 bytes).
[out]outputGFM result is returned here (16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_base64decode()

ATCA_STATUS atcab_base64decode ( const char *  encoded,
size_t  encoded_len,
uint8_t *  byte_array,
size_t *  array_len 
)

Decode base64 string to data.

Parameters
[in]encodedBase64 string to be decoded.
[in]encoded_lenSize of the base64 string in bytes.
[out]byte_arrayDecoded data will be returned here.
[in,out]array_lenAs input, the size of the byte_array buffer. As output, the length of the decoded data.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_base64decode_()

ATCA_STATUS atcab_base64decode_ ( const char *  encoded,
size_t  encoded_size,
uint8_t *  data,
size_t *  data_size,
const uint8_t *  rules 
)

Decode base64 string to data with ruleset option.

Parameters
[in]encodedBase64 string to be decoded.
[in]encoded_sizeSize of the base64 string in bytes.
[out]dataDecoded data will be returned here.
[in,out]data_sizeAs input, the size of the byte_array buffer. As output, the length of the decoded data.
[in]rulesbase64 ruleset to use

◆ atcab_base64encode()

ATCA_STATUS atcab_base64encode ( const uint8_t *  byte_array,
size_t  array_len,
char *  encoded,
size_t *  encoded_len 
)

Encode data as base64 string.

Parameters
[in]byte_arrayData to be encode in base64.
[in]array_lenSize of byte_array in bytes.
[in]encodedBase64 output is returned here.
[in,out]encoded_lenAs input, the size of the encoded buffer. As output, the length of the encoded base64 character string.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_base64encode_()

ATCA_STATUS atcab_base64encode_ ( const uint8_t *  data,
size_t  data_size,
char *  encoded,
size_t *  encoded_size,
const uint8_t *  rules 
)

Encode data as base64 string with ruleset option.

Parameters
[in]dataThe input byte array that will be converted to base 64 encoded characters
[in]data_sizeThe length of the byte array
[in]encodedThe output converted to base 64 encoded characters.
[in,out]encoded_sizeInput: The size of the encoded buffer, Output: The length of the encoded base 64 character string
[in]rulesruleset to use during encoding

◆ atcab_bin2hex()

ATCA_STATUS atcab_bin2hex ( const uint8_t *  bin,
size_t  bin_size,
char *  hex,
size_t *  hex_size 
)

Convert a binary buffer to a hex string for easy reading.

Parameters
[in]binInput data to convert.
[in]bin_sizeSize of data to convert.
[out]hexBuffer that receives hex string.
[in,out]hex_sizeAs input, the size of the hex buffer. As output, the size of the output hex.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_bin2hex_()

ATCA_STATUS atcab_bin2hex_ ( const uint8_t *  bin,
size_t  bin_size,
char *  hex,
size_t *  hex_size,
bool  is_pretty 
)

Function that converts a binary buffer to a hex string suitable for easy reading.

Parameters
[in]binInput data to convert.
[in]bin_sizeSize of data to convert.
[out]hexBuffer that receives hex string.
[in,out]hex_sizeAs input, the size of the hex buffer. As output, the size of the output hex.
[in]is_prettyIndicates whether spaces and new lines should be added for pretty printing.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_cfg_discover()

ATCA_STATUS atcab_cfg_discover ( ATCAIfaceCfg  cfg_array[],
int  max_ifaces 
)

auto discovery of crypto auth devices

Calls interface discovery functions and fills in cfg_array up to the maximum number of configurations either found or the size of the array. The cfg_array can have a mixture of interface types (ie: some I2C, some SWI or UART) depending upon which interfaces you've enabled

Parameters
[out]cfg_arrayptr to an array of interface configs
[in]max_ifacesmaximum size of cfg_array
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_challenge()

ATCA_STATUS atcab_challenge ( const uint8_t *  num_in)

Execute a Nonce command in pass-through mode to initialize TempKey to a specified value.

Parameters
[in]num_inData to be loaded into TempKey (32 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_challenge_seed_update()

ATCA_STATUS atcab_challenge_seed_update ( const uint8_t *  num_in,
uint8_t *  rand_out 
)

Execute a Nonce command to generate a random challenge combining a host nonce (num_in) and a device random number.

Parameters
[in]num_inHost nonce to be combined with the device random number (20 bytes).
[out]rand_outInternally generated 32-byte random number that was used in the nonce/challenge calculation is returned here. Can be NULL if not needed.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_checkmac()

ATCA_STATUS atcab_checkmac ( uint8_t  mode,
uint16_t  key_id,
const uint8_t *  challenge,
const uint8_t *  response,
const uint8_t *  other_data 
)

Compares a MAC response with input values.

Parameters
[in]modeControls which fields within the device are used in the message
[in]key_idKey location in the CryptoAuth device to use for the MAC
[in]challengeChallenge data (32 bytes)
[in]responseMAC response data (32 bytes)
[in]other_dataOtherData parameter (13 bytes)
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_cmp_config_zone()

ATCA_STATUS atcab_cmp_config_zone ( uint8_t *  config_data,
bool *  same_config 
)

Compares a specified configuration zone with the configuration zone currently on the device.

This only compares the static portions of the configuration zone and skips those that are unique per device (first 16 bytes) and areas that can change after the configuration zone has been locked (e.g. LastKeyUse).

Parameters
[in]config_dataFull configuration data to compare the device against.
[out]same_configResult is returned here. True if the static portions on the configuration zones are the same.
Returns
ATCA_SUCCESS on success, otherwise an error code.

Max for all configs

◆ atcab_counter()

ATCA_STATUS atcab_counter ( uint8_t  mode,
uint16_t  counter_id,
uint32_t *  counter_value 
)

Compute the Counter functions.

Parameters
[in]modethe mode used for the counter
[in]counter_idThe counter to be used
[out]counter_valuepointer to the counter value returned from device
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_counter_increment()

ATCA_STATUS atcab_counter_increment ( uint16_t  counter_id,
uint32_t *  counter_value 
)

Increments one of the device's monotonic counters.

Parameters
[in]counter_idCounter to be incremented
[out]counter_valueNew value of the counter is returned here. Can be NULL if not needed.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_counter_read()

ATCA_STATUS atcab_counter_read ( uint16_t  counter_id,
uint32_t *  counter_value 
)

Read one of the device's monotonic counters.

Parameters
[in]counter_idCounter to be read
[out]counter_valueCounter value is returned here.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_derivekey()

ATCA_STATUS atcab_derivekey ( uint8_t  mode,
uint16_t  target_key,
const uint8_t *  mac 
)

Executes the DeviveKey command for deriving a new key from a nonce (TempKey) and an existing key.

Parameters
[in]modeBit 2 must match the value in TempKey.SourceFlag
[in]target_keyKey slot to be written
[in]macOptional 32 byte MAC used to validate operation. NULL if not required.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_ecdh()

ATCA_STATUS atcab_ecdh ( uint16_t  key_id,
const uint8_t *  public_key,
uint8_t *  pms 
)

ECDH command with a private key in a slot and the premaster secret is returned in the clear.

Parameters
[in]key_idSlot of key for ECDH computation
[in]public_keyPublic key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]pmsComputed ECDH premaster secret is returned here. 32 bytes.
Returns
ATCA_SUCCESS on success

◆ atcab_ecdh_base()

ATCA_STATUS atcab_ecdh_base ( uint8_t  mode,
uint16_t  key_id,
const uint8_t *  public_key,
uint8_t *  pms,
uint8_t *  out_nonce 
)

Base function for generating premaster secret key using ECDH.

Parameters
[in]modeMode to be used for ECDH computation
[in]key_idSlot of key for ECDH computation
[in]public_keyPublic key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]pmsComputed ECDH pre-master secret is returned here (32 bytes) if returned directly. Otherwise NULL.
[out]out_nonceNonce used to encrypt pre-master secret. NULL if output encryption not used.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_ecdh_enc()

ATCA_STATUS atcab_ecdh_enc ( uint16_t  key_id,
const uint8_t *  public_key,
uint8_t *  pms,
const uint8_t *  read_key,
uint16_t  read_key_id 
)

ECDH command with a private key in a slot and the premaster secret is read from the next slot.

This function only works for even numbered slots with the proper configuration.

Parameters
[in]key_idSlot of key for ECDH computation
[in]public_keyPublic key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]pmsComputed ECDH premaster secret is returned here (32 bytes).
[in]read_keyRead key for the premaster secret slot (key_id|1).
[in]read_key_idRead key slot for read_key.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_ecdh_ioenc()

ATCA_STATUS atcab_ecdh_ioenc ( uint16_t  key_id,
const uint8_t *  public_key,
uint8_t *  pms,
const uint8_t *  io_key 
)

ECDH command with a private key in a slot and the premaster secret is returned encrypted using the IO protection key.

Parameters
[in]key_idSlot of key for ECDH computation
[in]public_keyPublic key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]pmsComputed ECDH premaster secret is returned here (32 bytes).
[in]io_keyIO protection key.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_ecdh_tempkey()

ATCA_STATUS atcab_ecdh_tempkey ( const uint8_t *  public_key,
uint8_t *  pms 
)

ECDH command with a private key in TempKey and the premaster secret is returned in the clear.

Parameters
[in]public_keyPublic key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]pmsComputed ECDH premaster secret is returned here (32 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_ecdh_tempkey_ioenc()

ATCA_STATUS atcab_ecdh_tempkey_ioenc ( const uint8_t *  public_key,
uint8_t *  pms,
const uint8_t *  io_key 
)

ECDH command with a private key in TempKey and the premaster secret is returned encrypted using the IO protection key.

Parameters
[in]public_keyPublic key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]pmsComputed ECDH premaster secret is returned here (32 bytes).
[in]io_keyIO protection key.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_gendig()

ATCA_STATUS atcab_gendig ( uint8_t  zone,
uint16_t  key_id,
const uint8_t *  other_data,
uint8_t  other_data_size 
)

Issues a GenDig command, which performs a SHA256 hash on the source data indicated by zone with the contents of TempKey. See the CryptoAuth datasheet for your chip to see what the values of zone correspond to.

Parameters
[in]zoneDesignates the source of the data to hash with TempKey.
[in]key_idIndicates the key, OTP block, or message order for shared nonce mode.
[in]other_dataFour bytes of data for SHA calculation when using a NoMac key, 32 bytes for "Shared Nonce" mode, otherwise ignored (can be NULL).
[in]other_data_sizeSize of other_data in bytes.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_genkey()

ATCA_STATUS atcab_genkey ( uint16_t  key_id,
uint8_t *  public_key 
)

Issues GenKey command, which generates a new random private key in slot and returns the public key.

Parameters
[in]key_idSlot number where an ECC private key is configured. Can also be ATCA_TEMPKEY_KEYID to generate a private key in TempKey.
[out]public_keyPublic key will be returned here. Format will be the X and Y integers in big-endian format. 64 bytes for P256 curve. Set to NULL if public key isn't required.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_genkey_base()

ATCA_STATUS atcab_genkey_base ( uint8_t  mode,
uint16_t  key_id,
const uint8_t *  other_data,
uint8_t *  public_key 
)

Issues GenKey command, which can generate a private key, compute a public key, nd/or compute a digest of a public key.

Parameters
[in]modeMode determines what operations the GenKey command performs.
[in]key_idSlot to perform the GenKey command on.
[in]other_dataOtherData for PubKey digest calculation. Can be set to NULL otherwise.
[out]public_keyIf the mode indicates a public key will be calculated, it will be returned here. Format will be the X and Y integers in big-endian format. 64 bytes for P256 curve. Set to NULL if public key isn't required.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_get_addr()

ATCA_STATUS atcab_get_addr ( uint8_t  zone,
uint16_t  slot,
uint8_t  block,
uint8_t  offset,
uint16_t *  addr 
)

Compute the address given the zone, slot, block, and offset.

Parameters
[in]zoneZone to get address from. Config(0), OTP(1), or Data(2) which requires a slot.
[in]slotSlot Id number for data zone and zero for other zones.
[in]blockBlock number within the data or configuration or OTP zone .
[in]offsetOffset Number within the block of data or configuration or OTP zone.
[out]addrPointer to the address of data or configuration or OTP zone.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_get_device()

ATCADevice atcab_get_device ( void  )

Get the global device object.

Returns
instance of global ATCADevice

◆ atcab_get_device_type()

ATCADeviceType atcab_get_device_type ( void  )

Get the current device type.

Returns
Device type if basic api is initialized or ATCA_DEV_UNKNOWN.

◆ atcab_get_pubkey()

ATCA_STATUS atcab_get_pubkey ( uint16_t  key_id,
uint8_t *  public_key 
)

Uses GenKey command to calculate the public key from an existing private key in a slot.

Parameters
[in]key_idSlot number of the private key.
[out]public_keyPublic key will be returned here. Format will be the X and Y integers in big-endian format. 64 bytes for P256 curve. Set to NULL if public key isn't required.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_get_zone_size()

ATCA_STATUS atcab_get_zone_size ( uint8_t  zone,
uint16_t  slot,
size_t *  size 
)

Gets the size of the specified zone in bytes.

Parameters
[in]zoneZone to get size information from. Config(0), OTP(1), or Data(2) which requires a slot.
[in]slotIf zone is Data(2), the slot to query for size.
[out]sizeZone size is returned here.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_hex2bin()

ATCA_STATUS atcab_hex2bin ( const char *  hex,
size_t  hex_size,
uint8_t *  bin,
size_t *  bin_size 
)

Function that converts a hex string to binary buffer.

Parameters
[in]hexInput buffer to convert
[in]hex_sizeLength of buffer to convert
[out]binBuffer that receives binary
[in,out]bin_sizeAs input, the size of the bin buffer. As output, the size of the bin data.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_hmac()

ATCA_STATUS atcab_hmac ( uint8_t  mode,
uint16_t  key_id,
uint8_t *  digest 
)

Issues a HMAC command, which computes an HMAC/SHA-256 digest of a key stored in the device, a challenge, and other information on the device.

Parameters
[in]modeControls which fields within the device are used in the message.
[in]key_idWhich key is to be used to generate the response. Bits 0:3 only are used to select a slot but all 16 bits are used in the HMAC message.
[out]digestHMAC digest is returned in this buffer (32 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_hw_sha2_256()

ATCA_STATUS atcab_hw_sha2_256 ( const uint8_t *  data,
size_t  data_size,
uint8_t *  digest 
)

Use the SHA command to compute a SHA-256 digest.

Parameters
[in]dataMessage data to be hashed.
[in]data_sizeSize of data in bytes.
[out]digestDigest is returned here (32 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_hw_sha2_256_finish()

ATCA_STATUS atcab_hw_sha2_256_finish ( atca_sha256_ctx_t ctx,
uint8_t *  digest 
)

Finish SHA-256 digest for a SHA context for performing a hardware SHA-256 operation on a device.

Parameters
[in]ctxSHA256 context
[out]digestSHA256 digest is returned here (32 bytes)
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_hw_sha2_256_init()

ATCA_STATUS atcab_hw_sha2_256_init ( atca_sha256_ctx_t ctx)

Initialize a SHA context for performing a hardware SHA-256 operation on a device. Note that only one SHA operation can be run at a time.

Parameters
[in]ctxSHA256 context
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_hw_sha2_256_update()

ATCA_STATUS atcab_hw_sha2_256_update ( atca_sha256_ctx_t ctx,
const uint8_t *  data,
size_t  data_size 
)

Add message data to a SHA context for performing a hardware SHA-256 operation on a device.

Parameters
[in]ctxSHA256 context
[in]dataMessage data to be added to hash.
[in]data_sizeSize of data in bytes.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_idle()

ATCA_STATUS atcab_idle ( void  )

idle the CryptoAuth device

Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_info()

ATCA_STATUS atcab_info ( uint8_t *  revision)

Use the Info command to get the device revision (DevRev).

Parameters
[out]revisionDevice revision is returned here (4 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_info_base()

ATCA_STATUS atcab_info_base ( uint8_t  mode,
uint16_t  param2,
uint8_t *  out_data 
)

Issues an Info command, which return internal device information and can control GPIO and the persistent latch.

Parameters
[in]modeSelects which mode to be used for info command.
[in]param2Selects the particular fields for the mode.
[out]out_dataResponse from info command (4 bytes). Can be set to NULL if not required.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_info_get_latch()

ATCA_STATUS atcab_info_get_latch ( bool *  state)

Use the Info command to get the persistent latch current state for an ATECC608A device.

Parameters
[out]stateThe state is returned here. Set (true) or Cler (false).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_info_set_latch()

ATCA_STATUS atcab_info_set_latch ( bool  state)

Use the Info command to set the persistent latch state for an ATECC608A device.

Parameters
[out]statePersistent latch state. Set (true) or clear (false).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_init()

ATCA_STATUS atcab_init ( ATCAIfaceCfg cfg)

Creates a global ATCADevice object used by Basic API.

Parameters
[in]cfgLogical interface configuration. Some predefined configurations can be found in atca_cfgs.h
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_init_device()

ATCA_STATUS atcab_init_device ( ATCADevice  ca_device)

Initialize the global ATCADevice object to point to one of your choosing for use with all the atcab_ basic API.

Parameters
[in]ca_deviceATCADevice instance to use as the global Basic API crypto device instance
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_is_locked()

ATCA_STATUS atcab_is_locked ( uint8_t  zone,
bool *  is_locked 
)

Executes Read command, which reads the configuration zone to see if the specified zone is locked.

Parameters
[in]zoneThe zone to query for locked (use LOCK_ZONE_CONFIG or LOCK_ZONE_DATA).
[out]is_lockedLock state returned here. True if locked.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_is_slot_locked()

ATCA_STATUS atcab_is_slot_locked ( uint16_t  slot,
bool *  is_locked 
)

Executes Read command, which reads the configuration zone to see if the specified slot is locked.

Parameters
[in]slotSlot to query for locked (slot 0-15)
[out]is_lockedLock state returned here. True if locked.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_kdf()

ATCA_STATUS atcab_kdf ( uint8_t  mode,
uint16_t  key_id,
const uint32_t  details,
const uint8_t *  message,
uint8_t *  out_data,
uint8_t *  out_nonce 
)

Executes the KDF command, which derives a new key in PRF, AES, or HKDF modes.

Generally this function combines a source key with an input string and creates a result key/digest/array.

Parameters
[in]modeMode determines KDF algorithm (PRF,AES,HKDF), source key location, and target key locations.
[in]key_idSource and target key slots if locations are in the EEPROM. Source key slot is the LSB and target key slot is the MSB.
[in]detailsFurther information about the computation, depending on the algorithm (4 bytes).
[in]messageInput value from system (up to 128 bytes). Actual size of message is 16 bytes for AES algorithm or is encoded in the MSB of the details parameter for other algorithms.
[out]out_dataOutput of the KDF function is returned here. If the result remains in the device, this can be NULL.
[out]out_nonceIf the output is encrypted, a 32 byte random nonce generated by the device is returned here. If output encryption is not used, this can be NULL.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_lock()

ATCA_STATUS atcab_lock ( uint8_t  mode,
uint16_t  summary_crc 
)

The Lock command prevents future modifications of the Configuration and/or Data and OTP zones. If the device is so configured, then this command can be used to lock individual data slots. This command fails if the designated area is already locked.

Parameters
[in]modeZone, and/or slot, and summary check (bit 7).
[in]summary_crcCRC of the config or data zones. Ignored for slot locks or when mode bit 7 is set.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_lock_config_zone()

ATCA_STATUS atcab_lock_config_zone ( void  )

Unconditionally (no CRC required) lock the config zone.

Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_lock_config_zone_crc()

ATCA_STATUS atcab_lock_config_zone_crc ( uint16_t  summary_crc)

Lock the config zone with summary CRC.

The CRC is calculated over the entire config zone contents. 88 bytes for ATSHA devices, 128 bytes for ATECC devices. Lock will fail if the provided CRC doesn't match the internally calculated one.

Parameters
[in]summary_crcExpected CRC over the config zone.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_lock_data_slot()

ATCA_STATUS atcab_lock_data_slot ( uint16_t  slot)

Lock an individual slot in the data zone on an ATECC device. Not available for ATSHA devices. Slot must be configured to be slot lockable (KeyConfig.Lockable=1).

Parameters
[in]slotSlot to be locked in data zone.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_lock_data_zone()

ATCA_STATUS atcab_lock_data_zone ( void  )

Unconditionally (no CRC required) lock the data zone (slots and OTP).

ConfigZone must be locked and DataZone must be unlocked for the zone to be successfully locked.

Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_lock_data_zone_crc()

ATCA_STATUS atcab_lock_data_zone_crc ( uint16_t  summary_crc)

Lock the data zone (slots and OTP) with summary CRC.

The CRC is calculated over the concatenated contents of all the slots and OTP at the end. Private keys (KeyConfig.Private=1) are skipped. Lock will fail if the provided CRC doesn't match the internally calculated one.

Parameters
[in]summary_crcExpected CRC over the data zone.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_mac()

ATCA_STATUS atcab_mac ( uint8_t  mode,
uint16_t  key_id,
const uint8_t *  challenge,
uint8_t *  digest 
)

Executes MAC command, which computes a SHA-256 digest of a key stored in the device, a challenge, and other information on the device.

Parameters
[in]modeControls which fields within the device are used in the message
[in]key_idKey in the CryptoAuth device to use for the MAC
[in]challengeChallenge message (32 bytes). May be NULL if mode indicates a challenge isn't required.
[out]digestMAC response is returned here (32 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_nonce()

ATCA_STATUS atcab_nonce ( const uint8_t *  num_in)

Execute a Nonce command in pass-through mode to initialize TempKey to a specified value.

Parameters
[in]num_inData to be loaded into TempKey (32 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_nonce_base()

ATCA_STATUS atcab_nonce_base ( uint8_t  mode,
uint16_t  zero,
const uint8_t *  num_in,
uint8_t *  rand_out 
)

Executes Nonce command, which loads a random or fixed nonce/data into the device for use by subsequent commands.

Parameters
[in]modeControls the mechanism of the internal RNG or fixed write.
[in]zeroParam2, normally 0, but can be used to indicate a nonce calculation mode (bit 15).
[in]num_inInput value to either be included in the nonce calculation in random modes (20 bytes) or to be written directly (32 bytes or 64 bytes(ATECC608A)) in pass-through mode.
[out]rand_outIf using a random mode, the internally generated 32-byte random number that was used in the nonce calculation is returned here. Can be NULL if not needed.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_nonce_load()

ATCA_STATUS atcab_nonce_load ( uint8_t  target,
const uint8_t *  num_in,
uint16_t  num_in_size 
)

Execute a Nonce command in pass-through mode to load one of the device's internal buffers with a fixed value.

For the ATECC608A, available targets are TempKey (32 or 64 bytes), Message Digest Buffer (32 or 64 bytes), or the Alternate Key Buffer (32 bytes). For all other devices, only TempKey (32 bytes) is available.

Parameters
[in]targetTarget device buffer to load. Can be NONCE_MODE_TARGET_TEMPKEY, NONCE_MODE_TARGET_MSGDIGBUF, or NONCE_MODE_TARGET_ALTKEYBUF.
[in]num_inData to load into the buffer.
[in]num_in_sizeSize of num_in in bytes. Can be 32 or 64 bytes depending on device and target.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_nonce_rand()

ATCA_STATUS atcab_nonce_rand ( const uint8_t *  num_in,
uint8_t *  rand_out 
)

Execute a Nonce command to generate a random nonce combining a host nonce (num_in) and a device random number.

Parameters
[in]num_inHost nonce to be combined with the device random number (20 bytes).
[out]rand_outInternally generated 32-byte random number that was used in the nonce/challenge calculation is returned here. Can be NULL if not needed.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_printbin()

ATCA_STATUS atcab_printbin ( uint8_t *  binary,
size_t  bin_len,
bool  add_space 
)

◆ atcab_printbin_label()

ATCA_STATUS atcab_printbin_label ( const char *  label,
uint8_t *  binary,
size_t  bin_len 
)

◆ atcab_printbin_sp()

ATCA_STATUS atcab_printbin_sp ( uint8_t *  binary,
size_t  bin_len 
)

◆ atcab_priv_write()

ATCA_STATUS atcab_priv_write ( uint16_t  key_id,
const uint8_t  priv_key[36],
uint16_t  write_key_id,
const uint8_t  write_key[32] 
)

Executes PrivWrite command, to write externally generated ECC private keys into the device.

Parameters
[in]key_idSlot to write the external private key into.
[in]priv_keyExternal private key (36 bytes) to be written. The first 4 bytes should be zero for P256 curve.
[in]write_key_idWrite key slot. Ignored if write_key is NULL.
[in]write_keyWrite key (32 bytes). If NULL, perform an unencrypted PrivWrite, which is only available when the data zone is unlocked.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_random()

ATCA_STATUS atcab_random ( uint8_t *  rand_out)

Executes Random command, which generates a 32 byte random number from the CryptoAuth device.

Parameters
[out]rand_out32 bytes of random data is returned here.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_read_bytes_zone()

ATCA_STATUS atcab_read_bytes_zone ( uint8_t  zone,
uint16_t  slot,
size_t  offset,
uint8_t *  data,
size_t  length 
)

Used to read an arbitrary number of bytes from any zone configured for clear reads.

This function will issue the Read command as many times as is required to read the requested data.

Parameters
[in]zoneZone to read data from. Option are ATCA_ZONE_CONFIG(0), ATCA_ZONE_OTP(1), or ATCA_ZONE_DATA(2).
[in]slotSlot number to read from if zone is ATCA_ZONE_DATA(2). Ignored for all other zones.
[in]offsetByte offset within the zone to read from.
[out]dataRead data is returned here.
[in]lengthNumber of bytes to read starting from the offset.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_read_config_zone()

ATCA_STATUS atcab_read_config_zone ( uint8_t *  config_data)

Executes Read command to read the complete device configuration zone.

Parameters
[out]config_dataConfiguration zone data is returned here. 88 bytes for ATSHA devices, 128 bytes for ATECC devices.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_read_enc()

ATCA_STATUS atcab_read_enc ( uint16_t  key_id,
uint8_t  block,
uint8_t *  data,
const uint8_t *  enc_key,
const uint16_t  enc_key_id 
)

Executes Read command on a slot configured for encrypted reads and decrypts the data to return it as plaintext.

Data zone must be locked for this command to succeed. Can only read 32 byte blocks.

Parameters
[in]key_idThe slot ID to read from.
[in]blockIndex of the 32 byte block within the slot to read.
[out]dataDecrypted (plaintext) data from the read is returned here (32 bytes).
[in]enc_key32 byte ReadKey for the slot being read.
[in]enc_key_idKeyID of the ReadKey being used.

returns ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_read_pubkey()

ATCA_STATUS atcab_read_pubkey ( uint16_t  slot,
uint8_t *  public_key 
)

Executes Read command to read an ECC P256 public key from a slot configured for clear reads.

This function assumes the public key is stored using the ECC public key format specified in the datasheet.

Parameters
[in]slotSlot number to read from. Only slots 8 to 15 are large enough for a public key.
[out]public_keyPublic key is returned here (64 bytes). Format will be the 32 byte X and Y big-endian integers concatenated.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_read_serial_number()

ATCA_STATUS atcab_read_serial_number ( uint8_t *  serial_number)

Executes Read command, which reads the 9 byte serial number of the device from the config zone.

Parameters
[out]serial_number9 byte serial number is returned here.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_read_sig()

ATCA_STATUS atcab_read_sig ( uint16_t  slot,
uint8_t *  sig 
)

Executes Read command to read a 64 byte ECDSA P256 signature from a slot configured for clear reads.

Parameters
[in]slotSlot number to read from. Only slots 8 to 15 are large enough for a signature.
[out]sigSignature will be returned here (64 bytes). Format will be the 32 byte R and S big-endian integers concatenated.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_read_zone()

ATCA_STATUS atcab_read_zone ( uint8_t  zone,
uint16_t  slot,
uint8_t  block,
uint8_t  offset,
uint8_t *  data,
uint8_t  len 
)

Executes Read command, which reads either 4 or 32 bytes of data from a given slot, configuration zone, or the OTP zone.

When reading a slot or OTP, data zone must be locked and the slot configuration must not be secret for a slot to be successfully read.

Parameters
[in]zoneZone to be read from device. Options are ATCA_ZONE_CONFIG, ATCA_ZONE_OTP, or ATCA_ZONE_DATA.
[in]slotSlot number for data zone and ignored for other zones.
[in]block32 byte block index within the zone.
[in]offset4 byte work index within the block. Ignored for 32 byte reads.
[out]dataRead data is returned here.
[in]lenLength of the data to be read. Must be either 4 or 32.

returns ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_release()

ATCA_STATUS atcab_release ( void  )

release (free) the global ATCADevice instance. This must be called in order to release or free up the interface.

Returns
Returns ATCA_SUCCESS .

◆ atcab_secureboot()

ATCA_STATUS atcab_secureboot ( uint8_t  mode,
uint16_t  param2,
const uint8_t *  digest,
const uint8_t *  signature,
uint8_t *  mac 
)

Executes Secure Boot command, which provides support for secure boot of an external MCU or MPU.

Parameters
[in]modeMode determines what operations the SecureBoot command performs.
[in]param2Not used, must be 0.
[in]digestDigest of the code to be verified (32 bytes).
[in]signatureSignature of the code to be verified (64 bytes). Can be NULL when using the FullStore mode.
[out]macValidating MAC will be returned here (32 bytes). Can be NULL if not required.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_secureboot_mac()

ATCA_STATUS atcab_secureboot_mac ( uint8_t  mode,
const uint8_t *  digest,
const uint8_t *  signature,
const uint8_t *  num_in,
const uint8_t *  io_key,
bool *  is_verified 
)

Executes Secure Boot command with encrypted digest and validated MAC response using the IO protection key.

Parameters
[in]modeMode determines what operations the SecureBoot command performs.
[in]digestDigest of the code to be verified (32 bytes). This is the plaintext digest (not encrypted).
[in]signatureSignature of the code to be verified (64 bytes). Can be NULL when using the FullStore mode.
[in]num_inHost nonce (20 bytes).
[in]io_keyIO protection key (32 bytes).
[out]is_verifiedVerify result is returned here.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_selftest()

ATCA_STATUS atcab_selftest ( uint8_t  mode,
uint16_t  param2,
uint8_t *  result 
)

Executes the SelfTest command, which performs a test of one or more of the cryptographic engines within the ATECC608A chip.

Parameters
[in]modeFunctions to test. Can be a bit field combining any of the following: SELFTEST_MODE_RNG, SELFTEST_MODE_ECDSA_VERIFY, SELFTEST_MODE_ECDSA_SIGN, SELFTEST_MODE_ECDH, SELFTEST_MODE_AES, SELFTEST_MODE_SHA, SELFTEST_MODE_ALL.
[in]param2Currently unused, should be 0.
[out]resultResults are returned here as a bit field.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha()

ATCA_STATUS atcab_sha ( uint16_t  length,
const uint8_t *  message,
uint8_t *  digest 
)

Use the SHA command to compute a SHA-256 digest.

Parameters
[in]lengthSize of message parameter in bytes.
[in]messageMessage data to be hashed.
[out]digestDigest is returned here (32 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_base()

ATCA_STATUS atcab_sha_base ( uint8_t  mode,
uint16_t  length,
const uint8_t *  message,
uint8_t *  data_out,
uint16_t *  data_out_size 
)

Executes SHA command, which computes a SHA-256 or HMAC/SHA-256 digest for general purpose use by the host system.

Only the Start(0) and Compute(1) modes are available for ATSHA devices.

Parameters
[in]modeSHA command mode Start(0), Update/Compute(1), End(2), Public(3), HMACstart(4), HMACend(5), Read_Context(6), or Write_Context(7). Also message digest target location for the ATECC608A.
[in]lengthNumber of bytes in the message parameter or KeySlot for the HMAC key if Mode is HMACstart(4) or Public(3).
[in]messageMessage bytes to be hashed or Write_Context if restoring a context on the ATECC608A. Can be NULL if not required by the mode.
[out]data_outData returned by the command (digest or context).
[in,out]data_out_sizeAs input, the size of the data_out buffer. As output, the number of bytes returned in data_out.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_end()

ATCA_STATUS atcab_sha_end ( uint8_t *  digest,
uint16_t  length,
const uint8_t *  message 
)

Executes SHA command to complete SHA-256 or HMAC/SHA-256 operation.

Parameters
[out]digestDigest from SHA-256 or HMAC/SHA-256 will be returned here (32 bytes).
[in]lengthLength of any remaining data to include in hash. Max 64 bytes.
[in]messageRemaining data to include in hash. NULL if length is 0.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_hmac()

ATCA_STATUS atcab_sha_hmac ( const uint8_t *  data,
size_t  data_size,
uint16_t  key_slot,
uint8_t *  digest,
uint8_t  target 
)

Use the SHA command to compute an HMAC/SHA-256 operation.

Parameters
[in]dataMessage data to be hashed.
[in]data_sizeSize of data in bytes.
[in]key_slotSlot key id to use for the HMAC calculation
[out]digestDigest is returned here (32 bytes).
[in]targetWhere to save the digest internal to the device. For ATECC608A, can be SHA_MODE_TARGET_TEMPKEY, SHA_MODE_TARGET_MSGDIGBUF, or SHA_MODE_TARGET_OUT_ONLY. For all other devices, SHA_MODE_TARGET_TEMPKEY is the only option.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_hmac_finish()

ATCA_STATUS atcab_sha_hmac_finish ( atca_hmac_sha256_ctx_t ctx,
uint8_t *  digest,
uint8_t  target 
)

Executes SHA command to complete a HMAC/SHA-256 operation.

Parameters
[in]ctxHMAC/SHA-256 context
[out]digestHMAC/SHA-256 result is returned here (32 bytes).
[in]targetWhere to save the digest internal to the device. For ATECC608A, can be SHA_MODE_TARGET_TEMPKEY, SHA_MODE_TARGET_MSGDIGBUF, or SHA_MODE_TARGET_OUT_ONLY. For all other devices, SHA_MODE_TARGET_TEMPKEY is the only option.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_hmac_init()

ATCA_STATUS atcab_sha_hmac_init ( atca_hmac_sha256_ctx_t ctx,
uint16_t  key_slot 
)

Executes SHA command to start an HMAC/SHA-256 operation.

Parameters
[in]ctxHMAC/SHA-256 context
[in]key_slotSlot key id to use for the HMAC calculation
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_hmac_update()

ATCA_STATUS atcab_sha_hmac_update ( atca_hmac_sha256_ctx_t ctx,
const uint8_t *  data,
size_t  data_size 
)

Executes SHA command to add an arbitrary amount of message data to a HMAC/SHA-256 operation.

Parameters
[in]ctxHMAC/SHA-256 context
[in]dataMessage data to add
[in]data_sizeSize of message data in bytes
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_read_context()

ATCA_STATUS atcab_sha_read_context ( uint8_t *  context,
uint16_t *  context_size 
)

Executes SHA command to read the SHA-256 context back. Only for ATECC608A with SHA-256 contexts. HMAC not supported.

Parameters
[out]contextContext data is returned here.
[in,out]context_sizeAs input, the size of the context buffer in bytes. As output, the size of the returned context data.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_start()

ATCA_STATUS atcab_sha_start ( void  )

Executes SHA command to initialize SHA-256 calculation engine.

Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_update()

ATCA_STATUS atcab_sha_update ( const uint8_t *  message)

Executes SHA command to add 64 bytes of message data to the current context.

Parameters
[in]message64 bytes of message data to add to add to operation.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sha_write_context()

ATCA_STATUS atcab_sha_write_context ( const uint8_t *  context,
uint16_t  context_size 
)

Executes SHA command to write (restore) a SHA-256 context into the the device. Only supported for ATECC608A with SHA-256 contexts.

Parameters
[in]contextContext data to be restored.
[in]context_sizeSize of the context data in bytes.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sign()

ATCA_STATUS atcab_sign ( uint16_t  key_id,
const uint8_t *  msg,
uint8_t *  signature 
)

Executes Sign command, to sign a 32-byte external message using the private key in the specified slot. The message to be signed will be loaded into the Message Digest Buffer to the ATECC608A device or TempKey for other devices.

Parameters
[in]key_idSlot of the private key to be used to sign the message.
[in]msg32-byte message to be signed. Typically the SHA256 hash of the full message.
[out]signatureSignature will be returned here. Format is R and S integers in big-endian format. 64 bytes for P256 curve.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sign_base()

ATCA_STATUS atcab_sign_base ( uint8_t  mode,
uint16_t  key_id,
uint8_t *  signature 
)

Executes the Sign command, which generates a signature using the ECDSA algorithm.

Parameters
[in]modeMode determines what the source of the message to be signed.
[in]key_idPrivate key slot used to sign the message.
[out]signatureSignature is returned here. Format is R and S integers in big-endian format. 64 bytes for P256 curve.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sign_internal()

ATCA_STATUS atcab_sign_internal ( uint16_t  key_id,
bool  is_invalidate,
bool  is_full_sn,
uint8_t *  signature 
)

Executes Sign command to sign an internally generated message.

Parameters
[in]key_idSlot of the private key to be used to sign the message.
[in]is_invalidateSet to true if the signature will be used with the Verify(Invalidate) command. false for all other cases.
[in]is_full_snSet to true if the message should incorporate the device's full serial number.
[out]signatureSignature is returned here. Format is R and S integers in big-endian format. 64 bytes for P256 curve.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_sleep()

ATCA_STATUS atcab_sleep ( void  )

invoke sleep on the CryptoAuth device

Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_updateextra()

ATCA_STATUS atcab_updateextra ( uint8_t  mode,
uint16_t  new_value 
)

Executes UpdateExtra command to update the values of the two extra bytes within the Configuration zone (bytes 84 and 85).

Can also be used to decrement the limited use counter associated with the key in slot NewValue.

Parameters
[in]modeMode determines what operations the UpdateExtra command performs.
[in]new_valueValue to be written.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_verify()

ATCA_STATUS atcab_verify ( uint8_t  mode,
uint16_t  key_id,
const uint8_t *  signature,
const uint8_t *  public_key,
const uint8_t *  other_data,
uint8_t *  mac 
)

Executes the Verify command, which takes an ECDSA [R,S] signature and verifies that it is correctly generated from a given message and public key. In all cases, the signature is an input to the command.

For the Stored, External, and ValidateExternal Modes, the contents of TempKey (or Message Digest Buffer in some cases for the ATECC608A) should contain the 32 byte message.

Parameters
[in]modeVerify command mode and options
[in]key_idStored mode, the slot containing the public key to be used for the verification. ValidateExternal mode, the slot containing the public key to be validated. External mode, KeyID contains the curve type to be used to Verify the signature. Validate or Invalidate mode, the slot containing the public key to be (in)validated.
[in]signatureSignature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]public_keyIf mode is External, the public key to be used for verification. X and Y integers in big-endian format. 64 bytes for P256 curve. NULL for all other modes.
[in]other_dataIf mode is Validate, the bytes used to generate the message for the validation (19 bytes). NULL for all other modes.
[out]macIf mode indicates a validating MAC, then the MAC will will be returned here. Can be NULL otherwise.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_verify_extern()

ATCA_STATUS atcab_verify_extern ( const uint8_t *  message,
const uint8_t *  signature,
const uint8_t *  public_key,
bool *  is_verified 
)

Executes the Verify command, which verifies a signature (ECDSA verify operation) with all components (message, signature, and public key) supplied. The message to be signed will be loaded into the Message Digest Buffer to the ATECC608A device or TempKey for other devices.

Parameters
[in]message32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]signatureSignature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]public_keyThe public key to be used for verification. X and Y integers in big-endian format. 64 bytes for P256 curve.
[out]is_verifiedBoolean whether or not the message, signature, public key verified.
Returns
ATCA_SUCCESS on verification success or failure, because the command still completed successfully.

◆ atcab_verify_extern_mac()

ATCA_STATUS atcab_verify_extern_mac ( const uint8_t *  message,
const uint8_t *  signature,
const uint8_t *  public_key,
const uint8_t *  num_in,
const uint8_t *  io_key,
bool *  is_verified 
)

Executes the Verify command with verification MAC, which verifies a signature (ECDSA verify operation) with all components (message, signature, and public key) supplied. This function is only available on the ATECC608A.

Parameters
[in]message32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]signatureSignature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]public_keyThe public key to be used for verification. X and Y integers in big-endian format. 64 bytes for P256 curve.
[in]num_inSystem nonce (32 byte) used for the verification MAC.
[in]io_keyIO protection key for verifying the validation MAC.
[out]is_verifiedBoolean whether or not the message, signature, public key verified.
Returns
ATCA_SUCCESS on verification success or failure, because the command still completed successfully.

◆ atcab_verify_invalidate()

ATCA_STATUS atcab_verify_invalidate ( uint16_t  key_id,
const uint8_t *  signature,
const uint8_t *  other_data,
bool *  is_verified 
)

Executes the Verify command in Invalidate mode which invalidates a previously validated public key stored in a slot.

This command can only be run after GenKey has been used to create a PubKey digest of the public key to be invalidated in TempKey (mode=0x10).

Parameters
[in]key_idSlot containing the public key to be invalidated.
[in]signatureSignature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]other_data19 bytes of data used to build the verification message.
[out]is_verifiedBoolean whether or not the message, signature, validation public key verified.
Returns
ATCA_SUCCESS on verification success or failure, because the command still completed successfully.

◆ atcab_verify_stored()

ATCA_STATUS atcab_verify_stored ( const uint8_t *  message,
const uint8_t *  signature,
uint16_t  key_id,
bool *  is_verified 
)

Executes the Verify command, which verifies a signature (ECDSA verify operation) with a public key stored in the device. The message to be signed will be loaded into the Message Digest Buffer to the ATECC608A device or TempKey for other devices.

Parameters
[in]message32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]signatureSignature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]key_idSlot containing the public key to be used in the verification.
[out]is_verifiedBoolean whether or not the message, signature, public key verified.
Returns
ATCA_SUCCESS on verification success or failure, because the command still completed successfully.

◆ atcab_verify_stored_mac()

ATCA_STATUS atcab_verify_stored_mac ( const uint8_t *  message,
const uint8_t *  signature,
uint16_t  key_id,
const uint8_t *  num_in,
const uint8_t *  io_key,
bool *  is_verified 
)

Executes the Verify command with verification MAC, which verifies a signature (ECDSA verify operation) with a public key stored in the device. This function is only available on the ATECC608A.

Parameters
[in]message32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]signatureSignature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]key_idSlot containing the public key to be used in the verification.
[in]num_inSystem nonce (32 byte) used for the verification MAC.
[in]io_keyIO protection key for verifying the validation MAC.
[out]is_verifiedBoolean whether or not the message, signature, public key verified.
Returns
ATCA_SUCCESS on verification success or failure, because the command still completed successfully.

◆ atcab_verify_validate()

ATCA_STATUS atcab_verify_validate ( uint16_t  key_id,
const uint8_t *  signature,
const uint8_t *  other_data,
bool *  is_verified 
)

Executes the Verify command in Validate mode to validate a public key stored in a slot.

This command can only be run after GenKey has been used to create a PubKey digest of the public key to be validated in TempKey (mode=0x10).

Parameters
[in]key_idSlot containing the public key to be validated.
[in]signatureSignature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]other_data19 bytes of data used to build the verification message.
[out]is_verifiedBoolean whether or not the message, signature, validation public key verified.
Returns
ATCA_SUCCESS on verification success or failure, because the command still completed successfully.

◆ atcab_version()

ATCA_STATUS atcab_version ( char *  ver_str)

basic API methods are all prefixed with atcab_ (CryptoAuthLib Basic) the fundamental premise of the basic API is it is based on a single interface instance and that instance is global, so all basic API commands assume that one global device is the one to operate on.

returns a version string for the CryptoAuthLib release. The format of the version string returned is "yyyymmdd"

Parameters
[out]ver_strptr to space to receive version string
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_wakeup()

ATCA_STATUS atcab_wakeup ( void  )

wakeup the CryptoAuth device

Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_write()

ATCA_STATUS atcab_write ( uint8_t  zone,
uint16_t  address,
const uint8_t *  value,
const uint8_t *  mac 
)

Executes the Write command, which writes either one four byte word or a 32-byte block to one of the EEPROM zones on the device. Depending upon the value of the WriteConfig byte for this slot, the data may be required to be encrypted by the system prior to being sent to the device. This command cannot be used to write slots configured as ECC private keys.

Parameters
[in]zoneZone/Param1 for the write command.
[in]addressAddress/Param2 for the write command.
[in]valuePlain-text data to be written or cipher-text for encrypted writes. 32 or 4 bytes depending on bit 7 in the zone.
[in]macMAC required for encrypted writes (32 bytes). Set to NULL if not required.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_write_bytes_zone()

ATCA_STATUS atcab_write_bytes_zone ( uint8_t  zone,
uint16_t  slot,
size_t  offset_bytes,
const uint8_t *  data,
size_t  length 
)

Executes the Write command, which writes data into the configuration, otp, or data zones with a given byte offset and length. Offset and length must be multiples of a word (4 bytes).

Config zone must be unlocked for writes to that zone. If data zone is unlocked, only 32-byte writes are allowed to slots and OTP and the offset and length must be multiples of 32 or the write will fail.

Parameters
[in]zoneZone to write data to: ATCA_ZONE_CONFIG(0), ATCA_ZONE_OTP(1), or ATCA_ZONE_DATA(2).
[in]slotIf zone is ATCA_ZONE_DATA(2), the slot number to write to. Ignored for all other zones.
[in]offset_bytesByte offset within the zone to write to. Must be a multiple of a word (4 bytes).
[in]dataData to be written.
[in]lengthNumber of bytes to be written. Must be a multiple of a word (4 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_write_config_counter()

ATCA_STATUS atcab_write_config_counter ( uint16_t  counter_id,
uint32_t  counter_value 
)

Initialize one of the monotonic counters in device with a specific value.

The monotonic counters are stored in the configuration zone using a special format. This encodes a binary count value into the 8 byte encoded value required. Can only be set while the configuration zone is unlocked.

Parameters
[in]counter_idCounter to be written.
[in]counter_valueCounter value to set.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_write_config_zone()

ATCA_STATUS atcab_write_config_zone ( const uint8_t *  config_data)

Executes the Write command, which writes the configuration zone.

First 16 bytes are skipped as they are not writable. LockValue and LockConfig are also skipped and can only be changed via the Lock command.

This command may fail if UserExtra and/or Selector bytes have already been set to non-zero values.

Parameters
[in]config_dataData to the config zone data. This should be 88 bytes for SHA devices and 128 bytes for ECC devices.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_write_enc()

ATCA_STATUS atcab_write_enc ( uint16_t  key_id,
uint8_t  block,
const uint8_t *  data,
const uint8_t *  enc_key,
const uint16_t  enc_key_id 
)

Executes the Write command, which performs an encrypted write of a 32 byte block into given slot.

The function takes clear text bytes and encrypts them for writing over the wire. Data zone must be locked and the slot configuration must be set to encrypted write for the block to be successfully written.

Parameters
[in]key_idSlot ID to write to.
[in]blockIndex of the 32 byte block to write in the slot.
[in]data32 bytes of clear text data to be written to the slot
[in]enc_keyWriteKey to encrypt with for writing
[in]enc_key_idThe KeyID of the WriteKey

returns ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_write_pubkey()

ATCA_STATUS atcab_write_pubkey ( uint16_t  slot,
const uint8_t *  public_key 
)

Executes the Write command, which writes a public key to a data slot in the device format.

Parameters
[in]slotSlot number to write. Only slots 8 to 15 are large enough to store a public key.
[in]public_keyPublic key to write into the slot specified. X and Y integers in big-endian format. 64 bytes for P256 curve.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_write_zone()

ATCA_STATUS atcab_write_zone ( uint8_t  zone,
uint16_t  slot,
uint8_t  block,
uint8_t  offset,
const uint8_t *  data,
uint8_t  len 
)

Executes the Write command, which writes either 4 or 32 bytes of data into a device zone.

Parameters
[in]zoneDevice zone to write to (0=config, 1=OTP, 2=data).
[in]slotIf writing to the data zone, it is the slot to write to, otherwise it should be 0.
[in]block32-byte block to write to.
[in]offset4-byte word within the specified block to write to. If performing a 32-byte write, this should be 0.
[in]dataData to be written.
[in]lenNumber of bytes to be written. Must be either 4 or 32.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ base64Char()

char base64Char ( uint8_t  id,
const uint8_t *  rules 
)

Returns the base 64 character of the given index.

Parameters
[in]idindex to check
[in]rulesbase64 ruleset to use
Returns
the base 64 character of the given index

◆ base64Index()

uint8_t base64Index ( char  c,
const uint8_t *  rules 
)

Returns the base 64 index of the given character.

Parameters
[in]ccharacter to check
[in]rulesbase64 ruleset to use
Returns
the base 64 index of the given character

◆ isAlpha()

bool isAlpha ( char  c)

Checks to see if a character is an ASCII representation of hex ((c >= 'A') and (c <= 'F')) || ((c >= 'a') and (c <= 'f'))

Parameters
[in]ccharacter to check
Returns
True if the character is a hex

◆ isBase64()

bool isBase64 ( char  c,
const uint8_t *  rules 
)

Returns true if this character is a valid base 64 character or if this is whitespace (A character can be included in a valid base 64 string).

Parameters
[in]ccharacter to check
[in]rulesbase64 ruleset to use
Returns
True if the character can be included in a valid base 64 string

◆ isBase64Digit()

bool isBase64Digit ( char  c,
const uint8_t *  rules 
)

Returns true if this character is a valid base 64 character.

Parameters
[in]ccharacter to check
[in]rulesbase64 ruleset to use
Returns
True if the character can be included in a valid base 64 string

◆ isDigit()

bool isDigit ( char  c)

Checks to see if a character is an ASCII representation of a digit ((c ge '0') and (c le '9'))

Parameters
[in]ccharacter to check
Returns
True if the character is a digit

◆ isHex()

bool isHex ( char  c)

Returns true if this character is a valid hex character or if this is whitespace (The character can be included in a valid hexstring).

Parameters
[in]ccharacter to check
Returns
True if the character can be included in a valid hexstring

◆ isHexAlpha()

bool isHexAlpha ( char  c)

Checks to see if a character is an ASCII representation of hex ((c >= 'A') and (c <= 'F')) || ((c >= 'a') and (c <= 'f'))

Parameters
[in]ccharacter to check
Returns
True if the character is a hex

◆ isHexDigit()

bool isHexDigit ( char  c)

Returns true if this character is a valid hex character.

Parameters
[in]ccharacter to check
Returns
True if the character can be included in a valid hexstring

◆ isWhiteSpace()

bool isWhiteSpace ( char  c)

Checks to see if a character is whitespace.

Parameters
[in]ccharacter to check
Returns
True if the character is whitespace

◆ packHex()

ATCA_STATUS packHex ( const char *  ascii_hex,
size_t  ascii_hex_len,
char *  packed_hex,
size_t *  packed_len 
)

Remove white space from a ASCII hex string.

Parameters
[in]ascii_hexInitial hex string to remove white space from
[in]ascii_hex_lenLength of the initial hex string
[in]packed_hexResulting hex string without white space
[in,out]packed_lenIn: Size to packed_hex buffer Out: Number of bytes in the packed hex string
Returns
ATCA_SUCCESS on success, otherwise an error code.

Variable Documentation

◆ _gDevice

ATCADevice _gDevice

◆ atcab_b64rules_default

uint8_t atcab_b64rules_default[4]

◆ atcab_b64rules_mime

uint8_t atcab_b64rules_mime[4]

◆ atcab_b64rules_urlsafe

uint8_t atcab_b64rules_urlsafe[4]