1 /* ghmac.h - data hashing functions
3 * Copyright (C) 2011 Collabora Ltd.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
15 * You should have received a copy of the GNU Library General Public
16 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 * Author: Stef Walter <stefw@collabora.co.uk>
27 #include "glib/galloca.h"
31 #include "gstrfuncs.h"
32 #include "gtestutils.h"
39 * @title: Secure HMAC Digests
40 * @short_description: computes the HMAC for data
42 * HMACs should be used when producing a cookie or hash based on data
43 * and a key. Simple mechanisms for using SHA1 and other algorithms to
44 * digest a key and data together are vulnerable to various security
46 * [HMAC](http://en.wikipedia.org/wiki/HMAC)
47 * uses algorithms like SHA1 in a secure way to produce a digest of a
50 * Both the key and data are arbitrary byte arrays of bytes or characters.
52 * Support for HMAC Digests has been added in GLib 2.30.
58 GChecksumType digest_type;
65 * @digest_type: the desired type of digest
66 * @key: (array length=key_len): the key for the HMAC
67 * @key_len: the length of the keys
69 * Creates a new #GHmac, using the digest algorithm @digest_type.
70 * If the @digest_type is not known, %NULL is returned.
71 * A #GHmac can be used to compute the HMAC of a key and an
72 * arbitrary binary blob, using different hashing algorithms.
74 * A #GHmac works by feeding a binary blob through g_hmac_update()
75 * until the data is complete; the digest can then be extracted
76 * using g_hmac_get_string(), which will return the checksum as a
77 * hexadecimal string; or g_hmac_get_digest(), which will return a
78 * array of raw bytes. Once either g_hmac_get_string() or
79 * g_hmac_get_digest() have been called on a #GHmac, the HMAC
80 * will be closed and it won't be possible to call g_hmac_update()
83 * Returns: the newly created #GHmac, or %NULL.
84 * Use g_hmac_unref() to free the memory allocated by it.
89 g_hmac_new (GChecksumType digest_type,
100 checksum = g_checksum_new (digest_type);
101 g_return_val_if_fail (checksum != NULL, NULL);
106 case G_CHECKSUM_SHA1:
107 block_size = 64; /* RFC 2104 */
109 case G_CHECKSUM_SHA256:
110 block_size = 64; /* RFC draft-kelly-ipsec-ciph-sha2-01 */
113 g_return_val_if_reached (NULL);
116 hmac = g_slice_new0 (GHmac);
118 hmac->digest_type = digest_type;
119 hmac->digesti = checksum;
120 hmac->digesto = g_checksum_new (digest_type);
122 buffer = g_alloca (block_size);
123 pad = g_alloca (block_size);
125 memset (buffer, 0, block_size);
127 /* If the key is too long, hash it */
128 if (key_len > block_size)
131 g_checksum_update (hmac->digesti, key, key_len);
132 g_checksum_get_digest (hmac->digesti, buffer, &len);
133 g_checksum_reset (hmac->digesti);
136 /* Otherwise pad it with zeros */
139 memcpy (buffer, key, key_len);
143 for (i = 0; i < block_size; i++)
144 pad[i] = 0x36 ^ buffer[i]; /* ipad value */
145 g_checksum_update (hmac->digesti, pad, block_size);
148 for (i = 0; i < block_size; i++)
149 pad[i] = 0x5c ^ buffer[i]; /* opad value */
150 g_checksum_update (hmac->digesto, pad, block_size);
157 * @hmac: the #GHmac to copy
159 * Copies a #GHmac. If @hmac has been closed, by calling
160 * g_hmac_get_string() or g_hmac_get_digest(), the copied
161 * HMAC will be closed as well.
163 * Returns: the copy of the passed #GHmac. Use g_hmac_unref()
164 * when finished using it.
169 g_hmac_copy (const GHmac *hmac)
173 g_return_val_if_fail (hmac != NULL, NULL);
175 copy = g_slice_new (GHmac);
177 copy->digest_type = hmac->digest_type;
178 copy->digesti = g_checksum_copy (hmac->digesti);
179 copy->digesto = g_checksum_copy (hmac->digesto);
186 * @hmac: a valid #GHmac
188 * Atomically increments the reference count of @hmac by one.
190 * This function is MT-safe and may be called from any thread.
192 * Returns: the passed in #GHmac.
197 g_hmac_ref (GHmac *hmac)
199 g_return_val_if_fail (hmac != NULL, NULL);
201 g_atomic_int_inc (&hmac->ref_count);
210 * Atomically decrements the reference count of @hmac by one.
212 * If the reference count drops to 0, all keys and values will be
213 * destroyed, and all memory allocated by the hash table is released.
214 * This function is MT-safe and may be called from any thread.
215 * Frees the memory allocated for @hmac.
220 g_hmac_unref (GHmac *hmac)
222 g_return_if_fail (hmac != NULL);
224 if (g_atomic_int_dec_and_test (&hmac->ref_count))
226 g_checksum_free (hmac->digesti);
227 g_checksum_free (hmac->digesto);
228 g_slice_free (GHmac, hmac);
235 * @data: (array length=length): buffer used to compute the checksum
236 * @length: size of the buffer, or -1 if it is a nul-terminated string
238 * Feeds @data into an existing #GHmac.
240 * The HMAC must still be open, that is g_hmac_get_string() or
241 * g_hmac_get_digest() must not have been called on @hmac.
246 g_hmac_update (GHmac *hmac,
250 g_return_if_fail (hmac != NULL);
251 g_return_if_fail (length == 0 || data != NULL);
253 g_checksum_update (hmac->digesti, data, length);
260 * Gets the HMAC as an hexadecimal string.
262 * Once this function has been called the #GHmac can no longer be
263 * updated with g_hmac_update().
265 * The hexadecimal characters will be lower case.
267 * Returns: the hexadecimal representation of the HMAC. The
268 * returned string is owned by the HMAC and should not be modified
274 g_hmac_get_string (GHmac *hmac)
279 g_return_val_if_fail (hmac != NULL, NULL);
281 digest_len = g_checksum_type_get_length (hmac->digest_type);
282 buffer = g_alloca (digest_len);
284 /* This is only called for its side-effect of updating hmac->digesto... */
285 g_hmac_get_digest (hmac, buffer, &digest_len);
286 /* ... because we get the string from the checksum rather than
287 * stringifying buffer ourselves
289 return g_checksum_get_string (hmac->digesto);
295 * @buffer: output buffer
296 * @digest_len: an inout parameter. The caller initializes it to the
297 * size of @buffer. After the call it contains the length of the digest
299 * Gets the digest from @checksum as a raw binary array and places it
300 * into @buffer. The size of the digest depends on the type of checksum.
302 * Once this function has been called, the #GHmac is closed and can
303 * no longer be updated with g_checksum_update().
308 g_hmac_get_digest (GHmac *hmac,
314 g_return_if_fail (hmac != NULL);
316 len = g_checksum_type_get_length (hmac->digest_type);
317 g_return_if_fail (*digest_len >= len);
319 /* Use the same buffer, because we can :) */
320 g_checksum_get_digest (hmac->digesti, buffer, &len);
321 g_checksum_update (hmac->digesto, buffer, len);
322 g_checksum_get_digest (hmac->digesto, buffer, digest_len);
326 * g_compute_hmac_for_data:
327 * @digest_type: a #GChecksumType to use for the HMAC
328 * @key: (array length=key_len): the key to use in the HMAC
329 * @key_len: the length of the key
330 * @data: binary blob to compute the HMAC of
331 * @length: length of @data
333 * Computes the HMAC for a binary @data of @length. This is a
334 * convenience wrapper for g_hmac_new(), g_hmac_get_string()
335 * and g_hmac_unref().
337 * The hexadecimal string returned will be in lower case.
339 * Returns: the HMAC of the binary data as a string in hexadecimal.
340 * The returned string should be freed with g_free() when done using it.
345 g_compute_hmac_for_data (GChecksumType digest_type,
354 g_return_val_if_fail (length == 0 || data != NULL, NULL);
356 hmac = g_hmac_new (digest_type, key, key_len);
360 g_hmac_update (hmac, data, length);
361 retval = g_strdup (g_hmac_get_string (hmac));
368 * g_compute_hmac_for_string:
369 * @digest_type: a #GChecksumType to use for the HMAC
370 * @key: (array length=key_len): the key to use in the HMAC
371 * @key_len: the length of the key
372 * @str: the string to compute the HMAC for
373 * @length: the length of the string, or -1 if the string is nul-terminated
375 * Computes the HMAC for a string.
377 * The hexadecimal string returned will be in lower case.
379 * Returns: the HMAC as a hexadecimal string.
380 * The returned string should be freed with g_free()
381 * when done using it.
386 g_compute_hmac_for_string (GChecksumType digest_type,
392 g_return_val_if_fail (length == 0 || str != NULL, NULL);
395 length = strlen (str);
397 return g_compute_hmac_for_data (digest_type, key, key_len,
398 (const guchar *) str, length);