gnupg/doc/gcryptref-digest.sgml

<!-- gcryptref-digest.sgml - libgcrypt reference (digests)
    Copyright (C) 2000 Free Software Foundation, Inc.

    This file is part of GnuPG.

    GnuPG is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    GnuPG is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-->

<!--**********************************************
***********  md_open, close, enable  ************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_open</refname>
    <refname>gcry_md_enable</refname>
    <refname>gcry_md_close</refname>
    <refpurpose>create and destroy a message digest context</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>GCRY_MD_HD <function>gcry_md_open</function></funcdef>
	<paramdef>int <parameter>algo</parameter></paramdef>
	<paramdef>unsigned int <parameter>flags</parameter></paramdef>
      </funcprototype>
      <funcprototype>
	<funcdef>void <function>gcry_md_enable</function></funcdef>
	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
	<paramdef>int <parameter>algo</parameter></paramdef>
      </funcprototype>
      <funcprototype>
	<funcdef>void <function>gcry_md_close</function></funcdef>
	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_open</secondary>
	     </indexterm>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_enable</secondary>
	     </indexterm>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_close</secondary>
	     </indexterm>
  <function>gcry_md_open</function> creates the context required for
  the message digest functions.  The hash algorithm may optionally be
  specified.
  <function>gcry_md_close</function> releases all resources associated
  with the context.
  <function>gcry_md_enable</function> may be used to enable hash
  algorithms.  This function may be used multiple times to create
  a hash context for multiple algorithms.  Adding an already enabled algorithm
  has no effect.  A algorithm must be enabled prios to calculate hash
  algorithms.
  </para>
</refentry>

<!--**********************************************
***********  md_copy *****************************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_copy</refname>
    <refpurpose>create and copy of a message digest context</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>GCRY_MD_HD <function>gcry_md_copy</function></funcdef>
	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_copy</secondary>
	     </indexterm>
  <function>gcry_md_copy</function> creates an excat copy of the given context.
  This is useful to calculate hashes with a common initial part of the
  plaintext.
  </para>
</refentry>

<!--**********************************************
***********  md_reset  ***************************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_reset</refname>
    <refpurpose>reset a message digest context</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>void <function>gcry_md_reset</function></funcdef>
	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_reset</secondary>
	     </indexterm>
  <function>gcry_md_reset</function> is used to reuse a message context
  without the overhead of an open and close operation.
  </para>
</refentry>


<!--**********************************************
***********  md_ctl  *****************************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_ctl</refname>
    <refname>gcry_md_final</refname>
    <refpurpose>perform special operations on a digest context</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>int <function>gcry_md_ctl</function></funcdef>
	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
	<paramdef>int <parameter>cmd</parameter></paramdef>
	<paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
	<paramdef>size_t <parameter>buflen</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_ctl</secondary>
	     </indexterm>
  <function>gcry_md_ctl</function> is a multi-purpose function
  to control the behaviour of all gcry_md functions or one instance
  of it.
  </para>
  <para>
  Currently defined values for <parameter>cmd</> are:
    <literal>GCRYCTL_FINALIZE</> and the conevnience macro
    <function>gcry_md_final(a)</>
  </para>
</refentry>

<!--**********************************************
***********  md_write, putc  *********************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_write</refname>
    <refname>gcry_md_putc</refname>
    <refpurpose>calculate the message digest of a buffer</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>int <function>gcry_md_write</function></funcdef>
	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
	<paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
	<paramdef>size_t <parameter>buflen</parameter></paramdef>
      </funcprototype>
      <funcprototype>
	<funcdef>int <function>gcry_md_putc</function></funcdef>
	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
	<paramdef>int <parameter>c</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_write</secondary></indexterm>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_putc</secondary></indexterm>
  <function>gcry_md_write</function> is used to actually calulate the message
  digest of a buffer.  This function updates the internal state of the message
  digest.
  </para>
  <para>
  <function>gcry_md_putc</function> is a macro which is used to update
  the message digest by one byte.  this is the preferred way to calculate
  a digest if only a few bytes at a time are available.
  </para>
</refentry>

<!--**********************************************
***********  md_read *****************************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_read</refname>
    <refpurpose>read out the message digest</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>unsigned char * <function>gcry_md_read</function></funcdef>
	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
	<paramdef>int <parameter>algo</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_read</secondary>
	     </indexterm>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_putc</secondary>
	     </indexterm>
  <function>gcry_md_read</function> returns the message digest after finalizing
  the calculation.  This function may be used as often as required but it
  will alwas return the same value for one handle.  The returned message
  digest is allocated within the message context and therefore valid until
  the conext is released.  <parameter>algo</> may be given as 0 to return the
  only enbaled message digest or it may specify one of the enabled algorithms.
  The function will return NULL if the algorithm has not been enabled.
  </para>
</refentry>


<!--**********************************************
***********  md_info  ****************************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_info</refname>
    <refpurpose>get information about a handle</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>int <function>gcry_md_info</function></funcdef>
	<paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
	<paramdef>int	     <parameter>what</parameter></paramdef>
	<paramdef>void * <parameter>buffer</parameter></paramdef>
	<paramdef>size_t <parameter>buflen</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_info</secondary>
	     </indexterm>
  <function>gcry_md_info</function> returns some information about the
  handle or an global parameter.
  </para>
  <para>
  The only defined value for <parameter>what</> is
  <literal>GCRYCTL_IS_SECURE</literal> to return whether the handle
  has been allocated in secure memory.	Buffer and buflen are not needed
  in this cases.  The convenience macro <function>gcry_md_is_secure(a)</>
  may be also used for this purpose.
  </para>
</refentry>


<!--**********************************************
***********  md_algo_info  ***********************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_algo_info</refname>
    <refname>gcry_md_test_algo</refname>
    <refname>gcry_md_get_algo_dlen</refname>
    <refpurpose>get information about an algorithm</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>int <function>gcry_md_algo_info</function></funcdef>
	<paramdef>int	     <parameter>algo</parameter></paramdef>
	<paramdef>int	     <parameter>what</parameter></paramdef>
	<paramdef>void * <parameter>buffer</parameter></paramdef>
	<paramdef>size_t <parameter>buflen</parameter></paramdef>
      </funcprototype>
      <funcprototype>
	<funcdef>unsigned int <function>gcry_md_get_algo_dlen</function></funcdef>
	<paramdef>int <parameter>algo</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_algo_info</secondary>
	     </indexterm>
  <function>gcry_md_algo_info</function> returns some information about an
  algorithm.  On error the value -1 is return and a more detailed error
  description is available with <function>gcry_errno</>.
  </para>
  <para>
  The defined values for <parameter>what</> are
  <literal>GCRYCTL_TEST_ALGO</literal> to return whether the algorithm
  is supported. Buffer and buflen are not needed
  in this cases.  The convenience macro <function>gcry_md_test_algo(a)</>
  may be used for this purpose.
  </para>
  <para>
  <literal>GCRYCTL_GET_ASNOID</literal> to return whether the ASN.1
  object identifier.  IF buffer is specified as NULL, only the required
  length for the buffer is returned.
  </para>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_get_algo_dlen</secondary>
	     </indexterm>
  <function>gcry_md_get_algo_dlen</function> returns the length of the
  digest for a given algorithm in bytes.
  </para>
</refentry>


<!--**********************************************
***********  md_algo_name, map_name  *************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_algo_name</refname>
    <refname>gcry_md_map_name</refname>
    <refpurpose>map algorithm to string</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>const char * <function>gcry_md_algo_name</function></funcdef>
	<paramdef>int	     <parameter>algo</parameter></paramdef>
      </funcprototype>
      <funcprototype>
	<funcdef>int <function>gcry_md_map_name</function></funcdef>
	<paramdef>const char*<parameter>name</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_algo_name</secondary>
	     </indexterm>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_map_name</secondary>
	     </indexterm>
  These both functions are used to map a string with the algorithm name to
  the internal algorithm identifier value and vice versa.
  </para>
  <para>
  <function>gcry_md_algo_name</> never returns NULL even in cases where the
  algorithm string is not available.  Instead a string consisting of a
  single question mark is returned.  Do not use this function to test
  for the existence of an algorithm.
  </para>
  <para>
  <function>gcry_md_map_name</> returns 0 if the algorithm is not known
  to &libgcrypt;.
  </para>
</refentry>



<!--**********************************************
***********  md_hash_buffer  *********************
***********************************************-->
<refentry>
  <refnamediv>
    <refname>gcry_md_hash_buffer</refname>
    <refpurpose>fast message calculation</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
      #include &lt;gcrypt.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
	<funcdef>int <function>gcry_md_hash_buffer</function></funcdef>
	<paramdef>int  <parameter>algo</parameter></paramdef>
	<paramdef>char * <parameter>digest</parameter></paramdef>
	<paramdef>const char * <parameter>buffer</parameter></paramdef>
	<paramdef>size_t <parameter>buflen</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
  <para>
  <indexterm><primary>hash functions</primary>
	     <secondary>gcry_md_hash_buffer</secondary>
	     </indexterm>
  <function>gcry_md_hash_buffer</function> is a shortcut function
  to calculate a message digest of a buffer.  This function does not require
  a context and immediatley returns the message digest.
  <parameter>digest</> must be string large enough to hold the digest
  given by algo.  This length may be obtained by using the function
  <function>gcry_md_get_algo_dlen</> but in most cases it will be a statically
  allocated buffer.
  </para>
</refentry>