5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 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/Hash Function Interface
27 * This is the interface for hash functions which are used to create message
28 * digests. The routines are used in various cryptographic operations.
34 * // Allocate SHA-1 hash function
35 * silc_hash_alloc(SILC_HASH_SHA1, &sha1hash);
38 * unsigned char digest[SILC_HASH_MAXLEN];
40 * silc_hash_init(sha1hash);
41 * silc_hash_update(sha1hash, "foobar", 6);
42 * silc_hash_final(sha1hash, digest);
44 * // Same can be done in one call also
45 * silc_hash_make(sha1hash, "foobar", 6, digest);
48 * silc_hash_free(sha1hash);
52 /****s* silccrypt/SilcHash
56 * typedef struct SilcHashStruct *SilcHash;
60 * This context is the actual hash function context and is allocated
61 * by silc_hash_alloc and given as argument usually to all
62 * silc_hash_* functions. It is freed by the silc_hash_free
66 typedef struct SilcHashStruct *SilcHash;
68 /****d* silccrypt/Hashes
76 * Supported hash function names. These names can be given as argument
81 #define SILC_HASH_SHA256 "sha256" /* SHA-256 */
82 #define SILC_HASH_SHA512 "sha512" /* SHA-512 */
83 #define SILC_HASH_SHA1 "sha1" /* SHA-1 */
84 #define SILC_HASH_MD5 "md5" /* MD5 */
87 /****d* silccrypt/Hash-OIDs
95 * Supported hash function OIDs. These names can be given as argument
96 * to silc_hash_alloc_by_oid.
100 #define SILC_HASH_OID_SHA256 "2.16.840.1.101.3.4.2.1"
101 #define SILC_HASH_OID_SHA512 "2.16.840.1.101.3.4.2.3"
102 #define SILC_HASH_OID_SHA1 "1.3.14.3.2.26"
103 #define SILC_HASH_OID_MD5 "1.2.840.113549.2.5"
106 /****d* silccrypt/SILC_HASH_MAXLEN
110 * #define SILC_HASH_MAXLEN 64
114 * Maximum size of digest any algorithm supported by SILC Crypto Toolkit
115 * would produce. You can use this to define static digest buffers and
116 * safely use it with any hash function.
120 * unsigned char digest[SILC_HASH_MAXLEN];
122 * silc_hash_make(hash, data, data_len, digest);
125 #define SILC_HASH_MAXLEN 64
127 /* Hash implementation object */
132 SilcUInt16 block_len;
134 void (*init)(void *);
135 void (*update)(void *, const unsigned char *, SilcUInt32);
136 void (*final)(void *, unsigned char *);
137 void (*transform)(void *, const unsigned char *);
138 SilcUInt32 (*context_len)();
141 /* Marks for all hash functions. This can be used in silc_hash_unregister
142 to unregister all hash function at once. */
143 #define SILC_ALL_HASH_FUNCTIONS ((SilcHashObject *)1)
145 /* Default hash functions for silc_hash_register_default(). */
146 extern DLLAPI const SilcHashObject silc_default_hash[];
150 /* Following macros are used to implement the SILC Hash API. These
151 macros should be used instead of declaring functions by hand. */
153 /* Macros that can be used to declare SILC Hash API functions. */
154 #define SILC_HASH_API_INIT(hash) \
155 void silc_##hash##_init(void *context)
156 #define SILC_HASH_API_UPDATE(hash) \
157 void silc_##hash##_update(void *context, const unsigned char *data, \
159 #define SILC_HASH_API_FINAL(hash) \
160 void silc_##hash##_final(void *context, unsigned char *digest)
161 #define SILC_HASH_API_TRANSFORM(hash) \
162 void silc_##hash##_transform(void *state, const unsigned char *buffer)
163 #define SILC_HASH_API_CONTEXT_LEN(hash) \
164 SilcUInt32 silc_##hash##_context_len()
168 /****f* silccrypt/silc_hash_register
172 * SilcBool silc_hash_register(const SilcHashObject *hash);
176 * Registers a new hash function into the SILC. This function can be
177 * used at the initialization. All registered hash functions should be
178 * unregistered with silc_hash_unregister. Returns FALSE on error.
179 * Usually this function is not needed. The default hash functions are
180 * automatically registered. This can be used to change the order of
181 * the registered hash functions by re-registering them in desired order,
182 * or add new hash functions.
185 SilcBool silc_hash_register(const SilcHashObject *hash);
187 /****f* silccrypt/silc_hash_unregister
191 * SilcBool silc_hash_unregister(SilcHashObject *hash);
195 * Unregister a hash function from SILC by the SilcHashObject `hash'.
196 * This should be called for all hash functions registered with
197 * silc_hash_register. Returns FALSE on error.
200 SilcBool silc_hash_unregister(SilcHashObject *hash);
202 /****f* silccrypt/silc_hash_register_default
206 * SilcBool silc_hash_register_default(void);
210 * Registers all default hash functions into the SILC. Application
211 * need not call this directly. By calling silc_crypto_init this function
215 SilcBool silc_hash_register_default(void);
217 /****f* silccrypt/silc_hash_unregister_all
221 * SilcBool silc_hash_unregister_all(void);
225 * Unregisters all registered hash functions. Application need not
226 * call this directly. By calling silc_crypto_uninit this function is
230 SilcBool silc_hash_unregister_all(void);
232 /****f* silccrypt/silc_hash_alloc
236 * SilcBool silc_hash_alloc(const char *name, SilcHash *new_hash);
240 * Allocates a new SilcHash object of name of `name'. The new allocated
241 * hash function is returned into `new_hash' pointer. This function
242 * returns FALSE if such hash function does not exist.
244 * See Hashes for supported hash functions.
247 SilcBool silc_hash_alloc(const char *name, SilcHash *new_hash);
249 /****f* silccrypt/silc_hash_alloc_by_oid
253 * SilcBool silc_hash_alloc_by_oid(const char *oid, SilcHash *new_hash);
257 * Same as silc_hash_alloc but allocates the hash algorithm by the
258 * hash algorithm OID string indicated by `oid'. Returns FALSE if such
259 * hash function does not exist.
261 * See Hash-OIDs for supported hash function OIDs.
264 SilcBool silc_hash_alloc_by_oid(const char *oid, SilcHash *new_hash);
266 /****f* silccrypt/silc_hash_free
270 * void silc_hash_free(SilcHash hash);
274 * Frees the allocated hash function context.
277 void silc_hash_free(SilcHash hash);
279 /****f* silccrypt/silc_hash_is_supported
283 * SilcBool silc_hash_is_supported(const char *name);
287 * Returns TRUE if the hash function indicated by the `name' exists.
290 SilcBool silc_hash_is_supported(const char *name);
292 /****f* silccrypt/silc_hash_get_supported
296 * char *silc_hash_get_supported(void);
300 * Returns comma (`,') separated list of registered hash functions This
301 * is used for example when sending supported hash function list during
302 * the SILC Key Exchange protocol (SKE). The caller must free the returned
306 char *silc_hash_get_supported(void);
308 /****f* silccrypt/silc_hash_len
312 * SilcUInt32 silc_hash_len(SilcHash hash);
316 * Returns the length of the message digest the hash function produce.
319 SilcUInt32 silc_hash_len(SilcHash hash);
321 /****f* silccrypt/silc_hash_block_len
325 * SilcUInt32 silc_hash_block_len(SilcHash hash);
329 * Returns the block length of the hash function.
332 SilcUInt32 silc_hash_block_len(SilcHash hash);
334 /****f* silccrypt/silc_hash_get_name
338 * const char *silc_hash_get_name(SilcHash hash);
342 * Returns the name of the hash function indicated by the `hash' context.
345 const char *silc_hash_get_name(SilcHash hash);
347 /****f* silccrypt/silc_hash_get_oid
351 * const char *silc_hash_get_name(SilcHash hash);
355 * Returns the hash OID string. Returns NULL if the hash doesn't have
356 * OID string. Use strlen() to get the OID string length.
359 const char *silc_hash_get_oid(SilcHash hash);
361 /****f* silccrypt/silc_hash_make
365 * void silc_hash_make(SilcHash hash, const unsigned char *data,
366 * SilcUInt32 len, unsigned char *return_hash);
370 * Computes the message digest (hash) out of the data indicated by
371 * `data' of length of `len' bytes. Returns the message digest to the
372 * `return_hash' buffer which must be at least of the size of the
373 * message digest the `hash' produces.
376 void silc_hash_make(SilcHash hash, const unsigned char *data,
377 SilcUInt32 len, unsigned char *return_hash);
379 /****f* silccrypt/silc_hash_init
383 * void silc_hash_init(SilcHash hash);
387 * Sometimes calling the silc_hash_make might not be the most optimal
388 * case of computing digests. If you have a lot of different data
389 * that you need to put together for computing a digest you may either
390 * put them into a buffer and compute the digest from the buffer by
391 * calling the silc_hash_make, or you can use the silc_hash_init,
392 * silc_hash_update and silc_hash_final to do the digest. This function
393 * prepares the allocated hash function context for this kind of digest
394 * computation. To add the data to be used in the digest computation
395 * call the silc_hash_update function.
398 void silc_hash_init(SilcHash hash);
400 /****f* silccrypt/silc_hash_update
404 * void silc_hash_update(SilcHash hash, const unsigned char *data,
405 * SilcUInt32 data_len);
409 * This function may be called to add data to be used in the digest
410 * computation. This can be called multiple times to add data from
411 * many sources before actually computing the digest. Once you've
412 * added all the data you need you can call the silc_hash_final to
413 * actually produce the message digest value.
417 * unsigned char digest[20];
419 * silc_hash_init(hash);
420 * silc_hash_update(hash, data, data_len);
421 * silc_hash_update(hash, more_data, more_data_len);
422 * silc_hash_final(hash, digest);
425 void silc_hash_update(SilcHash hash, const unsigned char *data,
426 SilcUInt32 data_len);
428 /****f* silccrypt/silc_hash_final
432 * void silc_hash_final(SilcHash hash, unsigned char *return_hash);
436 * This function is used to produce the final message digest from
437 * the data that has been added to the hash function context by calling
438 * the silc_hash_update function. The digest is copied in to the
439 * `return_hash' pointer which must be at least the size that
440 * the silc_hash_len returns.
443 void silc_hash_final(SilcHash hash, unsigned char *return_hash);
445 /****f* silccrypt/silc_hash_transform
449 * void silc_hash_transform(SilcHash hash, void *state,
450 * const unsigned char *data);
454 * This is special function for calling the hash function's internal
455 * digest generation function. The size of the `state' array and the
456 * sizeof the `data' buffer is hash function specific and must be
457 * known by the caller. Usually this function is not needed.
460 void silc_hash_transform(SilcHash hash, void *state,
461 const unsigned char *data);
463 /****f* silccrypt/silc_hash_fingerprint
467 * char *silc_hash_fingerprint(SilcHash hash, const unsigned char *data,
468 * SilcUInt32 data_len);
472 * Utility function which can be used to create a textual fingerprint
473 * out of the data indicated by `data' of length of `data_len' bytes.
474 * If `hash' is NULL then SHA1 hash function is used automatically.
475 * The caller must free the returned string.
477 * Example output could be:
478 * 41BF 5C2E 4149 039A 3917 831F 65C4 0A69 F98B 0A4D
481 char *silc_hash_fingerprint(SilcHash hash, const unsigned char *data,
482 SilcUInt32 data_len);
484 /****f* silccrypt/silc_hash_babbleprint
488 * char *silc_hash_babbleprint(SilcHash hash, const unsigned char *data,
489 * SilcUInt32 data_len);
493 * Utility function which can be used to create a textual babbleprint
494 * out of the data indicated by `data' of length of `data_len' bytes.
495 * If `hash' is NULL then SHA1 hash function is used automatically.
496 * The caller must free the returned string.
498 * The babbleprint is same as fingerprint but encoded in a form which
499 * makes it easier to pronounce. When verifying fingerprint for example
500 * over a phone call, the babbleprint makes it easier to read the
503 * Example output could be:
504 * xiber-zulad-vubug-noban-puvyc-labac-zonos-gedik-novem-rudog-tyxix
507 char *silc_hash_babbleprint(SilcHash hash, const unsigned char *data,
508 SilcUInt32 data_len);