1 \input texinfo @c -*-texinfo-*-
3 @setfilename acl-manual.info
4 @settitle AVR/ARM-Crypto-Lib Manual 1.0
8 This is a short example of a complete Texinfo file.
9 Copyright © 2011 Daniel Otte (@email{daniel.otte@@rub.de})
13 @title AVR/ARM-Crypto-Lib Manual 1.0
15 @vskip 0pt plus 1filll
18 @c Output the table of the contents at the beginning.
27 This documentation is a guide to the AVR-Crypto-Lib and ARM-Crypto-Lib.
28 Instead of documenting the full API and each function we choose the approach
29 of documenting the structure of the API so you know what to do when you want
32 @chapter Generic stuff
34 You should have the following software tools to build the library, the version
35 mentioned is the version used on the test system, older or newer versions may
38 @item a recent toolchain
41 @item gcc for AVR (avr-gcc)
43 @item GNU binutils for AVR
50 @item gcc for ARM (arm-elf-gcc)
51 @item GNU binutils for ARM
52 @item newlib with enabled malloc()
54 @item a flash tool to program your device
68 @item ruby (for the testing system)
80 @section File organisation
83 @section Build process
84 The build process is managed by a large relative complex @file{Makefile} and
85 a bunch of more specific Makefile-stubs (@file{*.mk} in the @file{mkfiles}
90 @subsection make-stubs
91 All stubs are included by the main Makefile automatically, so the addition of
92 algorithms should not require modifications to the Makefile.
94 Because all stubs are included by the main Makefile you can use all features
95 of your make system when writing them. Currently we use GNU make and we
96 recommend using GNU make when building the crypto library.
98 Each algorithm implementation has its own stub. A stub looks like the following:
101 ALGO_NAME := AES128_C
103 # comment out the following line for removement of AES from the build process
104 BLOCK_CIPHERS += $(ALGO_NAME)
106 $(ALGO_NAME)_DIR := aes/
107 $(ALGO_NAME)_INCDIR := gf256mul/ bcal/
108 $(ALGO_NAME)_OBJ := aes_enc.o aes_dec.o aes_sbox.o aes_invsbox.o \
109 aes_keyschedule.o gf256mul.o aes128_enc.o aes128_dec.o
110 $(ALGO_NAME)_TEST_BIN := main-aes128-test.o $(CLI_STD) $(BCAL_STD) \
112 $(ALGO_NAME)_NESSIE_TEST := test nessie
113 $(ALGO_NAME)_PERFORMANCE_TEST := performance
116 The most important thing is defining an unambiguous name for the implementation,
117 in this case it is AES128_C.
118 The next step is chaining the implementation into a category. Uncategorized
119 implementations will be ignored. So if you want to exclude an implementation
120 from the build process you can simply comment out the line which chains it into
123 The following lines declare ''Attributes'' of the implementation.
126 defines the directory where the implementation resides
128 defines directorys to search for additional files
130 defines the names of the objects which shoud be considered the implementations
133 defines the names of the objects required to build the test suit
135 (currently unused) defines the string which should be send to the test system
136 to perform nessie standard tests
138 (currently unused) defines the string which should be send to the test system
139 to perform a performance tests
141 defines macros to use while compiling
144 @section Testing system
145 @section Sizes in bits and bytes
146 Working with cryptographic functions involves working with different
147 lengths. Some times you want to know it in bits, sometimes in bytes and another
148 time in words (how long a word is must be defined by the context).
149 To reduce confusion, frustration and to avoid bugs we suffix a length
150 parameter with either _b, _B or _w depending on the meaning.
151 _b means in bits and _B means in bytes (big b big word) and _w meaning words.
153 @chapter Symmetric primitives
154 @include acl_keysizes.texi
155 @include acl_blockciphers.texi
157 @section Modes of operation
159 @include acl_streamciphers.texi
161 @include acl_hashes.texi
163 @section MAC functions
164 @section Pseudo random number generators (PRNGs)
170 @chapter Big integer functions
172 @chapter Asymmetric Primitives