5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1999 - 2006 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
23 /****h* silccrypt/SILC HMAC Interface
27 * This is the interface for HMAC, or the keyed hash values, that are
28 * used for packet and message authentication. These routines uses
29 * already implemented hash functions from the SilcHashAPI. These
30 * routines were created according to RFC 2104.
34 /****s* silccrypt/SilcHMACAPI/SilcHmac
38 * typedef struct SilcHmacStruct *SilcHmac;
42 * This context is the actual HMAC context and is allocated
43 * by silc_hmac_alloc and given as argument usually to all
44 * silc_hmac_* functions. It is freed by the silc_hmac_free
48 typedef struct SilcHmacStruct *SilcHmac;
50 /****s* silccrypt/SilcHMACAPI/SilcHmacObject
54 * typedef struct { ... } SilcHmacObject;
58 * This structure represents one HMAC. The HMAC's name and the
59 * MAC length is defined in the structure. This structure is
60 * then given as argument to the silc_hmac_register. That function
61 * is used to register all HMACs into SILC. They can be then
62 * allocated by the name found in this structure by calling the
71 /* Marks for all hmacs. This can be used in silc_hmac_unregister
72 to unregister all hmacs at once. */
73 #define SILC_ALL_HMACS ((SilcHmacObject *)1)
75 /* Default hmacs for silc_hmac_register_default(). */
76 extern DLLAPI const SilcHmacObject silc_default_hmacs[];
78 /* Default HMAC in the SILC protocol */
79 #define SILC_DEFAULT_HMAC "hmac-sha1-96"
83 /****f* silccrypt/SilcHMACAPI/silc_hmac_register
87 * SilcBool silc_hmac_register(const SilcHmacObject *hmac);
91 * Registers a new HMAC into the SILC. This function is used at the
92 * initialization of the SILC. All registered HMACs should be
93 * unregistered with silc_hmac_unregister. The `hmac' includes the
94 * name of the HMAC and the length of the MAC. Usually this
95 * function is not called directly. Instead, application can call
96 * the silc_hmac_register_default to register all default HMACs
97 * that are builtin the sources. Returns FALSE on error.
100 SilcBool silc_hmac_register(const SilcHmacObject *hmac);
102 /****f* silccrypt/SilcHMACAPI/silc_hmac_unregister
106 * SilcBool silc_hmac_unregister(SilcHmacObject *hmac);
110 * Unregister a HMAC from SILC by the HMAC structure `hmac'. This
111 * should be called for all registered HMAC's. Returns FALSE on
115 SilcBool silc_hmac_unregister(SilcHmacObject *hmac);
117 /****f* silccrypt/SilcHMACAPI/silc_hmac_register_default
121 * SilcBool silc_hmac_register_default(void);
125 * Registers all default HMACs into the SILC. These are the HMACs
126 * that are builtin in the sources. See the list of default HMACs
127 * in the silchmac.c source file. The application may use this
128 * to register default HMACs if specific HMAC in any specific order
129 * is not wanted (application's configuration usually may decide
130 * the order of the registration, in which case this should not be
134 SilcBool silc_hmac_register_default(void);
136 /****f* silccrypt/SilcHMACAPI/silc_hmac_unregister_all
140 * SilcBool silc_hmac_unregister_all(void);
144 * Unregisters all registered HMACs.
147 SilcBool silc_hmac_unregister_all(void);
149 /****f* silccrypt/SilcHMACAPI/silc_hmac_alloc
153 * SilcBool silc_hmac_alloc(const char *name, SilcHash hash,
154 * SilcHmac *new_hmac);
158 * Allocates a new SilcHmac object of name of `name'. The `hash' may
159 * be provided as argument. If provided it is used as the hash function
160 * of the HMAC. If it is NULL then the hash function is allocated and
161 * the name of the hash algorithm is derived from the `name'. Returns
162 * FALSE if such HMAC does not exist.
165 SilcBool silc_hmac_alloc(const char *name, SilcHash hash, SilcHmac *new_hmac);
167 /****f* silccrypt/SilcHMACAPI/silc_hmac_free
171 * void silc_hmac_free(SilcHmac hmac);
175 * Frees the allocated HMAC context. The key that may have been set
176 * with the silc_hmac_set_key is also destroyed.
179 void silc_hmac_free(SilcHmac hmac);
181 /****f* silccrypt/SilcHMACAPI/silc_hmac_is_supported
185 * SilcBool silc_hmac_is_supported(const char *name);
189 * Returns TRUE if the HMAC indicated by the `name' exists.
192 SilcBool silc_hmac_is_supported(const char *name);
194 /****f* silccrypt/SilcHMACAPI/silc_hmac_get_supported
198 * char *silc_hmac_get_supported(void);
202 * Returns comma (`,') separated list of registered HMACs. This is
203 * used for example when sending supported HMAC list during the SILC
204 * Key Exchange protocol (SKE). The caller must free the returned
208 char *silc_hmac_get_supported(void);
210 /****f* silccrypt/SilcHMACAPI/silc_hmac_len
214 * SilcUInt32 silc_hmac_len(SilcHmac hmac);
218 * Returns the length of the MAC that the HMAC will produce.
221 SilcUInt32 silc_hmac_len(SilcHmac hmac);
223 /****f* silccrypt/SilcHMACAPI/silc_hmac_get_hash
227 * SilcHash silc_hmac_get_hash(SilcHmac hmac);
231 * Returns the SilcHash context that has been associated with the
232 * HMAC context. The caller must not free the returned context.
235 SilcHash silc_hmac_get_hash(SilcHmac hmac);
237 /****f* silccrypt/SilcHMACAPI/silc_hmac_get_name
241 * const char *silc_hmac_get_name(SilcHmac hmac);
245 * Returns the name of the HMAC context.
248 const char *silc_hmac_get_name(SilcHmac hmac);
250 /****f* silccrypt/SilcHMACAPI/silc_hmac_set_key
254 * void silc_hmac_set_key(SilcHmac hmac, const unsigned char *key,
255 * SilcUInt32 key_len);
259 * Sets the key to be used in the HMAC operation. This must be set
260 * before calling silc_hmac_make or silc_hmac_final functions. If
261 * you do not want to set the key you can still produce a MAC by
262 * calling the silc_hmac_make_with_key where you give the key as
263 * argument. Usually application still wants to set the key.
266 void silc_hmac_set_key(SilcHmac hmac, const unsigned char *key,
269 /****f* silccrypt/SilcHMACAPI/silc_hmac_get_key
273 * const unsigned char *
274 * silc_hmac_get_key(SilcHmac hmac, SilcUInt32 *key_len);
278 * Returns the key data from the `hmac' set with silc_hamc_set_key.
279 * The caller must not free the returned pointer.
282 const unsigned char *silc_hmac_get_key(SilcHmac hmac, SilcUInt32 *key_len);
284 /****f* silccrypt/SilcHMACAPI/silc_hmac_make
288 * void silc_hmac_make(SilcHmac hmac, unsigned char *data,
289 * SilcUInt32 data_len, unsigned char *return_hash,
290 * SilcUInt32 *return_len);
294 * Computes a MAC from a data buffer indicated by the `data' of the
295 * length of `data_len'. The returned MAC is copied into the
296 * `return_hash' pointer which must be at least the size of the
297 * value silc_hmac_len returns. The returned length is still
298 * returned to `return_len'.
301 void silc_hmac_make(SilcHmac hmac, unsigned char *data,
302 SilcUInt32 data_len, unsigned char *return_hash,
303 SilcUInt32 *return_len);
305 /****f* silccrypt/SilcHMACAPI/silc_hmac_make_with_key
309 * void silc_hmac_make_with_key(SilcHmac hmac, unsigned char *data,
310 * SilcUInt32 data_len,
311 * unsigned char *key, SilcUInt32 key_len,
312 * unsigned char *return_hash,
313 * SilcUInt32 *return_len);
317 * Same as the silc_hmac_make but takes the key for the HMAC as
318 * argument. If this is used the key that may have been set by calling
319 * silc_hmac_set_key is ignored.
322 void silc_hmac_make_with_key(SilcHmac hmac, unsigned char *data,
324 unsigned char *key, SilcUInt32 key_len,
325 unsigned char *return_hash,
326 SilcUInt32 *return_len);
328 /****f* silccrypt/SilcHMACAPI/silc_hmac_make_truncated
332 * void silc_hmac_make_truncated(SilcHmac hmac,
333 * unsigned char *data,
334 * SilcUInt32 data_len,
335 * SilcUInt32 truncated_len,
336 * unsigned char *return_hash);
340 * Same as the silc_hmac_make except that the returned MAC is
341 * truncated to the length indicated by the `truncated_len'. Some
342 * special applications may need this function. The `return_hash'
343 * must be at least the size of `truncated_len'.
347 * For security reasons, one should not truncate to less than half
348 * of the length of the true MAC lenght. However, since this routine
349 * may be used to non-critical applications this allows these dangerous
353 void silc_hmac_make_truncated(SilcHmac hmac,
356 SilcUInt32 truncated_len,
357 unsigned char *return_hash);
359 /****f* silccrypt/SilcHMACAPI/silc_hmac_init
363 * void silc_hmac_init(SilcHmac hmac);
367 * Sometimes calling the silc_hmac_make might not be the most
368 * optimal case of doing MACs. If you have a lot of different data
369 * that you need to put together for computing a MAC you may either
370 * put them into a buffer and compute the MAC from the buffer by
371 * calling the silc_hmac_make, or you can use the silc_hmac_init,
372 * silc_hmac_update and silc_hmac_final to do the MAC. This function
373 * prepares the allocated HMAC context for this kind of MAC
374 * computation. The caller must have been called the function
375 * silc_hmac_set_key before calling this function. To add the
376 * data to be used in the MAC computation call the silc_hmac_update
380 void silc_hmac_init(SilcHmac hmac);
382 /****f* silccrypt/SilcHMACAPI/silc_hmac_init_with_key
386 * void silc_hmac_init_with_key(SilcHmac hmac, const unsigned char *key,
387 * SilcUInt32 key_len);
391 * Same as silc_hmac_init but initializes with specific key. The
392 * key that may have been set with silc_hmac_set_key is ignored.
395 void silc_hmac_init_with_key(SilcHmac hmac, const unsigned char *key,
398 /****f* silccrypt/SilcHMACAPI/silc_hmac_update
402 * void silc_hmac_update(SilcHmac hmac, const unsigned char *data,
403 * SilcUInt32 data_len);
407 * This function may be called to add data to be used in the MAC
408 * computation. This can be called multiple times to add data from
409 * many sources before actually performing the HMAC. Once you've
410 * added all the data you need you can call the silc_hmac_final to
411 * actually produce the MAC.
415 * unsigned char mac[20];
416 * SilcUInt32 mac_len;
418 * silc_hmac_init(hmac);
419 * silc_hmac_update(hmac, data, data_len);
420 * silc_hmac_update(hmac, more_data, more_data_len);
421 * silc_hmac_final(hmac, mac, &mac_len);
424 void silc_hmac_update(SilcHmac hmac, const unsigned char *data,
425 SilcUInt32 data_len);
427 /****f* silccrypt/SilcHMACAPI/silc_hmac_final
431 * void silc_hmac_final(SilcHmac hmac, unsigned char *return_hash,
432 * SilcUInt32 *return_len);
436 * This function is used to produce the final MAC from the data
437 * that has been added to the HMAC context by calling the
438 * silc_hmac_update function. The MAC is copied in to the
439 * `return_hash' pointer which must be at least the size that
440 * the silc_hmac_len returns. The length of the MAC is still
441 * returned into `return_len'.
444 void silc_hmac_final(SilcHmac hmac, unsigned char *return_hash,
445 SilcUInt32 *return_len);