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/SILC 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.
33 /****s* silccrypt/SilcMac
37 * typedef struct SilcMacStruct *SilcMac;
41 * This context is the actual MAC context and is allocated
42 * by silc_mac_alloc and given as argument usually to all
43 * silc_mac_* functions. It is freed by the silc_mac_free
47 typedef struct SilcMacStruct *SilcMac;
49 /****d* silccrypt/MACs
57 * Supported MAC algorithm names. These names can be given as argument
63 /* HMAC with SHA-256, MAC truncated to 96 bits */
64 #define SILC_MAC_HMAC_SHA256_96 "hmac-sha256-96"
66 /* HMAC with SHA-512, MAC truncated to 96 bits */
67 #define SILC_MAC_HMAC_SHA512_96 "hmac-sha512-96"
69 /* HMAC with SHA-1, MAC truncated to 96 bits */
70 #define SILC_MAC_HMAC_SHA1_96 "hmac-sha1-96"
72 /* HMAC with MD5, MAC truncated to 96 bits */
73 #define SILC_MAC_HMAC_MD5_96 "hmac-md5-96"
75 /* HMAC with SHA-256 */
76 #define SILC_MAC_HMAC_SHA256 "hmac-sha256"
78 /* HMAC with SHA-512 */
79 #define SILC_MAC_HMAC_SHA512 "hmac-sha512"
82 #define SILC_MAC_HMAC_SHA1 "hmac-sha1"
85 #define SILC_MAC_HMAC_MD5 "hmac-md5"
88 /* MAC implementation object */
94 /* Marks for all MACs. This can be used in silc_mac_unregister
95 to unregister all MACs at once. */
96 #define SILC_ALL_MACS ((SilcMacObject *)1)
98 /* Default MACs for silc_mac_register_default(). */
99 extern DLLAPI const SilcMacObject silc_default_macs[];
103 /****f* silccrypt/silc_mac_register
107 * SilcBool silc_mac_register(const SilcMacObject *mac);
111 * Registers a new MAC into Crypto Toolkit. This function can be used
112 * at the initialization. All registered MACs should be unregistered
113 * with silc_mac_unregister. Returns FALSE on error. Usually this
114 * function is not needed. The default MAC algorithms are automatically
115 * registered. This can be used to change the order of the registered
116 * MAC algorithms by re-registering them in desired order, or add new
120 SilcBool silc_mac_register(const SilcMacObject *mac);
122 /****f* silccrypt/silc_mac_unregister
126 * SilcBool silc_mac_unregister(SilcMacObject *mac);
130 * Unregister a MAC from SILC by the MAC structure `mac'. This
131 * should be called for all MACs registered with silc_mac_register.
132 * Returns FALSE on error.
135 SilcBool silc_mac_unregister(SilcMacObject *mac);
137 /****f* silccrypt/silc_mac_register_default
141 * SilcBool silc_mac_register_default(void);
145 * Registers all default MACs into the SILC. These are the MACs
146 * that are builtin in the sources. Application need not call this
147 * directly. By calling silc_crypto_init this function is called.
150 SilcBool silc_mac_register_default(void);
152 /****f* silccrypt/silc_mac_unregister_all
156 * SilcBool silc_mac_unregister_all(void);
160 * Unregisters all registered MACs. Application need not call this
161 * directly. By calling silc_crypto_uninit this function is called.
164 SilcBool silc_mac_unregister_all(void);
166 /****f* silccrypt/silc_mac_alloc
170 * SilcBool silc_mac_alloc(const char *name, SilcMac *new_mac);
174 * Allocates a new SilcMac object of name of `name'. Returns FALSE if
175 * such MAC does not exist. After the MAC is allocated a key must be
176 * set for it by calling silc_mac_set_key.
179 SilcBool silc_mac_alloc(const char *name, SilcMac *new_mac);
181 /****f* silccrypt/silc_mac_free
185 * void silc_mac_free(SilcMac mac);
189 * Frees the allocated MAC context. The key that may have been set
190 * with the silc_mac_set_key is also destroyed.
193 void silc_mac_free(SilcMac mac);
195 /****f* silccrypt/silc_mac_is_supported
199 * SilcBool silc_mac_is_supported(const char *name);
203 * Returns TRUE if the MAC indicated by the `name' exists.
206 SilcBool silc_mac_is_supported(const char *name);
208 /****f* silccrypt/silc_mac_get_supported
212 * char *silc_mac_get_supported(void);
216 * Returns comma (`,') separated list of registered MACs. The caller
217 * must free the returned pointer.
220 char *silc_mac_get_supported(void);
222 /****f* silccrypt/silc_mac_len
226 * SilcUInt32 silc_mac_len(SilcMac mac);
230 * Returns the length of the MAC that the MAC will produce.
233 SilcUInt32 silc_mac_len(SilcMac mac);
235 /****f* silccrypt/silc_mac_get_name
239 * const char *silc_mac_get_name(SilcMac mac);
243 * Returns the name of the MAC context.
246 const char *silc_mac_get_name(SilcMac mac);
248 /****f* silccrypt/silc_mac_get_hash
252 * SilcHash silc_mac_get_hash(SilcMac mac);
256 * Returns the SilcHash context that has been associated with the
257 * MAC context or NULL if the `mac' doesn't use hash function. In effect
258 * with HMACs this returns the underlaying hash function. The caller
259 * must not free the returned context.
262 SilcHash silc_mac_get_hash(SilcMac hmac);
264 /****f* silccrypt/silc_mac_set_key
268 * void silc_mac_set_key(SilcMac mac, const unsigned char *key,
269 * SilcUInt32 key_len);
273 * Sets the key to be used in the MAC operation. This must be set
274 * before calling silc_mac_make or silc_mac_final functions. If
275 * you do not want to set the key you can still produce a MAC by
276 * calling the silc_mac_make_with_key where you give the key as
277 * argument. Usually application still wants to set the key.
280 void silc_mac_set_key(SilcMac mac, const unsigned char *key,
283 /****f* silccrypt/silc_mac_get_key
287 * const unsigned char *
288 * silc_mac_get_key(SilcMac mac, SilcUInt32 *key_len);
292 * Returns the key data from the `mac' set with silc_hamc_set_key.
293 * The caller must not free the returned pointer.
296 const unsigned char *silc_mac_get_key(SilcMac mac, SilcUInt32 *key_len);
298 /****f* silccrypt/silc_mac_make
302 * void silc_mac_make(SilcMac mac, unsigned char *data,
303 * SilcUInt32 data_len, unsigned char *return_hash,
304 * SilcUInt32 *return_len);
308 * Computes a MAC from a data buffer indicated by the `data' of the
309 * length of `data_len'. The returned MAC is copied into the
310 * `return_hash' pointer which must be at least the size of the
311 * value silc_mac_len returns. The returned length is still
312 * returned to `return_len'.
315 void silc_mac_make(SilcMac mac, unsigned char *data,
316 SilcUInt32 data_len, unsigned char *return_hash,
317 SilcUInt32 *return_len);
319 /****f* silccrypt/silc_mac_make_with_key
323 * void silc_mac_make_with_key(SilcMac mac, unsigned char *data,
324 * SilcUInt32 data_len,
325 * unsigned char *key, SilcUInt32 key_len,
326 * unsigned char *return_hash,
327 * SilcUInt32 *return_len);
331 * Same as the silc_mac_make but takes the key for the MAC as argument.
332 * If this is used the key that may have been set by calling
333 * silc_mac_set_key is ignored.
336 void silc_mac_make_with_key(SilcMac mac, unsigned char *data,
338 unsigned char *key, SilcUInt32 key_len,
339 unsigned char *return_hash,
340 SilcUInt32 *return_len);
342 /****f* silccrypt/silc_mac_make_truncated
346 * void silc_mac_make_truncated(SilcMac mac,
347 * unsigned char *data,
348 * SilcUInt32 data_len,
349 * SilcUInt32 truncated_len,
350 * unsigned char *return_hash);
354 * Same as the silc_mac_make except that the returned MAC is
355 * truncated to the length indicated by the `truncated_len'. Some
356 * special applications may need this function. The `return_hash'
357 * must be at least the size of `truncated_len'.
361 * For security reasons, one should not truncate to less than half
362 * of the length of the true MAC lenght. However, since this routine
363 * may be used to non-critical applications this allows these dangerous
367 void silc_mac_make_truncated(SilcMac mac,
370 SilcUInt32 truncated_len,
371 unsigned char *return_hash);
373 /****f* silccrypt/silc_mac_init
377 * void silc_mac_init(SilcMac mac);
381 * Sometimes calling the silc_mac_make might not be the most
382 * optimal case of doing MACs. If you have a lot of different data
383 * that you need to put together for computing a MAC you may either
384 * put them into a buffer and compute the MAC from the buffer by
385 * calling the silc_mac_make, or you can use the silc_mac_init,
386 * silc_mac_update and silc_mac_final to do the MAC. This function
387 * prepares the allocated MAC context for this kind of MAC
388 * computation. The caller must have been called the function
389 * silc_mac_set_key before calling this function. To add the
390 * data to be used in the MAC computation call the silc_mac_update
394 void silc_mac_init(SilcMac mac);
396 /****f* silccrypt/silc_mac_init_with_key
400 * void silc_mac_init_with_key(SilcMac mac, const unsigned char *key,
401 * SilcUInt32 key_len);
405 * Same as silc_mac_init but initializes with specific key. The
406 * key that may have been set with silc_mac_set_key is ignored.
409 void silc_mac_init_with_key(SilcMac mac, const unsigned char *key,
412 /****f* silccrypt/silc_mac_update
416 * void silc_mac_update(SilcMac mac, const unsigned char *data,
417 * SilcUInt32 data_len);
421 * This function may be called to add data to be used in the MAC
422 * computation. This can be called multiple times to add data from
423 * many sources before actually performing the MAC. Once you've
424 * added all the data you need you can call the silc_mac_final to
425 * actually produce the MAC.
429 * unsigned char mac[20];
430 * SilcUInt32 mac_len;
432 * silc_mac_init(mac);
433 * silc_mac_update(mac, data, data_len);
434 * silc_mac_update(mac, more_data, more_data_len);
435 * silc_mac_final(hac, mac, &mac_len);
438 void silc_mac_update(SilcMac mac, const unsigned char *data,
439 SilcUInt32 data_len);
441 /****f* silccrypt/silc_mac_final
445 * void silc_mac_final(SilcMac mac, unsigned char *return_hash,
446 * SilcUInt32 *return_len);
450 * This function is used to produce the final MAC from the data
451 * that has been added to the MAC context by calling the
452 * silc_mac_update function. The MAC is copied in to the
453 * `return_hash' pointer which must be at least the size that
454 * the silc_mac_len returns. The length of the MAC is still
455 * returned into `return_len'.
458 void silc_mac_final(SilcMac mac, unsigned char *return_hash,
459 SilcUInt32 *return_len);
461 /* Backwards support for old HMAC API */
462 #define SilcHmac SilcMac
463 #define SilcHmacObject SilcMacObject
464 #define SILC_ALL_HMACS SILC_ALL_MACS
465 #define silc_default_hmacs silc_default_macs
466 #define silc_hmac_register silc_mac_register
467 #define silc_hmac_unregister silc_mac_unregister
468 #define silc_hmac_register_default silc_mac_register_default
469 #define silc_hmac_unregister_all silc_mac_unregister_all
470 #define silc_hmac_alloc(name, hash, new_hmac) silc_mac_alloc(name, new_hmac)
471 #define silc_hmac_free silc_mac_free
472 #define silc_hmac_is_supported silc_mac_is_supported
473 #define silc_hmac_get_supported silc_mac_get_supported
474 #define silc_hmac_len silc_mac_len
475 #define silc_hmac_get_hash silc_mac_get_hash
476 #define silc_hmac_get_name silc_mac_get_name
477 #define silc_hmac_set_key silc_mac_set_key
478 #define silc_hmac_get_key silc_mac_get_key
479 #define silc_hmac_make silc_mac_make
480 #define silc_hmac_init_with_key silc_mac_init_with_key
481 #define silc_hmac_update silc_mac_update
482 #define silc_hmac_final silc_mac_final
484 #endif /* SILCMAC_H */