security-and-privacy/gnupg
security-and-privacy/gnupg
1
0
Fork 0
mirror of git://git.gnupg.org/gnupg.git synced 2024-07-01 02:42:44 +02:00
Code Activity
b75f734a11
gnupg/doc/gcryptref-digest.sgml

487 lines
16 KiB
Plaintext
Raw Blame History

<!-- 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. It is possible to use these functions as MAC functons; therefore
the flag <literal/GCRY_MD_FLAG_HMAC/ must be given along with the
hash functions. Other MAC algorithms than HMAC are currently not
supported. The key for the MAC must be set using
the <function>gcry_md_setkey</> function.
<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>
<refname>gcry_md_setkey</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:
</para>
<para>
<literal>GCRYCTL_FINALIZE</> and the convenience macro
<function>gcry_md_final(a)</>
</para>
<para>
<literal>GCRYCTL_SET_KEY</> and the convenience macro
<function>gcry_md_setkey(a)</>. This is used to turn these
hash functions into MAC functions. The key may be any string
of the speicified length. The type of the MAC is determined
by special flags set with the open function.
NEW: There is now a function to do this
</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>
<!-- FIXME: doc gcry_md_setkey */
View Git Blame Copy Permalink