add source to libraries, and cruft for building under windows

author: Jay Threeth 2011-04-04 11:48:26 -0700
committer: Jay Threeth 2011-04-04 11:48:26 -0700
commit: 3c9cc506f741b980565ff5b3b001cd8b6ee36b12 (patch)
tree: cb862c57b3d5f74177cde3bd962a53fc377166f6 /linden/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.info
parent: build fixes, might build on linux now (diff)
download: meta-impy-3c9cc506f741b980565ff5b3b001cd8b6ee36b12.zip
meta-impy-3c9cc506f741b980565ff5b3b001cd8b6ee36b12.tar.gz
meta-impy-3c9cc506f741b980565ff5b3b001cd8b6ee36b12.tar.bz2
meta-impy-3c9cc506f741b980565ff5b3b001cd8b6ee36b12.tar.xz
1 files changed, 4698 insertions, 0 deletions
diff --git a/linden/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.info b/linden/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.info
new file mode 100755
index 0000000..ad64497
--- /dev/null
+++ b/linden/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.info
@@ -0,0 +1,4698 @@
+This is gcrypt.info, produced by makeinfo version 4.7 from gcrypt.texi.
+   This manual is for Libgcrypt (version 1.2.2, 29 July 2005), which is
+GNU's library of cryptographic building blocks.
+   Copyright (C) 2000, 2002, 2003, 2004 Free Software Foundation, Inc.
+     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".
+INFO-DIR-SECTION GNU Libraries
+START-INFO-DIR-ENTRY
+* libgcrypt: (gcrypt).  Cryptographic function library.
+END-INFO-DIR-ENTRY
+File: gcrypt.info,  Node: Top,  Next: Introduction,  Up: (dir)
+The Libgcrypt Library
+*********************
+This manual is for Libgcrypt (version 1.2.2, 29 July 2005), which is
+GNU's library of cryptographic building blocks.
+   Copyright (C) 2000, 2002, 2003, 2004 Free Software Foundation, Inc.
+     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".
+* Menu:
+* Introduction::                 What is 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.
+ --- The Detailed Node Listing ---
+Introduction
+* Getting Started::             How to use this manual.
+* Features::                    A glance at 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 Libgcrypt can be used in a MT environment.
+Generalities
+* Controlling the library::     Controlling 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::   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.
+File: gcrypt.info,  Node: Introduction,  Next: Preparation,  Prev: Top,  Up: Top
+1 Introduction
+**************
+`Libgcrypt' is a library providing cryptographic building blocks.
+* Menu:
+* Getting Started::             How to use this manual.
+* Features::                    A glance at Libgcrypt's features.
+* Overview::                    Overview about the library.
+File: gcrypt.info,  Node: Getting Started,  Next: Features,  Up: Introduction
+1.1 Getting Started
+===================
+This manual documents the `Libgcrypt' library application programming
+interface (API).  All functions and data types provided by the library
+are explained.
+The reader is assumed to possess basic knowledge about applied
+cryptography.
+   This manual can be used in several ways.  If read from the beginning
+to the end, it gives a good introduction into the library and how it
+can be used in an application.  Forward references are included where
+necessary.  Later on, the manual can be used as a reference manual to
+get just the information needed about any particular interface of the
+library.  Experienced programmers might want to start looking at the
+examples at the end of the manual, and then only read up those parts of
+the interface which are unclear.
+File: gcrypt.info,  Node: Features,  Next: Overview,  Prev: Getting Started,  Up: Introduction
+1.2 Features
+============
+`Libgcrypt' might have a couple of advantages over other libraries doing
+a similar job.
+It's Free Software
+     Anybody can use, modify, and redistribute it under the terms of
+     the GNU Lesser General Public License (*note 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
+     (*note Copying::); please see the README file of the distribution
+     for of list of these parts.
+It encapsulates the low level cryptography
+     `Libgcrypt' provides a high level interface to cryptographic
+     building blocks using an extendable and flexible API.
+File: gcrypt.info,  Node: Overview,  Prev: Features,  Up: Introduction
+1.3 Overview
+============
+The `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.
+   Libgcrypt depends on the library `libgpg-error', which contains
+common error handling related code for GnuPG components.
+File: gcrypt.info,  Node: Preparation,  Next: Generalities,  Prev: Introduction,  Up: Top
+2 Preparation
+*************
+To use `Libgcrypt', you have to perform some changes to your sources
+and the build system.  The necessary changes are small and explained in
+the following sections.  At the end of this chapter, it is described
+how the library is initialized, and how the requirements of the library
+are verified.
+* Menu:
+* Header::                      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 Libgcrypt can be used in a MT environment.
+File: gcrypt.info,  Node: Header,  Next: Building sources,  Up: Preparation
+2.1 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:
+     #include <gcrypt.h>
+   The name space of `Libgcrypt' is `gcry_*' for function and type
+names and `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 Libgcrypt uses libgpg-error, which
+uses `gpg_err_*' as name space for function and type names and
+`GPG_ERR_*' for other symbols, including all the error codes.
+File: gcrypt.info,  Node: Building sources,  Next: Building sources using Automake,  Prev: Header,  Up: Preparation
+2.2 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 `-I' option).
+   However, the path to the include file is determined at the time the
+source is configured.  To solve this problem, `Libgcrypt' ships with a
+small helper program `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
+`--cflags' option to `libgcrypt-config'.  The following example shows
+how it can be used at the command line:
+     gcc -c foo.c `libgcrypt-config --cflags`
+   Adding the output of `libgcrypt-config --cflags' to the compilers
+command line will ensure that the compiler can find the `Libgcrypt'
+header file.
+   A similar problem occurs when linking the program with the library.
+Again, the compiler has to find the library files.  For this to work,
+the path to the library files has to be added to the library search path
+(via the `-L' option).  For this, the option `--libs' to
+`libgcrypt-config' can be used.  For convenience, this option also
+outputs all other options that are required to link the program with
+the `Libgcrypt' libraries (in particular, the `-lgcrypt' option).  The
+example shows how to link `foo.o' with the `Libgcrypt' library to a
+program `foo'.
+     gcc -o foo foo.o `libgcrypt-config --libs`
+   Of course you can also combine both examples to a single command by
+specifying both options to `libgcrypt-config':
+     gcc -o foo foo.c `libgcrypt-config --cflags --libs`
+File: gcrypt.info,  Node: Building sources using Automake,  Next: Initializing the library,  Prev: Building sources,  Up: Preparation
+2.3 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 `libgcrypt-config' script at all.  Libgcrypt provides an
+extension to Automake that does all the work for you.
+ -- Macro: AM_PATH_LIBGCRYPT ([MINIMUM-VERSION], [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     Check whether Libgcrypt (at least version MINIMUM-VERSION, if
+     given) exists on the host system.  If it is found, execute
+     ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given.
+     Additionally, the function defines `LIBGCRYPT_CFLAGS' to the flags
+     needed for compilation of the program to find the `gcrypt.h'
+     header file, and `LIBGCRYPT_LIBS' to the linker flags needed to
+     link the program to the Libgcrypt library.
+   You can use the defined Autoconf variables like this in your
+`Makefile.am':
+     AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
+     LDADD = $(LIBGCRYPT_LIBS)
+File: gcrypt.info,  Node: Initializing the library,  Next: Multi Threading,  Prev: Building sources using Automake,  Up: Preparation
+2.4 Initializing the library
+============================
+It is often desirable to check that the version of `Libgcrypt' used is
+indeed one which fits all requirements.  Even with binary compatibility
+new features may have been introduced but due to problem with the
+dynamic linker an old version is actually used.  So you may want to
+check that the version is okay right after program startup.
+ -- Function: const char *gcry_check_version (const char *REQ_VERSION)
+     The function `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 Libgcrypt.
+File: gcrypt.info,  Node: Multi Threading,  Prev: Initializing the library,  Up: Preparation
+2.5 Multi Threading
+===================
+As mentioned earlier, the `Libgcrypt' library is thread-safe if you
+adhere to the following requirements:
+   * If your application is multi-threaded, you must set the thread
+     support callbacks with the `GCRYCTL_SET_THREAD_CBS' command
+     *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.
+   * The function `gcry_check_version' must be called before any other
+     function in the library, except the `GCRYCTL_SET_THREAD_CBS'
+     command (called via the `gcry_control' function), because it
+     initializes the thread support subsystem in Libgcrypt.  To achieve
+     this in multi-threaded programs, you must synchronize the memory
+     with respect to other threads that also want to use Libgcrypt.
+     For this, it is sufficient to call `gcry_check_version' before
+     creating the other threads using Libgcrypt(1).
+   *  As with the function `gpg_strerror', `gcry_strerror' is not
+     thread safe.  You have to use `gpg_strerror_r' instead.
+   Libgcrypt contains convenient macros, which define the necessary
+thread callbacks for PThread and for GNU Pth:
+`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".
+`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".
+   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.
+   ---------- Footnotes ----------
+   (1) At least this is true for POSIX threads, as `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.
+File: gcrypt.info,  Node: Generalities,  Next: Handler Functions,  Prev: Preparation,  Up: Top
+3 Generalities
+**************
+* Menu:
+* Controlling the library::     Controlling Libgcrypt's behavior.
+* Modules::                     Description of extension modules.
+* Error Handling::              Error codes and such.
+File: gcrypt.info,  Node: Controlling the library,  Next: Modules,  Up: Generalities
+3.1 Controlling the library
+===========================
+ -- Function: gcry_error_t gcry_control (enum gcry_ctl_cmds CMD, ...)
+     This function can be used to influence the general behavior of
+     Libgcrypt in several ways.  Depending on CMD, more arguments can
+     or have to be provided.
+File: gcrypt.info,  Node: Modules,  Next: Error Handling,  Prev: Controlling the library,  Up: Generalities
+3.2 Modules
+===========
+Libgcrypt supports the use of `extension modules', which implement
+algorithms in addition to those already built into the library directly.
+ -- Data type: gcry_module_t
+     This data type represents a `module'.
+   Functions registering modules provided by the user take a `module
+specification structure' as input and return a value of `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 Libgcrypt until it is unregistered
+again.
+File: gcrypt.info,  Node: Error Handling,  Prev: Modules,  Up: Generalities
+3.3 Error Handling
+==================
+Many functions in 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.
+   Libgcrypt uses the `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, Libgcrypt does not use its own identifiers
+for error codes, but uses those provided by `libgpg-error'.  They
+usually start with `GPG_ERR_'.
+   However, Libgcrypt does provide aliases for the functions defined in
+libgpg-error, which might be preferred for name space consistency.
+   Most functions in 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.
+File: gcrypt.info,  Node: Error Values,  Next: Error Sources,  Up: Error Handling
+3.3.1 Error Values
+------------------
+ -- Data type: gcry_err_code_t
+     The `gcry_err_code_t' type is an alias for the `libgpg-error' type
+     `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.
+ -- Data type: gcry_err_source_t
+     The `gcry_err_source_t' type is an alias for the `libgpg-error'
+     type `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.
+ -- Data type: gcry_error_t
+     The `gcry_error_t' type is an alias for the `libgpg-error' type
+     `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
+     (`GPG_ERR_NO_ERROR'), and that in this case all other parts of the
+     error value are set to 0, too.
+     Note that in 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.
+ -- Function: gcry_err_code_t gcry_err_code (gcry_error_t ERR)
+     The static inline function `gcry_err_code' returns the
+     `gcry_err_code_t' component of the error value ERR.  This function
+     must be used to extract the error code from an error value in
+     order to compare it with the `GPG_ERR_*' error code macros.
+ -- Function: gcry_err_source_t gcry_err_source (gcry_error_t ERR)
+     The static inline function `gcry_err_source' returns the
+     `gcry_err_source_t' component of the error value ERR.  This
+     function must be used to extract the error source from an error
+     value in order to compare it with the `GPG_ERR_SOURCE_*' error
+     source macros.
+ -- Function: gcry_error_t gcry_err_make (gcry_err_source_t SOURCE,
+          gcry_err_code_t CODE)
+     The static inline function `gcry_err_make' returns the error value
+     consisting of the error source SOURCE and the error code CODE.
+     This function can be used in callback functions to construct an
+     error value to return it to the library.
+ -- Function: gcry_error_t gcry_error (gcry_err_code_t CODE)
+     The static inline function `gcry_error' returns the error value
+     consisting of the default error source and the error code CODE.
+     For GCRY applications, the default error source is
+     `GPG_ERR_SOURCE_USER_1'.  You can define `GCRY_ERR_SOURCE_DEFAULT'
+     before including `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.
+   The `libgpg-error' library provides error codes for all system error
+numbers it knows about.  If ERR is an unknown error number, the error
+code `GPG_ERR_UNKNOWN_ERRNO' is used.  The following functions can be
+used to construct error values from system errno numbers.
+ -- Function: gcry_error_t gcry_err_make_from_errno
+          (gcry_err_source_t SOURCE, int ERR)
+     The function `gcry_err_make_from_errno' is like `gcry_err_make',
+     but it takes a system error like `errno' instead of a
+     `gcry_err_code_t' error code.
+ -- Function: gcry_error_t gcry_error_from_errno (int ERR)
+     The function `gcry_error_from_errno' is like `gcry_error', but it
+     takes a system error like `errno' instead of a `gcry_err_code_t'
+     error code.
+   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.
+ -- Function: gcry_err_code_t gcry_err_code_from_errno (int ERR)
+     The function `gcry_err_code_from_errno' returns the error code for
+     the system error ERR.  If ERR is not a known system error, the
+     function returns `GPG_ERR_UNKNOWN_ERRNO'.
+ -- Function: int gcry_err_code_to_errno (gcry_err_code_t ERR)
+     The function `gcry_err_code_to_errno' returns the system error for
+     the error code ERR.  If ERR is not an error code representing a
+     system error, or if this system error is not defined on this
+     system, the function returns `0'.
+File: gcrypt.info,  Node: Error Sources,  Next: Error Codes,  Prev: Error Values,  Up: Error Handling
+3.3.2 Error Sources
+-------------------
+The library `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 `0', the whole error
+value will be `0'.  In this case the error source part is of course
+`GPG_ERR_SOURCE_UNKNOWN'.
+   The list of error sources that might occur in applications using
+Libgctypt is:
+`GPG_ERR_SOURCE_UNKNOWN'
+     The error source is not known.  The value of this error source is
+     `0'.
+`GPG_ERR_SOURCE_GPGME'
+     The error source is GPGME itself.
+`GPG_ERR_SOURCE_GPG'
+     The error source is GnuPG, which is the crypto engine used for the
+     OpenPGP protocol.
+`GPG_ERR_SOURCE_GPGSM'
+     The error source is GPGSM, which is the crypto engine used for the
+     OpenPGP protocol.
+`GPG_ERR_SOURCE_GCRYPT'
+     The error source is `libgcrypt', which is used by crypto engines
+     to perform cryptographic operations.
+`GPG_ERR_SOURCE_GPGAGENT'
+     The error source is `gpg-agent', which is used by crypto engines
+     to perform operations with the secret key.
+`GPG_ERR_SOURCE_PINENTRY'
+     The error source is `pinentry', which is used by `gpg-agent' to
+     query the passphrase to unlock a secret key.
+`GPG_ERR_SOURCE_SCD'
+     The error source is the SmartCard Daemon, which is used by
+     `gpg-agent' to delegate operations with the secret key to a
+     SmartCard.
+`GPG_ERR_SOURCE_KEYBOX'
+     The error source is `libkbx', a library used by the crypto engines
+     to manage local keyrings.
+`GPG_ERR_SOURCE_USER_1'
+`GPG_ERR_SOURCE_USER_2'
+`GPG_ERR_SOURCE_USER_3'
+`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 Libgcrypt
+     can use them to mark error values coming from callback handlers.
+     Thus `GPG_ERR_SOURCE_USER_1' is the default for errors created
+     with `gcry_error' and `gcry_error_from_errno', unless you define
+     `GCRY_ERR_SOURCE_DEFAULT' before including `gcrypt.h'.
+File: gcrypt.info,  Node: Error Codes,  Next: Error Strings,  Prev: Error Sources,  Up: Error Handling
+3.3.3 Error Codes
+-----------------
+The library `libgpg-error' defines many error values.  The following
+list includes the most important error codes.
+`GPG_ERR_EOF'
+     This value indicates the end of a list, buffer or file.
+`GPG_ERR_NO_ERROR'
+     This value indicates success.  The value of this error code is
+     `0'.  Also, it is guaranteed that an error value made from the
+     error code `0' will be `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.
+`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.
+`GPG_ERR_ENOMEM'
+     This value means that an out-of-memory condition occurred.
+`GPG_ERR_E...'
+     System errors are mapped to GPG_ERR_EFOO where FOO is the symbol
+     for the system error.
+`GPG_ERR_INV_VALUE'
+     This value means that some user provided data was out of range.
+`GPG_ERR_UNUSABLE_PUBKEY'
+     This value means that some recipients for a message were invalid.
+`GPG_ERR_UNUSABLE_SECKEY'
+     This value means that some signers were invalid.
+`GPG_ERR_NO_DATA'
+     This value means that data was expected where no data was found.
+`GPG_ERR_CONFLICT'
+     This value means that a conflict of some sort occurred.
+`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.
+`GPG_ERR_DECRYPT_FAILED'
+     This value indicates that a decryption operation was unsuccessful.
+`GPG_ERR_WRONG_KEY_USAGE'
+     This value indicates that a key is not used appropriately.
+`GPG_ERR_NO_SECKEY'
+     This value indicates that no secret key for the user ID is
+     available.
+`GPG_ERR_UNSUPPORTED_ALGORITHM'
+     This value means a verification failed because the cryptographic
+     algorithm is not supported by the crypto backend.
+`GPG_ERR_BAD_SIGNATURE'
+     This value means a verification failed because the signature is
+     bad.
+`GPG_ERR_NO_PUBKEY'
+     This value means a verification failed because the public key is
+     not available.
+`GPG_ERR_USER_1'
+`GPG_ERR_USER_2'
+`...'
+`GPG_ERR_USER_16'
+     These error codes are not used by any GnuPG component and can be
+     freely used by other software.  Applications using 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.
+File: gcrypt.info,  Node: Error Strings,  Prev: Error Codes,  Up: Error Handling
+3.3.4 Error Strings
+-------------------
+ -- Function: const char * gcry_strerror (gcry_error_t ERR)
+     The function `gcry_strerror' returns a pointer to a statically
+     allocated string containing a description of the error code
+     contained in the error value ERR.  This string can be used to
+     output a diagnostic message to the user.
+ -- Function: const char * gcry_strsource (gcry_error_t ERR)
+     The function `gcry_strerror' returns a pointer to a statically
+     allocated string containing a description of the error source
+     contained in the error value ERR.  This string can be used to
+     output a diagnostic message to the user.
+   The following example illustrates the use of the functions described
+above:
+     {
+       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));
+         }
+     }
+File: gcrypt.info,  Node: Handler Functions,  Next: Symmetric cryptography,  Prev: Generalities,  Up: Top
+4 Handler Functions
+*******************
+Libgcrypt makes it possible to install so called `handler functions',
+which get called by 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.
+File: gcrypt.info,  Node: Progress handler,  Next: Allocation handler,  Up: Handler Functions
+4.1 Progress handler
+====================
+It is often useful to retrieve some feedback while long running
+operations are performed.
+ -- Data type: gcry_handler_progress_t
+     Progress handler functions have to be of the type
+     `gcry_handler_progress_t', which is defined as:
+     `void (*gcry_handler_progress_t) (void *, const char *, int, int,
+     int)'
+   The following function may be used to register a handler function for
+this purpose.
+ -- Function: void gcry_set_progress_handler (gcry_handler_progress_t
+          CB, void *CB_DATA)
+     This function installs CB as the `Progress handler' function.  CB
+     must be defined as follows:
+          void
+          my_progress_handler (void *CB_DATA, const char *WHAT,
+                               int PRINTCHAR, int CURRENT, int TOTAL)
+          {
+            /* Do something.  */
+          }
+     A description of the arguments of the progress handler function
+     follows.
+    CB_DATA
+          The argument provided in the call to
+          `gcry_set_progress_handler'.
+    WHAT
+          A string identifying the type of the progress output.  The
+          following values for WHAT are defined:
+         `need_entropy'
+               Not enough entropy is available.  TOTAL holds the number
+               of required bytes.
+         `primegen'
+               Values for PRINTCHAR:
+              `\n'
+                    Prime generated.
+              `!'
+                    Need to refresh the pool of prime numbers.
+              `<, >'
+                    Number of bits adjusted.
+              `^'
+                    Searching for a generator.
+              `.'
+                    Fermat test on 10 candidates failed.
+              `:'
+                    Restart with a new random value.
+              `+'
+                    Rabin Miller test passed.
+File: gcrypt.info,  Node: Allocation handler,  Next: Error handler,  Prev: Progress handler,  Up: Handler Functions
+4.2 Allocation handler
+======================
+It is possible to make Libgcrypt use special memory allocation
+functions instead of the built-in ones.
+   Memory allocation functions are of the following types:
+ -- Data type: gcry_handler_alloc_t
+     This type is defined as: `void *(*gcry_handler_alloc_t) (size_t
+     n)'.
+ -- Data type: gcry_handler_secure_check_t
+     This type is defined as: `int *(*gcry_handler_secure_check_t)
+     (const void *)'.
+ -- Data type: gcry_handler_realloc_t
+     This type is defined as: `void *(*gcry_handler_realloc_t) (void
+     *p, size_t n)'.
+ -- Data type: gcry_handler_free_t
+     This type is defined as: `void *(*gcry_handler_free_t) (void *)'.
+   Special memory allocation functions can be installed with the
+following function:
+ -- Function: void gcry_set_allocation_handler (gcry_handler_alloc_t
+          FUNC_ALLOC, gcry_handler_alloc_t FUNC_ALLOC_SECURE,
+          gcry_handler_secure_check_t FUNC_SECURE_CHECK,
+          gcry_handler_realloc_t FUNC_REALLOC, gcry_handler_free_t
+          FUNC_FREE)
+     Install the provided functions and use them instead of the built-in
+     functions for doing memory allocation.
+File: gcrypt.info,  Node: Error handler,  Next: Logging handler,  Prev: Allocation handler,  Up: Handler Functions
+4.3 Error handler
+=================
+The following functions may be used to register handler functions that
+are called by Libgcrypt in case certain error conditions occur.
+ -- Data type: gcry_handler_no_mem_t
+     This type is defined as: `void (*gcry_handler_no_mem_t) (void *,
+     size_t, unsigned int)'
+ -- Function: void gcry_set_outofcore_handler (gcry_handler_no_mem_t
+          FUNC_NO_MEM, void *CB_DATA)
+     This function registers FUNC_NO_MEM as `out-of-core handler',
+     which means that it will be called in the case of not having enough
+     memory available.
+ -- Data type: gcry_handler_error_t
+     This type is defined as: `void (*gcry_handler_error_t) (void *,
+     int, const char *)'
+ -- Function: void gcry_set_fatalerror_handler (gcry_handler_error_t
+          FUNC_ERROR, void *CB_DATA)
+     This function registers FUNC_ERROR as `error handler', which means
+     that it will be called in error conditions.
+File: gcrypt.info,  Node: Logging handler,  Prev: Error handler,  Up: Handler Functions
+4.4 Logging handler
+===================
+ -- Data type: gcry_handler_log_t
+     This type is defined as: `void (*gcry_handler_log_t) (void *, int,
+     const char *, va_list)'
+ -- Function: void gcry_set_log_handler (gcry_handler_log_t FUNC_LOG,
+          void *CB_DATA)
+     This function registers FUNC_LOG as `logging handler', which means
+     that it will be called in case Libgcrypt wants to log a message.
+File: gcrypt.info,  Node: Symmetric cryptography,  Next: Hashing,  Prev: Handler Functions,  Up: Top
+5 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 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.
+File: gcrypt.info,  Node: Available ciphers,  Next: Cipher modules,  Up: Symmetric cryptography
+5.1 Available ciphers
+=====================
+`GCRY_CIPHER_NONE'
+     This is not a real algorithm but used by some functions as error
+     return.  The value always evaluates to false.
+`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.
+`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.
+`GCRY_CIPHER_CAST5'
+     CAST128-5 block cipher algorithm.  The key size is 128 bits.
+`GCRY_CIPHER_BLOWFISH'
+     The blowfish algorithm. The current implementation allows only for
+     a key size of 128 bits.
+`GCRY_CIPHER_SAFER_SK128'
+     Reserved and not currently implemented.
+`GCRY_CIPHER_DES_SK'
+     Reserved and not currently implemented.
+`GCRY_CIPHER_AES'
+`GCRY_CIPHER_AES128'
+`GCRY_CIPHER_RIJNDAEL'
+`GCRY_CIPHER_RIJNDAEL128'
+     AES (Rijndael) with a 128 bit key.
+`GCRY_CIPHER_AES192'
+`GCRY_CIPHER_RIJNDAEL128'
+     AES (Rijndael) with a 192 bit key.
+`GCRY_CIPHER_AES256'
+`GCRY_CIPHER_RIJNDAEL256'
+     AES (Rijndael) with a 256 bit key.
+`GCRY_CIPHER_TWOFISH'
+     The Twofish algorithm with a 256 bit key.
+`GCRY_CIPHER_TWOFISH128'
+     The Twofish algorithm with a 128 bit key.
+`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.
+`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.
+File: gcrypt.info,  Node: Cipher modules,  Next: Available cipher modes,  Prev: Available ciphers,  Up: Symmetric cryptography
+5.2 Cipher modules
+==================
+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
+*Note Modules::.
+ -- 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:
+    `const char *name'
+          The primary name of the algorithm.
+    `const char **aliases'
+          A list of strings that are `aliases' for the algorithm.  The
+          list must be terminated with a NULL element.
+    `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.
+    `size_t blocksize'
+          The block size of the algorithm, in bytes.
+    `size_t keylen'
+          The length of the key, in bits.
+    `size_t contextsize'
+          The size of the algorithm-specific `context', that should be
+          allocated for each handle.
+    `gcry_cipher_setkey_t setkey'
+          The function responsible for initializing a handle with a
+          provided key.  See below for a description of this type.
+    `gcry_cipher_encrypt_t encrypt'
+          The function responsible for encrypting a single block.  See
+          below for a description of this type.
+    `gcry_cipher_decrypt_t decrypt'
+          The function responsible for decrypting a single block.  See
+          below for a description of this type.
+    `gcry_cipher_stencrypt_t stencrypt'
+          Like `encrypt', for stream ciphers.  See below for a
+          description of this type.
+    `gcry_cipher_stdecrypt_t stdecrypt'
+          Like `decrypt', for stream ciphers.  See below for a
+          description of this type.
+ -- 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:
+    `const char *oid'
+          Textual representation of the OID.
+    `int mode'
+          Cipher mode for which this OID is valid.
+ -- 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)
+ -- 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)
+ -- 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)
+ -- 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)
+ -- 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)
+ -- Function: gcry_error_t gcry_cipher_register (gcry_cipher_spec_t
+          *CIPHER, unsigned int *algorithm_id, gcry_module_t *MODULE)
+     Register a new cipher module whose specification can be found in
+     CIPHER.  On success, a new algorithm ID is stored in ALGORITHM_ID
+     and a pointer representing this module is stored in MODULE.
+ -- Function: void gcry_cipher_unregister (gcry_module_t MODULE)
+     Unregister the cipher identified by MODULE, which must have been
+     registered with gcry_cipher_register.
+ -- Function: gcry_error_t gcry_cipher_list (int *LIST, int
+          *LIST_LENGTH)
+     Get a list consisting of the IDs of the loaded cipher modules.  If
+     LIST is zero, write the number of loaded cipher modules to
+     LIST_LENGTH and return.  If LIST is non-zero, the first
+     *LIST_LENGTH algorithm IDs are stored in LIST, which must be of
+     according size.  In case there are less cipher modules than
+     *LIST_LENGTH, *LIST_LENGTH is updated to the correct number.
+File: gcrypt.info,  Node: Available cipher modes,  Next: Working with cipher handles,  Prev: Cipher modules,  Up: Symmetric cryptography
+5.3 Available cipher modes
+==========================
+`GCRY_CIPHER_MODE_NONE'
+     No mode specified, may be set later using other functions.  The
+     value of this constant is always 0.
+`GCRY_CIPHER_MODE_ECB'
+     Electronic Codebook mode.
+`GCRY_CIPHER_MODE_CFB'
+     Cipher Feedback mode.
+`GCRY_CIPHER_MODE_CBC'
+     Cipher Block Chaining mode.
+`GCRY_CIPHER_MODE_STREAM'
+     Stream mode, only to be used with stream cipher algorithms.
+`GCRY_CIPHER_MODE_OFB'
+     Outer Feedback mode.
+`GCRY_CIPHER_MODE_CTR'
+     Counter mode.
+File: gcrypt.info,  Node: Working with cipher handles,  Next: General cipher functions,  Prev: Available cipher modes,  Up: Symmetric cryptography
+5.4 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:
+ -- Function: gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *HD, int
+          ALGO, int MODE, unsigned int 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 ALGO.  See *Note
+     Available ciphers::, for a list of supported ciphers and the
+     according constants.
+     Besides using the constants directly, the function
+     `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 MODE.  See *Note
+     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 FLAGS can either be passed as `0' or as the
+     bit-wise OR of the following constants.
+    `GCRY_CIPHER_SECURE'
+          Make sure that all operations are allocated in secure memory.
+          This is useful, when the key material is highly confidential.
+    `GCRY_CIPHER_ENABLE_SYNC'
+          This flag enables the CFB sync mode, which is a special
+          feature of Libgcrypt's CFB mode implementation to allow for
+          OpenPGP's CFB variant.  See `gcry_cipher_sync'.
+    `GCRY_CIPHER_CBC_CTS'
+          Enable cipher text stealing (CTS) for the CBC mode.  Cannot
+          be used simultaneous as GCRY_CIPHER_CBC_MAC
+    `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.
+   Use the following function to release an existing handle:
+ -- Function: void gcry_cipher_close (gcry_cipher_hd_t H)
+     This function releases the context created by `gcry_cipher_open'.
+   In order to use a handle for performing cryptographic operations, a
+`key' has to be set first:
+ -- Function: gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t H, void
+          *K, size_t L)
+     Set the key K used for encryption or decryption in the context
+     denoted by the handle H.  The length L of the key 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.
+   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:
+ -- Function: gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t H, void
+          *K, size_t L)
+     Set the initialization vector used for encryption or decryption.
+     The vector is passed as the buffer K of length 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.
+ -- Function: gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t H, void
+          *C, size_t L)
+     Set the counter vector used for encryption or decryption. The
+     counter is passed as the buffer C of length 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.
+ -- Function: gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t 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.
+   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.
+ -- Function: gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t H,
+          void *out, size_t OUTSIZE, const void *IN, size_t INLEN)
+     `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 H.  There are 2
+     ways to use the function: If IN is passed as `NULL' and INLEN is
+     `0', in-place encryption of the data in OUT or length OUTSIZE
+     takes place.  With IN being not `NULL', INLEN bytes are encrypted
+     to the buffer OUT which must have at least a size of INLEN.
+     OUTLEN must be set to the allocated size of 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 `0' on success or an error code.
+ -- Function: gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t H,
+          void *out, size_t OUTSIZE, const void *IN, size_t INLEN)
+     `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 H.  There are 2
+     ways to use the function: If IN is passed as `NULL' and INLEN is
+     `0', in-place decryption of the data in OUT or length OUTSIZE
+     takes place.  With IN being not `NULL', INLEN bytes are decrypted
+     to the buffer OUT which must have at least a size of INLEN.
+     OUTLEN must be set to the allocated size of 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 `0' on success or an error code.
+   OpenPGP (as defined in RFC-2440) requires a special sync operation in
+some places, the following function is used for this:
+ -- Function: gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t H)
+     Perform the OpenPGP sync operation on context H. Note, that this
+     is a no-op unless the context was created with the flag
+     `GCRY_CIPHER_ENABLE_SYNC'
+   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:
+ -- Function: gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t H, int
+          CMD, void *BUFFER, size_t BUFLEN)
+     `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 CMD and the
+     passed context handle H.  Please see the comments in the source
+     code (`src/global.c') for details.
+ -- Function: gcry_error_t gcry_cipher_info (gcry_cipher_hd_t H, int
+          WHAT, void *BUFFER, size_t *NBYTES)
+     `gcry_cipher_info' is used to retrieve various information about a
+     cipher context or the cipher module in general.
+     Currently no information is available.
+File: gcrypt.info,  Node: General cipher functions,  Prev: Working with cipher handles,  Up: Symmetric cryptography
+5.5 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.
+ -- Function: gcry_error_t gcry_cipher_algo_info (int ALGO, int WHAT,
+          void *BUFFER, size_t *NBYTES)
+     This function is used to retrieve information on a specific
+     algorithm.  You pass the cipher algorithm ID as ALGO and the type
+     of information requested as WHAT. The result is either returned as
+     the return code of the function or copied to the provided BUFFER
+     whose allocated length must be available in an integer variable
+     with the address passed in NBYTES.  This variable will also
+     receive the actual used length of the buffer.
+     Here is a list of supported codes for WHAT:
+    `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 NBYTES; BUFFER must be zero.
+    `GCRYCTL_GET_BLKLEN:'
+          Return the block length of the algorithm.  The length is
+          returned as a number of octets in NBYTES; BUFFER must be zero.
+    `GCRYCTL_TEST_ALGO:'
+          Returns `0' when the specified algorithm is available for use.
+          BUFFER and NBYTES must be zero.
+ -- Function: const char *gcry_cipher_algo_name (int ALGO)
+     `gcry_cipher_algo_name' returns a string with the name of the
+     cipher algorithm ALGO.  If the algorithm is not known or another
+     error occurred, an empty string is returned.  This function will
+     never return `NULL'.
+ -- Function: int gcry_cipher_map_name (const char *NAME)
+     `gcry_cipher_map_name' returns the algorithm identifier for the
+     cipher algorithm described by the string NAME.  If this algorithm
+     is not available `0' is returned.
+ -- Function: int gcry_cipher_mode_from_oid (const char *STRING)
+     Return the cipher mode associated with an ASN.1 object identifier.
+     The object identifier is expected to be in the IETF-style dotted
+     decimal notation.  The function returns `0' for an unknown object
+     identifier or when no mode is associated with it.
+File: gcrypt.info,  Node: Hashing,  Next: Public Key cryptography (I),  Prev: Symmetric cryptography,  Up: Top
+6 Hashing
+*********
+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 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.
+File: gcrypt.info,  Node: Available hash algorithms,  Next: Hash algorithm modules,  Up: Hashing
+6.1 Available hash algorithms
+=============================
+`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 `0'.
+`GCRY_MD_SHA1'
+     This is the SHA-1 algorithm which yields a message digest of 20
+     bytes.
+`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.
+`GCRY_MD_MD5'
+     This is the well known MD5 algorithm, which yields a message
+     digest of 16 bytes.
+`GCRY_MD_MD4'
+     This is the MD4 algorithm, which yields a message digest of 16
+     bytes.
+`GCRY_MD_MD2'
+     This is an reserved identifier for MD-2; there is no
+     implementation yet.
+`GCRY_MD_TIGER'
+     This is the TIGER/192 algorithm which yields a message digest of
+     24 bytes.
+`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.
+`GCRY_MD_SHA256'
+     This is the SHA-256 algorithm which yields a message digest of 32
+     bytes.  See FIPS 180-2 for the specification.
+`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.
+`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.
+`GCRY_MD_CRC32'
+     This is the ISO 3309 and ITU-T V.42 cyclic redundancy check.  It
+     yields an output of 4 bytes.
+`GCRY_MD_CRC32_RFC1510'
+     This is the above cyclic redundancy check function, as modified by
+     RFC 1510.  It yields an output of 4 bytes.
+`GCRY_MD_CRC24_RFC2440'
+     This is the OpenPGP cyclic redundancy check function.  It yields an
+     output of 3 bytes.
+File: gcrypt.info,  Node: Hash algorithm modules,  Next: Working with hash algorithms,  Prev: Available hash algorithms,  Up: Hashing
+6.2 Hash algorithm modules
+==========================
+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 *Note Modules::.
+ -- 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:
+    `const char *name'
+          The primary name of this algorithm.
+    `unsigned char *asnoid'
+          Array of bytes that form the ASN OID.
+    `int asnlen'
+          Length of bytes in `asnoid'.
+    `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.
+    `int mdlen'
+          Length of the message digest algorithm.  See below for an
+          explanation of this type.
+    `gcry_md_init_t init'
+          The function responsible for initializing a handle.  See
+          below for an explanation of this type.
+    `gcry_md_write_t write'
+          The function responsible for writing data into a message
+          digest context.  See below for an explanation of this type.
+    `gcry_md_final_t final'
+          The function responsible for `finalizing' a message digest
+          context.  See below for an explanation of this type.
+    `gcry_md_read_t read'
+          The function responsible for reading out a message digest
+          result.  See below for an explanation of this type.
+    `size_t contextsize'
+          The size of the algorithm-specific `context', that should be
+          allocated for each handle.
+ -- 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:
+    `const char *oidstring'
+          Textual representation of the OID.
+ -- Data type: gcry_md_init_t
+     Type for the `init' function, defined as: void (*gcry_md_init_t)
+     (void *c)
+ -- 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)
+ -- Data type: gcry_md_final_t
+     Type for the `final' function, defined as: void (*gcry_md_final_t)
+     (void *c)
+ -- Data type: gcry_md_read_t
+     Type for the `read' function, defined as: unsigned char
+     *(*gcry_md_read_t) (void *c)
+ -- Function: gcry_error_t gcry_md_register (gcry_md_spec_t *DIGEST,
+          unsigned int *algorithm_id, gcry_module_t *MODULE)
+     Register a new digest module whose specification can be found in
+     DIGEST.  On success, a new algorithm ID is stored in ALGORITHM_ID
+     and a pointer representing this module is stored in MODULE.
+ -- Function: void gcry_md_unregister (gcry_module_t MODULE)
+     Unregister the digest identified by MODULE, which must have been
+     registered with gcry_md_register.
+ -- Function: gcry_error_t gcry_md_list (int *LIST, int *LIST_LENGTH)
+     Get a list consisting of the IDs of the loaded message digest
+     modules.  If LIST is zero, write the number of loaded message
+     digest modules to LIST_LENGTH and return.  If LIST is non-zero,
+     the first *LIST_LENGTH algorithm IDs are stored in LIST, which
+     must be of according size.  In case there are less message digests
+     modules than *LIST_LENGTH, *LIST_LENGTH is updated to the correct
+     number.
+File: gcrypt.info,  Node: Working with hash algorithms,  Prev: Hash algorithm modules,  Up: Hashing
+6.3 Working with hash algorithms
+================================
+To use most of these function it is necessary to create a context; this
+is done using:
+ -- Function: gcry_error_t gcry_md_open (gcry_md_hd_t *HD, int ALGO,
+          unsigned int FLAGS)
+     Create a message digest object for algorithm ALGO.  FLAGS may be
+     given as an bitwise OR of constants described below.  ALGO may be
+     given as `0' if the algorithms to use are later set using
+     `gcry_md_enable'. HD is guaranteed to either receive a valid
+     handle or NULL.
+     For a list of supported algorithms, see *Note Available hash
+     algorithms::.
+     The flags allowed for MODE are:
+    `GCRY_MD_FLAG_SECURE'
+          Allocate all buffers and the resulting digest in "secure
+          memory".  Use this is the hashed data is highly confidential.
+    `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 `gcry_md_setkey' must be used set the
+          MAC key.  If you want CBC message authentication codes based
+          on a cipher, see *Note Working with cipher handles::.
+     You may use the function `gcry_md_is_enabled' to later check
+     whether an algorithm has been enabled.
+   If you want to calculate several hash algorithms at the same time,
+you have to use the following function right after the `gcry_md_open':
+ -- Function: gcry_error_t gcry_md_enable (gcry_md_hd_t H, int ALGO)
+     Add the message digest algorithm ALGO to the digest object
+     described by handle H.  Duplicated enabling of algorithms is
+     detected and ignored.
+   If the flag `GCRY_MD_FLAG_HMAC' was used, the key for the MAC must
+be set using the function:
+ -- Function: gcry_error_t gcry_md_setkey (gcry_md_hd_t H, const void
+          *KEY, size_t KEYLEN)
+     For use with the HMAC feature, set the MAC key to the value of KEY
+     of length KEYLEN.
+   After you are done with the hash calculation, you should release the
+resources by using:
+ -- Function: void gcry_md_close (gcry_md_hd_t H)
+     Release all resources of hash context H.  H should not be used
+     after a call to this function.  A `NULL' passed as H is ignored.
+   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:
+ -- Function: void gcry_md_reset (gcry_md_hd_t 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.
+   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:
+ -- Function: gcry_error_t gcry_md_copy (gcry_md_hd_t *HANDLE_DST,
+          gcry_md_hd_t HANDLE_SRC)
+     Create a new digest object as an exact copy of the object
+     described by handle HANDLE_SRC and store it in HANDLE_DST.  The
+     context is not reset and you can continue to hash data using this
+     context and independently using the original context.
+   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.
+ -- Function: void gcry_md_write (gcry_md_hd_t H, const void *BUFFER,
+          size_t LENGTH)
+     Pass LENGTH bytes of the data in BUFFER to the digest object with
+     handle H to update the digest values. This function should be used
+     for large blocks of data.
+ -- Function: void gcry_md_putc (gcry_md_hd_t H, int C)
+     Pass the byte in C to the digest object with handle H to update
+     the digest value.  This is an efficient function, implemented as a
+     macro to buffer the data before an actual update.
+   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.
+ -- Function: void gcry_md_final (gcry_md_hd_t H)
+     Finalize the message digest calculation.  This is not really needed
+     because `gcry_md_read' does this implicitly.  After this has been
+     done no further updates (by means of `gcry_md_write' or
+     `gcry_md_putc' are allowed.  Only the first call to this function
+     has an effect. It is implemented as a macro.
+   The way to read out the calculated message digest is by using the
+function:
+ -- Function: unsigned char *gcry_md_read (gcry_md_hd_t H, int ALGO)
+     `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
+     `gcry_md_close' or `gcry_md_reset'.  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 `NULL' if the
+     requested algorithm has not been enabled.
+   Because it is often necessary to get the message digest of one block
+of memory, a fast convenience function is available for this task:
+ -- Function: void gcry_md_hash_buffer (int ALGO, void *DIGEST, const
+          cvoid *BUFFER, size_t LENGTH);
+     `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 LENGTH bytes at
+     BUFFER.  DIGEST must be allocated by the caller, large enough to
+     hold the message digest yielded by the the specified algorithm
+     ALGO.  This required size may be obtained by using the function
+     `gcry_md_get_algo_dlen'.
+     Note, that this function will abort the process if an unavailable
+     algorithm is used.
+   Hash algorithms are identified by internal algorithm numbers (see
+`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.
+ -- Function: const char *gcry_md_algo_name (int ALGO)
+     Map the digest algorithm id 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.
+ -- Function: int gcry_md_map_name (const char *NAME)
+     Map the algorithm with NAME to a digest algorithm identifier.
+     Returns 0 if the algorithm name is not known.  Names representing
+     ASN.1 object identifiers are recognized if the IETF dotted format
+     is used and the OID is prefixed with either "`oid.'" or "`OID.'".
+     For a list of supported OIDs, see the source code at
+     `cipher/md.c'. This function should not be used to test for the
+     availability of an algorithm.
+ -- Function: gcry_error_t gcry_md_get_asnoid (int ALGO, void *BUFFER,
+          size_t *LENGTH)
+     Return an DER encoded ASN.1 OID for the algorithm ALGO in the user
+     allocated BUFFER. LENGTH must point to variable with the available
+     size of BUFFER and receives after return the actual size of the
+     returned OID.  The returned error code may be `GPG_ERR_TOO_SHORT'
+     if the provided buffer is to short to receive the OID; it is
+     possible to call the function with `NULL' for BUFFER to have it
+     only return the required size.  The function returns 0 on success.
+   To test whether an algorithm is actually available for use, the
+following macro should be used:
+ -- Function: gcry_error_t gcry_md_test_algo (int ALGO)
+     The macro returns 0 if the algorithm ALGO is available for use.
+   If the length of a message digest is not known, it can be retrieved
+using the following function:
+ -- Function: unsigned int gcry_md_get_algo_dlen (int ALGO)
+     Retrieve the length in bytes of the digest yielded by algorithm
+     ALGO.  This is often used prior to `gcry_md_read' to allocate
+     sufficient memory for the digest.
+   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:
+ -- Function: int gcry_md_get_algo (gcry_md_hd_t H)
+     Retrieve the algorithm used with the handle H. Note, that this
+     does not work reliable if more than one algorithm is enabled in H.
+   The following macro might also be useful:
+ -- Function: int gcry_md_is_secure (gcry_md_hd_t H)
+     This function returns true when the digest object H is allocated
+     in "secure memory"; i.e. H was created with the
+     `GCRY_MD_FLAG_SECURE'.
+ -- Function: int gcry_md_is_enabled (gcry_md_hd_t H, int ALGO)
+     This function returns true when the algorithm ALGO has been
+     enabled for the digest object H.
+   Tracking bugs related to hashing is often a cumbersome task which
+requires to add a lot of printf statements into the code.  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:
+ -- Function: void gcry_md_start_debug (gcry_md_hd_t H, const char
+          *SUFFIX)
+     Enable debugging for the digest object with handle H.  This
+     creates create files named `dbgmd-<n>.<string>' while doing the
+     actual hashing.  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 `gcry_md_write' or
+     `gcry_md_putc'.
+ -- Function: void gcry_md_stop_debug (gcry_md_hd_t H, int RESERVED)
+     Stop debugging on handle H.  RESERVED should be specified as 0.
+     This function is usually not required because `gcry_md_close' does
+     implicitly stop debugging.
+File: gcrypt.info,  Node: Public Key cryptography (I),  Next: Public Key cryptography (II),  Prev: Hashing,  Up: Top
+7 Public Key cryptography (I)
+*****************************
+Public key cryptography, also known as asymmetric cryptography, is an
+easy way for key management and to provide digital signatures.
+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.
+File: gcrypt.info,  Node: Available algorithms,  Next: Used S-expressions,  Up: Public Key cryptography (I)
+7.1 Available algorithms
+========================
+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.
+File: gcrypt.info,  Node: Used S-expressions,  Next: Public key modules,  Prev: Available algorithms,  Up: Public Key cryptography (I)
+7.2 Used S-expressions
+======================
+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 Libgcrypt do.
+   The following information are stored in S-expressions:
+keys
+plain text data
+encrypted data
+signatures
+To describe how Libgcrypt expect keys, we use some examples. Note that
+words in uppercase indicate parameters whereas lowercase words are
+literals.
+     (private-key
+       (dsa
+         (p P-MPI)
+         (q Q-MPI)
+         (g G-MPI)
+         (y Y-MPI)
+         (x X-MPI)))
+This specifies a DSA private key with the following parameters:
+P-MPI
+     DSA prime p.
+Q-MPI
+     DSA group order q (which is a prime divisor of p-1).
+G-MPI
+     DSA group generator g.
+Y-MPI
+     DSA public key value y = g^x \bmod p.
+X-MPI
+     DSA secret exponent x.
+   All the MPI values are  expected to be in `GCRYMPI_FMT_USG' format.
+The public key is similar with "private-key" replaced by "public-key"
+and no X-MPI.
+   An easy way to create such an S-expressions is by using
+`gcry_sexp_build' which allows to pass a string with printf-like
+escapes to insert MPI values.
+Here is an example for an RSA key:
+     (private-key
+       (rsa
+         (n N-MPI)
+         (e E-MPI)
+         (d D-MPI)
+         (p P-MPI)
+         (q Q-MPI)
+         (u U-MPI)
+with
+N-MPI
+     RSA public modulus n.
+E-MPI
+     RSA public exponent e.
+D-MPI
+     RSA secret exponent d = e^-1 \bmod (p-1)(q-1).
+P-MPI
+     RSA secret prime p.
+Q-MPI
+     RSA secret prime q with q > p.
+U-MPI
+     multiplicative inverse u = p^-1 \bmod q.
+File: gcrypt.info,  Node: Public key modules,  Next: Cryptographic Functions,  Prev: Used S-expressions,  Up: Public Key cryptography (I)
+7.3 Public key modules
+======================
+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 *Note Modules::.
+ -- 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:
+    `const char *name'
+          The primary name of this algorithm.
+    `char **aliases'
+          A list of strings that are `aliases' for the algorithm.  The
+          list must be terminated with a NULL element.
+    `const char *elements_pkey'
+          String containing the one-letter names of the MPI values
+          contained in a public key.
+    `const char *element_skey'
+          String containing the one-letter names of the MPI values
+          contained in a secret key.
+    `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.
+    `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.
+    `const char *elements_grip'
+          String containing the one-letter names of the MPI values that
+          are to be included in the `key grip'.
+    `int use'
+          The bitwise-OR of the following flags, depending on the
+          abilities of the algorithm:
+         `GCRY_PK_USAGE_SIGN'
+               The algorithm supports signing and verifying of data.
+         `GCRY_PK_USAGE_ENCR'
+               The algorithm supports the encryption and decryption of
+               data.
+    `gcry_pk_generate_t generate'
+          The function responsible for generating a new key pair.  See
+          below for a description of this type.
+    `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.
+    `gcry_pk_encrypt_t encrypt'
+          The function responsible for encrypting data.  See below for a
+          description of this type.
+    `gcry_pk_decrypt_t decrypt'
+          The function responsible for decrypting data.  See below for a
+          description of this type.
+    `gcry_pk_sign_t sign'
+          The function responsible for signing data.  See below for a
+          description of this type.
+    `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.
+    `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.
+ -- 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)
+ -- 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)
+ -- 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)
+ -- 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)
+ -- 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)
+ -- 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)
+ -- 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)
+ -- Function: gcry_error_t gcry_pk_register (gcry_pk_spec_t *PUBKEY,
+          unsigned int *algorithm_id, gcry_module_t *MODULE)
+     Register a new public key module whose specification can be found
+     in PUBKEY.  On success, a new algorithm ID is stored in
+     ALGORITHM_ID and a pointer representing this module is stored in
+     MODULE.
+ -- Function: void gcry_pk_unregister (gcry_module_t MODULE)
+     Unregister the public key module identified by MODULE, which must
+     have been registered with gcry_pk_register.
+ -- Function: gcry_error_t gcry_pk_list (int *LIST, int *LIST_LENGTH)
+     Get a list consisting of the IDs of the loaded pubkey modules.  If
+     LIST is zero, write the number of loaded pubkey modules to
+     LIST_LENGTH and return.  If LIST is non-zero, the first
+     *LIST_LENGTH algorithm IDs are stored in LIST, which must be of
+     according size.  In case there are less pubkey modules than
+     *LIST_LENGTH, *LIST_LENGTH is updated to the correct number.
+File: gcrypt.info,  Node: Cryptographic Functions,  Next: General public-key related Functions,  Prev: Public key modules,  Up: Public Key cryptography (I)
+7.4 Cryptographic Functions
+===========================
+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.
+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:
+PKCS1
+     Use PKCS#1 block type 2 padding.
+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.
+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:
+ -- Function: gcry_error_t gcry_pk_encrypt (gcry_sexp_t *R_CIPH,
+          gcry_sexp_t DATA, gcry_sexp_t PKEY)
+     Obviously a public key must be provided for encryption.  It is
+     expected as an appropriate S-expression (see above) in 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.
+     If you don't want to let Libgcrypt handle the padding, you must
+     pass an appropriate MPI using this expression for DATA:
+          (data
+            (flags raw)
+            (value MPI))
+     This has the same semantics as the old style MPI only way.  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 DATA:
+          (data
+            (flags pkcs1)
+            (value BLOCK))
+     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
+     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
+     R_CIPH.  The caller is responsible to release this value using
+     `gcry_sexp_release'.  In case of an error, an error code is
+     returned and R_CIPH will be set to `NULL'.
+     The returned S-expression has this format when used with RSA:
+          (enc-val
+            (rsa
+              (a A-MPI)))
+     Where A-MPI is an MPI with the result of the RSA operation.  When
+     using the ElGamal algorithm, the return value will have this
+     format:
+          (enc-val
+            (elg
+              (a A-MPI)
+              (b B-MPI)))
+     Where A-MPI and B-MPI are MPIs with the result of the ElGamal
+     encryption operation.
+ -- Function: gcry_error_t gcry_pk_decrypt (gcry_sexp_t *R_PLAIN,
+          gcry_sexp_t DATA, gcry_sexp_t SKEY)
+     Obviously a private key must be provided for decryption.  It is
+     expected as an appropriate S-expression (see above) in SKEY.  The
+     data to be decrypted must match the format of the result as
+     returned by `gcry_pk_encrypt', but should be enlarged with a
+     `flags' element:
+          (enc-val
+            (flags)
+            (elg
+              (a A-MPI)
+              (b B-MPI)))
+     Note, that this function currently does not know of any padding
+     methods and the caller must do any un-padding on his own.
+     The function returns 0 on success or an error code.  The variable
+     at the address of R_PLAIN will be set to NULL on error or receive
+     the decrypted value on success.  The format of R_PLAIN is a simple
+     S-expression part (i.e. not a valid one) with just one MPI if
+     there was no `flags' element in DATA; if at least an empty `flags'
+     is passed in DATA, the format is:
+          (value PLAINTEXT)
+   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.  Libgcrypt supports digital signatures using 2
+functions, similar to the encryption functions:
+ -- Function: gcry_error_t gcry_pk_sign (gcry_sexp_t *R_SIG,
+          gcry_sexp_t DATA, gcry_sexp_t SKEY)
+     This function creates a digital signature for DATA using the
+     private key SKEY and place it into the variable at the address of
+     R_SIG.  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 Libgcrypt handle padding:
+           (data
+            (flags pkcs1)
+            (hash HASH-ALGO BLOCK))
+     This example requests to sign the data in BLOCK after applying
+     PKCS#1 block type 1 style padding.  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 Libgcrypt.  Most likely, this
+     will be "sha1", "rmd160" or "md5".  It is obvious that the length
+     of BLOCK must match the size of that message digests; the function
+     checks that this and other constraints are valid.
+     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:
+          (data
+            (flags raw)
+            (value MPI))
+     Here, the data to be signed is directly given as an MPI.
+     The signature is returned as a newly allocated S-expression in
+     R_SIG using this format for RSA:
+          (sig-val
+            (rsa
+              (s S-MPI)))
+     Where S-MPI is the result of the RSA sign operation.  For DSA the
+     S-expression returned is:
+          (sig-val
+            (dsa
+              (r R-MPI)
+              (s S-MPI)))
+     Where R-MPI and 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".
+The operation most commonly used is definitely the verification of a
+signature.  Libgcrypt provides this function:
+ -- Function: gcry_error_t gcry_pk_verify (gcry_sexp_t SIG,
+          gcry_sexp_t DATA, gcry_sexp_t PKEY)
+     This is used to check whether the signature SIG matches the DATA.
+     The public key PKEY must be provided to perform this verification.
+     This function is similar in its parameters to `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 `gcry_pk_sign', is passed to the function in SIG.
+     The result is 0 for success (i.e. the data matches the signature),
+     or an error code where the most relevant code is
+     `GCRYERR_BAD_SIGNATURE' to indicate that the signature does not
+     match the provided data.
+File: gcrypt.info,  Node: General public-key related Functions,  Prev: Cryptographic Functions,  Up: Public Key cryptography (I)
+7.5 General public-key related Functions
+========================================
+A couple of utility functions are available to retrieve the length of
+the key, map algorithm identifiers and perform sanity checks:
+ -- Function: const char * gcry_pk_algo_name (int ALGO)
+     Map the public key algorithm id ALGO to a string representation of
+     the algorithm name.  For unknown algorithms this functions returns
+     an empty string.
+ -- Function: int gcry_pk_map_name (const char *NAME)
+     Map the algorithm NAME to a public key algorithm Id.  Returns 0 if
+     the algorithm name is not known.
+ -- Function: int gcry_pk_test_algo (int ALGO)
+     Return 0 if the public key algorithm ALGO is available for use.
+     Note, that this is implemented as a macro.
+ -- Function: unsigned int gcry_pk_get_nbits (gcry_sexp_t KEY)
+     Return what is commonly referred as the key length for the given
+     public or private in KEY.
+ -- Function: unsigned char * gcry_pk_get_keygrip (gcry_sexp_t KEY,
+          unsigned char *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.  ARRAY must either provide space for 20 bytes or
+     `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 ARRAY is returned.  `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 KEY.
+ -- Function: gcry_error_t gcry_pk_testkey (gcry_sexp_t KEY)
+     Return zero if the private key KEY is `sane', an error code
+     otherwise.  Note, that it is not possible to chek the `saneness'
+     of a public key.
+ -- Function: int gcry_pk_algo_info (int ALGO, int WHAT, void *BUFFER,
+          size_t *NBYTES)
+     Depending on the value of WHAT return various information about
+     the public key algorithm with the id ALGO.  Note, that the
+     function returns `-1' on error and the actual error code must be
+     retrieved using the function `gcry_errno'.  The currently defined
+     values for WHAT are:
+    `GCRYCTL_TEST_ALGO:'
+          Return 0 when the specified algorithm is available for use.
+          BUFFER must be `NULL', NBYTES may be passed as `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:
+         `GCRY_PK_USAGE_SIGN'
+               Algorithm is usable for signing.
+         `GCRY_PK_USAGE_ENCR'
+               Algorithm is usable for encryption.
+    `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.
+    `GCRYCTL_GET_ALGO_NPKEY'
+          Return the number of elements the public key for algorithm
+          ALGO consist of.  Return 0 for an unknown algorithm.
+    `GCRYCTL_GET_ALGO_NSKEY'
+          Return the number of elements the private key for algorithm
+          ALGO consist of.  Note that this value is always larger than
+          that of the public key.  Return 0 for an unknown algorithm.
+    `GCRYCTL_GET_ALGO_NSIGN'
+          Return the number of elements a signature created with the
+          algorithm ALGO consists of.  Return 0 for an unknown
+          algorithm or for an algorithm not capable of creating
+          signatures.
+    `GCRYCTL_GET_ALGO_NENC'
+          Return the number of elements a encrypted message created
+          with the algorithm ALGO consists of.  Return 0 for an unknown
+          algorithm or for an algorithm not capable of encryption.
+     Please note that parameters not required should be passed as
+     `NULL'.
+ -- Function: gcry_error_t gcry_pk_ctl (int CMD, void *BUFFER,
+          size_t BUFLEN)
+     This is a general purpose function to perform certain control
+     operations.  CMD controls what is to be done. The return value is
+     0 for success or an error code.  Currently supported values for
+     CMD are:
+    `GCRYCTL_DISABLE_ALGO'
+          Disable the algorithm given as an algorithm id in BUFFER.
+          BUFFER must point to an `int' variable with the algorithm id
+          and BUFLEN must have the value `sizeof (int)'.
+Libgcrypt also provides a function for generating public key pairs:
+ -- Function: gcry_error_t gcry_pk_genkey (gcry_sexp_t *R_KEY,
+          gcry_sexp_t PARMS)
+     This function create a new public key pair using information given
+     in the S-expression PARMS and stores the private and the public key
+     in one new S-expression at the address given by R_KEY.  In case of
+     an error, R_KEY is set to `NULL'.  The return code is 0 for
+     success or an error code otherwise.
+     Here is an example for PARMS for creating a 1024 bit RSA key:
+          (genkey
+            (rsa
+              (nbits 4:1024)))
+     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:
+    `nbits'
+          This is always required to specify the length of the key.
+          The argument is a string with a number in C-notation.
+    `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:
+         `0'
+               Use a secure and fast value.  This is currently the
+               number 41.
+         `1'
+               Use a secure value as required by some specification.
+               This is currently the number 65537.
+         `2'
+               Reserved
+          If this parameter is not used, Libgcrypt uses for historic
+          reasons 65537.
+     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.
+     As an example, here is what the ElGamal key generation returns:
+          (key-data
+            (public-key
+              (elg
+                (p P-MPI)
+                (g G-MPI)
+                (y Y-MPI)))
+            (private-key
+              (elg
+                (p P-MPI)
+                (g G-MPI)
+                (y Y-MPI)
+                (x X-MPI)))
+            (misc-key-info
+              (pm1-factors N1 N2 ... NN)))
+     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. N1 N2 ... NN is a
+     list of prime numbers used to composite P-MPI; this is in general
+     not a very useful information.
+File: gcrypt.info,  Node: Public Key cryptography (II),  Next: Random Numbers,  Prev: Public Key cryptography (I),  Up: Top
+8 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.
+File: gcrypt.info,  Node: Available asymmetric algorithms,  Next: Working with sets of data,  Up: Public Key cryptography (II)
+8.1 Available asymmetric algorithms
+===================================
+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.
+ -- Data type: gcry_ac_id_t
+     The following constants are defined for this type:
+    `GCRY_AC_RSA'
+          Riven-Shamir-Adleman
+    `GCRY_AC_DSA'
+          Digital Signature Algorithm
+    `GCRY_AC_ELG'
+          ElGamal
+    `GCRY_AC_ELG_E'
+          ElGamal, encryption only.
+File: gcrypt.info,  Node: Working with sets of data,  Next: Working with handles,  Prev: Available asymmetric algorithms,  Up: Public Key cryptography (II)
+8.2 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.
+ -- Data type: gcry_ac_data_t
+     A data set, that is simply a list of named MPI values.
+   The following flags are supported:
+`GCRY_AC_FLAG_DEALLOC'
+     Used for storing data in a data set.  If given, the data will be
+     released by the library.
+`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.
+ -- Function: gcry_error_t gcry_ac_data_new (gcry_ac_data_t *DATA)
+     Creates a new, empty data set and stores it in DATA.
+ -- Function: void gcry_ac_data_destroy (gcry_ac_data_t DATA)
+     Destroys the data set DATA.
+ -- Function: gcry_error_t gcry_ac_data_set (gcry_ac_data_t DATA,
+          unsigned int FLAGS, char *NAME, gcry_mpi_t MPI)
+     Add the value MPI to DATA with the label NAME.  If FLAGS contains
+     GCRY_AC_FLAG_DATA_COPY, the data set will contain copies of NAME
+     and MPI.  If 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.
+ -- Function: gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *DATA_CP,
+          gcry_ac_data_t DATA)
+     Create a copy of the data set DATA and store it in DATA_CP.
+ -- Function: unsigned int gcry_ac_data_length (gcry_ac_data_t DATA)
+     Returns the number of named MPI values inside of the data set DATA.
+ -- Function: gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t DATA,
+          unsigned int FLAGS, char *NAME, gcry_mpi_t *MPI)
+     Store the value labelled with NAME found in DATA in MPI.  If FLAGS
+     contains GCRY_AC_FLAG_COPY, store a copy of the MPI value
+     contained in the data set.  MPI may be NULL.
+ -- Function: gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t DATA,
+          unsigned int flags, unsigned int INDEX, const char **NAME,
+          gcry_mpi_t *MPI)
+     Stores in NAME and MPI the named MPI value contained in the data
+     set DATA with the index IDX.  If FLAGS contains GCRY_AC_FLAG_COPY,
+     store copies of the values contained in the data set. NAME or MPI
+     may be NULL.
+ -- Function: void gcry_ac_data_clear (gcry_ac_data_t DATA)
+     Destroys any values contained in the data set DATA.
+File: gcrypt.info,  Node: Working with handles,  Next: Working with keys,  Prev: Working with sets of data,  Up: Public Key cryptography (II)
+8.3 Working with handles
+========================
+In order to use an algorithm, an according handle must be created.
+This is done using the following function:
+ -- Function: gcry_error_t gcry_ac_open (gcry_ac_handle_t *HANDLE, int
+          ALGORITHM, int FLAGS)
+     Creates a new handle for the algorithm ALGORITHM and stores it in
+     HANDLE.  FLAGS is not used yet.
+     ALGORITHM must be a valid algorithm ID, see *Note Available
+     algorithms::, for a list of supported algorithms and the according
+     constants.  Besides using the listed constants directly, the
+     functions `gcry_ac_name_to_id' may be used to convert the textual
+     name of an algorithm into the according numeric ID.
+ -- Function: void gcry_ac_close (gcry_ac_handle_t HANDLE)
+     Destroys the handle HANDLE.
+File: gcrypt.info,  Node: Working with keys,  Next: Using cryptographic functions,  Prev: Working with handles,  Up: Public Key cryptography (II)
+8.4 Working with keys
+=====================
+ -- Data type: gcry_ac_key_type_t
+     Defined constants:
+    `GCRY_AC_KEY_TYPE_SECRET'
+          Specifies a secret key.
+    `GCRY_AC_KEY_TYPE_PUBLIC'
+          Specifies a public key.
+ -- Data type: gcry_ac_key_t
+     This type represents a single `key', either a secret one or a
+     public one.
+ -- Data type: gcry_ac_key_pair_t
+     This type represents a `key pair' containing a secret and a public
+     key.
+   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.
+ -- Function: gcry_error_t gcry_ac_key_init (gcry_ac_key_t *KEY,
+          gcry_ac_handle_t HANDLE, gcry_ac_key_type_t TYPE,
+          gcry_ac_data_t DATA)
+     Creates a new key of type TYPE, consisting of the MPI values
+     contained in the data set DATA and stores it in KEY.
+ -- Function: gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t
+          HANDLE, unsigned int NBITS, void *KEY_SPEC,
+          gcry_ac_key_pair_t *KEY_PAIR, gcry_mpi_t **MISC_DATA)
+     Generates a new key pair via the handle HANDLE of NBITS bits and
+     stores it in KEY_PAIR.
+     In case non-standard settings are wanted, a pointer to a structure
+     of type `gcry_ac_key_spec_<algorithm>_t', matching the selected
+     algorithm, can be given as KEY_SPEC.  MISC_DATA is not used yet.
+     Such a structure does only exist for RSA.  A descriptions of the
+     members of the supported structures follows.
+    `gcry_ac_key_spec_rsa_t'
+         `gcry_mpi_t e'
+               Generate the key pair using a special `e'.  The value of
+               `e' has the following meanings:
+              `= 0'
+                    Let Libgcrypt device what exponent should be used.
+              `= 1'
+                    Request the use of a "secure" exponent; this is
+                    required by some specification to be 65537.
+              `> 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.
+     Example code:
+          {
+            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);
+          }
+ -- Function: gcry_ac_key_t gcry_ac_key_pair_extract
+          (gcry_ac_key_pair_t KEY_PAIR, gcry_ac_key_type_t WHICH)
+     Returns the key of type WHICH out of the key pair KEY_PAIR.
+ -- Function: void gcry_ac_key_destroy (gcry_ac_key_t KEY)
+     Destroys the key KEY.
+ -- Function: void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t
+          KEY_PAIR)
+     Destroys the key pair KEY_PAIR.
+ -- Function: gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t KEY)
+     Returns the data set contained in the key KEY.
+ -- Function: gcry_error_t gcry_ac_key_test (gcry_ac_handle_t HANDLE,
+          gcry_ac_key_t KEY)
+     Verifies that the private key KEY is sane via HANDLE.
+ -- Function: gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t
+          HANDLE, gcry_ac_key_t KEY, unsigned int *NBITS)
+     Stores the number of bits of the key KEY in NBITS via HANDLE.
+ -- Function: gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t
+          HANDLE, gcry_ac_key_t KEY, unsigned char *KEY_GRIP)
+     Writes the 20 byte long key grip of the key KEY to KEY_GRIP via
+     HANDLE.
+File: gcrypt.info,  Node: Using cryptographic functions,  Next: Handle-independent functions,  Prev: Working with keys,  Up: Public Key cryptography (II)
+8.5 Using cryptographic functions
+=================================
+The following flags might be relevant:
+`GCRY_AC_FLAG_NO_BLINDING'
+     Disable any blinding, which might be supported by the chosen
+     algorithm; blinding is the default.
+ -- Function: gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t
+          HANDLE, unsigned int FLAGS, gcry_ac_key_t KEY, gcry_mpi_t
+          DATA_PLAIN, gcry_ac_data_t **DATA_ENCRYPTED)
+     Encrypts the plain text MPI value DATA_PLAIN with the key public
+     KEY under the control of the flags FLAGS and stores the resulting
+     data set into DATA_ENCRYPTED.
+ -- Function: gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t
+          HANDLE, unsigned int FLAGS, gcry_ac_key_t KEY, gcry_mpi_t
+          *DATA_PLAIN, gcry_ac_data_t DATA_ENCRYPTED)
+     Decrypts the encrypted data contained in the data set
+     DATA_ENCRYPTED with the secret key KEY under the control of the
+     flags FLAGS and stores the resulting plain text MPI value in
+     DATA_PLAIN.
+ -- Function: gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t HANDLE,
+          gcry_ac_key_t KEY, gcry_mpi_t DATA, gcry_ac_data_t
+          *DATA_SIGNATURE)
+     Signs the data contained in DATA with the secret key KEY and
+     stores the resulting signature in the data set DATA_SIGNATURE.
+ -- Function: gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t
+          HANDLE, gcry_ac_key_t KEY, gcry_mpi_t DATA, gcry_ac_data_t
+          DATA_SIGNATURE)
+     Verifies that the signature contained in the data set
+     DATA_SIGNATURE is indeed the result of signing the data contained
+     in DATA with the secret key belonging to the public key KEY.
+File: gcrypt.info,  Node: Handle-independent functions,  Prev: Using cryptographic functions,  Up: Public Key cryptography (II)
+8.6 Handle-independent functions
+================================
+ -- Function: gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t ALGORITHM,
+          const char **NAME)
+     Stores the textual representation of the algorithm whose id is
+     given in ALGORITHM in NAME.
+ -- Function: gcry_error_t gcry_ac_name_to_id (const char *NAME,
+          gcry_ac_id_t *ALGORITHM)
+     Stores the numeric ID of the algorithm whose textual
+     representation is contained in NAME in ALGORITHM.
+File: gcrypt.info,  Node: Random Numbers,  Next: S-expressions,  Prev: Public Key cryptography (II),  Up: Top
+9 Random Numbers
+****************
+* Menu:
+* Quality of random numbers::   Libgcrypt uses different quality levels.
+* Retrieving random numbers::   How to retrieve random numbers.
+File: gcrypt.info,  Node: Quality of random numbers,  Next: Retrieving random numbers,  Up: Random Numbers
+9.1 Quality of random numbers
+=============================
+Libgcypt offers random numbers of different quality levels:
+ -- Data type: enum gcry_random_level
+     The constants for the random quality levels are of this type.
+`GCRY_WEAK_RANDOM'
+     This should not anymore be used.  It has recently been changed to
+     an alias of GCRY_STRONG_RANDOM.  Use `gcry_create_nonce' instead.
+`GCRY_STRONG_RANDOM'
+     Use this level for e.g. session keys and similar purposes.
+`GCRY_VERY_STRONG_RANDOM'
+     Use this level for e.g. key material.
+File: gcrypt.info,  Node: Retrieving random numbers,  Prev: Quality of random numbers,  Up: Random Numbers
+9.2 Retrieving random numbers
+=============================
+ -- Function: void gcry_randomize (unsigned char *BUFFER, size_t
+          LENGTH, enum gcry_random_level LEVEL)
+     Fill BUFFER with LENGTH random bytes using a random quality as
+     defined by LEVEL.
+ -- Function: void * gcry_random_bytes (size_t NBYTES, enum
+          gcry_random_level LEVEL)
+     Allocate a memory block consisting of NBYTES fresh random bytes
+     using a random quality as defined by LEVEL.
+ -- Function: void * gcry_random_bytes_secure (size_t NBYTES, enum
+          gcry_random_level LEVEL)
+     Allocate a memory block consisting of NBYTES fresh random bytes
+     using a random quality as defined by LEVEL.  This function differs
+     from `gcry_random_bytes' in that the returned buffer is allocated
+     in a "secure" area of the memory.
+ -- Function: void gcry_create_nonce (void *BUFFER, size_t LENGTH)
+     Fill BUFFER with 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.
+File: gcrypt.info,  Node: S-expressions,  Next: MPI library,  Prev: Random Numbers,  Up: Top
+10 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 Libgcrypt provides functions
+to parse and construct them.  For detailed information, see `Ron
+Rivest, code and description of S-expressions,
+`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.
+File: gcrypt.info,  Node: Data types for S-expressions,  Next: Working with S-expressions,  Up: S-expressions
+10.1 Data types for S-expressions
+=================================
+ -- Data type: gcry_sexp_t
+     The `gcry_sexp_t' type describes an object with the Libgcrypt
+     internal representation of an S-expression.
+File: gcrypt.info,  Node: Working with S-expressions,  Prev: Data types for S-expressions,  Up: S-expressions
+10.2 Working with S-expressions
+===============================
+There are several functions to create an 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:
+ -- Function: gcry_error_t gcry_sexp_new (gcry_sexp_t *R_SEXP,
+          const void *BUFFER, size_t LENGTH, int AUTODETECT)
+     This is the generic function to create an new S-expression object
+     from its external representation in BUFFER of LENGTH bytes.  On
+     success the result is stored at the address given by R_SEXP.  With
+     AUTODETECT set to 0, the data in BUFFER is expected to be in
+     canonized format, with AUTODETECT set to 1 the parses any of the
+     defined external formats.  If BUFFER does not hold a valid
+     S-expression an error code is returned and R_SEXP set to `NULL'.
+     Note, that the caller is responsible for releasing the newly
+     allocated S-expression using `gcry_sexp_release'.
+ -- Function: gcry_error_t gcry_sexp_create (gcry_sexp_t *R_SEXP,
+          void *BUFFER, size_t LENGTH, int AUTODETECT,
+          void (*FREEFNC)(void*))
+     This function is identical to `gcry_sexp_new' but has an extra
+     argument FREEFNC, which, when not set to `NULL', is expected to be
+     a function to release the BUFFER; most likely the standard `free'
+     function is used for this argument.  This has the effect of
+     transferring the ownership of BUFFER to the created object in
+     R_SEXP.  The advantage of using this function is that Libgcrypt
+     might decide to directly use the provided buffer and thus avoid
+     extra copying.
+ -- Function: gcry_error_t gcry_sexp_sscan (gcry_sexp_t *R_SEXP,
+          size_t *ERROFF, const char *BUFFER, size_t LENGTH)
+     This is another variant of the above functions.  It behaves nearly
+     identical but provides an ERROFF argument which will receive the
+     offset into the buffer where the parsing stopped on error.
+ -- Function: gcry_error_t gcry_sexp_build (gcry_sexp_t *R_SEXP,
+          size_t *ERROFF, const char *FORMAT, ...)
+     This function creates an internal S-expression from the string
+     template FORMAT and stores it at the address of R_SEXP. If there
+     is a parsing error, the function returns an appropriate error code
+     and stores the offset into FORMAT where the parsing stopped in
+     ERROFF.  The function supports a couple of printf-like formatting
+     characters and expects arguments for some of these escape
+     sequences right after FORMAT.  The following format characters are
+     defined:
+    `%m'
+          The next argument is expected to be of type `gcry_mpi_t' and
+          a copy of its value is inserted into the resulting
+          S-expression.
+    `%s'
+          The next argument is expected to be of type `char *' and that
+          string is inserted into the resulting S-expression.
+    `%d'
+          The next argument is expected to be of type `int' and its
+          value ist inserted into the resulting S-expression.
+    `%b'
+          The next argument is expected to be of type `int' directly
+          followed by an argument of type `char *'.  This represents a
+          buffer of given length to be inserted into the resulting
+          regular expression.
+     No other format characters are defined and would return an error.
+     Note, that the format character `%%' does not exists, because a
+     percent sign is not a valid character in an S-expression.
+ -- Function: void gcry_sexp_release (gcry_sexp_t SEXP)
+     Release the S-expression object SEXP.
+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.
+ -- Function: size_t gcry_sexp_sprint (gcry_sexp_t SEXP, int MODE,
+          void *BUFFER, size_t MAXLENGTH)
+     Copies the S-expression object SEXP into BUFFER using the format
+     specified in MODE.  MAXLENGTH must be set to the allocated length
+     of BUFFER.  The function returns the actual length of valid bytes
+     put into BUFFER or 0 if the provided buffer is too short.  Passing
+     `NULL' for BUFFER returns the required length for BUFFER.  For
+     convenience reasons an extra byte with value 0 is appended to the
+     buffer.
+     The following formats are supported:
+    `GCRYSEXP_FMT_DEFAULT'
+          Returns a convenient external S-expression representation.
+    `GCRYSEXP_FMT_CANON'
+          Return the S-expression in canonical format.
+    `GCRYSEXP_FMT_BASE64'
+          Not currently supported.
+    `GCRYSEXP_FMT_ADVANCED'
+          Returns the S-expression in advanced format.
+ -- Function: void gcry_sexp_dump (gcry_sexp_t SEXP)
+     Dumps SEXP in a format suitable for debugging to Libgcrypt's
+     logging stream.
+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"
+ -- Function: size_t gcry_sexp_canon_len (const unsigned char *BUFFER,
+          size_t LENGTH, size_t *ERROFF, int *ERRCODE)
+     Scan the canonical encoded 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 LENGTH is not 0, the
+     maximum length to scan is given; this can be used for syntax
+     checks of data passed from outside.  ERRCODE and ERROFF may both be
+     passed as `NULL'.
+There are a couple of functions to parse S-expressions and retrieve
+elements:
+ -- Function: gcry_sexp_t gcry_sexp_find_token (const gcry_sexp_t LIST,
+          const char *TOKEN, size_t TOKLEN)
+     Scan the S-expression for a sublist with a type (the car of the
+     list) matching the string TOKEN.  If 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
+     `NULL' when not found.
+ -- Function: int gcry_sexp_length (const gcry_sexp_t LIST)
+     Return the length of the LIST.  For a valid S-expression this
+     should be at least 1.
+ -- Function: gcry_sexp_t gcry_sexp_nth (const gcry_sexp_t LIST,
+          int NUMBER)
+     Create and return a new S-expression from the element with index
+     NUMBER in LIST.  Note that the first element has the index 0.  If
+     there is no such element, `NULL' is returned.
+ -- Function: gcry_sexp_t gcry_sexp_car (const gcry_sexp_t LIST)
+     Create and return a new S-expression from the first element in
+     LIST; this called the "type" and should always exist and be a
+     string. `NULL' is returned in case of a problem.
+ -- Function: gcry_sexp_t gcry_sexp_cdr (const gcry_sexp_t 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 `NULL' on error.
+ -- Function: const char * gcry_sexp_nth_data (const gcry_sexp_t LIST,
+          int NUMBER, size_t *DATALEN)
+     This function is used to get data from a LIST.  A pointer to the
+     actual data with index NUMBER is returned and the length of this
+     data will be stored to DATALEN.  If there is no data at the given
+     index or the index represents another list, `NULL' is returned.
+     *Take care:* The returned pointer is valid as long as LIST is not
+     modified or released.
+     Here is an example on how to extract and print the surname (Meier)
+     from the S-expression `(Name Otto Meier (address Burgplatz 3))':
+          size_t len;
+          const char *name;
+          name = gcry_sexp_nth_data (list, 2, &len);
+          printf ("my name is %.*s\n", (int)len, name);
+ -- Function: gcry_mpi_t gcry_sexp_nth_mpi (gcry_sexp_t LIST,
+          int NUMBER, int MPIFMT)
+     This function is used to get and convert data from a LIST. This
+     data is assumed to be an MPI stored in the format described by
+     MPIFMT and returned as a standard Libgcrypt MPI.  The caller must
+     release this returned value using `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, `NULL' is returned.
+File: gcrypt.info,  Node: MPI library,  Next: Utilities,  Prev: S-expressions,  Up: Top
+11 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.
+   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 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.
+In the context of Libgcrypt and in most other applications, these large
+numbers are called MPIs (multi-precision-integers).
+File: gcrypt.info,  Node: Data types,  Next: Basic functions,  Up: MPI library
+11.1 Data types
+===============
+ -- Data type: gcry_mpi_t
+     The `gcry_mpi_t' type represents an object to hold an MPI.
+File: gcrypt.info,  Node: Basic functions,  Next: MPI formats,  Prev: Data types,  Up: MPI library
+11.2 Basic functions
+====================
+To work with MPIs, storage must be allocated and released for the
+numbers.  This can be done with one of these functions:
+ -- Function: gcry_mpi_t gcry_mpi_new (unsigned int NBITS)
+     Allocate a new MPI object, initialize it to 0 and initially
+     allocate enough memory for a number of at least NBITS.  This
+     pre-allocation is only a small performance issue and not actually
+     necessary because Libgcrypt automatically re-allocates the
+     required memory.
+ -- Function: gcry_mpi_t gcry_mpi_snew (unsigned int NBITS)
+     This is identical to `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.
+ -- Function: gcry_mpi_t gcry_mpi_copy (const gcry_mpi_t A)
+     Create a new MPI as the exact copy of A.
+ -- Function: void gcry_mpi_release (gcry_mpi_t A)
+     Release the MPI A and free all associated resources.  Passing
+     `NULL' is allowed and ignored.  When a MPI stored in the "secure
+     memory" is released, that memory gets wiped out immediately.
+The simplest operations are used to assign a new value to an MPI:
+ -- Function: gcry_mpi_t gcry_mpi_set (gcry_mpi_t W, const gcry_mpi_t U)
+     Assign the value of U to W and return W.  If `NULL' is passed for
+     W, a new MPI is allocated, set to the value of U and returned.
+ -- Function: gcry_mpi_t gcry_mpi_set_ui (gcry_mpi_t W, unsigned long U)
+     Assign the value of U to W and return W.  If `NULL' is passed for
+     W, a new MPI is allocated, set to the value of U and returned.
+     This function takes an `unsigned int' as type for U and thus it is
+     only possible to set W to small values (usually up to the word
+     size of the CPU).
+ -- Function: void gcry_mpi_swap (gcry_mpi_t A, gcry_mpi_t B)
+     Swap the values of A and B.
+File: gcrypt.info,  Node: MPI formats,  Next: Calculations,  Prev: Basic functions,  Up: MPI library
+11.3 MPI formats
+================
+The following functions are used to convert between an external
+representation of an MPI and the internal one of Libgcrypt.
+ -- Function: int gcry_mpi_scan (gcry_mpi_t *R_MPI,
+          enum gcry_mpi_format FORMAT, const void *BUFFER,
+          size_t BUFLEN, size_t *NSCANNED)
+     Convert the external representation of an integer stored in BUFFER
+     with a length of BUFLEN into a newly created MPI returned which
+     will be stored at the address of R_MPI.  For certain formats the
+     length argument is not required and may be passed as `0'.  After a
+     successful operation the variable NSCANNED receives the number of
+     bytes actually scanned unless NSCANNED was given as `NULL'. FORMAT
+     describes the format of the MPI as stored in BUFFER:
+    `GCRYMPI_FMT_STD'
+          2-complement stored without a length header.
+    `GCRYMPI_FMT_PGP'
+          As used by OpenPGP (only defined as unsigned). This is
+          basically `GCRYMPI_FMT_STD' with a 2 byte big endian length
+          header.
+    `GCRYMPI_FMT_SSH'
+          As used in the Secure Shell protocol.  This is
+          `GCRYMPI_FMT_STD' with a 4 byte big endian header.
+    `GCRYMPI_FMT_HEX'
+          Stored as a C style string with each byte of the MPI encoded
+          as 2 hex digits.
+    `GCRYMPI_FMT_USG'
+          Simple unsigned integer.
+     Note, that all of the above formats store the integer in big-endian
+     format (MSB first).
+ -- Function: int gcry_mpi_print (enum gcry_mpi_format FORMAT,
+          unsigned char *BUFFER, size_t BUFLEN, size_t *NWRITTEN,
+          const gcry_mpi_t A)
+     Convert the MPI A into an external representation described by
+     FORMAT (see above) and store it in the provided BUFFER which has a
+     usable length of at least the BUFLEN bytes. If NWRITTEN is not
+     NULL, it will receive the number of bytes actually stored in
+     BUFFER after a successful operation.
+ -- Function: int gcry_mpi_aprint (enum gcry_mpi_format FORMAT,
+          unsigned char **BUFFER, size_t *NBYTES, const gcry_mpi_t A)
+     Convert the MPI A into an external representation described by
+     FORMAT (see above) and store it in a newly allocated buffer which
+     address will be stored in the variable BUFFER points to.  The
+     number of bytes stored in this buffer will be stored in the
+     variable NBYTES points to, unless NBYTES is `NULL'.
+ -- Function: void gcry_mpi_dump (const gcry_mpi_t A)
+     Dump the value of 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
+     `NULL' for A.
+File: gcrypt.info,  Node: Calculations,  Next: Comparisons,  Prev: MPI formats,  Up: MPI library
+11.4 Calculations
+=================
+Basic arithmetic operations:
+ -- Function: void gcry_mpi_add (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V)
+     W = U + V.
+ -- Function: void gcry_mpi_add_ui (gcry_mpi_t W, gcry_mpi_t U,
+          unsigned long V)
+     W = U + V.  Note, that V is an unsigned integer.
+ -- Function: void gcry_mpi_addm (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V, gcry_mpi_t M)
+     W = U + V \bmod M.
+ -- Function: void gcry_mpi_sub (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V)
+     W = U - V.
+ -- Function: void gcry_mpi_sub_ui (gcry_mpi_t W, gcry_mpi_t U,
+          unsigned long V)
+     W = U - V.  V is an unsigned integer.
+ -- Function: void gcry_mpi_subm (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V, gcry_mpi_t M)
+     W = U - V \bmod M.
+ -- Function: void gcry_mpi_mul (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V)
+     W = U * V.
+ -- Function: void gcry_mpi_mul_ui (gcry_mpi_t W, gcry_mpi_t U,
+          unsigned long V)
+     W = U * V.  V is an unsigned integer.
+ -- Function: void gcry_mpi_mulm (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V, gcry_mpi_t M)
+     W = U * V \bmod M.
+ -- Function: void gcry_mpi_mul_2exp (gcry_mpi_t W, gcry_mpi_t U,
+          unsigned long E)
+     W = U * 2^e.
+ -- Function: void gcry_mpi_div (gcry_mpi_t Q, gcry_mpi_t R,
+          gcry_mpi_t DIVIDEND, gcry_mpi_t DIVISOR, int ROUND)
+     Q = DIVIDEND / DIVISOR, R = DIVIDEND \bmod DIVISOR.  Q and R may
+     be passed as `NULL'.  ROUND should be negative or 0.
+ -- Function: void gcry_mpi_mod (gcry_mpi_t R, gcry_mpi_t DIVIDEND,
+          gcry_mpi_t DIVISOR)
+     R = DIVIDEND \bmod DIVISOR.
+ -- Function: void gcry_mpi_powm (gcry_mpi_t W, const gcry_mpi_t B,
+          const gcry_mpi_t E, const gcry_mpi_t M)
+     W = B^e \bmod M.
+ -- Function: int gcry_mpi_gcd (gcry_mpi_t G, gcry_mpi_t A,
+          gcry_mpi_t B)
+     Set G to the greatest common divisor of A and B.  Return true if
+     the G is 1.
+ -- Function: int gcry_mpi_invm (gcry_mpi_t X, gcry_mpi_t A,
+          gcry_mpi_t M)
+     Set X to the multiplicative inverse of A \bmod M.  Return true if
+     the inverse exists.
+File: gcrypt.info,  Node: Comparisons,  Next: Bit manipulations,  Prev: Calculations,  Up: MPI library
+11.5 Comparisons
+================
+The next 2 functions are used to compare MPIs:
+ -- Function: int gcry_mpi_cmp (const gcry_mpi_t U, const gcry_mpi_t V)
+     Compare the big integer number U and V returning 0 for equality, a
+     positive value for U > V and a negative for U < V.
+ -- Function: int gcry_mpi_cmp_ui (const gcry_mpi_t U, unsigned long V)
+     Compare the big integer number U with the unsigned integer V
+     returning 0 for equality, a positive value for U > V and a
+     negative for U < V.
+File: gcrypt.info,  Node: Bit manipulations,  Next: Miscellaneous,  Prev: Comparisons,  Up: MPI library
+11.6 Bit manipulations
+======================
+There are a couple of functions to get information on arbitrary bits in
+an MPI and to set or clear them:
+ -- Function: unsigned int gcry_mpi_get_nbits (gcry_mpi_t A)
+     Return the number of bits required to represent A.
+ -- Function: int gcry_mpi_test_bit (gcry_mpi_t A, unsigned int N)
+     Return true if bit number N (counting from 0) is set in A.
+ -- Function: void gcry_mpi_set_bit (gcry_mpi_t A, unsigned int N)
+     Set bit number N in A.
+ -- Function: void gcry_mpi_clear_bit (gcry_mpi_t A, unsigned int N)
+     Clear bit number N in A.
+ -- Function: void gcry_mpi_set_highbit (gcry_mpi_t A, unsigned int N)
+     Set bit number N in A and clear all bits greater than N.
+ -- Function: void gcry_mpi_clear_highbit (gcry_mpi_t A, unsigned int N)
+     Clear bit number N in A and all bits greater than N.
+ -- Function: void gcry_mpi_rshift (gcry_mpi_t X, gcry_mpi_t A,
+          unsigned int N)
+     Shift the value of A by N bits to the right and store the result
+     in X.
+File: gcrypt.info,  Node: Miscellaneous,  Prev: Bit manipulations,  Up: MPI library
+11.7 Miscellanous
+=================
+ -- Function: gcry_mpi_t gcry_mpi_set_opaque (gcry_mpi_t A, void *P,
+          unsigned int NBITS)
+     Store NBITS of the value P points to in A and mark 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 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.
+ -- Function: void * gcry_mpi_get_opaque (gcry_mpi_t A,
+          unsigned int *NBITS)
+     Return a pointer to an opaque value stored in A and return its
+     size in NBITS.  Note, that the returned pointer is still owned by
+     A and that the function should never be used for an non-opaque MPI.
+ -- Function: void gcry_mpi_set_flag (gcry_mpi_t A,
+          enum gcry_mpi_flag FLAG)
+     Set the FLAG for the MPI A.  Currently only the flag
+     `GCRYMPI_FLAG_SECURE' is allowed to convert A into an MPI stored
+     in "secure memory".
+ -- Function: void gcry_mpi_clear_flag (gcry_mpi_t A,
+          enum gcry_mpi_flag FLAG)
+     Clear FLAG for the big integer A.  Note, that this function is
+     currently useless as no flags are allowed.
+ -- Function: int gcry_mpi_get_flag (gcry_mpi_t A,
+          enum gcry_mpi_flag FLAG)
+     Return true when the FLAG is set for A.
+ -- Function: void gcry_mpi_randomize (gcry_mpi_t W,
+          unsigned int NBITS, enum gcry_random_level LEVEL)
+     Set the big integer W to a random value of NBITS, using random
+     data quality of level LEVEL.  In case NBITS is not a multiple of a
+     byte, NBITS is rounded up to the next byte boundary.
+File: gcrypt.info,  Node: Utilities,  Next: Library Copying,  Prev: MPI library,  Up: Top
+12 Utilities
+************
+* Menu:
+* Memory allocation::           Functions related with memory allocation.
+File: gcrypt.info,  Node: Memory allocation,  Up: Utilities
+12.1 Memory allocation
+======================
+ -- Function: void *gcry_malloc (size_t N)
+     This function tries to allocate N bytes of memory.  On success it
+     returns a pointer to the memory area, in an out-of-core condition,
+     it returns NULL.
+ -- Function: void *gcry_malloc_secure (size_t N)
+     Like `gcry_malloc', but uses secure memory.
+ -- Function: void *gcry_calloc (size_t N)
+     This function tries to allocate 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.
+ -- Function: void *gcry_calloc_secure (size_t N)
+     Like `gcry_calloc', but uses secure memory.
+ -- Function: void *gcry_realloc (void *P, size_t N)
+     This function tries to resize the memory area pointed to by P to 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 P is secure memory or not, gcry_realloc
+     tries to use secure memory as well.
+ -- Function: void gcry_free (void *P)
+     Release the memory area pointed to by P.
+File: gcrypt.info,  Node: Library Copying,  Next: Copying,  Prev: Utilities,  Up: Top
+Appendix A GNU LESSER GENERAL PUBLIC LICENSE
+********************************************
+                      Version 2.1, February 1999
+     Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+     [This is the first released version of the Lesser GPL.  It also counts
+     as the successor of the GNU Library Public License, version 2, hence the
+     version number 2.1.]
+A.0.1 Preamble
+--------------
+The licenses for most software are designed to take away your freedom
+to share and change it.  By contrast, the GNU General Public Licenses
+are intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.
+   This license, the Lesser General Public License, applies to some
+specially designated software--typically libraries--of the Free
+Software Foundation and other authors who decide to use it.  You can use
+it too, but we suggest you first think carefully about whether this
+license or the ordinary General Public License is the better strategy to
+use in any particular case, based on the explanations below.
+   When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of it
+in new free programs; and that you are informed that you can do these
+things.
+   To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+   For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+   We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+   To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know that
+what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+   Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+   Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and is
+quite different from the ordinary General Public License.  We use this
+license for certain libraries in order to permit linking those
+libraries into non-free programs.
+   When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+   We call this license the "Lesser" General Public License because it
+does _Less_ to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+   For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it
+becomes a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+   In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of free
+software.  For example, permission to use the GNU C Library in non-free
+programs enables many more people to use the whole GNU operating
+system, as well as its variant, the GNU/Linux operating system.
+   Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run that
+program using a modified version of the Library.
+   The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+                   GNU LESSER GENERAL PUBLIC LICENSE
+    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+  0. This License Agreement applies to any software library or other
+     program which contains a notice placed by the copyright holder or
+     other authorized party saying it may be distributed under the
+     terms of this Lesser General Public License (also called "this
+     License").  Each licensee is addressed as "you".
+     A "library" means a collection of software functions and/or data
+     prepared so as to be conveniently linked with application programs
+     (which use some of those functions and data) to form executables.
+     The "Library", below, refers to any such software library or work
+     which has been distributed under these terms.  A "work based on the
+     Library" means either the Library or any derivative work under
+     copyright law: that is to say, a work containing the Library or a
+     portion of it, either verbatim or with modifications and/or
+     translated straightforwardly into another language.  (Hereinafter,
+     translation is included without limitation in the term
+     "modification".)
+     "Source code" for a work means the preferred form of the work for
+     making modifications to it.  For a library, complete source code
+     means all the source code for all modules it contains, plus any
+     associated interface definition files, plus the scripts used to
+     control compilation and installation of the library.
+     Activities other than copying, distribution and modification are
+     not covered by this License; they are outside its scope.  The act
+     of running a program using the Library is not restricted, and
+     output from such a program is covered only if its contents
+     constitute a work based on the Library (independent of the use of
+     the Library in a tool for writing it).  Whether that is true
+     depends on what the Library does and what the program that uses
+     the Library does.
+  1. You may copy and distribute verbatim copies of the Library's
+     complete source code as you receive it, in any medium, provided
+     that you conspicuously and appropriately publish on each copy an
+     appropriate copyright notice and disclaimer of warranty; keep
+     intact all the notices that refer to this License and to the
+     absence of any warranty; and distribute a copy of this License
+     along with the Library.
+     You may charge a fee for the physical act of transferring a copy,
+     and you may at your option offer warranty protection in exchange
+     for a fee.
+  2. You may modify your copy or copies of the Library or any portion
+     of it, thus forming a work based on the Library, and copy and
+     distribute such modifications or work under the terms of Section 1
+     above, provided that you also meet all of these conditions:
+       a. The modified work must itself be a software library.
+       b. You must cause the files modified to carry prominent notices
+          stating that you changed the files and the date of any change.
+       c. You must cause the whole of the work to be licensed at no
+          charge to all third parties under the terms of this License.
+       d. If a facility in the modified Library refers to a function or
+          a table of data to be supplied by an application program that
+          uses the facility, other than as an argument passed when the
+          facility is invoked, then you must make a good faith effort
+          to ensure that, in the event an application does not supply
+          such function or table, the facility still operates, and
+          performs whatever part of its purpose remains meaningful.
+          (For example, a function in a library to compute square roots
+          has a purpose that is entirely well-defined independent of the
+          application.  Therefore, Subsection 2d requires that any
+          application-supplied function or table used by this function
+          must be optional: if the application does not supply it, the
+          square root function must still compute square roots.)
+     These requirements apply to the modified work as a whole.  If
+     identifiable sections of that work are not derived from the
+     Library, and can be reasonably considered independent and separate
+     works in themselves, then this License, and its terms, do not
+     apply to those sections when you distribute them as separate
+     works.  But when you distribute the same sections as part of a
+     whole which is a work based on the Library, the distribution of
+     the whole must be on the terms of this License, whose permissions
+     for other licensees extend to the entire whole, and thus to each
+     and every part regardless of who wrote it.
+     Thus, it is not the intent of this section to claim rights or
+     contest your rights to work written entirely by you; rather, the
+     intent is to exercise the right to control the distribution of
+     derivative or collective works based on the Library.
+     In addition, mere aggregation of another work not based on the
+     Library with the Library (or with a work based on the Library) on
+     a volume of a storage or distribution medium does not bring the
+     other work under the scope of this License.
+  3. You may opt to apply the terms of the ordinary GNU General Public
+     License instead of this License to a given copy of the Library.
+     To do this, you must alter all the notices that refer to this
+     License, so that they refer to the ordinary GNU General Public
+     License, version 2, instead of to this License.  (If a newer
+     version than version 2 of the ordinary GNU General Public License
+     has appeared, then you can specify that version instead if you
+     wish.)  Do not make any other change in these notices.
+     Once this change is made in a given copy, it is irreversible for
+     that copy, so the ordinary GNU General Public License applies to
+     all subsequent copies and derivative works made from that copy.
+     This option is useful when you wish to copy part of the code of
+     the Library into a program that is not a library.
+  4. You may copy and distribute the Library (or a portion or
+     derivative of it, under Section 2) in object code or executable
+     form under the terms of Sections 1 and 2 above provided that you
+     accompany it with the complete corresponding machine-readable
+     source code, which must be distributed under the terms of Sections
+     1 and 2 above on a medium customarily used for software
+     interchange.
+     If distribution of object code is made by offering access to copy
+     from a designated place, then offering equivalent access to copy
+     the source code from the same place satisfies the requirement to
+     distribute the source code, even though third parties are not
+     compelled to copy the source along with the object code.
+  5. A program that contains no derivative of any portion of the
+     Library, but is designed to work with the Library by being
+     compiled or linked with it, is called a "work that uses the
+     Library".  Such a work, in isolation, is not a derivative work of
+     the Library, and therefore falls outside the scope of this License.
+     However, linking a "work that uses the Library" with the Library
+     creates an executable that is a derivative of the Library (because
+     it contains portions of the Library), rather than a "work that
+     uses the library".  The executable is therefore covered by this
+     License.  Section 6 states terms for distribution of such
+     executables.
+     When a "work that uses the Library" uses material from a header
+     file that is part of the Library, the object code for the work may
+     be a derivative work of the Library even though the source code is
+     not.  Whether this is true is especially significant if the work
+     can be linked without the Library, or if the work is itself a
+     library.  The threshold for this to be true is not precisely
+     defined by law.
+     If such an object file uses only numerical parameters, data
+     structure layouts and accessors, and small macros and small inline
+     functions (ten lines or less in length), then the use of the object
+     file is unrestricted, regardless of whether it is legally a
+     derivative work.  (Executables containing this object code plus
+     portions of the Library will still fall under Section 6.)
+     Otherwise, if the work is a derivative of the Library, you may
+     distribute the object code for the work under the terms of Section
+     6.  Any executables containing that work also fall under Section 6,
+     whether or not they are linked directly with the Library itself.
+  6. As an exception to the Sections above, you may also combine or
+     link a "work that uses the Library" with the Library to produce a
+     work containing portions of the Library, and distribute that work
+     under terms of your choice, provided that the terms permit
+     modification of the work for the customer's own use and reverse
+     engineering for debugging such modifications.
+     You must give prominent notice with each copy of the work that the
+     Library is used in it and that the Library and its use are covered
+     by this License.  You must supply a copy of this License.  If the
+     work during execution displays copyright notices, you must include
+     the copyright notice for the Library among them, as well as a
+     reference directing the user to the copy of this License.  Also,
+     you must do one of these things:
+       a. Accompany the work with the complete corresponding
+          machine-readable source code for the Library including
+          whatever changes were used in the work (which must be
+          distributed under Sections 1 and 2 above); and, if the work
+          is an executable linked with the Library, with the complete
+          machine-readable "work that uses the Library", as object code
+          and/or source code, so that the user can modify the Library
+          and then relink to produce a modified executable containing
+          the modified Library.  (It is understood that the user who
+          changes the contents of definitions files in the Library will
+          not necessarily be able to recompile the application to use
+          the modified definitions.)
+       b. Use a suitable shared library mechanism for linking with the
+          Library.  A suitable mechanism is one that (1) uses at run
+          time a copy of the library already present on the user's
+          computer system, rather than copying library functions into
+          the executable, and (2) will operate properly with a modified
+          version of the library, if the user installs one, as long as
+          the modified version is interface-compatible with the version
+          that the work was made with.
+       c. Accompany the work with a written offer, valid for at least
+          three years, to give the same user the materials specified in
+          Subsection 6a, above, for a charge no more than the cost of
+          performing this distribution.
+       d. If distribution of the work is made by offering access to copy
+          from a designated place, offer equivalent access to copy the
+          above specified materials from the same place.
+       e. Verify that the user has already received a copy of these
+          materials or that you have already sent this user a copy.
+     For an executable, the required form of the "work that uses the
+     Library" must include any data and utility programs needed for
+     reproducing the executable from it.  However, as a special
+     exception, the materials to be distributed need not include
+     anything that is normally distributed (in either source or binary
+     form) with the major components (compiler, kernel, and so on) of
+     the operating system on which the executable runs, unless that
+     component itself accompanies the executable.
+     It may happen that this requirement contradicts the license
+     restrictions of other proprietary libraries that do not normally
+     accompany the operating system.  Such a contradiction means you
+     cannot use both them and the Library together in an executable
+     that you distribute.
+  7. You may place library facilities that are a work based on the
+     Library side-by-side in a single library together with other
+     library facilities not covered by this License, and distribute
+     such a combined library, provided that the separate distribution
+     of the work based on the Library and of the other library
+     facilities is otherwise permitted, and provided that you do these
+     two things:
+       a. Accompany the combined library with a copy of the same work
+          based on the Library, uncombined with any other library
+          facilities.  This must be distributed under the terms of the
+          Sections above.
+       b. Give prominent notice with the combined library of the fact
+          that part of it is a work based on the Library, and explaining
+          where to find the accompanying uncombined form of the same
+          work.
+  8. You may not copy, modify, sublicense, link with, or distribute the
+     Library except as expressly provided under this License.  Any
+     attempt otherwise to copy, modify, sublicense, link with, or
+     distribute the Library is void, and will automatically terminate
+     your rights under this License.  However, parties who have
+     received copies, or rights, from you under this License will not
+     have their licenses terminated so long as such parties remain in
+     full compliance.
+  9. You are not required to accept this License, since you have not
+     signed it.  However, nothing else grants you permission to modify
+     or distribute the Library or its derivative works.  These actions
+     are prohibited by law if you do not accept this License.
+     Therefore, by modifying or distributing the Library (or any work
+     based on the Library), you indicate your acceptance of this
+     License to do so, and all its terms and conditions for copying,
+     distributing or modifying the Library or works based on it.
+ 10. Each time you redistribute the Library (or any work based on the
+     Library), the recipient automatically receives a license from the
+     original licensor to copy, distribute, link with or modify the
+     Library subject to these terms and conditions.  You may not impose
+     any further restrictions on the recipients' exercise of the rights
+     granted herein.  You are not responsible for enforcing compliance
+     by third parties with this License.
+ 11. If, as a consequence of a court judgment or allegation of patent
+     infringement or for any other reason (not limited to patent
+     issues), conditions are imposed on you (whether by court order,
+     agreement or otherwise) that contradict the conditions of this
+     License, they do not excuse you from the conditions of this
+     License.  If you cannot distribute so as to satisfy simultaneously
+     your obligations under this License and any other pertinent
+     obligations, then as a consequence you may not distribute the
+     Library at all.  For example, if a patent license would not permit
+     royalty-free redistribution of the Library by all those who
+     receive copies directly or indirectly through you, then the only
+     way you could satisfy both it and this License would be to refrain
+     entirely from distribution of the Library.
+     If any portion of this section is held invalid or unenforceable
+     under any particular circumstance, the balance of the section is
+     intended to apply, and the section as a whole is intended to apply
+     in other circumstances.
+     It is not the purpose of this section to induce you to infringe any
+     patents or other property right claims or to contest validity of
+     any such claims; this section has the sole purpose of protecting
+     the integrity of the free software distribution system which is
+     implemented by public license practices.  Many people have made
+     generous contributions to the wide range of software distributed
+     through that system in reliance on consistent application of that
+     system; it is up to the author/donor to decide if he or she is
+     willing to distribute software through any other system and a
+     licensee cannot impose that choice.
+     This section is intended to make thoroughly clear what is believed
+     to be a consequence of the rest of this License.
+ 12. If the distribution and/or use of the Library is restricted in
+     certain countries either by patents or by copyrighted interfaces,
+     the original copyright holder who places the Library under this
+     License may add an explicit geographical distribution limitation
+     excluding those countries, so that distribution is permitted only
+     in or among countries not thus excluded.  In such case, this
+     License incorporates the limitation as if written in the body of
+     this License.
+ 13. The Free Software Foundation may publish revised and/or new
+     versions of the Lesser General Public License from time to time.
+     Such new versions will be similar in spirit to the present version,
+     but may differ in detail to address new problems or concerns.
+     Each version is given a distinguishing version number.  If the
+     Library specifies a version number of this License which applies
+     to it and "any later version", you have the option of following
+     the terms and conditions either of that version or of any later
+     version published by the Free Software Foundation.  If the Library
+     does not specify a license version number, you may choose any
+     version ever published by the Free Software Foundation.
+ 14. If you wish to incorporate parts of the Library into other free
+     programs whose distribution conditions are incompatible with these,
+     write to the author to ask for permission.  For software which is
+     copyrighted by the Free Software Foundation, write to the Free
+     Software Foundation; we sometimes make exceptions for this.  Our
+     decision will be guided by the two goals of preserving the free
+     status of all derivatives of our free software and of promoting
+     the sharing and reuse of software generally.
+                                NO WARRANTY
+ 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+     WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE
+     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+     HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT
+     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
+     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
+     QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU.  SHOULD THE
+     LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+     SERVICING, REPAIR OR CORRECTION.
+ 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+     MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
+     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+     INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
+     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+     OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY
+     OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+                      END OF TERMS AND CONDITIONS
+A.0.2 How to Apply These Terms to Your New Libraries
+----------------------------------------------------
+If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of
+the ordinary General Public License).
+   To apply these terms, attach the following notices to the library.
+It is safest to attach them to the start of each source file to most
+effectively convey the exclusion of warranty; and each file should have
+at least the "copyright" line and a pointer to where the full notice is
+found.
+     ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES.
+     Copyright (C) YEAR  NAME OF AUTHOR
+     This library is free software; you can redistribute it and/or modify it
+     under the terms of the GNU Lesser General Public License as published by
+     the Free Software Foundation; either version 2.1 of the License, or (at
+     your option) any later version.
+     This library is distributed in the hope that it will be useful, but
+     WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
+     USA.
+   Also add information on how to contact you by electronic and paper
+mail.
+   You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the library,
+if necessary.  Here is a sample; alter the names:
+     Yoyodyne, Inc., hereby disclaims all copyright interest in the library
+     `Frob' (a library for tweaking knobs) written by James Random Hacker.
+     SIGNATURE OF TY COON, 1 April 1990
+     Ty Coon, President of Vice
+   That's all there is to it!
+File: gcrypt.info,  Node: Copying,  Next: Concept Index,  Prev: Library Copying,  Up: Top
+Appendix B GNU GENERAL PUBLIC LICENSE
+*************************************
+                         Version 2, June 1991
+     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+B.0.1 Preamble
+--------------
+The licenses for most software are designed to take away your freedom
+to share and change it.  By contrast, the GNU General Public License is
+intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+   When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it in
+new free programs; and that you know you can do these things.
+   To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+   For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+   We protect your rights with two steps: (1) copyright the software,
+and (2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+   Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+   Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+   The precise terms and conditions for copying, distribution and
+modification follow.
+    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+  1. This License applies to any program or other work which contains a
+     notice placed by the copyright holder saying it may be distributed
+     under the terms of this General Public License.  The "Program",
+     below, refers to any such program or work, and a "work based on
+     the Program" means either the Program or any derivative work under
+     copyright law: that is to say, a work containing the Program or a
+     portion of it, either verbatim or with modifications and/or
+     translated into another language.  (Hereinafter, translation is
+     included without limitation in the term "modification".)  Each
+     licensee is addressed as "you".
+     Activities other than copying, distribution and modification are
+     not covered by this License; they are outside its scope.  The act
+     of running the Program is not restricted, and the output from the
+     Program is covered only if its contents constitute a work based on
+     the Program (independent of having been made by running the
+     Program).  Whether that is true depends on what the Program does.
+  2. You may copy and distribute verbatim copies of the Program's
+     source code as you receive it, in any medium, provided that you
+     conspicuously and appropriately publish on each copy an appropriate
+     copyright notice and disclaimer of warranty; keep intact all the
+     notices that refer to this License and to the absence of any
+     warranty; and give any other recipients of the Program a copy of
+     this License along with the Program.
+     You may charge a fee for the physical act of transferring a copy,
+     and you may at your option offer warranty protection in exchange
+     for a fee.
+  3. You may modify your copy or copies of the Program or any portion
+     of it, thus forming a work based on the Program, and copy and
+     distribute such modifications or work under the terms of Section 1
+     above, provided that you also meet all of these conditions:
+       a. You must cause the modified files to carry prominent notices
+          stating that you changed the files and the date of any change.
+       b. You must cause any work that you distribute or publish, that
+          in whole or in part contains or is derived from the Program
+          or any part thereof, to be licensed as a whole at no charge
+          to all third parties under the terms of this License.
+       c. If the modified program normally reads commands interactively
+          when run, you must cause it, when started running for such
+          interactive use in the most ordinary way, to print or display
+          an announcement including an appropriate copyright notice and
+          a notice that there is no warranty (or else, saying that you
+          provide a warranty) and that users may redistribute the
+          program under these conditions, and telling the user how to
+          view a copy of this License.  (Exception: if the Program
+          itself is interactive but does not normally print such an
+          announcement, your work based on the Program is not required
+          to print an announcement.)
+     These requirements apply to the modified work as a whole.  If
+     identifiable sections of that work are not derived from the
+     Program, and can be reasonably considered independent and separate
+     works in themselves, then this License, and its terms, do not
+     apply to those sections when you distribute them as separate
+     works.  But when you distribute the same sections as part of a
+     whole which is a work based on the Program, the distribution of
+     the whole must be on the terms of this License, whose permissions
+     for other licensees extend to the entire whole, and thus to each
+     and every part regardless of who wrote it.
+     Thus, it is not the intent of this section to claim rights or
+     contest your rights to work written entirely by you; rather, the
+     intent is to exercise the right to control the distribution of
+     derivative or collective works based on the Program.
+     In addition, mere aggregation of another work not based on the
+     Program with the Program (or with a work based on the Program) on
+     a volume of a storage or distribution medium does not bring the
+     other work under the scope of this License.
+  4. You may copy and distribute the Program (or a work based on it,
+     under Section 2) in object code or executable form under the terms
+     of Sections 1 and 2 above provided that you also do one of the
+     following:
+       a. Accompany it with the complete corresponding machine-readable
+          source code, which must be distributed under the terms of
+          Sections 1 and 2 above on a medium customarily used for
+          software interchange; or,
+       b. Accompany it with a written offer, valid for at least three
+          years, to give any third party, for a charge no more than your
+          cost of physically performing source distribution, a complete
+          machine-readable copy of the corresponding source code, to be
+          distributed under the terms of Sections 1 and 2 above on a
+          medium customarily used for software interchange; or,
+       c. Accompany it with the information you received as to the offer
+          to distribute corresponding source code.  (This alternative is
+          allowed only for noncommercial distribution and only if you
+          received the program in object code or executable form with
+          such an offer, in accord with Subsection b above.)
+     The source code for a work means the preferred form of the work for
+     making modifications to it.  For an executable work, complete
+     source code means all the source code for all modules it contains,
+     plus any associated interface definition files, plus the scripts
+     used to control compilation and installation of the executable.
+     However, as a special exception, the source code distributed need
+     not include anything that is normally distributed (in either
+     source or binary form) with the major components (compiler,
+     kernel, and so on) of the operating system on which the executable
+     runs, unless that component itself accompanies the executable.
+     If distribution of executable or object code is made by offering
+     access to copy from a designated place, then offering equivalent
+     access to copy the source code from the same place counts as
+     distribution of the source code, even though third parties are not
+     compelled to copy the source along with the object code.
+  5. You may not copy, modify, sublicense, or distribute the Program
+     except as expressly provided under this License.  Any attempt
+     otherwise to copy, modify, sublicense or distribute the Program is
+     void, and will automatically terminate your rights under this
+     License.  However, parties who have received copies, or rights,
+     from you under this License will not have their licenses
+     terminated so long as such parties remain in full compliance.
+  6. You are not required to accept this License, since you have not
+     signed it.  However, nothing else grants you permission to modify
+     or distribute the Program or its derivative works.  These actions
+     are prohibited by law if you do not accept this License.
+     Therefore, by modifying or distributing the Program (or any work
+     based on the Program), you indicate your acceptance of this
+     License to do so, and all its terms and conditions for copying,
+     distributing or modifying the Program or works based on it.
+  7. Each time you redistribute the Program (or any work based on the
+     Program), the recipient automatically receives a license from the
+     original licensor to copy, distribute or modify the Program
+     subject to these terms and conditions.  You may not impose any
+     further restrictions on the recipients' exercise of the rights
+     granted herein.  You are not responsible for enforcing compliance
+     by third parties to this License.
+  8. If, as a consequence of a court judgment or allegation of patent
+     infringement or for any other reason (not limited to patent
+     issues), conditions are imposed on you (whether by court order,
+     agreement or otherwise) that contradict the conditions of this
+     License, they do not excuse you from the conditions of this
+     License.  If you cannot distribute so as to satisfy simultaneously
+     your obligations under this License and any other pertinent
+     obligations, then as a consequence you may not distribute the
+     Program at all.  For example, if a patent license would not permit
+     royalty-free redistribution of the Program by all those who
+     receive copies directly or indirectly through you, then the only
+     way you could satisfy both it and this License would be to refrain
+     entirely from distribution of the Program.
+     If any portion of this section is held invalid or unenforceable
+     under any particular circumstance, the balance of the section is
+     intended to apply and the section as a whole is intended to apply
+     in other circumstances.
+     It is not the purpose of this section to induce you to infringe any
+     patents or other property right claims or to contest validity of
+     any such claims; this section has the sole purpose of protecting
+     the integrity of the free software distribution system, which is
+     implemented by public license practices.  Many people have made
+     generous contributions to the wide range of software distributed
+     through that system in reliance on consistent application of that
+     system; it is up to the author/donor to decide if he or she is
+     willing to distribute software through any other system and a
+     licensee cannot impose that choice.
+     This section is intended to make thoroughly clear what is believed
+     to be a consequence of the rest of this License.
+  9. If the distribution and/or use of the Program is restricted in
+     certain countries either by patents or by copyrighted interfaces,
+     the original copyright holder who places the Program under this
+     License may add an explicit geographical distribution limitation
+     excluding those countries, so that distribution is permitted only
+     in or among countries not thus excluded.  In such case, this
+     License incorporates the limitation as if written in the body of
+     this License.
+ 10. The Free Software Foundation may publish revised and/or new
+     versions of the General Public License from time to time.  Such
+     new versions will be similar in spirit to the present version, but
+     may differ in detail to address new problems or concerns.
+     Each version is given a distinguishing version number.  If the
+     Program specifies a version number of this License which applies
+     to it and "any later version", you have the option of following
+     the terms and conditions either of that version or of any later
+     version published by the Free Software Foundation.  If the Program
+     does not specify a version number of this License, you may choose
+     any version ever published by the Free Software Foundation.
+ 11. If you wish to incorporate parts of the Program into other free
+     programs whose distribution conditions are different, write to the
+     author to ask for permission.  For software which is copyrighted
+     by the Free Software Foundation, write to the Free Software
+     Foundation; we sometimes make exceptions for this.  Our decision
+     will be guided by the two goals of preserving the free status of
+     all derivatives of our free software and of promoting the sharing
+     and reuse of software generally.
+                                NO WARRANTY
+ 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
+     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
+     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
+     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+     SERVICING, REPAIR OR CORRECTION.
+ 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
+     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
+     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+                      END OF TERMS AND CONDITIONS
+How to Apply These Terms to Your New Programs
+=============================================
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+   To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
+     Copyright (C) 19YY  NAME OF AUTHOR
+     This program is free software; you can redistribute it and/or
+     modify it under the terms of the GNU General Public License
+     as published by the Free Software Foundation; either version 2
+     of the License, or (at your option) any later version.
+     This program is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+     GNU General Public License for more details.
+     You should have received a copy of the GNU General Public License along
+     with this program; if not, write to the Free Software Foundation, Inc.,
+     59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+   Also add information on how to contact you by electronic and paper
+mail.
+   If the program is interactive, make it output a short notice like
+this when it starts in an interactive mode:
+     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
+     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+     type `show w'.  This is free software, and you are welcome
+     to redistribute it under certain conditions; type `show c'
+     for details.
+   The hypothetical commands `show w' and `show c' should show the
+appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than `show w' and `show
+c'; they could even be mouse-clicks or menu items--whatever suits your
+program.
+   You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the program,
+if necessary.  Here is a sample; alter the names:
+     Yoyodyne, Inc., hereby disclaims all copyright
+     interest in the program `Gnomovision'
+     (which makes passes at compilers) written
+     by James Hacker.
+     SIGNATURE OF TY COON, 1 April 1989
+     Ty Coon, President of Vice
+   This General Public License does not permit incorporating your
+program into proprietary programs.  If your program is a subroutine
+library, you may consider it more useful to permit linking proprietary
+applications with the library.  If this is what you want to do, use the
+GNU Library General Public License instead of this License.
+File: gcrypt.info,  Node: Concept Index,  Next: Function and Data Index,  Prev: Copying,  Up: Top
+Concept Index
+*************
+* Menu:
+* error codes:                           Error Values.          (line 6)
+* error codes, list of <1>:              Error Codes.           (line 6)
+* error codes, list of:                  Error Sources.         (line 6)
+* error codes, printing of:              Error Strings.         (line 6)
+* error sources:                         Error Values.          (line 6)
+* error sources, printing of:            Error Strings.         (line 6)
+* error strings:                         Error Strings.         (line 6)
+* error values:                          Error Values.          (line 6)
+* error values, printing of:             Error Strings.         (line 6)
+* GPL, GNU General Public License:       Copying.               (line 6)
+* LGPL, Lesser General Public License:   Library Copying.       (line 6)
+File: gcrypt.info,  Node: Function and Data Index,  Prev: Concept Index,  Up: Top
+Function and Data Index
+***********************
+* Menu:
+* *:                                     Retrieving random numbers.
+                                                              (line  13)
+* *gcry_calloc:                          Memory allocation.   (line  15)
+* *gcry_calloc_secure:                   Memory allocation.   (line  21)
+* *gcry_malloc:                          Memory allocation.   (line   7)
+* *gcry_malloc_secure:                   Memory allocation.   (line  12)
+* *gcry_realloc:                         Memory allocation.   (line  24)
+* AM_PATH_LIBGCRYPT:                     Building sources using Automake.
+                                                              (line  13)
+* char <1>:                              Working with hash algorithms.
+                                                              (line 117)
+* char <2>:                              General cipher functions.
+                                                              (line  39)
+* char:                                  Initializing the library.
+                                                              (line  13)
+* enum:                                  Quality of random numbers.
+                                                              (line   9)
+* gcry_ac_close:                         Working with handles.
+                                                              (line  21)
+* gcry_ac_data_clear:                    Working with sets of data.
+                                                              (line  68)
+* gcry_ac_data_copy:                     Working with sets of data.
+                                                              (line  48)
+* gcry_ac_data_decrypt:                  Using cryptographic functions.
+                                                              (line  22)
+* gcry_ac_data_destroy:                  Working with sets of data.
+                                                              (line  36)
+* gcry_ac_data_encrypt:                  Using cryptographic functions.
+                                                              (line  15)
+* gcry_ac_data_get_index:                Working with sets of data.
+                                                              (line  62)
+* gcry_ac_data_get_name:                 Working with sets of data.
+                                                              (line  55)
+* gcry_ac_data_new:                      Working with sets of data.
+                                                              (line  33)
+* gcry_ac_data_set:                      Working with sets of data.
+                                                              (line  40)
+* gcry_ac_data_sign:                     Using cryptographic functions.
+                                                              (line  30)
+* gcry_ac_data_t:                        Working with sets of data.
+                                                              (line  19)
+* gcry_ac_data_verify:                   Using cryptographic functions.
+                                                              (line  36)
+* gcry_ac_id_t:                          Available asymmetric algorithms.
+                                                              (line  11)
+* gcry_ac_id_to_name:                    Handle-independent functions.
+                                                              (line   8)
+* gcry_ac_key_data_get:                  Working with keys.   (line  92)
+* gcry_ac_key_destroy:                   Working with keys.   (line  85)
+* gcry_ac_key_get_grip:                  Working with keys.   (line 104)
+* gcry_ac_key_get_nbits:                 Working with keys.   (line 100)
+* gcry_ac_key_init:                      Working with keys.   (line  30)
+* gcry_ac_key_pair_destroy:              Working with keys.   (line  89)
+* gcry_ac_key_pair_extract:              Working with keys.   (line  82)
+* gcry_ac_key_pair_generate:             Working with keys.   (line  36)
+* gcry_ac_key_pair_t:                    Working with keys.   (line  20)
+* gcry_ac_key_t:                         Working with keys.   (line  16)
+* gcry_ac_key_test:                      Working with keys.   (line  96)
+* gcry_ac_key_type_t:                    Working with keys.   (line   7)
+* gcry_ac_name_to_id:                    Handle-independent functions.
+                                                              (line  13)
+* gcry_ac_open:                          Working with handles.
+                                                              (line  11)
+* gcry_cipher_algo_info:                 General cipher functions.
+                                                              (line  12)
+* gcry_cipher_close:                     Working with cipher handles.
+                                                              (line  52)
+* gcry_cipher_ctl:                       Working with cipher handles.
+                                                              (line 152)
+* gcry_cipher_decrypt:                   Working with cipher handles.
+                                                              (line 122)
+* gcry_cipher_decrypt_t:                 Cipher modules.      (line  80)
+* gcry_cipher_encrypt:                   Working with cipher handles.
+                                                              (line 104)
+* gcry_cipher_encrypt_t:                 Cipher modules.      (line  75)
+* gcry_cipher_info:                      Working with cipher handles.
+                                                              (line 161)
+* gcry_cipher_list:                      Cipher modules.      (line 106)
+* gcry_cipher_map_name:                  General cipher functions.
+                                                              (line  45)
+* gcry_cipher_mode_from_oid:             General cipher functions.
+                                                              (line  50)
+* gcry_cipher_oid_spec_t:                Cipher modules.      (line  60)
+* gcry_cipher_open:                      Working with cipher handles.
+                                                              (line  11)
+* gcry_cipher_register:                  Cipher modules.      (line  96)
+* gcry_cipher_reset:                     Working with cipher handles.
+                                                              (line  92)
+* gcry_cipher_setctr:                    Working with cipher handles.
+                                                              (line  84)
+* gcry_cipher_setiv:                     Working with cipher handles.
+                                                              (line  76)
+* gcry_cipher_setkey:                    Working with cipher handles.
+                                                              (line  59)
+* gcry_cipher_setkey_t:                  Cipher modules.      (line  70)
+* gcry_cipher_spec_t:                    Cipher modules.      (line  12)
+* gcry_cipher_stdecrypt_t:               Cipher modules.      (line  90)
+* gcry_cipher_stencrypt_t:               Cipher modules.      (line  85)
+* gcry_cipher_sync:                      Working with cipher handles.
+                                                              (line 142)
+* gcry_cipher_unregister:                Cipher modules.      (line 101)
+* gcry_control:                          Controlling the library.
+                                                              (line   7)
+* gcry_create_nonce:                     Retrieving random numbers.
+                                                              (line  24)
+* gcry_err_code:                         Error Values.        (line  43)
+* gcry_err_code_from_errno:              Error Values.        (line  95)
+* gcry_err_code_t:                       Error Values.        (line   7)
+* gcry_err_code_to_errno:                Error Values.        (line 100)
+* gcry_err_make:                         Error Values.        (line  57)
+* gcry_err_make_from_errno:              Error Values.        (line  81)
+* gcry_err_source:                       Error Values.        (line  49)
+* gcry_err_source_t:                     Error Values.        (line  14)
+* gcry_error:                            Error Values.        (line  64)
+* gcry_error_from_errno:                 Error Values.        (line  86)
+* gcry_error_t:                          Error Values.        (line  25)
+* gcry_free:                             Memory allocation.   (line  31)
+* gcry_handler_alloc_t:                  Allocation handler.  (line  12)
+* gcry_handler_error_t:                  Error handler.       (line  20)
+* gcry_handler_free_t:                   Allocation handler.  (line  24)
+* gcry_handler_log_t:                    Logging handler.     (line   7)
+* gcry_handler_no_mem_t:                 Error handler.       (line  10)
+* gcry_handler_progress_t:               Progress handler.    (line  10)
+* gcry_handler_realloc_t:                Allocation handler.  (line  20)
+* gcry_handler_secure_check_t:           Allocation handler.  (line  16)
+* gcry_md_close:                         Working with hash algorithms.
+                                                              (line  59)
+* gcry_md_copy:                          Working with hash algorithms.
+                                                              (line  80)
+* gcry_md_enable:                        Working with hash algorithms.
+                                                              (line  43)
+* gcry_md_final:                         Working with hash algorithms.
+                                                              (line 107)
+* gcry_md_final_t:                       Hash algorithm modules.
+                                                              (line  73)
+* gcry_md_get_algo:                      Working with hash algorithms.
+                                                              (line 193)
+* gcry_md_get_asnoid:                    Working with hash algorithms.
+                                                              (line 165)
+* gcry_md_hash_buffer:                   Working with hash algorithms.
+                                                              (line 132)
+* gcry_md_init_t:                        Hash algorithm modules.
+                                                              (line  65)
+* gcry_md_is_enabled:                    Working with hash algorithms.
+                                                              (line 204)
+* gcry_md_is_secure:                     Working with hash algorithms.
+                                                              (line 199)
+* gcry_md_list:                          Hash algorithm modules.
+                                                              (line  91)
+* gcry_md_map_name:                      Working with hash algorithms.
+                                                              (line 155)
+* gcry_md_oid_spec_t:                    Hash algorithm modules.
+                                                              (line  57)
+* gcry_md_open:                          Working with hash algorithms.
+                                                              (line  11)
+* gcry_md_putc:                          Working with hash algorithms.
+                                                              (line  97)
+* gcry_md_read_t:                        Hash algorithm modules.
+                                                              (line  77)
+* gcry_md_register:                      Hash algorithm modules.
+                                                              (line  82)
+* gcry_md_reset:                         Working with hash algorithms.
+                                                              (line  68)
+* gcry_md_setkey:                        Working with hash algorithms.
+                                                              (line  52)
+* gcry_md_spec_t:                        Hash algorithm modules.
+                                                              (line  12)
+* gcry_md_start_debug:                   Working with hash algorithms.
+                                                              (line 215)
+* gcry_md_stop_debug:                    Working with hash algorithms.
+                                                              (line 223)
+* gcry_md_test_algo:                     Working with hash algorithms.
+                                                              (line 178)
+* gcry_md_unregister:                    Hash algorithm modules.
+                                                              (line  87)
+* gcry_md_write:                         Working with hash algorithms.
+                                                              (line  92)
+* gcry_md_write_t:                       Hash algorithm modules.
+                                                              (line  69)
+* gcry_module_t:                         Modules.             (line  10)
+* gcry_mpi_add:                          Calculations.        (line  10)
+* gcry_mpi_add_ui:                       Calculations.        (line  14)
+* gcry_mpi_addm:                         Calculations.        (line  18)
+* gcry_mpi_aprint:                       MPI formats.         (line  53)
+* gcry_mpi_clear_bit:                    Bit manipulations.   (line  19)
+* gcry_mpi_clear_flag:                   Miscellaneous.       (line  32)
+* gcry_mpi_clear_highbit:                Bit manipulations.   (line  25)
+* gcry_mpi_cmp:                          Comparisons.         (line   9)
+* gcry_mpi_cmp_ui:                       Comparisons.         (line  13)
+* gcry_mpi_copy:                         Basic functions.     (line  23)
+* gcry_mpi_div:                          Calculations.        (line  50)
+* gcry_mpi_dump:                         MPI formats.         (line  60)
+* gcry_mpi_gcd:                          Calculations.        (line  63)
+* gcry_mpi_get_flag:                     Miscellaneous.       (line  37)
+* gcry_mpi_get_nbits:                    Bit manipulations.   (line  10)
+* gcry_mpi_get_opaque:                   Miscellaneous.       (line  20)
+* gcry_mpi_invm:                         Calculations.        (line  68)
+* gcry_mpi_mod:                          Calculations.        (line  55)
+* gcry_mpi_mul:                          Calculations.        (line  34)
+* gcry_mpi_mul_2exp:                     Calculations.        (line  46)
+* gcry_mpi_mul_ui:                       Calculations.        (line  38)
+* gcry_mpi_mulm:                         Calculations.        (line  42)
+* gcry_mpi_new:                          Basic functions.     (line  10)
+* gcry_mpi_powm:                         Calculations.        (line  59)
+* gcry_mpi_print:                        MPI formats.         (line  45)
+* gcry_mpi_randomize:                    Miscellaneous.       (line  41)
+* gcry_mpi_release:                      Basic functions.     (line  26)
+* gcry_mpi_rshift:                       Bit manipulations.   (line  29)
+* gcry_mpi_scan:                         MPI formats.         (line  12)
+* gcry_mpi_set:                          Basic functions.     (line  33)
+* gcry_mpi_set_bit:                      Bit manipulations.   (line  16)
+* gcry_mpi_set_flag:                     Miscellaneous.       (line  26)
+* gcry_mpi_set_highbit:                  Bit manipulations.   (line  22)
+* gcry_mpi_set_opaque:                   Miscellaneous.       (line   8)
+* gcry_mpi_set_ui:                       Basic functions.     (line  37)
+* gcry_mpi_snew:                         Basic functions.     (line  17)
+* gcry_mpi_sub:                          Calculations.        (line  22)
+* gcry_mpi_sub_ui:                       Calculations.        (line  26)
+* gcry_mpi_subm:                         Calculations.        (line  30)
+* gcry_mpi_swap:                         Basic functions.     (line  44)
+* gcry_mpi_t:                            Data types.          (line   7)
+* gcry_mpi_test_bit:                     Bit manipulations.   (line  13)
+* gcry_pk_algo_info:                     General public-key related Functions.
+                                                              (line  46)
+* gcry_pk_algo_name:                     General public-key related Functions.
+                                                              (line  10)
+* gcry_pk_check_secret_key_t:            Public key modules.  (line  91)
+* gcry_pk_ctl:                           General public-key related Functions.
+                                                              (line  96)
+* gcry_pk_decrypt:                       Cryptographic Functions.
+                                                              (line  85)
+* gcry_pk_decrypt_t:                     Public key modules.  (line 101)
+* gcry_pk_encrypt:                       Cryptographic Functions.
+                                                              (line  29)
+* gcry_pk_encrypt_t:                     Public key modules.  (line  96)
+* gcry_pk_generate_t:                    Public key modules.  (line  86)
+* gcry_pk_genkey:                        General public-key related Functions.
+                                                              (line 111)
+* gcry_pk_get_keygrip:                   General public-key related Functions.
+                                                              (line  28)
+* gcry_pk_get_nbits:                     General public-key related Functions.
+                                                              (line  23)
+* gcry_pk_get_nbits_t:                   Public key modules.  (line 116)
+* gcry_pk_list:                          Public key modules.  (line 131)
+* gcry_pk_map_name:                      General public-key related Functions.
+                                                              (line  15)
+* gcry_pk_register:                      Public key modules.  (line 121)
+* gcry_pk_sign:                          Cryptographic Functions.
+                                                              (line 117)
+* gcry_pk_sign_t:                        Public key modules.  (line 106)
+* gcry_pk_spec_t:                        Public key modules.  (line  12)
+* gcry_pk_test_algo:                     General public-key related Functions.
+                                                              (line  19)
+* gcry_pk_testkey:                       General public-key related Functions.
+                                                              (line  39)
+* gcry_pk_unregister:                    Public key modules.  (line 127)
+* gcry_pk_verify:                        Cryptographic Functions.
+                                                              (line 170)
+* gcry_pk_verify_t:                      Public key modules.  (line 111)
+* gcry_randomize:                        Retrieving random numbers.
+                                                              (line   8)
+* gcry_set_allocation_handler:           Allocation handler.  (line  34)
+* gcry_set_fatalerror_handler:           Error handler.       (line  25)
+* gcry_set_log_handler:                  Logging handler.     (line  12)
+* gcry_set_outofcore_handler:            Error handler.       (line  15)
+* gcry_set_progress_handler:             Progress handler.    (line  21)
+* gcry_sexp_build:                       Working with S-expressions.
+                                                              (line  43)
+* gcry_sexp_canon_len:                   Working with S-expressions.
+                                                              (line 116)
+* gcry_sexp_car:                         Working with S-expressions.
+                                                              (line 146)
+* gcry_sexp_cdr:                         Working with S-expressions.
+                                                              (line 151)
+* gcry_sexp_create:                      Working with S-expressions.
+                                                              (line  26)
+* gcry_sexp_dump:                        Working with S-expressions.
+                                                              (line 107)
+* gcry_sexp_find_token:                  Working with S-expressions.
+                                                              (line 129)
+* gcry_sexp_length:                      Working with S-expressions.
+                                                              (line 136)
+* gcry_sexp_new:                         Working with S-expressions.
+                                                              (line  13)
+* gcry_sexp_nth:                         Working with S-expressions.
+                                                              (line 141)
+* gcry_sexp_nth_data:                    Working with S-expressions.
+                                                              (line 159)
+* gcry_sexp_nth_mpi:                     Working with S-expressions.
+                                                              (line 177)
+* gcry_sexp_release:                     Working with S-expressions.
+                                                              (line  76)
+* gcry_sexp_sprint:                      Working with S-expressions.
+                                                              (line  84)
+* gcry_sexp_sscan:                       Working with S-expressions.
+                                                              (line  37)
+* gcry_sexp_t:                           Data types for S-expressions.
+                                                              (line   7)
+* gcry_strerror:                         Error Strings.       (line   7)
+* gcry_strsource:                        Error Strings.       (line  13)
+* int <1>:                               Working with sets of data.
+                                                              (line  51)
+* int:                                   Working with hash algorithms.
+                                                              (line 184)
+Tag Table:
+Node: Top730
+Node: Introduction6207
+Node: Getting Started6581
+Node: Features7464
+Node: Overview8254
+Node: Preparation8902
+Node: Header9700
+Node: Building sources10583
+Node: Building sources using Automake12505
+Node: Initializing the library13686
+Node: Multi Threading14729
+Ref: Multi Threading-Footnote-118634
+Node: Generalities19042
+Node: Controlling the library19367
+Node: Modules19751
+Node: Error Handling20530
+Node: Error Values23055
+Node: Error Sources27995
+Node: Error Codes30266
+Node: Error Strings33227
+Node: Handler Functions34379
+Node: Progress handler34938
+Node: Allocation handler36885
+Node: Error handler38180
+Node: Logging handler39237
+Node: Symmetric cryptography39743
+Node: Available ciphers40532
+Node: Cipher modules42436
+Node: Available cipher modes46959
+Node: Working with cipher handles47638
+Node: General cipher functions55498
+Node: Hashing57975
+Node: Available hash algorithms58781
+Node: Hash algorithm modules60808
+Node: Working with hash algorithms64655
+Node: Public Key cryptography (I)75048
+Node: Available algorithms75901
+Node: Used S-expressions76254
+Node: Public key modules78046
+Node: Cryptographic Functions83634
+Node: General public-key related Functions91123
+Node: Public Key cryptography (II)98345
+Node: Available asymmetric algorithms99252
+Node: Working with sets of data99932
+Node: Working with handles102954
+Node: Working with keys103898
+Node: Using cryptographic functions107960
+Node: Handle-independent functions109778
+Node: Random Numbers110392
+Node: Quality of random numbers110687
+Node: Retrieving random numbers111343
+Node: S-expressions112755
+Node: Data types for S-expressions113399
+Node: Working with S-expressions113725
+Node: MPI library122259
+Node: Data types123567
+Node: Basic functions123773
+Node: MPI formats125841
+Node: Calculations128631
+Node: Comparisons130886
+Node: Bit manipulations131504
+Node: Miscellaneous132648
+Node: Utilities134492
+Node: Memory allocation134696
+Node: Library Copying135952
+Node: Copying164116
+Node: Concept Index183319
+Node: Function and Data Index184274
+End Tag Table
author	Jay Threeth	2011-04-04 11:48:26 -0700
committer	Jay Threeth	2011-04-04 11:48:26 -0700
commit	3c9cc506f741b980565ff5b3b001cd8b6ee36b12 (patch)
tree	cb862c57b3d5f74177cde3bd962a53fc377166f6 /linden/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.info
parent	build fixes, might build on linux now (diff)
download	meta-impy-3c9cc506f741b980565ff5b3b001cd8b6ee36b12.zip meta-impy-3c9cc506f741b980565ff5b3b001cd8b6ee36b12.tar.gz meta-impy-3c9cc506f741b980565ff5b3b001cd8b6ee36b12.tar.bz2 meta-impy-3c9cc506f741b980565ff5b3b001cd8b6ee36b12.tar.xz