1 | /* ghmac.h - data hashing functions |
2 | * |
3 | * Copyright (C) 2011 Collabora Ltd. |
4 | * |
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. |
9 | * |
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. |
14 | * |
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/>. |
17 | * |
18 | * Author: Stef Walter <stefw@collabora.co.uk> |
19 | */ |
20 | |
21 | #include "config.h" |
22 | |
23 | #include <string.h> |
24 | |
25 | #include "ghmac.h" |
26 | |
27 | #include "glib/galloca.h" |
28 | #include "gatomic.h" |
29 | #include "gslice.h" |
30 | #include "gmem.h" |
31 | #include "gstrfuncs.h" |
32 | #include "gtestutils.h" |
33 | #include "gtypes.h" |
34 | #include "glibintl.h" |
35 | |
36 | |
37 | /** |
38 | * SECTION:hmac |
39 | * @title: Secure HMAC Digests |
40 | * @short_description: computes the HMAC for data |
41 | * |
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 |
45 | * issues. |
46 | * [HMAC](http://en.wikipedia.org/wiki/HMAC) |
47 | * uses algorithms like SHA1 in a secure way to produce a digest of a |
48 | * key and data. |
49 | * |
50 | * Both the key and data are arbitrary byte arrays of bytes or characters. |
51 | * |
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. |
54 | */ |
55 | |
56 | struct _GHmac |
57 | { |
58 | int ref_count; |
59 | GChecksumType digest_type; |
60 | GChecksum *digesti; |
61 | GChecksum *digesto; |
62 | }; |
63 | |
64 | /** |
65 | * g_hmac_new: |
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 |
69 | * |
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. |
74 | * |
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() |
82 | * on it anymore. |
83 | * |
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. |
86 | * |
87 | * Returns: the newly created #GHmac, or %NULL. |
88 | * Use g_hmac_unref() to free the memory allocated by it. |
89 | * |
90 | * Since: 2.30 |
91 | */ |
92 | GHmac * |
93 | g_hmac_new (GChecksumType digest_type, |
94 | const guchar *key, |
95 | gsize key_len) |
96 | { |
97 | GChecksum *checksum; |
98 | GHmac *hmac; |
99 | guchar *buffer; |
100 | guchar *pad; |
101 | gsize i, len; |
102 | gsize block_size; |
103 | |
104 | checksum = g_checksum_new (checksum_type: digest_type); |
105 | g_return_val_if_fail (checksum != NULL, NULL); |
106 | |
107 | switch (digest_type) |
108 | { |
109 | case G_CHECKSUM_MD5: |
110 | case G_CHECKSUM_SHA1: |
111 | block_size = 64; /* RFC 2104 */ |
112 | break; |
113 | case G_CHECKSUM_SHA256: |
114 | block_size = 64; /* RFC 4868 */ |
115 | break; |
116 | case G_CHECKSUM_SHA384: |
117 | case G_CHECKSUM_SHA512: |
118 | block_size = 128; /* RFC 4868 */ |
119 | break; |
120 | default: |
121 | g_return_val_if_reached (NULL); |
122 | } |
123 | |
124 | hmac = g_slice_new0 (GHmac); |
125 | hmac->ref_count = 1; |
126 | hmac->digest_type = digest_type; |
127 | hmac->digesti = checksum; |
128 | hmac->digesto = g_checksum_new (checksum_type: digest_type); |
129 | |
130 | buffer = g_alloca (block_size); |
131 | pad = g_alloca (block_size); |
132 | |
133 | memset (s: buffer, c: 0, n: block_size); |
134 | |
135 | /* If the key is too long, hash it */ |
136 | if (key_len > block_size) |
137 | { |
138 | len = block_size; |
139 | g_checksum_update (checksum: hmac->digesti, data: key, length: key_len); |
140 | g_checksum_get_digest (checksum: hmac->digesti, buffer, digest_len: &len); |
141 | g_checksum_reset (checksum: hmac->digesti); |
142 | } |
143 | |
144 | /* Otherwise pad it with zeros */ |
145 | else |
146 | { |
147 | memcpy (dest: buffer, src: key, n: key_len); |
148 | } |
149 | |
150 | /* First pad */ |
151 | for (i = 0; i < block_size; i++) |
152 | pad[i] = 0x36 ^ buffer[i]; /* ipad value */ |
153 | g_checksum_update (checksum: hmac->digesti, data: pad, length: block_size); |
154 | |
155 | /* Second pad */ |
156 | for (i = 0; i < block_size; i++) |
157 | pad[i] = 0x5c ^ buffer[i]; /* opad value */ |
158 | g_checksum_update (checksum: hmac->digesto, data: pad, length: block_size); |
159 | |
160 | return hmac; |
161 | } |
162 | |
163 | /** |
164 | * g_hmac_copy: |
165 | * @hmac: the #GHmac to copy |
166 | * |
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. |
170 | * |
171 | * Returns: the copy of the passed #GHmac. Use g_hmac_unref() |
172 | * when finished using it. |
173 | * |
174 | * Since: 2.30 |
175 | */ |
176 | GHmac * |
177 | g_hmac_copy (const GHmac *hmac) |
178 | { |
179 | GHmac *copy; |
180 | |
181 | g_return_val_if_fail (hmac != NULL, NULL); |
182 | |
183 | copy = g_slice_new (GHmac); |
184 | copy->ref_count = 1; |
185 | copy->digest_type = hmac->digest_type; |
186 | copy->digesti = g_checksum_copy (checksum: hmac->digesti); |
187 | copy->digesto = g_checksum_copy (checksum: hmac->digesto); |
188 | |
189 | return copy; |
190 | } |
191 | |
192 | /** |
193 | * g_hmac_ref: |
194 | * @hmac: a valid #GHmac |
195 | * |
196 | * Atomically increments the reference count of @hmac by one. |
197 | * |
198 | * This function is MT-safe and may be called from any thread. |
199 | * |
200 | * Returns: the passed in #GHmac. |
201 | * |
202 | * Since: 2.30 |
203 | **/ |
204 | GHmac * |
205 | g_hmac_ref (GHmac *hmac) |
206 | { |
207 | g_return_val_if_fail (hmac != NULL, NULL); |
208 | |
209 | g_atomic_int_inc (&hmac->ref_count); |
210 | |
211 | return hmac; |
212 | } |
213 | |
214 | /** |
215 | * g_hmac_unref: |
216 | * @hmac: a #GHmac |
217 | * |
218 | * Atomically decrements the reference count of @hmac by one. |
219 | * |
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. |
224 | * |
225 | * Since: 2.30 |
226 | */ |
227 | void |
228 | g_hmac_unref (GHmac *hmac) |
229 | { |
230 | g_return_if_fail (hmac != NULL); |
231 | |
232 | if (g_atomic_int_dec_and_test (&hmac->ref_count)) |
233 | { |
234 | g_checksum_free (checksum: hmac->digesti); |
235 | g_checksum_free (checksum: hmac->digesto); |
236 | g_slice_free (GHmac, hmac); |
237 | } |
238 | } |
239 | |
240 | /** |
241 | * g_hmac_update: |
242 | * @hmac: a #GHmac |
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 |
245 | * |
246 | * Feeds @data into an existing #GHmac. |
247 | * |
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. |
250 | * |
251 | * Since: 2.30 |
252 | */ |
253 | void |
254 | g_hmac_update (GHmac *hmac, |
255 | const guchar *data, |
256 | gssize length) |
257 | { |
258 | g_return_if_fail (hmac != NULL); |
259 | g_return_if_fail (length == 0 || data != NULL); |
260 | |
261 | g_checksum_update (checksum: hmac->digesti, data, length); |
262 | } |
263 | |
264 | /** |
265 | * g_hmac_get_string: |
266 | * @hmac: a #GHmac |
267 | * |
268 | * Gets the HMAC as a hexadecimal string. |
269 | * |
270 | * Once this function has been called the #GHmac can no longer be |
271 | * updated with g_hmac_update(). |
272 | * |
273 | * The hexadecimal characters will be lower case. |
274 | * |
275 | * Returns: the hexadecimal representation of the HMAC. The |
276 | * returned string is owned by the HMAC and should not be modified |
277 | * or freed. |
278 | * |
279 | * Since: 2.30 |
280 | */ |
281 | const gchar * |
282 | g_hmac_get_string (GHmac *hmac) |
283 | { |
284 | guint8 *buffer; |
285 | gsize digest_len; |
286 | |
287 | g_return_val_if_fail (hmac != NULL, NULL); |
288 | |
289 | digest_len = g_checksum_type_get_length (checksum_type: hmac->digest_type); |
290 | buffer = g_alloca (digest_len); |
291 | |
292 | /* This is only called for its side-effect of updating hmac->digesto... */ |
293 | g_hmac_get_digest (hmac, buffer, digest_len: &digest_len); |
294 | /* ... because we get the string from the checksum rather than |
295 | * stringifying buffer ourselves |
296 | */ |
297 | return g_checksum_get_string (checksum: hmac->digesto); |
298 | } |
299 | |
300 | /** |
301 | * g_hmac_get_digest: |
302 | * @hmac: a #GHmac |
303 | * @buffer: (array length=digest_len): output buffer |
304 | * @digest_len: (inout): an inout parameter. The caller initializes it to the |
305 | * size of @buffer. After the call it contains the length of the digest |
306 | * |
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. |
309 | * |
310 | * Once this function has been called, the #GHmac is closed and can |
311 | * no longer be updated with g_checksum_update(). |
312 | * |
313 | * Since: 2.30 |
314 | */ |
315 | void |
316 | g_hmac_get_digest (GHmac *hmac, |
317 | guint8 *buffer, |
318 | gsize *digest_len) |
319 | { |
320 | gsize len; |
321 | |
322 | g_return_if_fail (hmac != NULL); |
323 | |
324 | len = g_checksum_type_get_length (checksum_type: hmac->digest_type); |
325 | g_return_if_fail (*digest_len >= len); |
326 | |
327 | /* Use the same buffer, because we can :) */ |
328 | g_checksum_get_digest (checksum: hmac->digesti, buffer, digest_len: &len); |
329 | g_checksum_update (checksum: hmac->digesto, data: buffer, length: len); |
330 | g_checksum_get_digest (checksum: hmac->digesto, buffer, digest_len); |
331 | } |
332 | |
333 | /** |
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 |
340 | * |
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(). |
344 | * |
345 | * The hexadecimal string returned will be in lower case. |
346 | * |
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. |
349 | * |
350 | * Since: 2.30 |
351 | */ |
352 | gchar * |
353 | g_compute_hmac_for_data (GChecksumType digest_type, |
354 | const guchar *key, |
355 | gsize key_len, |
356 | const guchar *data, |
357 | gsize length) |
358 | { |
359 | GHmac *hmac; |
360 | gchar *retval; |
361 | |
362 | g_return_val_if_fail (length == 0 || data != NULL, NULL); |
363 | |
364 | hmac = g_hmac_new (digest_type, key, key_len); |
365 | if (!hmac) |
366 | return NULL; |
367 | |
368 | g_hmac_update (hmac, data, length); |
369 | retval = g_strdup (str: g_hmac_get_string (hmac)); |
370 | g_hmac_unref (hmac); |
371 | |
372 | return retval; |
373 | } |
374 | |
375 | /** |
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 |
380 | * |
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(). |
384 | * |
385 | * The hexadecimal string returned will be in lower case. |
386 | * |
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. |
389 | * |
390 | * Since: 2.50 |
391 | */ |
392 | gchar * |
393 | g_compute_hmac_for_bytes (GChecksumType digest_type, |
394 | GBytes *key, |
395 | GBytes *data) |
396 | { |
397 | gconstpointer byte_data; |
398 | gsize length; |
399 | gconstpointer key_data; |
400 | gsize key_len; |
401 | |
402 | g_return_val_if_fail (data != NULL, NULL); |
403 | g_return_val_if_fail (key != NULL, NULL); |
404 | |
405 | byte_data = g_bytes_get_data (bytes: data, size: &length); |
406 | key_data = g_bytes_get_data (bytes: key, size: &key_len); |
407 | return g_compute_hmac_for_data (digest_type, key: key_data, key_len, data: byte_data, length); |
408 | } |
409 | |
410 | |
411 | /** |
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 |
418 | * |
419 | * Computes the HMAC for a string. |
420 | * |
421 | * The hexadecimal string returned will be in lower case. |
422 | * |
423 | * Returns: the HMAC as a hexadecimal string. |
424 | * The returned string should be freed with g_free() |
425 | * when done using it. |
426 | * |
427 | * Since: 2.30 |
428 | */ |
429 | gchar * |
430 | g_compute_hmac_for_string (GChecksumType digest_type, |
431 | const guchar *key, |
432 | gsize key_len, |
433 | const gchar *str, |
434 | gssize length) |
435 | { |
436 | g_return_val_if_fail (length == 0 || str != NULL, NULL); |
437 | |
438 | if (length < 0) |
439 | length = strlen (s: str); |
440 | |
441 | return g_compute_hmac_for_data (digest_type, key, key_len, |
442 | data: (const guchar *) str, length); |
443 | } |
444 | |