To use most of these function it is necessary to create a context; this is done using:
Create a MAC object for algorithm algo. flags may be given as a
bitwise OR of constants described below. hd is guaranteed to either
receive a valid handle or
NULL. ctx is context object to associate MAC
object with. ctx maybe set to
For a list of supported algorithms, see Available MAC algorithms.
The flags allowed for mode are:
Allocate all buffers and the resulting MAC in "secure memory". Use this if the MAC data is highly confidential.
In order to use a handle for performing MAC algorithm operations, a ‘key’ has to be set first:
Set the MAC key to the value of key of length keylen bytes. With HMAC algorithms, there is no restriction on the length of the key. With CMAC algorithms, the length of the key is restricted to those supported by the underlying block cipher.
GMAC algorithms and Poly1305-with-cipher algorithms need initialization vector to be set, which can be performed with function:
Set the IV to the value of iv of length ivlen bytes.
After you are done with the MAC calculation, you should release the resources by using:
Release all resources of MAC context h. h should not be
used after a call to this function. A
NULL passed as h is
ignored. The function also clears all sensitive information associated
with this handle.
Often you have to do several MAC operations using the same algorithm. To avoid the overhead of creating and releasing context, a reset function is provided:
Reset the current context to its initial state. This is effectively identical to a close followed by an open and setting same key.
Note that gcry_mac_reset is implemented as a macro.
Now that we have prepared everything to calculate MAC, it is time to see how it is actually done.
Pass length bytes of the data in buffer to the MAC object with handle h to update the MAC values. If this function is used after the context has been finalized, it will keep on pushing the data through the algorithm specific transform function and thereby change the context; however the results are not meaningful and this feature is only available to mitigate timing attacks.
The way to read out the calculated MAC is by using the function:
gcry_mac_read returns the MAC after finalizing the calculation.
Function copies the resulting MAC value to buffer of the length
length. If length is larger than length of resulting MAC value,
then length of MAC is returned through length.
To compare existing MAC value with recalculated MAC, one is to use the function:
gcry_mac_verify finalizes MAC calculation and compares result with
length bytes of data in buffer. Error code
is returned if the MAC value in the buffer buffer does not match
the MAC calculated in object h.
In some situations it might be hard to remember the algorithm used for the MAC calculation. The following function might be used to get that information:
Retrieve the algorithm used with the handle h.
MAC algorithms are identified by internal algorithm numbers (see
gcry_mac_open for a list). However, in most applications they are
used by names, so two functions are available to map between string
representations and MAC algorithm identifiers.
Map the MAC algorithm id algo to a string representation of the
algorithm name. For unknown algorithms this function returns the
"?". This function should not be used to test for the
availability of an algorithm.
Map the algorithm with name to a MAC algorithm identifier. Returns 0 if the algorithm name is not known. This function should not be used to test for the availability of an algorithm.
To test whether an algorithm is actually available for use, the following macro should be used:
The macro returns 0 if the MAC algorithm algo is available for use.
If the length of a message digest is not known, it can be retrieved using the following function:
Retrieve the length in bytes of the MAC yielded by algorithm algo.
This is often used prior to
gcry_mac_read to allocate sufficient memory
for the MAC value. On error
0 is returned.
This function returns length of the key for MAC algorithm algo. If
the algorithm supports multiple key lengths, the default supported key
length is returned. On error
0 is returned. The key length is
returned as number of octets.