GNU Sample
**********

This is a short example of a complete Texinfo file. Copyright © 2006-2015 Daniel Otte (daniel.otte@rub.de)

About
*****

This documentation is a guide to the AVR-Crypto-Lib and ARM-Crypto-Lib. Instead of documenting the full API and each function we choose the approach of documenting the structure of the API so you know what to do when you want to use the library.

Generic stuff
*************

Requirements
============

You should have the following software tools to build the library, the version mentioned is the version used on the test system, older or newer versions may or may not work):

a recent toolchain
     for AVR targets:

     gcc for AVR (avr-gcc)
          4.3.5

     GNU binutils for AVR
          2.21

     avr-libc
          1.6.8-2

     for ARM targets:

     gcc for ARM (arm-elf-gcc)

     GNU binutils for ARM

     newlib with enabled malloc()

a flash tool to program your device
     for AVR targets:

     avrdude
          5.10

     for ARM targets:

     openocd
          0.4.0

GNU make
     3.81

ruby (for the testing system)
     1.8.7.302-2

     rubygems
          1.3.7

     serialport
          1.0.4

     getopt
          1.4.0

File organisation
=================

Build process
=============

The build process is managed by a large relative complex Makefile and a bunch of more specific Makefile-stubs (*.mk in the mkfiles directory).

make-stubs
----------

All stubs are included by the main Makefile automatically, so the addition of algorithms should not require modifications to the Makefile.

Because all stubs are included by the main Makefile you can use all features of your make system when writing them. Currently we use GNU make and we recommend using GNU make when building the crypto library.

Each algorithm implementation has its own stub. A stub looks like the following:
# Makefile for AES
ALGO_NAME := AES128_C

# comment out the following line for removement of AES from the build process
BLOCK_CIPHERS += $(ALGO_NAME)

$(ALGO_NAME)_DIR      := aes/
$(ALGO_NAME)_INCDIR   := gf256mul/ bcal/
$(ALGO_NAME)_OBJ      := aes_enc.o aes_dec.o aes_sbox.o aes_invsbox.o  \
                         aes_keyschedule.o gf256mul.o aes128_enc.o aes128_dec.o
$(ALGO_NAME)_TEST_BIN := main-aes128-test.o $(CLI_STD) $(BCAL_STD) \
                         bcal_aes128.o
$(ALGO_NAME)_NESSIE_TEST      := test nessie
$(ALGO_NAME)_PERFORMANCE_TEST := performance

The most important thing is defining an unambiguous name for the implementation, in this case it is AES128_C. The next step is chaining the implementation into a category. Uncategorized implementations will be ignored. So if you want to exclude an implementation from the build process you can simply comment out the line which chains it into a category.

The following lines declare ''Attributes'' of the implementation.

_DIR
     defines the directory where the implementation resides

_INCDIR
     defines directorys to search for additional files

_OBJ
     defines the names of the objects which shoud be considered the implementations core

_TESTBIN
     defines the names of the objects required to build the test suit

_NESSIE_TEST
     (currently unused) defines the string which should be send to the test system to perform nessie standard tests

_NESSIE_TEST
     (currently unused) defines the string which should be send to the test system to perform a performance tests

_DEF
     defines macros to use while compiling

Testing system
==============

Sizes in bits and bytes
=======================

Working with cryptographic functions involves working with different lengths. Some times you want to know it in bits, sometimes in bytes and another time in words (how long a word is must be defined by the context). To reduce confusion, frustration and to avoid bugs we suffix a length parameter with either _b, _B or _w depending on the meaning. _b means in bits and _B means in bytes (big b big word) and _w meaning words.

Symmetric primitives
********************

     [file acl_keysizes.texi not included]
     [file acl_blockciphers.texi not included]

Modes of operation
==================

     [file acl_streamciphers.texi not included]

     [file acl_hashes.texi not included]

MAC functions
=============

Pseudo random number generators (PRNGs)
=======================================

Encodings
*********

Base64
======

ASN.1
=====

Big integer functions
*********************

Asymmetric Primitives
*********************

DSA
===

RSA
===

El-Gamal
========

MQQ
===