security-and-privacy/gnupg
security-and-privacy/gnupg
1
0
Fork 0
mirror of git://git.gnupg.org/gnupg.git synced 2025-01-08 12:44:23 +01:00
Code Activity

Removed libgcrypt doc files

Browse Source
This commit is contained in:
Werner Koch 2000-12-19 17:22:37 +00:00
parent 07ca4eaa9d
commit c58fdc9c2f
5 changed files with 0 additions and 1243 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

263
doc/gcryptref-cipher.sgml
View File

@ -1,263 +0,0 @@
<!-- gcryptref-cipher.sgml - libgcrypt reference (ciphers)
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
-->
<!--**********************************************
*********** cipher open, close *****************
***********************************************-->
<refentry>
<refnamediv>
<refname>gcry_cipher_open</refname>
<refname>gcry_cipher_close</refname>
<refpurpose>create and destroy an encryption context</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>GCRY_CIPHER_HD <function>gcry_cipher_open</function></funcdef>
<paramdef>int <parameter>algo</parameter></paramdef>
<paramdef>int <parameter>mode</parameter></paramdef>
<paramdef>unsigned in <parameter>flags</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>gcry_cipher_close</function></funcdef>
<paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>cipher functions</primary>
<secondary>gcry_cipher_open</secondary>
</indexterm>
<indexterm><primary>cipher functions</primary>
<secondary>gcry_cipher_close</secondary>
</indexterm>
<function>gcry_cipher_open</function> creates the context required for
most of the cipher functions.
</para>
</refentry>
<!--**********************************************
*********** cipher control *********************
***********************************************-->
<refentry>
<refnamediv>
<refname>gcry_cipher_ctl</refname>
<refname>gcry_cipher_setkey</refname>
<refname>gcry_cipher_setiv</refname>
<refname>gcry_cipher_setiv</refname>
<refpurpose>control cipher functions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>gcry_cipher_ctl</function></funcdef>
<paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
<paramdef>int <parameter>cmd</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>cipher functions</primary>
<secondary>gcry_cipher_ctl</secondary>
</indexterm>
<function>gcry_cipher_ctl</function> controls various aspects of the
cipher module and specific cipher contexts. A couple of macros may
be used for convenience:
gcry_cipher_setkey(h,k,l)
gcry_cipher_setiv(h,k,l)
gcry_cipher_sync(h)
</para>
</refentry>
<!--**********************************************
*********** cipher info ***********************
***********************************************-->
<refentry>
<refnamediv>
<refname>gcry_cipher_info</refname>
<refpurpose>return information about a cipher context</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>gcry_cipher_info</function></funcdef>
<paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
<paramdef>int <parameter>what</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>cipher functions</primary>
<secondary>gcry_cipher_info</secondary>
</indexterm>
<function>gcry_cipher_info</function> is used to retrieve various
information about a cipher context or the cipher module in general.
Currently no information is available.
</para>
</refentry>
<!--**********************************************
*********** cipher algo name ******************
***********************************************-->
<refentry>
<refnamediv>
<refname>gcry_cipher_algo_name</refname>
<refpurpose>return the name of a cipher algorithm</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>const char *<function>gcry_cipher_algo_name</function></funcdef>
<paramdef>int <parameter>algo</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>cipher functions</primary>
<secondary>gcry_cipher_algo_name</secondary>
</indexterm>
<function>gcry_cipher_algo_name</function> returns a string with the
name of the cipher algorithm <parameter>algo</parameter>. If the algorithm
is not known or an other error occured, an empty string is return. This
function will never return NULL.
</para>
</refentry>
<!--**********************************************
*********** cipher map name ********************
***********************************************-->
<refentry>
<refnamediv>
<refname>gcry_cipher_map_name</refname>
<refpurpose>return an algorithm identifier for string</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>gcry_cipher_map_name</function></funcdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>cipher functions</primary>
<secondary>gcry_cipher_map_name</secondary>
</indexterm>
<function>gcry_cipher_map_name</function> returns the algorithm identifier
for the cipher algorithm described by the string <parameter>name</parameter>.
If this algorith is not available 0 is returned.
</para>
</refentry>
<!--**********************************************
*********** cipher en/decryptlose **************
***********************************************-->
<refentry>
<refnamediv>
<refname>gcry_cipher_encrypt</refname>
<refname>gcry_cipher_decrypt</refname>
<refpurpose>encrypt data or decrypt data</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>gcry_cipher_encrypt</function></funcdef>
<paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
<paramdef>unsigned char <parameter>out</parameter></paramdef>
<paramdef>size_t <parameter>outsize</parameter></paramdef>
<paramdef>unsigned char <parameter>in</parameter></paramdef>
<paramdef>size_t <parameter>insize</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>gcry_cipher_decrypt</function></funcdef>
<paramdef>GCRY_CIPHER_HD <parameter>h</parameter></paramdef>
<paramdef>unsigned char <parameter>out</parameter></paramdef>
<paramdef>size_t <parameter>outsize</parameter></paramdef>
<paramdef>unsigned char <parameter>in</parameter></paramdef>
<paramdef>size_t <parameter>insize</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>cipher functions</primary>
<secondary>gcry_cipher_encrypt</secondary>
</indexterm>
<indexterm><primary>cipher functions</primary>
<secondary>gcry_cipher_decrypt</secondary>
</indexterm>
<function>gcry_cipher_encrypt</function> is used to encrypt the data.
the complemetary function <function>gcry_cipher_decrypt</function> is
be used to decrypt the data. The calling convention for both functions
is the same.
</para>
<para>These functions can either work in place or with two buffers.
Overlapping buffers are not allowed.
</para>
</refentry>

486
doc/gcryptref-digest.sgml
View File

@ -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 &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 */

326
doc/gcryptref-misc.sgml
View File

@ -1,326 +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
-->
<refentry>
<refnamediv>
<refname>gcry_check_version</refname>
<refpurpose>get or check the version of libgcrypt</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>const char *<function>gcry_check_version</function></funcdef>
<paramdef>const char *<parameter>req_version</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>gcry_check_version</primary>
</indexterm>
<function>gcry_check_version</function> checks
that the version of the library is at minimum the requested one
and return the version string; NULL is returned if the condition is
not met. You may pass NULL as reqy_version to simply get the version
string back without any checking.
</para>
</refentry>
<refentry>
<refnamediv>
<refname>gcry_errno</refname>
<refname>gcry_strerror</refname>
<refpurpose>Get the last error</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>gcry_errno</function></funcdef>
</funcprototype>
<funcprototype>
<funcdef>const char *<function>gcry_strerror</function></funcdef>
<paramdef>int<parameter>no</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>gcry_errno</primary></indexterm>
<indexterm><primary>gcry_strerror</primary></indexterm>
Both function are to be used like there Standard-C
counterparts. However <function>gcry_errno</function> is a function
and not just a global variable. If -1 is passed to
<function>gcry_strerror</>, <function>gcry_errno</> is implictly used.
</para>
</refentry>
<refentry>
<refnamediv>
<refname>gcry_control</refname>
<refpurpose>Multi purpose control function</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>gcry_control</function></funcdef>
<paramdef>enum gcry_ctl_cmds<parameter>cmd</parameter></paramdef>
<paramdef><parameter>...</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>gcry_control</primary></indexterm>
This function is used to control various aspects of &libgcrypt;
FIXME: Explain all commands here.
</para>
</refentry>
<refentry>
<refnamediv>
<refname>gcry_set_allocation_handler</refname>
<refname>gcry_set_outofcore_handler</refname>
<refpurpose>Use application defined malloc functions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>gcry_set_allocation_handler</></funcdef>
<paramdef>void *(*<parameter>alloc_func</>)(size_t n)</paramdef>
<paramdef>void *(*<parameter>alloc_secure_func</>)(size_t n)</paramdef>
<paramdef>int (*<parameter>is_secure_func</>)(const void *p)</paramdef>
<paramdef>void *(*<parameter>realloc_func</>)(void *p, size_t n)</paramdef>
<paramdef>void (*<parameter>free_func</>)(void *p)</paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>gcry_set_outofcore_handler</></funcdef>
<paramdef>int (*<parameter>h</>)( void*, size_t, unsigned int ),
void *opaque )</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>gcry_set_allocation_handler</primary></indexterm>
<indexterm><primary>gcry_set_outofcore_handler</primary></indexterm>
FIXME
</para>
</refentry>
<refentry>
<refnamediv>
<refname>gcry_set_fatalerror_handler</refname>
<refpurpose>change the default fatal error handler</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>gcry_set_fatalerror_handler</></funcdef>
<paramdef>void (*<parameter>func</>)(
void *, int, const char*)</paramdef>
<paramdef>void *<parameter>opaque</></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>gcry_set_fatalerror_handler</primary></indexterm>
At certain places the &libgcrypt; may need to call a fatal error fucntion
which does terminate the process. To allow an application to do
some emergency cleanup, it may register a fatal error handler with
the library. This handler is assumed to terminate the application;
however if it returns &libgcrypt; will abort anyway.
</para>
<para>
The handler is called with the opaque value registered here, an
errorcode from &libgcrypt; and some descriptive text string.
</para>
</refentry>
<refentry>
<refnamediv>
<refname>gcry_set_gettext_handler</refname>
<refpurpose>Change the default gettext function</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>gcry_set_gettext_handler</></funcdef>
<paramdef>const char *(*<parameter>func</>)(const char*)</paramdef>
<paramdef>void *<parameter>opaque</></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>gcry_set_log_handler</primary></indexterm>
FIXME!!
</para>
</refentry>
void gcry_set_log_handler( void (*f)(void*,int, const char*, va_list ),
void *opaque );
<refentry>
<refnamediv>
<refname>gcry_set_log_handler</refname>
<refpurpose>Change the default logging function</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>gcry_set_log_handler</></funcdef>
<paramdef>void (*<parameter>func</>)
(void*, int, const char*, va_list)</paramdef>
<paramdef>void *<parameter>opaque</></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>gcry_set_log_handler</primary></indexterm>
&libgcrypt; has it;s own logging functions. Applications which
need to use their own, should provide a log function to &libgcrypt;
so that it will use this function instead.
Fixme: Describe how this is intended to work.
</para>
</refentry>
void *gcry_malloc( size_t n );
void *gcry_calloc( size_t n, size_t m );
void *gcry_malloc_secure( size_t n );
void *gcry_calloc_secure( size_t n, size_t m );
void *gcry_realloc( void *a, size_t n );
void *gcry_xmalloc( size_t n );
void *gcry_xcalloc( size_t n, size_t m );
void *gcry_xmalloc_secure( size_t n );
void *gcry_xcalloc_secure( size_t n, size_t m );
void *gcry_xrealloc( void *a, size_t n );
char *gcry_xstrdup( const char * a);
void gcry_free( void *a );
int gcry_is_secure( const void *a );
<refentry>
<refnamediv>
<refname>gcry_malloc</refname>
<refname>gcry_calloc</refname>
<refname>gcry_malloc_secure</refname>
<refname>gcry_calloc_secure</refname>
<refname>gcry_realloc</refname>
<refname>gcry_xmalloc</refname>
<refname>gcry_xcalloc</refname>
<refname>gcry_xmalloc_secure</refname>
<refname>gcry_xcalloc_secure</refname>
<refname>gcry_xrealloc</refname>
<refname>gcry_xstrdup</refname>
WORk WORK
<refname>gcry_malloc</refname>
<refname>gcry_malloc</refname>
<refpurpose>Change the default logging function</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>gcry_set_log_handler</></funcdef>
<paramdef>void (*<parameter>func</>)
(void*, int, const char*, va_list)</paramdef>
<paramdef>void *<parameter>opaque</></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>gcry_set_log_handler</primary></indexterm>
&libgcrypt; has it;s own logging functions. Applications which
need to use their own, should provide a log function to &libgcrypt;
so that it will use this function instead.
Fixme: Describe how this is intended to work.
</para>
</refentry>
void gcry_randomize( byte *buffer, size_t length,
enum gcry_random_level level );
void *gcry_random_bytes( size_t nbytes, enum gcry_random_level level );
void *gcry_random_bytes_secure( size_t nbytes, enum gcry_random_level level );
-->

92
doc/gcryptref-pubkey.sgml
View File

@ -1,92 +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
-->
<!--**********************************************
*********** pk_encrypt *************************
***********************************************-->
<refentry>
<refnamediv>
<refname>gcry_pk_encrypt</refname>
<refpurpose>do a public key encryption</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>gcry_pk_encrypt</function></funcdef>
<paramdef>GCRY_SEXP *<parameter>result</parameter></paramdef>
<paramdef>GCRY_SEXP <parameter>data</parameter></paramdef>
<paramdef>GCRY_SEXP <parameter>pkey</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>public key functions</primary>
<secondary>gcry_pk_encrypt</secondary>
</indexterm>
<function>gcry_pk_encrypt</function> performs public key encryption
operations. The caller has to provide a public key as the &sexp;
<parameter>pkey</> and <parameter>data</> as a &sexp;
with just one MPI in it. The function returns a &sexp; which may
be passed tp to pk_decrypt.
Later versions of this functions may take more complex input data.
Returns: 0 or an errorcode.
</para>
<literallayout>
s_data = (<replaceable/mpi/)
s_pkey = <replaceable/key-as-defined-in-sexp_to_key/
r_ciph = (enc-val
(<replaceable/algo/
(<replaceable/param_name1/ <replaceable/mpi/)
...
(<replaceable/param_namen/ <replaceable/mpi/)
))
</literallayout>
</refentry>
<!--
int gcry_pk_decrypt( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
int gcry_pk_sign( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
int gcry_pk_verify( GCRY_SEXP sigval, GCRY_SEXP data, GCRY_SEXP pkey );
int gcry_pk_testkey( GCRY_SEXP key );
int gcry_pk_genkey( GCRY_SEXP *r_key, GCRY_SEXP s_parms );
int gcry_pk_ctl( int cmd, void *buffer, size_t buflen);
int gcry_pk_algo_info( int algo, int what, void *buffer, size_t *nbytes);
#define gcry_pk_test_algo(a) \
gcry_pk_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
const char *gcry_pk_algo_name( int algo );
int gcry_pk_map_name( const char* name );
unsigned int gcry_pk_get_nbits( GCRY_SEXP key );
-->

76
doc/gcryptref.sgml
View File

@ -1,76 +0,0 @@
<!-- gcryptref.sgml - libgcrypt reference
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
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!--entity genindex system "gcryptref.toc-idx"-->
<!entity packageversion system "version.sgml">
<!entity libgcrypt "Libgcrypt">
<!entity sexp "S-Exp">
<!entity cipherref system "gcryptref-cipher.sgml">
<!entity digestref system "gcryptref-digest.sgml">
<!entity pubkeyref system "gcryptref-pubkey.sgml">
<!entity miscref system "gcryptref-misc.sgml">
]>
<book>
<bookinfo>
<title>The &libgcrypt; Reference Manual</title>
<subtitle>Version &packageversion;</subtitle>
<date>
2000-03-13
</date>
<copyright>
<year>2000</year>
<holder>Free Software Foundation, Inc.</holder>
</copyright>
<abstract>
<para>
Please direct questions, bug reports, or suggestions concerning
this manual to the mailing list <email>gnupg-doc@gnupg.org</email>.
</para>
<para>
This manual may be redistributed under the terms of the
<ulink url="http://www.gnu.org/copyleft/gpl.html"><phrase>GNU
General Public License</phrase></ulink>.
</para>
</abstract>
</bookinfo>
<reference>
<title>&libgcrypt; Reference Pages</title>
<!--FIXME: How can we subdivide a reference (Part?)
Symmetric Cipher Functions -->
&cipherref;
<!-- Hash Functions -->
&digestref;
<!-- Public Key Functions -->
&pubkeyref;
<!-- Miscellaneous Functions -->
&miscref;
</reference>