1
0
mirror of git://git.gnupg.org/gnupg.git synced 2024-05-28 21:50:02 +02:00

Started with gcrypt manual

This commit is contained in:
Werner Koch 2000-02-08 12:34:10 +00:00
parent f00d949f87
commit e8e6125e92
5 changed files with 549 additions and 0 deletions

242
doc/gcryptref-cipher.sgml Normal file
View File

@ -0,0 +1,242 @@
<!-- 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
-->
<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>
<secondary>gcry_cipher_close</secondary>
</indexterm>
<function>gcry_cipher_open</function> creates the context required for
most of the cipher functions.
</para>
</refentry>
<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>
<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>
<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>
<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>
<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>
<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>

191
doc/gcryptref-digest.sgml Normal file
View File

@ -0,0 +1,191 @@
<!-- 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_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>
<secondary>gcry_md_enable</secondary>
<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>
<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>
<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>
<refnamediv>
<refname>gcry_md_ctl</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>
</refentry>
void gcry_md_write( GCRY_MD_HD hd, const byte *buffer, size_t length);
byte *gcry_md_read( GCRY_MD_HD hd, int algo );
void gcry_md_hash_buffer( int algo, char *digest,
const char *buffer, size_t length);
int gcry_md_get_algo( GCRY_MD_HD hd );
unsigned int gcry_md_get_algo_dlen( int algo );
int gcry_md_info( GCRY_MD_HD h, int what, void *buffer, size_t *nbytes);
int gcry_md_algo_info( int algo, int what, void *buffer, size_t *nbytes);
const char *gcry_md_algo_name( int algo );
int gcry_md_map_name( const char* name );
#define gcry_md_putc(h,c) \
do { \
if( (h)->bufpos == (h)->bufsize ) \
gcry_md_write( (h), NULL, 0 ); \
(h)->buf[(h)->bufpos++] = (c) & 0xff; \
} while(0)
#define gcry_md_final(a) \
gcry_md_ctl( (a), GCRYCTL_FINALIZE, NULL, 0 )
#define gcry_md_is_secure(a) \
gcry_md_info( (a), GCRYCTL_IS_SECURE, NULL, NULL )
#define gcry_md_test_algo(a) \
gcry_md_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )

20
doc/gcryptref-misc.sgml Normal file
View File

@ -0,0 +1,20 @@
<!-- 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
-->

20
doc/gcryptref-pubkey.sgml Normal file
View File

@ -0,0 +1,20 @@
<!-- 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
-->

76
doc/gcryptref.sgml Normal file
View File

@ -0,0 +1,76 @@
<!-- 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 reference PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!entity libgcrypt "Libgcrypt">
<!entity cipherref system "gcryptref-cipher.sgml">
<!entity digestref system "gcryptref-digest.sgml">
<!entity pubkeyref system "gcryptref-pubkey.sgml">
<!entity miscref system "gcryptref-misc.sgml">
]>
<!--
<refentry>
<refnamediv>
<refname>XXX</refname>
<refpurpose>xxx</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;gcrypt.h&gt;
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>XXX</function></funcdef>
<paramdef>int <parameter>algo</parameter></paramdef>
</funcprototype>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<indexterm><primary>cipher functions</primary>
<secondary>XXX</secondary>
</indexterm>
<function>XXX</function> xxx
</para>
</refentry>
-->
<reference>
<title>&libgcrypt; Reference Pages</title>
<subtitle>Symmetric Cipher Functions</subtitle>
&cipherref;
<subtitle>Hash Functions</subtitle>
&digestref;
<subtitle>Public Key Functions</subtitle>
&pubkeyref;
<subtitle>Miscellaneous Functions</subtitle>
&miscref;
</reference>