Top 
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 () 
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 SHA512 in GLib 2.42. Support for SHA384 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 
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.
Since: 2.30
g_hmac_ref ()
GHmac *
g_hmac_ref (GHmac *hmac
);
Atomically increments the reference count of hmac
by one.
This function is MTsafe and may be called from any thread.
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 MTsafe and may be called from any thread.
Frees the memory allocated for hmac
.
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 nulterminated 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.
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 
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 
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 nulterminated 
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