+This is gcrypt.info, produced by makeinfo version 4.13 from gcrypt.texi.
+
+This manual is for Libgcrypt (version 1.4.4, 22 January 2009), which is
+GNU's library of cryptographic building blocks.
+
+ Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008 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 "GNU General Public
+ License".
+
+INFO-DIR-SECTION GNU Libraries
+START-INFO-DIR-ENTRY
+* libgcrypt: (gcrypt). Cryptographic function library.
+END-INFO-DIR-ENTRY
+
+\1f
+File: gcrypt.info, Node: Top, Next: Introduction, Up: (dir)
+
+The Libgcrypt Library
+*********************
+
+This manual is for Libgcrypt (version 1.4.4, 22 January 2009), which is
+GNU's library of cryptographic building blocks.
+
+ Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008 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 "GNU General Public
+ License".
+
+* 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.
+* Public Key cryptography:: How to use public key cryptography.
+* Hashing:: How to use hash and MAC algorithms.
+* Random Numbers:: How to work with random numbers.
+* S-expressions:: How to manage S-expressions.
+* MPI library:: How to work with multi-precision-integers.
+* Prime numbers:: How to use the Prime number related functions.
+* Utilities:: Utility functions.
+* Architecture:: How Libgcrypt works internally.
+
+Appendices
+
+* Self-Tests:: Description of the self-tests.
+* FIPS Mode:: Description of the FIPS mode.
+* 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
+
+* Figures and Tables:: Index of figures and tables.
+* Concept Index:: Index of concepts and programs.
+* Function and Data Index:: Index of functions, variables and data types.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 in general not needed by
+ applications) 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 extensible and flexible API.
+
+
+\1f
+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. Not thread-safe 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.
+
+\1f
+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.
+* Enabling FIPS mode:: How to enable the FIPS mode.
+
+\1f
+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. Note that Libgcrypt uses libgpg-error,
+which uses `gpg_*' as name space for function and type names and
+`GPG_*' for other symbols, including all the error codes.
+
+Certain parts of gcrypt.h may be excluded by defining these macros:
+
+`GCRYPT_NO_MPI_MACROS'
+ Do not define the shorthand macros `mpi_*' for `gcry_mpi_*'.
+
+`GCRYPT_NO_DEPRECATED'
+ Do not include defintions for deprecated features. This is useful
+ to make sure that no deprecated features are used.
+
+\1f
+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`
+
+\1f
+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)
+
+\1f
+File: gcrypt.info, Node: Initializing the library, Next: Multi-Threading, Prev: Building sources using Automake, Up: Preparation
+
+2.4 Initializing the library
+============================
+
+Before the library can be used, it must initialize itself. This is
+achieved by invoking the function `gcry_check_version' described below.
+
+ Also, 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 may actually be 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' initializes some subsystems used
+ by Libgcrypt and must be invoked before any other function in the
+ library, with the exception of the `GCRYCTL_SET_THREAD_CBS' command
+ (called via the `gcry_control' function). *Note Multi-Threading::.
+
+ Furthermore, this function returns the version number of the
+ library. It can also verify that the version number is higher
+ than a certain required version number REQ_VERSION, if this value
+ is not a null pointer.
+
+ Libgcrypt uses a concept known as secure memory, which is a region of
+memory set aside for storing sensitive data. Because such memory is a
+scarce resource, it needs to be setup in advanced to a fixed size.
+Further, most operating systems have special requirements on how that
+secure memory can be used. For example, it might be required to install
+an application as "setuid(root)" to allow allocating such memory.
+Libgcrypt requires a sequence of initialization steps to make sure that
+this works correctly. The following examples show the necessary steps.
+
+ If you don't have a need for secure memory, for example if your
+application does not use secret keys or other confidential data or it
+runs in a controlled environment where key material floating around in
+memory is not a problem, you should initialize Libgcrypt this way:
+
+ /* Version check should be the very first call because it
+ makes sure that important subsystems are intialized. */
+ if (!gcry_check_version (GCRYPT_VERSION))
+ {
+ fputs ("libgcrypt version mismatch\n", stderr);
+ exit (2);
+ }
+
+ /* Disable secure memory. */
+ gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
+
+ /* ... If required, other initialization goes here. */
+
+ /* Tell Libgcrypt that initialization has completed. */
+ gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
+
+ If you have to protect your keys or other information in memory
+against being swapped out to disk and to enable an automatic overwrite
+of used and freed memory, you need to initialize Libgcrypt this way:
+
+ /* Version check should be the very first call because it
+ makes sure that important subsystems are intialized. */
+ if (!gcry_check_version (GCRYPT_VERSION))
+ {
+ fputs ("libgcrypt version mismatch\n", stderr);
+ exit (2);
+ }
+
+ /* We don't want to see any warnings, e.g. because we have not yet
+ parsed program options which might be used to suppress such
+ warnings. */
+ gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
+
+ /* ... If required, other initialization goes here. Note that the
+ process might still be running with increased privileges and that
+ the secure memory has not been intialized. */
+
+ /* Allocate a pool of 16k secure memory. This make the secure memory
+ available and also drops privileges where needed. */
+ gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
+
+ /* It is now okay to let Libgcrypt complain when there was/is
+ a problem with the secure memory. */
+ gcry_control (GCRYCTL_RESUME_SECMEM_WARN);
+
+ /* ... If required, other initialization goes here. */
+
+ /* Tell Libgcrypt that initialization has completed. */
+ gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
+
+ It is important that these initialization steps are not done by a
+library but by the actual application. A library using Libgcrypt might
+want to check for finished initialization using:
+
+ if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))
+ {
+ fputs ("libgcrypt has not been initialized\n", stderr);
+ abort ();
+ }
+
+ Instead of terminating the process, the library may instead print a
+warning and try to initialize Libgcrypt itself. See also the section on
+multi-threading below for more pitfalls.
+
+\1f
+File: gcrypt.info, Node: Multi-Threading, Next: Enabling FIPS mode, 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).
+
+ * Just like the function `gpg_strerror', the function
+ `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_pthread_mutex_lock', `gcry_pthread_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.
+
+\1f
+File: gcrypt.info, Node: Enabling FIPS mode, Prev: Multi-Threading, Up: Preparation
+
+2.6 How to enable the FIPS mode
+===============================
+
+Libgcrypt may be used in a FIPS 140-2 mode. Note, that this does not
+necessary mean that Libcgrypt is an appoved FIPS 140-2 module. Check
+the NIST database at `http://csrc.nist.gov/groups/STM/cmvp/' to see what
+versions of Libgcrypt are approved.
+
+ Because FIPS 140 has certain restrictions on the use of cryptography
+which are not always wanted, Libgcrypt needs to be put into FIPS mode
+explicitly. Three alternative mechanisms are provided to switch
+Libgcrypt into this mode:
+
+ * If the file `/proc/sys/crypto/fips_enabled' exists and contains a
+ numeric value other than `0', Libgcrypt is put into FIPS mode at
+ initialization time. Obviously this works only on systems with a
+ `proc' file system (i.e. GNU/Linux).
+
+ * If the file `/etc/gcrypt/fips_enabled' exists, Libgcrypt is put
+ into FIPS mode at initialization time. Note that this filename is
+ hardwired and does not depend on any configuration options.
+
+ * If the application requests FIPS mode using the control command
+ `GCRYCTL_FORCE_FIPS_MODE'. This must be done prior to any
+ initialization (i.e. before `gcry_check_version').
+
+
+ In addition to the standard FIPS mode, Libgcrypt may also be put into
+an Enforced FIPS mode by writing a non-zero value into the file
+`/etc/gcrypt/fips_enabled'. The Enforced FIPS mode helps to detect
+applications which don't fulfill all requirements for using Libgcrypt
+in FIPS mode (*note FIPS Mode::).
+
+ Once Libgcrypt has been put into FIPS mode, it is not possible to
+switch back to standard mode without terminating the process first. If
+the logging verbosity level of Libgcrypt has been set to at least 2,
+the state transitions and the self-tests are logged.
+
+\1f
+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.
+
+\1f
+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.
+
+ `GCRYCTL_ENABLE_M_GUARD; Arguments: none'
+ This command enables the built-in memory guard. It must not
+ be used to activate the memory guard after the memory
+ management has already been used; therefore it can ONLY be
+ used at initialization time. Note that the memory guard is
+ NOT used when the user of the library has set his own memory
+ management callbacks.
+
+ `GCRYCTL_ENABLE_QUICK_RANDOM; Arguments: none'
+ This command inhibits the use the very secure random quality
+ level (`GCRY_VERY_STRONG_RANDOM') and degrades all request
+ down to `GCRY_STRONG_RANDOM'. In general this is not
+ recommened. However, for some applications the extra quality
+ random Libgcrypt tries to create is not justified and this
+ option may help to get better performace. Please check with
+ a crypto expert whether this option can be used for your
+ application.
+
+ This option can only be used at initialization time.
+
+ `GCRYCTL_DUMP_RANDOM_STATS; Arguments: none'
+ This command dumps randum number generator related statistics
+ to the library's logging stream.
+
+ `GCRYCTL_DUMP_MEMORY_STATS; Arguments: none'
+ This command dumps memory managment related statistics to the
+ library's logging stream.
+
+ `GCRYCTL_DUMP_SECMEM_STATS; Arguments: none'
+ This command dumps secure memory manamgent related statistics
+ to the library's logging stream.
+
+ `GCRYCTL_DROP_PRIVS; Arguments: none'
+ This command disables the use of secure memory and drops the
+ priviliges of the current process. This command has not much
+ use; the suggested way to disable secure memory is to use
+ `GCRYCTL_DISABLE_SECMEM' right after initialization.
+
+ `GCRYCTL_DISABLE_SECMEM; Arguments: none'
+ This command disables the use of secure memory. If this
+ command is used in FIPS mode, FIPS mode will be disabled and
+ the function `gcry_fips_mode_active' returns false. However,
+ in Enforced FIPS mode this command has no effect at all.
+
+ Many applications do not require secure memory, so they
+ should disable it right away. This command should be
+ executed right after `gcry_check_version'.
+
+ `GCRYCTL_INIT_SECMEM; Arguments: int nbytes'
+ This command is used to allocate a pool of secure memory and
+ thus enabling the use of secure memory. It also drops all
+ extra privileges the process has (i.e. if it is run as setuid
+ (root)). If the argument NBYTES is 0, secure memory will be
+ disabled. The minimum amount of secure memory allocated is
+ currently 16384 bytes; you may thus use a value of 1 to
+ request that default size.
+
+ `GCRYCTL_TERM_SECMEM; Arguments: none'
+ This command zeroises the secure memory and destroys the
+ handler. The secure memory pool may not be used anymore
+ after running this command. If the secure memory pool as
+ already been destroyed, this command has no effect.
+ Applications might want to run this command from their exit
+ handler to make sure that the secure memory gets properly
+ destroyed. This command is not necessarily thread-safe but
+ that should not be needed in cleanup code. It may be called
+ from a signal handler.
+
+ `GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none'
+ Disable warning messages about problems with the secure memory
+ subsystem. This command should be run right after
+ `gcry_check_version'.
+
+ `GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none'
+ Postpone warning messages from the secure memory subsystem.
+ *Note the initialization example: sample-use-suspend-secmem,
+ on how to use it.
+
+ `GCRYCTL_RESUME_SECMEM_WARN; Arguments: none'
+ Resume warning messages from the secure memory subsystem.
+ *Note the initialization example: sample-use-resume-secmem,
+ on how to use it.
+
+ `GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none'
+ This command tells the PRNG to store random numbers in secure
+ memory. This command should be run right after
+ `gcry_check_version' and not later than the command
+ GCRYCTL_INIT_SECMEM. Note that in FIPS mode the secure
+ memory is always used.
+
+ `GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename'
+ This command specifies the file, which is to be used as seed
+ file for the PRNG. If the seed file is registered prior to
+ initialization of the PRNG, the seed file's content (if it
+ exists and seems to be valid) is fed into the PRNG pool.
+ After the seed file has been registered, the PRNG can be
+ signalled to write out the PRNG pool's content into the seed
+ file with the following command.
+
+ `GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none'
+ Write out the PRNG pool's content into the registered seed
+ file.
+
+ Multiple instances of the applications sharing the same
+ random seed file can be started in parallel, in which case
+ they will read out the same pool and then race for updating
+ it (the last update overwrites earlier updates). They will
+ differentiate only by the weak entropy that is added in
+ read_seed_file based on the PID and clock, and up to 16 bytes
+ of weak random non-blockingly. The consequence is that the
+ output of these different instances is correlated to some
+ extent. In a perfect attack scenario, the attacker can
+ control (or at least guess) the PID and clock of the
+ application, and drain the system's entropy pool to reduce
+ the "up to 16 bytes" above to 0. Then the dependencies of the
+ inital states of the pools are completely known. Note that
+ this is not an issue if random of `GCRY_VERY_STRONG_RANDOM'
+ quality is requested as in this case enough extra entropy
+ gets mixed. It is also not an issue when using Linux
+ (rndlinux driver), because this one guarantees to read full
+ 16 bytes from /dev/urandom and thus there is no way for an
+ attacker without kernel access to control these 16 bytes.
+
+ `GCRYCTL_SET_VERBOSITY; Arguments: int level'
+ This command sets the verbosity of the logging. A level of 0
+ disables all extra logging whereas positive numbers enable
+ more verbose logging. The level may be changed at any time
+ but be aware that no memory synchronization is done so the
+ effect of this command might not immediately show up in other
+ threads. This command may even be used prior to
+ `gcry_check_version'.
+
+ `GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags'
+ Set the debug flag bits as given by the argument. Be aware
+ that that no memory synchronization is done so the effect of
+ this command might not immediately show up in other threads.
+ The debug flags are not considered part of the API and thus
+ may change without notice. As of now bit 0 enables debugging
+ of cipher functions and bit 1 debugging of
+ multi-precision-integers. This command may even be used
+ prior to `gcry_check_version'.
+
+ `GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags'
+ Set the debug flag bits as given by the argument. Be aware
+ that that no memory synchronization is done so the effect of
+ this command might not immediately show up in other threads.
+ This command may even be used prior to `gcry_check_version'.
+
+ `GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none'
+ This command does nothing. It exists only for backward
+ compatibility.
+
+ `GCRYCTL_ANY_INITIALIZATION_P; Arguments: none'
+ This command returns true if the library has been basically
+ initialized. Such a basic initialization happens implicitly
+ with many commands to get certain internal subsystems
+ running. The common and suggested way to do this basic
+ intialization is by calling gcry_check_version.
+
+ `GCRYCTL_INITIALIZATION_FINISHED; Arguments: none'
+ This command tells the libray that the application has
+ finished the intialization.
+
+ `GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none'
+ This command returns true if the command
+ GCRYCTL_INITIALIZATION_FINISHED has already been run.
+
+ `GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops'
+ This command registers a thread-callback structure. *Note
+ Multi-Threading::.
+
+ `GCRYCTL_FAST_POLL; Arguments: none'
+ Run a fast random poll.
+
+ `GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename'
+ This command may be used to override the default name of the
+ EGD socket to connect to. It may be used only during
+ initialization as it is not thread safe. Changing the socket
+ name again is not supported. The function may return an
+ error if the given filename is too long for a local socket
+ name.
+
+ EGD is an alternative random gatherer, used only on systems
+ lacking a proper random device.
+
+ `GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream'
+ This command dumps information pertaining to the
+ configuration of the library to the given stream. If NULL is
+ given for STREAM, the log system is used. This command may
+ be used before the intialization has been finished but not
+ before a gcry_version_check.
+
+ `GCRYCTL_OPERATIONAL_P; Arguments: none'
+ This command returns true if the library is in an operational
+ state. This information makes only sense in FIPS mode. In
+ contrast to other functions, this is a pure test function and
+ won't put the library into FIPS mode or change the internal
+ state. This command may be used before the intialization has
+ been finished but not before a gcry_version_check.
+
+ `GCRYCTL_FIPS_MODE_P; Arguments: none'
+ This command returns true if the library is in FIPS mode.
+ Note, that this is no indication about the current state of
+ the library. This command may be used before the
+ intialization has been finished but not before a
+ gcry_version_check. An application may use this command or
+ the convenience macro below to check whether FIPS mode is
+ actually active.
+
+ -- Function: int gcry_fips_mode_active (void)
+ Returns true if the FIPS mode is active. Note that this
+ is implemented as a macro.
+
+ `GCRYCTL_FORCE_FIPS_MODE; Arguments: none'
+ Running this command puts the library into FIPS mode. If the
+ library is already in FIPS mode, a self-test is triggered and
+ thus the library will be put into operational state. This
+ command may be used before a call to gcry_check_version and
+ that is actually the recommended way to let an application
+ switch the library into FIPS mode. Note that Libgcrypt will
+ reject an attempt to switch to fips mode during or after the
+ intialization.
+
+ `GCRYCTL_SELFTEST; Arguments: none'
+ This may be used at anytime to have the library run all
+ implemented self-tests. It works in standard and in FIPS
+ mode. Returns 0 on success or an error code on failure.
+
+
+
+\1f
+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.
+
+\1f
+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 to 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.
+
+\1f
+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'.
+
+\1f
+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
+Libgcrypt 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'.
+
+\1f
+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 occurred, 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_NOT_OPERATIONAL'
+ This value means that the library is not yet in state which allows
+ to use this function. This error code is in particular returned if
+ Libgcrypt is operated in FIPS mode and the internal state of the
+ library does not yet or not anymore allow the use of a service.
+
+ This error code is only available with newer libgpg-error
+ versions, thus you might see "invalid error code" when passing
+ this to `gpg_strerror'. The numeric value of this error code is
+ 176.
+
+`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.
+
+\1f
+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));
+ }
+ }
+
+\1f
+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.
+
+\1f
+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. It
+ may be used only during initialization. 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.
+
+
+
+\1f
+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. Using this function is in
+ general not recommended because the standard Libgcrypt allocation
+ functions are guaranteed to zeroize memory if needed.
+
+ This function may be used only during initialization and may not be
+ used in fips mode.
+
+
+\1f
+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. They
+may and should be registered prior to calling `gcry_check_version'.
+
+ -- Data type: gcry_handler_no_mem_t
+ This type is defined as: `int (*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. The handler is called with 3 arguments: The
+ first one is the pointer CB_DATA as set with this function, the
+ second is the requested memory size and the last being a flag. If
+ bit 0 of the flag is set, secure memory has been requested. The
+ handler should either return true to indicate that Libgcrypt
+ should try again allocating memory or return false to let
+ Libgcrypt use its default fatal error handler.
+
+ -- 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.
+
+\1f
+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.
+ This function may and should be used prior to calling
+ `gcry_check_version'.
+
+\1f
+File: gcrypt.info, Node: Symmetric cryptography, Next: Public Key cryptography, 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.
+
+\1f
+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_RIJNDAEL192'
+ 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.
+
+`GCRY_CIPHER_SERPENT128'
+`GCRY_CIPHER_SERPENT192'
+`GCRY_CIPHER_SERPENT256'
+ The Serpent cipher from the AES contest.
+
+`GCRY_CIPHER_RFC2268_40'
+`GCRY_CIPHER_RFC2268_128'
+ Ron's Cipher 2 in the 40 and 128 bit variants. Note, that we
+ currently only support the 40 bit variant. The identifier for 128
+ is reserved for future use.
+
+`GCRY_CIPHER_SEED'
+ A 128 bit cipher as described by RFC4269.
+
+`GCRY_CIPHER_CAMELLIA128'
+`GCRY_CIPHER_CAMELLIA192'
+`GCRY_CIPHER_CAMELLIA256'
+ The Camellia cipher by NTT. See
+ `http://info.isl.ntt.co.jp/crypt/eng/camellia/specifications.html'.
+
+
+\1f
+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
+ciphers 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.
+
+\1f
+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. This should not be used. The only exception
+ is that if Libgcrypt is not used in FIPS mode and if any debug
+ flag has been set, this mode may be used to bypass the actual
+ encryption.
+
+`GCRY_CIPHER_MODE_ECB'
+ Electronic Codebook mode.
+
+`GCRY_CIPHER_MODE_CFB'
+ Cipher Feedback mode. The shift size equals the block size of the
+ cipher (e.g. for AES it is CFB-128).
+
+`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'
+ Output Feedback mode.
+
+`GCRY_CIPHER_MODE_CTR'
+ Counter mode.
+
+
+\1f
+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 are incompatible
+ with some algorithms - in particular, stream mode
+ (`GCRY_CIPHER_MODE_STREAM') only works with stream ciphers. Any
+ block cipher mode (`GCRY_CIPHER_MODE_ECB', `GCRY_CIPHER_MODE_CBC',
+ `GCRY_CIPHER_MODE_CFB', `GCRY_CIPHER_MODE_OFB' or
+ `GCRY_CIPHER_MODE_CTR') will work with any block cipher algorithm.
+
+ 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. CTS mode makes
+ it possible to transform data of almost arbitrary size (only
+ limitation is that it must be greater than the algorithm's
+ block size).
+
+ `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,
+ const 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.
+
+
+ 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, const
+ 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.
+
+ -- Function: gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t H,
+ const 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).
+
+ -- 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,
+ unsigned char *out, size_t OUTSIZE, const unsigned char *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.
+ OUTSIZE 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,
+ unsigned char *out, size_t OUTSIZE, const unsigned char *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.
+ OUTSIZE 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.
+
+\1f
+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, the string `"?"' is returned. This function should
+ not be used to test for the availability of an algorithm.
+
+ -- 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.
+
+\1f
+File: gcrypt.info, Node: Public Key cryptography, Next: Hashing, Prev: Symmetric cryptography, Up: Top
+
+6 Public Key cryptography
+*************************
+
+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.
+
+* AC Interface:: Alternative interface to public key functions.
+
+\1f
+File: gcrypt.info, Node: Available algorithms, Next: Used S-expressions, Up: Public Key cryptography
+
+6.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.
+
+\1f
+File: gcrypt.info, Node: Used S-expressions, Next: Public key modules, Prev: Available algorithms, Up: Public Key cryptography
+
+6.2 Used S-expressions
+======================
+
+Libgcrypt's API for asymmetric cryptography is based on data structures
+called S-expressions (see
+`http://people.csail.mit.edu/rivest/sexp.html') 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 examples. Note that words
+in uppercase indicate parameters whereas lowercase words are literals.
+
+ Note that all MPI (multi-precision-integers) values are expected to
+be in `GCRYMPI_FMT_USG' format. An easy way to create S-expressions is
+by using `gcry_sexp_build' which allows to pass a string with
+printf-like escapes to insert MPI values.
+
+* Menu:
+
+* RSA key parameters:: Parameters used with an RSA key.
+* DSA key parameters:: Parameters used with a DSA key.
+* ECC key parameters:: Parameters used with ECC keys.
+
+\1f
+File: gcrypt.info, Node: RSA key parameters, Next: DSA key parameters, Up: Used S-expressions
+
+6.2.1 RSA key parameters
+------------------------
+
+An RSA private key is described by this S-expression:
+
+ (private-key
+ (rsa
+ (n N-MPI)
+ (e E-MPI)
+ (d D-MPI)
+ (p P-MPI)
+ (q Q-MPI)
+ (u U-MPI)))
+
+An RSA public key is described by this S-expression:
+
+ (public-key
+ (rsa
+ (n N-MPI)
+ (e E-MPI)))
+
+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 p < q.
+
+U-MPI
+ Multiplicative inverse u = p^-1 \bmod q.
+
+ For signing and decryption the parameters (p, q, u) are optional but
+greatly improve the performance. Either all of these optional
+parameters must be given or none of them. They are mandatory for
+gcry_pk_testkey.
+
+ Note that OpenSSL uses slighly different parameters: q < p and u =
+q^-1 \bmod p. To use these parameters you will need to swap the values
+and recompute u. Here is example code to do this:
+
+ if (gcry_mpi_cmp (p, q) > 0)
+ {
+ gcry_mpi_swap (p, q);
+ gcry_mpi_invm (u, p, q);
+ }
+
+\1f
+File: gcrypt.info, Node: DSA key parameters, Next: ECC key parameters, Prev: RSA key parameters, Up: Used S-expressions
+
+6.2.2 DSA key parameters
+------------------------
+
+A DSA private key is described by this S-expression:
+
+ (private-key
+ (dsa
+ (p P-MPI)
+ (q Q-MPI)
+ (g G-MPI)
+ (y Y-MPI)
+ (x X-MPI)))
+
+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.
+
+ The public key is similar with "private-key" replaced by "public-key"
+and no X-MPI.
+
+\1f
+File: gcrypt.info, Node: ECC key parameters, Prev: DSA key parameters, Up: Used S-expressions
+
+6.2.3 ECC key parameters
+------------------------
+
+An ECC private key is described by this S-expression:
+
+ (private-key
+ (ecc
+ (p P-MPI)
+ (a A-MPI)
+ (b B-MPI)
+ (g G-POINT)
+ (n N-MPI)
+ (q Q-POINT)
+ (d D-MPI)))
+
+P-MPI
+ Prime specifying the field GF(p).
+
+A-MPI
+B-MPI
+ The two coefficients of the Weierstrass equation y^2 = x^3 + ax + b
+
+G-POINT
+ Base point g.
+
+N-MPI
+ Order of g
+
+Q-POINT
+ The point representing the public key Q = dP.
+
+D-MPI
+ The private key d
+
+ All point values are encoded in standard format; Libgcrypt does
+currently only support uncompressed points, thus the first byte needs to
+be `0x04'.
+
+ The public key is similar with "private-key" replaced by "public-key"
+and no D-MPI.
+
+ If the domain parameters are well-known, the name of this curve may
+be used. For example
+
+ (private-key
+ (ecc
+ (curve "NIST P-192")
+ (q Q-POINT)
+ (d D-MPI)))
+
+ The `curve' parameter may be given in any case and is used to replace
+missing parameters.
+
+Currently implemented curves are:
+`NIST P-192'
+`1.2.840.10045.3.1.1'
+`prime192v1'
+`secp192r1'
+ The NIST 192 bit curve, its OID, X9.62 and SECP aliases.
+
+`NIST P-224'
+`secp224r1'
+ The NIST 224 bit curve and its SECP alias.
+
+`NIST P-256'
+`1.2.840.10045.3.1.7'
+`prime256v1'
+`secp256r1'
+ The NIST 256 bit curve, its OID, X9.62 and SECP aliases.
+
+`NIST P-384'
+`secp384r1'
+ The NIST 384 bit curve and its SECP alias.
+
+`NIST P-521'
+`secp521r1'
+ The NIST 521 bit curve and its SECP alias.
+
+ As usual the OIDs may optionally be prefixed with the string `OID.'
+or `oid.'.
+
+\1f
+File: gcrypt.info, Node: Public key modules, Next: Cryptographic Functions, Prev: Used S-expressions, Up: Public Key cryptography
+
+6.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.
+
+\1f
+File: gcrypt.info, Node: Cryptographic Functions, Next: General public-key related Functions, Prev: Public key modules, Up: Public Key cryptography
+
+6.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 new S-expression with the encrypted
+ result is allocated and assigned 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.
+
+
+\1f
+File: gcrypt.info, Node: General public-key related Functions, Next: AC Interface, Prev: Cryptographic Functions, Up: Public Key cryptography
+
+6.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
+ the string `"?"'. This function should not be used to test for the
+ availability of an algorithm.
+
+ -- 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 be
+ `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 check the `saneness'
+ of a public key.
+
+
+ -- Function: gcry_error_t 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 if 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.
+
+ Unless you need to test for the allowed usage, it is in
+ general better to use the macro gcry_pk_test_algo instead.
+
+ `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 to generate 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 to create an 2048 bit RSA key:
+
+ (genkey
+ (rsa
+ (nbits 4:2048)))
+
+ 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. The
+ value should be a multiple of 8.
+
+ `curve NAME'
+ For ECC a named curve may be used instead of giving the
+ number of requested bits. This allows to request a specific
+ curve to override a default selection Libgcrypt would have
+ taken if `nbits' has been given. The available names are
+ listed with the description of the ECC public key parameters.
+
+ `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 value as required by some crypto policies. This
+ is currently the number 65537.
+
+ `2'
+ Reserved
+
+ `> 2'
+ Use the given value.
+
+ If this parameter is not used, Libgcrypt uses for historic
+ reasons 65537.
+
+ `qbits'
+ This is only meanigful for DSA keys. If it is given the DSA
+ key is generated with a Q parameyer of this size. If it is
+ not given or zero Q is deduced from NBITS in this way:
+ `512 <= N <= 1024'
+ Q = 160
+
+ `N = 2048'
+ Q = 224
+
+ `N = 3072'
+ Q = 256
+
+ `N = 7680'
+ Q = 384
+
+ `N = 15360'
+ Q = 512
+ Note that in this case only the values for N, as given in the
+ table, are allowed. When specifying Q all values of N in the
+ range 512 to 15680 are valid as long as they are multiples of
+ 8.
+
+ `transient-key'
+ This is only meaningful for RSA and DSA keys. This is a flag
+ with no value. If given the RSA or DSA key is created using
+ a faster and a somewhat less secure random number generator.
+ This flag may be used for keys which are only used for a
+ short time and do not require full cryptographic strength.
+
+ `domain'
+ This is only meaningful for DLP algorithms. If specified
+ keys are generated with domain parameters taken from this
+ list. The exact format of this parameter depends on the
+ actual algorithm. It is currently only implemented for DSA
+ using this format:
+
+ (genkey
+ (dsa
+ (domain
+ (p P-MPI)
+ (q Q-MPI)
+ (g Q-MPI))))
+
+ `nbits' and `qbits' may not be specified because they are
+ derived from the domain parameters.
+
+ `derive-parms'
+ This is currently only implemented for RSA and DSA keys. It
+ is not allowed to use this together with a `domain'
+ specification. If given, it is used to derive the keys using
+ the given parameters.
+
+ If given for an RSA key the X9.31 key generation algorithm is
+ used even if libgcrypt is not in FIPS mode. If given for a
+ DSA key, the FIPS 186 algorithm is used even if libgcrypt is
+ not in FIPS mode.
+
+ (genkey
+ (rsa
+ (nbits 4:1024)
+ (rsa-use-e 1:3)
+ (derive-parms
+ (Xp1 #1A1916DDB29B4EB7EB6732E128#)
+ (Xp2 #192E8AAC41C576C822D93EA433#)
+ (Xp #D8CD81F035EC57EFE822955149D3BFF70C53520D
+ 769D6D76646C7A792E16EBD89FE6FC5B605A6493
+ 39DFC925A86A4C6D150B71B9EEA02D68885F5009
+ B98BD984#)
+ (Xq1 #1A5CF72EE770DE50CB09ACCEA9#)
+ (Xq2 #134E4CAA16D2350A21D775C404#)
+ (Xq #CC1092495D867E64065DEE3E7955F2EBC7D47A2D
+ 7C9953388F97DDDC3E1CA19C35CA659EDC2FC325
+ 6D29C2627479C086A699A49C4C9CEE7EF7BD1B34
+ 321DE34A#))))
+
+ (genkey
+ (dsa
+ (nbits 4:1024)
+ (derive-parms
+ (seed SEED-MPI))))
+
+ `use-x931'
+ Force the use of the ANSI X9.31 key generation algorithm
+ instead of the default algorithm. This flag is only
+ meaningful for RSA and usually not required. Note that this
+ algorithm is implicitly used if either `derive-parms' is
+ given or Libgcrypt is in FIPS mode.
+
+ `use-fips186'
+ Force the use of the FIPS 186 key generation algorithm
+ instead of the default algorithm. This flag is only
+ meaningful for DSA and usually not required. Note that this
+ algorithm is implicitly used if either `derive-parms' is
+ given or Libgcrypt is in FIPS mode. As of now FIPS 186-2 is
+ implemented; after the approval of FIPS 186-3 the code will
+ be changed to implement 186-3.
+
+ `use-fips186-2'
+ Force the use of the FIPS 186-2 key generation algorithm
+ instead of the default algorithm. This algorithm is slighlty
+ different from FIPS 186-3 and allows only 1024 bit keys.
+ This flag is only meaningful for DSA and only required for
+ FIPS testing backward compatibility.
+
+
+ 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 and only available if the key
+ generation algorithm provides them.
+
+\1f
+File: gcrypt.info, Node: AC Interface, Prev: General public-key related Functions, Up: Public Key cryptography
+
+6.6 Alternative Public Key Interface
+====================================
+
+This section 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.
+
+ *This interface has a few known problems; most noteworthy an
+inherent tendency to leak memory. It might not be available in
+forthcoming versions of Libgcrypt.*
+
+* 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 IO objects:: How to work with IO objects.
+* 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.
+
+\1f
+File: gcrypt.info, Node: Available asymmetric algorithms, Next: Working with sets of data, Up: AC Interface
+
+6.6.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'
+ Rivest-Shamir-Adleman
+
+ `GCRY_AC_DSA'
+ Digital Signature Algorithm
+
+ `GCRY_AC_ELG'
+ Elgamal
+
+ `GCRY_AC_ELG_E'
+ Elgamal, encryption only.
+
+\1f
+File: gcrypt.info, Node: Working with sets of data, Next: Working with IO objects, Prev: Available asymmetric algorithms, Up: AC Interface
+
+6.6.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; a named MPI value is a an MPI value,
+associated with a label.
+
+ 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 data sets.
+
+ -- Data type: gcry_ac_data_t
+ A single data set.
+
+ 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. Note that whenever one of the ac
+ functions is about to release objects because of this flag, the
+ objects are expected to be stored in memory allocated through the
+ Libgcrypt memory management. In other words: gcry_free() is used
+ instead of free().
+
+`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_COPY, the data set will contain copies of NAME and
+ MPI. If FLAGS contains GCRY_AC_FLAG_DEALLOC or GCRY_AC_FLAG_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.
+ FIXME: exact semantics undefined.
+
+ -- 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 (this might be useful
+ for checking the existence of an MPI with extracting it).
+
+ -- 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.
+
+ -- Function: gcry_error_t gcry_ac_data_to_sexp (gcry_ac_data_t DATA,
+ gcry_sexp_t *SEXP, const char **IDENTIFIERS)
+ This function converts the data set DATA into a newly created
+ S-Expression, which is to be stored in SEXP; IDENTIFIERS is a NULL
+ terminated list of C strings, which specifies the structure of the
+ S-Expression.
+
+ Example:
+
+ If IDENTIFIERS is a list of pointers to the strings "foo" and
+ "bar" and if DATA is a data set containing the values "val1 =
+ 0x01" and "val2 = 0x02", then the resulting S-Expression will look
+ like this: (foo (bar ((val1 0x01) (val2 0x02))).
+
+ -- Function: gcry_error gcry_ac_data_from_sexp (gcry_ac_data_t *DATA,
+ gcry_sexp_t SEXP, const char **IDENTIFIERS)
+ This function converts the S-Expression SEXP into a newly created
+ data set, which is to be stored in DATA; IDENTIFIERS is a NULL
+ terminated list of C strings, which specifies the structure of the
+ S-Expression. If the list of identifiers does not match the
+ structure of the S-Expression, the function fails.
+
+\1f
+File: gcrypt.info, Node: Working with IO objects, Next: Working with handles, Prev: Working with sets of data, Up: AC Interface
+
+6.6.3 Working with IO objects
+-----------------------------
+
+Note: IO objects are currently only used in the context of message
+encoding/decoding and encryption/signature schemes.
+
+ -- Data type: gcry_ac_io_t
+ `gcry_ac_io_t' is the type to be used for IO objects.
+
+ IO objects provide an uniform IO layer on top of different underlying
+IO mechanisms; either they can be used for providing data to the
+library (mode is GCRY_AC_IO_READABLE) or they can be used for
+retrieving data from the library (mode is GCRY_AC_IO_WRITABLE).
+
+ IO object need to be initialized by calling on of the following
+functions:
+
+ -- Function: void gcry_ac_io_init (gcry_ac_io_t *AC_IO,
+ gcry_ac_io_mode_t MODE, gcry_ac_io_type_t TYPE, ...);
+ Initialize AC_IO according to MODE, TYPE and the variable list of
+ arguments. The list of variable arguments to specify depends on
+ the given TYPE.
+
+ -- Function: void gcry_ac_io_init_va (gcry_ac_io_t *AC_IO,
+ gcry_ac_io_mode_t MODE, gcry_ac_io_type_t TYPE, va_list AP);
+ Initialize AC_IO according to MODE, TYPE and the variable list of
+ arguments AP. The list of variable arguments to specify depends
+ on the given TYPE.
+
+ The following types of IO objects exist:
+
+`GCRY_AC_IO_STRING'
+ In case of GCRY_AC_IO_READABLE the IO object will provide data
+ from a memory string. Arguments to specify at initialization time:
+ `unsigned char *'
+ Pointer to the beginning of the memory string
+
+ `size_t'
+ Size of the memory string
+ In case of GCRY_AC_IO_WRITABLE the object will store retrieved
+ data in a newly allocated memory string. Arguments to specify at
+ initialization time:
+ `unsigned char **'
+ Pointer to address, at which the pointer to the newly created
+ memory string is to be stored
+
+ `size_t *'
+ Pointer to address, at which the size of the newly created
+ memory string is to be stored
+
+`GCRY_AC_IO_CALLBACK'
+ In case of GCRY_AC_IO_READABLE the object will forward read
+ requests to a provided callback function. Arguments to specify at
+ initialization time:
+ `gcry_ac_data_read_cb_t'
+ Callback function to use
+
+ `void *'
+ Opaque argument to provide to the callback function
+ In case of GCRY_AC_IO_WRITABLE the object will forward write
+ requests to a provided callback function. Arguments to specify at
+ initialization time:
+ `gcry_ac_data_write_cb_t'
+ Callback function to use
+
+ `void *'
+ Opaque argument to provide to the callback function
+
+\1f
+File: gcrypt.info, Node: Working with handles, Next: Working with keys, Prev: Working with IO objects, Up: AC Interface
+
+6.6.4 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 currently.
+
+ ALGORITHM must be a valid algorithm ID, see *Note Available
+ asymmetric algorithms::, for a list of supported algorithms and the
+ according constants. Besides using the listed constants directly,
+ the functions `gcry_pk_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.
+
+\1f
+File: gcrypt.info, Node: Working with keys, Next: Using cryptographic functions, Prev: Working with handles, Up: AC Interface
+
+6.6.5 Working with keys
+-----------------------
+
+ -- Data type: gcry_ac_key_type_t
+ Defined constants:
+
+ `GCRY_AC_KEY_SECRET'
+ Specifies a secret key.
+
+ `GCRY_AC_KEY_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 description 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 decide 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_t 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, 1024, &rsa_spec,
+ &key_pair, NULL);
+ 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.
+
+\1f
+File: gcrypt.info, Node: Using cryptographic functions, Next: Handle-independent functions, Prev: Working with keys, Up: AC Interface
+
+6.6.6 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.
+
+ There exist two kinds of cryptographic functions available through
+the ac interface: primitives, and high-level functions.
+
+ Primitives deal with MPIs (data sets) directly; what they provide is
+direct access to the cryptographic operations provided by an algorithm
+implementation.
+
+ High-level functions deal with octet strings, according to a
+specified "scheme". Schemes make use of "encoding methods", which are
+responsible for converting the provided octet strings into MPIs, which
+are then forwared to the cryptographic primitives. Since schemes are
+to be used for a special purpose in order to achieve a particular
+security goal, there exist "encryption schemes" and "signature
+schemes". Encoding methods can be used seperately or implicitly
+through schemes.
+
+ What follows is a description of the cryptographic primitives.
+
+ -- 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.
+
+ What follows is a description of the high-level functions.
+
+ The type "gcry_ac_em_t" is used for specifying encoding methods; the
+following methods are supported:
+
+`GCRY_AC_EME_PKCS_V1_5'
+ PKCS-V1_5 Encoding Method for Encryption. Options must be provided
+ through a pointer to a correctly initialized object of type
+ gcry_ac_eme_pkcs_v1_5_t.
+
+`GCRY_AC_EMSA_PKCS_V1_5'
+ PKCS-V1_5 Encoding Method for Signatures with Appendix. Options
+ must be provided through a pointer to a correctly initialized
+ object of type gcry_ac_emsa_pkcs_v1_5_t.
+
+ Option structure types:
+
+`gcry_ac_eme_pkcs_v1_5_t'
+
+ `gcry_ac_key_t key'
+
+ `gcry_ac_handle_t handle'
+
+`gcry_ac_emsa_pkcs_v1_5_t'
+
+ `gcry_md_algo_t md'
+
+ `size_t em_n'
+
+ Encoding methods can be used directly through the following
+functions:
+
+ -- Function: gcry_error_t gcry_ac_data_encode (gcry_ac_em_t METHOD,
+ unsigned int FLAGS, void *OPTIONS, unsigned char *M, size_t
+ M_N, unsigned char **EM, size_t *EM_N)
+ Encodes the message contained in M of size M_N according to
+ METHOD, FLAGS and OPTIONS. The newly created encoded message is
+ stored in EM and EM_N.
+
+ -- Function: gcry_error_t gcry_ac_data_decode (gcry_ac_em_t METHOD,
+ unsigned int FLAGS, void *OPTIONS, unsigned char *EM, size_t
+ EM_N, unsigned char **M, size_t *M_N)
+ Decodes the message contained in EM of size EM_N according to
+ METHOD, FLAGS and OPTIONS. The newly created decoded message is
+ stored in M and M_N.
+
+ The type "gcry_ac_scheme_t" is used for specifying schemes; the
+following schemes are supported:
+
+`GCRY_AC_ES_PKCS_V1_5'
+ PKCS-V1_5 Encryption Scheme. No options can be provided.
+
+`GCRY_AC_SSA_PKCS_V1_5'
+ PKCS-V1_5 Signature Scheme (with Appendix). Options can be
+ provided through a pointer to a correctly initialized object of
+ type gcry_ac_ssa_pkcs_v1_5_t.
+
+ Option structure types:
+
+`gcry_ac_ssa_pkcs_v1_5_t'
+
+ `gcry_md_algo_t md'
+
+ The functions implementing schemes:
+
+ -- Function: gcry_error_t gcry_ac_data_encrypt_scheme
+ (gcry_ac_handle_t HANDLE, gcry_ac_scheme_t SCHEME, unsigned
+ int FLAGS, void *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t
+ *IO_MESSAGE, gcry_ac_io_t *IO_CIPHER)
+ Encrypts the plain text readable from IO_MESSAGE through HANDLE
+ with the public key KEY according to SCHEME, FLAGS and OPTS. If
+ OPTS is not NULL, it has to be a pointer to a structure specific
+ to the chosen scheme (gcry_ac_es_*_t). The encrypted message is
+ written to IO_CIPHER.
+
+ -- Function: gcry_error_t gcry_ac_data_decrypt_scheme
+ (gcry_ac_handle_t HANDLE, gcry_ac_scheme_t SCHEME, unsigned
+ int FLAGS, void *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t
+ *IO_CIPHER, gcry_ac_io_t *IO_MESSAGE)
+ Decrypts the cipher text readable from IO_CIPHER through HANDLE
+ with the secret key KEY according to SCHEME, FLAGS and OPTS. If
+ OPTS is not NULL, it has to be a pointer to a structure specific
+ to the chosen scheme (gcry_ac_es_*_t). The decrypted message is
+ written to IO_MESSAGE.
+
+ -- Function: gcry_error_t gcry_ac_data_sign_scheme (gcry_ac_handle_t
+ HANDLE, gcry_ac_scheme_t SCHEME, unsigned int FLAGS, void
+ *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t *IO_MESSAGE,
+ gcry_ac_io_t *IO_SIGNATURE)
+ Signs the message readable from IO_MESSAGE through HANDLE with the
+ secret key KEY according to SCHEME, FLAGS and OPTS. If OPTS is
+ not NULL, it has to be a pointer to a structure specific to the
+ chosen scheme (gcry_ac_ssa_*_t). The signature is written to
+ IO_SIGNATURE.
+
+ -- Function: gcry_error_t gcry_ac_data_verify_scheme (gcry_ac_handle_t
+ HANDLE, gcry_ac_scheme_t SCHEME, unsigned int FLAGS, void
+ *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t *IO_MESSAGE,
+ gcry_ac_io_t *IO_SIGNATURE)
+ Verifies through HANDLE that the signature readable from
+ IO_SIGNATURE is indeed the result of signing the message readable
+ from IO_MESSAGE with the secret key belonging to the public key
+ KEY according to SCHEME and OPTS. If OPTS is not NULL, it has to
+ be an anonymous structure (gcry_ac_ssa_*_t) specific to the chosen
+ scheme.
+
+\1f
+File: gcrypt.info, Node: Handle-independent functions, Prev: Using cryptographic functions, Up: AC Interface
+
+6.6.7 Handle-independent functions
+----------------------------------
+
+These two functions are deprecated; do not use them for new code.
+
+ -- 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. Deprecated; use `gcry_pk_algo_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. Deprecated; use
+ `gcry_pk_map_name'.
+
+\1f
+File: gcrypt.info, Node: Hashing, Next: Random Numbers, Prev: Public Key cryptography, Up: Top
+
+7 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 compute 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.
+
+\1f
+File: gcrypt.info, Node: Available hash algorithms, Next: Hash algorithm modules, Up: Hashing
+
+7.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_SHA224'
+ This is the SHA-224 algorithm which yields a message digest of 28
+ bytes. See Change Notice 1 for FIPS 180-2 for the specification.
+
+`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 the SHA-384 algorithm which yields a message digest of 48
+ bytes. See FIPS 180-2 for the specification.
+
+`GCRY_MD_SHA512'
+ This is the SHA-384 algorithm which yields a message digest of 64
+ bytes. See FIPS 180-2 for the specification.
+
+`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.
+
+`GCRY_MD_WHIRLPOOL'
+ This is the Whirlpool algorithm which yields a message digest of 64
+ bytes.
+
+
+\1f
+File: gcrypt.info, Node: Hash algorithm modules, Next: Working with hash algorithms, Prev: Available hash algorithms, Up: Hashing
+
+7.2 Hash algorithm modules
+==========================
+
+Libgcrypt makes it possible to load additional `message digest
+modules'; these digests 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.
+
+\1f
+File: gcrypt.info, Node: Working with hash algorithms, Prev: Hash algorithm modules, Up: Hashing
+
+7.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 only works if just one algorithm is enabled
+ for the handle. Note that the function `gcry_md_setkey' must
+ be used to set the MAC key. The size of the MAC is equal to
+ the message digest of the underlying hash algorithm. 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. There is no restriction on the length of the
+ key.
+
+ 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 then 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, it is time
+to see how it is actually done. There are two 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 methods can be used on the same hash
+context.
+
+ -- 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 do not provide for reading out
+intermediate message digests because the calculation must be finalized
+first. This finalization may for example include the number of bytes
+hashed in the message digest or some padding.
+
+ -- 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
+ void *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 two 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 function returns the
+ 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.
+
+ -- Function: void gcry_md_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'. If `NULL' is used for SUFFIX, the debugging is
+ stopped and the file closed. This is only rarely required because
+ `gcry_md_close' implicitly stops debugging.
+
+ The following two deprecated macros are used for debugging by old
+code. They shopuld be replaced by `gcry_md_debug'.
+
+ -- 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.
+
+\1f
+File: gcrypt.info, Node: Random Numbers, Next: S-expressions, Prev: Hashing, Up: Top
+
+8 Random Numbers
+****************
+
+* Menu:
+
+* Quality of random numbers:: Libgcrypt uses different quality levels.
+* Retrieving random numbers:: How to retrieve random numbers.
+
+\1f
+File: gcrypt.info, Node: Quality of random numbers, Next: Retrieving random numbers, Up: Random Numbers
+
+8.1 Quality of random numbers
+=============================
+
+Libgcypt offers random numbers of different quality levels:
+
+ -- Data type: gcry_random_level_t
+ The constants for the random quality levels are of this enum type.
+
+`GCRY_WEAK_RANDOM'
+ For all functions, except for `gcry_mpi_randomize', this level maps
+ to GCRY_STRONG_RANDOM. If you do not want this, consider using
+ `gcry_create_nonce'.
+
+`GCRY_STRONG_RANDOM'
+ Use this level for session keys and similar purposes.
+
+`GCRY_VERY_STRONG_RANDOM'
+ Use this level for long term key material.
+
+\1f
+File: gcrypt.info, Node: Retrieving random numbers, Prev: Quality of random numbers, Up: Random Numbers
+
+8.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)
+ Convenience function to 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)
+ Convenience function to 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 (unsigned char *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.
+
+
+\1f
+File: gcrypt.info, Node: S-expressions, Next: MPI library, Prev: Random Numbers, Up: Top
+
+9 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.
+
+\1f
+File: gcrypt.info, Node: Data types for S-expressions, Next: Working with S-expressions, Up: S-expressions
+
+9.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.
+
+\1f
+File: gcrypt.info, Node: Working with S-expressions, Prev: Data types for S-expressions, Up: S-expressions
+
+9.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 is 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,
+ char *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.
+ *Caution:* 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: char * gcry_sexp_nth_string (gcry_sexp_t LIST, int NUMBER)
+ This function is used to get and convert data from a LIST. The
+ data is assumed to be a Nul terminated string. The caller must
+ release this returned value using `gcry_free'. If there is no
+ data at the given index, the index represents a list or the value
+ can't be converted to a string, `NULL' is returned.
+
+ -- 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.
+
+\1f
+File: gcrypt.info, Node: MPI library, Next: Prime numbers, Prev: S-expressions, Up: Top
+
+10 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. In the context of
+Libgcrypt and in most other applications, these large numbers are
+called MPIs (multi-precision-integers).
+
+\1f
+File: gcrypt.info, Node: Data types, Next: Basic functions, Up: MPI library
+
+10.1 Data types
+===============
+
+ -- Data type: gcry_mpi_t
+ This type represents an object to hold an MPI.
+
+\1f
+File: gcrypt.info, Node: Basic functions, Next: MPI formats, Prev: Data types, Up: MPI library
+
+10.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.
+
+\1f
+File: gcrypt.info, Node: MPI formats, Next: Calculations, Prev: Basic functions, Up: MPI library
+
+10.3 MPI formats
+================
+
+The following functions are used to convert between an external
+representation of an MPI and the internal one of Libgcrypt.
+
+ -- Function: gcry_error_t gcry_mpi_scan (gcry_mpi_t *R_MPI,
+ enum gcry_mpi_format FORMAT, const unsigned char *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 should 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. When using this format, BUFLEN must be zero.
+
+ `GCRYMPI_FMT_USG'
+ Simple unsigned integer.
+
+ Note that all of the above formats store the integer in big-endian
+ format (MSB first).
+
+ -- Function: gcry_error_t 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: gcry_error_t 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.
+
+\1f
+File: gcrypt.info, Node: Calculations, Next: Comparisons, Prev: MPI formats, Up: MPI library
+
+10.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.
+
+\1f
+File: gcrypt.info, Node: Comparisons, Next: Bit manipulations, Prev: Calculations, Up: MPI library
+
+10.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 multi-precision-integers 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 multi-precision-integers number U with the unsigned
+ integer V returning 0 for equality, a positive value for U > V and
+ a negative for U < V.
+
+\1f
+File: gcrypt.info, Node: Bit manipulations, Next: Miscellaneous, Prev: Comparisons, Up: MPI library
+
+10.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.
+
+ -- Function: void gcry_mpi_lshift (gcry_mpi_t X, gcry_mpi_t A,
+ unsigned int N)
+ Shift the value of A by N bits to the left and store the result in
+ X.
+
+\1f
+File: gcrypt.info, Node: Miscellaneous, Prev: Bit manipulations, Up: MPI library
+
+10.7 Miscellaneous
+==================
+
+ -- 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 multi-precision-integers 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 multi-precision-integers 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.
+ When using a LEVEL of `GCRY_WEAK_RANDOM' this function makes use of
+ `gcry_create_nonce'.
+
+\1f
+File: gcrypt.info, Node: Prime numbers, Next: Utilities, Prev: MPI library, Up: Top
+
+11 Prime numbers
+****************
+
+* Menu:
+
+* Generation:: Generation of new prime numbers.
+* Checking:: Checking if a given number is prime.
+
+\1f
+File: gcrypt.info, Node: Generation, Next: Checking, Up: Prime numbers
+
+11.1 Generation
+===============
+
+ -- Function: gcry_error_t gcry_prime_generate (gcry_mpi_t
+ *PRIME,unsigned int PRIME_BITS, unsigned int FACTOR_BITS,
+ gcry_mpi_t **FACTORS, gcry_prime_check_func_t CB_FUNC, void
+ *CB_ARG, gcry_random_level_t RANDOM_LEVEL, unsigned int FLAGS)
+ Generate a new prime number of PRIME_BITS bits and store it in
+ PRIME. If FACTOR_BITS is non-zero, one of the prime factors of
+ (PRIME - 1) / 2 must be FACTOR_BITS bits long. If FACTORS is
+ non-zero, allocate a new, `NULL'-terminated array holding the
+ prime factors and store it in FACTORS. FLAGS might be used to
+ influence the prime number generation process.
+
+ -- Function: gcry_error_t gcry_prime_group_generator (gcry_mpi_t *R_G,
+ gcry_mpi_t PRIME, gcry_mpi_t *FACTORS, gcry_mpi_t START_G)
+ Find a generator for PRIME where the factorization of (PRIME-1) is
+ in the `NULL' terminated array FACTORS. Return the generator as a
+ newly allocated MPI in R_G. If START_G is not NULL, use this as
+ the start for the search.
+
+ -- Function: void gcry_prime_release_factors (gcry_mpi_t *FACTORS)
+ Convenience function to release the FACTORS array.
+
+\1f
+File: gcrypt.info, Node: Checking, Prev: Generation, Up: Prime numbers
+
+11.2 Checking
+=============
+
+ -- Function: gcry_error_t gcry_prime_check (gcry_mpi_t P, unsigned int
+ FLAGS)
+ Check wether the number P is prime. Returns zero in case P is
+ indeed a prime, returns `GPG_ERR_NO_PRIME' in case P is not a
+ prime and a different error code in case something went horribly
+ wrong.
+
+\1f
+File: gcrypt.info, Node: Utilities, Next: Architecture, Prev: Prime numbers, Up: Top
+
+12 Utilities
+************
+
+* Menu:
+
+* Memory allocation:: Functions related with memory allocation.
+
+\1f
+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.
+
+\1f
+File: gcrypt.info, Node: Architecture, Next: Self-Tests, Prev: Utilities, Up: Top
+
+13 Architecture
+***************
+
+This chapter describes the internal architecture of Libgcrypt.
+
+ Libgcrypt is a function library written in ISO C-90. Any compliant
+compiler should be able to build Libgcrypt as long as the target is
+either a POSIX platform or compatible to the API used by Windows NT.
+Provisions have been take so that the library can be directly used from
+C++ applications; however building with a C++ compiler is not supported.
+
+ Building Libgcrypt is done by using the common `./configure && make'
+approach. The configure command is included in the source distribution
+and as a portable shell script it works on any Unix-alike system. The
+result of running the configure script are a C header file
+(`config.h'), customized Makefiles, the setup of symbolic links and a
+few other things. After that the make tool builds and optionally
+installs the library and the documentation. See the files `INSTALL'
+and `README' in the source distribution on how to do this.
+
+ Libgcrypt is developed using a Subversion(1) repository. Although
+all released versions are tagged in this repository, they should not be
+used to build production versions of Libgcrypt. Instead released
+tarballs should be used. These tarballs are available from several
+places with the master copy at <ftp://ftp.gnupg.org/gcrypt/libgcrypt/>.
+Announcements of new releases are posted to the
+<gnupg-announce@gnupg.org> mailing list(2).
+
+ \0\b[image src="libgcrypt-modules.png" alt="Libgcrypt subsystems"\0\b]
+Figure 13.1: Libgcrypt subsystems
+
+ Libgcrypt consists of several subsystems (*note Figure 13.1:
+fig:subsystems.) and all these subsystems provide a public API; this
+includes the helper subsystems like the one for S-expressions. The API
+style depends on the subsystem; in general an open-use-close approach
+is implemented. The open returns a handle to a context used for all
+further operations on this handle, several functions may then be used
+on this handle and a final close function releases all resources
+associated with the handle.
+
+* Menu:
+
+* Public-Key Subsystem Architecture:: About public keys.
+* Symmetric Encryption Subsystem Architecture:: About standard ciphers.
+* Hashing and MACing Subsystem Architecture:: About hashing.
+* Multi-Precision-Integer Subsystem Architecture:: About big integers.
+* Prime-Number-Generator Subsystem Architecture:: About prime numbers.
+* Random-Number Subsystem Architecture:: About random stuff.
+
+ ---------- Footnotes ----------
+
+ (1) A version control system available for many platforms
+
+ (2) See `http://www.gnupg.org/documentation/mailing-lists.en.html'
+for details.
+
+\1f
+File: gcrypt.info, Node: Public-Key Subsystem Architecture, Next: Symmetric Encryption Subsystem Architecture, Up: Architecture
+
+13.1 Public-Key Architecture
+============================
+
+Libgcrypt implements two interfaces for public key cryptography: The
+standard interface is PK interface using functions in the `gcry_pk_'
+name space. The AC interface in an alternative one which is now
+deprecated and will not be further described. The AC interface is also
+disabled in FIPS mode.
+
+ Because public key cryptography is almost always used to process
+small amounts of data (hash values or session keys), the interface is
+not implemented using the open-use-close paradigm, but with single
+self-contained functions. Due to the wide variety of parameters
+required by different algorithms S-expressions, as flexible way to
+convey these parameters, are used. There is a set of helper functions
+to work with these S-expressions.
+
+ Aside of functions to register new algorithms, map algorithms names
+to algorithms identifiers and to lookup properties of a key, the
+following main functions are available:
+
+`gcry_pk_encrypt'
+ Encrypt data using a public key.
+
+`gcry_pk_decrypt'
+ Decrypt data using a private key.
+
+`gcry_pk_sign'
+ Sign data using a private key.
+
+`gcry_pk_verify'
+ Verify that a signature matches the data.
+
+`gcry_pk_testkey'
+ Perform a consistency over a public or private key.
+
+`gcry_pk_genkey'
+ Create a new public/private key pair.
+
+
+ With the help of the module registration system all these functions
+lookup the module implementing the algorithm and pass the actual work
+to that module. The parsing of the S-expression input and the
+construction of S-expression for the return values is done by the high
+level code (`cipher/pubkey.c'). Thus the internal interface between
+the algorithm modules and the high level functions passes data in a
+custom format. The interface to the modules is published
+(`gcrypt-modules.h') so that it can used to register external
+implementations of algorithms with Libgcrypt. However, for some
+algorithms this module interface is to limited and thus for the
+internal modules an extra interface is sometimes used to convey more
+information.
+
+ By default Libgcrypt uses a blinding technique for RSA decryption to
+mitigate real world timing attacks over a network: Instead of using the
+RSA decryption directly, a blinded value y = x r^e \bmod n is decrypted
+and the unblinded value x' = y' r^-1 \bmod n returned. The blinding
+value r is a random value with the size of the modulus n and generated
+with `GCRY_WEAK_RANDOM' random level.
+
+ The algorithm used for RSA and DSA key generation depends on whether
+Libgcrypt is operated in standard or in FIPS mode. In standard mode an
+algorithm based on the Lim-Lee prime number generator is used. In FIPS
+mode RSA keys are generated as specified in ANSI X9.31 (1998) and DSA
+keys as specified in FIPS 186-2.
+
+\1f
+File: gcrypt.info, Node: Symmetric Encryption Subsystem Architecture, Next: Hashing and MACing Subsystem Architecture, Prev: Public-Key Subsystem Architecture, Up: Architecture
+
+13.2 Symmetric Encryption Subsystem Architecture
+================================================
+
+The interface to work with symmetric encryption algorithms is made up
+of functions from the `gcry_cipher_' name space. The implementation
+follows the open-use-close paradigm and uses registered algorithm
+modules for the actual work. Unless a module implements optimized
+cipher mode implementations, the high level code (`cipher/cipher.c')
+implements the modes and calls the core algorithm functions to process
+each block.
+
+ The most important functions are:
+
+`gcry_cipher_open'
+ Create a new instance to encrypt or decrypt using a specified
+ algorithm and mode.
+
+`gcry_cipher_close'
+ Release an instance.
+
+`gcry_cipher_setkey'
+ Set a key to be used for encryption or decryption.
+
+`gcry_cipher_setiv'
+ Set an initialization vector to be used for encryption or
+ decryption.
+
+`gcry_cipher_encrypt'
+`gcry_cipher_decrypt'
+ Encrypt or decrypt data. These functions may be called with
+ arbitrary amounts of data and as often as needed to encrypt or
+ decrypt all data.
+
+
+ There are also functions to query properties of algorithms or
+context, like block length, key length, map names or to enable features
+like padding methods.
+
+\1f
+File: gcrypt.info, Node: Hashing and MACing Subsystem Architecture, Next: Multi-Precision-Integer Subsystem Architecture, Prev: Symmetric Encryption Subsystem Architecture, Up: Architecture
+
+13.3 Hashing and MACing Subsystem Architecture
+==============================================
+
+The interface to work with message digests and CRC algorithms is made
+up of functions from the `gcry_md_' name space. The implementation
+follows the open-use-close paradigm and uses registered algorithm
+modules for the actual work. Although CRC algorithms are not
+considered cryptographic hash algorithms, they share enough properties
+so that it makes sense to handle them in the same way. It is possible
+to use several algorithms at once with one context and thus compute
+them all on the same data.
+
+ The most important functions are:
+
+`gcry_md_open'
+ Create a new message digest instance and optionally enable one
+ algorithm. A flag may be used to turn the message digest algorithm
+ into a HMAC algorithm.
+
+`gcry_md_enable'
+ Enable an additional algorithm for the instance.
+
+`gcry_md_setkey'
+ Set the key for the MAC.
+
+`gcry_md_write'
+ Pass more data for computing the message digest to an instance.
+
+`gcry_md_putc'
+ Buffered version of `gcry_md_write' implemented as a macro.
+
+`gcry_md_read'
+ Finalize the computation of the message digest or HMAC and return
+ the result.
+
+`gcry_md_close'
+ Release an instance
+
+`gcry_md_hash_buffer'
+ Convenience function to directly compute a message digest over a
+ memory buffer without the need to create an instance first.
+
+
+ There are also functions to query properties of algorithms or the
+instance, like enabled algorithms, digest length, map algorithm names.
+it is also possible to reset an instance or to copy the current state
+of an instance at any time. Debug functions to write the hashed data
+to files are available as well.
+
+\1f
+File: gcrypt.info, Node: Multi-Precision-Integer Subsystem Architecture, Next: Prime-Number-Generator Subsystem Architecture, Prev: Hashing and MACing Subsystem Architecture, Up: Architecture
+
+13.4 Multi-Precision-Integer Subsystem Architecture
+===================================================
+
+The implementation of Libgcrypt's big integer computation code is based
+on an old release of GNU Multi-Precision Library (GMP). The decision
+not to use the GMP library directly was due to stalled development at
+that time and due to security requirements which could not be provided
+by the code in GMP. As GMP does, Libgcrypt provides high performance
+assembler implementations of low level code for several CPUS to gain
+much better performance than with a generic C implementation.
+
+Major features of Libgcrypt's multi-precision-integer code compared to
+GMP are:
+
+ * Avoidance of stack based allocations to allow protection against
+ swapping out of sensitive data and for easy zeroing of sensitive
+ intermediate results.
+
+ * Optional use of secure memory and tracking of its use so that
+ results are also put into secure memory.
+
+ * MPIs are identified by a handle (implemented as a pointer) to give
+ better control over allocations and to augment them with extra
+ properties like opaque data.
+
+ * Removal of unnecessary code to reduce complexity.
+
+ * Functions specialized for public key cryptography.
+
+
+\1f
+File: gcrypt.info, Node: Prime-Number-Generator Subsystem Architecture, Next: Random-Number Subsystem Architecture, Prev: Multi-Precision-Integer Subsystem Architecture, Up: Architecture
+
+13.5 Prime-Number-Generator Subsystem Architecture
+==================================================
+
+Libgcrypt provides an interface to its prime number generator. These
+functions make use of the internal prime number generator which is
+required for the generation for public key key pairs. The plain prime
+checking function is exported as well.
+
+ The generation of random prime numbers is based on the Lim and Lee
+algorithm to create practically save primes.(1) This algorithm creates
+a pool of smaller primes, select a few of them to create candidate
+primes of the form 2 * p_0 * p_1 * ... * p_n + 1, tests the candidate
+for primality and permutates the pool until a prime has been found. It
+is possible to clamp one of the small primes to a certain size to help
+DSA style algorithms. Because most of the small primes in the pool are
+not used for the resulting prime number, they are saved for later use
+(see `save_pool_prime' and `get_pool_prime' in `cipher/primegen.c').
+The prime generator optionally supports the finding of an appropriate
+generator.
+
+The primality test works in three steps:
+
+ 1. The standard sieve algorithm using the primes up to 4999 is used
+ as a quick first check.
+
+ 2. A Fermat test filters out almost all non-primes.
+
+ 3. A 5 round Rabin-Miller test is finally used. The first round uses
+ a witness of 2, whereas the next rounds use a random witness.
+
+
+ To support the generation of RSA and DSA keys in FIPS mode according
+to X9.31 and FIPS 186-2, Libgcrypt implements two additional prime
+generation functions: `_gcry_derive_x931_prime' and
+`_gcry_generate_fips186_2_prime'. These functions are internal and not
+available through the public API.
+
+ ---------- Footnotes ----------
+
+ (1) Chae Hoon Lim and Pil Joong Lee. A key recovery attack on
+discrete log-based shemes using a prime order subgroup. In Burton S.
+Kaliski Jr., editor, Advances in Cryptology: Crypto '97, pages
+249Â-263, Berlin / Heidelberg / New York, 1997. Springer-Verlag.
+Described on page 260.
+
+\1f
+File: gcrypt.info, Node: Random-Number Subsystem Architecture, Prev: Prime-Number-Generator Subsystem Architecture, Up: Architecture
+
+13.6 Random-Number Subsystem Architecture
+=========================================
+
+Libgcrypt provides 3 levels or random quality: The level
+`GCRY_VERY_STRONG_RANDOM' usually used for key generation, the level
+`GCRY_STRONG_RANDOM' for all other strong random requirements and the
+function `gcry_create_nonce' which is used for weaker usages like
+nonces. There is also a level `GCRY_WEAK_RANDOM' which in general maps
+to `GCRY_STRONG_RANDOM' except when used with the function
+`gcry_mpi_randomize', where it randomizes an multi-precision-integer
+using the `gcry_create_nonce' function.
+
+There are two distinct random generators available:
+
+ * The Continuously Seeded Pseudo Random Number Generator (CSPRNG),
+ which is based on the classic GnuPG derived big pool
+ implementation. Implemented in `random/random-csprng.c' and used
+ by default.
+
+ * A FIPS approved ANSI X9.31 PRNG using AES with a 128 bit key.
+ Implemented in `random/random-fips.c' and used if Libgcrypt is in
+ FIPS mode.
+
+Both generators make use of so-called entropy gathering modules:
+
+rndlinux
+ Uses the operating system provided `/dev/random' and
+ `/dev/urandom' devices.
+
+rndunix
+ Runs several operating system commands to collect entropy from
+ sources like virtual machine and process statistics. It is a kind
+ of poor-man's `/dev/random' implementation. It is not available in
+ FIPS mode.
+
+rndegd
+ Uses the operating system provided Entropy Gathering Daemon (EGD).
+ The EGD basically uses the same algorithms as rndunix does.
+ However as a system daemon it keeps on running and thus can serve
+ several processes requiring entropy input and does not waste
+ collected entropy if the application does not need all the
+ collected entropy. It is not available in FIPS mode.
+
+rndw32
+ Targeted for the Microsoft Windows OS. It uses certain properties
+ of that system and is the only gathering module available for that
+ OS.
+
+rndhw
+ Extra module to collect additional entropy by utilizing a hardware
+ random number generator. As of now the only supported hardware
+ RNG is the Padlock engine of VIA (Centaur) CPUs. It is not
+ available in FIPS mode.
+
+
+* Menu:
+
+* CSPRNG Description:: Description of the CSPRNG.
+* FIPS PRNG Description:: Description of the FIPS X9.31 PRNG.
+
+\1f
+File: gcrypt.info, Node: CSPRNG Description, Next: FIPS PRNG Description, Up: Random-Number Subsystem Architecture
+
+13.6.1 Description of the CSPRNG
+--------------------------------
+
+This random number generator is loosely modelled after the one
+described in Peter Gutmann's paper: "Software Generation of Practically
+Strong Random Numbers".(1)
+
+ A pool of 600 bytes is used and mixed using the core RIPE-MD160 hash
+transform function. Several extra features are used to make the robust
+against a wide variety of attacks and to protect against failures of
+subsystems. The state of the generator may be saved to a file and
+initially seed form a file.
+
+ Depending on how Libgcrypt was build the generator is able to select
+the best working entropy gathering module. It makes use of the slow
+and fast collection methods and requires the pool to initially seeded
+form the slow gatherer or a seed file. An entropy estimation is used
+to mix in enough data from the gather modules before returning the
+actual random output. Process fork detection and protection is
+implemented.
+
+ The implementation of the nonce generator (for `gcry_create_nonce')
+is a straightforward repeated hash design: A 28 byte buffer is
+initially seeded with the PID and the time in seconds in the first 20
+bytes and with 8 bytes of random taken from the `GCRY_STRONG_RANDOM'
+generator. Random numbers are then created by hashing all the 28 bytes
+with SHA-1 and saving that again in the first 20 bytes. The hash is
+also returned as result.
+
+ ---------- Footnotes ----------
+
+ (1) Also described in chapter 6 of his book "Cryptographic Security
+Architecture", New York, 2004, ISBN 0-387-95387-6.
+
+\1f
+File: gcrypt.info, Node: FIPS PRNG Description, Prev: CSPRNG Description, Up: Random-Number Subsystem Architecture
+
+13.6.2 Description of the FIPS X9.31 PRNG
+-----------------------------------------
+
+The core of this deterministic random number generator is implemented
+according to the document "NIST-Recommended Random Number Generator
+Based on ANSI X9.31 Appendix A.2.4 Using the 3-Key Triple DES and AES
+Algorithms", dated 2005-01-31. This implementation uses the AES
+variant.
+
+ The generator is based on contexts to utilize the same core functions
+for all random levels as required by the high-level interface. All
+random generators return their data in 128 bit blocks. If the caller
+requests less bits, the extra bits are not used. The key for each
+generator is only set once at the first time a generator context is
+used. The seed value is set along with the key and again after 1000
+output blocks.
+
+ On Unix like systems the `GCRY_VERY_STRONG_RANDOM' and
+`GCRY_STRONG_RANDOM' generators are keyed and seeded using the rndlinux
+module with the `/dev/radnom' device. Thus these generators may block
+until the OS kernel has collected enough entropy. When used with
+Microsoft Windows the rndw32 module is used instead.
+
+ The generator used for `gcry_create_nonce' is keyed and seeded from
+the `GCRY_STRONG_RANDOM' generator. Thus is may also block if the
+`GCRY_STRONG_RANDOM' generator has not yet been used before and thus
+gets initialized on the first use by `gcry_create_nonce'. This special
+treatment is justified by the weaker requirements for a nonce generator
+and to save precious kernel entropy for use by the "real" random
+generators.
+
+ A self-test facility uses a separate context to check the
+functionality of the core X9.31 functions using a known answers test.
+During runtime each output block is compared to the previous one to
+detect a stucked generator.
+
+ The DT value for the generator is made up of the current time down to
+microseconds (if available) and a free running 64 bit counter. When
+used with the test context the DT value is taken from the context and
+incremented on each use.
+
+\1f
+File: gcrypt.info, Node: Self-Tests, Next: FIPS Mode, Prev: Architecture, Up: Top
+
+Appendix A Description of the Self-Tests
+****************************************
+
+In addition to the build time regression test suite, Libgcrypt
+implements self-tests to be performed at runtime. Which self-tests are
+actually used depends on the mode Libgcrypt is used in. In standard
+mode a limited set of self-tests is run at the time an algorithm is
+first used. Note that not all algorithms feature a self-test in
+standard mode. The `GCRYCTL_SELFTEST' control command may be used to
+run all implemented self-tests at any time; this will even run more
+tests than those run in FIPS mode.
+
+ If any of the self-tests fails, the library immediately returns an
+error code to the caller. If Libgcrypt is in FIPS mode the self-tests
+will be performed within the "Self-Test" state and any failure puts the
+library into the "Error" state.
+
+A.1 Power-Up Tests
+==================
+
+Power-up tests are only performed if Libgcrypt is in FIPS mode.
+
+A.1.1 Symmetric Cipher Algorithm Power-Up Tests
+-----------------------------------------------
+
+The following symmetric encryption algorithm tests are run during
+power-up:
+
+3DES
+ To test the 3DES 3-key EDE encryption in ECB mode these tests are
+ run:
+ 1. A known answer test is run on a 64 bit test vector processed
+ by 64 rounds of Single-DES block encryption and decryption
+ using a key changed with each round.
+
+ 2. A known answer test is run on a 64 bit test vector processed
+ by 16 rounds of 2-key and 3-key Triple-DES block encryption
+ and decryptions using a key changed with each round.
+
+ 3. 10 known answer tests using 3-key Triple-DES EDE encryption,
+ comparing the ciphertext to the known value, then running a
+ decryption and comparing it to the initial plaintext.
+ (`cipher/des.c:selftest')
+
+AES-128
+ A known answer tests is run using one test vector and one test key
+ with AES in ECB mode. (`cipher/rijndael.c:selftest_basic_128')
+
+AES-192
+ A known answer tests is run using one test vector and one test key
+ with AES in ECB mode. (`cipher/rijndael.c:selftest_basic_192')
+
+AES-256
+ A known answer tests is run using one test vector and one test key
+ with AES in ECB mode. (`cipher/rijndael.c:selftest_basic_256')
+
+A.1.2 Hash Algorithm Power-Up Tests
+-----------------------------------
+
+The following hash algorithm tests are run during power-up:
+
+SHA-1
+ A known answer test using the string `"abc"' is run.
+ (`cipher/sha1.c:selftests_sha1')
+
+SHA-224
+ A known answer test using the string `"abc"' is run.
+ (`cipher/sha256.c:selftests_sha224')
+
+SHA-256
+ A known answer test using the string `"abc"' is run.
+ (`cipher/sha256.c:selftests_sha256')
+
+SHA-384
+ A known answer test using the string `"abc"' is run.
+ (`cipher/sha512.c:selftests_sha384')
+
+SHA-512
+ A known answer test using the string `"abc"' is run.
+ (`cipher/sha512.c:selftests_sha512')
+
+A.1.3 MAC Algorithm Power-Up Tests
+----------------------------------
+
+The following MAC algorithm tests are run during power-up:
+
+HMAC SHA-1
+ A known answer test using 9 byte of data and a 64 byte key is run.
+ (`cipher/hmac-tests.c:selftests_sha1')
+
+HMAC SHA-224
+ A known answer test using 28 byte of data and a 4 byte key is run.
+ (`cipher/hmac-tests.c:selftests_sha224')
+
+HMAC SHA-256
+ A known answer test using 28 byte of data and a 4 byte key is run.
+ (`cipher/hmac-tests.c:selftests_sha256')
+
+HMAC SHA-384
+ A known answer test using 28 byte of data and a 4 byte key is run.
+ (`cipher/hmac-tests.c:selftests_sha384')
+
+HMAC SHA-512
+ A known answer test using 28 byte of data and a 4 byte key is run.
+ (`cipher/hmac-tests.c:selftests_sha512')
+
+A.1.4 Random Number Power-Up Test
+---------------------------------
+
+The DRNG is tested during power-up this way:
+
+ 1. Requesting one block of random using the public interface to check
+ general working and the duplicated block detection.
+
+ 2. 3 know answer tests using pre-defined keys, seed and initial DT
+ values. For each test 3 blocks of 16 bytes are requested and
+ compared to the expected result. The DT value is incremented for
+ each block.
+
+A.1.5 Public Key Algorithm Power-Up Tests
+-----------------------------------------
+
+The public key algorithms are tested during power-up:
+
+RSA
+ A pre-defined 1024 bit RSA key is used and these tests are run in
+ turn:
+ 1. Conversion of S-expression to internal format.
+ (`cipher/rsa.c:selftests_rsa')
+
+ 2. Private key consistency check. (`cipher/rsa.c:selftests_rsa')
+
+ 3. A pre-defined 20 byte value is signed with PKCS#1 padding for
+ SHA-1. The result is verified using the public key against
+ the original data and against modified data.
+ (`cipher/rsa.c:selftest_sign_1024')
+
+ 4. A 1000 bit random value is encrypted and checked that it does
+ not match the orginal random value. The encrtypted result is
+ then decrypted and checked that it macthes the original
+ random value. (`cipher/rsa.c:selftest_encr_1024')
+
+DSA
+ A pre-defined 1024 bit DSA key is used and these tests are run in
+ turn:
+ 1. Conversion of S-expression to internal format.
+ (`cipher/dsa.c:selftests_dsa')
+
+ 2. Private key consistency check. (`cipher/dsa.c:selftests_dsa')
+
+ 3. A pre-defined 20 byte value is signed with PKCS#1 padding for
+ SHA-1. The result is verified using the public key against
+ the original data and against modified data.
+ (`cipher/dsa.c:selftest_sign_1024')
+
+A.1.6 Integrity Power-Up Tests
+------------------------------
+
+The integrity of the Libgcrypt is tested during power-up but only if
+checking has been enabled at build time. The check works by computing
+a HMAC SHA-256 checksum over the file used to load Libgcrypt into
+memory. That checksum is compared against a checksum stored in a file
+of the same name but with a single dot as a prefix and a suffix of
+`.hmac'.
+
+A.1.7 Critical Functions Power-Up Tests
+---------------------------------------
+
+The 3DES weak key detection is tested during power-up by calling the
+detection function with keys taken from a table listening all weak
+keys. The table itself is protected using a SHA-1 hash.
+(`cipher/des.c:selftest')
+
+A.2 Conditional Tests
+=====================
+
+The conditional tests are performed if a certain contidion is met.
+This may occur at any time; the library does not necessary enter the
+"Self-Test" state to run these tests but will transit to the "Error"
+state if a test failed.
+
+A.2.1 Key-Pair Generation Tests
+-------------------------------
+
+After an asymmetric key-pair has been generated, Libgcrypt runs a
+pair-wise consistency tests on the generated key. On failure the
+generated key is not used, an error code is returned and, if in FIPS
+mode, the library is put into the "Error" state.
+
+RSA
+ The test uses a random number 64 bits less the size of the modulus
+ as plaintext and runs an encryption and decryption operation in
+ turn. The encrypted value is checked to not match the plaintext
+ and the result of the decryption is checked to match the plaintext.
+
+ A new random number of the same size is generated, signed and
+ verified to test the correctness of the signing operation. As a
+ second signing test, the signature is modified by incrementing its
+ value and then verified with the expected result that the
+ verification fails. (`cipher/rsa.c:test_keys')
+
+DSA
+ The test uses a random number of the size of the Q parameter to
+ create a signature and then checks that the signature verifies.
+ As a second signing test, the data is modified by incrementing its
+ value and then verified against the signature with the expected
+ result that the verification fails. (`cipher/dsa.c:test_keys')
+
+A.2.2 Software Load Tests
+-------------------------
+
+Loading of extra modules into libgcrypt is disabled in FIPS mode and
+thus no tests are implemented. (`cipher/cipher.c:gcry_cipher_register',
+`cipher/md.c:gcry_md_register', `cipher/md.c:gcry_pk_register')
+
+A.2.3 Manual Key Entry Tests
+----------------------------
+
+A manual key entry feature is not implemented in Libgcrypt.
+
+A.2.4 Continuous RNG Tests
+--------------------------
+
+The continuous random number test is only used in FIPS mode. The RNG
+generates blocks of 128 bit size; the first block generated per context
+is saved in the context and another block is generated to be returned
+to the caller. Each block is compared against the saved block and then
+stored in the context. If a duplicated block is detected an error is
+signaled and the libray is put into the "Fatal-Error" state.
+(`random/random-fips.c:x931_aes_driver')
+
+A.3 Application Requested Tests
+===============================
+
+The application may requests tests at any time by means of the
+`GCRYCTL_SELFTEST' control command. Note that using these tests is not
+FIPS conform: Although Libgcrypt rejects all application requests for
+services while running self-tests, it does not ensure that no other
+operations of Libgcrypt are still being executed. Thus, in FIPS mode
+an application requesting self-tests needs to power-cycle Libgcrypt
+instead.
+
+ When self-tests are requested, Libgcrypt runs all the tests it does
+during power-up as well as a few extra checks as described below.
+
+A.3.1 Symmetric Cipher Algorithm Tests
+--------------------------------------
+
+The following symmetric encryption algorithm tests are run in addition
+to the power-up tests:
+
+AES-128
+ A known answer tests with test vectors taken from NIST SP800-38a
+ and using the high level functions is run for block modes CFB and
+ OFB.
+
+
+A.3.2 Hash Algorithm Tests
+--------------------------
+
+The following hash algorithm tests are run in addition to the power-up
+tests:
+
+SHA-1
+SHA-224
+SHA-256
+ 1. A known answer test using a 56 byte string is run.
+
+ 2. A known answer test using a string of one million letters "a"
+ is run.
+ (`cipher/sha1.c:selftests_sha1',
+ `cipher/sha256.c:selftests_sha224',
+ `cipher/sha256.c:selftests_sha256')
+
+SHA-384
+
+SHA-512
+ 1. A known answer test using a 112 byte string is run.
+
+ 2. A known answer test using a string of one million letters "a"
+ is run.
+ (`cipher/sha512.c:selftests_sha384',
+ `cipher/sha512.c:selftests_sha512')
+
+A.3.3 MAC Algorithm Tests
+-------------------------
+
+The following MAC algorithm tests are run in addition to the power-up
+tests:
+
+HMAC SHA-1
+ 1. A known answer test using 9 byte of data and a 20 byte key is
+ run.
+
+ 2. A known answer test using 9 byte of data and a 100 byte key
+ is run.
+
+ 3. A known answer test using 9 byte of data and a 49 byte key is
+ run.
+ (`cipher/hmac-tests.c:selftests_sha1')
+
+HMAC SHA-224
+HMAC SHA-256
+HMAC SHA-384
+HMAC SHA-512
+ 1. A known answer test using 9 byte of data and a 20 byte key is
+ run.
+
+ 2. A known answer test using 50 byte of data and a 20 byte key
+ is run.
+
+ 3. A known answer test using 50 byte of data and a 26 byte key
+ is run.
+
+ 4. A known answer test using 54 byte of data and a 131 byte key
+ is run.
+
+ 5. A known answer test using 152 byte of data and a 131 byte key
+ is run.
+ (`cipher/hmac-tests.c:selftests_sha224',
+ `cipher/hmac-tests.c:selftests_sha256',
+ `cipher/hmac-tests.c:selftests_sha384',
+ `cipher/hmac-tests.c:selftests_sha512')
+
+\1f
+File: gcrypt.info, Node: FIPS Mode, Next: Library Copying, Prev: Self-Tests, Up: Top
+
+Appendix B Description of the FIPS Mode
+***************************************
+
+This appendix gives detailed information pertaining to the FIPS mode.
+In particular, the changes to the standard mode and the finite state
+machine are described. The self-tests required in this mode are
+described in the appendix on self-tests.
+
+B.1 Restrictions in FIPS Mode
+=============================
+
+If Libgcrypt is used in FIPS mode these restrictions are effective:
+
+ * The cryptographic algorithms are restricted to this list:
+
+ GCRY_CIPHER_3DES
+ 3 key EDE Triple-DES symmetric encryption.
+
+ GCRY_CIPHER_AES128
+ AES 128 bit symmetric encryption.
+
+ GCRY_CIPHER_AES192
+ AES 192 bit symmetric encryption.
+
+ GCRY_CIPHER_AES256
+ AES 256 bit symmetric encryption.
+
+ GCRY_MD_SHA1
+ SHA-1 message digest.
+
+ GCRY_MD_SHA224
+ SHA-224 message digest.
+
+ GCRY_MD_SHA256
+ SHA-256 message digest.
+
+ GCRY_MD_SHA384
+ SHA-384 message digest.
+
+ GCRY_MD_SHA512
+ SHA-512 message digest.
+
+ GCRY_MD_SHA1,GCRY_MD_FLAG_HMAC
+ HMAC using a SHA-1 message digest.
+
+ GCRY_MD_SHA224,GCRY_MD_FLAG_HMAC
+ HMAC using a SHA-224 message digest.
+
+ GCRY_MD_SHA256,GCRY_MD_FLAG_HMAC
+ HMAC using a SHA-256 message digest.
+
+ GCRY_MD_SHA384,GCRY_MD_FLAG_HMAC
+ HMAC using a SHA-384 message digest.
+
+ GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC
+ HMAC using a SHA-512 message digest.
+
+ GCRY_PK_RSA
+ RSA encryption and signing.
+
+ GCRY_PK_DSA
+ DSA signing.
+
+ Note that the CRC algorithms are not considered cryptographic
+ algorithms and thus are in addition available.
+
+ * RSA key generation refuses to create a key with a keysize of less
+ than 1024 bits.
+
+ * DSA key generation refuses to create a key with a keysize other
+ than 1024 bits.
+
+ * The `transient-key' flag for RSA and DSA key generation is ignored.
+
+ * Support for the VIA Padlock engine is disabled.
+
+ * FIPS mode may only be used on systems with a /dev/random device.
+ Switching into FIPS mode on other systems will fail at runtime.
+
+ * Saving and loading a random seed file is ignored.
+
+ * An X9.31 style random number generator is used in place of the
+ large-pool-CSPRNG generator.
+
+ * The command `GCRYCTL_ENABLE_QUICK_RANDOM' is ignored.
+
+ * The Alternative Public Key Interface (`gcry_ac_xxx') is not
+ supported and all API calls return an error.
+
+ * Registration of external modules is not supported.
+
+ * Message digest debugging is disabled.
+
+ * All debug output related to cryptographic data is suppressed.
+
+ * On-the-fly self-tests are not performed, instead self-tests are run
+ before entering operational state.
+
+ * The function `gcry_set_allocation_handler' may not be used. If it
+ is used Libgcrypt disables FIPS mode unless Enforced FIPS mode is
+ enabled, in which case Libgcrypt will enter the error state.
+
+ * The digest algorithm MD5 may not be used. If it is used Libgcrypt
+ disables FIPS mode unless Enforced FIPS mode is enabled, in which
+ case Libgcrypt will enter the error state.
+
+ * In Enforced FIPS mode the command `GCRYCTL_DISABLE_SECMEM' is
+ ignored. In standard FIPS mode it disables FIPS mode.
+
+ * A handler set by `gcry_set_outofcore_handler' is ignored.
+
+ * A handler set by `gcry_set_fatalerror_handler' is ignored.
+
+
+ Note that when we speak about disabling FIPS mode, it merely means
+that the function `gcry_fips_mode_active' returns false; it does not
+mean that any non FIPS algorithms are allowed.
+
+B.2 FIPS Finite State Machine
+=============================
+
+The FIPS mode of libgcrypt implements a finite state machine (FSM) using
+8 states (*note tbl:fips-states::) and checks at runtime that only valid
+transitions (*note tbl:fips-state-transitions::) may happen.
+
+ \0\b[image src="fips-fsm.png" alt="FIPS FSM Diagram"\0\b]
+Figure B.1: FIPS mode state diagram
+
+States used by the FIPS FSM:
+Power-Off
+ Libgcrypt is not runtime linked to another application. This
+ usually means that the library is not loaded into main memory.
+ This state is documentation only.
+
+Power-On
+ Libgcrypt is loaded into memory and API calls may be made.
+ Compiler introducted constructor functions may be run. Note that
+ Libgcrypt does not implement any arbitrary constructor functions
+ to be called by the operating system
+
+Init
+ The Libgcrypt initialization functions are performed and the
+ library has not yet run any self-test.
+
+Self-Test
+ Libgcrypt is performing self-tests.
+
+Operational
+ Libgcrypt is in the operational state and all interfaces may be
+ used.
+
+Error
+ Libgrypt is in the error state. When calling any FIPS relevant
+ interfaces they either return an error (`GPG_ERR_NOT_OPERATIONAL')
+ or put Libgcrypt into the Fatal-Error state and won't return.
+
+Fatal-Error
+ Libgcrypt is in a non-recoverable error state and will
+ automatically transit into the Shutdown state.
+
+Shutdown
+ Libgcrypt is about to be terminated and removed from the memory.
+ The application may at this point still runing cleanup handlers.
+
+
+Table B.1: FIPS mode states
+
+The valid state transitions (*note Figure B.1: fig:fips-fsm.) are:
+`1'
+ Power-Off to Power-On is implicitly done by the OS loading
+ Libgcrypt as a shared library and having it linked to an
+ application.
+
+`2'
+ Power-On to Init is triggered by the application calling the
+ Libgcrypt intialization function `gcry_check_version'.
+
+`3'
+ Init to Self-Test is either triggred by a dedicated API call or
+ implicit by invoking a libgrypt service conrolled by the FSM.
+
+`4'
+ Self-Test to Operational is triggered after all self-tests passed
+ successfully.
+
+`5'
+ Operational to Shutdown is an artifical state without any direct
+ action in Libgcrypt. When reaching the Shutdown state the library
+ is deinitialized and can't return to any other state again.
+
+`6'
+ Shutdown to Power-off is the process of removing Libgcrypt from the
+ computer's memory. For obvious reasons the Power-Off state can't
+ be represented within Libgcrypt and thus this transition is for
+ documentation only.
+
+`7'
+ Operational to Error is triggered if Libgcrypt detected an
+ application error which can't be returned to the caller but still
+ allows Libgcrypt to properly run. In the Error state all FIPS
+ relevant interfaces return an error code.
+
+`8'
+ Error to Shutdown is similar to the Operational to Shutdown
+ transition (5).
+
+`9'
+ Error to Fatal-Error is triggred if Libgrypt detects an fatal error
+ while already being in Error state.
+
+`10'
+ Fatal-Error to Shutdown is automatically entered by Libgcrypt
+ after having reported the error.
+
+`11'
+ Power-On to Shutdown is an artifical state to document that
+ Libgcrypt has not ye been initializaed but the process is about to
+ terminate.
+
+`12'
+ Power-On to Fatal-Error will be triggerd if certain Libgcrypt
+ functions are used without having reached the Init state.
+
+`13'
+ Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt
+ while running self-tests.
+
+`14'
+ Self-Test to Error is triggred by a failed self-test.
+
+`15'
+ Operational to Fatal-Error is triggered if Libcrypt encountered a
+ non-recoverable error.
+
+`16'
+ Operational to Self-Test is triggred if the application requested
+ to run the self-tests again.
+
+`17'
+ Error to Self-Test is triggered if the application has requested
+ to run self-tests to get to get back into operational state after
+ an error.
+
+`18'
+ Init to Error is triggered by errors in the initialization code.
+
+`19'
+ Init to Fatal-Error is triggered by non-recoverable errors in the
+ initialization code.
+
+`20'
+ Error to Error is triggered by errors while already in the Error
+ state.
+
+
+Table B.2: FIPS mode state transitions
+
+B.3 FIPS Miscellaneous Information
+==================================
+
+Libgcrypt does not do any key management on itself; the application
+needs to care about it. Keys which are passed to Libgcrypt should be
+allocated in secure memory as available with the functions
+`gcry_malloc_secure' and `gcry_calloc_secure'. By calling `gcry_free'
+on this memory, the memory and thus the keys are overwritten with zero
+bytes before releasing the memory.
+
+ For use with the random number generator, Libgcrypt generates 3
+internal keys which are stored in the encryption contexts used by the
+RNG. These keys are stored in secure memory for the lifetime of the
+process. Application are required to use `GCRYCTL_TERM_SECMEM' before
+process termination. This will zero out the entire secure memory and
+thus also the encryption contexts with these keys.
+
+\1f
+File: gcrypt.info, Node: Library Copying, Next: Copying, Prev: FIPS Mode, Up: Top
+
+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.]
+
+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
+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!
+
+\1f
+File: gcrypt.info, Node: Copying, Next: Figures and Tables, Prev: Library Copying, Up: Top
+
+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.
+
+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.
+
+\1f
+File: gcrypt.info, Node: Figures and Tables, Next: Concept Index, Prev: Copying, Up: Top
+
+List of Figures and Tables
+**************************
+
+* Menu:
+
+* Figure 13.1: Libgcrypt subsystems: fig:subsystems.
+* Figure B.1: FIPS mode state ...: fig:fips-fsm.
+
+* Menu:
+
+* Table B.1: FIPS mode states: tbl:fips-states.
+* Table B.2: FIPS mode state ...: tbl:fips-state-transitions.
+
+\1f
+File: gcrypt.info, Node: Concept Index, Next: Function and Data Index, Prev: Figures and Tables, Up: Top
+
+Concept Index
+*************
+
+\0\b[index\0\b]
+* Menu:
+
+* 3DES: Available ciphers. (line 16)
+* Advanced Encryption Standard: Available ciphers. (line 37)
+* AES: Available ciphers. (line 37)
+* Arcfour: Available ciphers. (line 54)
+* Blowfish: Available ciphers. (line 24)
+* Camellia: Available ciphers. (line 81)
+* CAST5: Available ciphers. (line 21)
+* CBC, Cipher Block Chaining mode: Available cipher modes.
+ (line 20)
+* CBC-MAC: Working with cipher handles.
+ (line 52)
+* CFB, Cipher Feedback mode: Available cipher modes.
+ (line 16)
+* cipher text stealing: Working with cipher handles.
+ (line 45)
+* CRC32: Available hash algorithms.
+ (line 6)
+* CTR, Counter mode: Available cipher modes.
+ (line 29)
+* DES: Available ciphers. (line 59)
+* DES-EDE: Available ciphers. (line 16)
+* Digital Encryption Standard: Available ciphers. (line 16)
+* ECB, Electronic Codebook mode: Available cipher modes.
+ (line 13)
+* Enforced FIPS mode: Enabling FIPS mode. (line 30)
+* 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)
+* FIPS 140: Enabling FIPS mode. (line 6)
+* FIPS 186 <1>: Public-Key Subsystem Architecture.
+ (line 63)
+* FIPS 186: General public-key related Functions.
+ (line 256)
+* FIPS mode: Enabling FIPS mode. (line 6)
+* GPL, GNU General Public License: Copying. (line 6)
+* HAVAL: Available hash algorithms.
+ (line 6)
+* HMAC: Working with hash algorithms.
+ (line 27)
+* IDEA: Available ciphers. (line 11)
+* LGPL, GNU Lesser General Public License: Library Copying. (line 6)
+* MD2, MD4, MD5: Available hash algorithms.
+ (line 6)
+* OFB, Output Feedback mode: Available cipher modes.
+ (line 26)
+* RC2: Available ciphers. (line 71)
+* RC4: Available ciphers. (line 54)
+* rfc-2268: Available ciphers. (line 71)
+* Rijndael: Available ciphers. (line 37)
+* RIPE-MD-160: Available hash algorithms.
+ (line 6)
+* Seed (cipher): Available ciphers. (line 76)
+* Serpent: Available ciphers. (line 67)
+* SHA-1: Available hash algorithms.
+ (line 6)
+* SHA-224, SHA-256, SHA-384, SHA-512: Available hash algorithms.
+ (line 6)
+* sync mode (OpenPGP): Working with cipher handles.
+ (line 40)
+* TIGER: Available hash algorithms.
+ (line 6)
+* Triple-DES: Available ciphers. (line 16)
+* Twofish: Available ciphers. (line 48)
+* Whirlpool: Available hash algorithms.
+ (line 6)
+* X9.31 <1>: Public-Key Subsystem Architecture.
+ (line 63)
+* X9.31: General public-key related Functions.
+ (line 249)
+
+\1f
+File: gcrypt.info, Node: Function and Data Index, Prev: Concept Index, Up: Top
+
+Function and Data Index
+***********************
+
+\0\b[index\0\b]
+* Menu:
+
+* AM_PATH_LIBGCRYPT: Building sources using Automake.
+ (line 13)
+* gcry_ac_close: Working with handles.
+ (line 21)
+* gcry_ac_data_clear: Working with sets of data.
+ (line 75)
+* gcry_ac_data_copy: Working with sets of data.
+ (line 53)
+* gcry_ac_data_decode: Using cryptographic functions.
+ (line 100)
+* gcry_ac_data_decrypt: Using cryptographic functions.
+ (line 40)
+* gcry_ac_data_decrypt_scheme: Using cryptographic functions.
+ (line 137)
+* gcry_ac_data_destroy: Working with sets of data.
+ (line 41)
+* gcry_ac_data_encode: Using cryptographic functions.
+ (line 93)
+* gcry_ac_data_encrypt: Using cryptographic functions.
+ (line 33)
+* gcry_ac_data_encrypt_scheme: Using cryptographic functions.
+ (line 127)
+* gcry_ac_data_from_sexp: Working with sets of data.
+ (line 93)
+* gcry_ac_data_get_index: Working with sets of data.
+ (line 69)
+* gcry_ac_data_get_name: Working with sets of data.
+ (line 61)
+* gcry_ac_data_length: Working with sets of data.
+ (line 57)
+* gcry_ac_data_new: Working with sets of data.
+ (line 38)
+* gcry_ac_data_set: Working with sets of data.
+ (line 45)
+* gcry_ac_data_sign: Using cryptographic functions.
+ (line 48)
+* gcry_ac_data_sign_scheme: Using cryptographic functions.
+ (line 147)
+* gcry_ac_data_t: Working with sets of data.
+ (line 20)
+* gcry_ac_data_to_sexp: Working with sets of data.
+ (line 79)
+* gcry_ac_data_verify: Using cryptographic functions.
+ (line 54)
+* gcry_ac_data_verify_scheme: Using cryptographic functions.
+ (line 157)
+* gcry_ac_id_t: Available asymmetric algorithms.
+ (line 11)
+* gcry_ac_id_to_name: Handle-independent functions.
+ (line 10)
+* gcry_ac_io_init: Working with IO objects.
+ (line 22)
+* gcry_ac_io_init_va: Working with IO objects.
+ (line 28)
+* gcry_ac_io_t: Working with IO objects.
+ (line 10)
+* gcry_ac_key_data_get: Working with keys. (line 93)
+* gcry_ac_key_destroy: Working with keys. (line 86)
+* gcry_ac_key_get_grip: Working with keys. (line 105)
+* gcry_ac_key_get_nbits: Working with keys. (line 101)
+* gcry_ac_key_init: Working with keys. (line 30)
+* gcry_ac_key_pair_destroy: Working with keys. (line 90)
+* gcry_ac_key_pair_extract: Working with keys. (line 83)
+* 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 97)
+* gcry_ac_key_type_t: Working with keys. (line 7)
+* gcry_ac_name_to_id: Handle-independent functions.
+ (line 15)
+* gcry_ac_open: Working with handles.
+ (line 11)
+* gcry_calloc: Memory allocation. (line 15)
+* gcry_calloc_secure: Memory allocation. (line 21)
+* gcry_check_version: Initializing the library.
+ (line 17)
+* gcry_cipher_algo_info: General cipher functions.
+ (line 12)
+* gcry_cipher_algo_name: General cipher functions.
+ (line 39)
+* gcry_cipher_close: Working with cipher handles.
+ (line 59)
+* gcry_cipher_ctl: Working with cipher handles.
+ (line 157)
+* gcry_cipher_decrypt: Working with cipher handles.
+ (line 127)
+* gcry_cipher_decrypt_t: Cipher modules. (line 80)
+* gcry_cipher_encrypt: Working with cipher handles.
+ (line 108)
+* gcry_cipher_encrypt_t: Cipher modules. (line 75)
+* gcry_cipher_info: Working with cipher handles.
+ (line 166)
+* 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 95)
+* gcry_cipher_setctr: Working with cipher handles.
+ (line 88)
+* gcry_cipher_setiv: Working with cipher handles.
+ (line 81)
+* gcry_cipher_setkey: Working with cipher handles.
+ (line 66)
+* 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 147)
+* gcry_cipher_unregister: Cipher modules. (line 101)
+* gcry_control: Controlling the library.
+ (line 7)
+* gcry_create_nonce: Retrieving random numbers.
+ (line 26)
+* 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_fips_mode_active: Controlling the library.
+ (line 221)
+* gcry_free: Memory allocation. (line 31)
+* gcry_handler_alloc_t: Allocation handler. (line 12)
+* gcry_handler_error_t: Error handler. (line 27)
+* gcry_handler_free_t: Allocation handler. (line 24)
+* gcry_handler_log_t: Logging handler. (line 7)
+* gcry_handler_no_mem_t: Error handler. (line 11)
+* 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_malloc: Memory allocation. (line 7)
+* gcry_malloc_secure: Memory allocation. (line 12)
+* gcry_md_algo_name: Working with hash algorithms.
+ (line 152)
+* gcry_md_close: Working with hash algorithms.
+ (line 61)
+* gcry_md_copy: Working with hash algorithms.
+ (line 82)
+* gcry_md_debug: Working with hash algorithms.
+ (line 216)
+* gcry_md_enable: Working with hash algorithms.
+ (line 44)
+* gcry_md_final: Working with hash algorithms.
+ (line 110)
+* gcry_md_final_t: Hash algorithm modules.
+ (line 73)
+* gcry_md_get_algo: Working with hash algorithms.
+ (line 196)
+* gcry_md_get_algo_dlen: Working with hash algorithms.
+ (line 187)
+* gcry_md_get_asnoid: Working with hash algorithms.
+ (line 168)
+* gcry_md_hash_buffer: Working with hash algorithms.
+ (line 135)
+* gcry_md_init_t: Hash algorithm modules.
+ (line 65)
+* gcry_md_is_enabled: Working with hash algorithms.
+ (line 207)
+* gcry_md_is_secure: Working with hash algorithms.
+ (line 202)
+* gcry_md_list: Hash algorithm modules.
+ (line 91)
+* gcry_md_map_name: Working with hash algorithms.
+ (line 158)
+* 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 100)
+* gcry_md_read: Working with hash algorithms.
+ (line 120)
+* 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 70)
+* gcry_md_setkey: Working with hash algorithms.
+ (line 53)
+* gcry_md_spec_t: Hash algorithm modules.
+ (line 12)
+* gcry_md_start_debug: Working with hash algorithms.
+ (line 230)
+* gcry_md_stop_debug: Working with hash algorithms.
+ (line 238)
+* gcry_md_test_algo: Working with hash algorithms.
+ (line 181)
+* gcry_md_unregister: Hash algorithm modules.
+ (line 87)
+* gcry_md_write: Working with hash algorithms.
+ (line 95)
+* 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 54)
+* 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 61)
+* 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_lshift: Bit manipulations. (line 34)
+* 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 47)
+* 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 100)
+* 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 115)
+* gcry_pk_get_keygrip: General public-key related Functions.
+ (line 29)
+* gcry_pk_get_nbits: General public-key related Functions.
+ (line 24)
+* 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 16)
+* 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 20)
+* gcry_pk_testkey: General public-key related Functions.
+ (line 40)
+* 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_prime_check: Checking. (line 8)
+* gcry_prime_generate: Generation. (line 10)
+* gcry_prime_group_generator: Generation. (line 19)
+* gcry_prime_release_factors: Generation. (line 25)
+* gcry_random_bytes: Retrieving random numbers.
+ (line 13)
+* gcry_random_bytes_secure: Retrieving random numbers.
+ (line 19)
+* gcry_random_level_t: Quality of random numbers.
+ (line 9)
+* gcry_randomize: Retrieving random numbers.
+ (line 8)
+* gcry_realloc: Memory allocation. (line 24)
+* gcry_set_allocation_handler: Allocation handler. (line 34)
+* gcry_set_fatalerror_handler: Error handler. (line 32)
+* gcry_set_log_handler: Logging handler. (line 12)
+* gcry_set_outofcore_handler: Error handler. (line 16)
+* 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 184)
+* gcry_sexp_nth_string: Working with S-expressions.
+ (line 176)
+* 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)
+
+
+\1f
+Tag Table:
+Node: Top\7f773
+Node: Introduction\7f2990
+Node: Getting Started\7f3362
+Node: Features\7f4243
+Node: Overview\7f5027
+Node: Preparation\7f5658
+Node: Header\7f6515
+Node: Building sources\7f7585
+Node: Building sources using Automake\7f9499
+Node: Initializing the library\7f10681
+Ref: sample-use-suspend-secmem\7f13856
+Ref: sample-use-resume-secmem\7f14476
+Node: Multi-Threading\7f15372
+Ref: Multi-Threading-Footnote-1\7f19385
+Node: Enabling FIPS mode\7f19793
+Node: Generalities\7f21659
+Node: Controlling the library\7f21984
+Node: Modules\7f34151
+Node: Error Handling\7f34930
+Node: Error Values\7f37453
+Node: Error Sources\7f42393
+Node: Error Codes\7f44664
+Node: Error Strings\7f48149
+Node: Handler Functions\7f49332
+Node: Progress handler\7f49891
+Node: Allocation handler\7f51887
+Node: Error handler\7f53438
+Node: Logging handler\7f55005
+Node: Symmetric cryptography\7f55597
+Node: Available ciphers\7f56402
+Node: Cipher modules\7f58909
+Node: Available cipher modes\7f63433
+Node: Working with cipher handles\7f64312
+Node: General cipher functions\7f72515
+Node: Public Key cryptography\7f75033
+Node: Available algorithms\7f75948
+Node: Used S-expressions\7f76297
+Node: RSA key parameters\7f77409
+Node: DSA key parameters\7f78684
+Node: ECC key parameters\7f79342
+Node: Public key modules\7f81107
+Node: Cryptographic Functions\7f86691
+Node: General public-key related Functions\7f94178
+Node: AC Interface\7f106467
+Node: Available asymmetric algorithms\7f107602
+Node: Working with sets of data\7f108271
+Node: Working with IO objects\7f112773
+Node: Working with handles\7f115493
+Node: Working with keys\7f116440
+Node: Using cryptographic functions\7f120522
+Node: Handle-independent functions\7f127429
+Node: Hashing\7f128177
+Node: Available hash algorithms\7f128968
+Node: Hash algorithm modules\7f131205
+Node: Working with hash algorithms\7f135053
+Node: Random Numbers\7f146257
+Node: Quality of random numbers\7f146531
+Node: Retrieving random numbers\7f147215
+Node: S-expressions\7f148699
+Node: Data types for S-expressions\7f149341
+Node: Working with S-expressions\7f149665
+Node: MPI library\7f158598
+Node: Data types\7f159556
+Node: Basic functions\7f159750
+Node: MPI formats\7f161818
+Node: Calculations\7f164701
+Node: Comparisons\7f166955
+Node: Bit manipulations\7f167599
+Node: Miscellaneous\7f168914
+Node: Prime numbers\7f170883
+Node: Generation\7f171153
+Node: Checking\7f172437
+Node: Utilities\7f172850
+Node: Memory allocation\7f173043
+Node: Architecture\7f174304
+Ref: fig:subsystems\7f175824
+Ref: Architecture-Footnote-1\7f176909
+Ref: Architecture-Footnote-2\7f176971
+Node: Public-Key Subsystem Architecture\7f177055
+Node: Symmetric Encryption Subsystem Architecture\7f179996
+Node: Hashing and MACing Subsystem Architecture\7f181443
+Node: Multi-Precision-Integer Subsystem Architecture\7f183367
+Node: Prime-Number-Generator Subsystem Architecture\7f184808
+Ref: Prime-Number-Generator Subsystem Architecture-Footnote-1\7f186739
+Node: Random-Number Subsystem Architecture\7f187026
+Node: CSPRNG Description\7f189515
+Ref: CSPRNG Description-Footnote-1\7f191077
+Node: FIPS PRNG Description\7f191200
+Node: Self-Tests\7f193335
+Node: FIPS Mode\7f205019
+Ref: fig:fips-fsm\7f208999
+Ref: tbl:fips-states\7f209101
+Ref: tbl:fips-state-transitions\7f210354
+Node: Library Copying\7f213968
+Node: Copying\7f242086
+Node: Figures and Tables\7f261260
+Node: Concept Index\7f261670
+Node: Function and Data Index\7f267235
+\1f
+End Tag Table
projects / external / libgcrypt11.git / commitdiff
