DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(gcrypt.info.gz) Working with hash algorithms

Info Catalog (gcrypt.info.gz) Hash algorithm modules (gcrypt.info.gz) Hashing
 
 6.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  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 does only work if just one algorithm is
           enabled for the handle and SHA-384 and SHA512 is not used.
           Note that the function `gcry_md_setkey' must be used set the
           MAC key.  If you want CBC message authentication codes based
           on a cipher, see  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.
 
    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.
 
 
    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 than 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, its time to
 see how it is actually done.  There are 2  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 may be used intermixed.
 
  -- 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 don't allow to read out
 intermediate message digests because the calculation must be finalized
 fist.  This finalization may for example include the number of bytes
 hashed in the message digest.
 
  -- 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
           cvoid *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 2 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 functions returns an
      empty 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.  The following 2 macros should be used to
 implement such a debugging facility:
 
  -- 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.
 
Info Catalog (gcrypt.info.gz) Hash algorithm modules (gcrypt.info.gz) Hashing
automatically generated byinfo2html