path: root/doc/gcrypt.texi

\input texinfo                  @c -*- Texinfo -*-
@c Copyright (C) 2000, 2002 Free Software Foundation, Inc.
@c 
@c This file is part of the libgcrypt.
@c
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.1 or
@c any later version published by the Free Software Foundation; with no
@c Invariant Sections, with no the Front-Cover texts, and with no
@c Back-Cover Texts. 
@c A copy of the license is included in the file 'fdl.texi'.
@c
@setfilename gcrypt.info
@settitle The `Libgcrypt' Reference Manual

@dircategory GNU Libraries
@direntry
* libgcrypt: (gcrypt) Cryptographic function library.
@end direntry

@include version.texi

@c Unify some of the indices.
@syncodeindex tp fn
@syncodeindex pg fn

@ifinfo
This file documents the `Libgcrypt' library.

This is Edition @value{EDITION}, last updated @value{UPDATED}, of
@cite{The `Libgcrypt' Reference Manual}, for Version
@value{VERSION}.

Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no the Front-Cover texts, and with no
Back-Cover Texts.  A copy of the license is included in the section
entitled ``GNU Free Documentation License''.
@end ifinfo

@iftex
@shorttitlepage The `Libgcrypt' Reference Manual
@end iftex
@titlepage
@center @titlefont{The `Libgcrypt'}
@sp 1
@center @titlefont{Reference Manual}
@sp 6
@center Edition @value{EDITION}
@sp 1
@center last updated @value{UPDATED}
@sp 1
@center for version @value{VERSION}
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no the Front-Cover texts, and with no
Back-Cover Texts.  A copy of the license is included in the section
entitled ``GNU Free Documentation License''.
@end titlepage
@page

@ifnottex
@node Top
@top Main Menu
This is Edition @value{EDITION}, last updated @value{UPDATED}, of
@cite{The `Libgcrypt' Reference Manual}, for Version
@value{VERSION} of the @acronym{GPGME} library.
@end ifnottex

@menu
* Introduction::                How to use this manual.
* Preparation::                 What you should do before using the library.
* Cipher Functions::            All about ciphers.
* Hash Functions::              How to use cryptographic hash functions.
* Public Key Functions::        How to use asymmetric encryption.
* Random Numbers::              How to create random.
* Utilities::                   Helper functions.
* Error Handling::              Error codes and such.

Appendices

* Copying::                     The GNU General Public License says how you
                                can copy and share `GnuPG Made Easy'.
* Free Documentation License::  This manual is under the GNU Free
                                Documentation License.

Indices

* Concept Index::               Index of concepts and programs.
* Function and Data Index::     Index of functions, variables and data types.

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Getting Started::             
* Features::                    
* Overview::                    

Preparation

* Header::                      
* Version Check::               
* Building the source::         

Error Handling

* Error values::                
* Error strings::               

@end detailmenu
@end menu

@c **********************************************************
@c *******************  Introduction  ***********************
@c **********************************************************
@node Introduction
@chapter Introduction
`Libgcrypt' is a library to provide cryptographic building blocks.

@menu
* Getting Started::             
* Features::                    
* Overview::                    
@end menu

@node Getting Started
@section Getting Started

This manual documents the `Libgcrypt' library programming interface.
All functions and data types provided by the library are explained.

The reader is assumed to possess basic knowledge about applied
cryptography.

This manual can be used in several ways.  If read from the beginning
to the end, it gives a good introduction into the library and how it
can be used in an application.  Forward references are included where
necessary.  Later on, the manual can be used as a reference manual to
get just the information needed about any particular interface of the
library.  Experienced programmers might want to start looking at the
examples at the end of the manual, and then only read up those parts
of the interface which are unclear.


@node Features
@section Features

`Libgcrypt' has a couple of advantages over other libraries doing a
similar job.

@table @asis
@item It's Free Software
Anybody can use, modify, and redistribute it under the terms of the GNU
General Public License (@pxref{Copying}).

@item It encapsulates the low level cryptography
`Libgcrypt' a high level interface to cryptographic buiilding blocks
using an extendable and flexible API.

@end table


@node Overview
@section Overview

Blurb

The `Libgcrypt' library is thread-safe.


@c **********************************************************
@c *******************  Preparation  ************************
@c **********************************************************
@node Preparation
@chapter Preparation

To use `Libgcrypt', you have to perform some changes to your sources and
the build system.  The necessary changes are small and explained in the
following sections.  At the end of this chapter, it is described how the
library is initialized, and how the requirements of the library are
verified.

@menu
* Header::                      
* Version Check::               
* Building the source::         
@end menu


@node Header
@section Header

All interfaces (data types and functions) of the library are defined
in the header file `gcrypt.h'.  You must include this in all programs
using the library, either directly or through some other header file,
like this:

@example
#include <gcrypt.h>
@end example

The name space of `Libgcrypt' is @code{gcry_*} for function names,
@code{Gcry*} for data types and @code{GCRY_*} for other symbols.  In
addition the same name prefixes with one prepended underscore are
reserved for internal use and should never be used by an application.

@node Version Check
@section Version Check

It is often desirable to check that the version of `Libgcrypt' used is
indeed one which fits all requirements.  Even with binary compatibility
new features may have been introduced but due to problem with the
dynamic linker an old version is actually used.  So you may want to
check that the version is okay right after program startup.

@deftypefun const char *gcry_check_version (const char *@var{req_version})

Check that the the version of the library is at minimum the one given as
a string in @var{req_version} and return the actual version string of
the library; return NULL if the condition is not met.  If @code{NULL} is
passed to this function no check is done and only the version string is
returned.  It is a pretty good idea to run this function as soon as
possible, because it may also intializes some subsystems.  In a
multithreaded environment if should be called before any more threads
are created.
@end deftypefun

@node Building the source
@section Building the source

If you want to compile a source file including the `gcry.h' header
file, you must make sure that the compiler can find it in the
directory hierarchy.  This is accomplished by adding the path to the
directory in which the header file is located to the compilers include
file search path (via the @option{-I} option).

However, the path to the include file is determined at the time the
source is configured.  To solve this problem, `Libgrypt' ships with a small
helper program @command{libgcrypt-config} that knows the path to the
include file and other configuration options.  The options that need
to be added to the compiler invocation at compile time are output by
the @option{--cflags} option to @command{libgcrypt-config}.  The following
example shows how it can be used at the command line:

@example
gcc -c foo.c `libgcrypt-config --cflags`
@end example

Adding the output of @samp{libgcrypt-config --cflags} to the compilers
command line will ensure that the compiler can find the `Libgcrypt' header
file.

A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files.  For this to work,
the path to the library files has to be added to the library search path
(via the @option{-L} option).  For this, the option @option{--libs} to
@command{libgcrypt-config} can be used.  For convenience, this option
also outputs all other options that are required to link the program
with the `Libgcrypt' libararies (in particular, the @samp{-lgcrypt}
option).  The example shows how to link @file{foo.o} with the `Libgcrypt'
library to a program @command{foo}.

@example
gcc -o foo foo.o `libgcrypt-config --libs`
@end example

Of course you can also combine both examples to a single command by
specifying both options to @command{libgcrypt-config}:

@example
gcc -o foo foo.c `libgcrypt-config --cflags --libs`
@end example


@c **********************************************************
@c *******************  Ciphers  ****************************
@c **********************************************************
@c @include cipher-ref.texi
@node Cipher Functions
@chapter Cipher Functions


@deftypefun GCRY_CIPHER_HD gcry_cipher_open (int @var{algo}, int @var{mode}, unsigned int @var{flags})

This function creates the context required for most of the othercipher
functions.  In case of an error @code{NULL} is returned.
@end deftypefun

@deftypefun void gcry_cipher_close (GCRY_CIPHER_HD @var{h})

This function releases the context created by @code{gcry_cipher_open}.
@end deftypefun


@deftypefun int gcry_cipher_ctl (GCRY_CIPHER_HD @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})

@code{gcry_cipher_ctl} controls various aspects of the cipher module and
specific cipher contexts.  Usually some more specialzed functions are
used for this purpose.
@end deftypefun

@deftypefun int gcry_cipher_setkey (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})

Set the key used for encryption or decryption.  Note, that this is
implemented as a macro.
@end deftypefun

@deftypefun int gcry_cipher_setiv (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})

Set the initialization vector used for encryption or decryption.  Note,
that this is implemented as a macro.
@end deftypefun

@deftypefun int gcry_cipher_sync (GCRY_CIPHER_HD @var{h})

Peform the a ``sync'' operation which is only used with certain modes.
@end deftypefun


@c ***********************************************
@c ***********  cipher info   ********************
@c ***********************************************
@deftypefun int gcry_cipher_info (GCRY_CIPHER_HD @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})

@code{gcry_cipher_info} is used to retrieve various
information about a cipher context or the cipher module in general.
Currently no information is available.
@end deftypefun

@deftypefun int gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})

fixme

@end deftypefun

@deftypefun const char *gcry_cipher_algo_name (int @var{algo})

@code{gcry_cipher_algo_name} returns a string with the name of the
cipher algorithm @var{algo}.  If the algorithm s not known or an other
error occured, an empty string is return.  This function will never
return @code{NULL}.
@end deftypefun

@deftypefun int gcry_cipher_map_name (const char *@var{name})

@code{gcry_cipher_map_name} returns the algorithm identifier for the
cipher algorithm described by the string @var{name}.  If this algorithm
is not available @code{0} is returned.
@end deftypefun

@deftypefun int gcry_cipher_mode_from_oid (const char *@var{string})

Return the cipher mode associated with an @acronym{ASN.1} object
identifier.  The object identifier is expected to be in the
@acronym{IETF}-style dotted decimal notation.  The function returns
@code{0} for an unknown object identifier or when no mode is associated
with it.
@end deftypefun

@c ******************************************
@c *******  cipher en/decrypt  **************
@c ******************************************

@deftypefun int gcry_cipher_encrypt (GCRY_CIPHER_HD @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})

@code{gcry_cipher_encrypt} is used to encrypt the data.
This function can either work in place or with two buffers.
Overlapping buffers are not allowed.
@end deftypefun

@deftypefun int gcry_cipher_decrypt (GCRY_CIPHER_HD @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})

@code{gcry_cipher_encrypt} is used to decrypt the data.
This function can either work in place or with two buffers.
Overlapping buffers are not allowed.
@end deftypefun

@c **********************************************************
@c *******************  Hash Functions  *********************
@c **********************************************************
@node Hash Functions
@chapter Hash Functions

How to use cryptographic hash functions.


<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>




@c **********************************************************
@c *******************  Public Key  *************************
@c **********************************************************
@node Public Key Functions
@chapter Public Key Functions

How to use asymmetric encryption.

<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 );
    -->


@c **********************************************************
@c *******************  Random  *****************************
@c **********************************************************
@node Random Numbers
@chapter Random Numbers


@deftypefun void gcry_randomize (unsigned char *@var{buffer}, size_t @var{length}, enum gcry_random_level @var{level})

Fill @var{buffer} with @var{length} random bytes using a random quality
as defined by @var{level}.
@end deftypefun

@deftypefun void *gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level})

Allocate a memory block consisting of @var{nbytes} fresh random bytes
using a random quality as defined by @var{level}.
@end deftypefun

@deftypefun void *gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level})

Allocate a memory block consisting of @var{nbytes} fresh random bytes
using a random quality as defined by @var{level}.  This fuinction
differs from @code{gcry_random_bytes} in that the returned buffer is
allcated in a ``secure'' area of the memory.
@end deftypefun



@c **********************************************************
@c *******************  Utilities  **************************
@c **********************************************************
@node Utilities
@chapter Utilities

Helper functions.

      <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>




@c **********************************************************
@c *******************  Errors  ****************************
@c **********************************************************
@node Error Handling
@chapter Error Handling

@menu
* Error values::                
* Error strings::               
@end menu

@node Error values
@section Error values


@node Error strings
@section Error strings

@deftypefun {const char *} gcry_strerror (@w{int @var{err}})
The function @code{gcry_strerror} returns a pointer to a statically
allocated string containing a description of the error with the error
value @var{err}.  This string can be used to output a diagnostic
message to the user.
@end deftypefun




@c **********************************************************
@c *******************  Appendices  *************************
@c **********************************************************

@include gpl.texi

@include fdl.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp

@node Function and Data Index
@unnumbered Function and Data Index

@printindex fn

@summarycontents
@contents
@bye