glib/ghmac.c

   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 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.
   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  * Library General Public License for more details.
  14  *
  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/>.
  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.
  53  */
  54
  55 struct _GHmac
  56 {
  57   int ref_count;
  58   GChecksumType digest_type;
  59   GChecksum *digesti;
  60   GChecksum *digesto;
  61 };
  62
  63 /**
  64  * g_hmac_new:
  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
  68  *
  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.
  73  *
  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()
  81  * on it anymore.
  82  *
  83  * Return value: the newly created #GHmac, or %NULL.
  84  *   Use g_hmac_unref() to free the memory allocated by it.
  85  *
  86  * Since: 2.30
  87  */
  88 GHmac *
  89 g_hmac_new (GChecksumType  digest_type,
  90             const guchar  *key,
  91             gsize          key_len)
  92 {
  93   GChecksum *checksum;
  94   GHmac *hmac;
  95   guchar *buffer;
  96   guchar *pad;
  97   gsize i, len;
  98   gsize block_size;
  99
 100   checksum = g_checksum_new (digest_type);
 101   g_return_val_if_fail (checksum != NULL, NULL);
 102
 103   switch (digest_type)
 104     {
 105     case G_CHECKSUM_MD5:
 106     case G_CHECKSUM_SHA1:
 107       block_size = 64; /* RFC 2104 */
 108       break;
 109     case G_CHECKSUM_SHA256:
 110       block_size = 64; /* RFC draft-kelly-ipsec-ciph-sha2-01 */
 111       break;
 112     default:
 113       g_return_val_if_reached (NULL);
 114     }
 115
 116   hmac = g_slice_new0 (GHmac);
 117   hmac->ref_count = 1;
 118   hmac->digest_type = digest_type;
 119   hmac->digesti = checksum;
 120   hmac->digesto = g_checksum_new (digest_type);
 121
 122   buffer = g_alloca (block_size);
 123   pad = g_alloca (block_size);
 124
 125   memset (buffer, 0, block_size);
 126
 127   /* If the key is too long, hash it */
 128   if (key_len > block_size)
 129     {
 130       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);
 134     }
 135
 136   /* Otherwise pad it with zeros */
 137   else
 138     {
 139       memcpy (buffer, key, key_len);
 140     }
 141
 142   /* First pad */
 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);
 146
 147   /* Second pad */
 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);
 151
 152   return hmac;
 153 }
 154
 155 /**
 156  * g_hmac_copy:
 157  * @hmac: the #GHmac to copy
 158  *
 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.
 162  *
 163  * Return value: the copy of the passed #GHmac. Use g_hmac_unref()
 164  *   when finished using it.
 165  *
 166  * Since: 2.30
 167  */
 168 GHmac *
 169 g_hmac_copy (const GHmac *hmac)
 170 {
 171   GHmac *copy;
 172
 173   g_return_val_if_fail (hmac != NULL, NULL);
 174
 175   copy = g_slice_new (GHmac);
 176   copy->ref_count = 1;
 177   copy->digest_type = hmac->digest_type;
 178   copy->digesti = g_checksum_copy (hmac->digesti);
 179   copy->digesto = g_checksum_copy (hmac->digesto);
 180
 181   return copy;
 182 }
 183
 184 /**
 185  * g_hmac_ref:
 186  * @hmac: a valid #GHmac
 187  *
 188  * Atomically increments the reference count of @hmac by one.
 189  *
 190  * This function is MT-safe and may be called from any thread.
 191  *
 192  * Return value: the passed in #GHmac.
 193  *
 194  * Since: 2.30
 195  **/
 196 GHmac *
 197 g_hmac_ref (GHmac *hmac)
 198 {
 199   g_return_val_if_fail (hmac != NULL, NULL);
 200
 201   g_atomic_int_inc (&hmac->ref_count);
 202
 203   return hmac;
 204 }
 205
 206 /**
 207  * g_hmac_unref:
 208  * @hmac: a #GHmac
 209  *
 210  * Atomically decrements the reference count of @hmac by one.
 211  *
 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.
 216  *
 217  * Since: 2.30
 218  */
 219 void
 220 g_hmac_unref (GHmac *hmac)
 221 {
 222   g_return_if_fail (hmac != NULL);
 223
 224   if (g_atomic_int_dec_and_test (&hmac->ref_count))
 225     {
 226       g_checksum_free (hmac->digesti);
 227       g_checksum_free (hmac->digesto);
 228       g_slice_free (GHmac, hmac);
 229     }
 230 }
 231
 232 /**
 233  * g_hmac_update:
 234  * @hmac: a #GHmac
 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
 237  *
 238  * Feeds @data into an existing #GHmac.
 239  *
 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.
 242  *
 243  * Since: 2.30
 244  */
 245 void
 246 g_hmac_update (GHmac        *hmac,
 247                const guchar *data,
 248                gssize        length)
 249 {
 250   g_return_if_fail (hmac != NULL);
 251   g_return_if_fail (length == 0 || data != NULL);
 252
 253   g_checksum_update (hmac->digesti, data, length);
 254 }
 255
 256 /**
 257  * g_hmac_get_string:
 258  * @hmac: a #GHmac
 259  *
 260  * Gets the HMAC as an hexadecimal string.
 261  *
 262  * Once this function has been called the #GHmac can no longer be
 263  * updated with g_hmac_update().
 264  *
 265  * The hexadecimal characters will be lower case.
 266  *
 267  * Return value: the hexadecimal representation of the HMAC. The
 268  *   returned string is owned by the HMAC and should not be modified
 269  *   or freed.
 270  *
 271  * Since: 2.30
 272  */
 273 const gchar *
 274 g_hmac_get_string (GHmac *hmac)
 275 {
 276   guint8 *buffer;
 277   gsize digest_len;
 278
 279   g_return_val_if_fail (hmac != NULL, NULL);
 280
 281   digest_len = g_checksum_type_get_length (hmac->digest_type);
 282   buffer = g_alloca (digest_len);
 283
 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
 288    */
 289   return g_checksum_get_string (hmac->digesto);
 290 }
 291
 292 /**
 293  * g_hmac_get_digest:
 294  * @hmac: a #GHmac
 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
 298  *
 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.
 301  *
 302  * Once this function has been called, the #GHmac is closed and can
 303  * no longer be updated with g_checksum_update().
 304  *
 305  * Since: 2.30
 306  */
 307 void
 308 g_hmac_get_digest (GHmac  *hmac,
 309                    guint8 *buffer,
 310                    gsize  *digest_len)
 311 {
 312   gsize len;
 313
 314   g_return_if_fail (hmac != NULL);
 315
 316   len = g_checksum_type_get_length (hmac->digest_type);
 317   g_return_if_fail (*digest_len >= len);
 318
 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);
 323 }
 324
 325 /**
 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
 332  *
 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().
 336  *
 337  * The hexadecimal string returned will be in lower case.
 338  *
 339  * Return value: 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.
 341  *
 342  * Since: 2.30
 343  */
 344 gchar *
 345 g_compute_hmac_for_data (GChecksumType  digest_type,
 346                          const guchar  *key,
 347                          gsize          key_len,
 348                          const guchar  *data,
 349                          gsize          length)
 350 {
 351   GHmac *hmac;
 352   gchar *retval;
 353
 354   g_return_val_if_fail (length == 0 || data != NULL, NULL);
 355
 356   hmac = g_hmac_new (digest_type, key, key_len);
 357   if (!hmac)
 358     return NULL;
 359
 360   g_hmac_update (hmac, data, length);
 361   retval = g_strdup (g_hmac_get_string (hmac));
 362   g_hmac_unref (hmac);
 363
 364   return retval;
 365 }
 366
 367 /**
 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
 374  *
 375  * Computes the HMAC for a string.
 376  *
 377  * The hexadecimal string returned will be in lower case.
 378  *
 379  * Return value: the HMAC as a hexadecimal string.
 380  *     The returned string should be freed with g_free()
 381  *     when done using it.
 382  *
 383  * Since: 2.30
 384  */
 385 gchar *
 386 g_compute_hmac_for_string (GChecksumType  digest_type,
 387                            const guchar  *key,
 388                            gsize          key_len,
 389                            const gchar   *str,
 390                            gssize         length)
 391 {
 392   g_return_val_if_fail (length == 0 || str != NULL, NULL);
 393
 394   if (length < 0)
 395     length = strlen (str);
 396
 397   return g_compute_hmac_for_data (digest_type, key, key_len,
 398                                   (const guchar *) str, length);
 399 }