5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2005 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 Hash Interface
27 * This is the interface for hash functions which are used to create
28 * message digests. The routines are used in various cryptographic
29 * operations. SILC Hash Interface is used for example by the
30 * SILC HMAC Interface (SilcHmac).
34 /****s* silccrypt/SilcHashAPI/SilcHash
38 * typedef struct SilcHashStruct *SilcHash;
42 * This context is the actual hash function context and is allocated
43 * by silc_hash_alloc and given as argument usually to all
44 * silc_hash_* functions. It is freed by the silc_hash_free
48 typedef struct SilcHashStruct *SilcHash;
50 /****s* silccrypt/SilcHashAPI/SilcHashObject
54 * typedef struct { ... } SilcHashObject;
58 * This structure represents one hash function. The hash function's
59 * name, digest length and block length are defined in the structure.
60 * This structure is then given as argument to the silc_hash_register.
61 * That function is used to register all hash functions into SILC.
62 * They can be then allocated by the name found in this structure by
63 * calling the silc_hash_alloc.
72 void (*update)(void *, const unsigned char *, SilcUInt32);
73 void (*final)(void *, unsigned char *);
74 void (*transform)(SilcUInt32 *, const unsigned char *);
75 SilcUInt32 (*context_len)();
78 /* Marks for all hash functions. This can be used in silc_hash_unregister
79 to unregister all hash function at once. */
80 #define SILC_ALL_HASH_FUNCTIONS ((SilcHashObject *)1)
82 /* Default hash functions for silc_hash_register_default(). */
83 extern DLLAPI const SilcHashObject silc_default_hash[];
85 /* Default HASH function in the SILC protocol */
86 #define SILC_DEFAULT_HASH "sha1"
87 #define SILC_HASH_MAXLEN 64
91 /* Following macros are used to implement the SILC Hash API. These
92 macros should be used instead of declaring functions by hand. */
94 /* Function names in SILC Hash modules. The name of the hash function
95 is appended into these names and used to the get correct symbol out
96 of the module. All SILC Hash API compliant modules has to support
97 these names as function names (use macros below to assure this). */
98 #define SILC_HASH_SIM_INIT "init"
99 #define SILC_HASH_SIM_UPDATE "update"
100 #define SILC_HASH_SIM_FINAL "final"
101 #define SILC_HASH_SIM_TRANSFORM "transform"
102 #define SILC_HASH_SIM_CONTEXT_LEN "context_len"
104 /* Macros that can be used to declare SILC Hash API functions. */
105 #define SILC_HASH_API_INIT(hash) \
106 void silc_##hash##_init(void *context)
107 #define SILC_HASH_API_UPDATE(hash) \
108 void silc_##hash##_update(void *context, const unsigned char *data, \
110 #define SILC_HASH_API_FINAL(hash) \
111 void silc_##hash##_final(void *context, unsigned char *digest)
112 #define SILC_HASH_API_TRANSFORM(hash) \
113 void silc_##hash##_transform(SilcUInt32 *state, const unsigned char *buffer)
114 #define SILC_HASH_API_CONTEXT_LEN(hash) \
115 SilcUInt32 silc_##hash##_context_len()
119 /****f* silccrypt/SilcHashAPI/silc_hash_register
123 * SilcBool silc_hash_register(const SilcHashObject *hash);
127 * Registers a new hash function into the SILC. This function is used
128 * at the initialization of the SILC. All registered hash functions
129 * should be unregistered with silc_hash_unregister. The `hash' includes
130 * the name of the hash function, digest length and block length. Usually
131 * this function is not called directly. Instead, application can call
132 * the silc_hash_register_default to register all default hash functions
133 * that are builtin the sources. Returns FALSE on error.
136 SilcBool silc_hash_register(const SilcHashObject *hash);
138 /****f* silccrypt/SilcHashAPI/silc_hash_unregister
142 * SilcBool silc_hash_unregister(SilcHashObject *hash);
146 * Unregister a hash function from SILC by the SilcHashObject `hash'.
147 * This should be called for all registered hash functions. Returns
151 SilcBool silc_hash_unregister(SilcHashObject *hash);
153 /****f* silccrypt/SilcHashAPI/silc_hash_register_default
157 * SilcBool silc_hash_register_default(void);
161 * Registers all default hash functions into the SILC. These are the
162 * hash functions that are builtin in the sources. See the list of
163 * default hash functions in the silchash.c source file. The application
164 * may use this to register default hash functions if specific hash
165 * function in any specific order is not wanted (application's
166 * configuration usually may decide the order of the registration, in
167 * which case this function should not be used).
170 SilcBool silc_hash_register_default(void);
172 /****f* silccrypt/SilcHashAPI/silc_hash_unregister_all
176 * SilcBool silc_hash_unregister_all(void);
180 * Unregisters all registered hash functions.
183 SilcBool silc_hash_unregister_all(void);
185 /****f* silccrypt/SilcHashAPI/silc_hash_alloc
189 * SilcBool silc_hash_alloc(const unsigned char *name, SilcHash *new_hash);
193 * Allocates a new SilcHash object of name of `name'. The new allocated
194 * hash function is returned into `new_hash' pointer. This function
195 * returns FALSE if such hash function does not exist.
198 SilcBool silc_hash_alloc(const unsigned char *name, SilcHash *new_hash);
200 /****f* silccrypt/SilcHashAPI/silc_hash_free
204 * void silc_hash_free(SilcHash hash);
208 * Frees the allocated hash function context.
211 void silc_hash_free(SilcHash hash);
213 /****f* silccrypt/SilcHashAPI/silc_hash_is_supported
217 * SilcBool silc_hash_is_supported(const unsigned char *name);
221 * Returns TRUE if the hash function indicated by the `name' exists.
224 SilcBool silc_hash_is_supported(const unsigned char *name);
226 /****f* silccrypt/SilcHashAPI/silc_hash_get_supported
230 * char *silc_hash_get_supported(void);
234 * Returns comma (`,') separated list of registered hash functions This
235 * is used for example when sending supported hash function list during
236 * the SILC Key Exchange protocol (SKE). The caller must free the returned
240 char *silc_hash_get_supported(void);
242 /****f* silccrypt/SilcHashAPI/silc_hash_len
246 * SilcUInt32 silc_hash_len(SilcHash hash);
250 * Returns the length of the message digest the hash function produce.
253 SilcUInt32 silc_hash_len(SilcHash hash);
255 /****f* silccrypt/SilcHashAPI/silc_hash_block_len
259 * SilcUInt32 silc_hash_block_len(SilcHash hash);
263 * Returns the block length of the hash function.
266 SilcUInt32 silc_hash_block_len(SilcHash hash);
268 /****f* silccrypt/SilcHashAPI/silc_hash_get_name
272 * const char *silc_hash_get_name(SilcHash hash);
276 * Returns the name of the hash function indicated by the `hash' context.
279 const char *silc_hash_get_name(SilcHash hash);
281 /****f* silccrypt/SilcHashAPI/silc_hash_make
285 * void silc_hash_make(SilcHash hash, const unsigned char *data,
286 * SilcUInt32 len, unsigned char *return_hash);
290 * Computes the message digest (hash) out of the data indicated by
291 * `data' of length of `len' bytes. Returns the message digest to the
292 * `return_hash' buffer which must be at least of the size of the
293 * message digest the `hash' produces.
296 void silc_hash_make(SilcHash hash, const unsigned char *data,
297 SilcUInt32 len, unsigned char *return_hash);
299 /****f* silccrypt/SilcHashAPI/silc_hash_init
303 * void silc_hash_init(SilcHash hash);
307 * Sometimes calling the silc_hash_make might not be the most optimal
308 * case of computing digests. If you have a lot of different data
309 * that you need to put together for computing a digest you may either
310 * put them into a buffer and compute the digest from the buffer by
311 * calling the silc_hash_make, or you can use the silc_hash_init,
312 * silc_hash_update and silc_hash_final to do the digest. This function
313 * prepares the allocated hash function context for this kind of digest
314 * computation. To add the data to be used in the digest computation
315 * call the silc_hash_update function.
318 void silc_hash_init(SilcHash hash);
320 /****f* silccrypt/SilcHashAPI/silc_hash_update
324 * void silc_hash_update(SilcHash hash, const unsigned char *data,
325 * SilcUInt32 data_len);
329 * This function may be called to add data to be used in the digest
330 * computation. This can be called multiple times to add data from
331 * many sources before actually computing the digest. Once you've
332 * added all the data you need you can call the silc_hash_final to
333 * actually produce the message digest value.
337 * unsigned char digest[20];
339 * silc_hash_init(hash);
340 * silc_hash_update(hash, data, data_len);
341 * silc_hash_update(hash, more_data, more_data_len);
342 * silc_hash_final(hash, digest);
345 void silc_hash_update(SilcHash hash, const unsigned char *data,
346 SilcUInt32 data_len);
348 /****f* silccrypt/SilcHashAPI/silc_hash_final
352 * void silc_hash_final(SilcHash hash, unsigned char *return_hash);
356 * This function is used to produce the final message digest from
357 * the data that has been added to the hash function context by calling
358 * the silc_hash_update function. The digest is copied in to the
359 * `return_hash' pointer which must be at least the size that
360 * the silc_hash_len returns.
363 void silc_hash_final(SilcHash hash, unsigned char *return_hash);
365 /****f* silccrypt/SilcHashAPI/silc_hash_transform
369 * void silc_hash_transform(SilcHash hash, SilcUInt32 *state,
370 * const unsigned char *data);
374 * This is special function for calling the hash function's internal
375 * digest generation function. The size of the `state' array and the
376 * sizeof the `data' buffer is hash function specific and must be
377 * known by the caller. Usually this function is not needed.
380 void silc_hash_transform(SilcHash hash, SilcUInt32 *state,
381 const unsigned char *data);
383 /****f* silccrypt/SilcHashAPI/silc_hash_fingerprint
387 * char *silc_hash_fingerprint(SilcHash hash, const unsigned char *data,
388 * SilcUInt32 data_len);
392 * Utility function which can be used to create a textual fingerprint
393 * out of the data indicated by `data' of length of `data_len' bytes.
394 * If `hash' is NULL then SHA1 hash function is used automatically.
395 * The caller must free the returned string.
397 * Example output could be:
398 * 41BF 5C2E 4149 039A 3917 831F 65C4 0A69 F98B 0A4D
401 char *silc_hash_fingerprint(SilcHash hash, const unsigned char *data,
402 SilcUInt32 data_len);
404 /****f* silccrypt/SilcHashAPI/silc_hash_babbleprint
408 * char *silc_hash_babbleprint(SilcHash hash, const unsigned char *data,
409 * SilcUInt32 data_len);
413 * Utility function which can be used to create a textual babbleprint
414 * out of the data indicated by `data' of length of `data_len' bytes.
415 * If `hash' is NULL then SHA1 hash function is used automatically.
416 * The caller must free the returned string.
418 * The babbleprint is same as fingerprint but encoded in a form which
419 * makes it easier to pronounce. When verifying fingerprint for example
420 * over a phone call, the babbleprint makes it easier to read the
423 * Example output could be:
424 * xiber-zulad-vubug-noban-puvyc-labac-zonos-gedik-novem-rudog-tyxix
427 char *silc_hash_babbleprint(SilcHash hash, const unsigned char *data,
428 SilcUInt32 data_len);