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 © 2011 Daniel Otte
  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 File organisation
  34 @section Build process
  35 @section Testing system
  36 @section Sizes in bits and bytes
  37  Working with cryptographic functions involves working with different
  38  lengths. Some times you want to know it in bits, sometimes in bytes and another
  39  time in words (how long a word is must be defined by the context).
  40  To reduce confusion, frustration and to avoid bugs we suffix a length
  41  parameter with either _b, _B or _w depending on the meaning.
  42  _b means in bits and _B means in bytes (big b big word) and _w meaning words.
  43
  44 @chapter Symmetric primitives
  45
  46 @section Block ciphers
  47 @subsection What a block cipher does
  48  A block cipher is a algorithm which turn an input of fixed length into an
  49  output of the same length (enciphering or encrypting). The transformation is
  50  specified by a key which has to be of a fixed length, or a length of a given
  51  set or range.
  52  Generally there is also an algorithm which turns the output back to the
  53  previous input (deciphering or decrypting) when supplied with the same key.
  54
  55 @subsection List of available block ciphers
  56 This is a list of the currently supported block ciphers:
  57 @itemize @bullet
  58   @item AES (Advanced Encryption Standard)
  59   @item Camellia
  60   @item CAST5
  61   @item CAST6
  62   @item CS-Cipher
  63   @item DES (Data Encryption Standard)
  64   @item Khazad
  65   @item Noekeon
  66   @item Present
  67   @item RC5
  68   @item RC6
  69   @item Seed
  70   @item Serpent (AES finalist)
  71   @item Shacal1
  72   @item Shacal2
  73   @item Skipjack
  74   @item TDES (Tripple DES)
  75   @item Threefish
  76   @item XTEA
  77 @end itemize
  78
  79 @subsection high frequent parameters:
  80   block size: 64 bits, 128 bits
  81   key size: 64 bits, 80 bits, 128 bits, 192 bits, 256 bits
  82   (note that some block ciphers use different sizes)
  83
  84 @subsection Parts of a block cipher
  85 @itemize @bullet
  86   @item encryption algorithm
  87   @item decryption algorithm
  88   @item mostly a set of subkeys
  89   @item mostly a keyschedule which generates the subkeys from the supplied key.
  90 @end itemize
  91  As we can see here a block cipher normally has an algorithm besides the
  92  encryption and decryption algorithm, which we call keyschedule.
  93  Mostly the encryption and decryption algorithm consist of multiple rounds,
  94  where each round (and sometimes between rounds) subkeys are needed to modify
  95  the data. This subkeys are generated by the keyschedule and stored in a state
  96  or context variable.
  97  Note that not all algorithms need a pregenerated context, sometimes it is easy
  98  to generate the subkeys "on the fly" so there is not always the need of a
  99  context variable. In this case instead of a context the actual key is passed
 100  to the encryption and decryption function.
 101
 102 @subsection API of block ciphers
 103  The API is not always consistent due to the fact that we tried to optimize the
 104  code for size (flash, heap and stack) and speed (runtime of the different
 105  components).
 106  Generally the API of the implemented block ciphers consists of:
 107 @itemize @bullet
 108  @item *_init function, which implements the keyschedule
 109  @item *_enc  function, which implements the encryption algorithm
 110  @item *_dec  function, which implements the decryption algorithm
 111  @item *_free function, which frees memory allocated for the keyschedule
 112  @item *_ctx_t context type, which can contain a keyschedule and other information
 113 @end itemize
 114 @subsubsection *_init function
 115  The *_init function generally takes a pointer to the key as first parameter.
 116  For ciphers where the keysize is not fixed the second parameter gives the
 117  keysize (in bits regularly) and the last parameter points to the context
 118  variable to fill.
 119  For some ciphers there are additional parameters like the number of rounds,
 120  these parameters generally occur before the context pointer.
 121
 122 @subsubsection *_enc and *_dec functions
 123  The encryption and decryption function of a specific algorithm normally do not
 124  differ in their parameters. Generally these functions take a pointer to the
 125  block to operate on. Some ciphers allow to specify two blocks, where the first
 126  one will be written to and the second will contain the source block. The two
 127  blocks may overlap or be the same. Most ciphers have only one block pointer.
 128  The block specified by the pointer is encrypted (if the *_enc function is
 129  called) or decrypted (if the *_dec function is called).
 130  The last parameter specifies either the key direct (with a pointer to it) or
 131  is a pointer to a context created with the *_init function.
 132  It is guaranteed that the context is in the same state as before the *_enc or
 133  *_dec function call. Most *_enc and *_dec functions do not modify the context
 134  at all, but some do for reducing dynamic memory requirements. So here are some
 135  limitations to the reentrant property.
 136
 137 @subsubsection *_free function
 138  A *_free function is only provided where needed (so most ciphers do not have
 139  it). It is used to free memory dynamically allocated by the *_init function.
 140
 141 @subsubsection *_ctx_t type
 142  A variable of the *_ctx_t type may hold information needed by the *_enc or
 143  *_dec function. It is initialized by the *_init function. If dynamic memory is
 144  allocated by the *_init function also a *_free function is provided which frees
 145  the allocated memory. An initialized *_ctx_t variable may not be copied as it
 146  may contains pointers to itself.
 147
 148 @section Block cipher abstraction layer (BCAL)
 149 The BlockCipeherAbstractionLayer (BCAL) is an abstraction layer which allows
 150 usage of all implemented block ciphers in a simple way. It abstracts specific
 151 function details and is suitable for implementations which want to be flexible
 152 in the choosing of specific block ciphers. Another important aspect is that this
 153 abstraction layer enables the implementation of block cipher operating modes
 154 independently from concrete ciphers. It is very simple to use and reassembles
 155 the API used to implement individual ciphers.
 156
 157 The main component is a block cipher descriptor which contains the details of
 158 the individual ciphers.
 159
 160 Care should be taken when choosing a specific keysize. It may be the case that
 161 the chosen keysize is not compatible with the chosen block cipher.
 162
 163
 164 @subsection Parts of BCAL
 165 The BCAL is split up in different parts:
 166 @itemize @bullet
 167   @item BCAL declaration for BCAL decriptors
 168   @item algorithm specific definitions of BCAL decriptors
 169   @item BCAL basic context type
 170   @item BCAL basic functions
 171 @end itemize
 172
 173 @subsubsection BCAL declaration for BCAL decriptors
 174 The BCAL descriptor is a structure which is usually placed in FLASH or ROM since
 175 modification is unnecessary. It contains all information required to use the
 176 according block cipher.
 177
 178 @verbatim
 179 typedef struct {
 180         uint8_t  type; /* 1==block cipher */
 181         uint8_t  flags;
 182         PGM_P    name;
 183         uint16_t ctxsize_B;
 184         uint16_t blocksize_b;
 185         bc_init_fpt init;
 186         bc_enc_fpt  enc;
 187         bc_dec_fpt  dec;
 188         bc_free_fpt free;
 189         PGM_VOID_P valid_keysize_desc;
 190 } bcdesc_t; /* block cipher descriptor type */
 191 @end verbatim
 192
 193 @table @var
 194   @item type
 195   should be set to @samp{1} to indicate that this descriptor is for a
 196   block cipher.
 197
 198  @item flags
 199  defines what kind of init function is provided and what kind of decrypt
 200  and encrypt functions are provided.
 201
 202  @table @asis
 203  @item bit 0
 204  if clear (@samp{0}) designates an init function with fixed key length, so
 205  the length parameter is omitted (@code{init(void* ctx, void* key)}).
 206
 207  if set (@samp{1}) designates an init function which requires an explicit
 208  keysize argument (@code{init(void*ctx, uint16_t length_b, void* key)}).
 209
 210  @item bit 1
 211  if clear (@samp{0}) designates that the encryption function transforms the
 212  plaintext block in place to the ciphertext (@code{enc(void* block, void* ctx)}).
 213
 214  if set (@samp{1}) designates that the encryption function offers a dedicated
 215  pointers for input and output. The two regions may be the same
 216  (@code{enc(void* out, void* in, void*ctx)}).
 217
 218  @item bit 2
 219  if clear (@samp{0}) designates that the decryption function transforms the
 220  ciphertext block in place to the plaintext (@code{dec(void* block, void* ctx)}).
 221
 222  if set (@samp{1}) designates that the decryption function offers a dedicated
 223  pointers for input and output. The two regions may be the same
 224  (@code{dec(void* out, void* in, void*ctx)}).
 225  @end table
 226
 227  @item name
 228  is a pointer to a zero terminated ASCII string giving the name of the
 229  implemented primitive. On targets with Harvard-architecture the string resides
 230  in code memory (FLASH, ROM, ...).
 231
 232  @item ctxsize_B
 233  is the number of bytes which should be allocated for the context variable.
 234
 235  @item blocksize_b
 236  is the number of bits on which the encrypt and decrypt function work on.
 237
 238  @item init
 239  is a pointer to the init function (see @samp{flags} how the init function
 240  should be called). If there is no init function this field is NULL.
 241
 242  @item enc
 243  is a pointer to the encryption function (see @samp{flags} how the encryption
 244  function should be called).
 245
 246  @item dec
 247  is a pointer to the decryption function (see @samp{flags} how the decryption
 248  function should be called).
 249
 250  @item free
 251  is a pointer to the free function or NULL if there is no free function.
 252
 253  @item valid_keysize_desc
 254  is a pointer to a keysize descriptor structure which is used to validate
 255  that the chosen keysize is valid
 256 @end table
 257
 258
 259
 260 @section Modes of operation
 261
 262 @section Stream ciphers
 263 @subsection List of available stream ciphers
 264 @subsection API of stream ciphers
 265 @subsection Stream cipher abstraction layer (SCAL)
 266
 267 @section Hash functions
 268 @subsection List of available hash functions
 269 @subsection API of hash functions
 270 @subsection Hash function abstraction layer (HFAL)
 271
 272 @section MAC functions
 273 @section Pseudo random number generators (PRNGs)
 274
 275 @chapter Encodings
 276 @section Base64
 277 @section ASN.1
 278
 279 @chapter Big integer functions
 280
 281 @chapter Asymmetric Primitives
 282 @section DSA
 283 @section RSA
 284 @section El-Gamal
 285 @section MQQ
 286
 287 @bye
 288