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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Author: Stef Walter <stefw@collabora.co.uk>
  21  */
  22
  23 #include "config.h"
  24
  25 #include <string.h>
  26
  27 #include "ghmac.h"
  28
  29 #include "glib/galloca.h"
  30 #include "gatomic.h"
  31 #include "gslice.h"
  32 #include "gmem.h"
  33 #include "gstrfuncs.h"
  34 #include "gtestutils.h"
  35 #include "gtypes.h"
  36 #include "glibintl.h"
  37
  38
  39 /**
  40  * SECTION:hmac
  41  * @title: Secure HMAC Digests
  42  * @short_description: computes the HMAC for data
  43  *
  44  * HMACs should be used when producing a cookie or hash based on data
  45  * and a key. Simple mechanisms for using SHA1 and other algorithms to
  46  * digest a key and data together are vulnerable to various security
  47  * issues. <ulink url="http://en.wikipedia.org/wiki/HMAC">HMAC</ulink>
  48  * uses algorithms like SHA1 in a secure way to produce a digest of a
  49  * key and data.
  50  *
  51  * Both the key and data are arbitrary byte arrays of bytes or characters.
  52  *
  53  * Support for HMAC Digests has been added in GLib 2.30.
  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  * Return value: the newly created #GHmac, or %NULL.
  85  *   Use g_hmac_unref() to free the memory allocated by it.
  86  *
  87  * Since: 2.30
  88  */
  89 GHmac *
  90 g_hmac_new (GChecksumType  digest_type,
  91             const guchar  *key,
  92             gsize          key_len)
  93 {
  94   GChecksum *checksum;
  95   GHmac *hmac;
  96   guchar *buffer;
  97   guchar *pad;
  98   gsize i, len;
  99   gsize block_size;
 100
 101   checksum = g_checksum_new (digest_type);
 102   g_return_val_if_fail (checksum != NULL, NULL);
 103
 104   switch (digest_type)
 105     {
 106     case G_CHECKSUM_MD5:
 107     case G_CHECKSUM_SHA1:
 108       block_size = 64; /* RFC 2104 */
 109       break;
 110     case G_CHECKSUM_SHA256:
 111       block_size = 64; /* RFC draft-kelly-ipsec-ciph-sha2-01 */
 112       break;
 113     default:
 114       g_return_val_if_reached (NULL);
 115     }
 116
 117   hmac = g_slice_new0 (GHmac);
 118   hmac->ref_count = 1;
 119   hmac->digest_type = digest_type;
 120   hmac->digesti = checksum;
 121   hmac->digesto = g_checksum_new (digest_type);
 122
 123   buffer = g_alloca (block_size);
 124   pad = g_alloca (block_size);
 125
 126   memset (buffer, 0, block_size);
 127
 128   /* If the key is too long, hash it */
 129   if (key_len > block_size)
 130     {
 131       len = block_size;
 132       g_checksum_update (hmac->digesti, key, key_len);
 133       g_checksum_get_digest (hmac->digesti, buffer, &len);
 134       g_checksum_reset (hmac->digesti);
 135     }
 136
 137   /* Otherwise pad it with zeros */
 138   else
 139     {
 140       memcpy (buffer, key, key_len);
 141     }
 142
 143   /* First pad */
 144   for (i = 0; i < block_size; i++)
 145     pad[i] = 0x36 ^ buffer[i]; /* ipad value */
 146   g_checksum_update (hmac->digesti, pad, block_size);
 147
 148   /* Second pad */
 149   for (i = 0; i < block_size; i++)
 150     pad[i] = 0x5c ^ buffer[i]; /* opad value */
 151   g_checksum_update (hmac->digesto, pad, block_size);
 152
 153   return hmac;
 154 }
 155
 156 /**
 157  * g_hmac_copy:
 158  * @hmac: the #GHmac to copy
 159  *
 160  * Copies a #GHmac. If @hmac has been closed, by calling
 161  * g_hmac_get_string() or g_hmac_get_digest(), the copied
 162  * HMAC will be closed as well.
 163  *
 164  * Return value: the copy of the passed #GHmac. Use g_hmac_unref()
 165  *   when finished using it.
 166  *
 167  * Since: 2.30
 168  */
 169 GHmac *
 170 g_hmac_copy (const GHmac *hmac)
 171 {
 172   GHmac *copy;
 173
 174   g_return_val_if_fail (hmac != NULL, NULL);
 175
 176   copy = g_slice_new (GHmac);
 177   copy->ref_count = 1;
 178   copy->digest_type = hmac->digest_type;
 179   copy->digesti = g_checksum_copy (hmac->digesti);
 180   copy->digesto = g_checksum_copy (hmac->digesto);
 181
 182   return copy;
 183 }
 184
 185 /**
 186  * g_hmac_ref:
 187  * @hmac: a valid #GHmac
 188  *
 189  * Atomically increments the reference count of @hmac by one.
 190  *
 191  * This function is MT-safe and may be called from any thread.
 192  *
 193  * Return value: the passed in #GHmac.
 194  *
 195  * Since: 2.30
 196  **/
 197 GHmac *
 198 g_hmac_ref (GHmac *hmac)
 199 {
 200   g_return_val_if_fail (hmac != NULL, NULL);
 201
 202   g_atomic_int_inc (&hmac->ref_count);
 203
 204   return hmac;
 205 }
 206
 207 /**
 208  * g_hmac_unref:
 209  * @hmac: a #GHmac
 210  *
 211  * Atomically decrements the reference count of @hmac by one.
 212  *
 213  * If the reference count drops to 0, all keys and values will be
 214  * destroyed, and all memory allocated by the hash table is released.
 215  * This function is MT-safe and may be called from any thread.
 216  * Frees the memory allocated for @hmac.
 217  *
 218  * Since: 2.30
 219  */
 220 void
 221 g_hmac_unref (GHmac *hmac)
 222 {
 223   g_return_if_fail (hmac != NULL);
 224
 225   if (g_atomic_int_dec_and_test (&hmac->ref_count))
 226     {
 227       g_checksum_free (hmac->digesti);
 228       g_checksum_free (hmac->digesto);
 229       g_slice_free (GHmac, hmac);
 230     }
 231 }
 232
 233 /**
 234  * g_hmac_update:
 235  * @hmac: a #GHmac
 236  * @data: (array length=length): buffer used to compute the checksum
 237  * @length: size of the buffer, or -1 if it is a nul-terminated string
 238  *
 239  * Feeds @data into an existing #GHmac.
 240  *
 241  * The HMAC must still be open, that is g_hmac_get_string() or
 242  * g_hmac_get_digest() must not have been called on @hmac.
 243  *
 244  * Since: 2.30
 245  */
 246 void
 247 g_hmac_update (GHmac        *hmac,
 248                const guchar *data,
 249                gssize        length)
 250 {
 251   g_return_if_fail (hmac != NULL);
 252   g_return_if_fail (length == 0 || data != NULL);
 253
 254   g_checksum_update (hmac->digesti, data, length);
 255 }
 256
 257 /**
 258  * g_hmac_get_string:
 259  * @hmac: a #GHmac
 260  *
 261  * Gets the HMAC as an hexadecimal string.
 262  *
 263  * Once this function has been called the #GHmac can no longer be
 264  * updated with g_hmac_update().
 265  *
 266  * The hexadecimal characters will be lower case.
 267  *
 268  * Return value: the hexadecimal representation of the HMAC. The
 269  *   returned string is owned by the HMAC and should not be modified
 270  *   or freed.
 271  *
 272  * Since: 2.30
 273  */
 274 const gchar *
 275 g_hmac_get_string (GHmac *hmac)
 276 {
 277   guint8 *buffer;
 278   gsize digest_len;
 279
 280   g_return_val_if_fail (hmac != NULL, NULL);
 281
 282   digest_len = g_checksum_type_get_length (hmac->digest_type);
 283   buffer = g_alloca (digest_len);
 284
 285   /* This is only called for its side-effect of updating hmac->digesto... */
 286   g_hmac_get_digest (hmac, buffer, &digest_len);
 287   /* ... because we get the string from the checksum rather than
 288    * stringifying buffer ourselves
 289    */
 290   return g_checksum_get_string (hmac->digesto);
 291 }
 292
 293 /**
 294  * g_hmac_get_digest:
 295  * @hmac: a #GHmac
 296  * @buffer: output buffer
 297  * @digest_len: an inout parameter. The caller initializes it to the
 298  *   size of @buffer. After the call it contains the length of the digest
 299  *
 300  * Gets the digest from @checksum as a raw binary array and places it
 301  * into @buffer. The size of the digest depends on the type of checksum.
 302  *
 303  * Once this function has been called, the #GHmac is closed and can
 304  * no longer be updated with g_checksum_update().
 305  *
 306  * Since: 2.30
 307  */
 308 void
 309 g_hmac_get_digest (GHmac  *hmac,
 310                    guint8 *buffer,
 311                    gsize  *digest_len)
 312 {
 313   gsize len;
 314
 315   g_return_if_fail (hmac != NULL);
 316
 317   len = g_checksum_type_get_length (hmac->digest_type);
 318   g_return_if_fail (*digest_len >= len);
 319
 320   /* Use the same buffer, because we can :) */
 321   g_checksum_get_digest (hmac->digesti, buffer, &len);
 322   g_checksum_update (hmac->digesto, buffer, len);
 323   g_checksum_get_digest (hmac->digesto, buffer, digest_len);
 324 }
 325
 326 /**
 327  * g_compute_hmac_for_data:
 328  * @digest_type: a #GChecksumType to use for the HMAC
 329  * @key: (array length=key_len): the key to use in the HMAC
 330  * @key_len: the length of the key
 331  * @data: binary blob to compute the HMAC of
 332  * @length: length of @data
 333  *
 334  * Computes the HMAC for a binary @data of @length. This is a
 335  * convenience wrapper for g_hmac_new(), g_hmac_get_string()
 336  * and g_hmac_unref().
 337  *
 338  * The hexadecimal string returned will be in lower case.
 339  *
 340  * Return value: the HMAC of the binary data as a string in hexadecimal.
 341  *   The returned string should be freed with g_free() when done using it.
 342  *
 343  * Since: 2.30
 344  */
 345 gchar *
 346 g_compute_hmac_for_data (GChecksumType  digest_type,
 347                          const guchar  *key,
 348                          gsize          key_len,
 349                          const guchar  *data,
 350                          gsize          length)
 351 {
 352   GHmac *hmac;
 353   gchar *retval;
 354
 355   g_return_val_if_fail (length == 0 || data != NULL, NULL);
 356
 357   hmac = g_hmac_new (digest_type, key, key_len);
 358   if (!hmac)
 359     return NULL;
 360
 361   g_hmac_update (hmac, data, length);
 362   retval = g_strdup (g_hmac_get_string (hmac));
 363   g_hmac_unref (hmac);
 364
 365   return retval;
 366 }
 367
 368 /**
 369  * g_compute_hmac_for_string:
 370  * @digest_type: a #GChecksumType to use for the HMAC
 371  * @key: (array length=key_len): the key to use in the HMAC
 372  * @key_len: the length of the key
 373  * @str: the string to compute the HMAC for
 374  * @length: the length of the string, or -1 if the string is nul-terminated
 375  *
 376  * Computes the HMAC for a string.
 377  *
 378  * The hexadecimal string returned will be in lower case.
 379  *
 380  * Return value: the HMAC as a hexadecimal string.
 381  *     The returned string should be freed with g_free()
 382  *     when done using it.
 383  *
 384  * Since: 2.30
 385  */
 386 gchar *
 387 g_compute_hmac_for_string (GChecksumType  digest_type,
 388                            const guchar  *key,
 389                            gsize          key_len,
 390                            const gchar   *str,
 391                            gssize         length)
 392 {
 393   g_return_val_if_fail (length == 0 || str != NULL, NULL);
 394
 395   if (length < 0)
 396     length = strlen (str);
 397
 398   return g_compute_hmac_for_data (digest_type, key, key_len,
 399                                   (const guchar *) str, length);
 400 }