diff options
Diffstat (limited to 'doc/gcryptref-digest.sgml')
| -rw-r--r-- | doc/gcryptref-digest.sgml | 486 |
1 files changed, 0 insertions, 486 deletions
diff --git a/doc/gcryptref-digest.sgml b/doc/gcryptref-digest.sgml deleted file mode 100644 index 3b4dcd7e8..000000000 --- a/doc/gcryptref-digest.sgml +++ /dev/null @@ -1,486 +0,0 @@ -<!-- 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 <gcrypt.h> - </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 <gcrypt.h> - </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 <gcrypt.h> - </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 <gcrypt.h> - </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 <gcrypt.h> - </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 <gcrypt.h> - </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 <gcrypt.h> - </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 <gcrypt.h> - </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 <gcrypt.h> - </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 <gcrypt.h> - </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 */ - |