]> git.cryptolib.org Git - avr-crypto-lib.git/blob - USAGE.hashfunctions
Grøstl in large (384 & 512 bit); warning: freaking linker
[avr-crypto-lib.git] / 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. block cipher 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 keyschedule
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 cryptographical 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