/* ghmac.h - data hashing functions

 *

 * Copyright (C) 2011  Collabora Ltd.

 *

 * SPDX-License-Identifier: LGPL-2.1-or-later

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Lesser General Public

 * License as published by the Free Software Foundation; either

 * version 2.1 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public License

 * along with this library; if not, see <http://www.gnu.org/licenses/>.

 *

 * Author: Stef Walter <stefw@collabora.co.uk>

 */

#include "config.h"

#include <string.h>

#include "ghmac.h"

#include "glib/galloca.h"

#include "gatomic.h"

#include "gslice.h"

#include "gmem.h"

#include "gstrfuncs.h"

#include "gtestutils.h"

#include "gtypes.h"

#include "glibintl.h"

/**

 * GHmac:

 *

 * HMACs should be used when producing a cookie or hash based on data

 * and a key. Simple mechanisms for using SHA1 and other algorithms to

 * digest a key and data together are vulnerable to various security

 * issues.

 * [HMAC](http://en.wikipedia.org/wiki/HMAC)

 * uses algorithms like SHA1 in a secure way to produce a digest of a

 * key and data.

 *

 * Both the key and data are arbitrary byte arrays of bytes or characters.

 *

 * Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512

 * in GLib 2.42. Support for SHA-384 was added in GLib 2.52.

 *

 * To create a new `GHmac`, use [ctor@GLib.Hmac.new]. To free a `GHmac`, use

 * [method@GLib.Hmac.unref].

 *

 * Since: 2.30

 */

struct _GHmac

{

  int ref_count;

  GChecksumType digest_type;

  GChecksum *digesti;

  GChecksum *digesto;

};

/**

 * g_hmac_new: (constructor)

 * @digest_type: the desired type of digest

 * @key: (array length=key_len): the key for the HMAC

 * @key_len: the length of the keys

 *

 * Creates a new #GHmac, using the digest algorithm @digest_type.

 * If the @digest_type is not known, %NULL is returned.

 * A #GHmac can be used to compute the HMAC of a key and an

 * arbitrary binary blob, using different hashing algorithms.

 *

 * A #GHmac works by feeding a binary blob through g_hmac_update()

 * until the data is complete; the digest can then be extracted

 * using g_hmac_get_string(), which will return the checksum as a

 * hexadecimal string; or g_hmac_get_digest(), which will return a

 * array of raw bytes. Once either g_hmac_get_string() or

 * g_hmac_get_digest() have been called on a #GHmac, the HMAC

 * will be closed and it won't be possible to call g_hmac_update()

 * on it anymore.

 *

 * Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42.

 * Support for %G_CHECKSUM_SHA384 was added in GLib 2.52.

 *

 * Returns: (nullable) (transfer full): the newly created #GHmac, or %NULL.

 *   Use g_hmac_unref() to free the memory allocated by it.

 *

 * Since: 2.30

 */

GHmac *

g_hmac_new (GChecksumType  digest_type,

            const guchar  *key,

            gsize          key_len)

{

  GChecksum *checksum;

  GHmac *hmac;

  guchar *buffer;

  guchar *pad;

  gsize i, len;

  gsize block_size;

  gssize block_size_signed, key_len_signed;

  g_return_val_if_fail (key_len <= G_MAXSSIZE, NULL);

  checksum = g_checksum_new (digest_type);

  g_return_val_if_fail (checksum != NULL, NULL);

  switch (digest_type)

    {

    case G_CHECKSUM_MD5:

    case G_CHECKSUM_SHA1:

      block_size = 64; /* RFC 2104 */

      break;

    case G_CHECKSUM_SHA256:

      block_size = 64; /* RFC 4868 */

      break;

    case G_CHECKSUM_SHA384:

    case G_CHECKSUM_SHA512:

      block_size = 128; /* RFC 4868 */

      break;

    default:

      g_return_val_if_reached (NULL);

    }

  hmac = g_slice_new0 (GHmac);

  hmac->ref_count = 1;

  hmac->digest_type = digest_type;

  hmac->digesti = checksum;

  hmac->digesto = g_checksum_new (digest_type);

  buffer = g_alloca0 (block_size);

  pad = g_alloca (block_size);

  /* If the key is too long, hash it */

  if (key_len > block_size)

    {

      len = block_size;

      g_assert (key_len <= G_MAXSSIZE);

      key_len_signed = key_len;

      g_checksum_update (hmac->digesti, key, key_len_signed);

      g_checksum_get_digest (hmac->digesti, buffer, &len);

      g_checksum_reset (hmac->digesti);

    }

  /* Otherwise pad it with zeros */

  else

    {

      memcpy (buffer, key, key_len);

    }

  /* g_checksum_update() accepts a signed length, so build and check that. */

  g_assert (block_size <= G_MAXSSIZE);

  block_size_signed = block_size;

  /* First pad */

  for (i = 0; i < block_size; i++)

    pad[i] = 0x36 ^ buffer[i]; /* ipad value */

  g_checksum_update (hmac->digesti, pad, block_size_signed);

  /* Second pad */

  for (i = 0; i < block_size; i++)

    pad[i] = 0x5c ^ buffer[i]; /* opad value */

  g_checksum_update (hmac->digesto, pad, block_size_signed);

  return hmac;

}

/**

 * g_hmac_copy:

 * @hmac: the #GHmac to copy

 *

 * Copies a #GHmac. If @hmac has been closed, by calling

 * g_hmac_get_string() or g_hmac_get_digest(), the copied

 * HMAC will be closed as well.

 *

 * Returns: (transfer full): the copy of the passed #GHmac. Use g_hmac_unref()

 *   when finished using it.

 *

 * Since: 2.30

 */

GHmac *

g_hmac_copy (const GHmac *hmac)

{

  GHmac *copy;

  g_return_val_if_fail (hmac != NULL, NULL);

  copy = g_slice_new (GHmac);

  copy->ref_count = 1;

  copy->digest_type = hmac->digest_type;

  copy->digesti = g_checksum_copy (hmac->digesti);

  copy->digesto = g_checksum_copy (hmac->digesto);

  return copy;

}

/**

 * g_hmac_ref:

 * @hmac: a valid #GHmac

 *

 * Atomically increments the reference count of @hmac by one.

 *

 * This function is MT-safe and may be called from any thread.

 *

 * Returns: (transfer full): the passed in #GHmac.

 *

 * Since: 2.30

 **/

GHmac *

g_hmac_ref (GHmac *hmac)

{

  g_return_val_if_fail (hmac != NULL, NULL);

  g_atomic_int_inc (&hmac->ref_count);

  return hmac;

}

/**

 * g_hmac_unref:

 * @hmac: (transfer full): a #GHmac

 *

 * Atomically decrements the reference count of @hmac by one.

 *

 * If the reference count drops to 0, all keys and values will be

 * destroyed, and all memory allocated by the hash table is released.

 * This function is MT-safe and may be called from any thread.

 * Frees the memory allocated for @hmac.

 *

 * Since: 2.30

 */

void

g_hmac_unref (GHmac *hmac)

{

  g_return_if_fail (hmac != NULL);

  if (g_atomic_int_dec_and_test (&hmac->ref_count))

    {

      g_checksum_free (hmac->digesti);

      g_checksum_free (hmac->digesto);

      g_slice_free (GHmac, hmac);

    }

}

/**

 * g_hmac_update:

 * @hmac: a #GHmac

 * @data: (array length=length): buffer used to compute the checksum

 * @length: size of the buffer, or -1 if it is a nul-terminated string

 *

 * Feeds @data into an existing #GHmac.

 *

 * The HMAC must still be open, that is g_hmac_get_string() or

 * g_hmac_get_digest() must not have been called on @hmac.

 *

 * Since: 2.30

 */

void

g_hmac_update (GHmac        *hmac,

               const guchar *data,

               gssize        length)

{

  g_return_if_fail (hmac != NULL);

  g_return_if_fail (length == 0 || data != NULL);

  g_checksum_update (hmac->digesti, data, length);

}

/**

 * g_hmac_get_string:

 * @hmac: a #GHmac

 *

 * Gets the HMAC as a hexadecimal string.

 *

 * Once this function has been called the #GHmac can no longer be

 * updated with g_hmac_update().

 *

 * The hexadecimal characters will be lower case.

 *

 * Returns: the hexadecimal representation of the HMAC. The

 *   returned string is owned by the HMAC and should not be modified

 *   or freed.

 *

 * Since: 2.30

 */

const gchar *

g_hmac_get_string (GHmac *hmac)

{

  guint8 *buffer;

  gssize digest_len_signed;

  gsize digest_len;

  g_return_val_if_fail (hmac != NULL, NULL);

  /* It shouldn’t be possible for @digest_len_signed to be negative, as

   * `hmac->digest_type` has already been validated as being supported. */

  digest_len_signed = g_checksum_type_get_length (hmac->digest_type);

  g_assert (digest_len_signed >= 0);

  digest_len = digest_len_signed;

  buffer = g_alloca (digest_len);

  /* This is only called for its side-effect of updating hmac->digesto... */

  g_hmac_get_digest (hmac, buffer, &digest_len);

  /* ... because we get the string from the checksum rather than

   * stringifying buffer ourselves

   */

  return g_checksum_get_string (hmac->digesto);

}

/**

 * g_hmac_get_digest:

 * @hmac: a #GHmac

 * @buffer: (array length=digest_len): output buffer

 * @digest_len: (inout): an inout parameter. The caller initializes it to the

 *   size of @buffer. After the call it contains the length of the digest

 *

 * Gets the digest from @checksum as a raw binary array and places it

 * into @buffer. The size of the digest depends on the type of checksum.

 *

 * Once this function has been called, the #GHmac is closed and can

 * no longer be updated with g_checksum_update().

 *

 * Since: 2.30

 */

void

g_hmac_get_digest (GHmac  *hmac,

                   guint8 *buffer,

                   gsize  *digest_len)

{

  gsize len;

  gssize len_signed;

  g_return_if_fail (hmac != NULL);

  /* It shouldn’t be possible for @len_signed to be negative, as

   * `hmac->digest_type` has already been validated as being supported. */

  len_signed = g_checksum_type_get_length (hmac->digest_type);

  g_assert (len_signed >= 0);

  len = len_signed;

  /* @buffer must be long enough for the digest */

  g_return_if_fail (*digest_len >= len);

  /* Use the same buffer, because we can :) */

  g_checksum_get_digest (hmac->digesti, buffer, &len);

  g_assert (len <= G_MAXSSIZE);

  len_signed = len;

  g_checksum_update (hmac->digesto, buffer, len_signed);

  g_checksum_get_digest (hmac->digesto, buffer, digest_len);

}

/**

 * g_compute_hmac_for_data:

 * @digest_type: a #GChecksumType to use for the HMAC

 * @key: (array length=key_len): the key to use in the HMAC

 * @key_len: the length of the key

 * @data: (array length=length): binary blob to compute the HMAC of

 * @length: length of @data

 *

 * Computes the HMAC for a binary @data of @length. This is a

 * convenience wrapper for g_hmac_new(), g_hmac_get_string()

 * and g_hmac_unref().

 *

 * The hexadecimal string returned will be in lower case.

 *

 * Returns: the HMAC of the binary data as a string in hexadecimal.

 *   The returned string should be freed with g_free() when done using it.

 *

 * Since: 2.30

 */

gchar *

g_compute_hmac_for_data (GChecksumType  digest_type,

                         const guchar  *key,

                         gsize          key_len,

                         const guchar  *data,

                         gsize          length)

{

  GHmac *hmac;

  gchar *retval;

  g_return_val_if_fail (length == 0 || data != NULL, NULL);

  hmac = g_hmac_new (digest_type, key, key_len);

  if (!hmac)

    return NULL;

  g_hmac_update (hmac, data, length);

  retval = g_strdup (g_hmac_get_string (hmac));

  g_hmac_unref (hmac);

  return retval;

}

/**

 * g_compute_hmac_for_bytes:

 * @digest_type: a #GChecksumType to use for the HMAC

 * @key: the key to use in the HMAC

 * @data: binary blob to compute the HMAC of

 *

 * Computes the HMAC for a binary @data. This is a

 * convenience wrapper for g_hmac_new(), g_hmac_get_string()

 * and g_hmac_unref().

 *

 * The hexadecimal string returned will be in lower case.

 *

 * Returns: the HMAC of the binary data as a string in hexadecimal.

 *   The returned string should be freed with g_free() when done using it.

 *

 * Since: 2.50

 */

gchar *

g_compute_hmac_for_bytes (GChecksumType  digest_type,

                          GBytes        *key,

                          GBytes        *data)

{

  gconstpointer byte_data;

  gsize length;

  gconstpointer key_data;

  gsize key_len;

  g_return_val_if_fail (data != NULL, NULL);

  g_return_val_if_fail (key != NULL, NULL);

  byte_data = g_bytes_get_data (data, &length);

  key_data = g_bytes_get_data (key, &key_len);

  return g_compute_hmac_for_data (digest_type, key_data, key_len, byte_data, length);

}

/**

 * g_compute_hmac_for_string:

 * @digest_type: a #GChecksumType to use for the HMAC

 * @key: (array length=key_len): the key to use in the HMAC

 * @key_len: the length of the key

 * @str: the string to compute the HMAC for

 * @length: the length of the string, or -1 if the string is nul-terminated

 *

 * Computes the HMAC for a string.

 *

 * The hexadecimal string returned will be in lower case.

 *

 * Returns: the HMAC as a hexadecimal string.

 *     The returned string should be freed with g_free()

 *     when done using it.

 *

 * Since: 2.30

 */

gchar *

g_compute_hmac_for_string (GChecksumType  digest_type,

                           const guchar  *key,

                           gsize          key_len,

                           const gchar   *str,

                           gssize         length)

{

  g_return_val_if_fail (length == 0 || str != NULL, NULL);

  if (length < 0)

    length = strlen (str);

  return g_compute_hmac_for_data (digest_type, key, key_len,

                                  (const guchar *) str, length);

}