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 The HashFunctionAbstractionLayer (BCAL) is an abstraction layer which allows
  87 usage of all implemented hash functions in a simple way. It abstracts specific
  88 function details and is suitable for implementations which want to be flexible
  89 in the choosing of specific hash functions. Another important aspect is that this
  90 abstraction layer enables the implementation of hash function operating modes
  91 independently from concrete hash function. It is very simple to use and reassembles
  92 the API used to implement individual hash functions.
  93
  94 The main component is a hash function descriptor which contains the details of
  95 the individual hash functions.
  96
  97 @subsection Parts of HFAL
  98 The HFAL is split up in different parts:
  99 @itemize @bullet
 100   @item HFAL declaration for HFAL decriptors
 101   @item algorithm specific definitions of HFAL decriptors
 102   @item HFAL basic context type
 103   @item HFAL basic functions
 104 @end itemize
 105
 106 @subsection HFAL declaration for HFAL decriptors
 107 The HFAL descriptor is a structure which is usually placed in FLASH or ROM since
 108 modification is unnecessary. It contains all information required to use the
 109 according hash function.
 110
 111 @verbatim
 112 typedef struct {
 113         uint8_t  type; /* 2 == hashfunction */
 114         uint8_t  flags;
 115         PGM_P    name;
 116         uint16_t ctxsize_B;
 117         uint16_t blocksize_b;
 118         uint16_t hashsize_b;
 119         hf_init_fpt init;
 120         hf_nextBlock_fpt  nextBlock;
 121         hf_lastBlock_fpt  lastBlock;
 122         hf_ctx2hash_fpt   ctx2hash;
 123         hf_free_fpt free;
 124         hf_mem_fpt mem;
 125 } hfdesc_t; /* hashfunction descriptor type */
 126 @end verbatim
 127
 128 @table @var
 129   @item type
 130   should be set to @samp{2} to indicate that this descriptor is for a
 131   hash function.
 132
 133  @item flags
 134  currently unused, should be set to zero.
 135
 136  @item name
 137  is a pointer to a zero terminated ASCII string giving the name of the
 138  implemented primitive. On targets with Harvard-architecture the string resides
 139  in code memory (FLASH, ROM, ...).
 140
 141  @item ctxsize_B
 142  is the number of bytes which should be allocated for the context variable.
 143
 144  @item blocksize_b
 145  is the number of bits on which are hashed by one iteration of the nextBlock
 146  function.
 147
 148  @item hashsize_b
 149  is the number of bits on which are outputed as final hash value.
 150
 151  @item init
 152  is a pointer to the init function.
 153
 154  @item nextBlock
 155  is a pointer to the algorithm specific nextBlock function.
 156
 157  @item lastBlock
 158  is a pointer to the algorithm specific lastBlock function.
 159
 160  @item ctx2hash
 161  is a pointer to the algorithm specific ctx2hash function.
 162
 163  @item free
 164  is a pointer to the free function or NULL if there is no free function.
 165
 166  @item mem
 167  is a pointer to the algorithm specific mem function. This function hashes
 168  a complete message which has to reside entirely in RAM. This value may be
 169  NULL if there is no such function.
 170 @end table
 171
 172 @subsection HFAL-Basic context
 173 Besides the context types for individual hash functions there is a generic context
 174 type for HFAL. This is the context to use when using HFAL based functions.
 175 The HFAL context has the following structure:
 176 @verbatim
 177 typedef struct{
 178         hfdesc_t* desc_ptr;
 179         void*     ctx;
 180 } hfgen_ctx_t;
 181 @end verbatim
 182 @table @code
 183 @item desc_ptr
 184 a pointer to the HFAL descriptor
 185 @item ctx
 186 pointer to the hash function specific context
 187 @end table
 188
 189 @subsection HFAL-Basic
 190 HFAL-Basic provides the basic features of an hash function on top of the
 191 HFAL. To use it you simply have to include the algorithms you want to use,
 192 the HFAL descriptor file and of course the HFAL-Basic implementation.
 193
 194 The following functions are provided:
 195
 196 @subsubsection @code{hfal_hash_init}
 197 @code{uint8_t hfal_hash_init(const hfdesc_t* hash_descriptor, hfgen_ctx_t* ctx)}
 198  this function initializes a HFAL context based on the given HFAL descriptor
 199  pointer (first parameter). The context to initialize is designated by the
 200  pointer passed as second parameter.
 201
 202  If everything works fine @samp{0} is returned. In the case something fails
 203  the following codes are returned:
 204 @table @samp
 205   @item 3
 206   It was not possible to allocate enough memory to hold the context variable
 207   for the selected hash function.
 208 @end table
 209
 210 @subsubsection @code{hfal_hash_nextBlock}
 211 @code{ void hfal_hash_nextBlock(hfgen_ctx_t* ctx, const void* block)}
 212   this function hashes a block of memory (of algorithm specific length) and
 213   updates the context accordingly.
 214
 215 @subsubsection @code{hfal_hash_lastBlock}
 216 @code{ void hfal_hash_lastBlock(hfgen_ctx_t* ctx, const void* block, uint16_t length_b)}
 217   this function is used to hash the last block of a message. Since messages are
 218   not required to consist of full blocks (or even full bytes) the length of the
 219   block must be given in bits. The context is updated accordingly. This function
 220   already performs padding and related stuff.
 221
 222 @subsubsection @code{hfal_hash_ctx2hash}
 223 @code{ void hfal_hash_ctx2hash(void* dest, hfgen_ctx_t* ctx)}
 224   this function converts a context into an actual hash value which is stored in
 225   @code{dest}. The application is responsible for allocating enough room.
 226
 227 @subsubsection @code{hfal_hash_free}
 228 @code{ void hfal_hash_free(hfgen_ctx_t* ctx)}
 229   this function differs from the individual hash functions @code{free} function
 230   in that it is allways provided and must be called to avoid memory holes.
 231   This function also automatically calls the implementation specific @code{free}
 232   function if one is provided.
 233
 234 @subsubsection @code{hfal_hash_mem}
 235 @code{ void hfal_hash_mem(const hfdesc_t* hash_descriptor, void* dest, const void* msg, uint32_t length_b)}
 236   this function is allways provided (even if the actual algorithm does not
 237   specify a @code{mem} function. It hashes an entire message which resides in
 238   RAM and stores the hash value in @code{dest}. @code{msg} is the pointer to the
 239   message and @code{length_b} is the message length in bits.
 240
 241 @subsubsection @code{hfal_hash_getBlocksize}
 242 @code{ uint16_t hfal_hash_getBlocksize(const hfdesc_t* hash_descriptor)}
 243   returns the blocksize of the described (@code{hash_descriptor}) hash function.
 244
 245 @subsubsection @code{hfal_hash_getHashsize}
 246 @code{ uint16_t hfal_hash_getHashsize(const hfdesc_t* hash_descriptor)}
 247   returns the hash value size of the described (@code{hash_descriptor}) hash function.
 248
 249 @subsubsection @code{hfal_hash_getCtxsize}
 250 @code{ uint16_t hfal_hash_getCtxsize_B(const hfdesc_t* hash_descriptor)}
 251   returns the size of a context variable of the described (@code{hash_descriptor}) hash function.
 252
 253
 254