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 Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 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 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public License
16 * 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, and support for SHA-512
53 * in GLib 2.42. Support for SHA-384 was added in GLib 2.52.
59 GChecksumType digest_type
;
66 * @digest_type: the desired type of digest
67 * @key: (array length=key_len): the key for the HMAC
68 * @key_len: the length of the keys
70 * Creates a new #GHmac, using the digest algorithm @digest_type.
71 * If the @digest_type is not known, %NULL is returned.
72 * A #GHmac can be used to compute the HMAC of a key and an
73 * arbitrary binary blob, using different hashing algorithms.
75 * A #GHmac works by feeding a binary blob through g_hmac_update()
76 * until the data is complete; the digest can then be extracted
77 * using g_hmac_get_string(), which will return the checksum as a
78 * hexadecimal string; or g_hmac_get_digest(), which will return a
79 * array of raw bytes. Once either g_hmac_get_string() or
80 * g_hmac_get_digest() have been called on a #GHmac, the HMAC
81 * will be closed and it won't be possible to call g_hmac_update()
84 * Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42.
85 * Support for %G_CHECKSUM_SHA384 was added in GLib 2.52.
87 * Returns: the newly created #GHmac, or %NULL.
88 * Use g_hmac_unref() to free the memory allocated by it.
93 g_hmac_new (GChecksumType digest_type
,
104 checksum
= g_checksum_new (digest_type
);
105 g_return_val_if_fail (checksum
!= NULL
, NULL
);
110 case G_CHECKSUM_SHA1
:
111 block_size
= 64; /* RFC 2104 */
113 case G_CHECKSUM_SHA256
:
114 block_size
= 64; /* RFC 4868 */
116 case G_CHECKSUM_SHA384
:
117 case G_CHECKSUM_SHA512
:
118 block_size
= 128; /* RFC 4868 */
121 g_return_val_if_reached (NULL
);
124 hmac
= g_slice_new0 (GHmac
);
126 hmac
->digest_type
= digest_type
;
127 hmac
->digesti
= checksum
;
128 hmac
->digesto
= g_checksum_new (digest_type
);
130 buffer
= g_alloca (block_size
);
131 pad
= g_alloca (block_size
);
133 memset (buffer
, 0, block_size
);
135 /* If the key is too long, hash it */
136 if (key_len
> block_size
)
139 g_checksum_update (hmac
->digesti
, key
, key_len
);
140 g_checksum_get_digest (hmac
->digesti
, buffer
, &len
);
141 g_checksum_reset (hmac
->digesti
);
144 /* Otherwise pad it with zeros */
147 memcpy (buffer
, key
, key_len
);
151 for (i
= 0; i
< block_size
; i
++)
152 pad
[i
] = 0x36 ^ buffer
[i
]; /* ipad value */
153 g_checksum_update (hmac
->digesti
, pad
, block_size
);
156 for (i
= 0; i
< block_size
; i
++)
157 pad
[i
] = 0x5c ^ buffer
[i
]; /* opad value */
158 g_checksum_update (hmac
->digesto
, pad
, block_size
);
165 * @hmac: the #GHmac to copy
167 * Copies a #GHmac. If @hmac has been closed, by calling
168 * g_hmac_get_string() or g_hmac_get_digest(), the copied
169 * HMAC will be closed as well.
171 * Returns: the copy of the passed #GHmac. Use g_hmac_unref()
172 * when finished using it.
177 g_hmac_copy (const GHmac
*hmac
)
181 g_return_val_if_fail (hmac
!= NULL
, NULL
);
183 copy
= g_slice_new (GHmac
);
185 copy
->digest_type
= hmac
->digest_type
;
186 copy
->digesti
= g_checksum_copy (hmac
->digesti
);
187 copy
->digesto
= g_checksum_copy (hmac
->digesto
);
194 * @hmac: a valid #GHmac
196 * Atomically increments the reference count of @hmac by one.
198 * This function is MT-safe and may be called from any thread.
200 * Returns: the passed in #GHmac.
205 g_hmac_ref (GHmac
*hmac
)
207 g_return_val_if_fail (hmac
!= NULL
, NULL
);
209 g_atomic_int_inc (&hmac
->ref_count
);
218 * Atomically decrements the reference count of @hmac by one.
220 * If the reference count drops to 0, all keys and values will be
221 * destroyed, and all memory allocated by the hash table is released.
222 * This function is MT-safe and may be called from any thread.
223 * Frees the memory allocated for @hmac.
228 g_hmac_unref (GHmac
*hmac
)
230 g_return_if_fail (hmac
!= NULL
);
232 if (g_atomic_int_dec_and_test (&hmac
->ref_count
))
234 g_checksum_free (hmac
->digesti
);
235 g_checksum_free (hmac
->digesto
);
236 g_slice_free (GHmac
, hmac
);
243 * @data: (array length=length): buffer used to compute the checksum
244 * @length: size of the buffer, or -1 if it is a nul-terminated string
246 * Feeds @data into an existing #GHmac.
248 * The HMAC must still be open, that is g_hmac_get_string() or
249 * g_hmac_get_digest() must not have been called on @hmac.
254 g_hmac_update (GHmac
*hmac
,
258 g_return_if_fail (hmac
!= NULL
);
259 g_return_if_fail (length
== 0 || data
!= NULL
);
261 g_checksum_update (hmac
->digesti
, data
, length
);
268 * Gets the HMAC as an hexadecimal string.
270 * Once this function has been called the #GHmac can no longer be
271 * updated with g_hmac_update().
273 * The hexadecimal characters will be lower case.
275 * Returns: the hexadecimal representation of the HMAC. The
276 * returned string is owned by the HMAC and should not be modified
282 g_hmac_get_string (GHmac
*hmac
)
287 g_return_val_if_fail (hmac
!= NULL
, NULL
);
289 digest_len
= g_checksum_type_get_length (hmac
->digest_type
);
290 buffer
= g_alloca (digest_len
);
292 /* This is only called for its side-effect of updating hmac->digesto... */
293 g_hmac_get_digest (hmac
, buffer
, &digest_len
);
294 /* ... because we get the string from the checksum rather than
295 * stringifying buffer ourselves
297 return g_checksum_get_string (hmac
->digesto
);
303 * @buffer: output buffer
304 * @digest_len: an inout parameter. The caller initializes it to the
305 * size of @buffer. After the call it contains the length of the digest
307 * Gets the digest from @checksum as a raw binary array and places it
308 * into @buffer. The size of the digest depends on the type of checksum.
310 * Once this function has been called, the #GHmac is closed and can
311 * no longer be updated with g_checksum_update().
316 g_hmac_get_digest (GHmac
*hmac
,
322 g_return_if_fail (hmac
!= NULL
);
324 len
= g_checksum_type_get_length (hmac
->digest_type
);
325 g_return_if_fail (*digest_len
>= len
);
327 /* Use the same buffer, because we can :) */
328 g_checksum_get_digest (hmac
->digesti
, buffer
, &len
);
329 g_checksum_update (hmac
->digesto
, buffer
, len
);
330 g_checksum_get_digest (hmac
->digesto
, buffer
, digest_len
);
334 * g_compute_hmac_for_data:
335 * @digest_type: a #GChecksumType to use for the HMAC
336 * @key: (array length=key_len): the key to use in the HMAC
337 * @key_len: the length of the key
338 * @data: (array length=length): binary blob to compute the HMAC of
339 * @length: length of @data
341 * Computes the HMAC for a binary @data of @length. This is a
342 * convenience wrapper for g_hmac_new(), g_hmac_get_string()
343 * and g_hmac_unref().
345 * The hexadecimal string returned will be in lower case.
347 * Returns: the HMAC of the binary data as a string in hexadecimal.
348 * The returned string should be freed with g_free() when done using it.
353 g_compute_hmac_for_data (GChecksumType digest_type
,
362 g_return_val_if_fail (length
== 0 || data
!= NULL
, NULL
);
364 hmac
= g_hmac_new (digest_type
, key
, key_len
);
368 g_hmac_update (hmac
, data
, length
);
369 retval
= g_strdup (g_hmac_get_string (hmac
));
376 * g_compute_hmac_for_bytes:
377 * @digest_type: a #GChecksumType to use for the HMAC
378 * @key: the key to use in the HMAC
379 * @data: binary blob to compute the HMAC of
381 * Computes the HMAC for a binary @data. This is a
382 * convenience wrapper for g_hmac_new(), g_hmac_get_string()
383 * and g_hmac_unref().
385 * The hexadecimal string returned will be in lower case.
387 * Returns: the HMAC of the binary data as a string in hexadecimal.
388 * The returned string should be freed with g_free() when done using it.
393 g_compute_hmac_for_bytes (GChecksumType digest_type
,
397 gconstpointer byte_data
;
399 gconstpointer key_data
;
402 g_return_val_if_fail (data
!= NULL
, NULL
);
403 g_return_val_if_fail (key
!= NULL
, NULL
);
405 byte_data
= g_bytes_get_data (data
, &length
);
406 key_data
= g_bytes_get_data (key
, &key_len
);
407 return g_compute_hmac_for_data (digest_type
, key_data
, key_len
, byte_data
, length
);
412 * g_compute_hmac_for_string:
413 * @digest_type: a #GChecksumType to use for the HMAC
414 * @key: (array length=key_len): the key to use in the HMAC
415 * @key_len: the length of the key
416 * @str: the string to compute the HMAC for
417 * @length: the length of the string, or -1 if the string is nul-terminated
419 * Computes the HMAC for a string.
421 * The hexadecimal string returned will be in lower case.
423 * Returns: the HMAC as a hexadecimal string.
424 * The returned string should be freed with g_free()
425 * when done using it.
430 g_compute_hmac_for_string (GChecksumType digest_type
,
436 g_return_val_if_fail (length
== 0 || str
!= NULL
, NULL
);
439 length
= strlen (str
);
441 return g_compute_hmac_for_data (digest_type
, key
, key_len
,
442 (const guchar
*) str
, length
);