[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Hashing

Libgcrypt provides an easy and consistent to use interface for hashing. Hashing is buffered and several hash algorithms can be updated at once. It is possible to compute a MAC using the same routines. The programming model follows an open/process/close paradigm and is in that similar to other building blocks provided by Libgcrypt.

For convenience reasons, a few cyclic redundancy check value operations are also supported.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.1 Available hash algorithms

GCRY_MD_NONE

This is not a real algorithm but used by some functions as an error return value. This constant is guaranteed to have the value 0.

GCRY_MD_SHA1

This is the SHA-1 algorithm which yields a message digest of 20 bytes. Note that SHA-1 begins to show some weaknesses and it is suggested to fade out its use if strong cryptographic properties are required.

GCRY_MD_RMD160

This is the 160 bit version of the RIPE message digest (RIPE-MD-160). Like SHA-1 it also yields a digest of 20 bytes. This algorithm share a lot of design properties with SHA-1 and thus it is advisable not to use it for new protocols.

GCRY_MD_MD5

This is the well known MD5 algorithm, which yields a message digest of 16 bytes. Note that the MD5 algorithm has severe weaknesses, for example it is easy to compute two messages yielding the same hash (collision attack). The use of this algorithm is only justified for non-cryptographic application.

GCRY_MD_MD4

This is the MD4 algorithm, which yields a message digest of 16 bytes. This algorithms ha severe weaknesses and should not be used.

GCRY_MD_MD2

This is an reserved identifier for MD-2; there is no implementation yet. This algorithm has severe weaknesses and should not be used.

GCRY_MD_TIGER

This is the TIGER/192 algorithm which yields a message digest of 24 bytes.

GCRY_MD_HAVAL

This is an reserved value for the HAVAL algorithm with 5 passes and 160 bit. It yields a message digest of 20 bytes. Note that there is no implementation yet available.

GCRY_MD_SHA224

This is the SHA-224 algorithm which yields a message digest of 28 bytes. See Change Notice 1 for FIPS 180-2 for the specification.

GCRY_MD_SHA256

This is the SHA-256 algorithm which yields a message digest of 32 bytes. See FIPS 180-2 for the specification.

GCRY_MD_SHA384

This is the SHA-384 algorithm which yields a message digest of 48 bytes. See FIPS 180-2 for the specification.

GCRY_MD_SHA512

This is the SHA-384 algorithm which yields a message digest of 64 bytes. See FIPS 180-2 for the specification.

GCRY_MD_CRC32

This is the ISO 3309 and ITU-T V.42 cyclic redundancy check. It yields an output of 4 bytes. Note that this is not a hash algorithm in the cryptographic sense.

GCRY_MD_CRC32_RFC1510

This is the above cyclic redundancy check function, as modified by RFC 1510. It yields an output of 4 bytes. Note that this is not a hash algorithm in the cryptographic sense.

GCRY_MD_CRC24_RFC2440

This is the OpenPGP cyclic redundancy check function. It yields an output of 3 bytes. Note that this is not a hash algorithm in the cryptographic sense.

GCRY_MD_WHIRLPOOL

This is the Whirlpool algorithm which yields a message digest of 64 bytes.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2 Hash algorithm modules

Libgcrypt makes it possible to load additional `message digest modules'; these digests can be used just like the message digest algorithms that are built into the library directly. For an introduction into extension modules, see See section Modules.

Data type: gcry_md_spec_t

This is the `module specification structure' needed for registering message digest modules, which has to be filled in by the user before it can be used to register a module. It contains the following members:

const char *name

The primary name of this algorithm.

unsigned char *asnoid

Array of bytes that form the ASN OID.

int asnlen

Length of bytes in `asnoid'.

gcry_md_oid_spec_t *oids

A list of OIDs that are to be associated with the algorithm. The list's last element must have it's `oid' member set to NULL. See below for an explanation of this type. See below for an explanation of this type.

int mdlen

Length of the message digest algorithm. See below for an explanation of this type.

gcry_md_init_t init

The function responsible for initializing a handle. See below for an explanation of this type.

gcry_md_write_t write

The function responsible for writing data into a message digest context. See below for an explanation of this type.

gcry_md_final_t final

The function responsible for `finalizing' a message digest context. See below for an explanation of this type.

gcry_md_read_t read

The function responsible for reading out a message digest result. See below for an explanation of this type.

size_t contextsize

The size of the algorithm-specific `context', that should be allocated for each handle.

Data type: gcry_md_oid_spec_t

This type is used for associating a user-provided algorithm implementation with certain OIDs. It contains the following members:

const char *oidstring

Textual representation of the OID.

Data type: gcry_md_init_t

Type for the `init' function, defined as: void (*gcry_md_init_t) (void *c)

Data type: gcry_md_write_t

Type for the `write' function, defined as: void (*gcry_md_write_t) (void *c, unsigned char *buf, size_t nbytes)

Data type: gcry_md_final_t

Type for the `final' function, defined as: void (*gcry_md_final_t) (void *c)

Data type: gcry_md_read_t

Type for the `read' function, defined as: unsigned char *(*gcry_md_read_t) (void *c)

Function: gcry_error_t gcry_md_register (gcry_md_spec_t *digest, unsigned int *algorithm_id, gcry_module_t *module)

Register a new digest module whose specification can be found in digest. On success, a new algorithm ID is stored in algorithm_id and a pointer representing this module is stored in module.

Function: void gcry_md_unregister (gcry_module_t module)

Unregister the digest identified by module, which must have been registered with gcry_md_register.

Function: gcry_error_t gcry_md_list (int *list, int *list_length)

Get a list consisting of the IDs of the loaded message digest modules. If list is zero, write the number of loaded message digest modules to list_length and return. If list is non-zero, the first *list_length algorithm IDs are stored in list, which must be of according size. In case there are less message digests modules than *list_length, *list_length is updated to the correct number.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3 Working with hash algorithms

To use most of these function it is necessary to create a context; this is done using:

Function: gcry_error_t gcry_md_open (gcry_md_hd_t *hd, int algo, unsigned int flags)

Create a message digest object for algorithm algo. flags may be given as an bitwise OR of constants described below. algo may be given as 0 if the algorithms to use are later set using gcry_md_enable. hd is guaranteed to either receive a valid handle or NULL.

For a list of supported algorithms, see See section Available hash algorithms.

The flags allowed for mode are:

GCRY_MD_FLAG_SECURE

Allocate all buffers and the resulting digest in "secure memory". Use this is the hashed data is highly confidential.

GCRY_MD_FLAG_HMAC

Turn the algorithm into a HMAC message authentication algorithm. This only works if just one algorithm is enabled for the handle. Note that the function gcry_md_setkey must be used to set the MAC key. The size of the MAC is equal to the message digest of the underlying hash algorithm. If you want CBC message authentication codes based on a cipher, see See section Working with cipher handles.

You may use the function gcry_md_is_enabled to later check whether an algorithm has been enabled.

If you want to calculate several hash algorithms at the same time, you have to use the following function right after the gcry_md_open:

Function: gcry_error_t gcry_md_enable (gcry_md_hd_t h, int algo)

Add the message digest algorithm algo to the digest object described by handle h. Duplicated enabling of algorithms is detected and ignored.

If the flag GCRY_MD_FLAG_HMAC was used, the key for the MAC must be set using the function:

Function: gcry_error_t gcry_md_setkey (gcry_md_hd_t h, const void *key, size_t keylen)

For use with the HMAC feature, set the MAC key to the value of key of length keylen bytes. There is no restriction on the length of the key.

After you are done with the hash calculation, you should release the resources by using:

Function: void gcry_md_close (gcry_md_hd_t h)

Release all resources of hash context h. h should not be used after a call to this function. A NULL passed as h is ignored. The function also zeroises all sensitive information associated with this handle.

Often you have to do several hash operations using the same algorithm. To avoid the overhead of creating and releasing context, a reset function is provided:

Function: void gcry_md_reset (gcry_md_hd_t h)

Reset the current context to its initial state. This is effectively identical to a close followed by an open and enabling all currently active algorithms.

Often it is necessary to start hashing some data and then continue to hash different data. To avoid hashing the same data several times (which might not even be possible if the data is received from a pipe), a snapshot of the current hash context can be taken and turned into a new context:

Function: gcry_error_t gcry_md_copy (gcry_md_hd_t *handle_dst, gcry_md_hd_t handle_src)

Create a new digest object as an exact copy of the object described by handle handle_src and store it in handle_dst. The context is not reset and you can continue to hash data using this context and independently using the original context.

Now that we have prepared everything to calculate hashes, it is time to see how it is actually done. There are two ways for this, one to update the hash with a block of memory and one macro to update the hash by just one character. Both methods can be used on the same hash context.

Function: void gcry_md_write (gcry_md_hd_t h, const void *buffer, size_t length)

Pass length bytes of the data in buffer to the digest object with handle h to update the digest values. This function should be used for large blocks of data.

Function: void gcry_md_putc (gcry_md_hd_t h, int c)

Pass the byte in c to the digest object with handle h to update the digest value. This is an efficient function, implemented as a macro to buffer the data before an actual update.

The semantics of the hash functions do not provide for reading out intermediate message digests because the calculation must be finalized first. This finalization may for example include the number of bytes hashed in the message digest or some padding.

Function: void gcry_md_final (gcry_md_hd_t h)

Finalize the message digest calculation. This is not really needed because gcry_md_read does this implicitly. After this has been done no further updates (by means of gcry_md_write or gcry_md_putc are allowed. Only the first call to this function has an effect. It is implemented as a macro.

The way to read out the calculated message digest is by using the function:

Function: unsigned char * gcry_md_read (gcry_md_hd_t h, int algo)

gcry_md_read returns the message digest after finalizing the calculation. This function may be used as often as required but it will always return the same value for one handle. The returned message digest is allocated within the message context and therefore valid until the handle is released or reseted (using gcry_md_close or gcry_md_reset. algo may be given as 0 to return the only enabled message digest or it may specify one of the enabled algorithms. The function does return NULL if the requested algorithm has not been enabled.

Because it is often necessary to get the message digest of one block of memory, a fast convenience function is available for this task:

Function: void gcry_md_hash_buffer (int algo, void *digest, const void *buffer, size_t length);

gcry_md_hash_buffer is a shortcut function to calculate a message digest of a buffer. This function does not require a context and immediately returns the message digest of the length bytes at buffer. digest must be allocated by the caller, large enough to hold the message digest yielded by the the specified algorithm algo. This required size may be obtained by using the function gcry_md_get_algo_dlen.

Note that this function will abort the process if an unavailable algorithm is used.

Hash algorithms are identified by internal algorithm numbers (see gcry_md_open for a list). However, in most applications they are used by names, so two functions are available to map between string representations and hash algorithm identifiers.

Function: const char * gcry_md_algo_name (int algo)

Map the digest algorithm id algo to a string representation of the algorithm name. For unknown algorithms this function returns the string "?". This function should not be used to test for the availability of an algorithm.

Function: int gcry_md_map_name (const char *name)

Map the algorithm with name to a digest algorithm identifier. Returns 0 if the algorithm name is not known. Names representing ASN.1 object identifiers are recognized if the IETF dotted format is used and the OID is prefixed with either "oid." or "OID.". For a list of supported OIDs, see the source code at `cipher/md.c'. This function should not be used to test for the availability of an algorithm.

Function: gcry_error_t gcry_md_get_asnoid (int algo, void *buffer, size_t *length)

Return an DER encoded ASN.1 OID for the algorithm algo in the user allocated buffer. length must point to variable with the available size of buffer and receives after return the actual size of the returned OID. The returned error code may be GPG_ERR_TOO_SHORT if the provided buffer is to short to receive the OID; it is possible to call the function with NULL for buffer to have it only return the required size. The function returns 0 on success.

To test whether an algorithm is actually available for use, the following macro should be used:

Function: gcry_error_t gcry_md_test_algo (int algo)

The macro returns 0 if the algorithm algo is available for use.

If the length of a message digest is not known, it can be retrieved using the following function:

Function: unsigned int gcry_md_get_algo_dlen (int algo)

Retrieve the length in bytes of the digest yielded by algorithm algo. This is often used prior to gcry_md_read to allocate sufficient memory for the digest.

In some situations it might be hard to remember the algorithm used for the ongoing hashing. The following function might be used to get that information:

Function: int gcry_md_get_algo (gcry_md_hd_t h)

Retrieve the algorithm used with the handle h. Note that this does not work reliable if more than one algorithm is enabled in h.

The following macro might also be useful:

Function: int gcry_md_is_secure (gcry_md_hd_t h)

This function returns true when the digest object h is allocated in "secure memory"; i.e. h was created with the GCRY_MD_FLAG_SECURE.

Function: int gcry_md_is_enabled (gcry_md_hd_t h, int algo)

This function returns true when the algorithm algo has been enabled for the digest object h.

Tracking bugs related to hashing is often a cumbersome task which requires to add a lot of printf statements into the code. Libgcrypt provides an easy way to avoid this. The actual data hashed can be written to files on request.

Function: void gcry_md_debug (gcry_md_hd_t h, const char *suffix)

Enable debugging for the digest object with handle h. This creates create files named `dbgmd-<n>.<string>' while doing the actual hashing. suffix is the string part in the filename. The number is a counter incremented for each new hashing. The data in the file is the raw data as passed to gcry_md_write or gcry_md_putc. If NULL is used for suffix, the debugging is stopped and the file closed. This is only rarely required because gcry_md_close implicitly stops debugging.

The following two deprecated macros are used for debugging by old code. They shopuld be replaced by gcry_md_debug.

Function: void gcry_md_start_debug (gcry_md_hd_t h, const char *suffix)

Enable debugging for the digest object with handle h. This creates create files named `dbgmd-<n>.<string>' while doing the actual hashing. suffix is the string part in the filename. The number is a counter incremented for each new hashing. The data in the file is the raw data as passed to gcry_md_write or gcry_md_putc.

Function: void gcry_md_stop_debug (gcry_md_hd_t h, int reserved)

Stop debugging on handle h. reserved should be specified as 0. This function is usually not required because gcry_md_close does implicitly stop debugging.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on January, 20 2010 using texi2html 1.76.