Basic Crypto API methods (atcab_)

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

Macros
#define	atcab_get_addr(...)   calib_get_addr(__VA_ARGS__)
#define	atca_execute_command(...)   calib_execute_command(__VA_ARGS__)
#define	SHA_CONTEXT_MAX_SIZE   (109)

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.
ATCA_STATUS	atcab_init_ext (ATCADevice *device, ATCAIfaceCfg *cfg)
	Creates and initializes a ATCADevice context.
ATCA_STATUS	atcab_init (ATCAIfaceCfg *cfg)
	Creates a global ATCADevice object used by Basic API.
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.
ATCA_STATUS	atcab_release_ext (ATCADevice *device)
	release (free) the an ATCADevice instance.
ATCA_STATUS	atcab_release (void)
	release (free) the global ATCADevice instance. This must be called in order to release or free up the interface.
ATCADevice	atcab_get_device (void)
	Get the global device object.
ATCADeviceType	atcab_get_device_type_ext (ATCADevice device)
	Get the selected device type of rthe device context.
ATCADeviceType	atcab_get_device_type (void)
	Get the current device type configured for the global ATCADevice.
uint8_t	atcab_get_device_address (ATCADevice device)
	Get the current device address based on the configured device and interface.
bool	atcab_is_ca_device (ATCADeviceType dev_type)
	Check whether the device is cryptoauth device.
bool	atcab_is_ca2_device (ATCADeviceType dev_type)
	Check whether the device is cryptoauth device.
bool	atcab_is_ta_device (ATCADeviceType dev_type)
	Check whether the device is Trust Anchor device.
ATCA_STATUS	atcab_pbkdf2_sha256_ext (ATCADevice device, const uint32_t iter, const uint16_t slot, const uint8_t *salt, const size_t salt_len, uint8_t *result, size_t result_len)
ATCA_STATUS	atcab_pbkdf2_sha256 (const uint32_t iter, const uint16_t slot, const uint8_t *salt, const size_t salt_len, uint8_t *result, size_t result_len)
ATCA_STATUS	atcab_wakeup (void)
	wakeup the CryptoAuth device
ATCA_STATUS	atcab_idle (void)
	idle the CryptoAuth device
ATCA_STATUS	atcab_sleep (void)
	invoke sleep on the CryptoAuth device
ATCA_STATUS	atcab_get_zone_size (uint8_t zone, uint16_t slot, size_t *size)
	Gets the size of the specified zone in bytes.
ATCA_STATUS	atcab_get_zone_size_ext (ATCADevice device, uint8_t zone, uint16_t slot, size_t *size)
	Gets the size of the specified zone in bytes.
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.
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.
ATCA_STATUS	atcab_aes_encrypt_ext (ATCADevice device, 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.
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.
ATCA_STATUS	atcab_aes_decrypt_ext (ATCADevice device, 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.
ATCA_STATUS	atcab_aes_gfm (const uint8_t *h, const uint8_t *input, uint8_t *output)
	Perform a Galois Field Multiply (GFM) operation.
ATCA_STATUS	atcab_aes_gcm_init (atca_aes_gcm_ctx_t *ctx, uint16_t key_id, uint8_t key_block, const uint8_t *iv, size_t iv_size)
	Initialize context for AES GCM operation with an existing IV, which is common when starting a decrypt operation.
ATCA_STATUS	atcab_aes_gcm_init_ext (ATCADevice device, atca_aes_gcm_ctx_t *ctx, uint16_t key_id, uint8_t key_block, const uint8_t *iv, size_t iv_size)
	Initialize context for AES GCM operation with an existing IV, which is common when starting a decrypt operation.
ATCA_STATUS	atcab_aes_gcm_init_rand (atca_aes_gcm_ctx_t *ctx, uint16_t key_id, uint8_t key_block, size_t rand_size, const uint8_t *free_field, size_t free_field_size, uint8_t *iv)
	Initialize context for AES GCM operation with a IV composed of a random and optional fixed(free) field, which is common when starting an encrypt operation.
ATCA_STATUS	atcab_aes_gcm_aad_update (atca_aes_gcm_ctx_t *ctx, const uint8_t *aad, uint32_t aad_size)
	Process Additional Authenticated Data (AAD) using GCM mode and a key within the ATECC608 device.
ATCA_STATUS	atcab_aes_gcm_aad_update_ext (ATCADevice device, atca_aes_gcm_ctx_t *ctx, const uint8_t *aad, uint32_t aad_size)
	Process Additional Authenticated Data (AAD) using GCM mode and a key within the ATECC608 device.
ATCA_STATUS	atcab_aes_gcm_encrypt_update (atca_aes_gcm_ctx_t *ctx, const uint8_t *plaintext, uint32_t plaintext_size, uint8_t *ciphertext)
	Encrypt data using GCM mode and a key within the ATECC608 device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.
ATCA_STATUS	atcab_aes_gcm_encrypt_update_ext (ATCADevice device, atca_aes_gcm_ctx_t *ctx, const uint8_t *plaintext, uint32_t plaintext_size, uint8_t *ciphertext)
	Encrypt data using GCM mode and a key within the ATECC608 device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.
ATCA_STATUS	atcab_aes_gcm_encrypt_finish (atca_aes_gcm_ctx_t *ctx, uint8_t *tag, size_t tag_size)
	Complete a GCM encrypt operation returning the authentication tag.
ATCA_STATUS	atcab_aes_gcm_encrypt_finish_ext (ATCADevice device, atca_aes_gcm_ctx_t *ctx, uint8_t *tag, size_t tag_size)
	Complete a GCM encrypt operation returning the authentication tag.
ATCA_STATUS	atcab_aes_gcm_decrypt_update (atca_aes_gcm_ctx_t *ctx, const uint8_t *ciphertext, uint32_t ciphertext_size, uint8_t *plaintext)
	Decrypt data using GCM mode and a key within the ATECC608 device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.
ATCA_STATUS	atcab_aes_gcm_decrypt_update_ext (ATCADevice device, atca_aes_gcm_ctx_t *ctx, const uint8_t *ciphertext, uint32_t ciphertext_size, uint8_t *plaintext)
	Decrypt data using GCM mode and a key within the ATECC608 device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.
ATCA_STATUS	atcab_aes_gcm_decrypt_finish (atca_aes_gcm_ctx_t *ctx, const uint8_t *tag, size_t tag_size, bool *is_verified)
	Complete a GCM decrypt operation verifying the authentication tag.
ATCA_STATUS	atcab_aes_gcm_decrypt_finish_ext (ATCADevice device, atca_aes_gcm_ctx_t *ctx, const uint8_t *tag, size_t tag_size, bool *is_verified)
	Complete a GCM decrypt operation verifying the authentication tag.
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.
ATCA_STATUS	atcab_checkmac_with_response_mac (uint8_t mode, const uint8_t *challenge, const uint8_t *response, const uint8_t *other_data, uint8_t *mac)
	Compares a MAC response with input values.SHA105 device can generate optional mac Output response mac mode only supports in SHA105 device.
ATCA_STATUS	atcab_counter (uint8_t mode, uint16_t counter_id, uint32_t *counter_value)
	Compute the Counter functions.
ATCA_STATUS	atcab_counter_increment (uint16_t counter_id, uint32_t *counter_value)
	Increments one of the device's monotonic counters.
ATCA_STATUS	atcab_counter_read (uint16_t counter_id, uint32_t *counter_value)
	Read one of the device's monotonic counters.
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.
ATCA_STATUS	atcab_derivekey_ext (ATCADevice device, 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.
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.
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.
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, const uint8_t num_in[(20)])
	ECDH command with a private key in a slot and the premaster secret is read from the next slot.
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.
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.
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.
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.
ATCA_STATUS	atcab_gendivkey (const uint8_t *other_data)
	Issues a GenDivKey command to generate the equivalent diversified key as that programmed into the client side device.
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.
ATCA_STATUS	atcab_genkey (uint16_t key_id, uint8_t *public_key)
	Issues GenKey command, which generates a new random private key in slot/handle and returns the public key.
ATCA_STATUS	atcab_genkey_ext (ATCADevice device, uint16_t key_id, uint8_t *public_key)
	Issues GenKey command, which generates a new random private key in slot/handle and returns the public key.
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.
ATCA_STATUS	atcab_get_pubkey_ext (ATCADevice device, uint16_t key_id, uint8_t *public_key)
	Uses GenKey command to calculate the public key from an existing private key in a slot.
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.
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.
ATCA_STATUS	atcab_info (uint8_t *revision)
	Use the Info command to get the device revision (DevRev).
ATCA_STATUS	atcab_info_ext (ATCADevice device, uint8_t *revision)
	Use the Info command to get the device revision (DevRev).
ATCA_STATUS	atcab_info_lock_status (uint16_t param2, uint8_t *is_locked)
	Use the Info command to get the lock status.
ATCA_STATUS	atcab_info_chip_status (uint8_t *chip_status)
	Use the Info command to get the chip status.
ATCA_STATUS	atcab_info_set_latch (bool state)
	Use the Info command to set the persistent latch state for an ATECC608 device.
ATCA_STATUS	atcab_info_get_latch (bool *state)
	Use the Info command to get the persistent latch current state for an ATECC608 device.
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.
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.
ATCA_STATUS	atcab_lock_config_zone (void)
	Unconditionally (no CRC required) lock the config zone.
ATCA_STATUS	atcab_lock_config_zone_ext (ATCADevice device)
	Unconditionally (no CRC required) lock the config zone.
ATCA_STATUS	atcab_lock_config_zone_crc (uint16_t summary_crc)
	Lock the config zone with summary CRC.
ATCA_STATUS	atcab_lock_data_zone (void)
	Unconditionally (no CRC required) lock the data zone (slots and OTP). for CryptoAuth devices and lock the setup for Trust Anchor device.
ATCA_STATUS	atcab_lock_data_zone_ext (ATCADevice device)
	Unconditionally (no CRC required) lock the data zone (slots and OTP). for CryptoAuth devices and lock the setup for Trust Anchor device.
ATCA_STATUS	atcab_lock_data_zone_crc (uint16_t summary_crc)
	Lock the data zone (slots and OTP) with summary CRC.
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) (for cryptoauth devices) or Lock an individual handle in shared data element on an Trust Anchor device (for Trust Anchor devices).
ATCA_STATUS	atcab_lock_data_slot_ext (ATCADevice device, 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) (for cryptoauth devices) or Lock an individual handle in shared data element on an Trust Anchor device (for Trust Anchor devices).
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.
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.
ATCA_STATUS	atcab_nonce (const uint8_t *num_in)
	Execute a Nonce command in pass-through mode to initialize TempKey to a specified value.
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.
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.
ATCA_STATUS	atcab_nonce_rand_ext (ATCADevice device, 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.
ATCA_STATUS	atcab_challenge (const uint8_t *num_in)
	Execute a Nonce command in pass-through mode to initialize TempKey to a specified value.
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.
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], const uint8_t num_in[(20)])
	Executes PrivWrite command, to write externally generated ECC private keys into the device.
ATCA_STATUS	atcab_random (uint8_t *rand_out)
	Executes Random command, which generates a 32 byte random number from the device.
ATCA_STATUS	atcab_random_ext (ATCADevice device, uint8_t *rand_out)
	Executes Random command, which generates a 32 byte random number from the device.
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.
ATCA_STATUS	atcab_read_zone_ext (ATCADevice device, 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.
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.
ATCA_STATUS	atcab_is_config_locked (bool *is_locked)
	This function check whether configuration zone is locked or not.
ATCA_STATUS	atcab_is_config_locked_ext (ATCADevice device, bool *is_locked)
	This function check whether configuration zone is locked or not.
ATCA_STATUS	atcab_is_data_locked (bool *is_locked)
	This function check whether data/setup zone is locked or not.
ATCA_STATUS	atcab_is_data_locked_ext (ATCADevice device, bool *is_locked)
	This function check whether data/setup zone is locked or not.
ATCA_STATUS	atcab_is_slot_locked (uint16_t slot, bool *is_locked)
	This function check whether slot/handle is locked or not.
ATCA_STATUS	atcab_is_slot_locked_ext (ATCADevice device, uint16_t slot, bool *is_locked)
	This function check whether slot/handle is locked or not.
ATCA_STATUS	atcab_is_private_ext (ATCADevice device, uint16_t slot, bool *is_private)
	Check to see if the key is a private key or not.
ATCA_STATUS	atcab_is_private (uint16_t slot, bool *is_private)
ATCA_STATUS	atcab_read_bytes_zone_ext (ATCADevice device, uint8_t zone, uint16_t slot, size_t offset, uint8_t *data, size_t length)
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.
ATCA_STATUS	atcab_read_serial_number (uint8_t *serial_number)
	This function returns serial number of the device.
ATCA_STATUS	atcab_read_serial_number_ext (ATCADevice device, uint8_t *serial_number)
	This function returns serial number of the device.
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.
ATCA_STATUS	atcab_read_pubkey_ext (ATCADevice device, uint16_t slot, uint8_t *public_key)
	Executes Read command to read an ECC P256 public key from a slot configured for clear reads.
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.
ATCA_STATUS	atcab_read_config_zone (uint8_t *config_data)
	Executes Read command to read the complete device configuration zone.
ATCA_STATUS	atcab_read_config_zone_ext (ATCADevice device, uint8_t *config_data)
	Executes Read command to read the complete device configuration 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.
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, const uint8_t num_in[(20)])
	Executes Read command on a slot configured for encrypted reads and decrypts the data to return it as plaintext.
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.
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.
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 ATECC608 chip.
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.
ATCA_STATUS	atcab_sha_start (void)
	Executes SHA command to initialize SHA-256 calculation engine.
ATCA_STATUS	atcab_sha_update (const uint8_t *message)
	Executes SHA command to add 64 bytes of message data to the current context.
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.
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 ATECC608 with SHA-256 contexts. HMAC not supported.
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 ATECC608 with SHA-256 contexts.
ATCA_STATUS	atcab_sha (uint16_t length, const uint8_t *message, uint8_t *digest)
	Use the SHA command to compute a SHA-256 digest.
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.
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.
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.
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.
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.
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.
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.
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.
ATCA_STATUS	atcab_sha_hmac_ext (ATCADevice device, 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.
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.
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 ATECC608 device or TempKey for other devices.
ATCA_STATUS	atcab_sign_ext (ATCADevice device, 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 ATECC608 device or TempKey for other devices.
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.
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).
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.
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 ATECC608 device or TempKey for other devices.
ATCA_STATUS	atcab_verify_extern_ext (ATCADevice device, 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 ATECC608 device or TempKey for other devices.
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 ATECC608.
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 ATECC608 device or TempKey for other devices.
ATCA_STATUS	atcab_verify_stored_ext (ATCADevice device, 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 ATECC608 device or TempKey for other devices.
ATCA_STATUS	atcab_verify_stored_with_tempkey (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. keyConfig.reqrandom bit should be set and the message to be signed should be already loaded into TempKey for all devices.
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 ATECC608.
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.
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.
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.
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.
ATCA_STATUS	atcab_write_zone_ext (ATCADevice device, 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.
ATCA_STATUS	atcab_write_bytes_zone_ext (ATCADevice device, uint8_t zone, uint16_t slot, size_t offset_bytes, const uint8_t *data, size_t length)
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).
ATCA_STATUS	atcab_write_pubkey (uint16_t slot, const uint8_t *public_key)
	Uses the write command to write a public key to a slot in the proper format.
ATCA_STATUS	atcab_write_pubkey_ext (ATCADevice device, uint16_t slot, const uint8_t *public_key)
	Uses the write command to write a public key to a slot in the proper format.
ATCA_STATUS	atcab_write_config_zone (const uint8_t *config_data)
	Executes the Write command, which writes the configuration zone.
ATCA_STATUS	atcab_write_config_zone_ext (ATCADevice device, const uint8_t *config_data)
	Executes the Write command, which writes the configuration zone.
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, const uint8_t num_in[(20)])
	Executes the Write command, which performs an encrypted write of a 32 byte block into given slot.
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.

Variables
ATCADevice	g_atcab_device_ptr
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.
ATCA_STATUS	atcab_bin2hex_ (const uint8_t *bin, size_t bin_size, char *hex, size_t *hex_size, bool is_pretty, bool is_space, bool is_upper)
	Function that converts a binary buffer to a hex string suitable for easy reading.
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.
ATCA_STATUS	atcab_hex2bin_ (const char *hex, size_t hex_size, uint8_t *bin, size_t *bin_size, bool is_space)
ATCA_STATUS	packHex (const char *ascii_hex, size_t ascii_hex_len, char *packed_hex, size_t *packed_len)
	Remove spaces from a ASCII hex string.
bool	isDigit (char c)
	Checks to see if a character is an ASCII representation of a digit ((c ge '0') and (c le '9'))
bool	isBlankSpace (char c)
	Checks to see if a character is blank space.
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'))
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'))
bool	isHex (char c)
	Returns true if this character is a valid hex character or if this is blankspace (The character can be included in a valid hexstring).
bool	isHexDigit (char c)
	Returns true if this character is a valid hex character.
bool	isBase64 (char c, const uint8_t *rules)
	Returns true if this character is a valid base 64 character or if this is space (A character can be included in a valid base 64 string).
bool	isBase64Digit (char c, const uint8_t *rules)
	Returns true if this character is a valid base 64 character.
const uint8_t *	atcab_b64rules_default (void)
const uint8_t *	atcab_b64rules_mime (void)
const uint8_t *	atcab_b64rules_urlsafe (void)
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.
ATCA_STATUS	atcab_base64encode (const uint8_t *byte_array, size_t array_len, char *encoded, size_t *encoded_len)
	Encode data as base64 string.
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.
ATCA_STATUS	atcab_base64decode (const char *encoded, size_t encoded_len, uint8_t *byte_array, size_t *array_len)
	Decode base64 string to data.
ATCA_STATUS	atcab_reversal (const uint8_t *bin, size_t bin_size, uint8_t *dest, size_t *dest_size)
	To reverse the input data.
int	atcab_memset_s (void *dest, size_t destsz, int ch, size_t count)
	Guaranteed to perform memory writes regardless of optimization level. Matches memset_s signature.
size_t	atcab_pointer_delta (const void *start, const void *end)
	Helper function to calculate the number of bytes between two pointers.
char	lib_toupper (char c)
	Converts a character to uppercase.
char	lib_tolower (char c)
	Converts a character to lowercase.
#define	IS_ADD_SAFE_UINT16_T(a, b)   (((UINT16_MAX - (a)) >= (b)) ? true : false)
#define	IS_ADD_SAFE_UINT32_T(a, b)   (((UINT32_MAX - (a)) >= (b)) ? true : false)
#define	IS_ADD_SAFE_UINT64_T(a, b)   (((UINT64_MAX - (a)) >= (b)) ? true : false)
#define	IS_ADD_SAFE_SIZE_T(a, b)   (((SIZE_MAX - (a)) >= (b)) ? true : false)
#define	IS_MUL_SAFE_UINT16_T(a, b)   ((((a) <= UINT16_MAX / (b))) ? true : false)
#define	IS_MUL_SAFE_UINT32_T(a, b)   ((((a) <= UINT32_MAX / (b))) ? true : false)
#define	IS_MUL_SAFE_UINT64_T(a, b)   ((((a) <= UINT64_MAX / (b))) ? true : false)
#define	IS_MUL_SAFE_SIZE_T(a, b)   ((((a) <= SIZE_MAX / (b))) ? true : false)

Detailed Description

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

Function Documentation

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]	mode	The mode for the AES command.
[in]	key_id	Key location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]	aes_in	Input data to the AES command (16 bytes).
[out]	aes_out	Output data from the AES command 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_id	Key location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]	key_block	Index of the 16-byte block to use within the key location for the actual key.
[in]	ciphertext	Input ciphertext to be decrypted (16 bytes).
[out]	plaintext	Output plaintext is returned here (16 bytes).

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_decrypt_ext()

ATCA_STATUS atcab_aes_decrypt_ext	(	ATCADevice	device,
		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]	device	Device context pointer
[in]	key_id	Key location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]	key_block	Index of the 16-byte block to use within the key location for the actual key.
[in]	ciphertext	Input ciphertext to be decrypted (16 bytes).
[out]	plaintext	Output 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_id	Key location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]	key_block	Index of the 16-byte block to use within the key location for the actual key.
[in]	plaintext	Input plaintext to be encrypted (16 bytes).
[out]	ciphertext	Output ciphertext is returned here (16 bytes).

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_encrypt_ext()

ATCA_STATUS atcab_aes_encrypt_ext	(	ATCADevice	device,
		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]	device	Device context pointer
[in]	key_id	Key location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]	key_block	Index of the 16-byte block to use within the key location for the actual key.
[in]	plaintext	Input plaintext to be encrypted (16 bytes).
[out]	ciphertext	Output ciphertext is returned here (16 bytes).

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_aad_update()

ATCA_STATUS atcab_aes_gcm_aad_update	(	atca_aes_gcm_ctx_t *	ctx,
		const uint8_t *	aad,
		uint32_t	aad_size
	)

Process Additional Authenticated Data (AAD) using GCM mode and a key within the ATECC608 device.

This can be called multiple times. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function. When there is AAD to include, this should be called before atcab_aes_gcm_encrypt_update() or atcab_aes_gcm_decrypt_update().

Parameters

[in]	ctx	AES GCM context
[in]	aad	Additional authenticated data to be added
[in]	aad_size	Size of aad in bytes

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_aad_update_ext()

ATCA_STATUS atcab_aes_gcm_aad_update_ext	(	ATCADevice	device,
		atca_aes_gcm_ctx_t *	ctx,
		const uint8_t *	aad,
		uint32_t	aad_size
	)

Process Additional Authenticated Data (AAD) using GCM mode and a key within the ATECC608 device.

This can be called multiple times. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function. When there is AAD to include, this should be called before atcab_aes_gcm_encrypt_update() or atcab_aes_gcm_decrypt_update().

Parameters

[in]	device	Device context
[in]	ctx	AES GCM context
[in]	aad	Additional authenticated data to be added
[in]	aad_size	Size of aad in bytes

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_decrypt_finish()

ATCA_STATUS atcab_aes_gcm_decrypt_finish	(	atca_aes_gcm_ctx_t *	ctx,
		const uint8_t *	tag,
		size_t	tag_size,
		bool *	is_verified
	)

Complete a GCM decrypt operation verifying the authentication tag.

Parameters

[in]	ctx	AES GCM context structure.
[in]	tag	Expected authentication tag.
[in]	tag_size	Size of tag in bytes (12 to 16 bytes).
[out]	is_verified	Returns whether or not the tag verified.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_decrypt_finish_ext()

ATCA_STATUS atcab_aes_gcm_decrypt_finish_ext	(	ATCADevice	device,
		atca_aes_gcm_ctx_t *	ctx,
		const uint8_t *	tag,
		size_t	tag_size,
		bool *	is_verified
	)

Complete a GCM decrypt operation verifying the authentication tag.

Parameters

[in]	device	Device context
[in]	ctx	AES GCM context structure.
[in]	tag	Expected authentication tag.
[in]	tag_size	Size of tag in bytes (12 to 16 bytes).
[out]	is_verified	Returns whether or not the tag verified.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_decrypt_update()

ATCA_STATUS atcab_aes_gcm_decrypt_update	(	atca_aes_gcm_ctx_t *	ctx,
		const uint8_t *	ciphertext,
		uint32_t	ciphertext_size,
		uint8_t *	plaintext
	)

Decrypt data using GCM mode and a key within the ATECC608 device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.

Parameters

[in]	ctx	AES GCM context structure.
[in]	ciphertext	Ciphertext to be decrypted.
[in]	ciphertext_size	Size of ciphertext in bytes.
[out]	plaintext	Decrypted data is returned here.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_decrypt_update_ext()

ATCA_STATUS atcab_aes_gcm_decrypt_update_ext	(	ATCADevice	device,
		atca_aes_gcm_ctx_t *	ctx,
		const uint8_t *	ciphertext,
		uint32_t	ciphertext_size,
		uint8_t *	plaintext
	)

Decrypt data using GCM mode and a key within the ATECC608 device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.

Parameters

[in]	device	Device context
[in]	ctx	AES GCM context structure.
[in]	ciphertext	Ciphertext to be decrypted.
[in]	ciphertext_size	Size of ciphertext in bytes.
[out]	plaintext	Decrypted data is returned here.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_encrypt_finish()

ATCA_STATUS atcab_aes_gcm_encrypt_finish	(	atca_aes_gcm_ctx_t *	ctx,
		uint8_t *	tag,
		size_t	tag_size
	)

Complete a GCM encrypt operation returning the authentication tag.

Parameters

[in]	ctx	AES GCM context structure.
[out]	tag	Authentication tag is returned here.
[in]	tag_size	Tag size in bytes (12 to 16 bytes).

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_encrypt_finish_ext()

ATCA_STATUS atcab_aes_gcm_encrypt_finish_ext	(	ATCADevice	device,
		atca_aes_gcm_ctx_t *	ctx,
		uint8_t *	tag,
		size_t	tag_size
	)

Complete a GCM encrypt operation returning the authentication tag.

Parameters

[in]	device	Device context
[in]	ctx	AES GCM context structure.
[out]	tag	Authentication tag is returned here.
[in]	tag_size	Tag size in bytes (12 to 16 bytes).

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_encrypt_update()

ATCA_STATUS atcab_aes_gcm_encrypt_update	(	atca_aes_gcm_ctx_t *	ctx,
		const uint8_t *	plaintext,
		uint32_t	plaintext_size,
		uint8_t *	ciphertext
	)

Encrypt data using GCM mode and a key within the ATECC608 device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.

Parameters

[in]	ctx	AES GCM context structure.
[in]	plaintext	Plaintext to be encrypted (16 bytes).
[in]	plaintext_size	Size of plaintext in bytes.
[out]	ciphertext	Encrypted data is returned here.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_encrypt_update_ext()

ATCA_STATUS atcab_aes_gcm_encrypt_update_ext	(	ATCADevice	device,
		atca_aes_gcm_ctx_t *	ctx,
		const uint8_t *	plaintext,
		uint32_t	plaintext_size,
		uint8_t *	ciphertext
	)

Encrypt data using GCM mode and a key within the ATECC608 device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.

Parameters

[in]	device	Device context
[in]	ctx	AES GCM context structure.
[in]	plaintext	Plaintext to be encrypted (16 bytes).
[in]	plaintext_size	Size of plaintext in bytes.
[out]	ciphertext	Encrypted data is returned here.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_init()

ATCA_STATUS atcab_aes_gcm_init	(	atca_aes_gcm_ctx_t *	ctx,
		uint16_t	key_id,
		uint8_t	key_block,
		const uint8_t *	iv,
		size_t	iv_size
	)

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

Parameters

[in]	ctx	AES GCM context to be initialized.
[in]	key_id	Key location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]	key_block	Index of the 16-byte block to use within the key location for the actual key.
[in]	iv	Initialization vector.
[in]	iv_size	Size of IV in bytes. Standard is 12 bytes.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_init_ext()

ATCA_STATUS atcab_aes_gcm_init_ext	(	ATCADevice	device,
		atca_aes_gcm_ctx_t *	ctx,
		uint16_t	key_id,
		uint8_t	key_block,
		const uint8_t *	iv,
		size_t	iv_size
	)

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

Parameters

[in]	device	Device context
[in]	ctx	AES GCM context to be initialized.
[in]	key_id	Key location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]	key_block	Index of the 16-byte block to use within the key location for the actual key.
[in]	iv	Initialization vector.
[in]	iv_size	Size of IV in bytes. Standard is 12 bytes.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_aes_gcm_init_rand()

ATCA_STATUS atcab_aes_gcm_init_rand	(	atca_aes_gcm_ctx_t *	ctx,
		uint16_t	key_id,
		uint8_t	key_block,
		size_t	rand_size,
		const uint8_t *	free_field,
		size_t	free_field_size,
		uint8_t *	iv
	)

Initialize context for AES GCM operation with a IV composed of a random and optional fixed(free) field, which is common when starting an encrypt operation.

Parameters

[in]	ctx	AES CTR context to be initialized.
[in]	key_id	Key location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]	key_block	Index of the 16-byte block to use within the key location for the actual key.
[in]	rand_size	Size of the random field in bytes. Minimum and recommended size is 12 bytes. Max is 32 bytes.
[in]	free_field	Fixed data to include in the IV after the random field. Can be NULL if not used.
[in]	free_field_size	Size of the free field in bytes.
[out]	iv	Initialization vector is returned here. Its size will be rand_size and free_field_size combined.

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]	h	First input value (16 bytes).
[in]	input	Second input value (16 bytes).
[out]	output	GFM 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]	encoded	Base64 string to be decoded.
[in]	encoded_len	Size of the base64 string in bytes.
[out]	byte_array	Decoded data will be returned here.
[in,out]	array_len	As 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]	encoded	Base64 string to be decoded.
[in]	encoded_size	Size of the base64 string in bytes.
[out]	data	Decoded data will be returned here.
[in,out]	data_size	As input, the size of the byte_array buffer. As output, the length of the decoded data.
[in]	rules	base64 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_array	Data to be encode in base64.
[in]	array_len	Size of byte_array in bytes.
[in]	encoded	Base64 output is returned here.
[in,out]	encoded_len	As 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]	data	The input byte array that will be converted to base 64 encoded characters
[in]	data_size	The length of the byte array
[in]	encoded	The output converted to base 64 encoded characters.
[in,out]	encoded_size	Input: The size of the encoded buffer, Output: The length of the encoded base 64 character string
[in]	rules	ruleset 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]	bin	Input data to convert.
[in]	bin_size	Size of data to convert.
[out]	hex	Buffer that receives hex string.
[in,out]	hex_size	As 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,
		bool	is_space,
		bool	is_upper
	)

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

Parameters

[in]	bin	Input data to convert.
[in]	bin_size	Size of data to convert.
[out]	hex	Buffer that receives hex string.
[in,out]	hex_size	As input, the size of the hex buffer. As output, the size of the output hex.
[in]	is_pretty	Indicates whether new lines should be added for pretty printing.
[in]	is_space	Convert the output hex with space between it.
[in]	is_upper	Convert the output hex to upper case.

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_in

Data 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_in	Host nonce to be combined with the device random number (20 bytes).
[out]	rand_out	Internally 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]	mode	Controls which fields within the device are used in the message
[in]	key_id	Key location in the CryptoAuth device to use for the MAC
[in]	challenge	Challenge data (32 bytes)
[in]	response	MAC response data (32 bytes)
[in]	other_data	OtherData parameter (13 bytes)

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_checkmac_with_response_mac()

ATCA_STATUS atcab_checkmac_with_response_mac	(	uint8_t	mode,
		const uint8_t *	challenge,
		const uint8_t *	response,
		const uint8_t *	other_data,
		uint8_t *	mac
	)

Compares a MAC response with input values.SHA105 device can generate optional mac Output response mac mode only supports in SHA105 device.

Parameters

[in]	mode	Controls which fields within the device are used in the message
[in]	challenge	Challenge data (32 bytes)
[in]	response	MAC response data (32 bytes)
[in]	other_data	OtherData parameter (13 bytes)
[out]	mac	MAC response (32 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_data	Full configuration data to compare the device against.
[out]	same_config	Result is returned here. True if the static portions on the configuration zones are the same.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_counter()

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

Compute the Counter functions.

Parameters

[in]	mode	the mode used for the counter
[in]	counter_id	The counter to be used
[out]	counter_value	pointer 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_id	Counter to be incremented
[out]	counter_value	New 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_id	Counter to be read
[out]	counter_value	Counter value is returned here.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_derivekey()

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.

Parameters

[in]	mode	Bit 2 must match the value in TempKey.SourceFlag
[in]	key_id	Key slot to be written
[in]	mac	Optional 32 byte MAC used to validate operation. NULL if not required.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_derivekey_ext()

ATCA_STATUS atcab_derivekey_ext	(	ATCADevice	device,
		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.

Parameters

[in]	device	Device context
[in]	mode	Bit 2 must match the value in TempKey.SourceFlag
[in]	key_id	Key slot to be written
[in]	mac	Optional 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_id	Slot of private key for ECDH computation
[in]	public_key	Public key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]	pms	Computed 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]	mode	Mode to be used for ECDH computation
[in]	key_id	Slot of key for ECDH computation
[in]	public_key	Public key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]	pms	Computed ECDH pre-master secret is returned here (32 bytes) if returned directly. Otherwise NULL.
[out]	out_nonce	Nonce 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,
		const uint8_t	num_in[(20)]
	)

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_id	Slot of key for ECDH computation
[in]	public_key	Public key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]	pms	Computed ECDH premaster secret is returned here (32 bytes).
[in]	read_key	Read key for the premaster secret slot (key_id|1).
[in]	read_key_id	Read key slot for read_key.
[in]	num_in	20 byte host nonce to inject into Nonce calculation

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_id	Slot of key for ECDH computation
[in]	public_key	Public key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]	pms	Computed ECDH premaster secret is returned here (32 bytes).
[in]	io_key	IO 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_key	Public key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]	pms	Computed 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_key	Public key input to ECDH calculation. X and Y integers in big-endian format. 64 bytes for P256 key.
[out]	pms	Computed ECDH premaster secret is returned here (32 bytes).
[in]	io_key	IO 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]	zone	Designates the source of the data to hash with TempKey.
[in]	key_id	Indicates the key, OTP block, or message order for shared nonce mode.
[in]	other_data	Four 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_size	Size of other_data in bytes.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_gendivkey()

ATCA_STATUS atcab_gendivkey

(

const uint8_t *

other_data

)

Issues a GenDivKey command to generate the equivalent diversified key as that programmed into the client side device.

Parameters

[in]	device	Device context pointer
[in]	other_data	Must match data used when generating the diversified key in the client device

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/handle and returns the public key.

Parameters

[in]	key_id	Slot number where an ECC private key is configured. Can also be ATCA_TEMPKEY_KEYID to generate a private key in TempKey.
[out]	public_key	Public 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]	mode	Mode determines what operations the GenKey command performs.
[in]	key_id	Slot to perform the GenKey command on.
[in]	other_data	OtherData for PubKey digest calculation. Can be set to NULL otherwise.
[out]	public_key	If 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_genkey_ext()

ATCA_STATUS atcab_genkey_ext	(	ATCADevice	device,
		uint16_t	key_id,
		uint8_t *	public_key
	)

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

Parameters

[in]	device	Device context
[in]	key_id	Slot number where an ECC private key is configured. Can also be ATCA_TEMPKEY_KEYID to generate a private key in TempKey.
[out]	public_key	Public 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_device()

ATCADevice atcab_get_device

(

void

)

Get the global device object.

Returns

instance of global ATCADevice

atcab_get_device_address()

uint8_t atcab_get_device_address

(

ATCADevice

device

)

Get the current device address based on the configured device and interface.

Returns

the device address if applicable else 0xFF

atcab_get_device_type()

ATCADeviceType atcab_get_device_type

(

void

)

Get the current device type configured for the global ATCADevice.

Returns

Device type if basic api is initialized or ATCA_DEV_UNKNOWN.

atcab_get_device_type_ext()

ATCADeviceType atcab_get_device_type_ext

(

ATCADevice

device

)

Get the selected device type of rthe device context.

Parameters

[in]

device

Device context pointer

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_id	Slot number of the private key.
[out]	public_key	Public 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_pubkey_ext()

ATCA_STATUS atcab_get_pubkey_ext	(	ATCADevice	device,
		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_id	Slot number of the private key.
[out]	public_key	Public 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]	zone	Zone to get size information from. Config(0), OTP(1), or Data(2) which requires a slot.
[in]	slot	If zone is Data(2), the slot to query for size.
[out]	size	Zone size is returned here.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_get_zone_size_ext()

ATCA_STATUS atcab_get_zone_size_ext	(	ATCADevice	device,
		uint8_t	zone,
		uint16_t	slot,
		size_t *	size
	)

Gets the size of the specified zone in bytes.

Parameters

[in]	device	Device context
[in]	zone	Zone to get size information from. Config(0), OTP(1), or Data(2) which requires a slot.
[in]	slot	If zone is Data(2), the slot to query for size.
[out]	size	Zone size is returned here.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_hex2bin()

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.

Returns

ATCA_SUCCESS on success, otherwise an error code.

Parameters

[in]	ascii_hex	Input buffer to convert
[in]	ascii_hex_len	Length of buffer to convert
[out]	binary	Buffer that receives binary
[in,out]	bin_len	As input, the size of the bin buffer. As output, the size of the bin data.

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]	mode	Controls which fields within the device are used in the message.
[in]	key_id	Which 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]	digest	HMAC 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]	data	Message data to be hashed.
[in]	data_size	Size of data in bytes.
[out]	digest	Digest 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]	ctx	SHA256 context
[out]	digest	SHA256 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]

ctx

SHA256 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]	ctx	SHA256 context
[in]	data	Message data to be added to hash.
[in]	data_size	Size 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]

revision

Device 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]	mode	Selects which mode to be used for info command.
[in]	param2	Selects the particular fields for the mode.
[out]	out_data	Response from info command (4 bytes). Can be set to NULL if not required.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_info_chip_status()

ATCA_STATUS atcab_info_chip_status

(

uint8_t *

chip_status

)

Use the Info command to get the chip status.

Parameters

[out]

chip_status

returns chip status here

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_info_ext()

ATCA_STATUS atcab_info_ext	(	ATCADevice	device,
		uint8_t *	revision
	)

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

Parameters

[in]	device	Device context
[out]	revision	Device revision is returned here (4 bytes).

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 ATECC608 device.

Parameters

[out]

state

The state is returned here. Set (true) or Cler (false).

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_info_lock_status()

ATCA_STATUS atcab_info_lock_status	(	uint16_t	param2,
		uint8_t *	is_locked
	)

Use the Info command to get the lock status.

Parameters

[in]	param2	selects the zone and slot
[out]	is_locked	returns lock status here

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 ATECC608 device.

Parameters

[out]

state

Persistent 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]

cfg

Logical 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.

Deprecated:

This function is not recommended for use generally. Use of _ext is recommended instead. You can use atcab_init_ext to obtain an initialized instance and associated it with the global structure - but this shouldn't be a required process except in extremely unusual circumstances.

Parameters

[in]

ca_device

ATCADevice instance to use as the global Basic API crypto device instance

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_init_ext()

ATCA_STATUS atcab_init_ext	(	ATCADevice *	device,
		ATCAIfaceCfg *	cfg
	)

Creates and initializes a ATCADevice context.

Parameters

[out]	device	Pointer to the device context pointer
[in]	cfg	Logical interface configuration. Some predefined configurations can be found in atca_cfgs.h

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_is_ca2_device()

bool atcab_is_ca2_device

(

ATCADeviceType

dev_type

)

Check whether the device is cryptoauth device.

Returns

True if device is cryptoauth device or False.

atcab_is_ca_device()

bool atcab_is_ca_device

(

ATCADeviceType

dev_type

)

Check whether the device is cryptoauth device.

Returns

True if device is cryptoauth device or False.

atcab_is_config_locked()

ATCA_STATUS atcab_is_config_locked

(

bool *

is_locked

)

This function check whether configuration zone is locked or not.

Parameters

[out]

is_locked

Lock state returned here. True if locked.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_is_config_locked_ext()

ATCA_STATUS atcab_is_config_locked_ext	(	ATCADevice	device,
		bool *	is_locked
	)

This function check whether configuration zone is locked or not.

Parameters

[in]	device	Device context
[out]	is_locked	Lock state returned here. True if locked.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_is_data_locked()

ATCA_STATUS atcab_is_data_locked

(

bool *

is_locked

)

This function check whether data/setup zone is locked or not.

Parameters

[out]

is_locked

Lock state returned here. True if locked.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_is_data_locked_ext()

ATCA_STATUS atcab_is_data_locked_ext	(	ATCADevice	device,
		bool *	is_locked
	)

This function check whether data/setup zone is locked or not.

Parameters

[in]	device	Device context
[out]	is_locked	Lock state returned here. True if locked.

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]	zone	The zone to query for locked (use LOCK_ZONE_CONFIG or LOCK_ZONE_DATA).
[out]	is_locked	Lock state returned here. True if locked.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_is_private_ext()

ATCA_STATUS atcab_is_private_ext	(	ATCADevice	device,
		uint16_t	slot,
		bool *	is_private
	)

Check to see if the key is a private key or not.

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

Parameters

[in]	slot	Slot number to read from if zone is ATCA_ZONE_DATA(2). Ignored for all other zones.
[out]	is_private	Returned valud if successful. True if key is private.

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
	)

This function check whether slot/handle is locked or not.

Parameters

[in]	slot	Slot to query for locked
[out]	is_locked	Lock state returned here. True if locked.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_is_slot_locked_ext()

ATCA_STATUS atcab_is_slot_locked_ext	(	ATCADevice	device,
		uint16_t	slot,
		bool *	is_locked
	)

This function check whether slot/handle is locked or not.

Parameters

[in]	device	Device context
[in]	slot	Slot to query for locked
[out]	is_locked	Lock state returned here. True if locked.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_is_ta_device()

bool atcab_is_ta_device

(

ATCADeviceType

dev_type

)

Check whether the device is Trust Anchor device.

Returns

True if device is Trust Anchor device or False.

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]	mode	Mode determines KDF algorithm (PRF,AES,HKDF), source key location, and target key locations.
[in]	key_id	Source and target key slots if locations are in the EEPROM. Source key slot is the LSB and target key slot is the MSB.
[in]	details	Further information about the computation, depending on the algorithm (4 bytes).
[in]	message	Input 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_data	Output of the KDF function is returned here. If the result remains in the device, this can be NULL.
[out]	out_nonce	If 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]	mode	Zone, and/or slot, and summary check (bit 7).
[in]	summary_crc	CRC 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. 48 bytes for TA100, 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_crc

Expected CRC over the config zone.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_lock_config_zone_ext()

ATCA_STATUS atcab_lock_config_zone_ext

(

ATCADevice

device

)

Unconditionally (no CRC required) lock the config zone.

Parameters

[in]

device

Device context

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) (for cryptoauth devices) or Lock an individual handle in shared data element on an Trust Anchor device (for Trust Anchor devices).

Parameters

[in]

slot

Slot to be locked in data zone.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_lock_data_slot_ext()

ATCA_STATUS atcab_lock_data_slot_ext	(	ATCADevice	device,
		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) (for cryptoauth devices) or Lock an individual handle in shared data element on an Trust Anchor device (for Trust Anchor devices).

Parameters

[in]	device	Device context
[in]	slot	Slot 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). for CryptoAuth devices and lock the setup for Trust Anchor device.

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_crc

Expected CRC over the data zone.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_lock_data_zone_ext()

ATCA_STATUS atcab_lock_data_zone_ext

(

ATCADevice

device

)

Unconditionally (no CRC required) lock the data zone (slots and OTP). for CryptoAuth devices and lock the setup for Trust Anchor device.

Parameters

[in]

device

Device context 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_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]	mode	Controls which fields within the device are used in the message
[in]	key_id	Key in the CryptoAuth device to use for the MAC
[in]	challenge	Challenge message (32 bytes). May be NULL if mode indicates a challenge isn't required.
[out]	digest	MAC 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_in

Data 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]	mode	Controls the mechanism of the internal RNG or fixed write.
[in]	zero	Param2, normally 0, but can be used to indicate a nonce calculation mode (bit 15).
[in]	num_in	Input value to either be included in the nonce calculation in random modes (20 bytes) or to be written directly (32 bytes or 64 bytes(ATECC608)) in pass-through mode.
[out]	rand_out	If 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 ATECC608, 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]	target	Target device buffer to load. Can be NONCE_MODE_TARGET_TEMPKEY, NONCE_MODE_TARGET_MSGDIGBUF, or NONCE_MODE_TARGET_ALTKEYBUF.
[in]	num_in	Data to load into the buffer.
[in]	num_in_size	Size 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_in	Host nonce to be combined with the device random number (20 bytes).
[out]	rand_out	Internally 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_nonce_rand_ext()

ATCA_STATUS atcab_nonce_rand_ext	(	ATCADevice	device,
		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]	device	Device context
[in]	num_in	Host nonce to be combined with the device random number (20 bytes).
[out]	rand_out	Internally 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_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],
		const uint8_t	num_in[(20)]
	)

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

Parameters

[in]	key_id	Slot to write the external private key into.
[in]	priv_key	External private key (36 bytes) to be written. The first 4 bytes should be zero for P256 curve.
[in]	write_key_id	Write key slot. Ignored if write_key is NULL.
[in]	write_key	Write key (32 bytes). If NULL, perform an unencrypted PrivWrite, which is only available when the data zone is unlocked.
[in]	num_in	20 byte host nonce to inject into Nonce calculation

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 device.

Parameters

[out]

rand_out

32 bytes of random data is returned here.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_random_ext()

ATCA_STATUS atcab_random_ext	(	ATCADevice	device,
		uint8_t *	rand_out
	)

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

Parameters

[in]	device	Device context pointer
[out]	rand_out	32 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]	zone	Zone to read data from. Option are ATCA_ZONE_CONFIG(0), ATCA_ZONE_OTP(1), or ATCA_ZONE_DATA(2).
[in]	slot	Slot number to read from if zone is ATCA_ZONE_DATA(2). Ignored for all other zones.
[in]	offset	Byte offset within the zone to read from.
[out]	data	Read data is returned here.
[in]	length	Number 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_data

Configuration zone data is returned here. 88 bytes for ATSHA devices, 128 bytes for ATECC devices and 48 bytes for Trust Anchor devices.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_read_config_zone_ext()

ATCA_STATUS atcab_read_config_zone_ext	(	ATCADevice	device,
		uint8_t *	config_data
	)

Executes Read command to read the complete device configuration zone.

Parameters

[in]	device	device context
[out]	config_data	Configuration zone data is returned here. 88 bytes for ATSHA devices, 128 bytes for ATECC devices and 48 bytes for Trust Anchor 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,
		const uint8_t	num_in[(20)]
	)

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_id	The slot ID to read from.
[in]	block	Index of the 32 byte block within the slot to read.
[out]	data	Decrypted (plaintext) data from the read is returned here (32 bytes).
[in]	enc_key	32 byte ReadKey for the slot being read.
[in]	enc_key_id	KeyID of the ReadKey being used.
[in]	num_in	20 byte host nonce to inject into Nonce calculation

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]	slot	Slot number to read from. Only slots 8 to 15 are large enough for a public key.
[out]	public_key	Public 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_pubkey_ext()

ATCA_STATUS atcab_read_pubkey_ext	(	ATCADevice	device,
		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]	device	Device context pointer
[in]	slot	Slot number to read from. Only slots 8 to 15 are large enough for a public key.
[out]	public_key	Public 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

)

This function returns serial number of the device.

Parameters

[out]

serial_number

9 byte serial number is returned here.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_read_serial_number_ext()

ATCA_STATUS atcab_read_serial_number_ext	(	ATCADevice	device,
		uint8_t *	serial_number
	)

This function returns serial number of the device.

Parameters

[in]	device	Device context
[out]	serial_number	9 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]	slot	Slot number to read from. Only slots 8 to 15 are large enough for a signature.
[out]	sig	Signature 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]	zone	Zone to be read from device. Options are ATCA_ZONE_CONFIG, ATCA_ZONE_OTP, or ATCA_ZONE_DATA.
[in]	slot	Slot number for data zone and ignored for other zones.
[in]	block	32 byte block index within the zone.
[in]	offset	4 byte work index within the block. Ignored for 32 byte reads.
[out]	data	Read data is returned here.
[in]	len	Length of the data to be read. Must be either 4 or 32.

returns ATCA_SUCCESS on success, otherwise an error code.

atcab_read_zone_ext()

ATCA_STATUS atcab_read_zone_ext	(	ATCADevice	device,
		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]	device	Device context
[in]	zone	Zone to be read from device. Options are ATCA_ZONE_CONFIG, ATCA_ZONE_OTP, or ATCA_ZONE_DATA.
[in]	slot	Slot number for data zone and ignored for other zones.
[in]	block	32 byte block index within the zone.
[in]	offset	4 byte work index within the block. Ignored for 32 byte reads.
[out]	data	Read data is returned here.
[in]	len	Length 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_release_ext()

ATCA_STATUS atcab_release_ext

(

ATCADevice *

device

)

release (free) the an ATCADevice instance.

Parameters

[in]

device

Pointer to the device context pointer

Returns

Returns ATCA_SUCCESS .

atcab_reversal()

ATCA_STATUS atcab_reversal	(	const uint8_t *	bin,
		size_t	bin_size,
		uint8_t *	dest,
		size_t *	dest_size
	)

To reverse the input data.

Parameters

[in]	bin	Input data to reverse.
[in]	bin_size	Size of data to reverse.
[out]	dest	Buffer to store reversed binary data.
[in]	dest_size	The size of the dest buffer.

Returns

ATCA_SUCCESS on success, otherwise an error code.

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]	mode	Mode determines what operations the SecureBoot command performs.
[in]	param2	Not used, must be 0.
[in]	digest	Digest of the code to be verified (32 bytes).
[in]	signature	Signature of the code to be verified (64 bytes). Can be NULL when using the FullStore mode.
[out]	mac	Validating 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]	mode	Mode determines what operations the SecureBoot command performs.
[in]	digest	Digest of the code to be verified (32 bytes). This is the plaintext digest (not encrypted).
[in]	signature	Signature of the code to be verified (64 bytes). Can be NULL when using the FullStore mode.
[in]	num_in	Host nonce (20 bytes).
[in]	io_key	IO protection key (32 bytes).
[out]	is_verified	Verify 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 ATECC608 chip.

Parameters

[in]	mode	Functions 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]	param2	Currently unused, should be 0.
[out]	result	Results 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]	length	Size of message parameter in bytes.
[in]	message	Message data to be hashed.
[out]	digest	Digest 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 *	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.

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

Parameters

[in]	mode	SHA 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 ATECC608.
[in]	length	Number of bytes in the message parameter or KeySlot for the HMAC key if Mode is HMACstart(4) or Public(3).
[in]	data_in	Message bytes to be hashed or Write_Context if restoring a context on the ATECC608. Can be NULL if not required by the mode.
[out]	data_out	Data returned by the command (digest or context).
[in,out]	data_out_size	As 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]	digest	Digest from SHA-256 or HMAC/SHA-256 will be returned here (32 bytes).
[in]	length	Length of any remaining data to include in hash. Max 64 bytes.
[in]	message	Remaining 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]	data	Message data to be hashed.
[in]	data_size	Size of data in bytes.
[in]	key_slot	Slot key id to use for the HMAC calculation
[out]	digest	Digest is returned here (32 bytes).
[in]	target	Where to save the digest internal to the device. For ATECC608, 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_ext()

ATCA_STATUS atcab_sha_hmac_ext	(	ATCADevice	device,
		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]	device	Device context pointer
[in]	data	Message data to be hashed.
[in]	data_size	Size of data in bytes.
[in]	key_slot	Slot key id to use for the HMAC calculation
[out]	digest	Digest is returned here (32 bytes).
[in]	target	Where to save the digest internal to the device. For ATECC608, 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]	ctx	HMAC/SHA-256 context
[out]	digest	HMAC/SHA-256 result is returned here (32 bytes).
[in]	target	Where to save the digest internal to the device. For ATECC608, 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]	ctx	HMAC/SHA-256 context
[in]	key_slot	Slot 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]	ctx	HMAC/SHA-256 context
[in]	data	Message data to add
[in]	data_size	Size 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 ATECC608 with SHA-256 contexts. HMAC not supported.

Parameters

[out]	context	Context data is returned here.
[in,out]	context_size	As 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]

message

64 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 ATECC608 with SHA-256 contexts.

Parameters

[in]	context	Context data to be restored.
[in]	context_size	Size 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 ATECC608 device or TempKey for other devices.

Parameters

[in]	key_id	Slot of the private key to be used to sign the message.
[in]	msg	32-byte message to be signed. Typically the SHA256 hash of the full message.
[out]	signature	Signature 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]	mode	Mode determines what the source of the message to be signed.
[in]	key_id	Private key slot used to sign the message.
[out]	signature	Signature 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_ext()

ATCA_STATUS atcab_sign_ext	(	ATCADevice	device,
		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 ATECC608 device or TempKey for other devices.

Parameters

[in]	device	Device context pointer
[in]	key_id	Slot of the private key to be used to sign the message.
[in]	msg	32-byte message to be signed. Typically the SHA256 hash of the full message.
[out]	signature	Signature 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_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_id	Slot of the private key to be used to sign the message.
[in]	is_invalidate	Set to true if the signature will be used with the Verify(Invalidate) command. false for all other cases.
[in]	is_full_sn	Set to true if the message should incorporate the device's full serial number.
[out]	signature	Signature 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]	mode	Mode determines what operations the UpdateExtra command performs.
[in]	new_value	Value 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 ATECC608) should contain the 32 byte message.

Parameters

[in]	mode	Verify command mode and options
[in]	key_id	Stored 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]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	public_key	If 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_data	If mode is Validate, the bytes used to generate the message for the validation (19 bytes). NULL for all other modes.
[out]	mac	If 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 ATECC608 device or TempKey for other devices.

Parameters

[in]	message	32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	public_key	The public key to be used for verification. X and Y integers in big-endian format. 64 bytes for P256 curve.
[out]	is_verified	Boolean 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_ext()

ATCA_STATUS atcab_verify_extern_ext	(	ATCADevice	device,
		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 ATECC608 device or TempKey for other devices.

Parameters

[in]	device	Device context pointer
[in]	message	32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	public_key	The public key to be used for verification. X and Y integers in big-endian format. 64 bytes for P256 curve.
[out]	is_verified	Boolean 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 ATECC608.

Parameters

[in]	message	32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	public_key	The public key to be used for verification. X and Y integers in big-endian format. 64 bytes for P256 curve.
[in]	num_in	System nonce (32 byte) used for the verification MAC.
[in]	io_key	IO protection key for verifying the validation MAC.
[out]	is_verified	Boolean 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_id	Slot containing the public key to be invalidated.
[in]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	other_data	19 bytes of data used to build the verification message.
[out]	is_verified	Boolean 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 ATECC608 device or TempKey for other devices.

Parameters

[in]	message	32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	key_id	Slot containing the public key to be used in the verification.
[out]	is_verified	Boolean 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_ext()

ATCA_STATUS atcab_verify_stored_ext	(	ATCADevice	device,
		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 ATECC608 device or TempKey for other devices.

Parameters

[in]	device	Device context pointer
[in]	message	32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	key_id	Slot containing the public key to be used in the verification.
[out]	is_verified	Boolean 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 ATECC608.

Parameters

[in]	message	32 byte message to be verified. Typically the SHA256 hash of the full message.
[in]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	key_id	Slot containing the public key to be used in the verification.
[in]	num_in	System nonce (32 byte) used for the verification MAC.
[in]	io_key	IO protection key for verifying the validation MAC.
[out]	is_verified	Boolean 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_with_tempkey()

ATCA_STATUS atcab_verify_stored_with_tempkey	(	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. keyConfig.reqrandom bit should be set and the message to be signed should be already loaded into TempKey for all devices.

Please refer to TEST(atca_cmd_basic_test, verify_stored_on_reqrandom_set) in atca_tests_verify.c for proper use of this api

Parameters

[in]	device	Device context pointer
[in]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	key_id	Slot containing the public key to be used in the verification.
[out]	is_verified	Boolean 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_id	Slot containing the public key to be validated.
[in]	signature	Signature to be verified. R and S integers in big-endian format. 64 bytes for P256 curve.
[in]	other_data	19 bytes of data used to build the verification message.
[out]	is_verified	Boolean 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_str

ptr 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]	zone	Zone/Param1 for the write command.
[in]	address	Address/Param2 for the write command.
[in]	value	Plain-text data to be written or cipher-text for encrypted writes. 32 or 4 bytes depending on bit 7 in the zone.
[in]	mac	MAC 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]	zone	Zone to write data to: ATCA_ZONE_CONFIG(0), ATCA_ZONE_OTP(1), or ATCA_ZONE_DATA(2).
[in]	slot	If zone is ATCA_ZONE_DATA(2), the slot number to write to. Ignored for all other zones.
[in]	offset_bytes	Byte offset within the zone to write to. Must be a multiple of a word (4 bytes).
[in]	data	Data to be written.
[in]	length	Number 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_id	Counter to be written.
[in]	counter_value	Counter 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_data

Data 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_config_zone_ext()

ATCA_STATUS atcab_write_config_zone_ext	(	ATCADevice	device,
		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]	device	Device context
[in]	config_data	Data 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,
		const uint8_t	num_in[(20)]
	)

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_id	Slot ID to write to.
[in]	block	Index of the 32 byte block to write in the slot.
[in]	data	32 bytes of clear text data to be written to the slot
[in]	enc_key	WriteKey to encrypt with for writing
[in]	enc_key_id	The KeyID of the WriteKey
[in]	num_in	20 byte host nonce to inject into Nonce calculation

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
	)

Uses the write command to write a public key to a slot in the proper format.

Parameters

[in]	slot	Slot number to write. Only slots 8 to 15 are large enough to store a public key.
[in]	public_key	Public 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_pubkey_ext()

ATCA_STATUS atcab_write_pubkey_ext	(	ATCADevice	device,
		uint16_t	slot,
		const uint8_t *	public_key
	)

Uses the write command to write a public key to a slot in the proper format.

Parameters

[in]	device	Device context
[in]	slot	Slot number to write. Only slots 8 to 15 are large enough to store a public key.
[in]	public_key	Public 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]	zone	Device zone to write to (0=config, 1=OTP, 2=data).
[in]	slot	If writing to the data zone, it is the slot to write to, otherwise it should be 0.
[in]	block	32-byte block to write to.
[in]	offset	4-byte word within the specified block to write to. If performing a 32-byte write, this should be 0.
[in]	data	Data to be written.
[in]	len	Number of bytes to be written. Must be either 4 or 32.

Returns

ATCA_SUCCESS on success, otherwise an error code.

atcab_write_zone_ext()

ATCA_STATUS atcab_write_zone_ext	(	ATCADevice	device,
		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]	device	Device context
[in]	zone	Device zone to write to (0=config, 1=OTP, 2=data).
[in]	slot	If writing to the data zone, it is the slot to write to, otherwise it should be 0.
[in]	block	32-byte block to write to.
[in]	offset	4-byte word within the specified block to write to. If performing a 32-byte write, this should be 0.
[in]	data	Data to be written.
[in]	len	Number of bytes to be written. Must be either 4 or 32.

Returns

ATCA_SUCCESS on success, otherwise an error code.

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]

c

character 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 space (A character can be included in a valid base 64 string).

Parameters

[in]	c	character to check
[in]	rules	base64 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]	c	character to check
[in]	rules	base64 ruleset to use

Returns

True if the character can be included in a valid base 64 string

isBlankSpace()

bool isBlankSpace

(

char

c

)

Checks to see if a character is blank space.

Parameters

[in]

c

character to check

Returns

True if the character is blankspace

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]

c

character 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 blankspace (The character can be included in a valid hexstring).

Parameters

[in]

c

character 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]

c

character 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]

c

character to check

Returns

True if the character can be included in a valid hexstring

packHex()

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

Remove spaces from a ASCII hex string.

Parameters

[in]	ascii_hex	Initial hex string to remove blankspace from
[in]	ascii_hex_len	Length of the initial hex string
[in]	packed_hex	Resulting hex string without blankspace
[in,out]	packed_len	In: Size to packed_hex buffer Out: Number of bytes in the packed hex string

Returns

ATCA_SUCCESS on success, otherwise an error code.