 |
CryptoAuthLib v3.7.4
Microchip CryptoAuthentication Library
|
|
|
CryptoAuthLib v3.7.4
Microchip CryptoAuthentication Library
|
|
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_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. | |
These methods provide the most convenient, simple API to CryptoAuth chips.
| 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.
| [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). |
| 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.
| [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). |
| 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.
| [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). |
| 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.
| [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). |
| 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.
| [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). |
| 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().
| [in] | ctx | AES GCM context |
| [in] | aad | Additional authenticated data to be added |
| [in] | aad_size | Size of aad in bytes |
| 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().
| [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 |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [in] | ctx | AES GCM context structure. |
| [out] | tag | Authentication tag is returned here. |
| [in] | tag_size | Tag size in bytes (12 to 16 bytes). |
| 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.
| [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). |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| ATCA_STATUS atcab_aes_gfm | ( | const uint8_t * | h, |
| const uint8_t * | input, | ||
| uint8_t * | output | ||
| ) |
Perform a Galois Field Multiply (GFM) operation.
| [in] | h | First input value (16 bytes). |
| [in] | input | Second input value (16 bytes). |
| [out] | output | GFM result is returned here (16 bytes). |
| ATCA_STATUS atcab_base64decode | ( | const char * | encoded, |
| size_t | encoded_len, | ||
| uint8_t * | byte_array, | ||
| size_t * | array_len | ||
| ) |
Decode base64 string to data.
| [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. |
| 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.
| [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 |
| ATCA_STATUS atcab_base64encode | ( | const uint8_t * | byte_array, |
| size_t | array_len, | ||
| char * | encoded, | ||
| size_t * | encoded_len | ||
| ) |
Encode data as base64 string.
| [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. |
| 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.
| [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 |
| 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.
| [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. |
| 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.
| [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. |
| ATCA_STATUS atcab_challenge | ( | const uint8_t * | num_in | ) |
Execute a Nonce command in pass-through mode to initialize TempKey to a specified value.
| [in] | num_in | Data to be loaded into TempKey (32 bytes). |
| 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.
| [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. |
| 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.
| [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) |
| 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.
| [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) |
| 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).
| [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. |
| ATCA_STATUS atcab_counter | ( | uint8_t | mode, |
| uint16_t | counter_id, | ||
| uint32_t * | counter_value | ||
| ) |
Compute the Counter functions.
| [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 |
| ATCA_STATUS atcab_counter_increment | ( | uint16_t | counter_id, |
| uint32_t * | counter_value | ||
| ) |
Increments one of the device's monotonic counters.
| [in] | counter_id | Counter to be incremented |
| [out] | counter_value | New value of the counter is returned here. Can be NULL if not needed. |
| ATCA_STATUS atcab_counter_read | ( | uint16_t | counter_id, |
| uint32_t * | counter_value | ||
| ) |
Read one of the device's monotonic counters.
| [in] | counter_id | Counter to be read |
| [out] | counter_value | Counter value is returned here. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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 |
| 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.
| [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. |
| 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.
| [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). |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [in] | device | Device context pointer |
| [in] | other_data | Must match data used when generating the diversified key in the client device |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| ATCADevice atcab_get_device | ( | void | ) |
Get the global device object.
| uint8_t atcab_get_device_address | ( | ATCADevice | device | ) |
Get the current device address based on the configured device and interface.
| ATCADeviceType atcab_get_device_type | ( | void | ) |
Get the current device type configured for the global ATCADevice.
| ATCADeviceType atcab_get_device_type_ext | ( | ATCADevice | device | ) |
Get the selected device type of rthe device context.
| [in] | device | Device context pointer |
| 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.
| [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. |
| 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.
| [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. |
| ATCA_STATUS atcab_get_zone_size | ( | uint8_t | zone, |
| uint16_t | slot, | ||
| size_t * | size | ||
| ) |
Gets the size of the specified zone in bytes.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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). |
| 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.
| [in] | data | Message data to be hashed. |
| [in] | data_size | Size of data in bytes. |
| [out] | digest | Digest is returned here (32 bytes). |
| 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.
| [in] | ctx | SHA256 context |
| [out] | digest | SHA256 digest is returned here (32 bytes) |
| 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.
| [in] | ctx | SHA256 context |
| 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.
| [in] | ctx | SHA256 context |
| [in] | data | Message data to be added to hash. |
| [in] | data_size | Size of data in bytes. |
| ATCA_STATUS atcab_idle | ( | void | ) |
idle the CryptoAuth device
| ATCA_STATUS atcab_info | ( | uint8_t * | revision | ) |
Use the Info command to get the device revision (DevRev).
| [out] | revision | Device revision is returned here (4 bytes). |
| 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.
| [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. |
| ATCA_STATUS atcab_info_chip_status | ( | uint8_t * | chip_status | ) |
Use the Info command to get the chip status.
| [out] | chip_status | returns chip status here |
| ATCA_STATUS atcab_info_ext | ( | ATCADevice | device, |
| uint8_t * | revision | ||
| ) |
Use the Info command to get the device revision (DevRev).
| [in] | device | Device context |
| [out] | revision | Device revision is returned here (4 bytes). |
| ATCA_STATUS atcab_info_get_latch | ( | bool * | state | ) |
Use the Info command to get the persistent latch current state for an ATECC608 device.
| [out] | state | The state is returned here. Set (true) or Cler (false). |
| ATCA_STATUS atcab_info_lock_status | ( | uint16_t | param2, |
| uint8_t * | is_locked | ||
| ) |
Use the Info command to get the lock status.
| [in] | param2 | selects the zone and slot |
| [out] | is_locked | returns lock status here |
| ATCA_STATUS atcab_info_set_latch | ( | bool | state | ) |
Use the Info command to set the persistent latch state for an ATECC608 device.
| [out] | state | Persistent latch state. Set (true) or clear (false). |
| ATCA_STATUS atcab_init | ( | ATCAIfaceCfg * | cfg | ) |
Creates a global ATCADevice object used by Basic API.
| [in] | cfg | Logical interface configuration. Some predefined configurations can be found in atca_cfgs.h |
| 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.
| [in] | ca_device | ATCADevice instance to use as the global Basic API crypto device instance |
| ATCA_STATUS atcab_init_ext | ( | ATCADevice * | device, |
| ATCAIfaceCfg * | cfg | ||
| ) |
Creates and initializes a ATCADevice context.
| [out] | device | Pointer to the device context pointer |
| [in] | cfg | Logical interface configuration. Some predefined configurations can be found in atca_cfgs.h |
| bool atcab_is_ca2_device | ( | ATCADeviceType | dev_type | ) |
Check whether the device is cryptoauth device.
| bool atcab_is_ca_device | ( | ATCADeviceType | dev_type | ) |
Check whether the device is cryptoauth device.
| ATCA_STATUS atcab_is_config_locked | ( | bool * | is_locked | ) |
This function check whether configuration zone is locked or not.
| [out] | is_locked | Lock state returned here. True if locked. |
| ATCA_STATUS atcab_is_config_locked_ext | ( | ATCADevice | device, |
| bool * | is_locked | ||
| ) |
This function check whether configuration zone is locked or not.
| [in] | device | Device context |
| [out] | is_locked | Lock state returned here. True if locked. |
| ATCA_STATUS atcab_is_data_locked | ( | bool * | is_locked | ) |
This function check whether data/setup zone is locked or not.
| [out] | is_locked | Lock state returned here. True if locked. |
| ATCA_STATUS atcab_is_data_locked_ext | ( | ATCADevice | device, |
| bool * | is_locked | ||
| ) |
This function check whether data/setup zone is locked or not.
| [in] | device | Device context |
| [out] | is_locked | Lock state returned here. True if 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.
| [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. |
| 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.
| [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. |
| ATCA_STATUS atcab_is_slot_locked | ( | uint16_t | slot, |
| bool * | is_locked | ||
| ) |
This function check whether slot/handle is locked or not.
| [in] | slot | Slot to query for locked |
| [out] | is_locked | Lock state returned here. True if locked. |
| 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.
| [in] | device | Device context |
| [in] | slot | Slot to query for locked |
| [out] | is_locked | Lock state returned here. True if locked. |
| bool atcab_is_ta_device | ( | ATCADeviceType | dev_type | ) |
Check whether the device is Trust Anchor 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.
Generally this function combines a source key with an input string and creates a result key/digest/array.
| [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. |
| 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.
| [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. |
| ATCA_STATUS atcab_lock_config_zone | ( | void | ) |
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.
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.
| [in] | summary_crc | Expected CRC over the config zone. |
| ATCA_STATUS atcab_lock_config_zone_ext | ( | ATCADevice | device | ) |
Unconditionally (no CRC required) lock the config zone.
| [in] | device | Device context |
| 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).
| [in] | slot | Slot to be locked in data zone. |
| 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).
| [in] | device | Device context |
| [in] | slot | Slot to be locked in 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.
| 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.
| [in] | summary_crc | Expected CRC over the data zone. |
| 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.
| [in] | device | Device context ConfigZone must be locked and DataZone must be unlocked for the zone to be successfully locked. |
| 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.
| [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). |
| ATCA_STATUS atcab_nonce | ( | const uint8_t * | num_in | ) |
Execute a Nonce command in pass-through mode to initialize TempKey to a specified value.
| [in] | num_in | Data to be loaded into TempKey (32 bytes). |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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 |
| ATCA_STATUS atcab_random | ( | uint8_t * | rand_out | ) |
Executes Random command, which generates a 32 byte random number from the device.
| [out] | rand_out | 32 bytes of random data is returned here. |
| ATCA_STATUS atcab_random_ext | ( | ATCADevice | device, |
| uint8_t * | rand_out | ||
| ) |
Executes Random command, which generates a 32 byte random number from the device.
| [in] | device | Device context pointer |
| [out] | rand_out | 32 bytes of random data is returned here. |
| 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.
| [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. |
| ATCA_STATUS atcab_read_config_zone | ( | uint8_t * | config_data | ) |
Executes Read command to read the complete device configuration zone.
| [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. |
| ATCA_STATUS atcab_read_config_zone_ext | ( | ATCADevice | device, |
| uint8_t * | config_data | ||
| ) |
Executes Read command to read the complete device configuration zone.
| [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. |
| 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.
| [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.
| 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.
| [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. |
| 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.
| [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. |
| ATCA_STATUS atcab_read_serial_number | ( | uint8_t * | serial_number | ) |
This function returns serial number of the device.
| [out] | serial_number | 9 byte serial number is returned here. |
| ATCA_STATUS atcab_read_serial_number_ext | ( | ATCADevice | device, |
| uint8_t * | serial_number | ||
| ) |
This function returns serial number of the device.
| [in] | device | Device context |
| [out] | serial_number | 9 byte serial number is returned here. |
| 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.
| [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. |
| 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.
| [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.
| ATCA_STATUS atcab_release | ( | void | ) |
release (free) the global ATCADevice instance. This must be called in order to release or free up the interface.
| ATCA_STATUS atcab_release_ext | ( | ATCADevice * | device | ) |
release (free) the an ATCADevice instance.
| [in] | device | Pointer to the device context pointer |
| ATCA_STATUS atcab_reversal | ( | const uint8_t * | bin, |
| size_t | bin_size, | ||
| uint8_t * | dest, | ||
| size_t * | dest_size | ||
| ) |
To reverse the input data.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| ATCA_STATUS atcab_sha | ( | uint16_t | length, |
| const uint8_t * | message, | ||
| uint8_t * | digest | ||
| ) |
Use the SHA command to compute a SHA-256 digest.
| [in] | length | Size of message parameter in bytes. |
| [in] | message | Message data to be hashed. |
| [out] | digest | Digest is returned here (32 bytes). |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [in] | ctx | HMAC/SHA-256 context |
| [in] | key_slot | Slot key id to use for the HMAC calculation |
| 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.
| [in] | ctx | HMAC/SHA-256 context |
| [in] | data | Message data to add |
| [in] | data_size | Size of message data in bytes |
| 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.
| [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. |
| 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.
| [in] | message | 64 bytes of message data to add to add to operation. |
| 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.
| [in] | context | Context data to be restored. |
| [in] | context_size | Size of the context data in bytes. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| ATCA_STATUS atcab_sleep | ( | void | ) |
invoke sleep on the CryptoAuth device
| 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.
| [in] | mode | Mode determines what operations the UpdateExtra command performs. |
| [in] | new_value | Value to be written. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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).
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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
| [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. |
| 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).
| [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. |
| 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"
| [out] | ver_str | ptr to space to receive version string |
| ATCA_STATUS atcab_wakeup | ( | void | ) |
wakeup the CryptoAuth device
| 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.
| [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. |
| 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.
| [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). |
| 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.
| [in] | counter_id | Counter to be written. |
| [in] | counter_value | Counter value to set. |
| 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.
| [in] | config_data | Data to the config zone data. This should be 88 bytes for SHA devices and 128 bytes for ECC devices. |
| 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.
| [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. |
| 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.
| [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.
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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'))
| [in] | c | character to check |
| 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).
| [in] | c | character to check |
| [in] | rules | base64 ruleset to use |
| bool isBase64Digit | ( | char | c, |
| const uint8_t * | rules | ||
| ) |
Returns true if this character is a valid base 64 character.
| [in] | c | character to check |
| [in] | rules | base64 ruleset to use |
| bool isBlankSpace | ( | char | c | ) |
Checks to see if a character is blank space.
| [in] | c | character to check |
| bool isDigit | ( | char | c | ) |
Checks to see if a character is an ASCII representation of a digit ((c ge '0') and (c le '9'))
| [in] | c | character to check |
| 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).
| [in] | c | character to check |
| 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'))
| [in] | c | character to check |
| bool isHexDigit | ( | char | c | ) |
Returns true if this character is a valid hex character.
| [in] | c | character to check |
| 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.
| [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 |
1.9.6