doc/acl_hashes.texi

   1 @c acl_hashes.texi
   2
   3 @section Hash functions
   4  A hash function is an algorithm to map an arbitrary long message (in the form
   5  of a bit string) to a fixed length message digest or hash value.
   6  The hash function aims to be collision free, which means that it is not
   7  practicable to find two messages with the same hash value (although this
   8  collision must exist). Also it should not be practicable to construct a
   9  message which maps to a given hash value.
  10
  11 @subsection List of available hash functions
  12  The following hash functions are currently implemented:
  13 @itemize @bullet
  14   @item Blake
  15   @item BlueMidnightWish
  16   @item CubeHash
  17   @item Echo
  18   @item Grøstl
  19   @item Keccak
  20   @item MD5
  21   @item SHA-256
  22   @item SHA-1
  23   @item Shabal
  24   @item Skein
  25 @end itemize
  26
  27 @subsection High frequent parameters:
  28 @table @asis
  29   @item block size
  30   512 bits
  31   @item hash value size
  32   128 bits, 160 bits, 224 bits, 256 bits, 384 bits, 512 bits
  33 @end table
  34
  35
  36 @subsection Parts of a hash function
  37 @itemize @bullet
  38   @item initialization function
  39   @item compression algorithm
  40   @item finalization function
  41 @end itemize
  42
  43 @subsection hash function API
  44  The API is not always consistent due to the fact that we tried to optimize the
  45  code for size (flash, heap and stack) and speed (runtime of the different
  46  components).
  47  Generally the API of the implemented block ciphers consists of:
  48 @table @code
  49  @item *_init
  50  function, which implements the initialisation of the context
  51  @item *_nextBlock
  52  function, which implements the compression algorithm
  53  @item *_lastBlock
  54  function, which implements the the padding algorithm
  55  @item *_ctx2hash
  56  function, which turns a context into an actual hash value
  57  @item *_ctx_t
  58  context type, which can contains the state of a hashing process
  59 @end table
  60
  61 @subsubsection @code{*_init} function
  62  The @code{*_init} function generally takes a pointer to the context as parameter.
  63  This function initializes the context with algorithm specific values.
  64
  65 @subsubsection @code{*_nextBlock} function
  66  The @code{*_nextBlock} function is the core of each hash function. It updates the hash
  67  state with a given message block. So this function uses a context pointer and
  68  a message pointer as parameters. The size of a message block is fixed for each
  69  hash function (mostly 512 bit). For the last block of a messages which may be
  70  smaller than the blocksize you have to use the @code{*_lastBlock} function described
  71  below.
  72
  73 @subsubsection @code{*_lastBlock} function
  74  The @code{*_lastBlock} function finalizes the context with the last bits of a
  75  message. Since the last block is not required to have the blocksize you have
  76  to specify the length of the last block (normally in bits). This function
  77  performs the padding and final processing.
  78
  79 @subsubsection @code{*_ctx2hash} function
  80  The @code{*_ctx2hash} function turns a given hash context into an actual hash value.
  81  If multiple sized hash value may be created from a context it is necessary to
  82  give the the size of the hash value as parameter.
  83
  84
  85 @subsection Hash function abstraction layer (HFAL)
  86
  87