ATECC108A-SSHDA-T - Atmel - Datasheet.Directory

Atmel-8770C-CryptoAuth-ATECC108-ATSHA204-Firmware-Library-UserGuide_012014

Features

Layered and Modular Design

Compact and Optimized for 8-bit Microcontrollers

Easy to Port

Supports I2C and Single-Wire Communication

Distributed as Source Code

Introduction

This user guide describes how to use the Atmel® ATECC108/ATSHA204 firmware library with your own

security project and how to tune it towards your hardware. To fully understand this document, it is required

to have the library code base.

The ATECC108 is fully backwards compatible with the ATSHA204. As a result, the ATECC108 library is an

extension of the ATSHA204 library and will require the ATSHA204 library to be present.

ATECC108/ATSHA204

Atmel Firmware Library

USER GUIDE

ATECC108/ATSHA204 Firmware Library [USER GUIDE]

Atmel-8770C-CryptoAuth-ATECC108-ATSHA204-Firmware-Library-UserGuide_012014

Table of Contents

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Layered Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Physical Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Communication Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Command Marshaling Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Application Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Portability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Robustness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Example Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Project Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Folder Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Porting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Physical Layer Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Communication Layer Timeout Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Timer Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Removal of Command Marshaling Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Removal of Communication Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Using UART Instead of GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

ATECC108/ATSHA204 Firmware Library [USER GUIDE]

Atmel-8770C-CryptoAuth-ATECC108-ATSHA204-Firmware-Library-UserGuide_012014

Overview

Layered Design

The library consists of logically layered components in each successive layer. Since the library is

distributed as C source code, a customer application project can use or include specific parts of the library

code. For instance, you can compile and link the command marshaling layer functionality or exclude it. For

an embedded application that only wants authentication from the device, it would make sense for that

application to construct the byte stream per the device specification and communicate directly with the

silicon via one of the communication methods available. This would generate the smallest code size and

simplest code.

Figure 1. ATECC108/ATSHA204 Firmware Library Design

Additional ATSHA204s

I2C Interface

(i2c_phys.c)

Single-Wire Interface

Bit-banged

(bitbang_phys.c)

Single Wire Interface

UART

(uart_phys.c)

Devices

Physical,

hardware

indepent

Command

Marshaling

Application

ATSHA204

I2C Interface

(sha204_i2c.c)

Physical,

hardware

dependent

Communications Interface (sha204_comm.c)

sha204c_wakeup(), sha204_send_and_receive(), sha204c_calculate_crc()

Commands (sha204_comm_marshaling.c)

sha204m_execute()

Customer

Application

Single Wire Interface

(sha204_swi.c)

Communication

I2C Interface

Bit-banged

(i2c_phys_bitbang.c)

ATECC108/ATSHA204 Firmware Library [USER GUIDE]

Atmel-8770C-CryptoAuth-ATECC108-ATSHA204-Firmware-Library-UserGuide_012014

Physical Layer

The Physical layer is divided into hardware-dependent and hardware-independent parts. Two physical

interfaces are provided:

I2C Interface

Single-Wire Interface (SWI)

The Physical layer provides a common calling interface that abstracts the hardware (or SWI). By keeping

the hardware-independent function names the same for the interfaces, the driver modules can easily be

exchanged in a project/makefile without touching the source code.

Atmel provides an implementation of the I2C and SWI interfaces for the Atmel AVR® AT90USB1287

microcontroller.

Communication Layer

The Communication layer provides a straightforward conduit for data exchange between the device and

the application software. Data exchange is based on sending a command and reading its response after

command execution. This layer retries a communication sequence in case of certain communication errors

reported by the Physical layer or the Device Status Register, or when there is an inconsistent response

packet (value in Count byte, CRC).

Command Marshaling Layer

The Command Marshaling layer is built on top of the Communication layer to implement commands that

the device supports. Such commands are assembled or marshaled into the correct byte streams expected

by the device.

Application Layer

Customers may build an API layer on top of the library to provide an easier interface for their security

solution.

Portability

The library has been tested for building applications and running them without errors for several target

platforms, including the Atmel AVR 8 bit MCU family. To make porting the library to a different target as

easy as possible, specific coding rules were applied:

No structures are used to avoid any “packed” and addressing issues on 32-bit targets

Functions in hardware-dependent modules (spi_phys.c and i2c_phys.c) do not “know” any specifics

of the device. It will be easy to replace these functions with others from target libraries or with your

own. Many I2C peripherals on 32-bit CPUs implement hardware-dependent module functionality. For

such cases, porting involves discarding the hardware-dependent I2C module altogether and

adapting the functions in the hardware-independent I2C module to the peripheral, or to an I2C library

provided by the CPU manufacturer or firmware development tool

Where 16-bit variables are inserted into or extracted from a communication buffer (LSB first), no type

casting is used [(uint8_t *) &uint16_variable], but the MSB and LSB are calculated

(msb = uint16_variable >> 8; lsb = uint16_variable & 0xFF). There is no need for a distinction

between big-endian and little-endian targets

Delays and timeouts are implemented using loop counters instead of hardware timers. They need to

be tuned to your specific CPU. If hardware or software timers are available in your system, you might

replace the pieces of the library that use loop counters with calls to those timer functions. All timing

values that all layers need to access are defined in sha204_config.h

ATECC108/ATSHA204 Firmware Library [USER GUIDE]

Atmel-8770C-CryptoAuth-ATECC108-ATSHA204-Firmware-Library-UserGuide_012014

Robustness

The library applies retry mechanisms in its communication layer (sha204_comm.c) in case of

communication failures. Therefore, there is no need for an application to implement such retries.

Optimization

In addition to the size and speed optimizations left to the compiler, certain requirements were established

for the code:

Feature creep is kept in check.

Only 8-bit and 16-bit variables are used, and so there is no need to import 32-bit compiler libraries.

This also makes the library run faster on 8-bit targets.

The layered architecture makes it easy to reduce code size by removing layers and/or functions that

are not needed in your project.

Some speed and size penalties are incurred in the communication layer (sha204_comm.c) due to

increased robustness. For instance, implementing retries increases code size, while error checking

(CRC, Count byte in response buffer) reduces speed and increases code size.

Arrays for certain commands and memory addresses are declared as “const,” which allows

compilers to skip copying such arrays to RAM at startup.

Example Projects

Atmel provides example projects for an Atmel AT90USB1287. To become familiar with the library, we

advise customers to use an Atmel development kit, such as an Atmel AT88CK101STK8. With this and an

integrated development environment (some can be downloaded for free, such as Atmel Studio®), you will

be able to rebuild the library, download the binary to the target, and start a debug session.

Project Integration

Integrating the library into your project is straightforward. What to modify in the physical layer modules and

in certain header files is explained in the following subchapters. The header file “includes” do not contain

paths, but only file names. Only one compilation switch to select the interface is used. The source compiles

under C99, but should also compile under ANSI C, with the exception of double slashes used for

comments.

ATECC108/ATSHA204 Firmware Library [USER GUIDE]

Atmel-8770C-CryptoAuth-ATECC108-ATSHA204-Firmware-Library-UserGuide_012014

Folder Structure

All modules reside in one folder. Because of this, you can either add the entire folder to your project and

then exclude the modules you don't need from compilation, or you can add the modules that you do need

one by one. Which modules to exclude from compilation depend on the interface you plan to use. Table 1

shows which modules to include in your project, depending on your interface. The modules in the other two

columns have to be excluded if they do not appear in the column you selected.

Table 1. Interface Modules

Porting

When porting the library to other targets or when using CPU clock speeds other than the ones provided by

the examples, certain modules have to be modified, including the physical layer modules you plan to use

(SWI or I2C) and the timer_utilities.c timer function (see “Timer Functions” on page 8).

Physical Layer Modules

To port the hardware-dependent modules for SWI or I2C to your target, you have several options:

Implement the modules from scratch.

Modify the UART or I2C module(s) provided by your target library.

Create a wrapper around your target library that matches the software interface of the

ATECC108/ATSHA204 library’s Physical layer. For instance, your target library for I2C might use

parameters of different type, number, or sequence than those in the i2c_phys.c module [e.g.,

i2c_send_bytes(uint8_t count, uint8_t *data) ].

Modify the calls to hardware-dependent functions in the hardware-independent module for the

Physical layer (sha204_swi.c / sha204_i2c.c) to match the functions in your target library. The

hardware-dependent module for I2C reflects a simple I2C peripheral, where single I2C operations can

be performed (Start, Stop, Write Byte, Read Byte, etc.). Many targets contain more sophisticated I2C

peripherals, where registers have to be loaded first with an I2C address, a Start or Stop condition, a

data buffer pointer, etc. In such cases, sha204_i2c.c has to be rewritten.

The hardware-dependent modules provided by Atmel use loop counters for timeout detection. When

porting, you can either adjust the loop counter start values, which get decremented while waiting for flags

to be set or cleared, or you can use hardware timers or timer services provided by a real-time operating

system you may be using. These values are defined in bitbang_phys.h (SWI GPIO), uart_phys.h (SWI

UART), and i2c_phys.h (I2C), respectively.

Interface SWI GPIO SWI UART I2C I2C_bitbang

Hardware

Independent File sha204_swi.c sha204_swi.c sha204_i2c.c sha204_i2c.c

Hardware

Dependent Files

bitbang_phys.c uart_phys.c i2c_phys.c i2c_phys_bitbang.c

bitbang_config.h uart_config.h i2c_phys.h i2c_phys_bitbang.h

swi_phys.h swi_phys.h

avr_compatible.h

Compilation Switch SHA204_GPIO_BITBANG SHA204_GPIO_UART SHA204_I2C SHA204_I2C_BITBANG

ATECC108/ATSHA204 Firmware Library [USER GUIDE]

Atmel-8770C-CryptoAuth-ATECC108-ATSHA204-Firmware-Library-UserGuide_012014

Communication Layer Timeout Tuning

For SWI, it can take a maximum time of 312.5μs after sending a transmit flag until the device responds.

For I2C, this time depends on the I2C clock frequency. For many AVR 8-bit CPUs, the maximum frequency

is 400kHz.

For SWI, every polling cycle takes 312.5μs, while for I2C at 400kHz, every polling cycle takes 37μs. These

values are defined as SHA204_RESPONSE_TIMEOUT in sha204_config.h. If you are running I2C at a

frequency other than 400kHz, calculate the value using the formulas below or measure it and change the

value in sha204_config.h.

Two descriptions follow about how to establish the SHA204_RESPONSE_TIMEOUT.

1. With an oscilloscope or logic analyzer, measure the time it takes for one loop iteration in the inner

do-while loop inside the sha204c_send_and_receive function or

2. If you cannot measure the time for one device polling iteration, you can derive it by establishing three

separate values:

○The transmission time for one byte.

○The transmission overhead time (for instance, setting peripheral registers or checking

peripheral status).

○The loop iteration time. Consider the following formulas:

Time to poll the device:

tpoll = tcomm + tcommoverhead + tloop

where:

tcomm(GPIO) = 312.5μs,

tcommoverhead(GPIO) = 0, (negligible)

tcomm(I2C, when I2C address gets “nacked”) = + tstart + tstop,

tcommoverhead(I2C) = texecutestart function + tdataregister write + texecutestop function,

tloop = tloop(sha204_send_and_receive), (do-while loop inside function)

I2C example, clocked at 200kHz:

tcomm(I2C, when“nacked”) = + 2.6μs + 3.6μs = 51.2μs,

tcommoverhead(I2C) = 18.6μs,

tloop(I2C) = 13.0μs,

tpoll(I2C) = 51.2μs + 18.6μs + 13.0μs = 82.8μs

I2C_address_byte · 9 clocks

I2C clock

I2C_address_byte · 9 clocks

0.2MHz

ATECC108/ATSHA204 Firmware Library [USER GUIDE]

Atmel-8770C-CryptoAuth-ATECC108-ATSHA204-Firmware-Library-UserGuide_012014

Timer Functions

The library provides two blocking timer functions, delay_10us and delay_ms. If you have hardware or

software timers available in your system, you may want to replace the library timer functions with those.

This way, you may be able to convert the provided blocking timer functions into non-blocking (interrupt

driven or task switched) ones. Be aware that because delay_ms uses a parameter of uint8_t type, this

function can only provide a delay of up to 255ms. The delay_ms function is used to read the response

buffer after a memory write or command execution delay. Both are shorter than 255ms.

Tuning

By decreasing robustness, features, and/or modularity, you can decrease code size and increase

execution speed. This chapter describes a few areas where you could start tuning the library towards

smaller code size and/or faster execution. As most of such modifications affect size and speed, they are

described in unison.

Removal of Command Marshaling Layer

This modification achieves the maximum reduction of code size, but removing the command marshaling

layer makes the library more difficult to use. It does not need any modifications of the library code.

Removal of Communication Layer

This modification probably achieves the maximum of a combined reduction of code size and increase in

speed, but at the expense of communication robustness and ease of use. It does not need any

modifications of the library code. Without the presence of the communication layer, an application has to

provide the CRC for commands it is sending and for evaluating the status byte in the response. The

application can still use any definitions contained it might need in sha204_comm.h, such as the codes for

the response status byte.

There are other ways to reduce code size and increase the speed of the communication layer. You could

remove the CRC check on responses, or you could disable retries by setting SHA204_RETRY_COUNT in

sha204_config.h to zero.

Using UART Instead of GPIO

The code space for the single-wire interface is smaller when using a UART than GPIO. Also, the code

execution is allowed to be slower than when using GPIO since a UART buffers at least one byte. Since the

maximum UART bit width is 4.34μs, the GPIO code has to be executed at a speed that allows reliable

generation of this bit. There is no such low limit in execution speed for a UART implementation.

Revision History

Doc. Rev. Date Comments

8770C 01/2014 Add I2C Interface Bit-banged.

8770B 06/2013 Add ATECC108 device and update template.

8770A 05/2011 Initial document release.

XXX

Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 | www.atmel.com

Atmel®, Atmel logo and combinations thereof, Enabling Unlimited Possibilities®, CryptoAuthentication™, AVR®, Studio®, and others are registered trademarks or

trademarks of Atmel Corporation or its subsidiaries. Other terms and product names may be trademarks of others.

DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right

is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE

ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT

SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES

FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS

BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this

document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information

contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended,

authorized, or warranted for use as components in applications intended to support or sustain life.

SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where

the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written

consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems.

Atmel products are not designed nor intended for use in military or aerospace applications or environments unless specifically designated by Atmel as military-grade. Atmel products are

not designed nor intended for use in automotive applications unless specifically designated by Atmel as automotive-grade.

Mouser Electronics

Authorized Distributor

Click to View Pricing, Inventory, Delivery & Lifecycle Information:

Atmel:

ATECC108A-MAHCZ-T ATECC108A-SSHDA-T ATECC108A-SSHDA-B ATECC108A-MAHDA-T ATECC108A-

SSHCZ-T ATECC108A-RBHCZ-T ATECC108A-SSHCZ-B