doc/acl-guide.texi

   1 \input texinfo  @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename acl-manual.info
   4 @settitle AVR/ARM-Crypto-Lib Manual 1.0
   5 @c %**end of header
   6
   7 @copying
   8 This is a short example of a complete Texinfo file.
   9 Copyright © 2006-2015 Daniel Otte (@email{bg@@nerilex.org})
  10 @end copying
  11
  12 @titlepage
  13 @title AVR/ARM-Crypto-Lib Manual 1.0
  14 @page
  15 @vskip 0pt plus 1filll
  16 @insertcopying
  17 @end titlepage
  18 @c Output the table of the contents at the beginning.
  19 @contents
  20 @ifnottex
  21 @node Top
  22 @top GNU Sample
  23 @insertcopying
  24 @end ifnottex
  25
  26 @chapter About
  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
  30 to use the library.
  31
  32 @chapter Generic stuff
  33 @section Requirements
  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
  36 or may not work):
  37 @table @asis
  38   @item a recent toolchain
  39   for AVR targets:
  40   @table @asis
  41     @item gcc for AVR (avr-gcc)
  42     4.3.5
  43     @item GNU binutils for AVR
  44     2.21
  45     @item avr-libc
  46     1.6.8-2
  47   @end table
  48   for ARM targets:
  49   @table @asis
  50     @item gcc for ARM (arm-elf-gcc)
  51     @item GNU binutils for ARM
  52     @item newlib with enabled malloc()
  53   @end table
  54   @item a flash tool to program your device
  55   for AVR targets:
  56   @table @asis
  57     @item avrdude
  58     5.10
  59   @end table
  60   for ARM targets:
  61   @table @asis
  62     @item openocd
  63     0.4.0
  64   @end table
  65
  66   @item GNU make
  67   3.81
  68   @item ruby (for the testing system)
  69   1.8.7.302-2
  70   @table @asis
  71     @item rubygems
  72     1.3.7
  73     @item serialport
  74     1.0.4
  75     @item getopt
  76     1.4.0
  77   @end table
  78 @end table
  79
  80 @section File organisation
  81
  82
  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}
  86 directory).
  87
  88
  89
  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.
  93
  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.
  97
  98 Each algorithm implementation has its own stub. A stub looks like the following:
  99 @verbatim
 100 # Makefile for AES
 101 ALGO_NAME := AES128_C
 102
 103 # comment out the following line for removement of AES from the build process
 104 BLOCK_CIPHERS += $(ALGO_NAME)
 105
 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) \
 111                          bcal_aes128.o
 112 $(ALGO_NAME)_NESSIE_TEST      := test nessie
 113 $(ALGO_NAME)_PERFORMANCE_TEST := performance
 114 @end verbatim
 115
 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
 121 a category.
 122
 123 The following lines declare ''Attributes'' of the implementation.
 124 @table @var
 125 @item _DIR
 126   defines the directory where the implementation resides
 127 @item _INCDIR
 128   defines directorys to search for additional files
 129 @item _OBJ
 130   defines the names of the objects which shoud be considered the implementations
 131   core
 132 @item _TESTBIN
 133   defines the names of the objects required to build the test suit
 134 @item _NESSIE_TEST
 135   (currently unused) defines the string which should be send to the test system
 136   to perform nessie standard tests
 137 @item _NESSIE_TEST
 138   (currently unused) defines the string which should be send to the test system
 139   to perform a performance tests
 140 @item _DEF
 141   defines macros to use while compiling
 142 @end table
 143
 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.
 152
 153 @chapter Symmetric primitives
 154 @include acl_keysizes.texi
 155 @include acl_blockciphers.texi
 156
 157 @section Modes of operation
 158
 159 @include acl_streamciphers.texi
 160
 161 @include acl_hashes.texi
 162
 163 @section MAC functions
 164 @section Pseudo random number generators (PRNGs)
 165
 166 @chapter Encodings
 167 @section Base64
 168 @section ASN.1
 169
 170 @chapter Big integer functions
 171
 172 @chapter Asymmetric Primitives
 173 @section DSA
 174 @section RSA
 175 @section El-Gamal
 176 @section MQQ
 177
 178 @bye
 179