Started with gcrypt manual

5 files changed, 549 insertions, 0 deletions

diff --git a/doc/cipher-ref.sgml b/doc/cipher-ref.sgml
new file mode 100644
index 00000000..1253b38f
--- /dev/null
+++ b/doc/cipher-ref.sgml
@@ -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>
+
diff --git a/doc/digest-ref.sgml b/doc/digest-ref.sgml
new file mode 100644
index 00000000..63a345a7
--- /dev/null
+++ b/doc/digest-ref.sgml
@@ -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 )
+
diff --git a/doc/misc-ref.sgml b/doc/misc-ref.sgml
new file mode 100644
index 00000000..88193186
--- /dev/null
+++ b/doc/misc-ref.sgml
@@ -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
+-->
+
diff --git a/doc/pubkey-ref.sgml b/doc/pubkey-ref.sgml
new file mode 100644
index 00000000..88193186
--- /dev/null
+++ b/doc/pubkey-ref.sgml
@@ -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
+-->
+
diff --git a/doc/reference.sgml b/doc/reference.sgml
new file mode 100644
index 00000000..6161e861
--- /dev/null
+++ b/doc/reference.sgml
@@ -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>
+