CryptoAuthLib
Atmel CryptoAuthentication Library
atca_basic.c File Reference

CryptoAuthLib Basic API methods. These methods provide a simpler way to access the core crypto methods. Their design center is around the most common modes and functions of each command rather than the complete implementation of each possible feature of the chip. If you need a feature not supplied in the Basic API, you can achieve the feature through the datasheet level command supplied through the ATCADevice and ATCACommand object. More...

#include "atca_basic.h"
#include "host/atca_host.h"

Macros

#define MAX_BUSES   4
 auto discovery of crypto auth devices More...
 

Functions

ATCA_STATUS atcab_version (char *verstr)
 returns a version string for the CryptoAuthLib release. The format of the version string returned is "yyyymmdd" More...
 
ATCA_STATUS atcab_init (ATCAIfaceCfg *cfg)
 atcab_init is called once for the life of the application and creates a global ATCADevice object used by Basic API. This method builds a global ATCADevice instance behinds the scenes that's used for all Basic API operations More...
 
ATCA_STATUS atcab_init_device (ATCADevice cadevice)
 atcab_init_device can be used to initialize the global ATCADevice object to point to one of your choosing for use with all the atcab_ basic API. More...
 
ATCA_STATUS atcab_release (void)
 release (free) the global ATCADevice instance. This must be called in order to release or free up the interface. More...
 
ATCADevice atcab_getDevice (void)
 a way to get the global device object. Generally for more sophisticated users of atca More...
 
ATCA_STATUS atcab_wakeup (void)
 wakeup the CryptoAuth device More...
 
ATCA_STATUS atcab_idle (void)
 idle the CryptoAuth device More...
 
ATCA_STATUS atcab_sleep (void)
 invoke sleep on the CryptoAuth device More...
 
ATCA_STATUS atcab_cfg_discover (ATCAIfaceCfg cfgArray[], int maxIfaces)
 
ATCA_STATUS atcab_info (uint8_t *revision)
 get the device revision information More...
 
ATCA_STATUS atcab_random (uint8_t *rand_out)
 Get a 32 byte random number from the CryptoAuth device. More...
 
ATCA_STATUS atcab_genkey (int slot, uint8_t *pubkey)
 generate a key on given slot More...
 
ATCA_STATUS atcab_nonce (const uint8_t *tempkey)
 Execute a pass-through Nonce command to initialize TempKey to the specified value. More...
 
ATCA_STATUS atcab_nonce_rand (const uint8_t *seed, uint8_t *rand_out)
 Initialize TempKey with a random Nonce. More...
 
ATCA_STATUS atcab_challenge (const uint8_t *challenge)
 send a challenge to the device (a pass-through nonce) More...
 
ATCA_STATUS atcab_challenge_seed_update (const uint8_t *seed, uint8_t *rand_out)
 send a challenge to the device (a seed update nonce) More...
 
ATCA_STATUS atcab_read_serial_number (uint8_t *serial_number)
 read the serial number of the device More...
 
ATCA_STATUS atcab_verify_extern (const uint8_t *message, const uint8_t *signature, const uint8_t *pubkey, bool *verified)
 verify a signature using CryptoAuth hardware (as opposed to an ECDSA software implementation) More...
 
ATCA_STATUS atcab_ecdh (uint16_t key_id, const uint8_t *pubkey, uint8_t *ret_ecdh)
 issues ecdh command More...
 
ATCA_STATUS atcab_ecdh_enc (uint16_t slotid, const uint8_t *pubkey, uint8_t *ret_ecdh, const uint8_t *enckey, const uint8_t enckeyid)
 issues ecdh command More...
 
ATCA_STATUS atcab_get_addr (uint8_t zone, uint8_t slot, uint8_t block, uint8_t offset, uint16_t *addr)
 Compute the address given the zone, slot, block, and offset. More...
 
ATCA_STATUS atcab_is_slot_locked (uint8_t slot, bool *islocked)
 Query to see if the specified slot is locked. More...
 
ATCA_STATUS atcab_is_locked (uint8_t zone, bool *islocked)
 Query to see if the specified zone is locked. More...
 
ATCA_STATUS atcab_write_zone (uint8_t zone, uint8_t slot, uint8_t block, uint8_t offset, const uint8_t *data, uint8_t len)
 write either 4 or 32 bytes of data into the device zone More...
 
ATCA_STATUS atcab_read_zone (uint8_t zone, uint8_t slot, uint8_t block, uint8_t offset, uint8_t *data, uint8_t len)
 read either 4 or 32 bytes of data into given slot More...
 
ATCA_STATUS atcab_read_enc (uint8_t slotid, uint8_t block, uint8_t *data, const uint8_t *enckey, const uint16_t enckeyid)
 Read 32 bytes of data from the given slot. The function returns clear text bytes. Encrypted bytes are read over the wire, then subsequently decrypted Data zone must be locked and the slot configuration must be set to encrypted read for the block to be successfully read. More...
 
ATCA_STATUS atcab_write_enc (uint8_t slotid, uint8_t block, const uint8_t *data, const uint8_t *enckey, const uint16_t enckeyid)
 Write 32 bytes of data into given slot. The function takes clear text bytes, but 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. More...
 
ATCA_STATUS atcab_read_ecc_config_zone (uint8_t *config_data)
 read the config zone by block by block for 32 byte read, offset is ignored data receives the contents read from the slot Config zone can be read regardless of it being locked or unlocked More...
 
ATCA_STATUS atcab_write_ecc_config_zone (const uint8_t *config_data)
 given an ECC configuration zone buffer, write its parts to the device's config zone More...
 
ATCA_STATUS atcab_read_sha_config_zone (uint8_t *config_data)
 given an SHA configuration zone buffer, read its parts from the device's config zone More...
 
ATCA_STATUS atcab_write_sha_config_zone (const uint8_t *config_data)
 given an SHA configuration zone buffer, write its parts to the device's config zone More...
 
ATCA_STATUS atcab_read_config_zone (ATCADeviceType dev_type, uint8_t *config_data)
 given an SHA configuration zone buffer and dev type, read its parts from the device's config zone More...
 
ATCA_STATUS atcab_write_config_zone (ATCADeviceType dev_type, const uint8_t *config_data)
 given an SHA configuration zone buffer and dev type, write its parts to the device's config zone More...
 
ATCA_STATUS atcab_cmp_config_zone (uint8_t *config_data, bool *same_config)
 This function compares all writable bytes in the configuration zone that is passed in to the bytes on the device. More...
 
ATCA_STATUS atcab_lock_config_zone (uint8_t *lock_response)
 lock the ATCA ECC config zone. config zone must be unlocked for the zone to be successfully locked More...
 
ATCA_STATUS atcab_lock_data_zone (uint8_t *lock_response)
 lock the ATCA ECC Data zone. More...
 
ATCA_STATUS atcab_lock_data_slot (uint8_t slot, uint8_t *lock_response)
 lock the ATCA ECC Data Slot ConfigZone must be locked and DataZone may or may not be locked for a individual data slot to be locked More...
 
ATCA_STATUS atcab_sign (uint16_t slot, const uint8_t *msg, uint8_t *signature)
 sign a buffer using private key in given slot, stuff the signature More...
 
ATCA_STATUS atcab_gendig (uint8_t zone, uint16_t key_id)
 Issues a GenDig command to SHA256 hash the source data indicated by zone with the contents of TempKey. See the CryptoAuth datasheet for your chip to see what the values of zone correspond to. More...
 
ATCA_STATUS atcab_gendig_host (uint8_t zone, uint16_t key_id, uint8_t *other_data, uint8_t len)
 Similar to atcab_gendig except this method does the operation in software on the host. More...
 
ATCA_STATUS atcab_read_sig (uint8_t slot8toF, uint8_t *sig)
 reads a signature found in one of slots 8 through F. More...
 
ATCA_STATUS atcab_get_pubkey (uint8_t slot, uint8_t *pubkey)
 returns a public key found in a designated slot. The slot must be configured as a slot with a private key. This method will use GenKey t geenrate the corresponding public key from the private key in the given slot. More...
 
ATCA_STATUS atcab_priv_write (uint8_t slot, const uint8_t priv_key[36], uint8_t write_key_slot, const uint8_t write_key[32])
 write a P256 private key in given slot using mac computation More...
 
ATCA_STATUS atcab_read_pubkey (uint8_t slot8toF, uint8_t *pubkey)
 reads a pub key from a readable data slot versus atcab_get_pubkey which generates a pubkey from a private key slot More...
 
ATCA_STATUS atcab_write_bytes_slot (uint8_t slot, uint16_t offset, const uint8_t *data, uint8_t len)
 write data into given slot of data zone with offset address More...
 
ATCA_STATUS atcab_write_bytes_zone (ATCADeviceType dev_type, uint8_t zone, uint16_t address, const uint8_t *data, uint8_t len)
 write data into config, otp or data zone with given zone and offset More...
 
ATCA_STATUS atcab_read_bytes_zone (ATCADeviceType dev_type, uint8_t zone, uint16_t address, uint8_t len, uint8_t *data)
 read data from config, otp or data zone with given zone, offset and len More...
 
ATCA_STATUS atcab_mac (uint8_t mode, uint16_t key_id, const uint8_t *challenge, uint8_t *digest)
 Get a 32 byte MAC from the CryptoAuth device given a key ID and a challenge. More...
 
ATCA_STATUS atcab_checkmac (uint8_t mode, uint16_t key_id, const uint8_t *challenge, const uint8_t *response, const uint8_t *other_data)
 Compares a MAC response with input values. More...
 
ATCA_STATUS atcab_sha_start (void)
 Initialize SHA-256 calculation engine. More...
 
ATCA_STATUS atcab_sha_update (uint16_t length, const uint8_t *message)
 Adds the message to be digested. More...
 
ATCA_STATUS atcab_sha_end (uint8_t *digest)
 The SHA-256 calculation is complete. More...
 
ATCA_STATUS atcab_sha (uint16_t length, const uint8_t *message, uint8_t *digest)
 Computes a SHA-256 digest. More...
 

Variables

char atca_version [] = { "20151211" }
 
ATCADevice _gDevice = NULL
 basic API methods are all prefixed with atcab_ (Atmel CryptoAuth Basic) the fundamental premise of the basic API is it is based on a single interface instance and that instance is global, so all basic API commands assume that one global device is the one to operate on. More...
 
ATCACommand _gCommandObj = NULL
 
ATCAIface _gIface = NULL
 

Detailed Description

CryptoAuthLib Basic API methods. These methods provide a simpler way to access the core crypto methods. Their design center is around the most common modes and functions of each command rather than the complete implementation of each possible feature of the chip. If you need a feature not supplied in the Basic API, you can achieve the feature through the datasheet level command supplied through the ATCADevice and ATCACommand object.

One primary assumption to all atcab_ routines is that the caller manages the wake/sleep/idle bracket so prior to calling the atcab_ routine, the chip should be awake; the routine will manage wake/sleep/idle within the function and leave the chip awake upon return.

Macro Definition Documentation

#define MAX_BUSES   4

auto discovery of crypto auth devices

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

Parameters
[out]cfgArray,ptrto an array of interface configs
[in]max,maximumsize of cfgArray
Returns
ATCA_STATUS

Variable Documentation

ATCACommand _gCommandObj = NULL
ATCADevice _gDevice = NULL

basic API methods are all prefixed with atcab_ (Atmel CryptoAuth 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.

ATCAIface _gIface = NULL
char atca_version[] = { "20151211" }