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 "gmem.h"
  32 #include "gstrfuncs.h"
  33 #include "gtestutils.h"
  34 #include "gtypes.h"
  35 #include "glibintl.h"
  36
  37
  38 /**
  39  * SECTION:hmac
  40  * @title: Secure HMAC Digests
  41  * @short_description: Computes the HMAC for data
  42  *
  43  * HMACs should be used when producing a cookie or hash based on data
  44  * and a key. Simple mechanisms for using SHA1 and other algorithms to
  45  * digest a key and data together are vulnerable to various security
  46  * issues. <ulink url="http://en.wikipedia.org/wiki/HMAC">HMAC</ulink>
  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->digest_type = hmac->digest_type;
 177   copy->digesti = g_checksum_copy (hmac->digesti);
 178   copy->digesto = g_checksum_copy (hmac->digesto);
 179
 180   return copy;
 181 }
 182
 183 /**
 184  * g_hmac_ref:
 185  * @hmac: a valid #GHmac
 186  *
 187  * Atomically increments the reference count of @hmac by one.
 188  *
 189  * This function is MT-safe and may be called from any thread.
 190  *
 191  * Return value: the passed in #GHmac.
 192  *
 193  * Since: 2.30
 194  **/
 195 GHmac *
 196 g_hmac_ref (GHmac *hmac)
 197 {
 198   g_return_val_if_fail (hmac != NULL, NULL);
 199
 200   g_atomic_int_inc (&hmac->ref_count);
 201
 202   return hmac;
 203 }
 204
 205 /**
 206  * g_hmac_unref:
 207  * @hmac: a #GHmac
 208  *
 209  * Atomically decrements the reference count of @hmac by one.
 210  *
 211  * If the reference count drops to 0, all keys and values will be
 212  * destroyed, and all memory allocated by the hash table is released.
 213  * This function is MT-safe and may be called from any thread.
 214  * Frees the memory allocated for @hmac.
 215  *
 216  * Since: 2.30
 217  */
 218 void
 219 g_hmac_unref (GHmac *hmac)
 220 {
 221   g_return_if_fail (hmac != NULL);
 222
 223   if (g_atomic_int_dec_and_test (&hmac->ref_count))
 224     {
 225       g_checksum_free (hmac->digesti);
 226       g_checksum_free (hmac->digesto);
 227       g_slice_free (GHmac, hmac);
 228     }
 229 }
 230
 231 /**
 232  * g_hmac_update:
 233  * @hmac: a #GHmac
 234  * @data: (array length=length): buffer used to compute the checksum
 235  * @length: size of the buffer, or -1 if it is a nul-terminated string
 236  *
 237  * Feeds @data into an existing #GHmac.
 238  *
 239  * The HMAC must still be open, that is g_hmac_get_string() or
 240  * g_hmac_get_digest() must not have been called on @hmac.
 241  *
 242  * Since: 2.30
 243  */
 244 void
 245 g_hmac_update (GHmac        *hmac,
 246                const guchar *data,
 247                gssize        length)
 248 {
 249   g_return_if_fail (hmac != NULL);
 250   g_return_if_fail (length == 0 || data != NULL);
 251
 252   g_checksum_update (hmac->digesti, data, length);
 253 }
 254
 255 /**
 256  * g_hmac_get_string:
 257  * @hmac: a #GHmac
 258  *
 259  * Gets the HMAC as an hexadecimal string.
 260  *
 261  * Once this function has been called the #GHmac can no longer be
 262  * updated with g_hmac_update().
 263  *
 264  * The hexadecimal characters will be lower case.
 265  *
 266  * Return value: the hexadecimal representation of the HMAC. The
 267  *   returned string is owned by the HMAC and should not be modified
 268  *   or freed.
 269  *
 270  * Since: 2.30
 271  */
 272 const gchar *
 273 g_hmac_get_string (GHmac *hmac)
 274 {
 275   guint8 *buffer;
 276   gsize digest_len;
 277
 278   g_return_val_if_fail (hmac != NULL, NULL);
 279
 280   digest_len = g_checksum_type_get_length (hmac->digest_type);
 281   buffer = g_malloc (digest_len);
 282
 283   g_hmac_get_digest (hmac, buffer, &digest_len);
 284   return g_checksum_get_string (hmac->digesto);
 285 }
 286
 287 /**
 288  * g_checksum_get_digest:
 289  * @hmac: a #GHmac
 290  * @buffer: output buffer
 291  * @digest_len: an inout parameter. The caller initializes it to the
 292  *   size of @buffer. After the call it contains the length of the digest
 293  *
 294  * Gets the digest from @checksum as a raw binary array and places it
 295  * into @buffer. The size of the digest depends on the type of checksum.
 296  *
 297  * Once this function has been called, the #GHmac is closed and can
 298  * no longer be updated with g_checksum_update().
 299  *
 300  * Since: 2.30
 301  */
 302 void
 303 g_hmac_get_digest (GHmac  *hmac,
 304                    guint8 *buffer,
 305                    gsize  *digest_len)
 306 {
 307   gsize len;
 308
 309   g_return_if_fail (hmac != NULL);
 310
 311   len = g_checksum_type_get_length (hmac->digest_type);
 312   g_return_if_fail (*digest_len >= len);
 313
 314   /* Use the same buffer, because we can :) */
 315   g_checksum_get_digest (hmac->digesti, buffer, &len);
 316   g_checksum_update (hmac->digesto, buffer, len);
 317   g_checksum_get_digest (hmac->digesto, buffer, digest_len);
 318 }
 319
 320 /**
 321  * g_compute_hmac_for_data:
 322  * @digest_type: a #GChecksumType to use for the HMAC
 323  * @key: (array length=key_len): the key to use in the HMAC
 324  * @key_len: the length of the key
 325  * @data: binary blob to compute the HMAC of
 326  * @length: length of @data
 327  *
 328  * Computes the HMAC for a binary @data of @length. This is a
 329  * convenience wrapper for g_hmac_new(), g_hmac_get_string()
 330  * and g_hmac_unref().
 331  *
 332  * The hexadecimal string returned will be in lower case.
 333  *
 334  * Return value: the HMAC of the binary data as a string in hexadecimal.
 335  *   The returned string should be freed with g_free() when done using it.
 336  *
 337  * Since: 2.30
 338  */
 339 gchar *
 340 g_compute_hmac_for_data (GChecksumType  digest_type,
 341                          const guchar  *key,
 342                          gsize          key_len,
 343                          const guchar  *data,
 344                          gsize          length)
 345 {
 346   GHmac *hmac;
 347   gchar *retval;
 348
 349   g_return_val_if_fail (length == 0 || data != NULL, NULL);
 350
 351   hmac = g_hmac_new (digest_type, key, key_len);
 352   if (!hmac)
 353     return NULL;
 354
 355   g_hmac_update (hmac, data, length);
 356   retval = g_strdup (g_hmac_get_string (hmac));
 357   g_hmac_unref (hmac);
 358
 359   return retval;
 360 }
 361
 362 /**
 363  * g_compute_hmac_for_string:
 364  * @digest_type: a #GChecksumType to use for the HMAC
 365  * @key: (array length=key_len): the key to use in the HMAC
 366  * @key_len: the length of the key
 367  * @str: the string to compute the HMAC for
 368  * @length: the length of the string, or -1 if the string is nul-terminated
 369  *
 370  * Computes the HMAC for a string.
 371  *
 372  * The hexadecimal string returned will be in lower case.
 373  *
 374  * Return value: the HMAC as a hexadecimal string.
 375  *     The returned string should be freed with g_free()
 376  *     when done using it.
 377  *
 378  * Since: 2.30
 379  */
 380 gchar *
 381 g_compute_hmac_for_string (GChecksumType  digest_type,
 382                            const guchar  *key,
 383                            gsize          key_len,
 384                            const gchar   *str,
 385                            gssize         length)
 386 {
 387   g_return_val_if_fail (length == 0 || str != NULL, NULL);
 388
 389   if (length < 0)
 390     length = strlen (str);
 391
 392   return g_compute_hmac_for_data (digest_type, key, key_len,
 393                                   (const guchar *) str, length);
 394 }