1mhash(3) mhash library mhash(3)
2
6 mhash - Hash Library
7
9 mhash 0.9.2
10
12 #include "mhash.h"
13 Informative Functions
15 size_t mhash_count(void);
17 size_t mhash_get_block_size(hashid type);
18 char *mhash_get_hash_name(hashid type);
19 size_t mhash_get_hash_pblock(hashid type);
20 hashid mhash_get_mhash_algo( MHASH);
21 Key Generation Functions
23 int mhash_keygen_ext(keygenid algorithm, KEYGEN algorithm_data,
25 void* keyword, int keysize,
26 unsigned char* password, int passwordlen);
27 Initializing Functions
29 MHASH mhash_init(hashid type);
31 MHASH mhash_hmac_init(const hashid type, void *key, int keysize, int block);
32 MHASH mhash_cp( MHASH);
33 Update Functions
35 int mhash(MHASH thread, const void *plaintext, size_t size);
37 Save/Restore Functions
39 int mhash_save_state_mem(MHASH thread, void *mem, int* mem_size );
41 MHASH mhash_restore_state_mem(void* mem);
42 Finalizing Functions
44 void mhash_deinit(MHASH thread, void *result);
46 void *mhash_end(MHASH thread);
47 void *mhash_end_m(MHASH thread, void* (*hash_malloc)(size_t));
48 void *mhash_hmac_end(MHASH thread);
50 void *mhash_hmac_end_m(MHASH thread, void* (*hash_malloc)(size_t));
51 int mhash_hmac_deinit(MHASH thread, void *result);
52 Available Hashes
54 CRC32: The crc32 algorithm is used to compute checksums. The two vari‐
56 ants used in mhash are: MHASH_CRC32 (like the one used in ethernet) and
57 MHASH_CRC32B (like the one used in ZIP programs).
58 ADLER32: The adler32 algorithm is used to compute checksums. It is
60 faster than CRC32 and it is considered to be as reliable as CRC32. This
61 algorithm is defined as MHASH_ADLER32.
62 MD5: The MD5 algorithm by Ron Rivest and RSA. In mhash this algorithm
64 is defined as MHASH_MD5.
65 MD4: The MD4 algorithm by Ron Rivest and RSA. This algorithm is consid‐
67 ered broken, so don't use it. In mhash this algorithm is defined as
68 MHASH_MD4.
69 SHA1/SHA256: The SHA algorithm by US. NIST/NSA. This algorithm is spec‐
71 ified for use in the NIST's Digital Signature Standard. In mhash these
72 algorithm are defined as MHASH_SHA1 and MHASH_SHA256.
73 HAVAL: HAVAL is a one-way hashing algorithm with variable length of
75 output. HAVAL is a modification of MD5. Defined in mhash as:
76 MHASH_HAVAL256, MHASH_HAVAL192, MHASH_HAVAL160, MHASH_HAVAL128.
77 RIPEMD160: RIPEMD-160 is a 160-bit cryptographic hash function,
79 designed by Hans Dobbertin, Antoon Bosselaers, and Bart Preneel. It is
80 intended to be used as a secure replacement for the 128-bit hash func‐
81 tions MD4, MD5, and RIPEMD. MD4 and MD5 were developed by Ron Rivest
82 for RSA Data Security, while RIPEMD was developed in the framework of
83 the EU project RIPE (RACE Integrity Primitives Evaluation, 1988-1992).
84 In mhash this algorithm is defined as MHASH_RIPEMD160.
85 TIGER: Tiger is a fast hash function, by Eli Biham and Ross Anderson.
87 Tiger was designed to be very fast on modern computers, and in particu‐
88 lar on the state-of-the-art 64-bit computers, while it is still not
89 slower than other suggested hash functions on 32-bit machines. In
90 mhash this algorithm is defined as: MHASH_TIGER, MHASH_TIGER160,
91 MHASH_TIGER128.
92 GOST: GOST algorithm is a russian standard and it uses the GOST encryp‐
94 tion algorithm to produce a 256 bit hash value. This algorithm is spec‐
95 ified for use in the Russian Digital Signature Standard. In mhash this
96 algorithm is defined as MHASH_GOST.
97 Available Key Generation algorithms
99 KEYGEN_MCRYPT: The key generator used in mcrypt.
101 KEYGEN_ASIS: Just returns the password as binary key.
103 KEYGEN_HEX: Just converts a hex key into a binary one.
105 KEYGEN_PKDES: The transformation used in Phil Karn's DES encryption
107 program.
108 KEYGEN_S2K_SIMPLE: The OpenPGP (rfc2440) Simple S2K.
110 KEYGEN_S2K_SALTED: The OpenPGP Salted S2K.
112 KEYGEN_S2K_ISALTED: The OpenPGP Iterated Salted S2K.
114
116 The mhash library provides an easy to use C interface for several hash
117 algorithms (also known as "one-way" algorithms). These can be used to
118 create checksums, message digests and more. Currently, MD5, SHA1, GOST,
119 TIGER, RIPE-MD160, HAVAL and several other algorithms are supported.
120 mhash support HMAC generation (a mechanism for message authentication
121 using cryptographic hash functions, and is described in rfc2104). HMAC
122 can be used to create message digests using a secret key, so that these
123 message digests cannot be regenerated (or replaced) by someone else. A
124 key generation mechanism was added to mhash since key generation algo‐
125 rithms usually involve hash algorithms.
126
128 We will describe the API of mhash in detail now. The order follows the
129 one in the SYNOPSIS directly.
130 size_t mhash_count(void);
132 This returns the "hashid" of the last available hash. Hashes are
133 numbered from 0 to "mhash_count()".
134 size_t mhash_get_block_size(hashid type);
136 If type exists, this returns the used blocksize of the hash type in
137 bytes. Otherwise, it returns 0.
138 char *mhash_get_hash_name(hashid type);
140 If type exists, this returns the name of the hash type. Otherwise,
141 a "NULL" pointer is returned. The string is allocated with mal‐
142 loc(3) seperately, so do not forget to free(3) it.
143 const char *mhash_get_hash_name_static(hashid type);
145 If type exists, this returns the name of the hash type. Otherwise,
146 a "NULL" pointer is returned.
147 size_t mhash_get_hash_pblock(hashid type);
149 It returns the block size that the algorithm operates. This is used
150 in mhash_hmac_init. If the return value is 0 you shouldn't use that
151 algorithm in HMAC.
152 hashid mhash_get_mhash_algo(MHASH src);
154 Returns the algorithm used in the state of src.
155 MHASH mhash_init(hashid type);
157 This setups a context to begin hashing using the algorithm type. It
158 returns a descriptor to that context which will result in leaking
159 memory, if you do not call mhash_deinit(3) later. Returns
160 "MHASH_FAILED" on failure.
161 MHASH mhash_hmac_init(const hashid type, void *key, int keysize, int
163 block);
164 This setups a context to begin hashing using the algorithm type in
165 HMAC mode. key should be a pointer to the key and keysize its len.
166 The block is the block size (in bytes) that the algorithm operates.
167 It should be obtained by mhash_get_hash_pblock(). If its 0 it
168 defaults to 64. After calling it you should use mhash() to update
169 the context. It returns a descriptor to that context which will
170 result in leaking memory, if you do not call mhash_hmac_deinit(3)
171 later. Returns "MHASH_FAILED" on failure.
172 MHASH mhash_cp(MHASH src);
174 This setups a new context using the state of src.
175 int mhash(MHASH thread, const void *plaintext, size_t size);
177 This updates the context described by thread with plaintext. size
178 is the length of plaintext which may be binary data.
179 int mhash_save_state_mem( MHASH thread, void *mem, int* mem_size);
181 Saves the state of a hashing algorithm such that it can be restored
182 at some later point in time using mhash_restore_state_mem().
183 mem_size should contain the size of the given mem pointer. If it is
184 not enough to hold the buffer the required value will be copied
185 there.
186 MHASH mhash_restore_state_mem(void* mem);
188 Restores the state of a hashing algorithm that was saved using
189 mhash_save_state_mem(). Use like mhash_init().
190 void *mhash_end(MHASH thread);
192 This frees all resources associated with thread and returns the
193 result of the whole hashing operation (the ``digest'').
194 void mhash_deinit(MHASH thread, void* digest);
196 This frees all resources associated with thread and stores the
197 result of the whole hashing operation in memory pointed by digest.
198 digest may be null.
199 void *mhash_hmac_end(MHASH thread);
201 This frees all resources associated with thread and returns the
202 result of the whole hashing operation (the ``mac'').
203 int mhash_hmac_deinit(MHASH thread, void* digest);
205 This frees all resources associated with thread and stores the
206 result of the whole hashing operation in memory pointed by digest.
207 Digest may be null. Returns non-zero in case of an error.
208 void *mhash_end_m(MHASH thread, void* (*hash_malloc)(size_t));
210 This frees all resources associated with thread and returns the
211 result of the whole hashing operation (the ``digest''). The result
212 will be allocated by using the hash_malloc() function provided.
213 void *mhash_hmac_end(MHASH thread, void* (*hash_malloc)(size_t));
215 This frees all resources associated with thread and returns the
216 result of the whole hashing operation (the ``mac''). The result
217 will be allocated by using the hash_malloc() function provided.
218
220 We will now describe the Key Generation API of mhash in detail.
221 int mhash_keygen_ext(keygenid algorithm, KEYGEN algorithm_data, void*
223 keyword, int keysize, unsigned char* password, int passwordlen);
224 This function, generates a key from a password. The password is
225 read from password and it's len should be in passwordlen. The key
226 generation algorithm is specified in algorithm, and that algorithm
227 may (internally) use the KEYGEN structure. The KEYGEN structure
228 consists of:
229 typedef struct keygen {
230 hashid hash_algorithm[2];
231 unsigned int count;
232 void* salt;
233 int salt_size;
234 } KEYGEN;
235 The algorithm(s) specified in algorithm_data.hash_algorithm, should
237 be hash algorithms and may be used by the key generation algorithm.
238 Some key generation algorithms may use more than one hash algo‐
239 rithms (view also mhash_keygen_uses_hash_algorithm()). If it is
240 desirable (and supported by the algorithm, eg. KEYGEN_S2K_SALTED) a
241 salt may be specified in algorithm_data.salt of size algo‐
242 rithm_data.salt_size or may be NULL.
243 The algorithm may use the algorithm_data.count internally (eg. KEY‐
245 GEN_S2K_ISALTED). The generated keyword is stored in keyword,
246 which should be (at least) keysize bytes long. The generated key‐
247 word is a binary one. Returns a negative number on failure.
248 int mhash_keygen_uses_salt( keygenid algorithm);
250 This function returns 1 if the specified key generation algorithm
251 needs a salt to be specified.
252 int mhash_keygen_uses_count( keygenid algorithm);
254 This function returns 1 if the specified key generation algorithm
255 needs the algorithm_data.count field in mhash_keygen_ext(). The
256 count field tells the algorithm to hash repeatedly the password and
257 to stop when count bytes have been processed.
258 int mhash_get_keygen_salt_size( keygenid algorithm);
260 This function returns the size of the salt size, that the specific
261 algorithm will use. If it returns 0, then there is no limitation in
262 the size.
263 int mhash_get_keygen_max_key_size( keygenid algorithm);
265 This function returns the maximum size of the key, that the key
266 generation algorithm may produce. If it returns 0, then there is
267 no limitation in the size.
268 int mhash_keygen_uses_hash_algorithm( keygenid algorithm);
270 This function returns the number of the hash algorithms the key
271 generation algorithm will use. If it is 0 then no hash algorithm is
272 used by the key generation algorithm. This is for the algo‐
273 rithm_data.hash_algorithm field in mhash_keygen_ext(). If
274 size_t mhash_keygen_count(void);
276 This returns the "keygenid" of the last available key generation
277 algorithm. Algorithms are numbered from 0 to "mhash_key‐
278 gen_count()".
279 char *mhash_get_keygen_name(keygenid type);
281 If type exists, this returns the name of the keygen type. Other‐
282 wise, a "NULL" pointer is returned. The string is allocated with
283 malloc(3) seperately, so do not forget to free(3) it.
284 const char *mhash_get_keygen_name_static(keygenid type);
286 If type exists, this returns the name of the keygen type. Other‐
287 wise, a "NULL" pointer is returned.
288
290 Hashing STDIN until EOF.
291 #include <mhash.h>
293 #include <stdio.h>
294 #include <stdlib.h>
295 int main(void)
297 {
298 int i;
299 MHASH td;
300 unsigned char buffer;
301 unsigned char hash[16]; /* enough size for MD5 */
302 td = mhash_init(MHASH_MD5);
304 if (td == MHASH_FAILED) exit(1);
306 while (fread(&buffer, 1, 1, stdin) == 1) {
308 mhash(td, &buffer, 1);
309 }
310 mhash_deinit(td, hash);
312 printf("Hash:");
314 for (i = 0; i < mhash_get_block_size(MHASH_MD5); i++) {
315 printf("%.2x", hash[i]);
316 }
317 printf("\n");
318 exit(0);
320 }
321
323 An example program using HMAC:
324 #include <mhash.h>
326 #include <stdio.h>
327 int main()
329 {
330 char password[] = "Jefe";
332 int keylen = 4;
333 char data[] = "what do ya want for nothing?";
334 int datalen = 28;
335 MHASH td;
336 unsigned char mac[16];
337 int j;
338 td = mhash_hmac_init(MHASH_MD5, password, keylen,
340 mhash_get_hash_pblock(MHASH_MD5));
341 mhash(td, data, datalen);
343 mhash_hmac_deinit(td, mac);
344 /*
346 * The output should be 0x750c783e6ab0b503eaa86e310a5db738
347 * according to RFC 2104.
348 */
349 printf("0x");
351 for (j = 0; j < mhash_get_block_size(MHASH_MD5); j++) {
352 printf("%.2x", mac[j]);
353 }
354 printf("\n");
355 exit(0);
357 }
358
360 This library was originally written by Nikos Mavroyanopoulos <nmav@hel‐
361 lug.gr> who passed the project over to Sascha Schumann <sascha@schu‐
362 mann.cx> in May 1999. Sascha maintained it until March 2000. The
363 library is now maintained by Nikos Mavroyanopoulos.
364
366 If you find any, please send a bug report (preferrably together with a
367 patch) to the maintainer with a detailed description on how to repro‐
368 duce the bug.
369
371 Sascha Schumann <sascha@schumann.cx> Nikos Mavroyanopoulos <nmav@hel‐
372 lug.gr>
373mhash 0.9.2 2000/03/23 mhash(3)