Provides the library for Microchip CryptoAuth devices. More...
Provides the library for Microchip CryptoAuth devices.
This package provides support for the official library for Microchip CryptoAuth devices.
to your Makefile.
To facilitate the device configuration the RIOT shell provides some helper commands. Currently there are shell commands to read the device's config zone, to lock the config zone (this will lock the config zone permanently and cannot be undone) and to check whether config and data zone are locked. The shell handler is enabled, if cryptoauthlib is included as a package in the Makefile of an application that also includes the shell (e.g. examples/default).
After sending a command to the device, responses are usually polled to enable quicker response times. Alternatively ATCA_NO_POLL can be enabled through CFLAGS to simply wait for the max execution time of a command before reading the response.
This implementation was partly tested with ATECC508A and ATECC608A devices. Currently the functions
hal_i2c_discover_buses are unimplemented, as well as
The library provides unittests for the library functions. There is a directory called "pkg_cryptoauthlib_internal_tests" in the RIOT testfolder which runs part of the unittests. Some of the provided tests can only be run when the config, data and/or otp zones of the device are locked. Some tests (but not all) will automatically lock zones as needed. We omit those tests at the moment, because zones can only be locked permanently. Unlocking is not possible! Also there is a test for comparing the runtime of the RIOT software implementation and the CryptoAuth hardware implementation for calculating a SHA-256 hash value.
When using more than one device, you can either connect devices with different I2C addresses to one bus or devices with the same address to separate buses. The ATECCX08A devices provide a way to change the I2C address during device configuration (for more details, read the datasheet or the API documentation).
ATECCX08A device parameters are configured in
RIOT/pkg/cryptoauthlib/include/atca_params.h. There you can specify your device's address, the I2C bus to use and more by defining
ATCA_PARAMS. Per default one device is defined in RIOT (example shown below).
If you want to use more than one device, the best way is to create a file called
custom_atca_params.h in your application folder (you can see an example of this in
In your custom file you can now add a second device to
Now you just need to add the following to your Makefile:
This way your custom params file is included in the build process and both your devices will be initialized by the
To use them you need to utilize the
calib-API of the cryptoauth driver, which allows you to pass a device handle. Pointers to all initialized devices are stored in the
atca_devs_ptr array, which is included in
atca_params.h in your source file and pass the device handle as shown below.
To use cryptoauthlib as a backend for PSA Crypto, it is best to overwrite the
atca_params.h file with your own
custom_atca_params.h file, similar to the one described in Using Multiple ATECCX08A Devices.
When using PSA, the
ATCA_PARAMS define contains an additional value: A location value of the type psa_key_location_t. Each secure element you use needs its own location value. The primary device can get the value PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT. All others must be within the range of PSA_KEY_LOCATION_SE_MIN and PSA_KEY_LOCATION_SE_MAX.
Your structure should now look like this:
When using multiple SEs, just add more device parameters as shown in section Using Multiple ATECCX08A Devices.
The ATECCX08A devices have their own key management, which can be configured by setting flags in the device's configuration and data zone. There is a large variety of possible configurations, which can not entirely be represented by PSA Crypto.
For now we assume that users are familiar with their device's datasheet and have configured it in a way that it is usable. PSA can not yet work with keys that are already stored on the device, which means all key slots must be writable after locking the configuration and data zone.
For ECC operations this means that key slot configurations need to allow at least the use of the
gen_key command, for AES and HMAC key slots it means that clear write operations must be allowed.
Users need to make their configurations known to PSA Crypto. For this you need to initialize a list of key slot configuration structures, with a structure for each slot.
For these devices the structure looks like this:
To make your configurations known to PSA, simply add the following to your
custom_atca_params.h file (these values are only an example, of course you need to modify them according to your needs).
To use multiple devices, define
ATCA_SLOTS_DEVX and add them to
ATCA_CONFIG_LIST like so:
A usage example for this can be found in
Make sure the I2C bus speed is set to
|Default addresses and device descriptor for CryptoAuth devices.
|Minimal configuration for the library build.
|Default configuration for Microchip CryptoAuth devices.