17.3 Hashing and MACing Subsystem Architecture

The interface to work with message digests and CRC algorithms is made up of functions from the gcry_md_ name space. The implementation follows the open-use-close paradigm and uses registered algorithm modules for the actual work. Although CRC algorithms are not considered cryptographic hash algorithms, they share enough properties so that it makes sense to handle them in the same way. It is possible to use several algorithms at once with one context and thus compute them all on the same data.

The most important functions are:

gcry_md_open

Create a new message digest instance and optionally enable one algorithm. A flag may be used to turn the message digest algorithm into a HMAC algorithm.

gcry_md_enable

Enable an additional algorithm for the instance.

gcry_md_setkey

Set the key for the MAC.

gcry_md_write

Pass more data for computing the message digest to an instance.

There is no strict alignment requirements for data, but the best performance can be archived if data is aligned to cacheline boundary.

gcry_md_putc

Buffered version of gcry_md_write implemented as a macro.

gcry_md_read

Finalize the computation of the message digest or HMAC and return the result.

gcry_md_close

Release an instance

gcry_md_hash_buffer

Convenience function to directly compute a message digest over a memory buffer without the need to create an instance first.

There are also functions to query properties of algorithms or the instance, like enabled algorithms, digest length, map algorithm names. It is also possible to reset an instance or to copy the current state of an instance at any time. Debug functions to write the hashed data to files are available as well.