GLib Reference Manual: Secure HMAC Digests

## Secure HMAC Digests Secure HMAC Digests — computes the HMAC for data |

## Synopsis

    #include <glib.h>

                        GHmac;
    GHmac *             g_hmac_new                          (GChecksumType digest_type,
                                                             const guchar *key,
                                                             gsize key_len);
    GHmac *             g_hmac_copy                         (const GHmac *hmac);
    GHmac *             g_hmac_ref                          (GHmac *hmac);
    void                g_hmac_unref                        (GHmac *hmac);
    void                g_hmac_update                       (GHmac *hmac,
                                                             const guchar *data,
                                                             gssize length);
    const gchar *       g_hmac_get_string                   (GHmac *hmac);
    void                g_hmac_get_digest                   (GHmac *hmac,
                                                             guint8 *buffer,
                                                             gsize *digest_len);

    gchar *             g_compute_hmac_for_data             (GChecksumType digest_type,
                                                             const guchar *key,
                                                             gsize key_len,
                                                             const guchar *data,
                                                             gsize length);
    gchar *             g_compute_hmac_for_string           (GChecksumType digest_type,
                                                             const guchar *key,
                                                             gsize key_len,
                                                             const gchar *str,
                                                             gssize length);

## Description

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 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.

## Details

### GHmac

    typedef struct _GHmac GHmac;

An opaque structure representing a HMAC operation. To create a new GHmac, use `g_hmac_new()`. To free a GHmac, use `g_hmac_unref()`.

Since 2.30

### g_hmac_new ()

    GHmac *             g_hmac_new                          (GChecksumType digest_type,
                                                             const guchar *key,
                                                             gsize key_len);

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.

`digest_type` : | the desired type of digest
`key` : | the key for the HMAC. [array length=key_len]
`key_len` : | the length of the keys
Returns : | the newly created GHmac, or `NULL`. Use `g_hmac_unref()` to free the memory allocated by it.

Since 2.30

### g_hmac_copy ()

    GHmac *             g_hmac_copy                         (const GHmac *hmac);

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.

`hmac` : | the GHmac to copy
Returns : | the copy of the passed GHmac. Use `g_hmac_unref()` when finished using it.

Since 2.30

### g_hmac_ref ()

    GHmac *             g_hmac_ref                          (GHmac *hmac);

Atomically increments the reference count of `hmac` by one.

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

`hmac` : | a valid GHmac
Returns : | the passed in GHmac.

Since 2.30

### g_hmac_unref ()

    void                g_hmac_unref                        (GHmac *hmac);

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`.

`hmac` : | a GHmac

Since 2.30

### g_hmac_update ()

    void                g_hmac_update                       (GHmac *hmac,
                                                             const guchar *data,
                                                             gssize length);

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`.

`hmac` : | a GHmac
`data` : | buffer used to compute the checksum. [array length=length]
`length` : | size of the buffer, or -1 if it is a nul-terminated string

Since 2.30

### g_hmac_get_string ()

    const gchar *       g_hmac_get_string                   (GHmac *hmac);

Gets the HMAC as an 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.

`hmac` : | a GHmac
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

### g_hmac_get_digest ()

    void                g_hmac_get_digest                   (GHmac *hmac,
                                                             guint8 *buffer,
                                                             gsize *digest_len);

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()`.

`hmac` : | a GHmac
`buffer` : | output buffer
`digest_len` : | an inout parameter. The caller initializes it to the size of `buffer`. After the call it contains the length of the digest

Since 2.30

### g_compute_hmac_for_data ()

    gchar *             g_compute_hmac_for_data             (GChecksumType digest_type,
                                                             const guchar *key,
                                                             gsize key_len,
                                                             const guchar *data,
                                                             gsize length);

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.

`digest_type` : | a GChecksumType to use for the HMAC
`key` : | the key to use in the HMAC. [array length=key_len]
`key_len` : | the length of the key
`data` : | binary blob to compute the HMAC of
`length` : | length of `data`
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

### g_compute_hmac_for_string ()

    gchar *             g_compute_hmac_for_string           (GChecksumType digest_type,
                                                             const guchar *key,
                                                             gsize key_len,
                                                             const gchar *str,
                                                             gssize length);

Computes the HMAC for a string.

The hexadecimal string returned will be in lower case.

`digest_type` : | a GChecksumType to use for the HMAC
`key` : | the key to use in the HMAC. [array length=key_len]
`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
Returns : | the HMAC as a hexadecimal string. The returned string should be freed with `g_free()` when done using it.

Since 2.30