1 files changed, 3756 insertions, 3756 deletions

diff --git a/linden/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.texi b/linden/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.texi
index 76b5977..aece0af 100755..100644
--- a/linden/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.texi
+++ b/linden/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.texi
@@ -1,3756 +1,3756 @@
-\input texinfo                  @c -*- Texinfo -*-

-@c %**start of header

-@setfilename gcrypt.info

-@include version.texi

-@settitle The Libgcrypt Reference Manual

-@c Unify some of the indices.

-@syncodeindex tp fn

-@syncodeindex pg fn

-@c %**end of header

-@copying

-This manual is for Libgcrypt

-(version @value{VERSION}, @value{UPDATED}),

-which is GNU's library of cryptographic building blocks.

-

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

-

-@quotation

-Permission is granted to copy, distribute and/or modify this document

-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. The text of the license can be found in the

-section entitled ``Copying''.

-@end quotation

-@end copying

-

-@dircategory GNU Libraries

-@direntry

-* libgcrypt: (gcrypt).  Cryptographic function library.

-@end direntry

-

-

-

-@c

-@c Titlepage

-@c

-@setchapternewpage odd

-@titlepage

-@title The Libgcrypt Reference Manual

-@subtitle Version @value{VERSION}

-@subtitle @value{UPDATED}

-@author Werner Koch (@email{wk@@gnupg.org})

-@author Moritz Schulte (@email{mo@@g10code.com})

-

-@page

-@vskip 0pt plus 1filll

-@insertcopying

-@end titlepage

-

-

-@summarycontents

-@contents

-@page

-

-

-@ifnottex

-@node Top

-@top The Libgcrypt Library

-@insertcopying

-@end ifnottex

-

-

-@menu

-* Introduction::                 What is @acronym{Libgcrypt}.

-* Preparation::                  What you should do before using the library.

-* Generalities::                 General library functions and data types.

-* Handler Functions::            Working with handler functions.

-* Symmetric cryptography::       How to use symmetric cryptography.

-* Hashing::                      How to use hashing.

-* Public Key cryptography (I)::  How to use public key cryptography.

-* Public Key cryptography (II):: How to use public key cryptography, alternatively.

-* Random Numbers::               How to work with random numbers.

-* S-expressions::                How to manage S-expressions.

-* MPI library::                  How to work with multi-precision-integers.

-* Utilities::                    Utility functions.

-

-Appendices

-

-* Library Copying::             The GNU Lesser General Public License

-                                says how you can copy and share `Libgcrypt'.

-* Copying::                     The GNU General Public License says how you

-                                can copy and share some parts of `Libgcrypt'.

-

-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::             How to use this manual.

-* Features::                    A glance at @acronym{Libgcrypt}'s features.

-* Overview::                    Overview about the library.

-

-Preparation

-* Header::                              What header file you need to include.

-* Building sources::                    How to build sources using the library.

-* Building sources using Automake::     How to build sources with the help of Automake.

-* Initializing the library::            How to initialize the library.

-* Multi Threading::                     How @acronym{Libgcrypt} can be used in a MT environment.

-

-Generalities

-* Controlling the library::     Controlling @acronym{Libgcrypt}'s behavior.

-* Modules::                     Description of extension modules.

-* Error Handling::              Error codes and such.

-

-Handler Functions

-* Progress handler::            Using a progress handler function.

-* Allocation handler::          Using special memory allocation functions.

-* Error handler::               Using error handler functions.

-* Logging handler::             Using a special logging function.

-

-Symmetric cryptography

-* Available ciphers::           List of ciphers supported by the library.

-* Cipher modules::              How to work with cipher modules.

-* Available cipher modes::      List of cipher modes supported by the library.

-* Working with cipher handles:: How to perform operations related to cipher handles.

-* General cipher functions::    General cipher functions independent of cipher handles.

-

-Hashing

-* Available hash algorithms::           List of hash algorithms supported by the library.

-* Hash algorithm modules::              How to work with hash algorithm modules.

-* Working with hash algorithms::        List of functions related to hashing.

-

-Public Key cryptography (I)

-* Used S-expressions::                    Introduction into the used S-expression.

-* Available algorithms::                  Algorithms supported by the library.

-* Public key modules::                    How to work with public key modules.

-* Cryptographic Functions::               Functions for performing the cryptographic actions.

-* General public-key related Functions::  General functions, not implementing any cryptography.

-

-Public Key cryptography (II)

-* Available asymmetric algorithms:: List of algorithms supported by the library.

-* Working with sets of data::       How to work with sets of data.

-* Working with handles::            How to use handles.

-* Working with keys::               How to work with keys.

-* Using cryptographic functions::   How to perform cryptographic operations.

-* Handle-independent functions::    General functions independent of handles.

-

-Random Numbers

-* Quality of random numbers::   @acronym{Libgcrypt} uses different quality levels.

-* Retrieving random numbers::   How to retrieve random numbers.

-

-S-expressions

-* Data types for S-expressions::   Data types related with S-expressions.

-* Working with S-expressions::     How to work with S-expressions.

-

-MPI library

-* Data types::                  MPI related data types.

-* Basic functions::             First steps with MPI numbers.

-* MPI formats::                 External representation of MPIs.

-* Calculations::                Performing MPI calculations.

-* Comparisons::                 How to compare MPI values.

-* Bit manipulations::           How to access single bits of MPI values.

-* Miscellaneous::               Miscellaneous MPI functions.

-

-Utilities

-* Memory allocation::           Functions related with memory allocation.

-

-@end detailmenu

-

-@end menu

-

-

-

-@c **********************************************************

-@c *******************  Introduction  ***********************

-@c **********************************************************

-@node Introduction

-@chapter Introduction

-`@acronym{Libgcrypt}' is a library providing cryptographic building blocks.

-

-@menu

-* Getting Started::             How to use this manual.

-* Features::                    A glance at @acronym{Libgcrypt}'s features.

-* Overview::                    Overview about the library.

-@end menu

-

-@node Getting Started

-@section Getting Started

-

-This manual documents the `@acronym{Libgcrypt}' library application programming

-interface (API).  All functions and data types provided by the library

-are explained.

-

-@noindent

-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' might have 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

-Lesser General Public License (@pxref{Library Copying}).  Note, that

-some parts (which are not needed on a GNU or GNU/Linux system) are

-subject to the terms of the GNU General Public License

-(@pxref{Copying}); please see the README file of the distribution for of

-list of these parts.

-

-@item It encapsulates the low level cryptography

-`@acronym{Libgcrypt}' provides a high level interface to cryptographic building

-blocks using an extendable and flexible API.

-

-@end table

-

-@node Overview

-@section Overview

-

-@noindent

-The `@acronym{Libgcrypt}' library is fully thread-safe, where it makes

-sense to be thread-safe.  An exception for thread-safety are some

-cryptographic functions that modify a certain context stored in

-handles.  If the user really intents to use such functions from

-different threads on the same handle, he has to take care of the

-serialization of such functions himself.  If not described otherwise,

-every function is thread-safe.

-

-@acronym{Libgcrypt} depends on the library `libgpg-error', which

-contains common error handling related code for GnuPG components.

-

-@c **********************************************************

-@c *******************  Preparation  ************************

-@c **********************************************************

-@node Preparation

-@chapter Preparation

-

-To use `@acronym{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::                      What header file you need to include.

-* Building sources::            How to build sources using the library.

-* Building sources using Automake::  How to build sources with the help of Automake.

-* Initializing the library::    How to initialize the library.

-* Multi Threading::             How @acronym{Libgcrypt} can be used in a MT environment.

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

-files using the library, either directly or through some other header

-file, like this:

-

-@example

-#include <gcrypt.h>

-@end example

-

-The name space of `@acronym{Libgcrypt}' is @code{gcry_*} for function

-and type names 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.  Furthermore

-`libgpg-error' defines functions prefixed with `gpg_' and preprocessor

-symbols prefixed with `GPG_'.  Note that @acronym{Libgcrypt} uses

-libgpg-error, which uses @code{gpg_err_*} as name space for function

-and type names and @code{GPG_ERR_*} for other symbols, including all

-the error codes.

-

-@node Building sources

-@section Building sources

-

-If you want to compile a source file including the `gcrypt.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, `@acronym{Libgcrypt}' 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 `@acronym{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 `@acronym{Libgcrypt}' libraries (in particular, the @samp{-lgcrypt}

-option).  The example shows how to link @file{foo.o} with the `@acronym{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

-

-@node Building sources using Automake

-@section Building sources using Automake

-

-It is much easier if you use GNU Automake instead of writing your own

-Makefiles.  If you do that you do not have to worry about finding and

-invoking the @command{libgcrypt-config} script at all.

-@acronym{Libgcrypt} provides an extension to Automake that does all

-the work for you.

-

-@c A simple macro for optional variables.

-@macro ovar{varname}

-@r{[}@var{\varname\}@r{]}

-@end macro

-@defmac AM_PATH_LIBGCRYPT (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})

-Check whether @acronym{Libgcrypt} (at least version

-@var{minimum-version}, if given) exists on the host system.  If it is

-found, execute @var{action-if-found}, otherwise do

-@var{action-if-not-found}, if given.

-

-Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the

-flags needed for compilation of the program to find the

-@file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker

-flags needed to link the program to the @acronym{Libgcrypt} library.

-@end defmac

-

-You can use the defined Autoconf variables like this in your

-@file{Makefile.am}:

-

-@example

-AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)

-LDADD = $(LIBGCRYPT_LIBS)

-@end example

-

-@node Initializing the library

-@section Initializing the library

-

-It is often desirable to check that the version of `@acronym{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})

-

-The function @code{gcry_check_version} has three purposes.  It can be

-used to retrieve the version number of the library.  In addition it

-can verify that the version number is higher than a certain required

-version number.

-

-In either case, the function initializes some sub-systems, and for

-this reason alone it must be invoked early in your program, before you

-make use of the other functions of @acronym{Libgcrypt}.

-@end deftypefun

-

-@node Multi Threading

-@section Multi Threading

-

-As mentioned earlier, the `@acronym{Libgcrypt}' library is 

-thread-safe if you adhere to the following requirements:

-

-@itemize @bullet

-@item

-If your application is multi-threaded, you must set the thread support

-callbacks with the @code{GCRYCTL_SET_THREAD_CBS} command

-@strong{before} any other function in the library.

-

-This is easy enough if you are indeed writing an application using

-Libgcrypt.  It is rather problematic if you are writing a library

-instead.  Here are some tips what to do if you are writing a library:

-

-If your library requires a certain thread package, just initialize

-Libgcrypt to use this thread package.  If your library supports multiple

-thread packages, but needs to be configured, you will have to

-implement a way to determine which thread package the application

-wants to use with your library anyway.  Then configure Libgcrypt to use

-this thread package.

-

-If your library is fully reentrant without any special support by a

-thread package, then you are lucky indeed.  Unfortunately, this does

-not relieve you from doing either of the two above, or use a third

-option.  The third option is to let the application initialize Libgcrypt

-for you.  Then you are not using Libgcrypt transparently, though.

-

-As if this was not difficult enough, a conflict may arise if two

-libraries try to initialize Libgcrypt independently of each others, and

-both such libraries are then linked into the same application.  To

-make it a bit simpler for you, this will probably work, but only if

-both libraries have the same requirement for the thread package.  This

-is currently only supported for the non-threaded case, GNU Pth and

-pthread.  Support for more thread packages is easy to add, so contact

-us if you require it.

-

-@item

-The function @code{gcry_check_version} must be called before any other

-function in the library, except the @code{GCRYCTL_SET_THREAD_CBS}

-command (called via the @code{gcry_control} function), because it

-initializes the thread support subsystem in @acronym{Libgcrypt}.  To

-achieve this in multi-threaded programs, you must synchronize the

-memory with respect to other threads that also want to use

-@acronym{Libgcrypt}.  For this, it is sufficient to call

-@code{gcry_check_version} before creating the other threads using

-@acronym{Libgcrypt}@footnote{At least this is true for POSIX threads,

-as @code{pthread_create} is a function that synchronizes memory with

-respects to other threads.  There are many functions which have this

-property, a complete list can be found in POSIX, IEEE Std 1003.1-2003,

-Base Definitions, Issue 6, in the definition of the term ``Memory

-Synchronization''.  For other thread packages, more relaxed or more

-strict rules may apply.}.

-

-@item

-

-As with the function @code{gpg_strerror}, @code{gcry_strerror} is not

-thread safe.  You have to use @code{gpg_strerror_r} instead.

-@end itemize

-

-

-@acronym{Libgcrypt} contains convenient macros, which define the

-necessary thread callbacks for PThread and for GNU Pth:

-

-@table @code

-@item GCRY_THREAD_OPTION_PTH_IMPL

-

-This macro defines the following (static) symbols: gcry_pth_init,

-gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock,

-gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write, gcry_pth_select,

-gcry_pth_waitpid, gcry_pth_accept, gcry_pth_connect, gcry_threads_pth.

-

-After including this macro, gcry_control() shall be used with a

-command of GCRYCTL_SET_THREAD_CBS in order to register the thread

-callback structure named ``gcry_threads_pth''.

-

-@item GCRY_THREAD_OPTION_PTHREAD_IMPL

-

-This macro defines the following (static) symbols:

-gcry_pthread_mutex_init, gcry_pthread_mutex_destroy, gcry_mutex_lock,

-gcry_mutex_unlock, gcry_threads_pthread.

-

-After including this macro, gcry_control() shall be used with a

-command of GCRYCTL_SET_THREAD_CBS in order to register the thread

-callback structure named ``gcry_threads_pthread''.

-@end table

-

-Note that these macros need to be terminated with a semicolon.  Keep

-in mind that these are convenient macros for C programmers; C++

-programmers might have to wrap these macros in an ``extern C'' body.

-

-@c **********************************************************

-@c *******************  General  ****************************

-@c **********************************************************

-@node Generalities

-@chapter Generalities

-

-@menu

-* Controlling the library::     Controlling @acronym{Libgcrypt}'s behavior.

-* Modules::                     Description of extension modules.

-* Error Handling::              Error codes and such.

-@end menu

-

-@node Controlling the library

-@section Controlling the library

-

-@deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)

-

-This function can be used to influence the general behavior of

-@acronym{Libgcrypt} in several ways.  Depending on @var{cmd}, more

-arguments can or have to be provided.

-

-@end deftypefun

-

-@node Modules

-@section Modules

-

-@acronym{Libgcrypt} supports the use of `extension modules', which

-implement algorithms in addition to those already built into the

-library directly.

-

-@deftp {Data type} gcry_module_t

-This data type represents a `module'.

-@end deftp

-

-Functions registering modules provided by the user take a `module

-specification structure' as input and return a value of

-@code{gcry_module_t} and an ID that is unique in the modules'

-category.  This ID can be used to reference the newly registered

-module.  After registering a module successfully, the new functionality

-should be able to be used through the normal functions provided by

-@acronym{Libgcrypt} until it is unregistered again.

-

-@c **********************************************************

-@c *******************  Errors  ****************************

-@c **********************************************************

-@node Error Handling

-@section Error Handling

-

-Many functions in @acronym{Libgcrypt} can return an error if they

-fail.  For this reason, the application should always catch the error

-condition and take appropriate measures, for example by releasing the

-resources and passing the error up to the caller, or by displaying a

-descriptive message to the user and cancelling the operation.

-

-Some error values do not indicate a system error or an error in the

-operation, but the result of an operation that failed properly.  For

-example, if you try to decrypt a tempered message, the decryption will

-fail.  Another error value actually means that the end of a data

-buffer or list has been reached.  The following descriptions explain

-for many error codes what they mean usually.  Some error values have

-specific meanings if returned by a certain functions.  Such cases are

-described in the documentation of those functions.

-

-@acronym{Libgcrypt} uses the @code{libgpg-error} library.  This allows

-to share the error codes with other components of the GnuPG system,

-and thus pass error values transparently from the crypto engine, or

-some helper application of the crypto engine, to the user.  This way

-no information is lost.  As a consequence, @acronym{Libgcrypt} does

-not use its own identifiers for error codes, but uses those provided

-by @code{libgpg-error}.  They usually start with @code{GPG_ERR_}.

-

-However, @acronym{Libgcrypt} does provide aliases for the functions

-defined in libgpg-error, which might be preferred for name space

-consistency.

-

-

-Most functions in @acronym{Libgcrypt} return an error code in the case

-of failure.  For this reason, the application should always catch the

-error condition and take appropriate measures, for example by

-releasing the resources and passing the error up to the caller, or by

-displaying a descriptive message to the user and canceling the

-operation.

-

-Some error values do not indicate a system error or an error in the

-operation, but the result of an operation that failed properly.

-

-GnuPG components, including Libgcrypt, use an extra library named

-libgpg-error to provide a common error handling scheme.  For more

-information on libgpg-error, see the according manual.

-

-@menu

-* Error Values::                The error value and what it means.

-* Error Sources::               A list of important error sources.

-* Error Codes::                 A list of important error codes.

-* Error Strings::               How to get a descriptive string from a value.

-@end menu

-

-

-@node Error Values

-@subsection Error Values

-@cindex error values

-@cindex error codes

-@cindex error sources

-

-@deftp {Data type} {gcry_err_code_t}

-The @code{gcry_err_code_t} type is an alias for the

-@code{libgpg-error} type @code{gpg_err_code_t}.  The error code

-indicates the type of an error, or the reason why an operation failed.

-

-A list of important error codes can be found in the next section.

-@end deftp

-

-@deftp {Data type} {gcry_err_source_t}

-The @code{gcry_err_source_t} type is an alias for the

-@code{libgpg-error} type @code{gpg_err_source_t}.  The error source

-has not a precisely defined meaning.  Sometimes it is the place where

-the error happened, sometimes it is the place where an error was

-encoded into an error value.  Usually the error source will give an

-indication to where to look for the problem.  This is not always true,

-but it is attempted to achieve this goal.

-

-A list of important error sources can be found in the next section.

-@end deftp

-

-@deftp {Data type} {gcry_error_t}

-The @code{gcry_error_t} type is an alias for the @code{libgpg-error}

-type @code{gpg_error_t}.  An error value like this has always two

-components, an error code and an error source.  Both together form the

-error value.

-

-Thus, the error value can not be directly compared against an error

-code, but the accessor functions described below must be used.

-However, it is guaranteed that only 0 is used to indicate success

-(@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of

-the error value are set to 0, too.

-

-Note that in @acronym{Libgcrypt}, the error source is used purely for

-diagnostic purposes.  Only the error code should be checked to test

-for a certain outcome of a function.  The manual only documents the

-error code part of an error value.  The error source is left

-unspecified and might be anything.

-@end deftp

-

-@deftypefun {gcry_err_code_t} gcry_err_code (@w{gcry_error_t @var{err}})

-The static inline function @code{gcry_err_code} returns the

-@code{gcry_err_code_t} component of the error value @var{err}.  This

-function must be used to extract the error code from an error value in

-order to compare it with the @code{GPG_ERR_*} error code macros.

-@end deftypefun

-

-@deftypefun {gcry_err_source_t} gcry_err_source (@w{gcry_error_t @var{err}})

-The static inline function @code{gcry_err_source} returns the

-@code{gcry_err_source_t} component of the error value @var{err}.  This

-function must be used to extract the error source from an error value in

-order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.

-@end deftypefun

-

-@deftypefun {gcry_error_t} gcry_err_make (@w{gcry_err_source_t @var{source}}, @w{gcry_err_code_t @var{code}})

-The static inline function @code{gcry_err_make} returns the error

-value consisting of the error source @var{source} and the error code

-@var{code}.

-

-This function can be used in callback functions to construct an error

-value to return it to the library.

-@end deftypefun

-

-@deftypefun {gcry_error_t} gcry_error (@w{gcry_err_code_t @var{code}})

-The static inline function @code{gcry_error} returns the error value

-consisting of the default error source and the error code @var{code}.

-

-For @acronym{GCRY} applications, the default error source is

-@code{GPG_ERR_SOURCE_USER_1}.  You can define

-@code{GCRY_ERR_SOURCE_DEFAULT} before including @file{gcrypt.h} to

-change this default.

-

-This function can be used in callback functions to construct an error

-value to return it to the library.

-@end deftypefun

-

-The @code{libgpg-error} library provides error codes for all system

-error numbers it knows about.  If @var{err} is an unknown error

-number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used.  The

-following functions can be used to construct error values from system

-errno numbers.

-

-@deftypefun {gcry_error_t} gcry_err_make_from_errno (@w{gcry_err_source_t @var{source}}, @w{int @var{err}})

-The function @code{gcry_err_make_from_errno} is like

-@code{gcry_err_make}, but it takes a system error like @code{errno}

-instead of a @code{gcry_err_code_t} error code.

-@end deftypefun

-

-@deftypefun {gcry_error_t} gcry_error_from_errno (@w{int @var{err}})

-The function @code{gcry_error_from_errno} is like @code{gcry_error},

-but it takes a system error like @code{errno} instead of a

-@code{gcry_err_code_t} error code.

-@end deftypefun

-

-Sometimes you might want to map system error numbers to error codes

-directly, or map an error code representing a system error back to the

-system error number.  The following functions can be used to do that.

-

-@deftypefun {gcry_err_code_t} gcry_err_code_from_errno (@w{int @var{err}})

-The function @code{gcry_err_code_from_errno} returns the error code

-for the system error @var{err}.  If @var{err} is not a known system

-error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.

-@end deftypefun

-

-@deftypefun {int} gcry_err_code_to_errno (@w{gcry_err_code_t @var{err}})

-The function @code{gcry_err_code_to_errno} returns the system error

-for the error code @var{err}.  If @var{err} is not an error code

-representing a system error, or if this system error is not defined on

-this system, the function returns @code{0}.

-@end deftypefun

-

-

-@node Error Sources

-@subsection Error Sources

-@cindex error codes, list of

-

-The library @code{libgpg-error} defines an error source for every

-component of the GnuPG system.  The error source part of an error

-value is not well defined.  As such it is mainly useful to improve the

-diagnostic error message for the user.

-

-If the error code part of an error value is @code{0}, the whole error

-value will be @code{0}.  In this case the error source part is of

-course @code{GPG_ERR_SOURCE_UNKNOWN}.

-

-The list of error sources that might occur in applications using

-@acronym{Libgctypt} is:

-

-@table @code

-@item GPG_ERR_SOURCE_UNKNOWN

-The error source is not known.  The value of this error source is

-@code{0}.

-

-@item GPG_ERR_SOURCE_GPGME

-The error source is @acronym{GPGME} itself.

-

-@item GPG_ERR_SOURCE_GPG

-The error source is GnuPG, which is the crypto engine used for the

-OpenPGP protocol.

-

-@item GPG_ERR_SOURCE_GPGSM

-The error source is GPGSM, which is the crypto engine used for the

-OpenPGP protocol.

-

-@item GPG_ERR_SOURCE_GCRYPT

-The error source is @code{libgcrypt}, which is used by crypto engines

-to perform cryptographic operations.

-

-@item GPG_ERR_SOURCE_GPGAGENT

-The error source is @command{gpg-agent}, which is used by crypto

-engines to perform operations with the secret key.

-

-@item GPG_ERR_SOURCE_PINENTRY

-The error source is @command{pinentry}, which is used by

-@command{gpg-agent} to query the passphrase to unlock a secret key.

-

-@item GPG_ERR_SOURCE_SCD

-The error source is the SmartCard Daemon, which is used by

-@command{gpg-agent} to delegate operations with the secret key to a

-SmartCard.

-

-@item GPG_ERR_SOURCE_KEYBOX

-The error source is @code{libkbx}, a library used by the crypto

-engines to manage local keyrings.

-

-@item GPG_ERR_SOURCE_USER_1

-@item GPG_ERR_SOURCE_USER_2

-@item GPG_ERR_SOURCE_USER_3

-@item GPG_ERR_SOURCE_USER_4

-These error sources are not used by any GnuPG component and can be

-used by other software.  For example, applications using

-@acronym{Libgcrypt} can use them to mark error values coming from callback

-handlers.  Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors

-created with @code{gcry_error} and @code{gcry_error_from_errno},

-unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including

-@file{gcrypt.h}.

-@end table

-

-

-@node Error Codes

-@subsection Error Codes

-@cindex error codes, list of

-

-The library @code{libgpg-error} defines many error values.  The

-following list includes the most important error codes.

-

-@table @code

-@item GPG_ERR_EOF

-This value indicates the end of a list, buffer or file.

-

-@item GPG_ERR_NO_ERROR

-This value indicates success.  The value of this error code is

-@code{0}.  Also, it is guaranteed that an error value made from the

-error code @code{0} will be @code{0} itself (as a whole).  This means

-that the error source information is lost for this error code,

-however, as this error code indicates that no error occured, this is

-generally not a problem.

-

-@item GPG_ERR_GENERAL

-This value means that something went wrong, but either there is not

-enough information about the problem to return a more useful error

-value, or there is no separate error value for this type of problem.

-

-@item GPG_ERR_ENOMEM

-This value means that an out-of-memory condition occurred.

-

-@item GPG_ERR_E...

-System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for

-the system error.

-

-@item GPG_ERR_INV_VALUE

-This value means that some user provided data was out of range.

-

-@item GPG_ERR_UNUSABLE_PUBKEY

-This value means that some recipients for a message were invalid.

-

-@item GPG_ERR_UNUSABLE_SECKEY

-This value means that some signers were invalid.

-

-@item GPG_ERR_NO_DATA

-This value means that data was expected where no data was found.

-

-@item GPG_ERR_CONFLICT

-This value means that a conflict of some sort occurred.

-

-@item GPG_ERR_NOT_IMPLEMENTED

-This value indicates that the specific function (or operation) is not

-implemented.  This error should never happen.  It can only occur if

-you use certain values or configuration options which do not work,

-but for which we think that they should work at some later time.

-

-@item GPG_ERR_DECRYPT_FAILED

-This value indicates that a decryption operation was unsuccessful.

-

-@item GPG_ERR_WRONG_KEY_USAGE

-This value indicates that a key is not used appropriately.

-

-@item GPG_ERR_NO_SECKEY

-This value indicates that no secret key for the user ID is available.

-

-@item GPG_ERR_UNSUPPORTED_ALGORITHM

-This value means a verification failed because the cryptographic

-algorithm is not supported by the crypto backend.

-

-@item GPG_ERR_BAD_SIGNATURE

-This value means a verification failed because the signature is bad.

-

-@item GPG_ERR_NO_PUBKEY

-This value means a verification failed because the public key is not

-available.

-

-@item GPG_ERR_USER_1

-@item GPG_ERR_USER_2

-@item ...

-@item GPG_ERR_USER_16

-These error codes are not used by any GnuPG component and can be

-freely used by other software.  Applications using @acronym{Libgcrypt}

-might use them to mark specific errors returned by callback handlers

-if no suitable error codes (including the system errors) for these

-errors exist already.

-@end table

-

-

-@node Error Strings

-@subsection Error Strings

-@cindex error values, printing of

-@cindex error codes, printing of

-@cindex error sources, printing of

-@cindex error strings

-

-@deftypefun {const char *} gcry_strerror (@w{gcry_error_t @var{err}})

-The function @code{gcry_strerror} returns a pointer to a statically

-allocated string containing a description of the error code contained

-in the error value @var{err}.  This string can be used to output a

-diagnostic message to the user.

-@end deftypefun

-

-

-@deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}})

-The function @code{gcry_strerror} returns a pointer to a statically

-allocated string containing a description of the error source

-contained in the error value @var{err}.  This string can be used to

-output a diagnostic message to the user.

-@end deftypefun

-

-The following example illustrates the use of the functions described

-above:

-

-@example

-@{

-  gcry_cipher_hd_t handle;

-  gcry_error_t err = 0;

-

-  err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0);

-  if (err)

-    @{

-      fprintf (stderr, "Failure: %s/%s\n",

-               gcry_strsource (err),

-               gcry_strerror (err));

-    @}

-@}

-@end example

-

-@c **********************************************************

-@c *******************  General  ****************************

-@c **********************************************************

-@node Handler Functions

-@chapter Handler Functions

-

-@acronym{Libgcrypt} makes it possible to install so called `handler functions',

-which get called by @acronym{Libgcrypt} in case of certain events.

-

-@menu

-* Progress handler::            Using a progress handler function.

-* Allocation handler::          Using special memory allocation functions.

-* Error handler::               Using error handler functions.

-* Logging handler::             Using a special logging function.

-@end menu

-

-@node Progress handler

-@section Progress handler

-

-It is often useful to retrieve some feedback while long running

-operations are performed.

-

-@deftp {Data type} gcry_handler_progress_t

-Progress handler functions have to be of the type

-@code{gcry_handler_progress_t}, which is defined as:

-

-@code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)}

-@end deftp

-

-The following function may be used to register a handler function for

-this purpose.

-

-@deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data})

-

-This function installs @var{cb} as the `Progress handler' function.

-@var{cb} must be defined as follows:

-

-@example

-void

-my_progress_handler (void *@var{cb_data}, const char *@var{what},

-                     int @var{printchar}, int @var{current}, int @var{total})

-@{

-  /* Do something.  */

-@}

-@end example

-

-A description of the arguments of the progress handler function follows.

-

-@table @var

-@item cb_data

-The argument provided in the call to @code{gcry_set_progress_handler}.

-@item what

-A string identifying the type of the progress output.  The following

-values for @var{what} are defined:

-

-@table @code

-@item need_entropy

-Not enough entropy is available.  @var{total} holds the number of

-required bytes.

-

-@item primegen

-Values for @var{printchar}:

-@table @code

-@item \n

-Prime generated.

-@item !

-Need to refresh the pool of prime numbers.

-@item <, >

-Number of bits adjusted.

-@item ^

-Searching for a generator.

-@item .

-Fermat test on 10 candidates failed.

-@item :

-Restart with a new random value.

-@item +

-Rabin Miller test passed.

-@end table

-

-@end table

-

-@end table

-@end deftypefun

-

-@node Allocation handler

-@section Allocation handler

-

-It is possible to make @acronym{Libgcrypt} use special memory

-allocation functions instead of the built-in ones.

-

-Memory allocation functions are of the following types:

-@deftp {Data type} gcry_handler_alloc_t

-This type is defined as: @code{void *(*gcry_handler_alloc_t) (size_t n)}.

-@end deftp

-@deftp {Data type} gcry_handler_secure_check_t

-This type is defined as: @code{int *(*gcry_handler_secure_check_t) (const void *)}.

-@end deftp

-@deftp {Data type} gcry_handler_realloc_t

-This type is defined as: @code{void *(*gcry_handler_realloc_t) (void *p, size_t n)}.

-@end deftp

-@deftp {Data type} gcry_handler_free_t

-This type is defined as: @code{void *(*gcry_handler_free_t) (void *)}.

-@end deftp

-

-Special memory allocation functions can be installed with the

-following function:

-

-@deftypefun void gcry_set_allocation_handler (gcry_handler_alloc_t @var{func_alloc}, gcry_handler_alloc_t @var{func_alloc_secure}, gcry_handler_secure_check_t @var{func_secure_check}, gcry_handler_realloc_t @var{func_realloc}, gcry_handler_free_t @var{func_free})

-Install the provided functions and use them instead of the built-in

-functions for doing memory allocation.

-@end deftypefun

-

-@node Error handler

-@section Error handler

-

-The following functions may be used to register handler functions that

-are called by @acronym{Libgcrypt} in case certain error conditions

-occur.

-

-@deftp {Data type} gcry_handler_no_mem_t

-This type is defined as: @code{void (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)}

-@end deftp

-@deftypefun void gcry_set_outofcore_handler (gcry_handler_no_mem_t @var{func_no_mem}, void *@var{cb_data})

-This function registers @var{func_no_mem} as `out-of-core handler',

-which means that it will be called in the case of not having enough

-memory available.

-@end deftypefun

-

-@deftp {Data type} gcry_handler_error_t

-This type is defined as: @code{void (*gcry_handler_error_t) (void *, int, const char *)}

-@end deftp

-

-@deftypefun void gcry_set_fatalerror_handler (gcry_handler_error_t @var{func_error}, void *@var{cb_data})

-This function registers @var{func_error} as `error handler',

-which means that it will be called in error conditions.

-@end deftypefun

-

-@node Logging handler

-@section Logging handler

-

-@deftp {Data type} gcry_handler_log_t

-This type is defined as: @code{void (*gcry_handler_log_t) (void *, int, const char *, va_list)}

-@end deftp

-

-@deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})

-This function registers @var{func_log} as `logging handler', which

-means that it will be called in case @acronym{Libgcrypt} wants to log

-a message.

-@end deftypefun

-

-@c **********************************************************

-@c *******************  Ciphers  ****************************

-@c **********************************************************

-@c @include cipher-ref.texi

-@node Symmetric cryptography

-@chapter Symmetric cryptography

-

-The cipher functions are used for symmetrical cryptography,

-i.e. cryptography using a shared key.  The programming model follows

-an open/process/close paradigm and is in that similar to other

-building blocks provided by @acronym{Libgcrypt}.

-

-@menu

-* Available ciphers::           List of ciphers supported by the library.

-* Cipher modules::              How to work with cipher modules.

-* Available cipher modes::      List of cipher modes supported by the library.

-* Working with cipher handles::  How to perform operations related to cipher handles.

-* General cipher functions::    General cipher functions independent of cipher handles.

-@end menu

-

-@node Available ciphers

-@section Available ciphers

-

-@table @code

-@item GCRY_CIPHER_NONE

-This is not a real algorithm but used by some functions as error return.

-The value always evaluates to false.

-

-@item GCRY_CIPHER_IDEA

-This is the IDEA algorithm.  The constant is provided but there is

-currently no implementation for it because the algorithm is patented.

-

-@item GCRY_CIPHER_3DES

-Triple-DES with 3 Keys as EDE.  The key size of this algorithm is 168 but

-you have to pass 192 bits because the most significant bits of each byte

-are ignored.

-

-@item GCRY_CIPHER_CAST5

-CAST128-5 block cipher algorithm.  The key size is 128 bits.

-        

-@item GCRY_CIPHER_BLOWFISH

-The blowfish algorithm. The current implementation allows only for a key

-size of 128 bits.

-

-@item GCRY_CIPHER_SAFER_SK128

-Reserved and not currently implemented.

-

-@item GCRY_CIPHER_DES_SK          

-Reserved and not currently implemented.

- 

-@item  GCRY_CIPHER_AES        

-@itemx GCRY_CIPHER_AES128

-@itemx GCRY_CIPHER_RIJNDAEL

-@itemx GCRY_CIPHER_RIJNDAEL128

-AES (Rijndael) with a 128 bit key.

-

-@item  GCRY_CIPHER_AES192     

-@itemx GCRY_CIPHER_RIJNDAEL128

-AES (Rijndael) with a 192 bit key.

-

-@item  GCRY_CIPHER_AES256 

-@itemx GCRY_CIPHER_RIJNDAEL256

-AES (Rijndael) with a 256 bit key.

-    

-@item  GCRY_CIPHER_TWOFISH

-The Twofish algorithm with a 256 bit key.

-    

-@item  GCRY_CIPHER_TWOFISH128

-The Twofish algorithm with a 128 bit key.

-    

-@item  GCRY_CIPHER_ARCFOUR   

-An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm.

-Note that this is a stream cipher and must be used very carefully to

-avoid a couple of weaknesses. 

-

-@item  GCRY_CIPHER_DES       

-Standard DES with a 56 bit key. You need to pass 64 bit but the high

-bits of each byte are ignored.  Note, that this is a weak algorithm

-which can be broken in reasonable time using a brute force approach.

-

-@end table

-

-@node Cipher modules

-@section Cipher modules

-

-@acronym{Libgcrypt} makes it possible to load additional `cipher

-modules'; these cipher can be used just like the cipher algorithms

-that are built into the library directly.  For an introduction into

-extension modules, see @xref{Modules}.

-

-@deftp {Data type} gcry_cipher_spec_t

-This is the `module specification structure' needed for registering

-cipher modules, which has to be filled in by the user before it can be

-used to register a module.  It contains the following members:

-

-@table @code

-@item const char *name

-The primary name of the algorithm.

-@item const char **aliases

-A list of strings that are `aliases' for the algorithm.  The list must

-be terminated with a NULL element.

-@item gcry_cipher_oid_spec_t *oids

-A list of OIDs that are to be associated with the algorithm.  The

-list's last element must have it's `oid' member set to NULL.  See

-below for an explanation of this type.

-@item size_t blocksize

-The block size of the algorithm, in bytes.

-@item size_t keylen

-The length of the key, in bits.

-@item size_t contextsize

-The size of the algorithm-specific `context', that should be allocated

-for each handle.

-@item gcry_cipher_setkey_t setkey

-The function responsible for initializing a handle with a provided

-key.  See below for a description of this type.

-@item gcry_cipher_encrypt_t encrypt

-The function responsible for encrypting a single block.  See below for

-a description of this type.

-@item gcry_cipher_decrypt_t decrypt

-The function responsible for decrypting a single block.  See below for

-a description of this type.

-@item gcry_cipher_stencrypt_t stencrypt

-Like `encrypt', for stream ciphers.  See below for a description of

-this type.

-@item gcry_cipher_stdecrypt_t stdecrypt

-Like `decrypt', for stream ciphers.  See below for a description of

-this type.

-@end table

-@end deftp

-

-@deftp {Data type} gcry_cipher_oid_spec_t

-This type is used for associating a user-provided algorithm

-implementation with certain OIDs.  It contains the following members:

-@table @code

-@item const char *oid

-Textual representation of the OID.

-@item int mode

-Cipher mode for which this OID is valid.

-@end table

-@end deftp

-

-@deftp {Data type} gcry_cipher_setkey_t

-Type for the `setkey' function, defined as: gcry_err_code_t

-(*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned

-keylen)

-@end deftp

-

-@deftp {Data type} gcry_cipher_encrypt_t

-Type for the `encrypt' function, defined as: gcry_err_code_t

-(*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const

-unsigned char *inbuf)

-@end deftp

-

-@deftp {Data type} gcry_cipher_decrypt_t

-Type for the `decrypt' function, defined as: gcry_err_code_t

-(*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const

-unsigned char *inbuf)

-@end deftp

-

-@deftp {Data type} gcry_cipher_stencrypt_t

-Type for the `stencrypt' function, defined as: gcry_err_code_t

-(*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, const

-unsigned char *, unsigned int n)

-@end deftp

-

-@deftp {Data type} gcry_cipher_stdecrypt_t

-Type for the `stdecrypt' function, defined as: gcry_err_code_t

-(*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, const

-unsigned char *, unsigned int n)

-@end deftp

-

-@deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module})

-

-Register a new cipher module whose specification can be found in

-@var{cipher}.  On success, a new algorithm ID is stored in

-@var{algorithm_id} and a pointer representing this module is stored

-in @var{module}.

-@end deftypefun

-

-@deftypefun void gcry_cipher_unregister (gcry_module_t @var{module})

-Unregister the cipher identified by @var{module}, which must have been

-registered with gcry_cipher_register.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length})

-Get a list consisting of the IDs of the loaded cipher modules.  If

-@var{list} is zero, write the number of loaded cipher modules to

-@var{list_length} and return.  If @var{list} is non-zero, the first

-*@var{list_length} algorithm IDs are stored in @var{list}, which must

-be of according size.  In case there are less cipher modules than

-*@var{list_length}, *@var{list_length} is updated to the correct

-number.

-@end deftypefun

-

-@node Available cipher modes

-@section Available cipher modes

-

-@table @code

-@item GCRY_CIPHER_MODE_NONE

-No mode specified, may be set later using other functions.  The value

-of this constant is always 0.

-

-@item GCRY_CIPHER_MODE_ECB

-Electronic Codebook mode.  

-

-@item GCRY_CIPHER_MODE_CFB

-Cipher Feedback mode.

-

-@item  GCRY_CIPHER_MODE_CBC

-Cipher Block Chaining mode.

-

-@item GCRY_CIPHER_MODE_STREAM

-Stream mode, only to be used with stream cipher algorithms.

-

-@item GCRY_CIPHER_MODE_OFB

-Outer Feedback mode.

-

-@item  GCRY_CIPHER_MODE_CTR

-Counter mode.

-

-@end table

-

-@node Working with cipher handles

-@section Working with cipher handles

-

-To use a cipher algorithm, you must first allocate an according

-handle.  This is to be done using the open function:

-

-@deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd}, int @var{algo}, int @var{mode}, unsigned int @var{flags})

-

-This function creates the context handle required for most of the

-other cipher functions and returns a handle to it in `hd'.  In case of

-an error, an according error code is returned.

-

-The ID of algorithm to use must be specified via @var{algo}.  See

-@xref{Available ciphers}, for a list of supported ciphers and the

-according constants.

-

-Besides using the constants directly, the function

-@code{gcry_cipher_map_name} may be used to convert the textual name of

-an algorithm into the according numeric ID.

-

-The cipher mode to use must be specified via @var{mode}.  See

-@xref{Available cipher modes}, for a list of supported cipher modes

-and the according constants.  Note, that some modes do not work

-together with all algorithms.

-

-The third argument @var{flags} can either be passed as @code{0} or as

-the bit-wise OR of the following constants.

-

-@table @code

-@item GCRY_CIPHER_SECURE

-Make sure that all operations are allocated in secure memory.  This is

-useful, when the key material is highly confidential.

-@item GCRY_CIPHER_ENABLE_SYNC

-This flag enables the CFB sync mode, which is a special feature of

-@acronym{Libgcrypt}'s CFB mode implementation to allow for OpenPGP's CFB variant. 

-See @code{gcry_cipher_sync}.

-@item GCRY_CIPHER_CBC_CTS

-Enable cipher text stealing (CTS) for the CBC mode.  Cannot be used

-simultaneous as GCRY_CIPHER_CBC_MAC

-@item GCRY_CIPHER_CBC_MAC

-Compute CBC-MAC keyed checksums.  This is the same as CBC mode, but

-only output the last block.  Cannot be used simultaneous as

-GCRY_CIPHER_CBC_CTS.

-@end table

-@end deftypefun 

-

-Use the following function to release an existing handle:

-

-@deftypefun void gcry_cipher_close (gcry_cipher_hd_t @var{h})

-

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

-@end deftypefun

-

-In order to use a handle for performing cryptographic operations, a

-`key' has to be set first:

-

-@deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})

-

-Set the key @var{k} used for encryption or decryption in the context

-denoted by the handle @var{h}.  The length @var{l} of the key @var{k}

-must match the required length of the algorithm set for this context or

-be in the allowed range for algorithms with variable key size.  The

-function checks this and returns an error if there is a problem.  A

-caller should always check for an error.

-

-Note, this is currently implemented as a macro but may be changed to a

-function in the future.

-@end deftypefun

-

-Most crypto modes requires an initialization vector (IV), which

-usually is a non-secret random string acting as a kind of salt value.

-The CTR mode requires a counter, which is also similar to a salt

-value.  To set the IV or CTR, use these functions:

-

-@deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})

-

-Set the initialization vector used for encryption or decryption. The

-vector is passed as the buffer @var{K} of length @var{l} and copied to

-internal data structures.  The function checks that the IV matches the

-requirement of the selected algorithm and mode.  Note, that this is

-implemented as a macro.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, void *@var{c}, size_t @var{l})

-

-Set the counter vector used for encryption or decryption. The counter

-is passed as the buffer @var{c} of length @var{l} and copied to

-internal data structures.  The function checks that the counter

-matches the requirement of the selected algorithm (i.e., it must be

-the same size as the block size).  Note, that this is implemented as a

-macro.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})

-

-Set the given handle's context back to the state it had after the last

-call to gcry_cipher_setkey and clear the initialization vector.

-

-Note, that gcry_cipher_reset is implemented as a macro.

-@end deftypefun

-

-The actual encryption and decryption is done by using one of the

-following functions.  They may be used as often as required to process

-all the data.

-

-@deftypefun gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t @var{h}, void *{out}, size_t @var{outsize}, const void *@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.  It uses the cipher

-context already setup and described by the handle @var{h}.  There are 2

-ways to use the function: If @var{in} is passed as @code{NULL} and

-@var{inlen} is @code{0}, in-place encryption of the data in @var{out} or

-length @var{outsize} takes place.  With @var{in} being not @code{NULL},

-@var{inlen} bytes are encrypted to the buffer @var{out} which must have

-at least a size of @var{inlen}.  @var{outlen} must be set to the

-allocated size of @var{out}, so that the function can check that there

-is sufficient space. Note, that overlapping buffers are not allowed.

-

-Depending on the selected algorithms and encryption mode, the length of

-the buffers must be a multiple of the block size.

-

-The function returns @code{0} on success or an error code.

-@end deftypefun

-

-

-@deftypefun gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t @var{h}, void *{out}, size_t @var{outsize}, const void *@var{in}, size_t @var{inlen})

-

-@code{gcry_cipher_decrypt} is used to decrypt the data.  This function

-can either work in place or with two buffers.  It uses the cipher

-context already setup and described by the handle @var{h}.  There are 2

-ways to use the function: If @var{in} is passed as @code{NULL} and

-@var{inlen} is @code{0}, in-place decryption of the data in @var{out} or

-length @var{outsize} takes place.  With @var{in} being not @code{NULL},

-@var{inlen} bytes are decrypted to the buffer @var{out} which must have

-at least a size of @var{inlen}.  @var{outlen} must be set to the

-allocated size of @var{out}, so that the function can check that there

-is sufficient space. Note, that overlapping buffers are not allowed.

-

-Depending on the selected algorithms and encryption mode, the length of

-the buffers must be a multiple of the block size.

-

-The function returns @code{0} on success or an error code.

-@end deftypefun

-

-

-OpenPGP (as defined in RFC-2440) requires a special sync operation in

-some places, the following function is used for this:

-

-@deftypefun gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})

-

-Perform the OpenPGP sync operation on context @var{h}. Note, that this

-is a no-op unless the context was created with the flag

-@code{GCRY_CIPHER_ENABLE_SYNC}

-@end deftypefun

-

-Some of the described functions are implemented as macros utilizing a

-catch-all control function.  This control function is rarely used

-directly but there is nothing which would inhibit it:

-

-@deftypefun gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t @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 specialized functions or

-macros are used for this purpose.  The semantics of the function and its

-parameters depends on the the command @var{cmd} and the passed context

-handle @var{h}.  Please see the comments in the source code

-(@code{src/global.c}) for details.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_cipher_info (gcry_cipher_hd_t @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

-

-@node General cipher functions

-@section General cipher functions

-

-To work with the algorithms, several functions are available to map

-algorithm names to the internal identifiers, as well as ways to

-retrieve information about an algorithm or the current cipher context.

-

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

-

-This function is used to retrieve information on a specific algorithm.

-You pass the cipher algorithm ID as @var{algo} and the type of

-information requested as @var{what}. The result is either returned as

-the return code of the function or copied to the provided @var{buffer}

-whose allocated length must be available in an integer variable with the

-address passed in @var{nbytes}.  This variable will also receive the

-actual used length of the buffer. 

-

-Here is a list of supported codes for @var{what}:

-

-@c begin constants for gcry_cipher_algo_info

-@table @code

-@item GCRYCTL_GET_KEYLEN:

-Return the length of the key. If the algorithm supports multiple key

-lengths, the maximum supported value is returned.  The length is

-returned as number of octets (bytes) and not as number of bits in

-@var{nbytes}; @var{buffer} must be zero.

-

-@item GCRYCTL_GET_BLKLEN:

-Return the block length of the algorithm.  The length is returned as a

-number of octets in @var{nbytes}; @var{buffer} must be zero.

-

-@item GCRYCTL_TEST_ALGO:

-Returns @code{0} when the specified algorithm is available for use.

-@var{buffer} and @var{nbytes} must be zero.

- 

-@end table  

-@c end constants for gcry_cipher_algo_info

-

-@end deftypefun

-@c end gcry_cipher_algo_info

-

-@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 is not known or another

-error occurred, an empty string is returned.  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 *******************  Hash Functions  *********************

-@c **********************************************************

-@node Hashing

-@chapter Hashing

-

-@acronym{Libgcrypt} provides an easy and consistent to use interface

-for hashing.  Hashing is buffered and several hash algorithms can be

-updated at once.  It is possible to calculate a MAC using the same

-routines.  The programming model follows an open/process/close

-paradigm and is in that similar to other building blocks provided by

-@acronym{Libgcrypt}.

-

-For convenience reasons, a few cyclic redundancy check value operations

-are also supported.

-

-@menu

-* Available hash algorithms::   List of hash algorithms supported by the library.

-* Hash algorithm modules::      How to work with hash algorithm modules.

-* Working with hash algorithms::  List of functions related to hashing.

-@end menu

-

-@node Available hash algorithms

-@section Available hash algorithms

-

-@c begin table of hash algorithms

-@table @code

-@item GCRY_MD_NONE

-This is not a real algorithm but used by some functions as an error

-return value.  This constant is guaranteed to have the value @code{0}.

-

-@item GCRY_MD_SHA1

-This is the SHA-1 algorithm which yields a message digest of 20 bytes.

-

-@item GCRY_MD_RMD160

-This is the 160 bit version of the RIPE message digest (RIPE-MD-160).

-Like SHA-1 it also yields a digest of 20 bytes.

-

-@item GCRY_MD_MD5

-This is the well known MD5 algorithm, which yields a message digest of

-16 bytes. 

-

-@item GCRY_MD_MD4

-This is the MD4 algorithm, which yields a message digest of 16 bytes.

-

-@item GCRY_MD_MD2

-This is an reserved identifier for MD-2; there is no implementation yet.

-

-@item GCRY_MD_TIGER

-This is the TIGER/192 algorithm which yields a message digest of 24 bytes.

-

-@item GCRY_MD_HAVAL

-This is an reserved for the HAVAL algorithm with 5 passes and 160

-bit. It yields a message digest of 20 bytes.  Note that there is no

-implementation yet available.

-

-@item GCRY_MD_SHA256

-This is the SHA-256 algorithm which yields a message digest of 32 bytes.

-See FIPS 180-2 for the specification.

-

-@item GCRY_MD_SHA384

-This is reserved for SHA-2 with 384 bits. It yields a message digest of

-48 bytes.  Note that there is no implementation yet available.

-

-@item GCRY_MD_SHA512

-This is reserved for SHA-2 with 512 bits. It yields a message digest of

-64 bytes.  Note that there is no implementation yet available.

-

-@item GCRY_MD_CRC32

-This is the ISO 3309 and ITU-T V.42 cyclic redundancy check.  It

-yields an output of 4 bytes.

-

-@item GCRY_MD_CRC32_RFC1510

-This is the above cyclic redundancy check function, as modified by RFC

-1510.  It yields an output of 4 bytes.

-

-@item GCRY_MD_CRC24_RFC2440

-This is the OpenPGP cyclic redundancy check function.  It yields an

-output of 3 bytes.

-

-@end table

-@c end table of hash algorithms

-

-@node Hash algorithm modules

-@section Hash algorithm modules

-

-@acronym{Libgcrypt} makes it possible to load additional `message

-digest modules'; these cipher can be used just like the message digest

-algorithms that are built into the library directly.  For an

-introduction into extension modules, see @xref{Modules}.

-

-@deftp {Data type} gcry_md_spec_t

-This is the `module specification structure' needed for registering

-message digest modules, which has to be filled in by the user before

-it can be used to register a module.  It contains the following

-members:

-

-@table @code

-@item const char *name

-The primary name of this algorithm.

-@item unsigned char *asnoid

-Array of bytes that form the ASN OID.

-@item int asnlen

-Length of bytes in `asnoid'.

-@item gcry_md_oid_spec_t *oids

-A list of OIDs that are to be associated with the algorithm.  The

-list's last element must have it's `oid' member set to NULL.  See

-below for an explanation of this type.  See below for an explanation

-of this type.

-@item int mdlen

-Length of the message digest algorithm.  See below for an explanation

-of this type.

-@item gcry_md_init_t init

-The function responsible for initializing a handle.  See below for an

-explanation of this type.

-@item gcry_md_write_t write

-The function responsible for writing data into a message digest

-context.  See below for an explanation of this type.

-@item gcry_md_final_t final

-The function responsible for `finalizing' a message digest context.

-See below for an explanation of this type.

-@item gcry_md_read_t read

-The function responsible for reading out a message digest result.  See

-below for an explanation of this type.

-@item size_t contextsize

-The size of the algorithm-specific `context', that should be

-allocated for each handle.

-@end table

-@end deftp

-

-@deftp {Data type} gcry_md_oid_spec_t

-This type is used for associating a user-provided algorithm

-implementation with certain OIDs.  It contains the following members:

-

-@table @code

-@item const char *oidstring

-Textual representation of the OID.

-@end table

-@end deftp

-

-@deftp {Data type} gcry_md_init_t

-Type for the `init' function, defined as: void (*gcry_md_init_t) (void

-*c)

-@end deftp

-

-@deftp {Data type} gcry_md_write_t

-Type for the `write' function, defined as: void (*gcry_md_write_t)

-(void *c, unsigned char *buf, size_t nbytes)

-@end deftp

-

-@deftp {Data type} gcry_md_final_t

-Type for the `final' function, defined as: void (*gcry_md_final_t)

-(void *c)

-@end deftp

-

-@deftp {Data type} gcry_md_read_t

-Type for the `read' function, defined as: unsigned char

-*(*gcry_md_read_t) (void *c)

-@end deftp

-

-@deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})

-

-Register a new digest module whose specification can be found in

-@var{digest}.  On success, a new algorithm ID is stored in

-@var{algorithm_id} and a pointer representing this module is stored

-in @var{module}.

-@end deftypefun

-

-@deftypefun void gcry_md_unregister (gcry_module_t @var{module})

-Unregister the digest identified by @var{module}, which must have been

-registered with gcry_md_register.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length})

-Get a list consisting of the IDs of the loaded message digest modules.

-If @var{list} is zero, write the number of loaded message digest

-modules to @var{list_length} and return.  If @var{list} is non-zero,

-the first *@var{list_length} algorithm IDs are stored in @var{list},

-which must be of according size.  In case there are less message

-digests modules than *@var{list_length}, *@var{list_length} is updated

-to the correct number.

-@end deftypefun

-

-@node Working with hash algorithms

-@section Working with hash algorithms

-

-To use most of these function it is necessary to create a context;

-this is done using:

-

-@deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})

-

-Create a message digest object for algorithm @var{algo}.  @var{flags}

-may be given as an bitwise OR of constants described below.  @var{algo}

-may be given as @code{0} if the algorithms to use are later set using

-@code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid

-handle or NULL.

-

-For a list of supported algorithms, see @xref{Available hash

-algorithms}.

-

-The flags allowed for @var{mode} are:

-

-@c begin table of hash flags

-@table @code

-@item GCRY_MD_FLAG_SECURE

-Allocate all buffers and the resulting digest in "secure memory".  Use

-this is the hashed data is highly confidential.

-

-@item GCRY_MD_FLAG_HMAC

-Turn the algorithm into a HMAC message authentication algorithm.  This

-does only work if just one algorithm is enabled for the handle and

-SHA-384 and SHA512 is not used.  Note that the function

-@code{gcry_md_setkey} must be used set the MAC key.  If you want CBC

-message authentication codes based on a cipher, see @xref{Working with

-cipher handles}.

-

-@end table

-@c begin table of hash flags

-

-You may use the function @code{gcry_md_is_enabled} to later check

-whether an algorithm has been enabled.

-

-@end deftypefun

-@c end function gcry_md_open

-

-If you want to calculate several hash algorithms at the same time, you

-have to use the following function right after the @code{gcry_md_open}:

-

-@deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})

-

-Add the message digest algorithm @var{algo} to the digest object

-described by handle @var{h}.  Duplicated enabling of algorithms is

-detected and ignored.

-@end deftypefun

-

-If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must

-be set using the function:

-

-@deftypefun gcry_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key}, size_t @var{keylen})

-

-For use with the HMAC feature, set the MAC key to the value of @var{key}

-of length @var{keylen}.

-@end deftypefun

-

-

-After you are done with the hash calculation, you should release the

-resources by using:

-

-@deftypefun void gcry_md_close (gcry_md_hd_t @var{h})

-

-Release all resources of hash context @var{h}.  @var{h} should not be

-used after a call to this function.  A @code{NULL} passed as @var{h} is

-ignored.

-

-@end deftypefun

-

-Often you have to do several hash operations using the same algorithm.

-To avoid the overhead of creating and releasing context, a reset function

-is provided:

-

-@deftypefun void gcry_md_reset (gcry_md_hd_t @var{h})

-

-Reset the current context to its initial state.  This is effectively

-identical to a close followed by an open and enabling all currently

-active algorithms.

-@end deftypefun

-

-

-Often it is necessary to start hashing some data and than continue to

-hash different data.  To avoid hashing the same data several times (which

-might not even be possible if the data is received from a pipe), a

-snapshot of the current hash context can be taken and turned into a new

-context:

-

-@deftypefun gcry_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src})

-

-Create a new digest object as an exact copy of the object described by

-handle @var{handle_src} and store it in @var{handle_dst}.  The context

-is not reset and you can continue to hash data using this context and

-independently using the original context.

-@end deftypefun

-

-

-Now that we have prepared everything to calculate hashes, its time to

-see how it is actually done.  There are 2  ways for this, one to

-update the hash with a block of memory and one macro to update the hash

-by just one character.  Both may be used intermixed.

-

-@deftypefun void gcry_md_write (gcry_md_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})

-

-Pass @var{length} bytes of the data in @var{buffer} to the digest object

-with handle @var{h} to update the digest values. This

-function should be used for large blocks of data.

-@end deftypefun

-

-@deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c})

-

-Pass the byte in @var{c} to the digest object with handle @var{h} to

-update the digest value.  This is an efficient function, implemented as

-a macro to buffer the data before an actual update. 

-@end deftypefun

-

-The semantics of the hash functions don't allow to read out intermediate

-message digests because the calculation must be finalized fist.  This

-finalization may for example include the number of bytes hashed in the

-message digest.  

-

-@deftypefun void gcry_md_final (gcry_md_hd_t @var{h})

-

-Finalize the message digest calculation.  This is not really needed

-because @code{gcry_md_read} does this implicitly.  After this has been

-done no further updates (by means of @code{gcry_md_write} or

-@code{gcry_md_putc} are allowed.  Only the first call to this function

-has an effect. It is implemented as a macro.

-@end deftypefun

-

-The way to read out the calculated message digest is by using the

-function:

-

-@deftypefun unsigned char *gcry_md_read (gcry_md_hd_t @var{h}, int @var{algo})

-

-@code{gcry_md_read} returns the message digest after finalizing the

-calculation.  This function may be used as often as required but it will

-always return the same value for one handle.  The returned message digest

-is allocated within the message context and therefore valid until the

-handle is released or reseted (using @code{gcry_md_close} or

-@code{gcry_md_reset}.  @var{algo} may be given as 0 to return the only

-enabled message digest or it may specify one of the enabled algorithms.

-The function does return @code{NULL} if the requested algorithm has not

-been enabled.

-@end deftypefun

-

-Because it is often necessary to get the message digest of one block of

-memory, a fast convenience function is available for this task: 

-

-@deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const cvoid *@var{buffer}, size_t @var{length});

-

-@code{gcry_md_hash_buffer} is a shortcut function to calculate a message

-digest of a buffer.  This function does not require a context and

-immediately returns the message digest of the @var{length} bytes at

-@var{buffer}.  @var{digest} must be allocated by the caller, large

-enough to hold the message digest yielded by the the specified algorithm

-@var{algo}.  This required size may be obtained by using the function

-@code{gcry_md_get_algo_dlen}.

-

-Note, that this function will abort the process if an unavailable

-algorithm is used.

-@end deftypefun

-

-@c ***********************************

-@c ***** MD info functions ***********

-@c ***********************************

-

-Hash algorithms are identified by internal algorithm numbers (see

-@code{gcry_md_open} for a list.  However, in most applications they are

-used by names, so 2 functions are available to map between string

-representations and hash algorithm identifiers.

-

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

-

-Map the digest algorithm id @var{algo} to a string representation of the

-algorithm name.  For unknown algorithms this functions returns an

-empty string.  This function should not be used to test for the

-availability of an algorithm.

-@end deftypefun

-

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

-

-Map the algorithm with @var{name} to a digest algorithm identifier.

-Returns 0 if the algorithm name is not known.  Names representing

-@acronym{ASN.1} object identifiers are recognized if the @acronym{IETF}

-dotted format is used and the OID is prefixed with either "@code{oid.}"

-or "@code{OID.}".  For a list of supported OIDs, see the source code at

-@file{cipher/md.c}. This function should not be used to test for the

-availability of an algorithm.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})

-

-Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the

-user allocated @var{buffer}. @var{length} must point to variable with

-the available size of @var{buffer} and receives after return the

-actual size of the returned OID.  The returned error code may be

-@code{GPG_ERR_TOO_SHORT} if the provided buffer is to short to receive

-the OID; it is possible to call the function with @code{NULL} for

-@var{buffer} to have it only return the required size.  The function

-returns 0 on success.

-

-@end deftypefun

-

-

-To test whether an algorithm is actually available for use, the

-following macro should be used:

-

-@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo}) 

-

-The macro returns 0 if the algorithm @var{algo} is available for use.

-@end deftypefun

-

-If the length of a message digest is not known, it can be retrieved

-using the following function:

-

-@deftypefun unsigned int gcry_md_get_algo_dlen (int @var{algo})

-

-Retrieve the length in bytes of the digest yielded by algorithm

-@var{algo}.  This is often used prior to @code{gcry_md_read} to allocate

-sufficient memory for the digest.

-@end deftypefun

-

-

-In some situations it might be hard to remember the algorithm used for

-the ongoing hashing. The following function might be used to get that

-information:

-

-@deftypefun int gcry_md_get_algo (gcry_md_hd_t @var{h})

-

-Retrieve the algorithm used with the handle @var{h}. Note, that this

-does not work reliable if more than one algorithm is enabled in @var{h}.

-@end deftypefun

-

-The following macro might also be useful:

-

-@deftypefun int gcry_md_is_secure (gcry_md_hd_t @var{h})

-

-This function returns true when the digest object @var{h} is allocated

-in "secure memory"; i.e. @var{h} was created with the

-@code{GCRY_MD_FLAG_SECURE}.

-@end deftypefun

-

-@deftypefun int gcry_md_is_enabled (gcry_md_hd_t @var{h}, int @var{algo})

-

-This function returns true when the algorithm @var{algo} has been

-enabled for the digest object @var{h}.

-@end deftypefun

-

-

-

-Tracking bugs related to hashing is often a cumbersome task which

-requires to add a lot of printf statements into the code.  @acronym{Libgcrypt}

-provides an easy way to avoid this.  The actual data hashed can be

-written to files on request.  The following 2 macros should be used to

-implement such a debugging facility:

-

-@deftypefun void gcry_md_start_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})

-

-Enable debugging for the digest object with handle @var{h}.  This

-creates create files named @file{dbgmd-<n>.<string>} while doing the

-actual hashing.  @var{suffix} is the string part in the filename.  The

-number is a counter incremented for each new hashing.  The data in the

-file is the raw data as passed to @code{gcry_md_write} or

-@code{gcry_md_putc}.

-@end deftypefun

-

-

-@deftypefun void gcry_md_stop_debug (gcry_md_hd_t @var{h}, int @var{reserved})

-

-Stop debugging on handle @var{h}.  @var{reserved} should be specified as

-0.  This function is usually not required because @code{gcry_md_close}

-does implicitly stop debugging.

-@end deftypefun

-

-

-@c **********************************************************

-@c *******************  Public Key  *************************

-@c **********************************************************

-@node Public Key cryptography (I)

-@chapter Public Key cryptography (I)

-

-Public key cryptography, also known as asymmetric cryptography, is an

-easy way for key management and to provide digital signatures.

-@acronym{Libgcrypt} provides two completely different interfaces to

-public key cryptography, this chapter explains the one based on

-S-expressions.

-

-@menu

-* Available algorithms::        Algorithms supported by the library.

-* Used S-expressions::          Introduction into the used S-expression.

-* Public key modules::          How to work with public key modules.

-* Cryptographic Functions::     Functions for performing the cryptographic actions.

-* General public-key related Functions::  General functions, not implementing any cryptography.

-@end menu

-

-@node Available algorithms

-@section Available algorithms

-

-@acronym{Libgcrypt} supports the RSA (Rivest-Shamir-Adleman) algorithms as well

-as DSA (Digital Signature Algorithm) and ElGamal.  The versatile

-interface allows to add more algorithms in the future.

-

-@node Used S-expressions

-@section Used S-expressions

-

-@acronym{Libgcrypt}'s API for asymmetric cryptography is based on data

-structures called S-expressions (see XXXX) and does not work with

-contexts as most of the other building blocks of @acronym{Libgcrypt}

-do.

-

-The following information are stored in S-expressions:

-

-@table @asis

-@item keys

-

-@item plain text data

-

-@item encrypted data

-

-@item signatures

-

-@end table

-

-@noindent

-To describe how @acronym{Libgcrypt} expect keys, we use some examples. Note that

-words in

-@ifnottex

-uppercase

-@end ifnottex

-@iftex

-italics

-@end iftex

-indicate parameters whereas lowercase words are literals.

-

-@example

-(private-key

-  (dsa

-    (p @var{p-mpi})

-    (q @var{q-mpi})

-    (g @var{g-mpi})

-    (y @var{y-mpi})

-    (x @var{x-mpi})))

-@end example

-

-@noindent

-This specifies a DSA private key with the following parameters:

-

-@table @var

-@item p-mpi

-DSA prime @math{p}.

-@item q-mpi

-DSA group order @math{q} (which is a prime divisor of @math{p-1}).

-@item g-mpi

-DSA group generator @math{g}.

-@item y-mpi

-DSA public key value @math{y = g^x \bmod p}.

-@item x-mpi

-DSA secret exponent x.

-@end table

-

-All the MPI values are  expected to be in @code{GCRYMPI_FMT_USG} format.

-The public key is similar with "private-key" replaced by "public-key"

-and no @var{x-mpi}.

-

-An easy way to create such an S-expressions is by using

-@code{gcry_sexp_build} which allows to pass a string with printf-like

-escapes to insert MPI values.

-

-@noindent

-Here is an example for an RSA key:

-

-@example

-(private-key

-  (rsa

-    (n @var{n-mpi})

-    (e @var{e-mpi})

-    (d @var{d-mpi})

-    (p @var{p-mpi})

-    (q @var{q-mpi})

-    (u @var{u-mpi})

-@end example

-

-@noindent

-with

-

-@table @var

-@item n-mpi

-RSA public modulus @math{n}.

-@item e-mpi

-RSA public exponent @math{e}.

-@item d-mpi

-RSA secret exponent @math{d = e^{-1} \bmod (p-1)(q-1)}.

-@item p-mpi

-RSA secret prime @math{p}.

-@item q-mpi

-RSA secret prime @math{q} with @math{q > p}.

-@item u-mpi

-multiplicative inverse @math{u = p^{-1} \bmod q}.

-@end table

-

-@node Public key modules

-@section Public key modules

-

-@acronym{Libgcrypt} makes it possible to load additional `public key

-modules'; these public key algorithms can be used just like the

-algorithms that are built into the library directly.  For an

-introduction into extension modules, see @xref{Modules}.

-

-@deftp {Data type} gcry_pk_spec_t

-This is the `module specification structure' needed for registering

-public key modules, which has to be filled in by the user before it

-can be used to register a module.  It contains the following members:

-

-@table @code

-@item const char *name

-The primary name of this algorithm.

-@item char **aliases

-A list of strings that are `aliases' for the algorithm.  The list

-must be terminated with a NULL element.

-@item const char *elements_pkey

-String containing the one-letter names of the MPI values contained in

-a public key.

-@item const char *element_skey

-String containing the one-letter names of the MPI values contained in

-a secret key.

-@item const char *elements_enc

-String containing the one-letter names of the MPI values that are the

-result of an encryption operation using this algorithm.

-@item const char *elements_sig

-String containing the one-letter names of the MPI values that are the

-result of a sign operation using this algorithm.

-@item const char *elements_grip

-String containing the one-letter names of the MPI values that are to

-be included in the `key grip'.

-@item int use

-The bitwise-OR of the following flags, depending on the abilities of

-the algorithm:

-@table @code

-@item GCRY_PK_USAGE_SIGN

-The algorithm supports signing and verifying of data.

-@item GCRY_PK_USAGE_ENCR

-The algorithm supports the encryption and decryption of data.

-@end table

-@item gcry_pk_generate_t generate

-The function responsible for generating a new key pair.  See below for

-a description of this type.

-@item gcry_pk_check_secret_key_t check_secret_key

-The function responsible for checking the sanity of a provided secret

-key.  See below for a description of this type.

-@item gcry_pk_encrypt_t encrypt

-The function responsible for encrypting data.  See below for a

-description of this type.

-@item gcry_pk_decrypt_t decrypt

-The function responsible for decrypting data.  See below for a

-description of this type.

-@item gcry_pk_sign_t sign

-The function responsible for signing data.  See below for a description

-of this type.

-@item gcry_pk_verify_t verify

-The function responsible for verifying that the provided signature

-matches the provided data.  See below for a description of this type.

-@item gcry_pk_get_nbits_t get_nbits

-The function responsible for returning the number of bits of a provided

-key.  See below for a description of this type.

-@end table

-@end deftp

-

-@deftp {Data type} gcry_pk_generate_t

-Type for the `generate' function, defined as: gcry_err_code_t

-(*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long

-use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors)

-@end deftp

-

-@deftp {Data type} gcry_pk_check_secret_key_t

-Type for the `check_secret_key' function, defined as: gcry_err_code_t

-(*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey)

-@end deftp

-

-@deftp {Data type} gcry_pk_encrypt_t

-Type for the `encrypt' function, defined as: gcry_err_code_t

-(*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,

-gcry_mpi_t *pkey, int flags)

-@end deftp

-

-@deftp {Data type} gcry_pk_decrypt_t

-Type for the `decrypt' function, defined as: gcry_err_code_t

-(*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data,

-gcry_mpi_t *skey, int flags)

-@end deftp

-

-@deftp {Data type} gcry_pk_sign_t

-Type for the `sign' function, defined as: gcry_err_code_t

-(*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,

-gcry_mpi_t *skey)

-@end deftp

-

-@deftp {Data type} gcry_pk_verify_t

-Type for the `verify' function, defined as: gcry_err_code_t

-(*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data,

-gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev)

-@end deftp

-

-@deftp {Data type} gcry_pk_get_nbits_t

-Type for the `get_nbits' function, defined as: unsigned

-(*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey)

-@end deftp

-

-@deftypefun gcry_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module})

-

-Register a new public key module whose specification can be found in

-@var{pubkey}.  On success, a new algorithm ID is stored in

-@var{algorithm_id} and a pointer representing this module is stored

-in @var{module}.

-@end deftypefun

-

-@deftypefun void gcry_pk_unregister (gcry_module_t @var{module})

-Unregister the public key module identified by @var{module}, which

-must have been registered with gcry_pk_register.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_pk_list (int *@var{list}, int *@var{list_length})

-Get a list consisting of the IDs of the loaded pubkey modules.  If

-@var{list} is zero, write the number of loaded pubkey modules to

-@var{list_length} and return.  If @var{list} is non-zero, the first

-*@var{list_length} algorithm IDs are stored in @var{list}, which must

-be of according size.  In case there are less pubkey modules than

-*@var{list_length}, *@var{list_length} is updated to the correct

-number.

-@end deftypefun

-

-@node Cryptographic Functions

-@section Cryptographic Functions

-

-@noindent

-Note, that we will in future allow to use keys without p,q and u

-specified and may also support other parameters for performance

-reasons. 

-

-@noindent

-

-Some functions operating on S-expressions support `flags', that

-influence the operation.  These flags have to be listed in a

-sub-S-expression named `flags'; the following flags are known:

-

-@table @var

-@item pkcs1

-Use PKCS#1 block type 2 padding.

-@item no-blinding

-Do not use a technique called `blinding', which is used by default in

-order to prevent leaking of secret information.  Blinding is only

-implemented by RSA, but it might be implemented by other algorithms in

-the future as well, when necessary.

-@end table

-

-@noindent

-Now that we know the key basics, we can carry on and explain how to

-encrypt and decrypt data.  In almost all cases the data is a random

-session key which is in turn used for the actual encryption of the real

-data.  There are 2 functions to do this:

-

-@deftypefun gcry_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}})

-

-Obviously a public key must be provided for encryption.  It is

-expected as an appropriate S-expression (see above) in @var{pkey}.

-The data to be encrypted can either be in the simple old format, which

-is a very simple S-expression consisting only of one MPI, or it may be

-a more complex S-expression which also allows to specify flags for

-operation, like e.g. padding rules.

-

-@noindent

-If you don't want to let @acronym{Libgcrypt} handle the padding, you must pass an

-appropriate MPI using this expression for @var{data}:

-

-@example 

-(data

-  (flags raw)

-  (value @var{mpi}))

-@end example

-

-@noindent

-This has the same semantics as the old style MPI only way.  @var{MPI} is

-the actual data, already padded appropriate for your protocol.  Most

-systems however use PKCS#1 padding and so you can use this S-expression

-for @var{data}:

-

-@example 

-(data

-  (flags pkcs1)

-  (value @var{block}))

-@end example

-

-@noindent

-Here, the "flags" list has the "pkcs1" flag which let the function know

-that it should provide PKCS#1 block type 2 padding.  The actual data to

-be encrypted is passed as a string of octets in @var{block}.  The

-function checks that this data actually can be used with the given key,

-does the padding and encrypts it.

-

-If the function could successfully perform the encryption, the return

-value will be 0 and a a new S-expression with the encrypted result is

-allocated and assign to the variable at the address of @var{r_ciph}.

-The caller is responsible to release this value using

-@code{gcry_sexp_release}.  In case of an error, an error code is

-returned and @var{r_ciph} will be set to @code{NULL}.

-

-@noindent

-The returned S-expression has this format when used with RSA:

-

-@example

-(enc-val

-  (rsa

-    (a @var{a-mpi})))

-@end example

-

-@noindent

-Where @var{a-mpi} is an MPI with the result of the RSA operation.  When

-using the ElGamal algorithm, the return value will have this format:

-

-@example

-(enc-val

-  (elg

-    (a @var{a-mpi})

-    (b @var{b-mpi})))

-@end example

-

-@noindent

-Where @var{a-mpi} and @var{b-mpi} are MPIs with the result of the

-ElGamal encryption operation.

-@end deftypefun

-@c end gcry_pk_encrypt

-

-@deftypefun gcry_error_t gcry_pk_decrypt (@w{gcry_sexp_t *@var{r_plain},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})

-

-Obviously a private key must be provided for decryption.  It is expected

-as an appropriate S-expression (see above) in @var{skey}.  The data to

-be decrypted must match the format of the result as returned by

-@code{gcry_pk_encrypt}, but should be enlarged with a @code{flags}

-element:

-

-@example

-(enc-val

-  (flags)

-  (elg

-    (a @var{a-mpi})

-    (b @var{b-mpi})))

-@end example

-

-@noindent

-Note, that this function currently does not know of any padding

-methods and the caller must do any un-padding on his own.

-

-@noindent

-The function returns 0 on success or an error code.  The variable at the

-address of @var{r_plain} will be set to NULL on error or receive the

-decrypted value on success.  The format of @var{r_plain} is a

-simple S-expression part (i.e. not a valid one) with just one MPI if

-there was no @code{flags} element in @var{data}; if at least an empty

-@code{flags} is passed in @var{data}, the format is:

-

-@example

-(value @var{plaintext})

-@end example

-@end deftypefun

-@c end gcry_pk_decrypt

-

-

-Another operation commonly performed using public key cryptography is

-signing data.  In some sense this is even more important than

-encryption because digital signatures are an important instrument for

-key management.  @acronym{Libgcrypt} supports digital signatures using

-2 functions, similar to the encryption functions:

-

-@deftypefun gcry_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})

-

-This function creates a digital signature for @var{data} using the

-private key @var{skey} and place it into the variable at the address of

-@var{r_sig}.  @var{data} may either be the simple old style S-expression

-with just one MPI or a modern and more versatile S-expression which

-allows to let @acronym{Libgcrypt} handle padding:

-

-@example 

- (data

-  (flags pkcs1)

-  (hash @var{hash-algo} @var{block}))

-@end example

-

-@noindent

-This example requests to sign the data in @var{block} after applying

-PKCS#1 block type 1 style padding.  @var{hash-algo} is a string with the

-hash algorithm to be encoded into the signature, this may be any hash

-algorithm name as supported by @acronym{Libgcrypt}.  Most likely, this will be

-"sha1", "rmd160" or "md5".  It is obvious that the length of @var{block}

-must match the size of that message digests; the function checks that

-this and other constraints are valid.

-

-@noindent

-If PKCS#1 padding is not required (because the caller does already

-provide a padded value), either the old format or better the following

-format should be used:

-

-@example

-(data

-  (flags raw)

-  (value @var{mpi}))

-@end example

-

-@noindent

-Here, the data to be signed is directly given as an @var{MPI}.

-

-@noindent

-The signature is returned as a newly allocated S-expression in

-@var{r_sig} using this format for RSA:

-

-@example

-(sig-val

-  (rsa

-    (s @var{s-mpi})))

-@end example

-

-Where @var{s-mpi} is the result of the RSA sign operation.  For DSA the

-S-expression returned is:

-

-@example

-(sig-val

-  (dsa

-    (r @var{r-mpi})

-    (s @var{s-mpi})))

-@end example

-

-Where @var{r-mpi} and @var{s-mpi} are the result of the DSA sign

-operation.  For ElGamal signing (which is slow, yields large numbers

-and probably is not as secure as the other algorithms), the same format is

-used with "elg" replacing "dsa".

-@end deftypefun

-@c end gcry_pk_sign

-

-@noindent

-The operation most commonly used is definitely the verification of a

-signature.  @acronym{Libgcrypt} provides this function:

-

-@deftypefun gcry_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})

-

-This is used to check whether the signature @var{sig} matches the

-@var{data}.  The public key @var{pkey} must be provided to perform this

-verification.  This function is similar in its parameters to

-@code{gcry_pk_sign} with the exceptions that the public key is used

-instead of the private key and that no signature is created but a

-signature, in a format as created by @code{gcry_pk_sign}, is passed to

-the function in @var{sig}.

-

-@noindent

-The result is 0 for success (i.e. the data matches the signature), or an

-error code where the most relevant code is @code{GCRYERR_BAD_SIGNATURE}

-to indicate that the signature does not match the provided data.

-

-@end deftypefun

-@c end gcry_pk_verify

-

-@node General public-key related Functions

-@section General public-key related Functions

-

-@noindent

-A couple of utility functions are available to retrieve the length of

-the key, map algorithm identifiers and perform sanity checks:

-

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

-

-Map the public key algorithm id @var{algo} to a string representation of

-the algorithm name.  For unknown algorithms this functions returns an

-empty string.

-@end deftypefun

-

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

-

-Map the algorithm @var{name} to a public key algorithm Id.  Returns 0 if

-the algorithm name is not known.

-@end deftypefun

-

-@deftypefun int gcry_pk_test_algo (int @var{algo})

-

-Return 0 if the public key algorithm @var{algo} is available for use.

-Note, that this is implemented as a macro.

-@end deftypefun

-

-

-@deftypefun {unsigned int} gcry_pk_get_nbits (gcry_sexp_t @var{key})

-

-Return what is commonly referred as the key length for the given

-public or private in @var{key}.

-@end deftypefun

-

-@deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{gcry_sexp_t @var{key}}, @w{unsigned char *@var{array}})

-

-Return the so called "keygrip" which is the SHA-1 hash of the public key

-parameters expressed in a way depended on the algorithm.  @var{array}

-must either provide space for 20 bytes or @code{NULL;}. In the latter

-case a newly allocated array of that size is returned.  On success a

-pointer to the newly allocated space or to @var{array} is returned.

-@code{NULL} is returned to indicate an error which is most likely an unknown

-algorithm or one where a "keygrip" has not yet been defined.

-The function accepts public or secret keys in @var{key}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key})

-

-Return zero if the private key @var{key} is `sane', an error code otherwise.

-Note, that it is not possible to chek the `saneness' of a public key.

-

-@end deftypefun

-

-

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

-

-Depending on the value of @var{what} return various information about

-the public key algorithm with the id @var{algo}.  Note, that the

-function returns @code{-1} on error and the actual error code must be

-retrieved using the function @code{gcry_errno}.  The currently defined

-values for @var{what} are:

-

-@table @code

-@item GCRYCTL_TEST_ALGO:

-Return 0 when the specified algorithm is available for use.

-@var{buffer} must be @code{NULL}, @var{nbytes} may be passed as

-@code{NULL} or point to a variable with the required usage of the

-algorithm. This may be 0 for "don't care" or the bit-wise OR of these

-flags:

-

-@table @code

-@item GCRY_PK_USAGE_SIGN 

-Algorithm is usable for signing.

-@item GCRY_PK_USAGE_ENCR 

-Algorithm is usable for encryption.

-@end table

-

-@item GCRYCTL_GET_ALGO_USAGE:

-Return the usage flags for the given algorithm.  An invalid algorithm

-return 0.  Disabled algorithms are ignored here because we

-want to know whether the algorithm is at all capable of a certain usage.

-

-@item GCRYCTL_GET_ALGO_NPKEY

-Return the number of elements the public key for algorithm @var{algo}

-consist of.  Return 0 for an unknown algorithm.

-

-@item GCRYCTL_GET_ALGO_NSKEY

-Return the number of elements the private key for algorithm @var{algo}

-consist of.  Note that this value is always larger than that of the

-public key.  Return 0 for an unknown algorithm.

-

-@item GCRYCTL_GET_ALGO_NSIGN

-Return the number of elements a signature created with the algorithm

-@var{algo} consists of.  Return 0 for an unknown algorithm or for an

-algorithm not capable of creating signatures.

-

-@item GCRYCTL_GET_ALGO_NENC

-Return the number of elements a encrypted message created with the algorithm

-@var{algo} consists of.  Return 0 for an unknown algorithm or for an

-algorithm not capable of encryption.

-@end table

-

-@noindent

-Please note that parameters not required should be passed as @code{NULL}.

-@end deftypefun

-@c end gcry_pk_algo_info

-

-

-@deftypefun gcry_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})

-

-This is a general purpose function to perform certain control

-operations.  @var{cmd} controls what is to be done. The return value is

-0 for success or an error code.  Currently supported values for

-@var{cmd} are:

-

-@table @code

-@item GCRYCTL_DISABLE_ALGO

-Disable the algorithm given as an algorithm id in @var{buffer}.

-@var{buffer} must point to an @code{int} variable with the algorithm id

-and @var{buflen} must have the value @code{sizeof (int)}.

-

-@end table

-@end deftypefun

-@c end gcry_pk_ctl

-

-@noindent

-@acronym{Libgcrypt} also provides a function for generating public key

-pairs:

-

-@deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})

-

-This function create a new public key pair using information given in

-the S-expression @var{parms} and stores the private and the public key

-in one new S-expression at the address given by @var{r_key}.  In case of

-an error, @var{r_key} is set to @code{NULL}.  The return code is 0 for

-success or an error code otherwise.

-

-@noindent

-Here is an example for @var{parms} for creating a 1024 bit RSA key:

-

-@example

-(genkey

-  (rsa

-    (nbits 4:1024)))

-@end example

-

-@noindent

-To create an ElGamal key, substitute "elg" for "rsa" and to create a DSA

-key use "dsa".  Valid ranges for the key length depend on the

-algorithms; all commonly used key lengths are supported.  Currently

-supported parameters are:

-

-@table @code

-@item nbits

-This is always required to specify the length of the key.  The argument

-is a string with a number in C-notation.

-

-@item rsa-use-e

-This is only used with RSA to give a hint for the public exponent. The

-value will be used as a base to test for a usable exponent. Some values

-are special:

-

-@table @samp

-@item 0

-Use a secure and fast value.  This is currently the number 41.

-@item 1

-Use a secure value as required by some specification.  This is currently

-the number 65537.

-@item 2

-Reserved

-@end table

-

-@noindent

-If this parameter is not used, @acronym{Libgcrypt} uses for historic reasons

-65537.

-

-@end table

-@c end table of parameters

-

-@noindent

-The key pair is returned in a format depending on the algorithm.  Both

-private and public keys are returned in one container and may be

-accompanied by some miscellaneous information.

-

-@noindent

-As an example, here is what the ElGamal key generation returns:

-

-@example

-(key-data

-  (public-key

-    (elg

-      (p @var{p-mpi})

-      (g @var{g-mpi})

-      (y @var{y-mpi})))

-  (private-key

-    (elg

-      (p @var{p-mpi})

-      (g @var{g-mpi})

-      (y @var{y-mpi})

-      (x @var{x-mpi})))

-  (misc-key-info

-    (pm1-factors @var{n1 n2 ... nn})))

-@end example

-

-@noindent

-As you can see, some of the information is duplicated, but this provides

-an easy way to extract either the public or the private key.  Note that

-the order of the elements is not defined, e.g. the private key may be

-stored before the public key. @var{n1 n2 ... nn} is a list of prime

-numbers used to composite @var{p-mpi}; this is in general not a very

-useful information.

-@end deftypefun

-@c end gcry_pk_genkey

-

-@node Public Key cryptography (II)

-@chapter Public Key cryptography (II)

-

-This chapter documents the alternative interface to asymmetric

-cryptography (ac) that is not based on S-expressions, but on native C

-data structures.  As opposed to the pk interface described in the

-former chapter, this one follows an open/use/close paradigm like other

-building blocks of the library.

-

-@menu

-* Available asymmetric algorithms::  List of algorithms supported by the library.

-* Working with sets of data::   How to work with sets of data.

-* Working with handles::        How to use handles.

-* Working with keys::           How to work with keys.

-* Using cryptographic functions::  How to perform cryptographic operations.

-* Handle-independent functions::  General functions independent of handles.

-@end menu

-

-@node Available asymmetric algorithms

-@section Available asymmetric algorithms

-

-@acronym{Libgcrypt} supports the RSA (Rivest-Shamir-Adleman)

-algorithms as well as DSA (Digital Signature Algorithm) and ElGamal.

-The versatile interface allows to add more algorithms in the future.

-

-@deftp {Data type} gcry_ac_id_t

-

-The following constants are defined for this type:

-

-@table @code

-@item GCRY_AC_RSA

-Riven-Shamir-Adleman

-@item GCRY_AC_DSA

-Digital Signature Algorithm

-@item GCRY_AC_ELG

-ElGamal

-@item GCRY_AC_ELG_E

-ElGamal, encryption only.

-@end table

-@end deftp

-

-@node Working with sets of data

-@section Working with sets of data

-

-In the context of this interface the term `data set' refers to a list

-of `named MPI values' that is used by functions performing

-cryptographic operations.

-

-Such data sets are used for representing keys, since keys simply

-consist of a variable amount of numbers.  Furthermore some functions

-return data sets to the caller that are to be provided to other

-functions.

-

-This section documents the data types, symbols and functions that are

-relevant for working with such data sets.

-

-@deftp {Data type} gcry_ac_data_t

-A data set, that is simply a list of named MPI values.

-@end deftp

-

-The following flags are supported:

-

-@table @code

-@item GCRY_AC_FLAG_DEALLOC

-Used for storing data in a data set.  If given, the data will be

-released by the library.

-

-@item GCRY_AC_FLAG_COPY

-Used for storing/retrieving data in/from a data set.  If given, the

-library will create copies of the provided/contained data, which will

-then be given to the user/associated with the data set.

-@end table

-

-@deftypefun gcry_error_t gcry_ac_data_new (gcry_ac_data_t *@var{data})

-Creates a new, empty data set and stores it in @var{data}.

-@end deftypefun

-

-@deftypefun void gcry_ac_data_destroy (gcry_ac_data_t @var{data})

-Destroys the data set @var{data}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_data_set (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t @var{mpi})

-Add the value @var{mpi} to @var{data} with the label @var{name}.  If

-@var{flags} contains GCRY_AC_FLAG_DATA_COPY, the data set will contain

-copies of @var{name} and @var{mpi}.  If @var{flags} contains

-GCRY_AC_FLAG_DATA_DEALLOC or GCRY_AC_FLAG_DATA_COPY, the values

-contained in the data set will be deallocated when they are to be

-removed from the data set.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data})

-Create a copy of the data set @var{data} and store it in @var{data_cp}.

-@end deftypefun

-

-@deftypefun unsigned int gcry_ac_data_length (gcry_ac_data_t @var{data})

-Returns the number of named MPI values inside of the data set

-@var{data}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t *@var{mpi})

-Store the value labelled with @var{name} found in @var{data} in

-@var{mpi}.  If @var{flags} contains GCRY_AC_FLAG_COPY, store a copy of

-the @var{mpi} value contained in the data set.  @var{mpi} may be NULL.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t @var{data}, unsigned int flags, unsigned int @var{index}, const char **@var{name}, gcry_mpi_t *@var{mpi})

-Stores in @var{name} and @var{mpi} the named @var{mpi} value contained

-in the data set @var{data} with the index @var{idx}.  If @var{flags}

-contains GCRY_AC_FLAG_COPY, store copies of the values contained in

-the data set. @var{name} or @var{mpi} may be NULL.

-@end deftypefun

-

-@deftypefun void gcry_ac_data_clear (gcry_ac_data_t @var{data})

-Destroys any values contained in the data set @var{data}.

-@end deftypefun

-

-@node Working with handles

-@section Working with handles

-

-In order to use an algorithm, an according handle must be created.

-This is done using the following function:

-

-@deftypefun gcry_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle}, int @var{algorithm}, int @var{flags})

-

-Creates a new handle for the algorithm @var{algorithm} and stores it

-in @var{handle}.  @var{flags} is not used yet.

-

-@var{algorithm} must be a valid algorithm ID, see @xref{Available

-algorithms}, for a list of supported algorithms and the according

-constants.  Besides using the listed constants directly, the functions

-@code{gcry_ac_name_to_id} may be used to convert the textual name of

-an algorithm into the according numeric ID.

-@end deftypefun

-

-@deftypefun void gcry_ac_close (gcry_ac_handle_t @var{handle})

-Destroys the handle @var{handle}.

-@end deftypefun

-

-@node Working with keys

-@section Working with keys

-

-@deftp {Data type} gcry_ac_key_type_t

-Defined constants:

-

-@table @code

-@item GCRY_AC_KEY_TYPE_SECRET

-Specifies a secret key.

-@item GCRY_AC_KEY_TYPE_PUBLIC

-Specifies a public key.

-@end table

-@end deftp

-

-@deftp {Data type} gcry_ac_key_t

-This type represents a single `key', either a secret one or a public

-one.

-@end deftp

-

-@deftp {Data type} gcry_ac_key_pair_t

-This type represents a `key pair' containing a secret and a public key.

-@end deftp

-

-Key data structures can be created in two different ways; a new key

-pair can be generated, resulting in ready-to-use key.  Alternatively a

-key can be initialized from a given data set.

-

-@deftypefun gcry_error_t gcry_ac_key_init (gcry_ac_key_t *@var{key}, gcry_ac_handle_t @var{handle}, gcry_ac_key_type_t @var{type}, gcry_ac_data_t @var{data})

-Creates a new key of type @var{type}, consisting of the MPI values

-contained in the data set @var{data} and stores it in @var{key}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t @var{handle}, unsigned int @var{nbits}, void *@var{key_spec}, gcry_ac_key_pair_t *@var{key_pair}, gcry_mpi_t **@var{misc_data})

-

-Generates a new key pair via the handle @var{handle} of @var{NBITS}

-bits and stores it in @var{key_pair}.

-

-In case non-standard settings are wanted, a pointer to a structure of

-type @code{gcry_ac_key_spec_<algorithm>_t}, matching the selected

-algorithm, can be given as @var{key_spec}.  @var{misc_data} is not

-used yet.  Such a structure does only exist for RSA.  A descriptions

-of the members of the supported structures follows.

-

-@table @code

-@item gcry_ac_key_spec_rsa_t

-@table @code

-@item gcry_mpi_t e

-Generate the key pair using a special @code{e}.  The value of @code{e}

-has the following meanings:

-@table @code

-@item = 0

-Let @acronym{Libgcrypt} device what exponent should be used.

-@item = 1

-Request the use of a ``secure'' exponent; this is required by some

-specification to be 65537.

-@item > 2

-Try starting at this value until a working exponent is found.  Note,

-that the current implementation leaks some information about the

-private key because the incrementation used is not randomized.  Thus,

-this function will be changed in the future to return a random

-exponent of the given size.

-@end table

-@end table

-@end table

-

-Example code:

-@example

-@{

-  gcry_ac_key_pair_t key_pair;

-  gcry_ac_key_spec_rsa  rsa_spec;

-

-  rsa_spec.e = gcry_mpi_new (0);

-  gcry_mpi_set_ui (rsa_spec.e, 1)

-

-  err = gcry_ac_open  (&handle, GCRY_AC_RSA, 0);

-  assert (! err);

-

-  err = gcry_ac_key_pair_generate (handle, &key_pair, 1024, (void *) &rsa_spec);

-  assert (! err);

-@}

-@end example

-@end deftypefun

-

-

-@deftypefun gcry_ac_key_t gcry_ac_key_pair_extract (gcry_ac_key_pair_t @var{key_pair}, gcry_ac_key_type_t @var{which})

-Returns the key of type @var{which} out of the key pair

-@var{key_pair}.

-@end deftypefun

-

-@deftypefun void gcry_ac_key_destroy (gcry_ac_key_t @var{key})

-Destroys the key @var{key}.

-@end deftypefun

-

-@deftypefun void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t @var{key_pair})

-Destroys the key pair @var{key_pair}.

-@end deftypefun

-

-@deftypefun gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t @var{key})

-Returns the data set contained in the key @var{key}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_key_test (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key})

-Verifies that the private key @var{key} is sane via @var{handle}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned int *@var{nbits})

-Stores the number of bits of the key @var{key} in @var{nbits} via @var{handle}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned char *@var{key_grip})

-Writes the 20 byte long key grip of the key @var{key} to

-@var{key_grip} via @var{handle}.

-@end deftypefun

-

-@node Using cryptographic functions

-@section Using cryptographic functions

-

-The following flags might be relevant:

-

-@table @code

-@item GCRY_AC_FLAG_NO_BLINDING

-Disable any blinding, which might be supported by the chosen

-algorithm; blinding is the default.

-@end table

-

-@deftypefun gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data_plain}, gcry_ac_data_t **@var{data_encrypted})

-Encrypts the plain text MPI value @var{data_plain} with the key public

-@var{key} under the control of the flags @var{flags} and stores the

-resulting data set into @var{data_encrypted}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t *@var{data_plain}, gcry_ac_data_t @var{data_encrypted})

-Decrypts the encrypted data contained in the data set

-@var{data_encrypted} with the secret key KEY under the control of the

-flags @var{flags} and stores the resulting plain text MPI value in

-@var{DATA_PLAIN}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t *@var{data_signature})

-Signs the data contained in @var{data} with the secret key @var{key}

-and stores the resulting signature in the data set

-@var{data_signature}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t @var{data_signature})

-Verifies that the signature contained in the data set

-@var{data_signature} is indeed the result of signing the data

-contained in @var{data} with the secret key belonging to the public

-key @var{key}.

-@end deftypefun

-

-@node Handle-independent functions

-@section Handle-independent functions

-

-@deftypefun gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t @var{algorithm}, const char **@var{name})

-Stores the textual representation of the algorithm whose id is given

-in @var{algorithm} in @var{name}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_ac_name_to_id (const char *@var{name}, gcry_ac_id_t *@var{algorithm})

-Stores the numeric ID of the algorithm whose textual representation is

-contained in @var{name} in @var{algorithm}.

-@end deftypefun

-

-@c **********************************************************

-@c *******************  Random  *****************************

-@c **********************************************************

-@node Random Numbers

-@chapter Random Numbers

-

-@menu

-* Quality of random numbers::   @acronym{Libgcrypt} uses different quality levels.

-* Retrieving random numbers::   How to retrieve random numbers.

-@end menu

-

-@node Quality of random numbers

-@section Quality of random numbers

-

-@acronym{Libgcypt} offers random numbers of different quality levels:

-

-@deftp {Data type} enum gcry_random_level

-The constants for the random quality levels are of this type.

-@end deftp

-

-@table @code

-@item GCRY_WEAK_RANDOM

-This should not anymore be used.  It has recently been changed to an

-alias of GCRY_STRONG_RANDOM.  Use @code{gcry_create_nonce} instead.

-@item GCRY_STRONG_RANDOM

-Use this level for e.g. session keys and similar purposes.

-@item GCRY_VERY_STRONG_RANDOM

-Use this level for e.g. key material.

-@end table

-

-@node Retrieving random numbers

-@section Retrieving 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 function

-differs from @code{gcry_random_bytes} in that the returned buffer is

-allocated in a ``secure'' area of the memory.

-@end deftypefun

-

-@deftypefun void gcry_create_nonce (void *@var{buffer}, size_t @var{length})

-

-Fill @var{buffer} with @var{length} unpredictable bytes.  This is

-commonly called a nonce and may also be used for initialization

-vectors and padding.  This is an extra function nearly independent of

-the other random function for 3 reasons: It better protects the

-regular random generator's internal state, provides better performance

-and does not drain the precious entropy pool.

-

-@end deftypefun

-

-

-

-@c **********************************************************

-@c *******************  S-Expressions ***********************

-@c **********************************************************

-@node S-expressions

-@chapter S-expressions

-

-S-expressions are used by the public key functions to pass complex data

-structures around.  These LISP like objects are used by some

-cryptographic protocols (cf. RFC-2692) and @acronym{Libgcrypt} provides functions

-to parse and construct them.  For detailed information, see

-@cite{Ron Rivest, code and description of S-expressions,

-@uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}.

-

-@menu

-* Data types for S-expressions::  Data types related with S-expressions.

-* Working with S-expressions::  How to work with S-expressions.

-@end menu

-

-@node Data types for S-expressions

-@section Data types for S-expressions

-

-@deftp {Data type} gcry_sexp_t

-The @code{gcry_sexp_t} type describes an object with the @acronym{Libgcrypt} internal

-representation of an S-expression.

-@end deftp

-

-@node Working with S-expressions

-@section Working with S-expressions

-

-@noindent

-There are several functions to create an @acronym{Libgcrypt} S-expression object

-from its external representation or from a string template.  There is

-also a function to convert the internal representation back into one of

-the external formats:

-

-

-@deftypefun gcry_error_t gcry_sexp_new (@w{gcry_sexp_t *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}})

-

-This is the generic function to create an new S-expression object from

-its external representation in @var{buffer} of @var{length} bytes.  On

-success the result is stored at the address given by @var{r_sexp}. 

-With @var{autodetect} set to 0, the data in @var{buffer} is expected to

-be in canonized format, with @var{autodetect} set to 1 the parses any of

-the defined external formats.  If @var{buffer} does not hold a valid

-S-expression an error code is returned and @var{r_sexp} set to

-@code{NULL}.

-Note, that the caller is responsible for releasing the newly allocated

-S-expression using @code{gcry_sexp_release}.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_sexp_create (@w{gcry_sexp_t *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)})

-

-This function is identical to @code{gcry_sexp_new} but has an extra

-argument @var{freefnc}, which, when not set to @code{NULL}, is expected

-to be a function to release the @var{buffer}; most likely the standard

-@code{free} function is used for this argument.  This has the effect of

-transferring the ownership of @var{buffer} to the created object in

-@var{r_sexp}.  The advantage of using this function is that @acronym{Libgcrypt}

-might decide to directly use the provided buffer and thus avoid extra

-copying.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_sexp_sscan (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})

-

-This is another variant of the above functions.  It behaves nearly

-identical but provides an @var{erroff} argument which will receive the

-offset into the buffer where the parsing stopped on error.

-@end deftypefun

-

-@deftypefun gcry_error_t gcry_sexp_build (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...})

-

-This function creates an internal S-expression from the string template

-@var{format} and stores it at the address of @var{r_sexp}. If there is a

-parsing error, the function returns an appropriate error code and stores

-the offset into @var{format} where the parsing stopped in @var{erroff}.

-The function supports a couple of printf-like formatting characters and

-expects arguments for some of these escape sequences right after

-@var{format}.  The following format characters are defined:

-

-@table @samp

-@item %m

-The next argument is expected to be of type @code{gcry_mpi_t} and a copy of

-its value is inserted into the resulting S-expression.

-@item %s

-The next argument is expected to be of type @code{char *} and that

-string is inserted into the resulting S-expression.

-@item %d

-The next argument is expected to be of type @code{int} and its 

-value ist inserted into the resulting S-expression.

-@item %b

-The next argument is expected to be of type @code{int} directly

-followed by an argument of type @code{char *}.  This represents a

-buffer of given length to be inserted into the resulting regular

-expression.

-@end table

-

-@noindent

-No other format characters are defined and would return an error.  Note,

-that the format character @samp{%%} does not exists, because a percent

-sign is not a valid character in an S-expression.

-@end deftypefun

-

-@deftypefun void gcry_sexp_release (@w{gcry_sexp_t @var{sexp}})

-

-Release the S-expression object @var{sexp}.

-@end deftypefun

-

-

-@noindent

-The next 2 functions are used to convert the internal representation

-back into a regular external S-expression format and to show the

-structure for debugging.

-

-@deftypefun size_t gcry_sexp_sprint (@w{gcry_sexp_t @var{sexp}}, @w{int @var{mode}}, @w{void *@var{buffer}}, @w{size_t @var{maxlength}})

-

-Copies the S-expression object @var{sexp} into @var{buffer} using the

-format specified in @var{mode}.  @var{maxlength} must be set to the

-allocated length of @var{buffer}.  The function returns the actual

-length of valid bytes put into @var{buffer} or 0 if the provided buffer

-is too short.  Passing @code{NULL} for @var{buffer} returns the required

-length for @var{buffer}.  For convenience reasons an extra byte with

-value 0 is appended to the buffer.

-

-@noindent

-The following formats are supported:

-

-@table @code

-@item GCRYSEXP_FMT_DEFAULT

-Returns a convenient external S-expression representation.

-

-@item GCRYSEXP_FMT_CANON

-Return the S-expression in canonical format.

-

-@item GCRYSEXP_FMT_BASE64

-Not currently supported.

-

-@item GCRYSEXP_FMT_ADVANCED

-Returns the S-expression in advanced format.

-@end table

-@end deftypefun

-

-@deftypefun void gcry_sexp_dump (@w{gcry_sexp_t @var{sexp}})

-

-Dumps @var{sexp} in a format suitable for debugging to @acronym{Libgcrypt}'s

-logging stream.

-@end deftypefun

-

-@noindent

-Often canonical encoding is used in the external representation.  The

-following function can be used to check for valid encoding and to learn

-the length of the S-expression"

-

-@deftypefun size_t gcry_sexp_canon_len (@w{const unsigned char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{erroff}}, @w{int *@var{errcode}})

-

-Scan the canonical encoded @var{buffer} with implicit length values and

-return the actual length this S-expression uses.  For a valid S-expression

-it should never return 0.  If @var{length} is not 0, the maximum

-length to scan is given; this can be used for syntax checks of

-data passed from outside.  @var{errcode} and @var{erroff} may both be

-passed as @code{NULL}.

-

-@end deftypefun

-

-

-@noindent

-There are a couple of functions to parse S-expressions and retrieve

-elements:

-

-@deftypefun gcry_sexp_t gcry_sexp_find_token (@w{const gcry_sexp_t @var{list}}, @w{const char *@var{token}}, @w{size_t @var{toklen}})

-

-Scan the S-expression for a sublist with a type (the car of the list)

-matching the string @var{token}.  If @var{toklen} is not 0, the token is

-assumed to be raw memory of this length.  The function returns a newly

-allocated S-expression consisting of the found sublist or @code{NULL}

-when not found.

-@end deftypefun

-

-

-@deftypefun int gcry_sexp_length (@w{const gcry_sexp_t @var{list}})

-

-Return the length of the @var{list}.  For a valid S-expression this

-should be at least 1.

-@end deftypefun

-

-

-@deftypefun gcry_sexp_t gcry_sexp_nth (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}})

-

-Create and return a new S-expression from the element with index @var{number} in

-@var{list}.  Note that the first element has the index 0.  If there is

-no such element, @code{NULL} is returned.

-@end deftypefun

-

-@deftypefun gcry_sexp_t gcry_sexp_car (@w{const gcry_sexp_t @var{list}})

-

-Create and return a new S-expression from the first element in

-@var{list}; this called the "type" and should always exist and be a

-string. @code{NULL} is returned in case of a problem.

-@end deftypefun

-

-@deftypefun gcry_sexp_t gcry_sexp_cdr (@w{const gcry_sexp_t @var{list}})

-

-Create and return a new list form all elements except for the first one.

-Note, that this function may return an invalid S-expression because it

-is not guaranteed, that the type exists and is a string.  However, for

-parsing a complex S-expression it might be useful for intermediate

-lists.  Returns @code{NULL} on error.

-@end deftypefun

-

-

-@deftypefun {const char *} gcry_sexp_nth_data (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{size_t *@var{datalen}})

-

-This function is used to get data from a @var{list}.  A pointer to the

-actual data with index @var{number} is returned and the length of this

-data will be stored to @var{datalen}.  If there is no data at the given

-index or the index represents another list, @code{NULL} is returned.

-@strong{Take care:} The returned pointer is valid as long as @var{list} is

-not modified or released.

-

-@noindent

-Here is an example on how to extract and print the surname (Meier) from

-the S-expression @samp{(Name Otto Meier (address Burgplatz 3))}:

-

-@example

-size_t len;

-const char *name;

-

-name = gcry_sexp_nth_data (list, 2, &len);

-printf ("my name is %.*s\n", (int)len, name);

-@end example

-@end deftypefun

-

-@deftypefun gcry_mpi_t gcry_sexp_nth_mpi (@w{gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{int @var{mpifmt}})

-

-This function is used to get and convert data from a @var{list}. This

-data is assumed to be an MPI stored in the format described by

-@var{mpifmt} and returned as a standard @acronym{Libgcrypt} MPI.  The caller must

-release this returned value using @code{gcry_mpi_release}.  If there is

-no data at the given index, the index represents a list or the value

-can't be converted to an MPI, @code{NULL} is returned.

-@end deftypefun

-

-

-@c **********************************************************

-@c *******************  MPIs ******** ***********************

-@c **********************************************************

-@node MPI library

-@chapter MPI library

-

-@menu

-* Data types::                  MPI related data types.

-* Basic functions::             First steps with MPI numbers.

-* MPI formats::                 External representation of MPIs.

-* Calculations::                Performing MPI calculations.

-* Comparisons::                 How to compare MPI values.

-* Bit manipulations::           How to access single bits of MPI values.

-* Miscellaneous::               Miscellaneous MPI functions.

-@end menu

-

-Public key cryptography is based on mathematics with large numbers.  To

-implement the public key functions, a library for handling these large

-numbers is required.  Because of the general usefulness of such a

-library, its interface is exposed by @acronym{Libgcrypt}.  The implementation is

-based on an old release of GNU Multi-Precision Library (GMP) but in the

-meantime heavily modified and stripped down to what is required for

-cryptography. For a lot of CPUs, high performance assembler

-implementations of some very low level functions are used to gain much

-better performance than with the standard C implementation.

-

-@noindent

-In the context of @acronym{Libgcrypt} and in most other applications, these large

-numbers are called MPIs (multi-precision-integers).

-

-@node Data types

-@section Data types

-

-@deftp {Data type} gcry_mpi_t

-The @code{gcry_mpi_t} type represents an object to hold an MPI.

-@end deftp

-

-@node Basic functions

-@section Basic functions

-

-@noindent

-To work with MPIs, storage must be allocated and released for the

-numbers.  This can be done with one of these functions:

-

-@deftypefun gcry_mpi_t gcry_mpi_new (@w{unsigned int @var{nbits}})

-

-Allocate a new MPI object, initialize it to 0 and initially allocate

-enough memory for a number of at least @var{nbits}.  This pre-allocation is

-only a small performance issue and not actually necessary because

-@acronym{Libgcrypt} automatically re-allocates the required memory.

-@end deftypefun

-

-@deftypefun gcry_mpi_t gcry_mpi_snew (@w{unsigned int @var{nbits}})

-

-This is identical to @code{gcry_mpi_new} but allocates the MPI in the so

-called "secure memory" which in turn will take care that all derived

-values will also be stored in this "secure memory".  Use this for highly

-confidential data like private key parameters.

-@end deftypefun

-

-@deftypefun gcry_mpi_t gcry_mpi_copy (@w{const gcry_mpi_t @var{a}})

-

-Create a new MPI as the exact copy of @var{a}.

-@end deftypefun

-

-

-@deftypefun void gcry_mpi_release (@w{gcry_mpi_t @var{a}})

-

-Release the MPI @var{a} and free all associated resources.  Passing

-@code{NULL} is allowed and ignored.  When a MPI stored in the "secure

-memory" is released, that memory gets wiped out immediately.

-@end deftypefun

-

-@noindent

-The simplest operations are used to assign a new value to an MPI:

-

-@deftypefun gcry_mpi_t gcry_mpi_set (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{u}})

-

-Assign the value of @var{u} to @var{w} and return @var{w}.  If

-@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the

-value of @var{u} and returned.

-@end deftypefun

-

-@deftypefun gcry_mpi_t gcry_mpi_set_ui (@w{gcry_mpi_t @var{w}}, @w{unsigned long @var{u}})

-

-Assign the value of @var{u} to @var{w} and return @var{w}.  If

-@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the

-value of @var{u} and returned.  This function takes an @code{unsigned

-int} as type for @var{u} and thus it is only possible to set @var{w} to

-small values (usually up to the word size of the CPU).

-@end deftypefun

-

-@deftypefun void gcry_mpi_swap (@w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})

-

-Swap the values of @var{a} and @var{b}.

-@end deftypefun

-

-@node MPI formats

-@section MPI formats

-

-@noindent

-The following functions are used to convert between an external

-representation of an MPI and the internal one of @acronym{Libgcrypt}.

-

-@deftypefun int gcry_mpi_scan (@w{gcry_mpi_t *@var{r_mpi}}, @w{enum gcry_mpi_format @var{format}}, @w{const void *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nscanned}})

-

-Convert the external representation of an integer stored in @var{buffer}

-with a length of @var{buflen} into a newly created MPI returned which

-will be stored at the address of @var{r_mpi}.  For certain formats the

-length argument is not required and may be passed as @code{0}.  After a

-successful operation the variable @var{nscanned} receives the number of

-bytes actually scanned unless @var{nscanned} was given as

-@code{NULL}. @var{format} describes the format of the MPI as stored in

-@var{buffer}:

-

-@table @code

-@item GCRYMPI_FMT_STD

-2-complement stored without a length header.

-

-@item GCRYMPI_FMT_PGP

-As used by OpenPGP (only defined as unsigned). This is basically

-@code{GCRYMPI_FMT_STD} with a 2 byte big endian length header.

-

-@item GCRYMPI_FMT_SSH

-As used in the Secure Shell protocol.  This is @code{GCRYMPI_FMT_STD}

-with a 4 byte big endian header.

-

-@item GCRYMPI_FMT_HEX

-Stored as a C style string with each byte of the MPI encoded as 2 hex

-digits.

-

-@item GCRYMPI_FMT_USG

-Simple unsigned integer.

-@end table

-

-@noindent

-Note, that all of the above formats store the integer in big-endian

-format (MSB first).

-@end deftypefun

-

-

-@deftypefun int gcry_mpi_print (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nwritten}}, @w{const gcry_mpi_t @var{a}})

-

-Convert the MPI @var{a} into an external representation described by

-@var{format} (see above) and store it in the provided @var{buffer}

-which has a usable length of at least the @var{buflen} bytes. If

-@var{nwritten} is not NULL, it will receive the number of bytes

-actually stored in @var{buffer} after a successful operation.

-@end deftypefun

-

-@deftypefun int gcry_mpi_aprint (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char **@var{buffer}}, @w{size_t *@var{nbytes}}, @w{const gcry_mpi_t @var{a}})

-

-Convert the MPI @var{a} into an external representation described by

-@var{format} (see above) and store it in a newly allocated buffer which

-address will be stored in the variable @var{buffer} points to.  The

-number of bytes stored in this buffer will be stored in the variable

-@var{nbytes} points to, unless @var{nbytes} is @code{NULL}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_dump (@w{const gcry_mpi_t @var{a}})

-

-Dump the value of @var{a} in a format suitable for debugging to

-Libgcrypt's logging stream.  Note that one leading space but no trailing

-space or linefeed will be printed.  It is okay to pass @code{NULL} for

-@var{a}.

-@end deftypefun

-

-

-@node Calculations

-@section Calculations

-

-@noindent

-Basic arithmetic operations:

-

-@deftypefun void gcry_mpi_add (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})

-

-@math{@var{w} = @var{u} + @var{v}}.

-@end deftypefun

-

-

-@deftypefun void gcry_mpi_add_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})

-

-@math{@var{w} = @var{u} + @var{v}}.  Note, that @var{v} is an unsigned integer.

-@end deftypefun

-

-

-@deftypefun void gcry_mpi_addm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})

-

-@math{@var{w} = @var{u} + @var{v} \bmod @var{m}}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_sub (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})

-

-@math{@var{w} = @var{u} - @var{v}}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_sub_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})

-

-@math{@var{w} = @var{u} - @var{v}}.  @var{v} is an unsigned integer.

-@end deftypefun

-

-@deftypefun void gcry_mpi_subm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})

-

-@math{@var{w} = @var{u} - @var{v} \bmod @var{m}}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_mul (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})

-

-@math{@var{w} = @var{u} * @var{v}}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_mul_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})

-

-@math{@var{w} = @var{u} * @var{v}}.  @var{v} is an unsigned integer.

-@end deftypefun

-

-@deftypefun void gcry_mpi_mulm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})

-

-@math{@var{w} = @var{u} * @var{v} \bmod @var{m}}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_mul_2exp (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{e}})

-

-@c FIXME: I am in need for a real TeX{info} guru:

-@c I don't know why TeX can grok @var{e} here.

-@math{@var{w} = @var{u} * 2^e}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_div (@w{gcry_mpi_t @var{q}}, @w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}}, @w{int @var{round}})

-

-@math{@var{q} = @var{dividend} / @var{divisor}}, @math{@var{r} =

-@var{dividend} \bmod @var{divisor}}.  @var{q} and @var{r} may be passed

-as @code{NULL}.  @var{round} should be negative or 0.

-@end deftypefun

-

-@deftypefun void gcry_mpi_mod (@w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}})

-

-@math{@var{r} = @var{dividend} \bmod @var{divisor}}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_powm (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{b}}, @w{const gcry_mpi_t @var{e}}, @w{const gcry_mpi_t @var{m}})

-

-@c I don't know why TeX can grok @var{e} here.

-@math{@var{w} = @var{b}^e \bmod @var{m}}.

-@end deftypefun

-

-@deftypefun int gcry_mpi_gcd (@w{gcry_mpi_t @var{g}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})

-

-Set @var{g} to the greatest common divisor of @var{a} and @var{b}.  

-Return true if the @var{g} is 1.

-@end deftypefun

-

-@deftypefun int gcry_mpi_invm (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{m}})

-

-Set @var{x} to the multiplicative inverse of @math{@var{a} \bmod @var{m}}.

-Return true if the inverse exists.

-@end deftypefun

-

-

-@node Comparisons

-@section Comparisons

-

-@noindent

-The next 2 functions are used to compare MPIs:

-

-

-@deftypefun int gcry_mpi_cmp (@w{const gcry_mpi_t @var{u}}, @w{const gcry_mpi_t @var{v}})

-

-Compare the big integer number @var{u} and @var{v} returning 0 for

-equality, a positive value for @var{u} > @var{v} and a negative for

-@var{u} < @var{v}.

-@end deftypefun

-

-@deftypefun int gcry_mpi_cmp_ui (@w{const gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})

-

-Compare the big integer number @var{u} with the unsigned integer @var{v}

-returning 0 for equality, a positive value for @var{u} > @var{v} and a

-negative for @var{u} < @var{v}.

-@end deftypefun

-

-

-@node Bit manipulations

-@section Bit manipulations

-

-@noindent

-There are a couple of functions to get information on arbitrary bits

-in an MPI and to set or clear them:

-

-@deftypefun {unsigned int} gcry_mpi_get_nbits (@w{gcry_mpi_t @var{a}})

-

-Return the number of bits required to represent @var{a}.

-@end deftypefun

-

-@deftypefun int gcry_mpi_test_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})

-

-Return true if bit number @var{n} (counting from 0) is set in @var{a}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_set_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})

-

-Set bit number @var{n} in @var{a}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_clear_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})

-

-Clear bit number @var{n} in @var{a}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_set_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})

-

-Set bit number @var{n} in @var{a} and clear all bits greater than @var{n}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_clear_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})

-

-Clear bit number @var{n} in @var{a} and all bits greater than @var{n}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_rshift (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})

-

-Shift the value of @var{a} by @var{n} bits to the right and store the

-result in @var{x}.

-@end deftypefun

-

-@node Miscellaneous

-@section Miscellanous

-

-@deftypefun gcry_mpi_t gcry_mpi_set_opaque (@w{gcry_mpi_t @var{a}}, @w{void *@var{p}}, @w{unsigned int @var{nbits}})

-

-Store @var{nbits} of the value @var{p} points to in @var{a} and mark

-@var{a} as an opaque value (i.e. an value that can't be used for any

-math calculation and is only used to store an arbitrary bit pattern in

-@var{a}).

-

-WARNING: Never use an opaque MPI for actual math operations.  The only

-valid functions are gcry_mpi_get_opaque and gcry_mpi_release.  Use

-gcry_mpi_scan to convert a string of arbitrary bytes into an MPI.

-

-@end deftypefun

-

-@deftypefun {void *} gcry_mpi_get_opaque (@w{gcry_mpi_t @var{a}}, @w{unsigned int *@var{nbits}})

-

-Return a pointer to an opaque value stored in @var{a} and return its

-size in @var{nbits}.  Note, that the returned pointer is still owned by

-@var{a} and that the function should never be used for an non-opaque

-MPI.

-@end deftypefun

-

-@deftypefun void gcry_mpi_set_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})

-

-Set the @var{flag} for the MPI @var{a}.  Currently only the flag

-@code{GCRYMPI_FLAG_SECURE} is allowed to convert @var{a} into an MPI

-stored in "secure memory".

-@end deftypefun

-

-@deftypefun void gcry_mpi_clear_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})

-

-Clear @var{flag} for the big integer @var{a}.  Note, that this function is

-currently useless as no flags are allowed.

-@end deftypefun

-

-@deftypefun int gcry_mpi_get_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})

-

-Return true when the @var{flag} is set for @var{a}.

-@end deftypefun

-

-@deftypefun void gcry_mpi_randomize (@w{gcry_mpi_t @var{w}}, @w{unsigned int @var{nbits}}, @w{enum gcry_random_level @var{level}})

-

-Set the big integer @var{w} to a random value of @var{nbits}, using

-random data quality of level @var{level}.  In case @var{nbits} is not

-a multiple of a byte, @var{nbits} is rounded up to the next byte

-boundary.

-@end deftypefun

-

-@node Utilities

-@chapter Utilities

-

-@menu

-* Memory allocation::           Functions related with memory allocation.

-@end menu

-

-@node Memory allocation

-@section Memory allocation

-

-@deftypefun void *gcry_malloc (size_t @var{n})

-

-This function tries to allocate @var{n} bytes of memory.  On success

-it returns a pointer to the memory area, in an out-of-core condition,

-it returns NULL.

-@end deftypefun

-

-@deftypefun void *gcry_malloc_secure (size_t @var{n})

-Like @code{gcry_malloc}, but uses secure memory.

-@end deftypefun

-

-@deftypefun void *gcry_calloc (size_t @var{n})

-

-This function tries to allocate @var{n} bytes of cleared memory

-(i.e. memory that is initialized with zero bytes).  On success it

-returns a pointer to the memory area, in an out-of-core condition, it

-returns NULL.

-@end deftypefun

-

-@deftypefun void *gcry_calloc_secure (size_t @var{n})

-Like @code{gcry_calloc}, but uses secure memory.

-@end deftypefun

-

-@deftypefun void *gcry_realloc (void *@var{p}, size_t @var{n})

-

-This function tries to resize the memory area pointed to by @var{p} to

-@var{n} bytes.  On success it returns a pointer to the new memory

-area, in an out-of-core condition, it returns NULL.  Depending on

-whether the memory pointed to by @var{p} is secure memory or not,

-gcry_realloc tries to use secure memory as well.

-@end deftypefun

-

-@deftypefun void gcry_free (void *@var{p})

-Release the memory area pointed to by @var{p}.

-@end deftypefun

-

-@c **********************************************************

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

-@c **********************************************************

-

-@include lgpl.texi

-

-@include gpl.texi

-

-@node Concept Index

-@unnumbered Concept Index

-

-@printindex cp

-

-@node Function and Data Index

-@unnumbered Function and Data Index

-

-@printindex fn

-

-@bye

-

-  /* Version check should be the very first gcry call because it

-     makes sure that constructor functions are run. */

-  if (!gcry_check_version (GCRYPT_VERSION))

-    die ("version mismatch\n");

-  /* Many applications don't require secure memory, so they should

-     disable it right away.  There won't be a problem unless one makes

-     use of a feature which requires secure memory - in that case the

-     process would abort because the secmem is not initialized. */

-  gcry_control (GCRYCTL_DISABLE_SECMEM, 0);

-

-  /* .. add whatever initialization you want, but better don't make calls

-        to libgcrypt from more than one thread ... */

-

-  /* Tell Libgcrypt that initialization has completed. */

-  gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);

-

-

-If you require secure memory, this code should be used: 

-

-  if (!gcry_check_version (GCRYPT_VERSION))

-    die ("version mismatch\n");

-  /* We don't want to see any warnings, e.g. because we have not yet

-    parsed options which might be used to suppress such warnings */

-  gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);

-

-  /* ... */

-

-  /* Allocate a pool of 16k secure memory.  This also drops priviliges

-     on some systems. */

-  gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);

-

-  /* It is now okay to let Libgcrypt complain when there was/is a problem

-     with the secure memory. */

-  gcry_control (GCRYCTL_RESUME_SECMEM_WARN);

-

-  /* Tell Libgcrypt that initialization has completed. */

-  gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);

-

-

-This sounds a bit complicated but has the advantage that the caller

-must decide whether he wants secure memory or not - there is no

-default.

-

-It is important that this initialization is not done by a library but

-in the application.  The library might want to check for finished

-initialization using:

-

-  if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))

-    return MYLIB_ERROR_LIBGCRYPT_NOT_INITIALIZED;

-

-

-@c  LocalWords:  int HD

-

-

-

-

+\input texinfo                  @c -*- Texinfo -*-
+@c %**start of header
+@setfilename gcrypt.info
+@include version.texi
+@settitle The Libgcrypt Reference Manual
+@c Unify some of the indices.
+@syncodeindex tp fn
+@syncodeindex pg fn
+@c %**end of header
+@copying
+This manual is for Libgcrypt
+(version @value{VERSION}, @value{UPDATED}),
+which is GNU's library of cryptographic building blocks.
+
+Copyright @copyright{} 2000, 2002, 2003, 2004 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+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. The text of the license can be found in the
+section entitled ``Copying''.
+@end quotation
+@end copying
+
+@dircategory GNU Libraries
+@direntry
+* libgcrypt: (gcrypt).  Cryptographic function library.
+@end direntry
+
+
+
+@c
+@c Titlepage
+@c
+@setchapternewpage odd
+@titlepage
+@title The Libgcrypt Reference Manual
+@subtitle Version @value{VERSION}
+@subtitle @value{UPDATED}
+@author Werner Koch (@email{wk@@gnupg.org})
+@author Moritz Schulte (@email{mo@@g10code.com})
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+
+@summarycontents
+@contents
+@page
+
+
+@ifnottex
+@node Top
+@top The Libgcrypt Library
+@insertcopying
+@end ifnottex
+
+
+@menu
+* Introduction::                 What is @acronym{Libgcrypt}.
+* Preparation::                  What you should do before using the library.
+* Generalities::                 General library functions and data types.
+* Handler Functions::            Working with handler functions.
+* Symmetric cryptography::       How to use symmetric cryptography.
+* Hashing::                      How to use hashing.
+* Public Key cryptography (I)::  How to use public key cryptography.
+* Public Key cryptography (II):: How to use public key cryptography, alternatively.
+* Random Numbers::               How to work with random numbers.
+* S-expressions::                How to manage S-expressions.
+* MPI library::                  How to work with multi-precision-integers.
+* Utilities::                    Utility functions.
+
+Appendices
+
+* Library Copying::             The GNU Lesser General Public License
+                                says how you can copy and share `Libgcrypt'.
+* Copying::                     The GNU General Public License says how you
+                                can copy and share some parts of `Libgcrypt'.
+
+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::             How to use this manual.
+* Features::                    A glance at @acronym{Libgcrypt}'s features.
+* Overview::                    Overview about the library.
+
+Preparation
+* Header::                              What header file you need to include.
+* Building sources::                    How to build sources using the library.
+* Building sources using Automake::     How to build sources with the help of Automake.
+* Initializing the library::            How to initialize the library.
+* Multi Threading::                     How @acronym{Libgcrypt} can be used in a MT environment.
+
+Generalities
+* Controlling the library::     Controlling @acronym{Libgcrypt}'s behavior.
+* Modules::                     Description of extension modules.
+* Error Handling::              Error codes and such.
+
+Handler Functions
+* Progress handler::            Using a progress handler function.
+* Allocation handler::          Using special memory allocation functions.
+* Error handler::               Using error handler functions.
+* Logging handler::             Using a special logging function.
+
+Symmetric cryptography
+* Available ciphers::           List of ciphers supported by the library.
+* Cipher modules::              How to work with cipher modules.
+* Available cipher modes::      List of cipher modes supported by the library.
+* Working with cipher handles:: How to perform operations related to cipher handles.
+* General cipher functions::    General cipher functions independent of cipher handles.
+
+Hashing
+* Available hash algorithms::           List of hash algorithms supported by the library.
+* Hash algorithm modules::              How to work with hash algorithm modules.
+* Working with hash algorithms::        List of functions related to hashing.
+
+Public Key cryptography (I)
+* Used S-expressions::                    Introduction into the used S-expression.
+* Available algorithms::                  Algorithms supported by the library.
+* Public key modules::                    How to work with public key modules.
+* Cryptographic Functions::               Functions for performing the cryptographic actions.
+* General public-key related Functions::  General functions, not implementing any cryptography.
+
+Public Key cryptography (II)
+* Available asymmetric algorithms:: List of algorithms supported by the library.
+* Working with sets of data::       How to work with sets of data.
+* Working with handles::            How to use handles.
+* Working with keys::               How to work with keys.
+* Using cryptographic functions::   How to perform cryptographic operations.
+* Handle-independent functions::    General functions independent of handles.
+
+Random Numbers
+* Quality of random numbers::   @acronym{Libgcrypt} uses different quality levels.
+* Retrieving random numbers::   How to retrieve random numbers.
+
+S-expressions
+* Data types for S-expressions::   Data types related with S-expressions.
+* Working with S-expressions::     How to work with S-expressions.
+
+MPI library
+* Data types::                  MPI related data types.
+* Basic functions::             First steps with MPI numbers.
+* MPI formats::                 External representation of MPIs.
+* Calculations::                Performing MPI calculations.
+* Comparisons::                 How to compare MPI values.
+* Bit manipulations::           How to access single bits of MPI values.
+* Miscellaneous::               Miscellaneous MPI functions.
+
+Utilities
+* Memory allocation::           Functions related with memory allocation.
+
+@end detailmenu
+
+@end menu
+
+
+
+@c **********************************************************
+@c *******************  Introduction  ***********************
+@c **********************************************************
+@node Introduction
+@chapter Introduction
+`@acronym{Libgcrypt}' is a library providing cryptographic building blocks.
+
+@menu
+* Getting Started::             How to use this manual.
+* Features::                    A glance at @acronym{Libgcrypt}'s features.
+* Overview::                    Overview about the library.
+@end menu
+
+@node Getting Started
+@section Getting Started
+
+This manual documents the `@acronym{Libgcrypt}' library application programming
+interface (API).  All functions and data types provided by the library
+are explained.
+
+@noindent
+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' might have 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
+Lesser General Public License (@pxref{Library Copying}).  Note, that
+some parts (which are not needed on a GNU or GNU/Linux system) are
+subject to the terms of the GNU General Public License
+(@pxref{Copying}); please see the README file of the distribution for of
+list of these parts.
+
+@item It encapsulates the low level cryptography
+`@acronym{Libgcrypt}' provides a high level interface to cryptographic building
+blocks using an extendable and flexible API.
+
+@end table
+
+@node Overview
+@section Overview
+
+@noindent
+The `@acronym{Libgcrypt}' library is fully thread-safe, where it makes
+sense to be thread-safe.  An exception for thread-safety are some
+cryptographic functions that modify a certain context stored in
+handles.  If the user really intents to use such functions from
+different threads on the same handle, he has to take care of the
+serialization of such functions himself.  If not described otherwise,
+every function is thread-safe.
+
+@acronym{Libgcrypt} depends on the library `libgpg-error', which
+contains common error handling related code for GnuPG components.
+
+@c **********************************************************
+@c *******************  Preparation  ************************
+@c **********************************************************
+@node Preparation
+@chapter Preparation
+
+To use `@acronym{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::                      What header file you need to include.
+* Building sources::            How to build sources using the library.
+* Building sources using Automake::  How to build sources with the help of Automake.
+* Initializing the library::    How to initialize the library.
+* Multi Threading::             How @acronym{Libgcrypt} can be used in a MT environment.
+@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 source
+files using the library, either directly or through some other header
+file, like this:
+
+@example
+#include <gcrypt.h>
+@end example
+
+The name space of `@acronym{Libgcrypt}' is @code{gcry_*} for function
+and type names 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.  Furthermore
+`libgpg-error' defines functions prefixed with `gpg_' and preprocessor
+symbols prefixed with `GPG_'.  Note that @acronym{Libgcrypt} uses
+libgpg-error, which uses @code{gpg_err_*} as name space for function
+and type names and @code{GPG_ERR_*} for other symbols, including all
+the error codes.
+
+@node Building sources
+@section Building sources
+
+If you want to compile a source file including the `gcrypt.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, `@acronym{Libgcrypt}' 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 `@acronym{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 `@acronym{Libgcrypt}' libraries (in particular, the @samp{-lgcrypt}
+option).  The example shows how to link @file{foo.o} with the `@acronym{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
+
+@node Building sources using Automake
+@section Building sources using Automake
+
+It is much easier if you use GNU Automake instead of writing your own
+Makefiles.  If you do that you do not have to worry about finding and
+invoking the @command{libgcrypt-config} script at all.
+@acronym{Libgcrypt} provides an extension to Automake that does all
+the work for you.
+
+@c A simple macro for optional variables.
+@macro ovar{varname}
+@r{[}@var{\varname\}@r{]}
+@end macro
+@defmac AM_PATH_LIBGCRYPT (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
+Check whether @acronym{Libgcrypt} (at least version
+@var{minimum-version}, if given) exists on the host system.  If it is
+found, execute @var{action-if-found}, otherwise do
+@var{action-if-not-found}, if given.
+
+Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the
+flags needed for compilation of the program to find the
+@file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker
+flags needed to link the program to the @acronym{Libgcrypt} library.
+@end defmac
+
+You can use the defined Autoconf variables like this in your
+@file{Makefile.am}:
+
+@example
+AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
+LDADD = $(LIBGCRYPT_LIBS)
+@end example
+
+@node Initializing the library
+@section Initializing the library
+
+It is often desirable to check that the version of `@acronym{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})
+
+The function @code{gcry_check_version} has three purposes.  It can be
+used to retrieve the version number of the library.  In addition it
+can verify that the version number is higher than a certain required
+version number.
+
+In either case, the function initializes some sub-systems, and for
+this reason alone it must be invoked early in your program, before you
+make use of the other functions of @acronym{Libgcrypt}.
+@end deftypefun
+
+@node Multi Threading
+@section Multi Threading
+
+As mentioned earlier, the `@acronym{Libgcrypt}' library is 
+thread-safe if you adhere to the following requirements:
+
+@itemize @bullet
+@item
+If your application is multi-threaded, you must set the thread support
+callbacks with the @code{GCRYCTL_SET_THREAD_CBS} command
+@strong{before} any other function in the library.
+
+This is easy enough if you are indeed writing an application using
+Libgcrypt.  It is rather problematic if you are writing a library
+instead.  Here are some tips what to do if you are writing a library:
+
+If your library requires a certain thread package, just initialize
+Libgcrypt to use this thread package.  If your library supports multiple
+thread packages, but needs to be configured, you will have to
+implement a way to determine which thread package the application
+wants to use with your library anyway.  Then configure Libgcrypt to use
+this thread package.
+
+If your library is fully reentrant without any special support by a
+thread package, then you are lucky indeed.  Unfortunately, this does
+not relieve you from doing either of the two above, or use a third
+option.  The third option is to let the application initialize Libgcrypt
+for you.  Then you are not using Libgcrypt transparently, though.
+
+As if this was not difficult enough, a conflict may arise if two
+libraries try to initialize Libgcrypt independently of each others, and
+both such libraries are then linked into the same application.  To
+make it a bit simpler for you, this will probably work, but only if
+both libraries have the same requirement for the thread package.  This
+is currently only supported for the non-threaded case, GNU Pth and
+pthread.  Support for more thread packages is easy to add, so contact
+us if you require it.
+
+@item
+The function @code{gcry_check_version} must be called before any other
+function in the library, except the @code{GCRYCTL_SET_THREAD_CBS}
+command (called via the @code{gcry_control} function), because it
+initializes the thread support subsystem in @acronym{Libgcrypt}.  To
+achieve this in multi-threaded programs, you must synchronize the
+memory with respect to other threads that also want to use
+@acronym{Libgcrypt}.  For this, it is sufficient to call
+@code{gcry_check_version} before creating the other threads using
+@acronym{Libgcrypt}@footnote{At least this is true for POSIX threads,
+as @code{pthread_create} is a function that synchronizes memory with
+respects to other threads.  There are many functions which have this
+property, a complete list can be found in POSIX, IEEE Std 1003.1-2003,
+Base Definitions, Issue 6, in the definition of the term ``Memory
+Synchronization''.  For other thread packages, more relaxed or more
+strict rules may apply.}.
+
+@item
+
+As with the function @code{gpg_strerror}, @code{gcry_strerror} is not
+thread safe.  You have to use @code{gpg_strerror_r} instead.
+@end itemize
+
+
+@acronym{Libgcrypt} contains convenient macros, which define the
+necessary thread callbacks for PThread and for GNU Pth:
+
+@table @code
+@item GCRY_THREAD_OPTION_PTH_IMPL
+
+This macro defines the following (static) symbols: gcry_pth_init,
+gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock,
+gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write, gcry_pth_select,
+gcry_pth_waitpid, gcry_pth_accept, gcry_pth_connect, gcry_threads_pth.
+
+After including this macro, gcry_control() shall be used with a
+command of GCRYCTL_SET_THREAD_CBS in order to register the thread
+callback structure named ``gcry_threads_pth''.
+
+@item GCRY_THREAD_OPTION_PTHREAD_IMPL
+
+This macro defines the following (static) symbols:
+gcry_pthread_mutex_init, gcry_pthread_mutex_destroy, gcry_mutex_lock,
+gcry_mutex_unlock, gcry_threads_pthread.
+
+After including this macro, gcry_control() shall be used with a
+command of GCRYCTL_SET_THREAD_CBS in order to register the thread
+callback structure named ``gcry_threads_pthread''.
+@end table
+
+Note that these macros need to be terminated with a semicolon.  Keep
+in mind that these are convenient macros for C programmers; C++
+programmers might have to wrap these macros in an ``extern C'' body.
+
+@c **********************************************************
+@c *******************  General  ****************************
+@c **********************************************************
+@node Generalities
+@chapter Generalities
+
+@menu
+* Controlling the library::     Controlling @acronym{Libgcrypt}'s behavior.
+* Modules::                     Description of extension modules.
+* Error Handling::              Error codes and such.
+@end menu
+
+@node Controlling the library
+@section Controlling the library
+
+@deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
+
+This function can be used to influence the general behavior of
+@acronym{Libgcrypt} in several ways.  Depending on @var{cmd}, more
+arguments can or have to be provided.
+
+@end deftypefun
+
+@node Modules
+@section Modules
+
+@acronym{Libgcrypt} supports the use of `extension modules', which
+implement algorithms in addition to those already built into the
+library directly.
+
+@deftp {Data type} gcry_module_t
+This data type represents a `module'.
+@end deftp
+
+Functions registering modules provided by the user take a `module
+specification structure' as input and return a value of
+@code{gcry_module_t} and an ID that is unique in the modules'
+category.  This ID can be used to reference the newly registered
+module.  After registering a module successfully, the new functionality
+should be able to be used through the normal functions provided by
+@acronym{Libgcrypt} until it is unregistered again.
+
+@c **********************************************************
+@c *******************  Errors  ****************************
+@c **********************************************************
+@node Error Handling
+@section Error Handling
+
+Many functions in @acronym{Libgcrypt} can return an error if they
+fail.  For this reason, the application should always catch the error
+condition and take appropriate measures, for example by releasing the
+resources and passing the error up to the caller, or by displaying a
+descriptive message to the user and cancelling the operation.
+
+Some error values do not indicate a system error or an error in the
+operation, but the result of an operation that failed properly.  For
+example, if you try to decrypt a tempered message, the decryption will
+fail.  Another error value actually means that the end of a data
+buffer or list has been reached.  The following descriptions explain
+for many error codes what they mean usually.  Some error values have
+specific meanings if returned by a certain functions.  Such cases are
+described in the documentation of those functions.
+
+@acronym{Libgcrypt} uses the @code{libgpg-error} library.  This allows
+to share the error codes with other components of the GnuPG system,
+and thus pass error values transparently from the crypto engine, or
+some helper application of the crypto engine, to the user.  This way
+no information is lost.  As a consequence, @acronym{Libgcrypt} does
+not use its own identifiers for error codes, but uses those provided
+by @code{libgpg-error}.  They usually start with @code{GPG_ERR_}.
+
+However, @acronym{Libgcrypt} does provide aliases for the functions
+defined in libgpg-error, which might be preferred for name space
+consistency.
+
+
+Most functions in @acronym{Libgcrypt} return an error code in the case
+of failure.  For this reason, the application should always catch the
+error condition and take appropriate measures, for example by
+releasing the resources and passing the error up to the caller, or by
+displaying a descriptive message to the user and canceling the
+operation.
+
+Some error values do not indicate a system error or an error in the
+operation, but the result of an operation that failed properly.
+
+GnuPG components, including Libgcrypt, use an extra library named
+libgpg-error to provide a common error handling scheme.  For more
+information on libgpg-error, see the according manual.
+
+@menu
+* Error Values::                The error value and what it means.
+* Error Sources::               A list of important error sources.
+* Error Codes::                 A list of important error codes.
+* Error Strings::               How to get a descriptive string from a value.
+@end menu
+
+
+@node Error Values
+@subsection Error Values
+@cindex error values
+@cindex error codes
+@cindex error sources
+
+@deftp {Data type} {gcry_err_code_t}
+The @code{gcry_err_code_t} type is an alias for the
+@code{libgpg-error} type @code{gpg_err_code_t}.  The error code
+indicates the type of an error, or the reason why an operation failed.
+
+A list of important error codes can be found in the next section.
+@end deftp
+
+@deftp {Data type} {gcry_err_source_t}
+The @code{gcry_err_source_t} type is an alias for the
+@code{libgpg-error} type @code{gpg_err_source_t}.  The error source
+has not a precisely defined meaning.  Sometimes it is the place where
+the error happened, sometimes it is the place where an error was
+encoded into an error value.  Usually the error source will give an
+indication to where to look for the problem.  This is not always true,
+but it is attempted to achieve this goal.
+
+A list of important error sources can be found in the next section.
+@end deftp
+
+@deftp {Data type} {gcry_error_t}
+The @code{gcry_error_t} type is an alias for the @code{libgpg-error}
+type @code{gpg_error_t}.  An error value like this has always two
+components, an error code and an error source.  Both together form the
+error value.
+
+Thus, the error value can not be directly compared against an error
+code, but the accessor functions described below must be used.
+However, it is guaranteed that only 0 is used to indicate success
+(@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
+the error value are set to 0, too.
+
+Note that in @acronym{Libgcrypt}, the error source is used purely for
+diagnostic purposes.  Only the error code should be checked to test
+for a certain outcome of a function.  The manual only documents the
+error code part of an error value.  The error source is left
+unspecified and might be anything.
+@end deftp
+
+@deftypefun {gcry_err_code_t} gcry_err_code (@w{gcry_error_t @var{err}})
+The static inline function @code{gcry_err_code} returns the
+@code{gcry_err_code_t} component of the error value @var{err}.  This
+function must be used to extract the error code from an error value in
+order to compare it with the @code{GPG_ERR_*} error code macros.
+@end deftypefun
+
+@deftypefun {gcry_err_source_t} gcry_err_source (@w{gcry_error_t @var{err}})
+The static inline function @code{gcry_err_source} returns the
+@code{gcry_err_source_t} component of the error value @var{err}.  This
+function must be used to extract the error source from an error value in
+order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
+@end deftypefun
+
+@deftypefun {gcry_error_t} gcry_err_make (@w{gcry_err_source_t @var{source}}, @w{gcry_err_code_t @var{code}})
+The static inline function @code{gcry_err_make} returns the error
+value consisting of the error source @var{source} and the error code
+@var{code}.
+
+This function can be used in callback functions to construct an error
+value to return it to the library.
+@end deftypefun
+
+@deftypefun {gcry_error_t} gcry_error (@w{gcry_err_code_t @var{code}})
+The static inline function @code{gcry_error} returns the error value
+consisting of the default error source and the error code @var{code}.
+
+For @acronym{GCRY} applications, the default error source is
+@code{GPG_ERR_SOURCE_USER_1}.  You can define
+@code{GCRY_ERR_SOURCE_DEFAULT} before including @file{gcrypt.h} to
+change this default.
+
+This function can be used in callback functions to construct an error
+value to return it to the library.
+@end deftypefun
+
+The @code{libgpg-error} library provides error codes for all system
+error numbers it knows about.  If @var{err} is an unknown error
+number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used.  The
+following functions can be used to construct error values from system
+errno numbers.
+
+@deftypefun {gcry_error_t} gcry_err_make_from_errno (@w{gcry_err_source_t @var{source}}, @w{int @var{err}})
+The function @code{gcry_err_make_from_errno} is like
+@code{gcry_err_make}, but it takes a system error like @code{errno}
+instead of a @code{gcry_err_code_t} error code.
+@end deftypefun
+
+@deftypefun {gcry_error_t} gcry_error_from_errno (@w{int @var{err}})
+The function @code{gcry_error_from_errno} is like @code{gcry_error},
+but it takes a system error like @code{errno} instead of a
+@code{gcry_err_code_t} error code.
+@end deftypefun
+
+Sometimes you might want to map system error numbers to error codes
+directly, or map an error code representing a system error back to the
+system error number.  The following functions can be used to do that.
+
+@deftypefun {gcry_err_code_t} gcry_err_code_from_errno (@w{int @var{err}})
+The function @code{gcry_err_code_from_errno} returns the error code
+for the system error @var{err}.  If @var{err} is not a known system
+error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
+@end deftypefun
+
+@deftypefun {int} gcry_err_code_to_errno (@w{gcry_err_code_t @var{err}})
+The function @code{gcry_err_code_to_errno} returns the system error
+for the error code @var{err}.  If @var{err} is not an error code
+representing a system error, or if this system error is not defined on
+this system, the function returns @code{0}.
+@end deftypefun
+
+
+@node Error Sources
+@subsection Error Sources
+@cindex error codes, list of
+
+The library @code{libgpg-error} defines an error source for every
+component of the GnuPG system.  The error source part of an error
+value is not well defined.  As such it is mainly useful to improve the
+diagnostic error message for the user.
+
+If the error code part of an error value is @code{0}, the whole error
+value will be @code{0}.  In this case the error source part is of
+course @code{GPG_ERR_SOURCE_UNKNOWN}.
+
+The list of error sources that might occur in applications using
+@acronym{Libgctypt} is:
+
+@table @code
+@item GPG_ERR_SOURCE_UNKNOWN
+The error source is not known.  The value of this error source is
+@code{0}.
+
+@item GPG_ERR_SOURCE_GPGME
+The error source is @acronym{GPGME} itself.
+
+@item GPG_ERR_SOURCE_GPG
+The error source is GnuPG, which is the crypto engine used for the
+OpenPGP protocol.
+
+@item GPG_ERR_SOURCE_GPGSM
+The error source is GPGSM, which is the crypto engine used for the
+OpenPGP protocol.
+
+@item GPG_ERR_SOURCE_GCRYPT
+The error source is @code{libgcrypt}, which is used by crypto engines
+to perform cryptographic operations.
+
+@item GPG_ERR_SOURCE_GPGAGENT
+The error source is @command{gpg-agent}, which is used by crypto
+engines to perform operations with the secret key.
+
+@item GPG_ERR_SOURCE_PINENTRY
+The error source is @command{pinentry}, which is used by
+@command{gpg-agent} to query the passphrase to unlock a secret key.
+
+@item GPG_ERR_SOURCE_SCD
+The error source is the SmartCard Daemon, which is used by
+@command{gpg-agent} to delegate operations with the secret key to a
+SmartCard.
+
+@item GPG_ERR_SOURCE_KEYBOX
+The error source is @code{libkbx}, a library used by the crypto
+engines to manage local keyrings.
+
+@item GPG_ERR_SOURCE_USER_1
+@item GPG_ERR_SOURCE_USER_2
+@item GPG_ERR_SOURCE_USER_3
+@item GPG_ERR_SOURCE_USER_4
+These error sources are not used by any GnuPG component and can be
+used by other software.  For example, applications using
+@acronym{Libgcrypt} can use them to mark error values coming from callback
+handlers.  Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
+created with @code{gcry_error} and @code{gcry_error_from_errno},
+unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including
+@file{gcrypt.h}.
+@end table
+
+
+@node Error Codes
+@subsection Error Codes
+@cindex error codes, list of
+
+The library @code{libgpg-error} defines many error values.  The
+following list includes the most important error codes.
+
+@table @code
+@item GPG_ERR_EOF
+This value indicates the end of a list, buffer or file.
+
+@item GPG_ERR_NO_ERROR
+This value indicates success.  The value of this error code is
+@code{0}.  Also, it is guaranteed that an error value made from the
+error code @code{0} will be @code{0} itself (as a whole).  This means
+that the error source information is lost for this error code,
+however, as this error code indicates that no error occured, this is
+generally not a problem.
+
+@item GPG_ERR_GENERAL
+This value means that something went wrong, but either there is not
+enough information about the problem to return a more useful error
+value, or there is no separate error value for this type of problem.
+
+@item GPG_ERR_ENOMEM
+This value means that an out-of-memory condition occurred.
+
+@item GPG_ERR_E...
+System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for
+the system error.
+
+@item GPG_ERR_INV_VALUE
+This value means that some user provided data was out of range.
+
+@item GPG_ERR_UNUSABLE_PUBKEY
+This value means that some recipients for a message were invalid.
+
+@item GPG_ERR_UNUSABLE_SECKEY
+This value means that some signers were invalid.
+
+@item GPG_ERR_NO_DATA
+This value means that data was expected where no data was found.
+
+@item GPG_ERR_CONFLICT
+This value means that a conflict of some sort occurred.
+
+@item GPG_ERR_NOT_IMPLEMENTED
+This value indicates that the specific function (or operation) is not
+implemented.  This error should never happen.  It can only occur if
+you use certain values or configuration options which do not work,
+but for which we think that they should work at some later time.
+
+@item GPG_ERR_DECRYPT_FAILED
+This value indicates that a decryption operation was unsuccessful.
+
+@item GPG_ERR_WRONG_KEY_USAGE
+This value indicates that a key is not used appropriately.
+
+@item GPG_ERR_NO_SECKEY
+This value indicates that no secret key for the user ID is available.
+
+@item GPG_ERR_UNSUPPORTED_ALGORITHM
+This value means a verification failed because the cryptographic
+algorithm is not supported by the crypto backend.
+
+@item GPG_ERR_BAD_SIGNATURE
+This value means a verification failed because the signature is bad.
+
+@item GPG_ERR_NO_PUBKEY
+This value means a verification failed because the public key is not
+available.
+
+@item GPG_ERR_USER_1
+@item GPG_ERR_USER_2
+@item ...
+@item GPG_ERR_USER_16
+These error codes are not used by any GnuPG component and can be
+freely used by other software.  Applications using @acronym{Libgcrypt}
+might use them to mark specific errors returned by callback handlers
+if no suitable error codes (including the system errors) for these
+errors exist already.
+@end table
+
+
+@node Error Strings
+@subsection Error Strings
+@cindex error values, printing of
+@cindex error codes, printing of
+@cindex error sources, printing of
+@cindex error strings
+
+@deftypefun {const char *} gcry_strerror (@w{gcry_error_t @var{err}})
+The function @code{gcry_strerror} returns a pointer to a statically
+allocated string containing a description of the error code contained
+in the error value @var{err}.  This string can be used to output a
+diagnostic message to the user.
+@end deftypefun
+
+
+@deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}})
+The function @code{gcry_strerror} returns a pointer to a statically
+allocated string containing a description of the error source
+contained in the error value @var{err}.  This string can be used to
+output a diagnostic message to the user.
+@end deftypefun
+
+The following example illustrates the use of the functions described
+above:
+
+@example
+@{
+  gcry_cipher_hd_t handle;
+  gcry_error_t err = 0;
+
+  err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0);
+  if (err)
+    @{
+      fprintf (stderr, "Failure: %s/%s\n",
+               gcry_strsource (err),
+               gcry_strerror (err));
+    @}
+@}
+@end example
+
+@c **********************************************************
+@c *******************  General  ****************************
+@c **********************************************************
+@node Handler Functions
+@chapter Handler Functions
+
+@acronym{Libgcrypt} makes it possible to install so called `handler functions',
+which get called by @acronym{Libgcrypt} in case of certain events.
+
+@menu
+* Progress handler::            Using a progress handler function.
+* Allocation handler::          Using special memory allocation functions.
+* Error handler::               Using error handler functions.
+* Logging handler::             Using a special logging function.
+@end menu
+
+@node Progress handler
+@section Progress handler
+
+It is often useful to retrieve some feedback while long running
+operations are performed.
+
+@deftp {Data type} gcry_handler_progress_t
+Progress handler functions have to be of the type
+@code{gcry_handler_progress_t}, which is defined as:
+
+@code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)}
+@end deftp
+
+The following function may be used to register a handler function for
+this purpose.
+
+@deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data})
+
+This function installs @var{cb} as the `Progress handler' function.
+@var{cb} must be defined as follows:
+
+@example
+void
+my_progress_handler (void *@var{cb_data}, const char *@var{what},
+                     int @var{printchar}, int @var{current}, int @var{total})
+@{
+  /* Do something.  */
+@}
+@end example
+
+A description of the arguments of the progress handler function follows.
+
+@table @var
+@item cb_data
+The argument provided in the call to @code{gcry_set_progress_handler}.
+@item what
+A string identifying the type of the progress output.  The following
+values for @var{what} are defined:
+
+@table @code
+@item need_entropy
+Not enough entropy is available.  @var{total} holds the number of
+required bytes.
+
+@item primegen
+Values for @var{printchar}:
+@table @code
+@item \n
+Prime generated.
+@item !
+Need to refresh the pool of prime numbers.
+@item <, >
+Number of bits adjusted.
+@item ^
+Searching for a generator.
+@item .
+Fermat test on 10 candidates failed.
+@item :
+Restart with a new random value.
+@item +
+Rabin Miller test passed.
+@end table
+
+@end table
+
+@end table
+@end deftypefun
+
+@node Allocation handler
+@section Allocation handler
+
+It is possible to make @acronym{Libgcrypt} use special memory
+allocation functions instead of the built-in ones.
+
+Memory allocation functions are of the following types:
+@deftp {Data type} gcry_handler_alloc_t
+This type is defined as: @code{void *(*gcry_handler_alloc_t) (size_t n)}.
+@end deftp
+@deftp {Data type} gcry_handler_secure_check_t
+This type is defined as: @code{int *(*gcry_handler_secure_check_t) (const void *)}.
+@end deftp
+@deftp {Data type} gcry_handler_realloc_t
+This type is defined as: @code{void *(*gcry_handler_realloc_t) (void *p, size_t n)}.
+@end deftp
+@deftp {Data type} gcry_handler_free_t
+This type is defined as: @code{void *(*gcry_handler_free_t) (void *)}.
+@end deftp
+
+Special memory allocation functions can be installed with the
+following function:
+
+@deftypefun void gcry_set_allocation_handler (gcry_handler_alloc_t @var{func_alloc}, gcry_handler_alloc_t @var{func_alloc_secure}, gcry_handler_secure_check_t @var{func_secure_check}, gcry_handler_realloc_t @var{func_realloc}, gcry_handler_free_t @var{func_free})
+Install the provided functions and use them instead of the built-in
+functions for doing memory allocation.
+@end deftypefun
+
+@node Error handler
+@section Error handler
+
+The following functions may be used to register handler functions that
+are called by @acronym{Libgcrypt} in case certain error conditions
+occur.
+
+@deftp {Data type} gcry_handler_no_mem_t
+This type is defined as: @code{void (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)}
+@end deftp
+@deftypefun void gcry_set_outofcore_handler (gcry_handler_no_mem_t @var{func_no_mem}, void *@var{cb_data})
+This function registers @var{func_no_mem} as `out-of-core handler',
+which means that it will be called in the case of not having enough
+memory available.
+@end deftypefun
+
+@deftp {Data type} gcry_handler_error_t
+This type is defined as: @code{void (*gcry_handler_error_t) (void *, int, const char *)}
+@end deftp
+
+@deftypefun void gcry_set_fatalerror_handler (gcry_handler_error_t @var{func_error}, void *@var{cb_data})
+This function registers @var{func_error} as `error handler',
+which means that it will be called in error conditions.
+@end deftypefun
+
+@node Logging handler
+@section Logging handler
+
+@deftp {Data type} gcry_handler_log_t
+This type is defined as: @code{void (*gcry_handler_log_t) (void *, int, const char *, va_list)}
+@end deftp
+
+@deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})
+This function registers @var{func_log} as `logging handler', which
+means that it will be called in case @acronym{Libgcrypt} wants to log
+a message.
+@end deftypefun
+
+@c **********************************************************
+@c *******************  Ciphers  ****************************
+@c **********************************************************
+@c @include cipher-ref.texi
+@node Symmetric cryptography
+@chapter Symmetric cryptography
+
+The cipher functions are used for symmetrical cryptography,
+i.e. cryptography using a shared key.  The programming model follows
+an open/process/close paradigm and is in that similar to other
+building blocks provided by @acronym{Libgcrypt}.
+
+@menu
+* Available ciphers::           List of ciphers supported by the library.
+* Cipher modules::              How to work with cipher modules.
+* Available cipher modes::      List of cipher modes supported by the library.
+* Working with cipher handles::  How to perform operations related to cipher handles.
+* General cipher functions::    General cipher functions independent of cipher handles.
+@end menu
+
+@node Available ciphers
+@section Available ciphers
+
+@table @code
+@item GCRY_CIPHER_NONE
+This is not a real algorithm but used by some functions as error return.
+The value always evaluates to false.
+
+@item GCRY_CIPHER_IDEA
+This is the IDEA algorithm.  The constant is provided but there is
+currently no implementation for it because the algorithm is patented.
+
+@item GCRY_CIPHER_3DES
+Triple-DES with 3 Keys as EDE.  The key size of this algorithm is 168 but
+you have to pass 192 bits because the most significant bits of each byte
+are ignored.
+
+@item GCRY_CIPHER_CAST5
+CAST128-5 block cipher algorithm.  The key size is 128 bits.
+        
+@item GCRY_CIPHER_BLOWFISH
+The blowfish algorithm. The current implementation allows only for a key
+size of 128 bits.
+
+@item GCRY_CIPHER_SAFER_SK128
+Reserved and not currently implemented.
+
+@item GCRY_CIPHER_DES_SK          
+Reserved and not currently implemented.
+ 
+@item  GCRY_CIPHER_AES        
+@itemx GCRY_CIPHER_AES128
+@itemx GCRY_CIPHER_RIJNDAEL
+@itemx GCRY_CIPHER_RIJNDAEL128
+AES (Rijndael) with a 128 bit key.
+
+@item  GCRY_CIPHER_AES192     
+@itemx GCRY_CIPHER_RIJNDAEL128
+AES (Rijndael) with a 192 bit key.
+
+@item  GCRY_CIPHER_AES256 
+@itemx GCRY_CIPHER_RIJNDAEL256
+AES (Rijndael) with a 256 bit key.
+    
+@item  GCRY_CIPHER_TWOFISH
+The Twofish algorithm with a 256 bit key.
+    
+@item  GCRY_CIPHER_TWOFISH128
+The Twofish algorithm with a 128 bit key.
+    
+@item  GCRY_CIPHER_ARCFOUR   
+An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm.
+Note that this is a stream cipher and must be used very carefully to
+avoid a couple of weaknesses. 
+
+@item  GCRY_CIPHER_DES       
+Standard DES with a 56 bit key. You need to pass 64 bit but the high
+bits of each byte are ignored.  Note, that this is a weak algorithm
+which can be broken in reasonable time using a brute force approach.
+
+@end table
+
+@node Cipher modules
+@section Cipher modules
+
+@acronym{Libgcrypt} makes it possible to load additional `cipher
+modules'; these cipher can be used just like the cipher algorithms
+that are built into the library directly.  For an introduction into
+extension modules, see @xref{Modules}.
+
+@deftp {Data type} gcry_cipher_spec_t
+This is the `module specification structure' needed for registering
+cipher modules, which has to be filled in by the user before it can be
+used to register a module.  It contains the following members:
+
+@table @code
+@item const char *name
+The primary name of the algorithm.
+@item const char **aliases
+A list of strings that are `aliases' for the algorithm.  The list must
+be terminated with a NULL element.
+@item gcry_cipher_oid_spec_t *oids
+A list of OIDs that are to be associated with the algorithm.  The
+list's last element must have it's `oid' member set to NULL.  See
+below for an explanation of this type.
+@item size_t blocksize
+The block size of the algorithm, in bytes.
+@item size_t keylen
+The length of the key, in bits.
+@item size_t contextsize
+The size of the algorithm-specific `context', that should be allocated
+for each handle.
+@item gcry_cipher_setkey_t setkey
+The function responsible for initializing a handle with a provided
+key.  See below for a description of this type.
+@item gcry_cipher_encrypt_t encrypt
+The function responsible for encrypting a single block.  See below for
+a description of this type.
+@item gcry_cipher_decrypt_t decrypt
+The function responsible for decrypting a single block.  See below for
+a description of this type.
+@item gcry_cipher_stencrypt_t stencrypt
+Like `encrypt', for stream ciphers.  See below for a description of
+this type.
+@item gcry_cipher_stdecrypt_t stdecrypt
+Like `decrypt', for stream ciphers.  See below for a description of
+this type.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_cipher_oid_spec_t
+This type is used for associating a user-provided algorithm
+implementation with certain OIDs.  It contains the following members:
+@table @code
+@item const char *oid
+Textual representation of the OID.
+@item int mode
+Cipher mode for which this OID is valid.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_cipher_setkey_t
+Type for the `setkey' function, defined as: gcry_err_code_t
+(*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned
+keylen)
+@end deftp
+
+@deftp {Data type} gcry_cipher_encrypt_t
+Type for the `encrypt' function, defined as: gcry_err_code_t
+(*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const
+unsigned char *inbuf)
+@end deftp
+
+@deftp {Data type} gcry_cipher_decrypt_t
+Type for the `decrypt' function, defined as: gcry_err_code_t
+(*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const
+unsigned char *inbuf)
+@end deftp
+
+@deftp {Data type} gcry_cipher_stencrypt_t
+Type for the `stencrypt' function, defined as: gcry_err_code_t
+(*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, const
+unsigned char *, unsigned int n)
+@end deftp
+
+@deftp {Data type} gcry_cipher_stdecrypt_t
+Type for the `stdecrypt' function, defined as: gcry_err_code_t
+(*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, const
+unsigned char *, unsigned int n)
+@end deftp
+
+@deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module})
+
+Register a new cipher module whose specification can be found in
+@var{cipher}.  On success, a new algorithm ID is stored in
+@var{algorithm_id} and a pointer representing this module is stored
+in @var{module}.
+@end deftypefun
+
+@deftypefun void gcry_cipher_unregister (gcry_module_t @var{module})
+Unregister the cipher identified by @var{module}, which must have been
+registered with gcry_cipher_register.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length})
+Get a list consisting of the IDs of the loaded cipher modules.  If
+@var{list} is zero, write the number of loaded cipher modules to
+@var{list_length} and return.  If @var{list} is non-zero, the first
+*@var{list_length} algorithm IDs are stored in @var{list}, which must
+be of according size.  In case there are less cipher modules than
+*@var{list_length}, *@var{list_length} is updated to the correct
+number.
+@end deftypefun
+
+@node Available cipher modes
+@section Available cipher modes
+
+@table @code
+@item GCRY_CIPHER_MODE_NONE
+No mode specified, may be set later using other functions.  The value
+of this constant is always 0.
+
+@item GCRY_CIPHER_MODE_ECB
+Electronic Codebook mode.  
+
+@item GCRY_CIPHER_MODE_CFB
+Cipher Feedback mode.
+
+@item  GCRY_CIPHER_MODE_CBC
+Cipher Block Chaining mode.
+
+@item GCRY_CIPHER_MODE_STREAM
+Stream mode, only to be used with stream cipher algorithms.
+
+@item GCRY_CIPHER_MODE_OFB
+Outer Feedback mode.
+
+@item  GCRY_CIPHER_MODE_CTR
+Counter mode.
+
+@end table
+
+@node Working with cipher handles
+@section Working with cipher handles
+
+To use a cipher algorithm, you must first allocate an according
+handle.  This is to be done using the open function:
+
+@deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd}, int @var{algo}, int @var{mode}, unsigned int @var{flags})
+
+This function creates the context handle required for most of the
+other cipher functions and returns a handle to it in `hd'.  In case of
+an error, an according error code is returned.
+
+The ID of algorithm to use must be specified via @var{algo}.  See
+@xref{Available ciphers}, for a list of supported ciphers and the
+according constants.
+
+Besides using the constants directly, the function
+@code{gcry_cipher_map_name} may be used to convert the textual name of
+an algorithm into the according numeric ID.
+
+The cipher mode to use must be specified via @var{mode}.  See
+@xref{Available cipher modes}, for a list of supported cipher modes
+and the according constants.  Note, that some modes do not work
+together with all algorithms.
+
+The third argument @var{flags} can either be passed as @code{0} or as
+the bit-wise OR of the following constants.
+
+@table @code
+@item GCRY_CIPHER_SECURE
+Make sure that all operations are allocated in secure memory.  This is
+useful, when the key material is highly confidential.
+@item GCRY_CIPHER_ENABLE_SYNC
+This flag enables the CFB sync mode, which is a special feature of
+@acronym{Libgcrypt}'s CFB mode implementation to allow for OpenPGP's CFB variant. 
+See @code{gcry_cipher_sync}.
+@item GCRY_CIPHER_CBC_CTS
+Enable cipher text stealing (CTS) for the CBC mode.  Cannot be used
+simultaneous as GCRY_CIPHER_CBC_MAC
+@item GCRY_CIPHER_CBC_MAC
+Compute CBC-MAC keyed checksums.  This is the same as CBC mode, but
+only output the last block.  Cannot be used simultaneous as
+GCRY_CIPHER_CBC_CTS.
+@end table
+@end deftypefun 
+
+Use the following function to release an existing handle:
+
+@deftypefun void gcry_cipher_close (gcry_cipher_hd_t @var{h})
+
+This function releases the context created by @code{gcry_cipher_open}.
+@end deftypefun
+
+In order to use a handle for performing cryptographic operations, a
+`key' has to be set first:
+
+@deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
+
+Set the key @var{k} used for encryption or decryption in the context
+denoted by the handle @var{h}.  The length @var{l} of the key @var{k}
+must match the required length of the algorithm set for this context or
+be in the allowed range for algorithms with variable key size.  The
+function checks this and returns an error if there is a problem.  A
+caller should always check for an error.
+
+Note, this is currently implemented as a macro but may be changed to a
+function in the future.
+@end deftypefun
+
+Most crypto modes requires an initialization vector (IV), which
+usually is a non-secret random string acting as a kind of salt value.
+The CTR mode requires a counter, which is also similar to a salt
+value.  To set the IV or CTR, use these functions:
+
+@deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
+
+Set the initialization vector used for encryption or decryption. The
+vector is passed as the buffer @var{K} of length @var{l} and copied to
+internal data structures.  The function checks that the IV matches the
+requirement of the selected algorithm and mode.  Note, that this is
+implemented as a macro.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, void *@var{c}, size_t @var{l})
+
+Set the counter vector used for encryption or decryption. The counter
+is passed as the buffer @var{c} of length @var{l} and copied to
+internal data structures.  The function checks that the counter
+matches the requirement of the selected algorithm (i.e., it must be
+the same size as the block size).  Note, that this is implemented as a
+macro.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
+
+Set the given handle's context back to the state it had after the last
+call to gcry_cipher_setkey and clear the initialization vector.
+
+Note, that gcry_cipher_reset is implemented as a macro.
+@end deftypefun
+
+The actual encryption and decryption is done by using one of the
+following functions.  They may be used as often as required to process
+all the data.
+
+@deftypefun gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t @var{h}, void *{out}, size_t @var{outsize}, const void *@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.  It uses the cipher
+context already setup and described by the handle @var{h}.  There are 2
+ways to use the function: If @var{in} is passed as @code{NULL} and
+@var{inlen} is @code{0}, in-place encryption of the data in @var{out} or
+length @var{outsize} takes place.  With @var{in} being not @code{NULL},
+@var{inlen} bytes are encrypted to the buffer @var{out} which must have
+at least a size of @var{inlen}.  @var{outlen} must be set to the
+allocated size of @var{out}, so that the function can check that there
+is sufficient space. Note, that overlapping buffers are not allowed.
+
+Depending on the selected algorithms and encryption mode, the length of
+the buffers must be a multiple of the block size.
+
+The function returns @code{0} on success or an error code.
+@end deftypefun
+
+
+@deftypefun gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t @var{h}, void *{out}, size_t @var{outsize}, const void *@var{in}, size_t @var{inlen})
+
+@code{gcry_cipher_decrypt} is used to decrypt the data.  This function
+can either work in place or with two buffers.  It uses the cipher
+context already setup and described by the handle @var{h}.  There are 2
+ways to use the function: If @var{in} is passed as @code{NULL} and
+@var{inlen} is @code{0}, in-place decryption of the data in @var{out} or
+length @var{outsize} takes place.  With @var{in} being not @code{NULL},
+@var{inlen} bytes are decrypted to the buffer @var{out} which must have
+at least a size of @var{inlen}.  @var{outlen} must be set to the
+allocated size of @var{out}, so that the function can check that there
+is sufficient space. Note, that overlapping buffers are not allowed.
+
+Depending on the selected algorithms and encryption mode, the length of
+the buffers must be a multiple of the block size.
+
+The function returns @code{0} on success or an error code.
+@end deftypefun
+
+
+OpenPGP (as defined in RFC-2440) requires a special sync operation in
+some places, the following function is used for this:
+
+@deftypefun gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})
+
+Perform the OpenPGP sync operation on context @var{h}. Note, that this
+is a no-op unless the context was created with the flag
+@code{GCRY_CIPHER_ENABLE_SYNC}
+@end deftypefun
+
+Some of the described functions are implemented as macros utilizing a
+catch-all control function.  This control function is rarely used
+directly but there is nothing which would inhibit it:
+
+@deftypefun gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t @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 specialized functions or
+macros are used for this purpose.  The semantics of the function and its
+parameters depends on the the command @var{cmd} and the passed context
+handle @var{h}.  Please see the comments in the source code
+(@code{src/global.c}) for details.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_cipher_info (gcry_cipher_hd_t @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
+
+@node General cipher functions
+@section General cipher functions
+
+To work with the algorithms, several functions are available to map
+algorithm names to the internal identifiers, as well as ways to
+retrieve information about an algorithm or the current cipher context.
+
+@deftypefun gcry_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
+
+This function is used to retrieve information on a specific algorithm.
+You pass the cipher algorithm ID as @var{algo} and the type of
+information requested as @var{what}. The result is either returned as
+the return code of the function or copied to the provided @var{buffer}
+whose allocated length must be available in an integer variable with the
+address passed in @var{nbytes}.  This variable will also receive the
+actual used length of the buffer. 
+
+Here is a list of supported codes for @var{what}:
+
+@c begin constants for gcry_cipher_algo_info
+@table @code
+@item GCRYCTL_GET_KEYLEN:
+Return the length of the key. If the algorithm supports multiple key
+lengths, the maximum supported value is returned.  The length is
+returned as number of octets (bytes) and not as number of bits in
+@var{nbytes}; @var{buffer} must be zero.
+
+@item GCRYCTL_GET_BLKLEN:
+Return the block length of the algorithm.  The length is returned as a
+number of octets in @var{nbytes}; @var{buffer} must be zero.
+
+@item GCRYCTL_TEST_ALGO:
+Returns @code{0} when the specified algorithm is available for use.
+@var{buffer} and @var{nbytes} must be zero.
+ 
+@end table  
+@c end constants for gcry_cipher_algo_info
+
+@end deftypefun
+@c end gcry_cipher_algo_info
+
+@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 is not known or another
+error occurred, an empty string is returned.  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 *******************  Hash Functions  *********************
+@c **********************************************************
+@node Hashing
+@chapter Hashing
+
+@acronym{Libgcrypt} provides an easy and consistent to use interface
+for hashing.  Hashing is buffered and several hash algorithms can be
+updated at once.  It is possible to calculate a MAC using the same
+routines.  The programming model follows an open/process/close
+paradigm and is in that similar to other building blocks provided by
+@acronym{Libgcrypt}.
+
+For convenience reasons, a few cyclic redundancy check value operations
+are also supported.
+
+@menu
+* Available hash algorithms::   List of hash algorithms supported by the library.
+* Hash algorithm modules::      How to work with hash algorithm modules.
+* Working with hash algorithms::  List of functions related to hashing.
+@end menu
+
+@node Available hash algorithms
+@section Available hash algorithms
+
+@c begin table of hash algorithms
+@table @code
+@item GCRY_MD_NONE
+This is not a real algorithm but used by some functions as an error
+return value.  This constant is guaranteed to have the value @code{0}.
+
+@item GCRY_MD_SHA1
+This is the SHA-1 algorithm which yields a message digest of 20 bytes.
+
+@item GCRY_MD_RMD160
+This is the 160 bit version of the RIPE message digest (RIPE-MD-160).
+Like SHA-1 it also yields a digest of 20 bytes.
+
+@item GCRY_MD_MD5
+This is the well known MD5 algorithm, which yields a message digest of
+16 bytes. 
+
+@item GCRY_MD_MD4
+This is the MD4 algorithm, which yields a message digest of 16 bytes.
+
+@item GCRY_MD_MD2
+This is an reserved identifier for MD-2; there is no implementation yet.
+
+@item GCRY_MD_TIGER
+This is the TIGER/192 algorithm which yields a message digest of 24 bytes.
+
+@item GCRY_MD_HAVAL
+This is an reserved for the HAVAL algorithm with 5 passes and 160
+bit. It yields a message digest of 20 bytes.  Note that there is no
+implementation yet available.
+
+@item GCRY_MD_SHA256
+This is the SHA-256 algorithm which yields a message digest of 32 bytes.
+See FIPS 180-2 for the specification.
+
+@item GCRY_MD_SHA384
+This is reserved for SHA-2 with 384 bits. It yields a message digest of
+48 bytes.  Note that there is no implementation yet available.
+
+@item GCRY_MD_SHA512
+This is reserved for SHA-2 with 512 bits. It yields a message digest of
+64 bytes.  Note that there is no implementation yet available.
+
+@item GCRY_MD_CRC32
+This is the ISO 3309 and ITU-T V.42 cyclic redundancy check.  It
+yields an output of 4 bytes.
+
+@item GCRY_MD_CRC32_RFC1510
+This is the above cyclic redundancy check function, as modified by RFC
+1510.  It yields an output of 4 bytes.
+
+@item GCRY_MD_CRC24_RFC2440
+This is the OpenPGP cyclic redundancy check function.  It yields an
+output of 3 bytes.
+
+@end table
+@c end table of hash algorithms
+
+@node Hash algorithm modules
+@section Hash algorithm modules
+
+@acronym{Libgcrypt} makes it possible to load additional `message
+digest modules'; these cipher can be used just like the message digest
+algorithms that are built into the library directly.  For an
+introduction into extension modules, see @xref{Modules}.
+
+@deftp {Data type} gcry_md_spec_t
+This is the `module specification structure' needed for registering
+message digest modules, which has to be filled in by the user before
+it can be used to register a module.  It contains the following
+members:
+
+@table @code
+@item const char *name
+The primary name of this algorithm.
+@item unsigned char *asnoid
+Array of bytes that form the ASN OID.
+@item int asnlen
+Length of bytes in `asnoid'.
+@item gcry_md_oid_spec_t *oids
+A list of OIDs that are to be associated with the algorithm.  The
+list's last element must have it's `oid' member set to NULL.  See
+below for an explanation of this type.  See below for an explanation
+of this type.
+@item int mdlen
+Length of the message digest algorithm.  See below for an explanation
+of this type.
+@item gcry_md_init_t init
+The function responsible for initializing a handle.  See below for an
+explanation of this type.
+@item gcry_md_write_t write
+The function responsible for writing data into a message digest
+context.  See below for an explanation of this type.
+@item gcry_md_final_t final
+The function responsible for `finalizing' a message digest context.
+See below for an explanation of this type.
+@item gcry_md_read_t read
+The function responsible for reading out a message digest result.  See
+below for an explanation of this type.
+@item size_t contextsize
+The size of the algorithm-specific `context', that should be
+allocated for each handle.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_md_oid_spec_t
+This type is used for associating a user-provided algorithm
+implementation with certain OIDs.  It contains the following members:
+
+@table @code
+@item const char *oidstring
+Textual representation of the OID.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_md_init_t
+Type for the `init' function, defined as: void (*gcry_md_init_t) (void
+*c)
+@end deftp
+
+@deftp {Data type} gcry_md_write_t
+Type for the `write' function, defined as: void (*gcry_md_write_t)
+(void *c, unsigned char *buf, size_t nbytes)
+@end deftp
+
+@deftp {Data type} gcry_md_final_t
+Type for the `final' function, defined as: void (*gcry_md_final_t)
+(void *c)
+@end deftp
+
+@deftp {Data type} gcry_md_read_t
+Type for the `read' function, defined as: unsigned char
+*(*gcry_md_read_t) (void *c)
+@end deftp
+
+@deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})
+
+Register a new digest module whose specification can be found in
+@var{digest}.  On success, a new algorithm ID is stored in
+@var{algorithm_id} and a pointer representing this module is stored
+in @var{module}.
+@end deftypefun
+
+@deftypefun void gcry_md_unregister (gcry_module_t @var{module})
+Unregister the digest identified by @var{module}, which must have been
+registered with gcry_md_register.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length})
+Get a list consisting of the IDs of the loaded message digest modules.
+If @var{list} is zero, write the number of loaded message digest
+modules to @var{list_length} and return.  If @var{list} is non-zero,
+the first *@var{list_length} algorithm IDs are stored in @var{list},
+which must be of according size.  In case there are less message
+digests modules than *@var{list_length}, *@var{list_length} is updated
+to the correct number.
+@end deftypefun
+
+@node Working with hash algorithms
+@section Working with hash algorithms
+
+To use most of these function it is necessary to create a context;
+this is done using:
+
+@deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})
+
+Create a message digest object for algorithm @var{algo}.  @var{flags}
+may be given as an bitwise OR of constants described below.  @var{algo}
+may be given as @code{0} if the algorithms to use are later set using
+@code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid
+handle or NULL.
+
+For a list of supported algorithms, see @xref{Available hash
+algorithms}.
+
+The flags allowed for @var{mode} are:
+
+@c begin table of hash flags
+@table @code
+@item GCRY_MD_FLAG_SECURE
+Allocate all buffers and the resulting digest in "secure memory".  Use
+this is the hashed data is highly confidential.
+
+@item GCRY_MD_FLAG_HMAC
+Turn the algorithm into a HMAC message authentication algorithm.  This
+does only work if just one algorithm is enabled for the handle and
+SHA-384 and SHA512 is not used.  Note that the function
+@code{gcry_md_setkey} must be used set the MAC key.  If you want CBC
+message authentication codes based on a cipher, see @xref{Working with
+cipher handles}.
+
+@end table
+@c begin table of hash flags
+
+You may use the function @code{gcry_md_is_enabled} to later check
+whether an algorithm has been enabled.
+
+@end deftypefun
+@c end function gcry_md_open
+
+If you want to calculate several hash algorithms at the same time, you
+have to use the following function right after the @code{gcry_md_open}:
+
+@deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
+
+Add the message digest algorithm @var{algo} to the digest object
+described by handle @var{h}.  Duplicated enabling of algorithms is
+detected and ignored.
+@end deftypefun
+
+If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must
+be set using the function:
+
+@deftypefun gcry_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key}, size_t @var{keylen})
+
+For use with the HMAC feature, set the MAC key to the value of @var{key}
+of length @var{keylen}.
+@end deftypefun
+
+
+After you are done with the hash calculation, you should release the
+resources by using:
+
+@deftypefun void gcry_md_close (gcry_md_hd_t @var{h})
+
+Release all resources of hash context @var{h}.  @var{h} should not be
+used after a call to this function.  A @code{NULL} passed as @var{h} is
+ignored.
+
+@end deftypefun
+
+Often you have to do several hash operations using the same algorithm.
+To avoid the overhead of creating and releasing context, a reset function
+is provided:
+
+@deftypefun void gcry_md_reset (gcry_md_hd_t @var{h})
+
+Reset the current context to its initial state.  This is effectively
+identical to a close followed by an open and enabling all currently
+active algorithms.
+@end deftypefun
+
+
+Often it is necessary to start hashing some data and than continue to
+hash different data.  To avoid hashing the same data several times (which
+might not even be possible if the data is received from a pipe), a
+snapshot of the current hash context can be taken and turned into a new
+context:
+
+@deftypefun gcry_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src})
+
+Create a new digest object as an exact copy of the object described by
+handle @var{handle_src} and store it in @var{handle_dst}.  The context
+is not reset and you can continue to hash data using this context and
+independently using the original context.
+@end deftypefun
+
+
+Now that we have prepared everything to calculate hashes, its time to
+see how it is actually done.  There are 2  ways for this, one to
+update the hash with a block of memory and one macro to update the hash
+by just one character.  Both may be used intermixed.
+
+@deftypefun void gcry_md_write (gcry_md_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
+
+Pass @var{length} bytes of the data in @var{buffer} to the digest object
+with handle @var{h} to update the digest values. This
+function should be used for large blocks of data.
+@end deftypefun
+
+@deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c})
+
+Pass the byte in @var{c} to the digest object with handle @var{h} to
+update the digest value.  This is an efficient function, implemented as
+a macro to buffer the data before an actual update. 
+@end deftypefun
+
+The semantics of the hash functions don't allow to read out intermediate
+message digests because the calculation must be finalized fist.  This
+finalization may for example include the number of bytes hashed in the
+message digest.  
+
+@deftypefun void gcry_md_final (gcry_md_hd_t @var{h})
+
+Finalize the message digest calculation.  This is not really needed
+because @code{gcry_md_read} does this implicitly.  After this has been
+done no further updates (by means of @code{gcry_md_write} or
+@code{gcry_md_putc} are allowed.  Only the first call to this function
+has an effect. It is implemented as a macro.
+@end deftypefun
+
+The way to read out the calculated message digest is by using the
+function:
+
+@deftypefun unsigned char *gcry_md_read (gcry_md_hd_t @var{h}, int @var{algo})
+
+@code{gcry_md_read} returns the message digest after finalizing the
+calculation.  This function may be used as often as required but it will
+always return the same value for one handle.  The returned message digest
+is allocated within the message context and therefore valid until the
+handle is released or reseted (using @code{gcry_md_close} or
+@code{gcry_md_reset}.  @var{algo} may be given as 0 to return the only
+enabled message digest or it may specify one of the enabled algorithms.
+The function does return @code{NULL} if the requested algorithm has not
+been enabled.
+@end deftypefun
+
+Because it is often necessary to get the message digest of one block of
+memory, a fast convenience function is available for this task: 
+
+@deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const cvoid *@var{buffer}, size_t @var{length});
+
+@code{gcry_md_hash_buffer} is a shortcut function to calculate a message
+digest of a buffer.  This function does not require a context and
+immediately returns the message digest of the @var{length} bytes at
+@var{buffer}.  @var{digest} must be allocated by the caller, large
+enough to hold the message digest yielded by the the specified algorithm
+@var{algo}.  This required size may be obtained by using the function
+@code{gcry_md_get_algo_dlen}.
+
+Note, that this function will abort the process if an unavailable
+algorithm is used.
+@end deftypefun
+
+@c ***********************************
+@c ***** MD info functions ***********
+@c ***********************************
+
+Hash algorithms are identified by internal algorithm numbers (see
+@code{gcry_md_open} for a list.  However, in most applications they are
+used by names, so 2 functions are available to map between string
+representations and hash algorithm identifiers.
+
+@deftypefun const char *gcry_md_algo_name (int @var{algo})
+
+Map the digest algorithm id @var{algo} to a string representation of the
+algorithm name.  For unknown algorithms this functions returns an
+empty string.  This function should not be used to test for the
+availability of an algorithm.
+@end deftypefun
+
+@deftypefun int gcry_md_map_name (const char *@var{name})
+
+Map the algorithm with @var{name} to a digest algorithm identifier.
+Returns 0 if the algorithm name is not known.  Names representing
+@acronym{ASN.1} object identifiers are recognized if the @acronym{IETF}
+dotted format is used and the OID is prefixed with either "@code{oid.}"
+or "@code{OID.}".  For a list of supported OIDs, see the source code at
+@file{cipher/md.c}. This function should not be used to test for the
+availability of an algorithm.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
+
+Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the
+user allocated @var{buffer}. @var{length} must point to variable with
+the available size of @var{buffer} and receives after return the
+actual size of the returned OID.  The returned error code may be
+@code{GPG_ERR_TOO_SHORT} if the provided buffer is to short to receive
+the OID; it is possible to call the function with @code{NULL} for
+@var{buffer} to have it only return the required size.  The function
+returns 0 on success.
+
+@end deftypefun
+
+
+To test whether an algorithm is actually available for use, the
+following macro should be used:
+
+@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo}) 
+
+The macro returns 0 if the algorithm @var{algo} is available for use.
+@end deftypefun
+
+If the length of a message digest is not known, it can be retrieved
+using the following function:
+
+@deftypefun unsigned int gcry_md_get_algo_dlen (int @var{algo})
+
+Retrieve the length in bytes of the digest yielded by algorithm
+@var{algo}.  This is often used prior to @code{gcry_md_read} to allocate
+sufficient memory for the digest.
+@end deftypefun
+
+
+In some situations it might be hard to remember the algorithm used for
+the ongoing hashing. The following function might be used to get that
+information:
+
+@deftypefun int gcry_md_get_algo (gcry_md_hd_t @var{h})
+
+Retrieve the algorithm used with the handle @var{h}. Note, that this
+does not work reliable if more than one algorithm is enabled in @var{h}.
+@end deftypefun
+
+The following macro might also be useful:
+
+@deftypefun int gcry_md_is_secure (gcry_md_hd_t @var{h})
+
+This function returns true when the digest object @var{h} is allocated
+in "secure memory"; i.e. @var{h} was created with the
+@code{GCRY_MD_FLAG_SECURE}.
+@end deftypefun
+
+@deftypefun int gcry_md_is_enabled (gcry_md_hd_t @var{h}, int @var{algo})
+
+This function returns true when the algorithm @var{algo} has been
+enabled for the digest object @var{h}.
+@end deftypefun
+
+
+
+Tracking bugs related to hashing is often a cumbersome task which
+requires to add a lot of printf statements into the code.  @acronym{Libgcrypt}
+provides an easy way to avoid this.  The actual data hashed can be
+written to files on request.  The following 2 macros should be used to
+implement such a debugging facility:
+
+@deftypefun void gcry_md_start_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
+
+Enable debugging for the digest object with handle @var{h}.  This
+creates create files named @file{dbgmd-<n>.<string>} while doing the
+actual hashing.  @var{suffix} is the string part in the filename.  The
+number is a counter incremented for each new hashing.  The data in the
+file is the raw data as passed to @code{gcry_md_write} or
+@code{gcry_md_putc}.
+@end deftypefun
+
+
+@deftypefun void gcry_md_stop_debug (gcry_md_hd_t @var{h}, int @var{reserved})
+
+Stop debugging on handle @var{h}.  @var{reserved} should be specified as
+0.  This function is usually not required because @code{gcry_md_close}
+does implicitly stop debugging.
+@end deftypefun
+
+
+@c **********************************************************
+@c *******************  Public Key  *************************
+@c **********************************************************
+@node Public Key cryptography (I)
+@chapter Public Key cryptography (I)
+
+Public key cryptography, also known as asymmetric cryptography, is an
+easy way for key management and to provide digital signatures.
+@acronym{Libgcrypt} provides two completely different interfaces to
+public key cryptography, this chapter explains the one based on
+S-expressions.
+
+@menu
+* Available algorithms::        Algorithms supported by the library.
+* Used S-expressions::          Introduction into the used S-expression.
+* Public key modules::          How to work with public key modules.
+* Cryptographic Functions::     Functions for performing the cryptographic actions.
+* General public-key related Functions::  General functions, not implementing any cryptography.
+@end menu
+
+@node Available algorithms
+@section Available algorithms
+
+@acronym{Libgcrypt} supports the RSA (Rivest-Shamir-Adleman) algorithms as well
+as DSA (Digital Signature Algorithm) and ElGamal.  The versatile
+interface allows to add more algorithms in the future.
+
+@node Used S-expressions
+@section Used S-expressions
+
+@acronym{Libgcrypt}'s API for asymmetric cryptography is based on data
+structures called S-expressions (see XXXX) and does not work with
+contexts as most of the other building blocks of @acronym{Libgcrypt}
+do.
+
+The following information are stored in S-expressions:
+
+@table @asis
+@item keys
+
+@item plain text data
+
+@item encrypted data
+
+@item signatures
+
+@end table
+
+@noindent
+To describe how @acronym{Libgcrypt} expect keys, we use some examples. Note that
+words in
+@ifnottex
+uppercase
+@end ifnottex
+@iftex
+italics
+@end iftex
+indicate parameters whereas lowercase words are literals.
+
+@example
+(private-key
+  (dsa
+    (p @var{p-mpi})
+    (q @var{q-mpi})
+    (g @var{g-mpi})
+    (y @var{y-mpi})
+    (x @var{x-mpi})))
+@end example
+
+@noindent
+This specifies a DSA private key with the following parameters:
+
+@table @var
+@item p-mpi
+DSA prime @math{p}.
+@item q-mpi
+DSA group order @math{q} (which is a prime divisor of @math{p-1}).
+@item g-mpi
+DSA group generator @math{g}.
+@item y-mpi
+DSA public key value @math{y = g^x \bmod p}.
+@item x-mpi
+DSA secret exponent x.
+@end table
+
+All the MPI values are  expected to be in @code{GCRYMPI_FMT_USG} format.
+The public key is similar with "private-key" replaced by "public-key"
+and no @var{x-mpi}.
+
+An easy way to create such an S-expressions is by using
+@code{gcry_sexp_build} which allows to pass a string with printf-like
+escapes to insert MPI values.
+
+@noindent
+Here is an example for an RSA key:
+
+@example
+(private-key
+  (rsa
+    (n @var{n-mpi})
+    (e @var{e-mpi})
+    (d @var{d-mpi})
+    (p @var{p-mpi})
+    (q @var{q-mpi})
+    (u @var{u-mpi})
+@end example
+
+@noindent
+with
+
+@table @var
+@item n-mpi
+RSA public modulus @math{n}.
+@item e-mpi
+RSA public exponent @math{e}.
+@item d-mpi
+RSA secret exponent @math{d = e^{-1} \bmod (p-1)(q-1)}.
+@item p-mpi
+RSA secret prime @math{p}.
+@item q-mpi
+RSA secret prime @math{q} with @math{q > p}.
+@item u-mpi
+multiplicative inverse @math{u = p^{-1} \bmod q}.
+@end table
+
+@node Public key modules
+@section Public key modules
+
+@acronym{Libgcrypt} makes it possible to load additional `public key
+modules'; these public key algorithms can be used just like the
+algorithms that are built into the library directly.  For an
+introduction into extension modules, see @xref{Modules}.
+
+@deftp {Data type} gcry_pk_spec_t
+This is the `module specification structure' needed for registering
+public key modules, which has to be filled in by the user before it
+can be used to register a module.  It contains the following members:
+
+@table @code
+@item const char *name
+The primary name of this algorithm.
+@item char **aliases
+A list of strings that are `aliases' for the algorithm.  The list
+must be terminated with a NULL element.
+@item const char *elements_pkey
+String containing the one-letter names of the MPI values contained in
+a public key.
+@item const char *element_skey
+String containing the one-letter names of the MPI values contained in
+a secret key.
+@item const char *elements_enc
+String containing the one-letter names of the MPI values that are the
+result of an encryption operation using this algorithm.
+@item const char *elements_sig
+String containing the one-letter names of the MPI values that are the
+result of a sign operation using this algorithm.
+@item const char *elements_grip
+String containing the one-letter names of the MPI values that are to
+be included in the `key grip'.
+@item int use
+The bitwise-OR of the following flags, depending on the abilities of
+the algorithm:
+@table @code
+@item GCRY_PK_USAGE_SIGN
+The algorithm supports signing and verifying of data.
+@item GCRY_PK_USAGE_ENCR
+The algorithm supports the encryption and decryption of data.
+@end table
+@item gcry_pk_generate_t generate
+The function responsible for generating a new key pair.  See below for
+a description of this type.
+@item gcry_pk_check_secret_key_t check_secret_key
+The function responsible for checking the sanity of a provided secret
+key.  See below for a description of this type.
+@item gcry_pk_encrypt_t encrypt
+The function responsible for encrypting data.  See below for a
+description of this type.
+@item gcry_pk_decrypt_t decrypt
+The function responsible for decrypting data.  See below for a
+description of this type.
+@item gcry_pk_sign_t sign
+The function responsible for signing data.  See below for a description
+of this type.
+@item gcry_pk_verify_t verify
+The function responsible for verifying that the provided signature
+matches the provided data.  See below for a description of this type.
+@item gcry_pk_get_nbits_t get_nbits
+The function responsible for returning the number of bits of a provided
+key.  See below for a description of this type.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_pk_generate_t
+Type for the `generate' function, defined as: gcry_err_code_t
+(*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long
+use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors)
+@end deftp
+
+@deftp {Data type} gcry_pk_check_secret_key_t
+Type for the `check_secret_key' function, defined as: gcry_err_code_t
+(*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey)
+@end deftp
+
+@deftp {Data type} gcry_pk_encrypt_t
+Type for the `encrypt' function, defined as: gcry_err_code_t
+(*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
+gcry_mpi_t *pkey, int flags)
+@end deftp
+
+@deftp {Data type} gcry_pk_decrypt_t
+Type for the `decrypt' function, defined as: gcry_err_code_t
+(*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data,
+gcry_mpi_t *skey, int flags)
+@end deftp
+
+@deftp {Data type} gcry_pk_sign_t
+Type for the `sign' function, defined as: gcry_err_code_t
+(*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
+gcry_mpi_t *skey)
+@end deftp
+
+@deftp {Data type} gcry_pk_verify_t
+Type for the `verify' function, defined as: gcry_err_code_t
+(*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data,
+gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev)
+@end deftp
+
+@deftp {Data type} gcry_pk_get_nbits_t
+Type for the `get_nbits' function, defined as: unsigned
+(*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey)
+@end deftp
+
+@deftypefun gcry_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module})
+
+Register a new public key module whose specification can be found in
+@var{pubkey}.  On success, a new algorithm ID is stored in
+@var{algorithm_id} and a pointer representing this module is stored
+in @var{module}.
+@end deftypefun
+
+@deftypefun void gcry_pk_unregister (gcry_module_t @var{module})
+Unregister the public key module identified by @var{module}, which
+must have been registered with gcry_pk_register.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_pk_list (int *@var{list}, int *@var{list_length})
+Get a list consisting of the IDs of the loaded pubkey modules.  If
+@var{list} is zero, write the number of loaded pubkey modules to
+@var{list_length} and return.  If @var{list} is non-zero, the first
+*@var{list_length} algorithm IDs are stored in @var{list}, which must
+be of according size.  In case there are less pubkey modules than
+*@var{list_length}, *@var{list_length} is updated to the correct
+number.
+@end deftypefun
+
+@node Cryptographic Functions
+@section Cryptographic Functions
+
+@noindent
+Note, that we will in future allow to use keys without p,q and u
+specified and may also support other parameters for performance
+reasons. 
+
+@noindent
+
+Some functions operating on S-expressions support `flags', that
+influence the operation.  These flags have to be listed in a
+sub-S-expression named `flags'; the following flags are known:
+
+@table @var
+@item pkcs1
+Use PKCS#1 block type 2 padding.
+@item no-blinding
+Do not use a technique called `blinding', which is used by default in
+order to prevent leaking of secret information.  Blinding is only
+implemented by RSA, but it might be implemented by other algorithms in
+the future as well, when necessary.
+@end table
+
+@noindent
+Now that we know the key basics, we can carry on and explain how to
+encrypt and decrypt data.  In almost all cases the data is a random
+session key which is in turn used for the actual encryption of the real
+data.  There are 2 functions to do this:
+
+@deftypefun gcry_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}})
+
+Obviously a public key must be provided for encryption.  It is
+expected as an appropriate S-expression (see above) in @var{pkey}.
+The data to be encrypted can either be in the simple old format, which
+is a very simple S-expression consisting only of one MPI, or it may be
+a more complex S-expression which also allows to specify flags for
+operation, like e.g. padding rules.
+
+@noindent
+If you don't want to let @acronym{Libgcrypt} handle the padding, you must pass an
+appropriate MPI using this expression for @var{data}:
+
+@example 
+(data
+  (flags raw)
+  (value @var{mpi}))
+@end example
+
+@noindent
+This has the same semantics as the old style MPI only way.  @var{MPI} is
+the actual data, already padded appropriate for your protocol.  Most
+systems however use PKCS#1 padding and so you can use this S-expression
+for @var{data}:
+
+@example 
+(data
+  (flags pkcs1)
+  (value @var{block}))
+@end example
+
+@noindent
+Here, the "flags" list has the "pkcs1" flag which let the function know
+that it should provide PKCS#1 block type 2 padding.  The actual data to
+be encrypted is passed as a string of octets in @var{block}.  The
+function checks that this data actually can be used with the given key,
+does the padding and encrypts it.
+
+If the function could successfully perform the encryption, the return
+value will be 0 and a a new S-expression with the encrypted result is
+allocated and assign to the variable at the address of @var{r_ciph}.
+The caller is responsible to release this value using
+@code{gcry_sexp_release}.  In case of an error, an error code is
+returned and @var{r_ciph} will be set to @code{NULL}.
+
+@noindent
+The returned S-expression has this format when used with RSA:
+
+@example
+(enc-val
+  (rsa
+    (a @var{a-mpi})))
+@end example
+
+@noindent
+Where @var{a-mpi} is an MPI with the result of the RSA operation.  When
+using the ElGamal algorithm, the return value will have this format:
+
+@example
+(enc-val
+  (elg
+    (a @var{a-mpi})
+    (b @var{b-mpi})))
+@end example
+
+@noindent
+Where @var{a-mpi} and @var{b-mpi} are MPIs with the result of the
+ElGamal encryption operation.
+@end deftypefun
+@c end gcry_pk_encrypt
+
+@deftypefun gcry_error_t gcry_pk_decrypt (@w{gcry_sexp_t *@var{r_plain},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
+
+Obviously a private key must be provided for decryption.  It is expected
+as an appropriate S-expression (see above) in @var{skey}.  The data to
+be decrypted must match the format of the result as returned by
+@code{gcry_pk_encrypt}, but should be enlarged with a @code{flags}
+element:
+
+@example
+(enc-val
+  (flags)
+  (elg
+    (a @var{a-mpi})
+    (b @var{b-mpi})))
+@end example
+
+@noindent
+Note, that this function currently does not know of any padding
+methods and the caller must do any un-padding on his own.
+
+@noindent
+The function returns 0 on success or an error code.  The variable at the
+address of @var{r_plain} will be set to NULL on error or receive the
+decrypted value on success.  The format of @var{r_plain} is a
+simple S-expression part (i.e. not a valid one) with just one MPI if
+there was no @code{flags} element in @var{data}; if at least an empty
+@code{flags} is passed in @var{data}, the format is:
+
+@example
+(value @var{plaintext})
+@end example
+@end deftypefun
+@c end gcry_pk_decrypt
+
+
+Another operation commonly performed using public key cryptography is
+signing data.  In some sense this is even more important than
+encryption because digital signatures are an important instrument for
+key management.  @acronym{Libgcrypt} supports digital signatures using
+2 functions, similar to the encryption functions:
+
+@deftypefun gcry_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
+
+This function creates a digital signature for @var{data} using the
+private key @var{skey} and place it into the variable at the address of
+@var{r_sig}.  @var{data} may either be the simple old style S-expression
+with just one MPI or a modern and more versatile S-expression which
+allows to let @acronym{Libgcrypt} handle padding:
+
+@example 
+ (data
+  (flags pkcs1)
+  (hash @var{hash-algo} @var{block}))
+@end example
+
+@noindent
+This example requests to sign the data in @var{block} after applying
+PKCS#1 block type 1 style padding.  @var{hash-algo} is a string with the
+hash algorithm to be encoded into the signature, this may be any hash
+algorithm name as supported by @acronym{Libgcrypt}.  Most likely, this will be
+"sha1", "rmd160" or "md5".  It is obvious that the length of @var{block}
+must match the size of that message digests; the function checks that
+this and other constraints are valid.
+
+@noindent
+If PKCS#1 padding is not required (because the caller does already
+provide a padded value), either the old format or better the following
+format should be used:
+
+@example
+(data
+  (flags raw)
+  (value @var{mpi}))
+@end example
+
+@noindent
+Here, the data to be signed is directly given as an @var{MPI}.
+
+@noindent
+The signature is returned as a newly allocated S-expression in
+@var{r_sig} using this format for RSA:
+
+@example
+(sig-val
+  (rsa
+    (s @var{s-mpi})))
+@end example
+
+Where @var{s-mpi} is the result of the RSA sign operation.  For DSA the
+S-expression returned is:
+
+@example
+(sig-val
+  (dsa
+    (r @var{r-mpi})
+    (s @var{s-mpi})))
+@end example
+
+Where @var{r-mpi} and @var{s-mpi} are the result of the DSA sign
+operation.  For ElGamal signing (which is slow, yields large numbers
+and probably is not as secure as the other algorithms), the same format is
+used with "elg" replacing "dsa".
+@end deftypefun
+@c end gcry_pk_sign
+
+@noindent
+The operation most commonly used is definitely the verification of a
+signature.  @acronym{Libgcrypt} provides this function:
+
+@deftypefun gcry_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})
+
+This is used to check whether the signature @var{sig} matches the
+@var{data}.  The public key @var{pkey} must be provided to perform this
+verification.  This function is similar in its parameters to
+@code{gcry_pk_sign} with the exceptions that the public key is used
+instead of the private key and that no signature is created but a
+signature, in a format as created by @code{gcry_pk_sign}, is passed to
+the function in @var{sig}.
+
+@noindent
+The result is 0 for success (i.e. the data matches the signature), or an
+error code where the most relevant code is @code{GCRYERR_BAD_SIGNATURE}
+to indicate that the signature does not match the provided data.
+
+@end deftypefun
+@c end gcry_pk_verify
+
+@node General public-key related Functions
+@section General public-key related Functions
+
+@noindent
+A couple of utility functions are available to retrieve the length of
+the key, map algorithm identifiers and perform sanity checks:
+
+@deftypefun {const char *} gcry_pk_algo_name (int @var{algo})
+
+Map the public key algorithm id @var{algo} to a string representation of
+the algorithm name.  For unknown algorithms this functions returns an
+empty string.
+@end deftypefun
+
+@deftypefun int gcry_pk_map_name (const char *@var{name})
+
+Map the algorithm @var{name} to a public key algorithm Id.  Returns 0 if
+the algorithm name is not known.
+@end deftypefun
+
+@deftypefun int gcry_pk_test_algo (int @var{algo})
+
+Return 0 if the public key algorithm @var{algo} is available for use.
+Note, that this is implemented as a macro.
+@end deftypefun
+
+
+@deftypefun {unsigned int} gcry_pk_get_nbits (gcry_sexp_t @var{key})
+
+Return what is commonly referred as the key length for the given
+public or private in @var{key}.
+@end deftypefun
+
+@deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{gcry_sexp_t @var{key}}, @w{unsigned char *@var{array}})
+
+Return the so called "keygrip" which is the SHA-1 hash of the public key
+parameters expressed in a way depended on the algorithm.  @var{array}
+must either provide space for 20 bytes or @code{NULL;}. In the latter
+case a newly allocated array of that size is returned.  On success a
+pointer to the newly allocated space or to @var{array} is returned.
+@code{NULL} is returned to indicate an error which is most likely an unknown
+algorithm or one where a "keygrip" has not yet been defined.
+The function accepts public or secret keys in @var{key}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key})
+
+Return zero if the private key @var{key} is `sane', an error code otherwise.
+Note, that it is not possible to chek the `saneness' of a public key.
+
+@end deftypefun
+
+
+@deftypefun int gcry_pk_algo_info (@w{int @var{algo}}, @w{int @var{what}}, @w{void *@var{buffer}}, @w{size_t *@var{nbytes}})
+
+Depending on the value of @var{what} return various information about
+the public key algorithm with the id @var{algo}.  Note, that the
+function returns @code{-1} on error and the actual error code must be
+retrieved using the function @code{gcry_errno}.  The currently defined
+values for @var{what} are:
+
+@table @code
+@item GCRYCTL_TEST_ALGO:
+Return 0 when the specified algorithm is available for use.
+@var{buffer} must be @code{NULL}, @var{nbytes} may be passed as
+@code{NULL} or point to a variable with the required usage of the
+algorithm. This may be 0 for "don't care" or the bit-wise OR of these
+flags:
+
+@table @code
+@item GCRY_PK_USAGE_SIGN 
+Algorithm is usable for signing.
+@item GCRY_PK_USAGE_ENCR 
+Algorithm is usable for encryption.
+@end table
+
+@item GCRYCTL_GET_ALGO_USAGE:
+Return the usage flags for the given algorithm.  An invalid algorithm
+return 0.  Disabled algorithms are ignored here because we
+want to know whether the algorithm is at all capable of a certain usage.
+
+@item GCRYCTL_GET_ALGO_NPKEY
+Return the number of elements the public key for algorithm @var{algo}
+consist of.  Return 0 for an unknown algorithm.
+
+@item GCRYCTL_GET_ALGO_NSKEY
+Return the number of elements the private key for algorithm @var{algo}
+consist of.  Note that this value is always larger than that of the
+public key.  Return 0 for an unknown algorithm.
+
+@item GCRYCTL_GET_ALGO_NSIGN
+Return the number of elements a signature created with the algorithm
+@var{algo} consists of.  Return 0 for an unknown algorithm or for an
+algorithm not capable of creating signatures.
+
+@item GCRYCTL_GET_ALGO_NENC
+Return the number of elements a encrypted message created with the algorithm
+@var{algo} consists of.  Return 0 for an unknown algorithm or for an
+algorithm not capable of encryption.
+@end table
+
+@noindent
+Please note that parameters not required should be passed as @code{NULL}.
+@end deftypefun
+@c end gcry_pk_algo_info
+
+
+@deftypefun gcry_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})
+
+This is a general purpose function to perform certain control
+operations.  @var{cmd} controls what is to be done. The return value is
+0 for success or an error code.  Currently supported values for
+@var{cmd} are:
+
+@table @code
+@item GCRYCTL_DISABLE_ALGO
+Disable the algorithm given as an algorithm id in @var{buffer}.
+@var{buffer} must point to an @code{int} variable with the algorithm id
+and @var{buflen} must have the value @code{sizeof (int)}.
+
+@end table
+@end deftypefun
+@c end gcry_pk_ctl
+
+@noindent
+@acronym{Libgcrypt} also provides a function for generating public key
+pairs:
+
+@deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
+
+This function create a new public key pair using information given in
+the S-expression @var{parms} and stores the private and the public key
+in one new S-expression at the address given by @var{r_key}.  In case of
+an error, @var{r_key} is set to @code{NULL}.  The return code is 0 for
+success or an error code otherwise.
+
+@noindent
+Here is an example for @var{parms} for creating a 1024 bit RSA key:
+
+@example
+(genkey
+  (rsa
+    (nbits 4:1024)))
+@end example
+
+@noindent
+To create an ElGamal key, substitute "elg" for "rsa" and to create a DSA
+key use "dsa".  Valid ranges for the key length depend on the
+algorithms; all commonly used key lengths are supported.  Currently
+supported parameters are:
+
+@table @code
+@item nbits
+This is always required to specify the length of the key.  The argument
+is a string with a number in C-notation.
+
+@item rsa-use-e
+This is only used with RSA to give a hint for the public exponent. The
+value will be used as a base to test for a usable exponent. Some values
+are special:
+
+@table @samp
+@item 0
+Use a secure and fast value.  This is currently the number 41.
+@item 1
+Use a secure value as required by some specification.  This is currently
+the number 65537.
+@item 2
+Reserved
+@end table
+
+@noindent
+If this parameter is not used, @acronym{Libgcrypt} uses for historic reasons
+65537.
+
+@end table
+@c end table of parameters
+
+@noindent
+The key pair is returned in a format depending on the algorithm.  Both
+private and public keys are returned in one container and may be
+accompanied by some miscellaneous information.
+
+@noindent
+As an example, here is what the ElGamal key generation returns:
+
+@example
+(key-data
+  (public-key
+    (elg
+      (p @var{p-mpi})
+      (g @var{g-mpi})
+      (y @var{y-mpi})))
+  (private-key
+    (elg
+      (p @var{p-mpi})
+      (g @var{g-mpi})
+      (y @var{y-mpi})
+      (x @var{x-mpi})))
+  (misc-key-info
+    (pm1-factors @var{n1 n2 ... nn})))
+@end example
+
+@noindent
+As you can see, some of the information is duplicated, but this provides
+an easy way to extract either the public or the private key.  Note that
+the order of the elements is not defined, e.g. the private key may be
+stored before the public key. @var{n1 n2 ... nn} is a list of prime
+numbers used to composite @var{p-mpi}; this is in general not a very
+useful information.
+@end deftypefun
+@c end gcry_pk_genkey
+
+@node Public Key cryptography (II)
+@chapter Public Key cryptography (II)
+
+This chapter documents the alternative interface to asymmetric
+cryptography (ac) that is not based on S-expressions, but on native C
+data structures.  As opposed to the pk interface described in the
+former chapter, this one follows an open/use/close paradigm like other
+building blocks of the library.
+
+@menu
+* Available asymmetric algorithms::  List of algorithms supported by the library.
+* Working with sets of data::   How to work with sets of data.
+* Working with handles::        How to use handles.
+* Working with keys::           How to work with keys.
+* Using cryptographic functions::  How to perform cryptographic operations.
+* Handle-independent functions::  General functions independent of handles.
+@end menu
+
+@node Available asymmetric algorithms
+@section Available asymmetric algorithms
+
+@acronym{Libgcrypt} supports the RSA (Rivest-Shamir-Adleman)
+algorithms as well as DSA (Digital Signature Algorithm) and ElGamal.
+The versatile interface allows to add more algorithms in the future.
+
+@deftp {Data type} gcry_ac_id_t
+
+The following constants are defined for this type:
+
+@table @code
+@item GCRY_AC_RSA
+Riven-Shamir-Adleman
+@item GCRY_AC_DSA
+Digital Signature Algorithm
+@item GCRY_AC_ELG
+ElGamal
+@item GCRY_AC_ELG_E
+ElGamal, encryption only.
+@end table
+@end deftp
+
+@node Working with sets of data
+@section Working with sets of data
+
+In the context of this interface the term `data set' refers to a list
+of `named MPI values' that is used by functions performing
+cryptographic operations.
+
+Such data sets are used for representing keys, since keys simply
+consist of a variable amount of numbers.  Furthermore some functions
+return data sets to the caller that are to be provided to other
+functions.
+
+This section documents the data types, symbols and functions that are
+relevant for working with such data sets.
+
+@deftp {Data type} gcry_ac_data_t
+A data set, that is simply a list of named MPI values.
+@end deftp
+
+The following flags are supported:
+
+@table @code
+@item GCRY_AC_FLAG_DEALLOC
+Used for storing data in a data set.  If given, the data will be
+released by the library.
+
+@item GCRY_AC_FLAG_COPY
+Used for storing/retrieving data in/from a data set.  If given, the
+library will create copies of the provided/contained data, which will
+then be given to the user/associated with the data set.
+@end table
+
+@deftypefun gcry_error_t gcry_ac_data_new (gcry_ac_data_t *@var{data})
+Creates a new, empty data set and stores it in @var{data}.
+@end deftypefun
+
+@deftypefun void gcry_ac_data_destroy (gcry_ac_data_t @var{data})
+Destroys the data set @var{data}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_data_set (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t @var{mpi})
+Add the value @var{mpi} to @var{data} with the label @var{name}.  If
+@var{flags} contains GCRY_AC_FLAG_DATA_COPY, the data set will contain
+copies of @var{name} and @var{mpi}.  If @var{flags} contains
+GCRY_AC_FLAG_DATA_DEALLOC or GCRY_AC_FLAG_DATA_COPY, the values
+contained in the data set will be deallocated when they are to be
+removed from the data set.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data})
+Create a copy of the data set @var{data} and store it in @var{data_cp}.
+@end deftypefun
+
+@deftypefun unsigned int gcry_ac_data_length (gcry_ac_data_t @var{data})
+Returns the number of named MPI values inside of the data set
+@var{data}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t *@var{mpi})
+Store the value labelled with @var{name} found in @var{data} in
+@var{mpi}.  If @var{flags} contains GCRY_AC_FLAG_COPY, store a copy of
+the @var{mpi} value contained in the data set.  @var{mpi} may be NULL.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t @var{data}, unsigned int flags, unsigned int @var{index}, const char **@var{name}, gcry_mpi_t *@var{mpi})
+Stores in @var{name} and @var{mpi} the named @var{mpi} value contained
+in the data set @var{data} with the index @var{idx}.  If @var{flags}
+contains GCRY_AC_FLAG_COPY, store copies of the values contained in
+the data set. @var{name} or @var{mpi} may be NULL.
+@end deftypefun
+
+@deftypefun void gcry_ac_data_clear (gcry_ac_data_t @var{data})
+Destroys any values contained in the data set @var{data}.
+@end deftypefun
+
+@node Working with handles
+@section Working with handles
+
+In order to use an algorithm, an according handle must be created.
+This is done using the following function:
+
+@deftypefun gcry_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle}, int @var{algorithm}, int @var{flags})
+
+Creates a new handle for the algorithm @var{algorithm} and stores it
+in @var{handle}.  @var{flags} is not used yet.
+
+@var{algorithm} must be a valid algorithm ID, see @xref{Available
+algorithms}, for a list of supported algorithms and the according
+constants.  Besides using the listed constants directly, the functions
+@code{gcry_ac_name_to_id} may be used to convert the textual name of
+an algorithm into the according numeric ID.
+@end deftypefun
+
+@deftypefun void gcry_ac_close (gcry_ac_handle_t @var{handle})
+Destroys the handle @var{handle}.
+@end deftypefun
+
+@node Working with keys
+@section Working with keys
+
+@deftp {Data type} gcry_ac_key_type_t
+Defined constants:
+
+@table @code
+@item GCRY_AC_KEY_TYPE_SECRET
+Specifies a secret key.
+@item GCRY_AC_KEY_TYPE_PUBLIC
+Specifies a public key.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_ac_key_t
+This type represents a single `key', either a secret one or a public
+one.
+@end deftp
+
+@deftp {Data type} gcry_ac_key_pair_t
+This type represents a `key pair' containing a secret and a public key.
+@end deftp
+
+Key data structures can be created in two different ways; a new key
+pair can be generated, resulting in ready-to-use key.  Alternatively a
+key can be initialized from a given data set.
+
+@deftypefun gcry_error_t gcry_ac_key_init (gcry_ac_key_t *@var{key}, gcry_ac_handle_t @var{handle}, gcry_ac_key_type_t @var{type}, gcry_ac_data_t @var{data})
+Creates a new key of type @var{type}, consisting of the MPI values
+contained in the data set @var{data} and stores it in @var{key}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t @var{handle}, unsigned int @var{nbits}, void *@var{key_spec}, gcry_ac_key_pair_t *@var{key_pair}, gcry_mpi_t **@var{misc_data})
+
+Generates a new key pair via the handle @var{handle} of @var{NBITS}
+bits and stores it in @var{key_pair}.
+
+In case non-standard settings are wanted, a pointer to a structure of
+type @code{gcry_ac_key_spec_<algorithm>_t}, matching the selected
+algorithm, can be given as @var{key_spec}.  @var{misc_data} is not
+used yet.  Such a structure does only exist for RSA.  A descriptions
+of the members of the supported structures follows.
+
+@table @code
+@item gcry_ac_key_spec_rsa_t
+@table @code
+@item gcry_mpi_t e
+Generate the key pair using a special @code{e}.  The value of @code{e}
+has the following meanings:
+@table @code
+@item = 0
+Let @acronym{Libgcrypt} device what exponent should be used.
+@item = 1
+Request the use of a ``secure'' exponent; this is required by some
+specification to be 65537.
+@item > 2
+Try starting at this value until a working exponent is found.  Note,
+that the current implementation leaks some information about the
+private key because the incrementation used is not randomized.  Thus,
+this function will be changed in the future to return a random
+exponent of the given size.
+@end table
+@end table
+@end table
+
+Example code:
+@example
+@{
+  gcry_ac_key_pair_t key_pair;
+  gcry_ac_key_spec_rsa  rsa_spec;
+
+  rsa_spec.e = gcry_mpi_new (0);
+  gcry_mpi_set_ui (rsa_spec.e, 1)
+
+  err = gcry_ac_open  (&handle, GCRY_AC_RSA, 0);
+  assert (! err);
+
+  err = gcry_ac_key_pair_generate (handle, &key_pair, 1024, (void *) &rsa_spec);
+  assert (! err);
+@}
+@end example
+@end deftypefun
+
+
+@deftypefun gcry_ac_key_t gcry_ac_key_pair_extract (gcry_ac_key_pair_t @var{key_pair}, gcry_ac_key_type_t @var{which})
+Returns the key of type @var{which} out of the key pair
+@var{key_pair}.
+@end deftypefun
+
+@deftypefun void gcry_ac_key_destroy (gcry_ac_key_t @var{key})
+Destroys the key @var{key}.
+@end deftypefun
+
+@deftypefun void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t @var{key_pair})
+Destroys the key pair @var{key_pair}.
+@end deftypefun
+
+@deftypefun gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t @var{key})
+Returns the data set contained in the key @var{key}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_key_test (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key})
+Verifies that the private key @var{key} is sane via @var{handle}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned int *@var{nbits})
+Stores the number of bits of the key @var{key} in @var{nbits} via @var{handle}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned char *@var{key_grip})
+Writes the 20 byte long key grip of the key @var{key} to
+@var{key_grip} via @var{handle}.
+@end deftypefun
+
+@node Using cryptographic functions
+@section Using cryptographic functions
+
+The following flags might be relevant:
+
+@table @code
+@item GCRY_AC_FLAG_NO_BLINDING
+Disable any blinding, which might be supported by the chosen
+algorithm; blinding is the default.
+@end table
+
+@deftypefun gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data_plain}, gcry_ac_data_t **@var{data_encrypted})
+Encrypts the plain text MPI value @var{data_plain} with the key public
+@var{key} under the control of the flags @var{flags} and stores the
+resulting data set into @var{data_encrypted}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t *@var{data_plain}, gcry_ac_data_t @var{data_encrypted})
+Decrypts the encrypted data contained in the data set
+@var{data_encrypted} with the secret key KEY under the control of the
+flags @var{flags} and stores the resulting plain text MPI value in
+@var{DATA_PLAIN}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t *@var{data_signature})
+Signs the data contained in @var{data} with the secret key @var{key}
+and stores the resulting signature in the data set
+@var{data_signature}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t @var{data_signature})
+Verifies that the signature contained in the data set
+@var{data_signature} is indeed the result of signing the data
+contained in @var{data} with the secret key belonging to the public
+key @var{key}.
+@end deftypefun
+
+@node Handle-independent functions
+@section Handle-independent functions
+
+@deftypefun gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t @var{algorithm}, const char **@var{name})
+Stores the textual representation of the algorithm whose id is given
+in @var{algorithm} in @var{name}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_name_to_id (const char *@var{name}, gcry_ac_id_t *@var{algorithm})
+Stores the numeric ID of the algorithm whose textual representation is
+contained in @var{name} in @var{algorithm}.
+@end deftypefun
+
+@c **********************************************************
+@c *******************  Random  *****************************
+@c **********************************************************
+@node Random Numbers
+@chapter Random Numbers
+
+@menu
+* Quality of random numbers::   @acronym{Libgcrypt} uses different quality levels.
+* Retrieving random numbers::   How to retrieve random numbers.
+@end menu
+
+@node Quality of random numbers
+@section Quality of random numbers
+
+@acronym{Libgcypt} offers random numbers of different quality levels:
+
+@deftp {Data type} enum gcry_random_level
+The constants for the random quality levels are of this type.
+@end deftp
+
+@table @code
+@item GCRY_WEAK_RANDOM
+This should not anymore be used.  It has recently been changed to an
+alias of GCRY_STRONG_RANDOM.  Use @code{gcry_create_nonce} instead.
+@item GCRY_STRONG_RANDOM
+Use this level for e.g. session keys and similar purposes.
+@item GCRY_VERY_STRONG_RANDOM
+Use this level for e.g. key material.
+@end table
+
+@node Retrieving random numbers
+@section Retrieving 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 function
+differs from @code{gcry_random_bytes} in that the returned buffer is
+allocated in a ``secure'' area of the memory.
+@end deftypefun
+
+@deftypefun void gcry_create_nonce (void *@var{buffer}, size_t @var{length})
+
+Fill @var{buffer} with @var{length} unpredictable bytes.  This is
+commonly called a nonce and may also be used for initialization
+vectors and padding.  This is an extra function nearly independent of
+the other random function for 3 reasons: It better protects the
+regular random generator's internal state, provides better performance
+and does not drain the precious entropy pool.
+
+@end deftypefun
+
+
+
+@c **********************************************************
+@c *******************  S-Expressions ***********************
+@c **********************************************************
+@node S-expressions
+@chapter S-expressions
+
+S-expressions are used by the public key functions to pass complex data
+structures around.  These LISP like objects are used by some
+cryptographic protocols (cf. RFC-2692) and @acronym{Libgcrypt} provides functions
+to parse and construct them.  For detailed information, see
+@cite{Ron Rivest, code and description of S-expressions,
+@uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}.
+
+@menu
+* Data types for S-expressions::  Data types related with S-expressions.
+* Working with S-expressions::  How to work with S-expressions.
+@end menu
+
+@node Data types for S-expressions
+@section Data types for S-expressions
+
+@deftp {Data type} gcry_sexp_t
+The @code{gcry_sexp_t} type describes an object with the @acronym{Libgcrypt} internal
+representation of an S-expression.
+@end deftp
+
+@node Working with S-expressions
+@section Working with S-expressions
+
+@noindent
+There are several functions to create an @acronym{Libgcrypt} S-expression object
+from its external representation or from a string template.  There is
+also a function to convert the internal representation back into one of
+the external formats:
+
+
+@deftypefun gcry_error_t gcry_sexp_new (@w{gcry_sexp_t *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}})
+
+This is the generic function to create an new S-expression object from
+its external representation in @var{buffer} of @var{length} bytes.  On
+success the result is stored at the address given by @var{r_sexp}. 
+With @var{autodetect} set to 0, the data in @var{buffer} is expected to
+be in canonized format, with @var{autodetect} set to 1 the parses any of
+the defined external formats.  If @var{buffer} does not hold a valid
+S-expression an error code is returned and @var{r_sexp} set to
+@code{NULL}.
+Note, that the caller is responsible for releasing the newly allocated
+S-expression using @code{gcry_sexp_release}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_sexp_create (@w{gcry_sexp_t *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)})
+
+This function is identical to @code{gcry_sexp_new} but has an extra
+argument @var{freefnc}, which, when not set to @code{NULL}, is expected
+to be a function to release the @var{buffer}; most likely the standard
+@code{free} function is used for this argument.  This has the effect of
+transferring the ownership of @var{buffer} to the created object in
+@var{r_sexp}.  The advantage of using this function is that @acronym{Libgcrypt}
+might decide to directly use the provided buffer and thus avoid extra
+copying.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_sexp_sscan (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
+
+This is another variant of the above functions.  It behaves nearly
+identical but provides an @var{erroff} argument which will receive the
+offset into the buffer where the parsing stopped on error.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_sexp_build (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...})
+
+This function creates an internal S-expression from the string template
+@var{format} and stores it at the address of @var{r_sexp}. If there is a
+parsing error, the function returns an appropriate error code and stores
+the offset into @var{format} where the parsing stopped in @var{erroff}.
+The function supports a couple of printf-like formatting characters and
+expects arguments for some of these escape sequences right after
+@var{format}.  The following format characters are defined:
+
+@table @samp
+@item %m
+The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
+its value is inserted into the resulting S-expression.
+@item %s
+The next argument is expected to be of type @code{char *} and that
+string is inserted into the resulting S-expression.
+@item %d
+The next argument is expected to be of type @code{int} and its 
+value ist inserted into the resulting S-expression.
+@item %b
+The next argument is expected to be of type @code{int} directly
+followed by an argument of type @code{char *}.  This represents a
+buffer of given length to be inserted into the resulting regular
+expression.
+@end table
+
+@noindent
+No other format characters are defined and would return an error.  Note,
+that the format character @samp{%%} does not exists, because a percent
+sign is not a valid character in an S-expression.
+@end deftypefun
+
+@deftypefun void gcry_sexp_release (@w{gcry_sexp_t @var{sexp}})
+
+Release the S-expression object @var{sexp}.
+@end deftypefun
+
+
+@noindent
+The next 2 functions are used to convert the internal representation
+back into a regular external S-expression format and to show the
+structure for debugging.
+
+@deftypefun size_t gcry_sexp_sprint (@w{gcry_sexp_t @var{sexp}}, @w{int @var{mode}}, @w{void *@var{buffer}}, @w{size_t @var{maxlength}})
+
+Copies the S-expression object @var{sexp} into @var{buffer} using the
+format specified in @var{mode}.  @var{maxlength} must be set to the
+allocated length of @var{buffer}.  The function returns the actual
+length of valid bytes put into @var{buffer} or 0 if the provided buffer
+is too short.  Passing @code{NULL} for @var{buffer} returns the required
+length for @var{buffer}.  For convenience reasons an extra byte with
+value 0 is appended to the buffer.
+
+@noindent
+The following formats are supported:
+
+@table @code
+@item GCRYSEXP_FMT_DEFAULT
+Returns a convenient external S-expression representation.
+
+@item GCRYSEXP_FMT_CANON
+Return the S-expression in canonical format.
+
+@item GCRYSEXP_FMT_BASE64
+Not currently supported.
+
+@item GCRYSEXP_FMT_ADVANCED
+Returns the S-expression in advanced format.
+@end table
+@end deftypefun
+
+@deftypefun void gcry_sexp_dump (@w{gcry_sexp_t @var{sexp}})
+
+Dumps @var{sexp} in a format suitable for debugging to @acronym{Libgcrypt}'s
+logging stream.
+@end deftypefun
+
+@noindent
+Often canonical encoding is used in the external representation.  The
+following function can be used to check for valid encoding and to learn
+the length of the S-expression"
+
+@deftypefun size_t gcry_sexp_canon_len (@w{const unsigned char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{erroff}}, @w{int *@var{errcode}})
+
+Scan the canonical encoded @var{buffer} with implicit length values and
+return the actual length this S-expression uses.  For a valid S-expression
+it should never return 0.  If @var{length} is not 0, the maximum
+length to scan is given; this can be used for syntax checks of
+data passed from outside.  @var{errcode} and @var{erroff} may both be
+passed as @code{NULL}.
+
+@end deftypefun
+
+
+@noindent
+There are a couple of functions to parse S-expressions and retrieve
+elements:
+
+@deftypefun gcry_sexp_t gcry_sexp_find_token (@w{const gcry_sexp_t @var{list}}, @w{const char *@var{token}}, @w{size_t @var{toklen}})
+
+Scan the S-expression for a sublist with a type (the car of the list)
+matching the string @var{token}.  If @var{toklen} is not 0, the token is
+assumed to be raw memory of this length.  The function returns a newly
+allocated S-expression consisting of the found sublist or @code{NULL}
+when not found.
+@end deftypefun
+
+
+@deftypefun int gcry_sexp_length (@w{const gcry_sexp_t @var{list}})
+
+Return the length of the @var{list}.  For a valid S-expression this
+should be at least 1.
+@end deftypefun
+
+
+@deftypefun gcry_sexp_t gcry_sexp_nth (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}})
+
+Create and return a new S-expression from the element with index @var{number} in
+@var{list}.  Note that the first element has the index 0.  If there is
+no such element, @code{NULL} is returned.
+@end deftypefun
+
+@deftypefun gcry_sexp_t gcry_sexp_car (@w{const gcry_sexp_t @var{list}})
+
+Create and return a new S-expression from the first element in
+@var{list}; this called the "type" and should always exist and be a
+string. @code{NULL} is returned in case of a problem.
+@end deftypefun
+
+@deftypefun gcry_sexp_t gcry_sexp_cdr (@w{const gcry_sexp_t @var{list}})
+
+Create and return a new list form all elements except for the first one.
+Note, that this function may return an invalid S-expression because it
+is not guaranteed, that the type exists and is a string.  However, for
+parsing a complex S-expression it might be useful for intermediate
+lists.  Returns @code{NULL} on error.
+@end deftypefun
+
+
+@deftypefun {const char *} gcry_sexp_nth_data (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{size_t *@var{datalen}})
+
+This function is used to get data from a @var{list}.  A pointer to the
+actual data with index @var{number} is returned and the length of this
+data will be stored to @var{datalen}.  If there is no data at the given
+index or the index represents another list, @code{NULL} is returned.
+@strong{Take care:} The returned pointer is valid as long as @var{list} is
+not modified or released.
+
+@noindent
+Here is an example on how to extract and print the surname (Meier) from
+the S-expression @samp{(Name Otto Meier (address Burgplatz 3))}:
+
+@example
+size_t len;
+const char *name;
+
+name = gcry_sexp_nth_data (list, 2, &len);
+printf ("my name is %.*s\n", (int)len, name);
+@end example
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_sexp_nth_mpi (@w{gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{int @var{mpifmt}})
+
+This function is used to get and convert data from a @var{list}. This
+data is assumed to be an MPI stored in the format described by
+@var{mpifmt} and returned as a standard @acronym{Libgcrypt} MPI.  The caller must
+release this returned value using @code{gcry_mpi_release}.  If there is
+no data at the given index, the index represents a list or the value
+can't be converted to an MPI, @code{NULL} is returned.
+@end deftypefun
+
+
+@c **********************************************************
+@c *******************  MPIs ******** ***********************
+@c **********************************************************
+@node MPI library
+@chapter MPI library
+
+@menu
+* Data types::                  MPI related data types.
+* Basic functions::             First steps with MPI numbers.
+* MPI formats::                 External representation of MPIs.
+* Calculations::                Performing MPI calculations.
+* Comparisons::                 How to compare MPI values.
+* Bit manipulations::           How to access single bits of MPI values.
+* Miscellaneous::               Miscellaneous MPI functions.
+@end menu
+
+Public key cryptography is based on mathematics with large numbers.  To
+implement the public key functions, a library for handling these large
+numbers is required.  Because of the general usefulness of such a
+library, its interface is exposed by @acronym{Libgcrypt}.  The implementation is
+based on an old release of GNU Multi-Precision Library (GMP) but in the
+meantime heavily modified and stripped down to what is required for
+cryptography. For a lot of CPUs, high performance assembler
+implementations of some very low level functions are used to gain much
+better performance than with the standard C implementation.
+
+@noindent
+In the context of @acronym{Libgcrypt} and in most other applications, these large
+numbers are called MPIs (multi-precision-integers).
+
+@node Data types
+@section Data types
+
+@deftp {Data type} gcry_mpi_t
+The @code{gcry_mpi_t} type represents an object to hold an MPI.
+@end deftp
+
+@node Basic functions
+@section Basic functions
+
+@noindent
+To work with MPIs, storage must be allocated and released for the
+numbers.  This can be done with one of these functions:
+
+@deftypefun gcry_mpi_t gcry_mpi_new (@w{unsigned int @var{nbits}})
+
+Allocate a new MPI object, initialize it to 0 and initially allocate
+enough memory for a number of at least @var{nbits}.  This pre-allocation is
+only a small performance issue and not actually necessary because
+@acronym{Libgcrypt} automatically re-allocates the required memory.
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_mpi_snew (@w{unsigned int @var{nbits}})
+
+This is identical to @code{gcry_mpi_new} but allocates the MPI in the so
+called "secure memory" which in turn will take care that all derived
+values will also be stored in this "secure memory".  Use this for highly
+confidential data like private key parameters.
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_mpi_copy (@w{const gcry_mpi_t @var{a}})
+
+Create a new MPI as the exact copy of @var{a}.
+@end deftypefun
+
+
+@deftypefun void gcry_mpi_release (@w{gcry_mpi_t @var{a}})
+
+Release the MPI @var{a} and free all associated resources.  Passing
+@code{NULL} is allowed and ignored.  When a MPI stored in the "secure
+memory" is released, that memory gets wiped out immediately.
+@end deftypefun
+
+@noindent
+The simplest operations are used to assign a new value to an MPI:
+
+@deftypefun gcry_mpi_t gcry_mpi_set (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{u}})
+
+Assign the value of @var{u} to @var{w} and return @var{w}.  If
+@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the
+value of @var{u} and returned.
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_mpi_set_ui (@w{gcry_mpi_t @var{w}}, @w{unsigned long @var{u}})
+
+Assign the value of @var{u} to @var{w} and return @var{w}.  If
+@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the
+value of @var{u} and returned.  This function takes an @code{unsigned
+int} as type for @var{u} and thus it is only possible to set @var{w} to
+small values (usually up to the word size of the CPU).
+@end deftypefun
+
+@deftypefun void gcry_mpi_swap (@w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
+
+Swap the values of @var{a} and @var{b}.
+@end deftypefun
+
+@node MPI formats
+@section MPI formats
+
+@noindent
+The following functions are used to convert between an external
+representation of an MPI and the internal one of @acronym{Libgcrypt}.
+
+@deftypefun int gcry_mpi_scan (@w{gcry_mpi_t *@var{r_mpi}}, @w{enum gcry_mpi_format @var{format}}, @w{const void *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nscanned}})
+
+Convert the external representation of an integer stored in @var{buffer}
+with a length of @var{buflen} into a newly created MPI returned which
+will be stored at the address of @var{r_mpi}.  For certain formats the
+length argument is not required and may be passed as @code{0}.  After a
+successful operation the variable @var{nscanned} receives the number of
+bytes actually scanned unless @var{nscanned} was given as
+@code{NULL}. @var{format} describes the format of the MPI as stored in
+@var{buffer}:
+
+@table @code
+@item GCRYMPI_FMT_STD
+2-complement stored without a length header.
+
+@item GCRYMPI_FMT_PGP
+As used by OpenPGP (only defined as unsigned). This is basically
+@code{GCRYMPI_FMT_STD} with a 2 byte big endian length header.
+
+@item GCRYMPI_FMT_SSH
+As used in the Secure Shell protocol.  This is @code{GCRYMPI_FMT_STD}
+with a 4 byte big endian header.
+
+@item GCRYMPI_FMT_HEX
+Stored as a C style string with each byte of the MPI encoded as 2 hex
+digits.
+
+@item GCRYMPI_FMT_USG
+Simple unsigned integer.
+@end table
+
+@noindent
+Note, that all of the above formats store the integer in big-endian
+format (MSB first).
+@end deftypefun
+
+
+@deftypefun int gcry_mpi_print (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nwritten}}, @w{const gcry_mpi_t @var{a}})
+
+Convert the MPI @var{a} into an external representation described by
+@var{format} (see above) and store it in the provided @var{buffer}
+which has a usable length of at least the @var{buflen} bytes. If
+@var{nwritten} is not NULL, it will receive the number of bytes
+actually stored in @var{buffer} after a successful operation.
+@end deftypefun
+
+@deftypefun int gcry_mpi_aprint (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char **@var{buffer}}, @w{size_t *@var{nbytes}}, @w{const gcry_mpi_t @var{a}})
+
+Convert the MPI @var{a} into an external representation described by
+@var{format} (see above) and store it in a newly allocated buffer which
+address will be stored in the variable @var{buffer} points to.  The
+number of bytes stored in this buffer will be stored in the variable
+@var{nbytes} points to, unless @var{nbytes} is @code{NULL}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_dump (@w{const gcry_mpi_t @var{a}})
+
+Dump the value of @var{a} in a format suitable for debugging to
+Libgcrypt's logging stream.  Note that one leading space but no trailing
+space or linefeed will be printed.  It is okay to pass @code{NULL} for
+@var{a}.
+@end deftypefun
+
+
+@node Calculations
+@section Calculations
+
+@noindent
+Basic arithmetic operations:
+
+@deftypefun void gcry_mpi_add (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
+
+@math{@var{w} = @var{u} + @var{v}}.
+@end deftypefun
+
+
+@deftypefun void gcry_mpi_add_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
+
+@math{@var{w} = @var{u} + @var{v}}.  Note, that @var{v} is an unsigned integer.
+@end deftypefun
+
+
+@deftypefun void gcry_mpi_addm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
+
+@math{@var{w} = @var{u} + @var{v} \bmod @var{m}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_sub (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
+
+@math{@var{w} = @var{u} - @var{v}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_sub_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
+
+@math{@var{w} = @var{u} - @var{v}}.  @var{v} is an unsigned integer.
+@end deftypefun
+
+@deftypefun void gcry_mpi_subm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
+
+@math{@var{w} = @var{u} - @var{v} \bmod @var{m}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_mul (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
+
+@math{@var{w} = @var{u} * @var{v}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_mul_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
+
+@math{@var{w} = @var{u} * @var{v}}.  @var{v} is an unsigned integer.
+@end deftypefun
+
+@deftypefun void gcry_mpi_mulm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
+
+@math{@var{w} = @var{u} * @var{v} \bmod @var{m}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_mul_2exp (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{e}})
+
+@c FIXME: I am in need for a real TeX{info} guru:
+@c I don't know why TeX can grok @var{e} here.
+@math{@var{w} = @var{u} * 2^e}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_div (@w{gcry_mpi_t @var{q}}, @w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}}, @w{int @var{round}})
+
+@math{@var{q} = @var{dividend} / @var{divisor}}, @math{@var{r} =
+@var{dividend} \bmod @var{divisor}}.  @var{q} and @var{r} may be passed
+as @code{NULL}.  @var{round} should be negative or 0.
+@end deftypefun
+
+@deftypefun void gcry_mpi_mod (@w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}})
+
+@math{@var{r} = @var{dividend} \bmod @var{divisor}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_powm (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{b}}, @w{const gcry_mpi_t @var{e}}, @w{const gcry_mpi_t @var{m}})
+
+@c I don't know why TeX can grok @var{e} here.
+@math{@var{w} = @var{b}^e \bmod @var{m}}.
+@end deftypefun
+
+@deftypefun int gcry_mpi_gcd (@w{gcry_mpi_t @var{g}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
+
+Set @var{g} to the greatest common divisor of @var{a} and @var{b}.  
+Return true if the @var{g} is 1.
+@end deftypefun
+
+@deftypefun int gcry_mpi_invm (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{m}})
+
+Set @var{x} to the multiplicative inverse of @math{@var{a} \bmod @var{m}}.
+Return true if the inverse exists.
+@end deftypefun
+
+
+@node Comparisons
+@section Comparisons
+
+@noindent
+The next 2 functions are used to compare MPIs:
+
+
+@deftypefun int gcry_mpi_cmp (@w{const gcry_mpi_t @var{u}}, @w{const gcry_mpi_t @var{v}})
+
+Compare the big integer number @var{u} and @var{v} returning 0 for
+equality, a positive value for @var{u} > @var{v} and a negative for
+@var{u} < @var{v}.
+@end deftypefun
+
+@deftypefun int gcry_mpi_cmp_ui (@w{const gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
+
+Compare the big integer number @var{u} with the unsigned integer @var{v}
+returning 0 for equality, a positive value for @var{u} > @var{v} and a
+negative for @var{u} < @var{v}.
+@end deftypefun
+
+
+@node Bit manipulations
+@section Bit manipulations
+
+@noindent
+There are a couple of functions to get information on arbitrary bits
+in an MPI and to set or clear them:
+
+@deftypefun {unsigned int} gcry_mpi_get_nbits (@w{gcry_mpi_t @var{a}})
+
+Return the number of bits required to represent @var{a}.
+@end deftypefun
+
+@deftypefun int gcry_mpi_test_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Return true if bit number @var{n} (counting from 0) is set in @var{a}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_set_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Set bit number @var{n} in @var{a}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_clear_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Clear bit number @var{n} in @var{a}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_set_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Set bit number @var{n} in @var{a} and clear all bits greater than @var{n}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_clear_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Clear bit number @var{n} in @var{a} and all bits greater than @var{n}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_rshift (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Shift the value of @var{a} by @var{n} bits to the right and store the
+result in @var{x}.
+@end deftypefun
+
+@node Miscellaneous
+@section Miscellanous
+
+@deftypefun gcry_mpi_t gcry_mpi_set_opaque (@w{gcry_mpi_t @var{a}}, @w{void *@var{p}}, @w{unsigned int @var{nbits}})
+
+Store @var{nbits} of the value @var{p} points to in @var{a} and mark
+@var{a} as an opaque value (i.e. an value that can't be used for any
+math calculation and is only used to store an arbitrary bit pattern in
+@var{a}).
+
+WARNING: Never use an opaque MPI for actual math operations.  The only
+valid functions are gcry_mpi_get_opaque and gcry_mpi_release.  Use
+gcry_mpi_scan to convert a string of arbitrary bytes into an MPI.
+
+@end deftypefun
+
+@deftypefun {void *} gcry_mpi_get_opaque (@w{gcry_mpi_t @var{a}}, @w{unsigned int *@var{nbits}})
+
+Return a pointer to an opaque value stored in @var{a} and return its
+size in @var{nbits}.  Note, that the returned pointer is still owned by
+@var{a} and that the function should never be used for an non-opaque
+MPI.
+@end deftypefun
+
+@deftypefun void gcry_mpi_set_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
+
+Set the @var{flag} for the MPI @var{a}.  Currently only the flag
+@code{GCRYMPI_FLAG_SECURE} is allowed to convert @var{a} into an MPI
+stored in "secure memory".
+@end deftypefun
+
+@deftypefun void gcry_mpi_clear_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
+
+Clear @var{flag} for the big integer @var{a}.  Note, that this function is
+currently useless as no flags are allowed.
+@end deftypefun
+
+@deftypefun int gcry_mpi_get_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
+
+Return true when the @var{flag} is set for @var{a}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_randomize (@w{gcry_mpi_t @var{w}}, @w{unsigned int @var{nbits}}, @w{enum gcry_random_level @var{level}})
+
+Set the big integer @var{w} to a random value of @var{nbits}, using
+random data quality of level @var{level}.  In case @var{nbits} is not
+a multiple of a byte, @var{nbits} is rounded up to the next byte
+boundary.
+@end deftypefun
+
+@node Utilities
+@chapter Utilities
+
+@menu
+* Memory allocation::           Functions related with memory allocation.
+@end menu
+
+@node Memory allocation
+@section Memory allocation
+
+@deftypefun void *gcry_malloc (size_t @var{n})
+
+This function tries to allocate @var{n} bytes of memory.  On success
+it returns a pointer to the memory area, in an out-of-core condition,
+it returns NULL.
+@end deftypefun
+
+@deftypefun void *gcry_malloc_secure (size_t @var{n})
+Like @code{gcry_malloc}, but uses secure memory.
+@end deftypefun
+
+@deftypefun void *gcry_calloc (size_t @var{n})
+
+This function tries to allocate @var{n} bytes of cleared memory
+(i.e. memory that is initialized with zero bytes).  On success it
+returns a pointer to the memory area, in an out-of-core condition, it
+returns NULL.
+@end deftypefun
+
+@deftypefun void *gcry_calloc_secure (size_t @var{n})
+Like @code{gcry_calloc}, but uses secure memory.
+@end deftypefun
+
+@deftypefun void *gcry_realloc (void *@var{p}, size_t @var{n})
+
+This function tries to resize the memory area pointed to by @var{p} to
+@var{n} bytes.  On success it returns a pointer to the new memory
+area, in an out-of-core condition, it returns NULL.  Depending on
+whether the memory pointed to by @var{p} is secure memory or not,
+gcry_realloc tries to use secure memory as well.
+@end deftypefun
+
+@deftypefun void gcry_free (void *@var{p})
+Release the memory area pointed to by @var{p}.
+@end deftypefun
+
+@c **********************************************************
+@c *******************  Appendices  *************************
+@c **********************************************************
+
+@include lgpl.texi
+
+@include gpl.texi
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Function and Data Index
+@unnumbered Function and Data Index
+
+@printindex fn
+
+@bye
+
+  /* Version check should be the very first gcry call because it
+     makes sure that constructor functions are run. */
+  if (!gcry_check_version (GCRYPT_VERSION))
+    die ("version mismatch\n");
+  /* Many applications don't require secure memory, so they should
+     disable it right away.  There won't be a problem unless one makes
+     use of a feature which requires secure memory - in that case the
+     process would abort because the secmem is not initialized. */
+  gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
+
+  /* .. add whatever initialization you want, but better don't make calls
+        to libgcrypt from more than one thread ... */
+
+  /* Tell Libgcrypt that initialization has completed. */
+  gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
+
+
+If you require secure memory, this code should be used: 
+
+  if (!gcry_check_version (GCRYPT_VERSION))
+    die ("version mismatch\n");
+  /* We don't want to see any warnings, e.g. because we have not yet
+    parsed options which might be used to suppress such warnings */
+  gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
+
+  /* ... */
+
+  /* Allocate a pool of 16k secure memory.  This also drops priviliges
+     on some systems. */
+  gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
+
+  /* It is now okay to let Libgcrypt complain when there was/is a problem
+     with the secure memory. */
+  gcry_control (GCRYCTL_RESUME_SECMEM_WARN);
+
+  /* Tell Libgcrypt that initialization has completed. */
+  gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
+
+
+This sounds a bit complicated but has the advantage that the caller
+must decide whether he wants secure memory or not - there is no
+default.
+
+It is important that this initialization is not done by a library but
+in the application.  The library might want to check for finished
+initialization using:
+
+  if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))
+    return MYLIB_ERROR_LIBGCRYPT_NOT_INITIALIZED;
+
+
+@c  LocalWords:  int HD
+
+
+
+