doc/acl_blockciphers.texi

   1 @c acl_blockcipher.texi
   2
   3 @section Block ciphers
   4  A block cipher is a algorithm which turns an input of fixed length into an
   5  output of the same length (enciphering or encrypting). The transformation is
   6  specified by a key which has to be of a fixed length, or a length of a given
   7  set or range.
   8  Generally there is also an algorithm which turns the output back to the
   9  previous input (deciphering or decrypting) when supplied with the same key.
  10
  11 @subsection List of available block ciphers
  12 This is a list of the currently supported block ciphers:
  13 @itemize @bullet
  14   @item AES (Advanced Encryption Standard)
  15   @item Camellia
  16   @item CAST5
  17   @item CAST6
  18   @item CS-Cipher
  19   @item DES (Data Encryption Standard)
  20   @item Khazad
  21   @item Noekeon
  22   @item Present
  23   @item RC5
  24   @item RC6
  25   @item Seed
  26   @item Serpent (AES finalist)
  27   @item Shacal1
  28   @item Shacal2
  29   @item Skipjack
  30   @item TDES (Tripple DES)
  31   @item Threefish
  32   @item XTEA
  33 @end itemize
  34
  35 @subsection high frequent parameters:
  36 @table @asis
  37   @item block size
  38   64 bits, 128 bits
  39   @item key size
  40   64 bits, 80 bits, 128 bits, 192 bits, 256 bits
  41   (note that some block ciphers use different sizes)
  42 @end table
  43
  44 @subsection Parts of a block cipher
  45 @itemize @bullet
  46   @item encryption algorithm
  47   @item decryption algorithm
  48   @item mostly a set of subkeys
  49   @item mostly a keyschedule which generates the subkeys from the supplied key.
  50 @end itemize
  51  As we can see here a block cipher normally has an algorithm besides the
  52  encryption and decryption algorithm, which we call keyschedule.
  53  Mostly the encryption and decryption algorithm consist of multiple rounds,
  54  where each round (and sometimes between rounds) subkeys are needed to modify
  55  the data. This subkeys are generated by the keyschedule and stored in a state
  56  or context variable.
  57  Note that not all algorithms need a pregenerated context, sometimes it is easy
  58  to generate the subkeys "on the fly" so there is not always the need of a
  59  context variable. In this case instead of a context the actual key is passed
  60  to the encryption and decryption function.
  61
  62 @subsection API of block ciphers
  63  The API is not always consistent due to the fact that we tried to optimize the
  64  code for size (flash, heap and stack) and speed (runtime of the different
  65  components).
  66  Generally the API of the implemented block ciphers consists of:
  67 @table @code
  68  @item *_init
  69  function, which implements the keyschedule
  70  @item *_enc
  71  function, which implements the encryption algorithm
  72  @item *_dec
  73  function, which implements the decryption algorithm
  74  @item *_free
  75  function, which frees memory allocated for the keyschedule
  76  @item *_ctx_t
  77  context type, which can contain a keyschedule and other information
  78 @end table
  79 @subsubsection @code{*_init} function
  80  The @code{*_init} function generally takes a pointer to the key as first parameter.
  81  For ciphers where the keysize is not fixed the second parameter gives the
  82  keysize (in bits regularly) and the last parameter points to the context
  83  variable to fill.
  84  For some ciphers there are additional parameters like the number of rounds,
  85  these parameters generally occur before the context pointer.
  86
  87 @subsubsection @code{*_enc} and @code{*_dec} functions
  88  The encryption and decryption function of a specific algorithm normally do not
  89  differ in their parameters. Generally these functions take a pointer to the
  90  block to operate on. Some ciphers allow to specify two blocks, where the first
  91  one will be written to and the second will contain the source block. The two
  92  blocks may overlap or be the same. Most ciphers have only one block pointer.
  93  The block specified by the pointer is encrypted (if the @code{*_enc} function is
  94  called) or decrypted (if the @code{*_dec} function is called).
  95  The last parameter specifies either the key direct (with a pointer to it) or
  96  is a pointer to a context created with the @code{*_init} function.
  97  It is guaranteed that the context is in the same state as before the *_enc or
  98  @code{*_dec} function call. Most @code{*_enc} and @code{*_dec} functions do not modify the context
  99  at all, but some do for reducing dynamic memory requirements. So here are some
 100  limitations to the reentrant property.
 101
 102 @subsubsection @code{*_free} function
 103  A @code{*_free} function is only provided where needed (so most ciphers do not have
 104  it). It is used to free memory dynamically allocated by the @code{*_init} function.
 105
 106 @subsubsection *_ctx_t type
 107  A variable of the @code{*_ctx_t} type may hold information needed by the @code{*_enc} or
 108  @code{*_dec} function. It is initialized by the @code{*_init} function. If dynamic memory is
 109  allocated by the @code{*_init} function also a @code{*_free} function is provided which frees
 110  the allocated memory. An initialized @code{*_ctx_t} variable may not be copied as it
 111  may contains pointers to itself.
 112
 113 @section Block cipher abstraction layer (BCAL)
 114 The BlockCipeherAbstractionLayer (BCAL) is an abstraction layer which allows
 115 usage of all implemented block ciphers in a simple way. It abstracts specific
 116 function details and is suitable for implementations which want to be flexible
 117 in the choosing of specific block ciphers. Another important aspect is that this
 118 abstraction layer enables the implementation of block cipher operating modes
 119 independently from concrete ciphers. It is very simple to use and reassembles
 120 the API used to implement individual ciphers.
 121
 122 The main component is a block cipher descriptor which contains the details of
 123 the individual ciphers.
 124
 125 Care should be taken when choosing a specific keysize. It may be the case that
 126 the chosen keysize is not compatible with the chosen block cipher.
 127
 128
 129 @subsection Parts of BCAL
 130 The BCAL is split up in different parts:
 131 @itemize @bullet
 132   @item BCAL declaration for BCAL decriptors
 133   @item algorithm specific definitions of BCAL decriptors
 134   @item BCAL basic context type
 135   @item BCAL basic functions
 136 @end itemize
 137
 138 @subsection BCAL declaration for BCAL decriptors
 139 The BCAL descriptor is a structure which is usually placed in FLASH or ROM since
 140 modification is unnecessary. It contains all information required to use the
 141 according block cipher.
 142
 143 @verbatim
 144 typedef struct {
 145         uint8_t  type; /* 1==block cipher */
 146         uint8_t  flags;
 147         PGM_P    name;
 148         uint16_t ctxsize_B;
 149         uint16_t blocksize_b;
 150         bc_init_fpt init;
 151         bc_enc_fpt  enc;
 152         bc_dec_fpt  dec;
 153         bc_free_fpt free;
 154         PGM_VOID_P valid_keysize_desc;
 155 } bcdesc_t; /* block cipher descriptor type */
 156 @end verbatim
 157
 158 @table @var
 159   @item type
 160   should be set to @samp{1} to indicate that this descriptor is for a
 161   block cipher.
 162
 163  @item flags
 164  defines what kind of init function is provided and what kind of decrypt
 165  and encrypt functions are provided.
 166
 167  @table @asis
 168  @item bit 0
 169  if clear (@samp{0}) designates an init function with fixed key length, so
 170  the length parameter is omitted (@code{init(void* ctx, void* key)}).
 171
 172  if set (@samp{1}) designates an init function which requires an explicit
 173  keysize argument (@code{init(void*ctx, uint16_t length_b, void* key)}).
 174
 175  @item bit 1
 176  if clear (@samp{0}) designates that the encryption function transforms the
 177  plaintext block in place to the ciphertext (@code{enc(void* block, void* ctx)}).
 178
 179  if set (@samp{1}) designates that the encryption function offers a dedicated
 180  pointers for input and output. The two regions may be the same
 181  (@code{enc(void* out, void* in, void*ctx)}).
 182
 183  @item bit 2
 184  if clear (@samp{0}) designates that the decryption function transforms the
 185  ciphertext block in place to the plaintext (@code{dec(void* block, void* ctx)}).
 186
 187  if set (@samp{1}) designates that the decryption function offers a dedicated
 188  pointers for input and output. The two regions may be the same
 189  (@code{dec(void* out, void* in, void*ctx)}).
 190  @end table
 191
 192  @item name
 193  is a pointer to a zero terminated ASCII string giving the name of the
 194  implemented primitive. On targets with Harvard-architecture the string resides
 195  in code memory (FLASH, ROM, ...).
 196
 197  @item ctxsize_B
 198  is the number of bytes which should be allocated for the context variable.
 199
 200  @item blocksize_b
 201  is the number of bits on which the encrypt and decrypt function work on.
 202
 203  @item init
 204  is a pointer to the init function (see @samp{flags} how the init function
 205  should be called). If there is no init function this field is NULL.
 206
 207  @item enc
 208  is a pointer to the encryption function (see @samp{flags} how the encryption
 209  function should be called).
 210
 211  @item dec
 212  is a pointer to the decryption function (see @samp{flags} how the decryption
 213  function should be called).
 214
 215  @item free
 216  is a pointer to the free function or NULL if there is no free function.
 217
 218  @item valid_keysize_desc
 219  is a pointer to a keysize descriptor structure which is used to validate
 220  that the chosen keysize is valid
 221 @end table
 222
 223 @subsection BCAL-Basic context
 224 Besides the context types for individual ciphers there is a generic context
 225 type for BCAL. This is the context to use when using BCAL based functions.
 226 The BCAL context has the following structure:
 227 @verbatim
 228 typedef struct{
 229         bcdesc_t* desc_ptr;
 230         uint16_t  keysize;
 231         void*     ctx;
 232 } bcgen_ctx_t;
 233 @end verbatim
 234 @table @code
 235 @item desc_ptr
 236 a pointer to the BCAL descriptor
 237 @item keysize
 238 the chosen keysize
 239 @item ctx
 240 pointer to the cipher specific context
 241 @end table
 242
 243
 244
 245 @subsection BCAL-Basic
 246 BCAL-Basic provides the basic features of an block cipher on top of the
 247 BCAL. To use it you simply have to include the algorithms you want to use,
 248 the BCAL descriptor file and of course the BCAL-Basic implementation.
 249
 250 The following functions are provided:
 251 @subsubsection @code{bcal_cipher_init}
 252 @code{uint8_t bcal_cipher_init(const bcdesc_t* cipher_descriptor, const void* key, uint16_t keysize_b, bcgen_ctx_t* ctx)}
 253  this function initializes a BCAL context based on the given BCAL descriptor
 254  pointer (first parameter) with a given key (second parameter) of a given length
 255  (third parameter). The context to initialize is designated by the pointer
 256  passed as fourth parameter.
 257
 258  If everything works fine @samp{0} is returned. In the case something fails
 259  the following codes are returned:
 260 @table @samp
 261   @item 1
 262   The specified keysize is not available with this cipher
 263   @item 2
 264   It was not possible to allocate enough memory to hold the key.
 265   (This is returned when there is no actual init function and you ran out
 266   of memory)
 267   @item 3
 268   It was not possible to allocate enough memory to hold the context variable
 269   for the selected cipher.
 270 @end table
 271
 272 @subsubsection @code{bcal_cipher_free}
 273 @code{void bcal_cipher_free(bcgen_ctx_t* ctx)} this function frees the memory
 274 allocated by the init function and should be called whenever you are finished
 275 with BCAL context. It automatically also calls the @code{free} function if
 276 necessary.
 277
 278 @subsubsection @code{bcal_cipher_enc}
 279 @code{void bcal_cipher_enc(void* block, const bcgen_ctx_t* ctx)}
 280 this function encrypts a block in-place using a given BCAL contex.
 281
 282 @subsubsection @code{bcal_cipher_dec}
 283 @code{void bcal_cipher_dec(void* block, const bcgen_ctx_t* ctx)}
 284 this function decrypts a block in-place using a given BCAL contex.
 285
 286 @subsubsection @code{bcal_cipher_getBlocksize_b}
 287 @code{uint16_t bcal_cipher_getBlocksize_b(const bcdesc_t* desc)}
 288 this function returns the block size of a given cipher by using the BCAL
 289 descriptor (to which a pointer must be passed).
 290
 291 @subsubsection @code{bcal_cipher_getKeysizeDesc}
 292 @code{PGM_VOID_P bcal_cipher_getKeysizeDesc(const bcdesc_t* desc)}
 293 this function returns a pointer to the keysize descriptor of a given cipher by
 294 using the BCAL descriptor (to which a pointer must be passed).
 295
 296
 297