1 ===================================
2 = Usage of hash functions =
3 ===================================
6 email: daniel.otte@rub.de
10 This file will describe how to use the hash function implementations provided
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.
22 1.1. high frequent parameters:
24 hash value size: 128 bits, 160 bits, 224 bits, 256 bits, 384 bits, 512 bits
26 2. Parts of a hash function
27 * initialization function
28 * compression algorithm
29 * finalization function
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
35 Generally the API of the implemented block ciphers consists of:
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
43 3.1 look at the prototypes
44 Generally the prototypes (defined in the *.h files) will tell you what
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
55 The *_init function generally takes a pointer to the context as parameter.
56 This function initializes the context with algorithm specific values.
58 3.3. *_nexBlock 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
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.
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.