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. <ulink url="http://en.wikipedia.org/wiki/HMAC">HMAC</ulink>
  46  * uses algorithms like SHA1 in a secure way to produce a digest of a
  47  * key and data.
  48  *
  49  * Both the key and data are arbitrary byte arrays of bytes or characters.
  50  *
  51  * Support for HMAC Digests has been added in GLib 2.30.
  52  */
  53
  54 struct _GHmac
  55 {
  56   int ref_count;
  57   GChecksumType digest_type;
  58   GChecksum *digesti;
  59   GChecksum *digesto;
  60 };
  61
  62 /**
  63  * g_hmac_new:
  64  * @digest_type: the desired type of digest
  65  * @key: (array length=key_len): the key for the HMAC
  66  * @key_len: the length of the keys
  67  *
  68  * Creates a new #GHmac, using the digest algorithm @digest_type.
  69  * If the @digest_type is not known, %NULL is returned.
  70  * A #GHmac can be used to compute the HMAC of a key and an
  71  * arbitrary binary blob, using different hashing algorithms.
  72  *
  73  * A #GHmac works by feeding a binary blob through g_hmac_update()
  74  * until the data is complete; the digest can then be extracted
  75  * using g_hmac_get_string(), which will return the checksum as a
  76  * hexadecimal string; or g_hmac_get_digest(), which will return a
  77  * array of raw bytes. Once either g_hmac_get_string() or
  78  * g_hmac_get_digest() have been called on a #GHmac, the HMAC
  79  * will be closed and it won't be possible to call g_hmac_update()
  80  * on it anymore.
  81  *
  82  * Return value: the newly created #GHmac, or %NULL.
  83  *   Use g_hmac_unref() to free the memory allocated by it.
  84  *
  85  * Since: 2.30
  86  */
  87 GHmac *
  88 g_hmac_new (GChecksumType  digest_type,
  89             const guchar  *key,
  90             gsize          key_len)
  91 {
  92   GChecksum *checksum;
  93   GHmac *hmac;
  94   guchar *buffer;
  95   guchar *pad;
  96   gsize i, len;
  97   gsize block_size;
  98
  99   checksum = g_checksum_new (digest_type);
 100   g_return_val_if_fail (checksum != NULL, NULL);
 101
 102   switch (digest_type)
 103     {
 104     case G_CHECKSUM_MD5:
 105     case G_CHECKSUM_SHA1:
 106       block_size = 64; /* RFC 2104 */
 107       break;
 108     case G_CHECKSUM_SHA256:
 109       block_size = 64; /* RFC draft-kelly-ipsec-ciph-sha2-01 */
 110       break;
 111     default:
 112       g_return_val_if_reached (NULL);
 113     }
 114
 115   hmac = g_slice_new0 (GHmac);
 116   hmac->ref_count = 1;
 117   hmac->digest_type = digest_type;
 118   hmac->digesti = checksum;
 119   hmac->digesto = g_checksum_new (digest_type);
 120
 121   buffer = g_alloca (block_size);
 122   pad = g_alloca (block_size);
 123
 124   memset (buffer, 0, block_size);
 125
 126   /* If the key is too long, hash it */
 127   if (key_len > block_size)
 128     {
 129       len = block_size;
 130       g_checksum_update (hmac->digesti, key, key_len);
 131       g_checksum_get_digest (hmac->digesti, buffer, &len);
 132       g_checksum_reset (hmac->digesti);
 133     }
 134
 135   /* Otherwise pad it with zeros */
 136   else
 137     {
 138       memcpy (buffer, key, key_len);
 139     }
 140
 141   /* First pad */
 142   for (i = 0; i < block_size; i++)
 143     pad[i] = 0x36 ^ buffer[i]; /* ipad value */
 144   g_checksum_update (hmac->digesti, pad, block_size);
 145
 146   /* Second pad */
 147   for (i = 0; i < block_size; i++)
 148     pad[i] = 0x5c ^ buffer[i]; /* opad value */
 149   g_checksum_update (hmac->digesto, pad, block_size);
 150
 151   return hmac;
 152 }
 153
 154 /**
 155  * g_hmac_copy:
 156  * @hmac: the #GHmac to copy
 157  *
 158  * Copies a #GHmac. If @hmac has been closed, by calling
 159  * g_hmac_get_string() or g_hmac_get_digest(), the copied
 160  * HMAC will be closed as well.
 161  *
 162  * Return value: the copy of the passed #GHmac. Use g_hmac_unref()
 163  *   when finished using it.
 164  *
 165  * Since: 2.30
 166  */
 167 GHmac *
 168 g_hmac_copy (const GHmac *hmac)
 169 {
 170   GHmac *copy;
 171
 172   g_return_val_if_fail (hmac != NULL, NULL);
 173
 174   copy = g_slice_new (GHmac);
 175   copy->ref_count = 1;
 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_alloca (digest_len);
 282
 283   /* This is only called for its side-effect of updating hmac->digesto... */
 284   g_hmac_get_digest (hmac, buffer, &digest_len);
 285   /* ... because we get the string from the checksum rather than
 286    * stringifying buffer ourselves
 287    */
 288   return g_checksum_get_string (hmac->digesto);
 289 }
 290
 291 /**
 292  * g_hmac_get_digest:
 293  * @hmac: a #GHmac
 294  * @buffer: output buffer
 295  * @digest_len: an inout parameter. The caller initializes it to the
 296  *   size of @buffer. After the call it contains the length of the digest
 297  *
 298  * Gets the digest from @checksum as a raw binary array and places it
 299  * into @buffer. The size of the digest depends on the type of checksum.
 300  *
 301  * Once this function has been called, the #GHmac is closed and can
 302  * no longer be updated with g_checksum_update().
 303  *
 304  * Since: 2.30
 305  */
 306 void
 307 g_hmac_get_digest (GHmac  *hmac,
 308                    guint8 *buffer,
 309                    gsize  *digest_len)
 310 {
 311   gsize len;
 312
 313   g_return_if_fail (hmac != NULL);
 314
 315   len = g_checksum_type_get_length (hmac->digest_type);
 316   g_return_if_fail (*digest_len >= len);
 317
 318   /* Use the same buffer, because we can :) */
 319   g_checksum_get_digest (hmac->digesti, buffer, &len);
 320   g_checksum_update (hmac->digesto, buffer, len);
 321   g_checksum_get_digest (hmac->digesto, buffer, digest_len);
 322 }
 323
 324 /**
 325  * g_compute_hmac_for_data:
 326  * @digest_type: a #GChecksumType to use for the HMAC
 327  * @key: (array length=key_len): the key to use in the HMAC
 328  * @key_len: the length of the key
 329  * @data: binary blob to compute the HMAC of
 330  * @length: length of @data
 331  *
 332  * Computes the HMAC for a binary @data of @length. This is a
 333  * convenience wrapper for g_hmac_new(), g_hmac_get_string()
 334  * and g_hmac_unref().
 335  *
 336  * The hexadecimal string returned will be in lower case.
 337  *
 338  * Return value: the HMAC of the binary data as a string in hexadecimal.
 339  *   The returned string should be freed with g_free() when done using it.
 340  *
 341  * Since: 2.30
 342  */
 343 gchar *
 344 g_compute_hmac_for_data (GChecksumType  digest_type,
 345                          const guchar  *key,
 346                          gsize          key_len,
 347                          const guchar  *data,
 348                          gsize          length)
 349 {
 350   GHmac *hmac;
 351   gchar *retval;
 352
 353   g_return_val_if_fail (length == 0 || data != NULL, NULL);
 354
 355   hmac = g_hmac_new (digest_type, key, key_len);
 356   if (!hmac)
 357     return NULL;
 358
 359   g_hmac_update (hmac, data, length);
 360   retval = g_strdup (g_hmac_get_string (hmac));
 361   g_hmac_unref (hmac);
 362
 363   return retval;
 364 }
 365
 366 /**
 367  * g_compute_hmac_for_string:
 368  * @digest_type: a #GChecksumType to use for the HMAC
 369  * @key: (array length=key_len): the key to use in the HMAC
 370  * @key_len: the length of the key
 371  * @str: the string to compute the HMAC for
 372  * @length: the length of the string, or -1 if the string is nul-terminated
 373  *
 374  * Computes the HMAC for a string.
 375  *
 376  * The hexadecimal string returned will be in lower case.
 377  *
 378  * Return value: the HMAC as a hexadecimal string.
 379  *     The returned string should be freed with g_free()
 380  *     when done using it.
 381  *
 382  * Since: 2.30
 383  */
 384 gchar *
 385 g_compute_hmac_for_string (GChecksumType  digest_type,
 386                            const guchar  *key,
 387                            gsize          key_len,
 388                            const gchar   *str,
 389                            gssize         length)
 390 {
 391   g_return_val_if_fail (length == 0 || str != NULL, NULL);
 392
 393   if (length < 0)
 394     length = strlen (str);
 395
 396   return g_compute_hmac_for_data (digest_type, key, key_len,
 397                                   (const guchar *) str, length);
 398 }