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->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_malloc (digest_len);
 283
 284   g_hmac_get_digest (hmac, buffer, &digest_len);
 285   return g_checksum_get_string (hmac->digesto);
 286 }
 287
 288 /**
 289  * g_hmac_get_digest:
 290  * @hmac: a #GHmac
 291  * @buffer: output buffer
 292  * @digest_len: an inout parameter. The caller initializes it to the
 293  *   size of @buffer. After the call it contains the length of the digest
 294  *
 295  * Gets the digest from @checksum as a raw binary array and places it
 296  * into @buffer. The size of the digest depends on the type of checksum.
 297  *
 298  * Once this function has been called, the #GHmac is closed and can
 299  * no longer be updated with g_checksum_update().
 300  *
 301  * Since: 2.30
 302  */
 303 void
 304 g_hmac_get_digest (GHmac  *hmac,
 305                    guint8 *buffer,
 306                    gsize  *digest_len)
 307 {
 308   gsize len;
 309
 310   g_return_if_fail (hmac != NULL);
 311
 312   len = g_checksum_type_get_length (hmac->digest_type);
 313   g_return_if_fail (*digest_len >= len);
 314
 315   /* Use the same buffer, because we can :) */
 316   g_checksum_get_digest (hmac->digesti, buffer, &len);
 317   g_checksum_update (hmac->digesto, buffer, len);
 318   g_checksum_get_digest (hmac->digesto, buffer, digest_len);
 319 }
 320
 321 /**
 322  * g_compute_hmac_for_data:
 323  * @digest_type: a #GChecksumType to use for the HMAC
 324  * @key: (array length=key_len): the key to use in the HMAC
 325  * @key_len: the length of the key
 326  * @data: binary blob to compute the HMAC of
 327  * @length: length of @data
 328  *
 329  * Computes the HMAC for a binary @data of @length. This is a
 330  * convenience wrapper for g_hmac_new(), g_hmac_get_string()
 331  * and g_hmac_unref().
 332  *
 333  * The hexadecimal string returned will be in lower case.
 334  *
 335  * Return value: the HMAC of the binary data as a string in hexadecimal.
 336  *   The returned string should be freed with g_free() when done using it.
 337  *
 338  * Since: 2.30
 339  */
 340 gchar *
 341 g_compute_hmac_for_data (GChecksumType  digest_type,
 342                          const guchar  *key,
 343                          gsize          key_len,
 344                          const guchar  *data,
 345                          gsize          length)
 346 {
 347   GHmac *hmac;
 348   gchar *retval;
 349
 350   g_return_val_if_fail (length == 0 || data != NULL, NULL);
 351
 352   hmac = g_hmac_new (digest_type, key, key_len);
 353   if (!hmac)
 354     return NULL;
 355
 356   g_hmac_update (hmac, data, length);
 357   retval = g_strdup (g_hmac_get_string (hmac));
 358   g_hmac_unref (hmac);
 359
 360   return retval;
 361 }
 362
 363 /**
 364  * g_compute_hmac_for_string:
 365  * @digest_type: a #GChecksumType to use for the HMAC
 366  * @key: (array length=key_len): the key to use in the HMAC
 367  * @key_len: the length of the key
 368  * @str: the string to compute the HMAC for
 369  * @length: the length of the string, or -1 if the string is nul-terminated
 370  *
 371  * Computes the HMAC for a string.
 372  *
 373  * The hexadecimal string returned will be in lower case.
 374  *
 375  * Return value: the HMAC as a hexadecimal string.
 376  *     The returned string should be freed with g_free()
 377  *     when done using it.
 378  *
 379  * Since: 2.30
 380  */
 381 gchar *
 382 g_compute_hmac_for_string (GChecksumType  digest_type,
 383                            const guchar  *key,
 384                            gsize          key_len,
 385                            const gchar   *str,
 386                            gssize         length)
 387 {
 388   g_return_val_if_fail (length == 0 || str != NULL, NULL);
 389
 390   if (length < 0)
 391     length = strlen (str);
 392
 393   return g_compute_hmac_for_data (digest_type, key, key_len,
 394                                   (const guchar *) str, length);
 395 }