μNaCl – The Networking and Cryptography library for microcontrollers


AVRNaCl – μNaCl for AVR ATmega


API and supported primitives

AVRNaCl implements the NaCl C API. The only difference between the NaCl C API and the API of AVRNaCl is that lengths of inputs are not passed as 64-bit unsigned integers, but as 16-bit unsigned integers (datatype crypto_uint16). For detailed documentation of the NaCl C API see the NaCl website. The following functions are currently supported by AVRNaCl. Functions marked in red use the additional randombytes function. The implementation of this function which is currently included in the AVRNacl archive is completely deterministic and must not be used to generate cryptographic keys. The only reason to include this function is for testing.


Build instructions

Installing an AVR GNU toolchain

In order to build AVRNaCl you need an AVR GNU toolchain installed. On a Debian (jessie) systems this is easily achieved by adding the following line to the file /etc/apt/sources.list:

deb http://www.emdebian.org/debian jessie main

and then the following commands (as root):

apt-get update
apt-get install gcc-avr binutils-avr avr-libc avrdude

Building AVRNaCl

First download and unpack AVRNaCl:

wget http://munacl.cryptojedi.org/data/avrnacl-20140813.tar.bz2
tar xjvf avrnacl-20140813.tar.bz2
cd avrnacl-20140813/

Now edit the file called config and set the following variables (in the example set to their default values):

TARGET_DEVICE=atmega2560
CPUFREQ=16000000
CC=/usr/bin/avr-gcc
OBJCOPY=/usr/bin/avr-objcopy
AR=/usr/bin/avr-ar
STRIP=/usr/bin/avr-strip

Please make sure that the value of TARGET_DEVICE matches the -mmcu flag expected by gcc for your target microcontroller and that the value of CPUFREQ matches the CPU frequency of the target microcontroller. If you installed the AVR GNU toolchain as described above, the paths of avr-gcc, avr-objcopy, avr-ar, and avr-strip should be correct; otherwise edit them to match your system.
Now you are ready to build AVRNaCl by running

make

This will build different versions of AVRNaCl:

The header file for all these versions is the file avrnacl.h.


Testing and benchmarking

The make process described above also builds various hex files that run tests and benchmarks of AVRNaCl. AVRNaCl comes with three scripts that automate the process of programming a microcontroller with these tests and writing the results to log files. We use the Arduino MEGA development board with an ATmega2560 to run those tests and benchmarks. Some of the tests may not work on an ATmega with less flash and RAM (even though the library will work); the reason is that testvectors need additional space in RAM and the test code needs additional space in flash. To run tests and benchmarks first edit the file named config to set the following variables

DEVICE_FILE=/dev/ttyACM0
TESTLOGFILE=test.log
SPEEDLOGFILE=speed.log
STACKLOGFILE=stack.log

The DEVICE_FILE variable sets the serial device file of the development board. When connecting the Arduino MEGA through USB, this is most likely going to be the default value /dev/ttyACM0. The other three variables set output file names of the test, the speed benchmark, and the stack benchmark, respecitvely.
To run tests of all primitives of all implementations of AVRNaCl, simply run

./run_test.sh

This test will take about 2.5 hours and the results will be printed to the file configured by the variable TESTLOGFILE in config (by default test.log). It is also possible to run tests of only one implementation or only one primitive of one implementation. For example, to only test the "fast" implementation, run

./run_test.sh fast
To test only crypto_stream_salsa20 of the "small" implementation, run

./run_test.sh small crypto_stream_salsa20

Similarly, the script run_speed.sh performs a speed benchmarks and prints results to the file configured in the SPEEDLOGFILE variable and the script run_stack.sh performs stack benchmarks and prints results to the file configured in the STACKLOGFILE variable.