]> git.cryptolib.org Git - avr-crypto-lib.git/blob - doc/acl_hashes.texi
8b351ca2785a11b251be65a876d788b3ac25e4a4
[avr-crypto-lib.git] / 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