## Secure HMAC Digests

Secure HMAC Digests — computes the HMAC for data

## Functions

GHmac * | g_hmac_new ()
GHmac * | g_hmac_copy ()
GHmac * | g_hmac_ref ()
void | g_hmac_unref ()
void | g_hmac_update ()
const gchar * | g_hmac_get_string ()
void | g_hmac_get_digest ()
gchar * | g_compute_hmac_for_data ()
gchar * | g_compute_hmac_for_string ()
gchar * | g_compute_hmac_for_bytes ()

## Types and Values

| GHmac

## Includes

    #include <glib.h>
    #include <glib/gi18n.h>

## 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, and support for SHA-512 in GLib 2.42. Support for SHA-384 was added in GLib 2.52.

## Functions

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

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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. | [array length=length]
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.

#### Parameters

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

### g_compute_hmac_for_bytes ()

    gchar *
    g_compute_hmac_for_bytes (GChecksumType digest_type,
                              GBytes *key,
                              GBytes *data);

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.

#### Parameters

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 |

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

## Types and Values

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