5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1999 - 2008 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/MAC Interface
27 * The Message Authentication Code interface for computing MAC values for
28 * authentication purposes. The MAC is usually used in combination with
29 * encryption to provide authentication.
36 * silc_mac_alloc(SILC_MAC_HMAC_SHA256, &hmac);
38 * // Set secret key to the MAC
39 * silc_mac_set_key(hmac, key, key_len);
42 * unsigned char mac[SILC_MAC_MAXLEN];
45 * silc_mac_make(hmac, data, data_len, digest, &mac_len);
48 * silc_mac_free(hmac);
52 /****s* silccrypt/SilcMac
56 * typedef struct SilcMacStruct *SilcMac;
60 * This context is the actual MAC context and is allocated
61 * by silc_mac_alloc and given as argument usually to all
62 * silc_mac_* functions. It is freed by the silc_mac_free
66 typedef struct SilcMacStruct *SilcMac;
68 /****d* silccrypt/MACs
76 * Supported MAC algorithm names. These names can be given as argument
82 /* HMAC with SHA-256, MAC truncated to 96 bits */
83 #define SILC_MAC_HMAC_SHA256_96 "hmac-sha256-96"
85 /* HMAC with SHA-512, MAC truncated to 96 bits */
86 #define SILC_MAC_HMAC_SHA512_96 "hmac-sha512-96"
88 /* HMAC with SHA-1, MAC truncated to 96 bits */
89 #define SILC_MAC_HMAC_SHA1_96 "hmac-sha1-96"
91 /* HMAC with MD5, MAC truncated to 96 bits */
92 #define SILC_MAC_HMAC_MD5_96 "hmac-md5-96"
94 /* HMAC with SHA-256 */
95 #define SILC_MAC_HMAC_SHA256 "hmac-sha256"
97 /* HMAC with SHA-512 */
98 #define SILC_MAC_HMAC_SHA512 "hmac-sha512"
100 /* HMAC with SHA-1 */
101 #define SILC_MAC_HMAC_SHA1 "hmac-sha1"
104 #define SILC_MAC_HMAC_MD5 "hmac-md5"
107 /****d* silccrypt/SILC_MAC_MAXLEN
111 * #define SILC_MAC_MAXLEN 64
115 * Maximum size of digest any algorithm supported by SILC Crypto Toolkit
116 * would produce. You can use this to define static digest buffers and
117 * safely use it with any hash function.
120 #define SILC_MAC_MAXLEN 64
122 /* MAC implementation object */
128 /* Marks for all MACs. This can be used in silc_mac_unregister
129 to unregister all MACs at once. */
130 #define SILC_ALL_MACS ((SilcMacObject *)1)
132 /* Default MACs for silc_mac_register_default(). */
133 extern DLLAPI const SilcMacObject silc_default_macs[];
137 /****f* silccrypt/silc_mac_register
141 * SilcBool silc_mac_register(const SilcMacObject *mac);
145 * Registers a new MAC into Crypto Toolkit. This function can be used
146 * at the initialization. All registered MACs should be unregistered
147 * with silc_mac_unregister. Returns FALSE on error. Usually this
148 * function is not needed. The default MAC algorithms are automatically
149 * registered. This can be used to change the order of the registered
150 * MAC algorithms by re-registering them in desired order, or add new
154 SilcBool silc_mac_register(const SilcMacObject *mac);
156 /****f* silccrypt/silc_mac_unregister
160 * SilcBool silc_mac_unregister(SilcMacObject *mac);
164 * Unregister a MAC from SILC by the MAC structure `mac'. This
165 * should be called for all MACs registered with silc_mac_register.
166 * Returns FALSE on error.
169 SilcBool silc_mac_unregister(SilcMacObject *mac);
171 /****f* silccrypt/silc_mac_register_default
175 * SilcBool silc_mac_register_default(void);
179 * Registers all default MACs into the SILC. These are the MACs
180 * that are builtin in the sources. Application need not call this
181 * directly. By calling silc_crypto_init this function is called.
184 SilcBool silc_mac_register_default(void);
186 /****f* silccrypt/silc_mac_unregister_all
190 * SilcBool silc_mac_unregister_all(void);
194 * Unregisters all registered MACs. Application need not call this
195 * directly. By calling silc_crypto_uninit this function is called.
198 SilcBool silc_mac_unregister_all(void);
200 /****f* silccrypt/silc_mac_alloc
204 * SilcBool silc_mac_alloc(const char *name, SilcMac *new_mac);
208 * Allocates a new SilcMac object of name of `name'. Returns FALSE if
209 * such MAC does not exist. After the MAC is allocated a key must be
210 * set for it by calling silc_mac_set_key.
212 * See MACs for supported MAC algorithms.
215 SilcBool silc_mac_alloc(const char *name, SilcMac *new_mac);
217 /****f* silccrypt/silc_mac_free
221 * void silc_mac_free(SilcMac mac);
225 * Frees the allocated MAC context. The key that may have been set
226 * with the silc_mac_set_key is also destroyed.
229 void silc_mac_free(SilcMac mac);
231 /****f* silccrypt/silc_mac_is_supported
235 * SilcBool silc_mac_is_supported(const char *name);
239 * Returns TRUE if the MAC indicated by the `name' exists.
242 SilcBool silc_mac_is_supported(const char *name);
244 /****f* silccrypt/silc_mac_get_supported
248 * char *silc_mac_get_supported(void);
252 * Returns comma (`,') separated list of registered MACs. The caller
253 * must free the returned pointer.
256 char *silc_mac_get_supported(void);
258 /****f* silccrypt/silc_mac_len
262 * SilcUInt32 silc_mac_len(SilcMac mac);
266 * Returns the length of the MAC that the MAC will produce.
269 SilcUInt32 silc_mac_len(SilcMac mac);
271 /****f* silccrypt/silc_mac_get_name
275 * const char *silc_mac_get_name(SilcMac mac);
279 * Returns the name of the MAC context.
282 const char *silc_mac_get_name(SilcMac mac);
284 /****f* silccrypt/silc_mac_get_hash
288 * SilcHash silc_mac_get_hash(SilcMac mac);
292 * Returns the SilcHash context that has been associated with the
293 * MAC context or NULL if the `mac' doesn't use hash function. In effect
294 * with HMACs this returns the underlaying hash function. The caller
295 * must not free the returned context.
298 SilcHash silc_mac_get_hash(SilcMac hmac);
300 /****f* silccrypt/silc_mac_set_key
304 * void silc_mac_set_key(SilcMac mac, const unsigned char *key,
305 * SilcUInt32 key_len);
309 * Sets the key to be used in the MAC operation. This must be set
310 * before calling silc_mac_make or silc_mac_final functions. If
311 * you do not want to set the key you can still produce a MAC by
312 * calling the silc_mac_make_with_key where you give the key as
313 * argument. Usually application still wants to set the key.
316 void silc_mac_set_key(SilcMac mac, const unsigned char *key,
319 /****f* silccrypt/silc_mac_get_key
323 * const unsigned char *
324 * silc_mac_get_key(SilcMac mac, SilcUInt32 *key_len);
328 * Returns the key data from the `mac' set with silc_hamc_set_key.
329 * The caller must not free the returned pointer.
332 const unsigned char *silc_mac_get_key(SilcMac mac, SilcUInt32 *key_len);
334 /****f* silccrypt/silc_mac_make
338 * void silc_mac_make(SilcMac mac, unsigned char *data,
339 * SilcUInt32 data_len, unsigned char *return_hash,
340 * SilcUInt32 *return_len);
344 * Computes a MAC from a data buffer indicated by the `data' of the
345 * length of `data_len'. The returned MAC is copied into the
346 * `return_hash' pointer which must be at least the size of the
347 * value silc_mac_len returns. The returned length is still
348 * returned to `return_len'.
351 void silc_mac_make(SilcMac mac, unsigned char *data,
352 SilcUInt32 data_len, unsigned char *return_hash,
353 SilcUInt32 *return_len);
355 /****f* silccrypt/silc_mac_make_with_key
359 * void silc_mac_make_with_key(SilcMac mac, unsigned char *data,
360 * SilcUInt32 data_len,
361 * unsigned char *key, SilcUInt32 key_len,
362 * unsigned char *return_hash,
363 * SilcUInt32 *return_len);
367 * Same as the silc_mac_make but takes the key for the MAC as argument.
368 * If this is used the key that may have been set by calling
369 * silc_mac_set_key is ignored.
372 void silc_mac_make_with_key(SilcMac mac, unsigned char *data,
374 unsigned char *key, SilcUInt32 key_len,
375 unsigned char *return_hash,
376 SilcUInt32 *return_len);
378 /****f* silccrypt/silc_mac_make_truncated
382 * void silc_mac_make_truncated(SilcMac mac,
383 * unsigned char *data,
384 * SilcUInt32 data_len,
385 * SilcUInt32 truncated_len,
386 * unsigned char *return_hash);
390 * Same as the silc_mac_make except that the returned MAC is
391 * truncated to the length indicated by the `truncated_len'. Some
392 * special applications may need this function. The `return_hash'
393 * must be at least the size of `truncated_len'.
397 * For security reasons, one should not truncate to less than half
398 * of the length of the true MAC lenght. However, since this routine
399 * may be used to non-critical applications this allows these dangerous
403 void silc_mac_make_truncated(SilcMac mac,
406 SilcUInt32 truncated_len,
407 unsigned char *return_hash);
409 /****f* silccrypt/silc_mac_init
413 * void silc_mac_init(SilcMac mac);
417 * Sometimes calling the silc_mac_make might not be the most
418 * optimal case of doing MACs. If you have a lot of different data
419 * that you need to put together for computing a MAC you may either
420 * put them into a buffer and compute the MAC from the buffer by
421 * calling the silc_mac_make, or you can use the silc_mac_init,
422 * silc_mac_update and silc_mac_final to do the MAC. This function
423 * prepares the allocated MAC context for this kind of MAC
424 * computation. The caller must have been called the function
425 * silc_mac_set_key before calling this function. To add the
426 * data to be used in the MAC computation call the silc_mac_update
430 void silc_mac_init(SilcMac mac);
432 /****f* silccrypt/silc_mac_init_with_key
436 * void silc_mac_init_with_key(SilcMac mac, const unsigned char *key,
437 * SilcUInt32 key_len);
441 * Same as silc_mac_init but initializes with specific key. The
442 * key that may have been set with silc_mac_set_key is ignored.
445 void silc_mac_init_with_key(SilcMac mac, const unsigned char *key,
448 /****f* silccrypt/silc_mac_update
452 * void silc_mac_update(SilcMac mac, const unsigned char *data,
453 * SilcUInt32 data_len);
457 * This function may be called to add data to be used in the MAC
458 * computation. This can be called multiple times to add data from
459 * many sources before actually performing the MAC. Once you've
460 * added all the data you need you can call the silc_mac_final to
461 * actually produce the MAC.
465 * unsigned char mac[20];
466 * SilcUInt32 mac_len;
468 * silc_mac_init(mac);
469 * silc_mac_update(mac, data, data_len);
470 * silc_mac_update(mac, more_data, more_data_len);
471 * silc_mac_final(hac, mac, &mac_len);
474 void silc_mac_update(SilcMac mac, const unsigned char *data,
475 SilcUInt32 data_len);
477 /****f* silccrypt/silc_mac_final
481 * void silc_mac_final(SilcMac mac, unsigned char *return_hash,
482 * SilcUInt32 *return_len);
486 * This function is used to produce the final MAC from the data
487 * that has been added to the MAC context by calling the
488 * silc_mac_update function. The MAC is copied in to the
489 * `return_hash' pointer which must be at least the size that
490 * the silc_mac_len returns. The length of the MAC is still
491 * returned into `return_len'.
494 void silc_mac_final(SilcMac mac, unsigned char *return_hash,
495 SilcUInt32 *return_len);
497 /* Backwards support for old HMAC API */
498 #define SilcHmac SilcMac
499 #define SilcHmacObject SilcMacObject
500 #define SILC_ALL_HMACS SILC_ALL_MACS
501 #define silc_default_hmacs silc_default_macs
502 #define silc_hmac_register silc_mac_register
503 #define silc_hmac_unregister silc_mac_unregister
504 #define silc_hmac_register_default silc_mac_register_default
505 #define silc_hmac_unregister_all silc_mac_unregister_all
506 #define silc_hmac_alloc(name, hash, new_hmac) silc_mac_alloc(name, new_hmac)
507 #define silc_hmac_free silc_mac_free
508 #define silc_hmac_is_supported silc_mac_is_supported
509 #define silc_hmac_get_supported silc_mac_get_supported
510 #define silc_hmac_len silc_mac_len
511 #define silc_hmac_get_hash silc_mac_get_hash
512 #define silc_hmac_get_name silc_mac_get_name
513 #define silc_hmac_set_key silc_mac_set_key
514 #define silc_hmac_get_key silc_mac_get_key
515 #define silc_hmac_make silc_mac_make
516 #define silc_hmac_init silc_mac_init
517 #define silc_hmac_init_with_key silc_mac_init_with_key
518 #define silc_hmac_update silc_mac_update
519 #define silc_hmac_final silc_mac_final
521 #endif /* SILCMAC_H */