USAGE.hashfunctions

   1 ===================================
   2 =    Usage of hash functions      =
   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 hash function implementations provided
  11   by this library.
  12
  13 1. What a hash function does
  14  A hash function is an algorithm to map an arbitrary long message (in the form
  15  of a bit string) to a fixed length message digest or hash value.
  16  The hash function aims to be collision free, which means that it is not
  17  practicable to find two messages with the same hash value (although this
  18  collision must exist). Also it should not be practicable to construct a
  19  message which maps to a given hash value.
  20
  21
  22 1.1. high frequent parameters:
  23   block size: 512 bits
  24   hash value size: 128 bits, 160 bits, 224 bits, 256 bits, 384 bits, 512 bits
  25
  26 2. Parts of a hash function
  27   * initialization function
  28   * compression algorithm
  29   * finalization function
  30
  31 3. hash function API
  32  The API is not always consistent due to the fact that we tried to optimize the
  33  code for size (flash, heap and stack) and speed (runtime of the different
  34  components).
  35  Generally the API of the implemented block ciphers consists of:
  36
  37  *_init      function, which implements the initialisation of the context
  38  *_nextBlock function, which implements the compression algorithm
  39  *_lastBlock function, which implements the the padding algorithm
  40  *_ctx2hash  function, which turns a context into an actual hash value
  41  *_ctx_t     context type, which can contains the state of a hashing process
  42
  43 3.1 look at the prototypes
  44  Generally the prototypes (defined in the *.h files) will tell you what
  45  parameter means what.
  46
  47 3.1.2 sizes in bits and bytes
  48  Working with cryptographic functions involves working with different
  49  lengths. Some times you want to know it in bits and sometimes in bytes. To
  50  reduce frustration and to avoid bugs we suffix a length parameter with either
  51  _b or _B depending on the meaning. _b means in bits and _B means in bytes
  52  (big b big word).
  53
  54 3.2. *_init function
  55  The *_init function generally takes a pointer to the context as parameter.
  56  This function initializes the context with algorithm specific values.
  57
  58 3.3. *_nextBlock function
  59  The *_nextBlock function is the core of each hash function. It updates the hash
  60  state with a given message block. So this function uses a context pointer and
  61  a message pointer as parameters. The size of a message block is fixed for each
  62  hash function (mostly 512 bit). For the last block of a messages which may be
  63  smaller than the blocksize you have to use the *_lastBlock function described
  64  below.
  65
  66 3.4 *_lastBlock function
  67  The *_lastBlock function finalizes the context with the last bits of a
  68  message. Since the last block is not required to have the blocksize you have
  69  to specify the length of the last block (normally in bits). This function
  70  performs the padding and final processing.
  71
  72 3.5. *_ctx2hash function
  73  The *_ctx2hash function turns a given hash context into an actual hash value.
  74  If multiple sized hash value may be created from a context it is necessary to
  75  give the the size of the hash value as parameter.
  76