USAGE.streamciphers

   1 ====================================
   2 =      Usage of streamciphers      =
   3 ====================================
   4
   5 Author: Daniel Otte
   6 email:  daniel.otte@rub.de
   7
   8
   9 0. Foreword
  10  This file will describe how to use the streamcipher implementations provided
  11  by this library. It will not only show how to call the cryptographic functions
  12  but also discuss a little how to build security mechanisms from that.
  13
  14 1. What a streamcipher does
  15  A streamcipher normally generates a deterministic, random looking stream of
  16  bits, known as keystream. For encryption purpose this keystream is XORed with
  17  the data stream. So decryption is exactly the same as encryption. The
  18  data-stream is XORed with the keystream giving the plaintext. So both sides
  19  need exactly the same streamcipher in the same state.
  20
  21 1.1. high frequent parameters:
  22         output-size: 8 bit, 1 bit
  23         keysize: 64 bit, 80 bit, 128 bit
  24         IVsize: 64 bit
  25
  26 2. Parts of a streamcipher
  27   * generation algorithm
  28   * initialization algorithm
  29   * state
  30  As we can see all streamciphers seem to utilize an internal state which
  31  determines the output. This state is initialized by the initialization
  32  algorithm with a key and an IV (initialization vector). It is very important
  33  for security that _never_ the same key with the same IV is used again. The
  34  IV is not required to be kept secret.
  35
  36 3. streamcipher API
  37  The API is not always consistent due to the fact that we tried to optimize the
  38  code for size (flash, heap and stack) and speed (runtime of the different
  39  components).
  40  Generally the API of the implemented streamciphers consists of:
  41
  42  *_init function, which implements the initialization
  43  *_gen  function, which implements the streamcipher algorithm and generates a
  44         keystream output
  45  *_ctx_t context type, which contains internal state information
  46
  47 3.1 look at the prototypes
  48  Generally the prototypes (defined in the *.h files) will tell you what
  49  parameter means what.
  50
  51 3.1.2 sizes in bits and bytes
  52  Working with cryptographical functions involves working with different lengths.
  53  Some times you want to know it in bits and sometimes in bytes. To reduce
  54  frustration and to avoid bugs we suffix a length parameter with either _b or
  55  _B depending on the meaning. _b means in bits and _B means in bytes
  56  (big b big word).
  57
  58 3.2. *_init function
  59  The *_init function generally takes a pointer to the key as first parameter.
  60  For ciphers where the keysize is not fixed the second parameter gives the
  61  keysize (in bits regularly) followed by a pointer to the IV and a length
  62  parameter for not fixed IV sizes (both are omitted if the algorithm does not
  63  specify IV handling, in this case a part of the key should be used as IV).
  64  The last parameter points to the context variable to fill.
  65
  66 3.3. *_gen function
  67  The *_gen function updates the internal state to which a pointer is given as
  68  parameter and returns a fixed length part of the keystream as return value.
  69
  70
  71