CryptoAuthLib - Microchip CryptoAuthentication Library

Introduction

This code base implements an object-oriented C library which supports Microchip CryptoAuth devices. The family of devices supported currently are:

• ATSHA204A
• ATECC108A
• ATECC508A
• ATECC608A

Online documentation is at https://microchiptech.github.io/cryptoauthlib/

Latest software and examples can be found at:

• http://www.microchip.com/SWLibraryWeb/product.aspx?product=CryptoAuthLib
• https://github.com/MicrochipTech/cryptoauthtools

Prerequisite skills:

• strong C programming and code reading
• Atmel Studio familiarity
• Knowledge of flashing microcontrollers with new code
• Familiarity with Microchip CryptoAuth device functionality

Prerequisite hardware to run CryptoAuthLib examples:

• ATSAMR21 Xplained Pro or ATSAMD21 Xplained Pro
• CryptoAuth Xplained Pro Extension or CryptoAuthentication SOIC Socket Board to accept SOIC parts

For most development, using socketed top-boards is preferable until your configuration is well tested, then you can commit it to a CryptoAuth Xplained Pro Extension, for example. Keep in mind that once you lock a device, it will not be changeable.

There are two major compiler defines that affect the operation of the library.

• ATCA_NO_POLL can be used to revert to a non-polling mechanism for device responses. Normally responses are polled for after sending a command, giving quicker response times. However, if ATCA_NO_POLL is defined, then the library will simply delay the max execution time of a command before reading the response.
• ATCA_NO_HEAP can be used to remove the use of malloc/free from the main library. This can be helpful for smaller MCUs that don't have a heap implemented. If just using the basic API, then there shouldn't be any code changes required. The lower-level API will no longer use the new/delete functions and the init/release functions should be used directly.

Examples

• Watch CryptoAuthLib Documents for new examples coming online.
• Node Authentication Example Using Asymmetric PKI is a complete, all-in-one example demonstrating all the stages of crypto authentication starting from provisioning the Crypto Authentication device ATECC608A/ATECC508A with keys and certificates to demonstrating an authentication sequence using asymmetric techniques. http://www.microchip.com/SWLibraryWeb/product.aspx?product=CryptoAuthLib

Configuration

In order to properly configured the library there must be a header file in your project named atca_config.h at minimum this needs to contain defines for the hal and device types being used:

/* Cryptoauthlib Configuration File */
#ifndef ATCA_CONFIG_H
#define ATCA_CONFIG_H

/* Include HALS */
#define ATCA_HAL_I2C

/* Included device support */
#define ATCA_ATECC608A_SUPPORT

/* \brief How long to wait after an initial wake failure for the POST to
 *         complete.
 * If Power-on self test (POST) is enabled, the self test will run on waking
 * from sleep or during power-on, which delays the wake reply.
 */
#ifndef ATCA_POST_DELAY_MSEC
#define ATCA_POST_DELAY_MSEC 25
#endif

#endif // ATCA_CONFIG_H

Release notes

02/05/2020 (v3.1.0)

• The library is now semantic versioned along with the legacy date versioning. Python will continue to be released with the date version. Version APIs have been updated.
• Configuration is done via a configuration file atca_config.h rather than global compiler options. You have to add this file to your project to support this version of the library.
• Harmony 3 support has been added. Update harmony configurator (and content loader) or manually clone crytoauthlib into your harmony directory.
• Additional Compiler support has been added for IAR-ARM and ARMCC

11/22/2019

• Patches for CVE-2019-16128 & CVE-2019-16129: Ensure reported packet length is valid for the packet being processed.
• Improvement to encrypted read operations to allow supply of a host nonce (prevent replay of a read sequence to the host). Default API is changed but can be reverted by setting the option ATCA_USE_CONSTANT_HOST_NONCE
• Added Azure compatible TNGTLS and TNGLORA certificates. Use the TNG client API to retrieve the proper certificate based on the device.
• Misc Python updates (updated APIs for encrypted reads to match the C-API change) atcacert_cert_element_t now initializes properly

08/30/2019

• Added big-endian architecture support
• Fixes to atcah_gen_dig() and atcah_nonce()

05/17/2019

• Added support for TNG devices (cert transforms, new API)
• atcab_write_pub_key() now works when the data zone is unlocked

03/04/2019

• mbed TLS wrapper added
• Minor bug fixes

01/25/2019

• Python JWT support
• Python configuration structures added
• Restructure of secure boot app

01/04/2019

• Added GCM functions
• Split AES modes into separate files
• Bug fix in SWI START driver

10/25/2018

• Added basic certificate functions to the python wrapper.
• Added Espressif ESP32 I2C driver.
• Made generic Atmel START drivers to support most MCUs in START.
• Added AES-CTR mode functions.
• Python wrapper functions now return single values with AtcaReference.
• Added mutex support to HAL and better support for freeRTOS.

08/17/2018

• Better support for multiple kit protocol devices

07/25/2018

• Clean up python wrapper

07/18/2018

• Added ATCA_NO_HEAP define to remove use of malloc/free.
• Moved PEM functions to their own file in atcacert.
• Added wake retry to accomodate power on self test delay.
• Added ca_cert_def member to atcacert_def_s so cert chains can be traversed as a linked list.

03/29/2018

• Added support for response polling by default, which will make commands return faster (define ATCA_NO_POLL to use old delay method).
• Removed atcatls related files as they were of limited value.
• Test framework generates a prompt before locking test configuration.
• Test framework puts device to sleep between tests.
• Fixed mode parameter issue in atcah_gen_key_msg().
• ATECC608A health test error code added.

01/15/2018

• Added AES-128 CBC implementation using AES command
• Added AES-128 CMAC implementation using AES command

11/22/2017

• Added support for FLEXCOM6 on SAMG55 driver

11/17/2017

• Added library support for the ATECC608A device
• Added support for Counter command
• atca_basic functions and tests now split into multiple files based on command
• Added support for multiple base64 encoding rules
• Added support for JSON Web Tokens (jwt)
• Fixed atcab_write_enc() function to encrypt the data even when the device is unlocked
• Fixed atcab_base64encode_() for the extra newline
• Updated atcab_ecdh_enc() to work more consistently

07/01/2017

• Removed assumption of SN[0:1]=0123, SN[8]=EE. SN now needs to be passed in for functions in atca_host and atca_basic functions will now read the config zone for the SN if needed.
• Renamed atcab_gendig_host() to atcab_gendig() since it's not a host function. Removed original atcab_gendig(), which had limited scope.
• Fixed atcah_hmac() for host side HMAC calculations. Added atcab_hmac().
• Removed unnecessary ATCADeviceType parameters from some atca_basic functions.
• Added atcacert_create_csr() to create a signed CSR.
• New HAL implementation for Kit protocol over HID on Linux. Please see the Incorporating CryptoAuthLib in a Linux project using USB HID devices section in this file for more information.
• Added atcacert_write_cert() for writing certificates to the device.
• Added support for dynamic length certificate serial numbers in atcacert.
• Added atcab_write() for lower level write commands.
• Fixed atcah_write_auth_mac(), which had wrong OpCode.
• Added atcab_verify() command for lower level verify commands.
• Added atcab_verify_stored() for verifying data with a stored public key.
• Removed atcab_write_bytes_slot(). Use atcab_write_bytes_zone() instead.
• Modified atcab_write_bytes_zone() and atcab_read_bytes_zone() to specify a slot
• Added atcab_verify_validate() and atcab_verify_invalidate()
• Improvements to host functions to handle more cases.
• Added atcab_updateextra(), atcab_derive_key()
• Added support for more certificate formats.
• Added general purpose hardware SHA256 functions. See atcab_hw_sha2_256().
• Removed device specific config read/write. Generic now handles both.
• Removed unnecessary response parameter from lock commands.
• Enhanced and added unit tests.
• Encrypted read and write functions now handle keys with SlotConfig.NoMac set
• atcab_cmp_config_zone() handles all devices now.
• Fixed some edge cases in atcab_read_bytes_zone().
• Updated atSHA() to work with all devices.
• Fixed atcacert_get_device_locs() when using stored sn.

01/08/2016

• New HAL implementations for
  • Single Wire interface for SAMD21 / SAMR21
  • SAMV71 I2C HAL implementation
  • XMega A3Bu HAL implementation
• Added atcab_version() method to return current version string of libary to application
• New Bus and Discovery API
  • returns a list of ATCA device configurations for each CryptoAuth device found
  • currently implemented on SAMD21/R21 I2C, SAMV71
  • additional discovery implementations to come
• TLS APIs solidified and documented
• Added missing doxygen documentation for some CryptoAuthLib methods
• Stubs for HAL SPI removed as they are unused for SHA204A and ECC508A support
• bug fixes
• updated atcab_sha() to accept a variable length message that is > 64 bytes and not a multiple of 64 bytes (the SHA block size).
• refactored Cert I/O and Cert Data tests to be smaller
• 'uncrustify' source formatting
• published on GitHub

9/19/2015

• Kit protocol over HID on Windows
• Kit protocol over CDC on Linux
• TLS integration with ATECC508A
• Certificate I/O and reconstruction
• New SHA2 implementation
• Major update to API docs, Doxygen files found in cryptoauthlib/docs
• load cryptoauthlib/docs/index.html with your browser

Host Device Support

CryptoAuthLib will run on a variety of platforms from small micro-controllers to desktop host systems. The current list of hardware abstraction layer support includes:

Rich OS Hosts:

• Linux Kit Protocol over CDC USB
• Linux Kit Protocol over HID USB
• Linux I2C protocol.
• Windows Kit Protocol over CDC USB
• Windows Kit Protocol over HID USB

Microcontrollers:

• SAMD21 (I2C, SWI, and Bit Banging)
• SAMR21 (I2C and SWI)
• SAM4S (I2C)
• SAMV71 (I2C)
• SAMB11 (I2C)
• SAMG55 (I2C)
• AVR XMEGA A3BU (I2C and SWI)
• AVR AT90USB1287 (I2C and SWI)
• PIC32MX695F512H (I2C)

If you have specific microcontrollers or Rich OS platforms you need support for, please contact us through the Microchip portal with your request.

CryptoAuthLib Architecture

See the 'docs' directory of CryptoAuthLib for supporting documentation including architecture diagrams and more detailed usage docs.

The library is structured to support portability to:

• multiple hardware/microcontroller platforms
• multiple environments including bare-metal, Windows, and Linux OS
• multiple chip communication protocols (I2C, SPI, UART, and SWI)

All platform dependencies are contained within the HAL (hardware abstraction layer).

There are three primary object types in CryptoAuthLib:

• Device (ATCADevice)
• Command (ATCACommand)
• Interface (ATCAIface)

ATCADevice is a composite object made up of ATCACommand ATCAIface.

Currently, the vast majority of testing has been performed on:

• ATSAMR21 Xplained Pro
• ATSAMD21 Xplained Pro
• ATSAMV71 Xplained Pro
• Windows (kit protocol HID)

These host containers implement a host test environment and test console to exercise tests. They presume that a CryptoAuth Xplained Pro or other I2C socket for an ATECC608A/ATECC508A/ATECC108A/ATSHA204A are connected to the I2C pins of the host Xplained Pro development board or in the case of windows is using a HID connection to an ATCK101 or ATCK590.

The unit tests and basic tests exercise the core datasheet commands of the device as well as the more convenient, basic API methods.

If you need an example of how to use a command, these hosts and tests are a good place to reference.

Object Architecture

Even though this is a C library, it follows object-oriented design patterns.

An object is minimally defined to be data and the actions which operate on that data.

Each CryptoAuth device is a composite object, a structure which includes the command table (list of commands) which are valid for the device, and the data used to hold the state of that device.

ATCADevice is the object which represents the Microchip CryptAuth device

ATCACommand is the object which represents the valid methods of the Device.

ATCAInterface is the physical interface object (I2C or SWI instance). Currently, each Device may have a single OATCAInterface.

ATCADevice represents an ATSHA or ATECC family device.

In order to add new protocol support for a platform, you provide a HAL (hardware abstraction layer) C file for the protocol and target. In your project's IDE or Makefile, you select which HAL support you need for the hardware configuration. Generally, there are separate files for each protocol and platform combination - (ie: samd21_i2c_asf.c would target SAMD21 MCUs with I2C using the ASF low-level driver support.)

Directory Structure

docs - AppNotes and Doxygen HTML documentation for the library API. Load "docs/html/index.html" in your browser
lib - primary library source code
lib/atcacert - certificate data and i/o methods
lib/basic - the Basic API way to access the core classes
lib/crypto - Software crypto implementations (primarily SHA1 and SHA256)
lib/hal - hardware abstraction layer code for supporting specific platforms
lib/host - support functions for common host-side calculations
lib/jwt - json web token functions
test - unit tests. See test/cmd-processor.c for main() implementation.

For production code, test directories should be excluded by not compiling it
into a project, so it is up to the developer to include or not as needed.  Test
code adds significant bulk to an application - it's not intended to be included
in production code.

Tests

There is a set of unit tests found in the test directory which will at least partially demonstrate the use of the objects. Some tests may depend upon a certain device being configured in a certain way and may not work for all devices or specific configurations of the device.

The test/cmd-processor.c file contains a main() function for running the tests. It implements a command-line interface. Typing help will bring up the list of commands available.

One first selects a device type, with one of the following commands:

• 204 (ATSHA204A)
• 108 (ATECC108A)
• 508 (ATECC508A)
• 608 (ATECC608A)

From there the following unit test sweets are available:

• unit (test command builder functions)
• basic (test basic API functions)
• cio (test certification i/o functions)
• cd (test certificate data functions)
• util (test utility functions)
• crypto (test software crypto functions)

Unit tests available depend on the lock level of the device. The unit tests won't lock the config or data zones automatically to allow retesting at desired lock levels. Therefore, some commands will need to be repeated after locking to exercise all available tests.

Starting from a blank device, the sequence of commands to exercise all unit tests is:

unit
basic
lockcfg
unit
basic
lockdata
unit
basic
cio
cd
util
crypto

Using CryptoAuthLib (Microchip CryptoAuth Library)

Using a new library is often easier when you can load an example and see how it works. We've provided examples in the form of "host containers" which are host projects that incorporate CryptoAuthLib and target various processors or communication APIs.

We maintain host test containers for each of the HAL layers we support. We've published the host container for SAMD21 which demonstrates a simple console interface to invoke test runners.

Look for SAMD21 Unit Tests CryptoAuthLib at http://www.microchip.com/SWLibraryWeb/product.aspx?product=CryptoAuthLib

The best way to learn how to use CryptoAuthLib is to study the host test projects that exercise the library and ATECC and ATSHA devices.

New examples will be forthcoming as the software matures. Continue checking the CryptoAuthentication web page for new updates.

Using Git to Incorporate CryptoAuthLib as a Submodule

You can include this project in your own project under git.

Using CryptoAuthLib as a git submodule, you can maintain your application separately from CryptoAuthLib.

If your project is already in git but you haven't yet intergrated CryptoAuthLib, change to the directory where you want to put CryptoAuthLib

git submodule add -b master <giturl to CryptoAuthLib>

This adds CryptoAuthLib as a subdirectory and separate git repo within your own project. Changes and commits to your project vs CryptoAuthLib will remain separated into each respective repository.

If there is a project you want to checkout that already incorporates CryptoAuthLib as a submodule if you clone the repo that incorporates CryptoAuthLib, after cloning, you'll still need to fill out the CryptoAuthLib submodule after cloning:

git submodule init
git submodule update --remote
cd cryptoauthlib
git checkout master

Now that CryptoAuthLib is a full-fledged submodule in your git project, in order to easily add it to your project within Atmel Studio, please see this tip

Incorporating CryptoAuthLib in a project

1. In your Makefile or IDE, choose the HAL support you need from the HAL directory and exclude other HAL files from your project.

2. For I2C interfaces, define the symbol ATCA_HAL_I2C in your compiler's symbol definitions. This will hook up the CryptoAuthLib interface class with your HAL implementation of I2C methods.

3. HAL implementations for CDC and HID interfaces to the ATCK101 are also included for use with Windows or Linux versions of the test host.

Incorporating CryptoAuthLib in a Linux project using USB HID devices

The Linux HID HAL files use the Linux udev development software package.

To install the udev development package under Ubuntu Linux, please type the following command at the terminal window:

sudo apt-get install libudev-dev

This adds the udev development development software package to the Ubuntu Linux installation.

The Linux HID HAL files also require a udev rule to be added to change the permissions of the USB HID Devices. Please add a new udev rule for the Microchip CryptoAuth USB devices.

cd /etc/udev/rules.d
sudo touch mchp-cryptoauth.rules

Edit the mchp-cryptoauth.rules file and add the following line to the file:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2312", MODE="0666"