The Libgcrypt Reference Manual

The Libgcrypt Library

This manual is for Libgcrypt (version 1.5.3, 25 July 2013), which is GNU's library of cryptographic building blocks.

Copyright © 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011 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”.

• 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.
• Key Derivation: How to derive keys from strings
• 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.

1 Introduction

Libgcrypt is a library providing cryptographic building blocks.

• Getting Started: How to use this manual.
• Features: A glance at Libgcrypt's features.
• Overview: Overview about the library.

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.

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 (see 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 (see 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.

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.

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.

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

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 definitions for deprecated features. This is useful to make sure that no deprecated features are used.

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`

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.

You can use the defined Autoconf variables like this in your Makefile.am:

     AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
     LDADD = $(LIBGCRYPT_LIBS)

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.

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.

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.

  If you use pthread and your applications forks and does not directly call exec (even calling stdio functions), all kind of problems may occur. Future versions of Libgcrypt will try to cleanup using pthread_atfork but even that may lead to problems. This is a common problem with almost all applications using pthread and fork.

  Note that future versions of Libgcrypt will drop this flexible thread support and instead only support the platforms standard thread implementation.

• 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¹.
• 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”. Example:

            ret = gcry_control (GCRYCTL_SET_THREAD_CBS, &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”. Example:

            ret = gcry_control (GCRYCTL_SET_THREAD_CBS, &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.

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 or by using the control command GCRYCTL_SET_ENFORCED_FIPS_FLAG before any other calls to libgcrypt. The Enforced FIPS mode helps to detect applications which don't fulfill all requirements for using Libgcrypt in FIPS mode (see 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.

3 Generalities

• Controlling the library: Controlling Libgcrypt's behavior.
• Modules: Description of extension modules.
• Error Handling: Error codes and such.

3.1 Controlling the library

3.2 Modules

Libgcrypt supports the use of `extension modules', which implement algorithms in addition to those already built into the library directly.

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.

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.

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

3.3.1 Error Values

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.

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.

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.

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.

3.3.4 Error Strings

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

4 Handler Functions

Libgcrypt makes it possible to install so called `handler functions', which get called by Libgcrypt in case of certain events.

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

4.1 Progress handler

It is often useful to retrieve some feedback while long running operations are performed.

The following function may be used to register a handler function for this purpose.

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:

Special memory allocation functions can be installed with the following function:

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.

4.4 Logging handler

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.

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

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.

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 See Modules.

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.

GCRY_CIPHER_MODE_AESWRAP

This mode is used to implement the AES-Wrap algorithm according to RFC-3394. It may be used with any 128 bit block length algorithm, however the specs require one of the 3 AES algorithms. These special conditions apply: If gcry_cipher_setiv has not been used the standard IV is used; if it has been used the lower 64 bit of the IV are used as the Alternative Initial Value. On encryption the provided output buffer must be 64 bit (8 byte) larger than the input buffer; in-place encryption is still allowed. On decryption the output buffer may be specified 64 bit (8 byte) shorter than then input buffer. As per specs the input length must be at least 128 bits and the length must be a multiple of 64 bits.

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:

Use the following function to release an existing handle:

In order to use a handle for performing cryptographic operations, a `key' has to be set first:

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:

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.

OpenPGP (as defined in RFC-2440) requires a special sync operation in some places. The following function is used for this:

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:

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.

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.

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

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.

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.

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

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

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.

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.

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 See Modules.

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 for encryption, block type 1 padding for signing.

oaep

Use RSA-OAEP padding for encryption.

pss

Use RSA-PSS padding for signing.

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:

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:

The operation most commonly used is definitely the verification of a signature. Libgcrypt provides this function:

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:

Libgcrypt also provides a function to generate public key pairs:

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.

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

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.

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.

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.

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.

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:

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

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:

6.6.5 Working with keys

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.

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.

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:

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:

6.6.7 Handle-independent functions

These two functions are deprecated; do not use them for new code.

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.

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

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. Note that SHA-1 begins to show some weaknesses and it is suggested to fade out its use if strong cryptographic properties are required.

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. This algorithm share a lot of design properties with SHA-1 and thus it is advisable not to use it for new protocols.

GCRY_MD_MD5

This is the well known MD5 algorithm, which yields a message digest of 16 bytes. Note that the MD5 algorithm has severe weaknesses, for example it is easy to compute two messages yielding the same hash (collision attack). The use of this algorithm is only justified for non-cryptographic application.

GCRY_MD_MD4

This is the MD4 algorithm, which yields a message digest of 16 bytes. This algorithms ha severe weaknesses and should not be used.

GCRY_MD_MD2

This is an reserved identifier for MD-2; there is no implementation yet. This algorithm has severe weaknesses and should not be used.

GCRY_MD_TIGER

This is the TIGER/192 algorithm which yields a message digest of 24 bytes. Actually this is a variant of TIGER with a different output print order as used by GnuPG up to version 1.3.2.

GCRY_MD_TIGER1

This is the TIGER variant as used by the NESSIE project. It uses the most commonly used output print order.

GCRY_MD_TIGER2

This is another variant of TIGER with a different padding scheme.

GCRY_MD_HAVAL

This is an reserved value 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. Note that this is not a hash algorithm in the cryptographic sense.

GCRY_MD_CRC32_RFC1510

This is the above cyclic redundancy check function, as modified by RFC 1510. It yields an output of 4 bytes. Note that this is not a hash algorithm in the cryptographic sense.

GCRY_MD_CRC24_RFC2440

This is the OpenPGP cyclic redundancy check function. It yields an output of 3 bytes. Note that this is not a hash algorithm in the cryptographic sense.

GCRY_MD_WHIRLPOOL

This is the Whirlpool algorithm which yields a message digest of 64 bytes.

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 See Modules.

7.3 Working with hash algorithms

To use most of these function it is necessary to create a context; this is done using:

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:

If the flag GCRY_MD_FLAG_HMAC was used, the key for the MAC must be set using the function:

After you are done with the hash calculation, you should release the resources by using:

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:

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:

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.

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.

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

Because it is often necessary to get the message digest of one block of memory, a fast convenience function is available for this task:

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.

To test whether an algorithm is actually available for use, the following macro should be used:

If the length of a message digest is not known, it can be retrieved using the following function:

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:

The following macro might also be useful:

Tracking bugs related to hashing is often a cumbersome task which requires to add a lot of printf statements into the code. Libgcrypt provides an easy way to avoid this. The actual data hashed can be written to files on request.

The following two deprecated macros are used for debugging by old code. They shopuld be replaced by gcry_md_debug.

8 Key Derivation

Libgcypt provides a general purpose function to derive keys from strings.

9 Random Numbers

• Quality of random numbers: Libgcrypt uses different quality levels.
• Retrieving random numbers: How to retrieve random numbers.

9.1 Quality of random numbers

Libgcypt offers random numbers of different quality levels:

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.

9.2 Retrieving random numbers

10 S-expressions

S-expressions are used by the public key functions to pass complex data structures around. These LISP like objects are used by some cryptographic protocols (cf. RFC-2692) and Libgcrypt provides functions to parse and construct them. For detailed information, see Ron Rivest, code and description of S-expressions, http://theory.lcs.mit.edu/~rivest/sexp.html.

• Data types for S-expressions: Data types related with S-expressions.
• Working with S-expressions: How to work with S-expressions.

10.1 Data types for S-expressions

10.2 Working with S-expressions

There are several functions to create an Libgcrypt S-expression object from its external representation or from a string template. There is also a function to convert the internal representation back into one of the external formats:

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.

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"

There are functions to parse S-expressions and retrieve elements:

11 MPI library

• Data types: MPI related data types.
• Basic functions: First steps with MPI numbers.
• MPI formats: External representation of MPIs.
• Calculations: Performing MPI calculations.
• Comparisons: How to compare MPI values.
• Bit manipulations: How to access single bits of MPI values.
• Miscellaneous: Miscellaneous MPI functions.

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

11.1 Data types

11.2 Basic functions

To work with MPIs, storage must be allocated and released for the numbers. This can be done with one of these functions:

The simplest operations are used to assign a new value to an MPI:

11.3 MPI formats

The following functions are used to convert between an external representation of an MPI and the internal one of Libgcrypt.

11.4 Calculations

Basic arithmetic operations:

11.5 Comparisons

The next 2 functions are used to compare MPIs:

11.6 Bit manipulations

There are a couple of functions to get information on arbitrary bits in an MPI and to set or clear them:

11.7 Miscellaneous

12 Prime numbers

• Generation: Generation of new prime numbers.
• Checking: Checking if a given number is prime.

12.1 Generation

12.2 Checking

13 Utilities

• Memory allocation: Functions related with memory allocation.

13.1 Memory allocation

14 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² 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³.

Figure 14.1: Libgcrypt subsystems

Libgcrypt consists of several subsystems (see Figure 14.1) 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.

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

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

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

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

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

14.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.⁴ 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.

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

• CSPRNG Description: Description of the CSPRNG.
• FIPS PRNG Description: Description of the FIPS X9.31 PRNG.

14.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".⁵

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.

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

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/pubkey.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 library 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)

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 (see tbl:fips-states) and checks at runtime that only valid transitions (see tbl:fips-state-transitions) may happen.

Figure B.1: FIPS mode state diagram

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.

GNU Lesser General Public License

     Copyright © 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.

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:
   1. The modified work must itself be a software library.
   2. You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.
   3. You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.
   4. 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:

   1. 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.)
   2. 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.
   3. 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.
   4. 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.
   5. 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:
   1. 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.
   2. 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.
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.

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!

GNU General Public License

     Copyright © 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.

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:
   1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
   2. 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.
   3. 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:
   1. 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,
   2. 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,
   3. 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.
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.

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.

List of Figures and Tables

• Figure 14.1: Libgcrypt subsystems
• Figure B.1: FIPS mode state diagram

• Table B.1: FIPS mode states
• Table B.2: FIPS mode state transitions

Concept Index

• 3DES: Available ciphers
• Advanced Encryption Standard: Available ciphers
• AES: Available ciphers
• AES-Wrap mode: Available cipher modes
• Arcfour: Available ciphers
• Blowfish: Available ciphers
• Camellia: Available ciphers
• CAST5: Available ciphers
• CBC, Cipher Block Chaining mode: Available cipher modes
• CBC-MAC: Working with cipher handles
• CFB, Cipher Feedback mode: Available cipher modes
• cipher text stealing: Working with cipher handles
• CRC32: Available hash algorithms
• CTR, Counter mode: Available cipher modes
• DES: Available ciphers
• DES-EDE: Available ciphers
• Digital Encryption Standard: Available ciphers
• ECB, Electronic Codebook mode: Available cipher modes
• Enforced FIPS mode: Enabling FIPS mode
• error codes: Error Values
• error codes, list of: Error Codes
• error codes, list of: Error Sources
• error codes, printing of: Error Strings
• error sources: Error Values
• error sources, printing of: Error Strings
• error strings: Error Strings
• error values: Error Values
• error values, printing of: Error Strings
• FIPS 140: Enabling FIPS mode
• FIPS 186: Public-Key Subsystem Architecture
• FIPS 186: General public-key related Functions
• FIPS mode: Enabling FIPS mode
• GPL, GNU General Public License: Copying
• HAVAL: Available hash algorithms
• HMAC: Working with hash algorithms
• IDEA: Available ciphers
• LGPL, GNU Lesser General Public License: Library Copying
• MD2, MD4, MD5: Available hash algorithms
• OFB, Output Feedback mode: Available cipher modes
• RC2: Available ciphers
• RC4: Available ciphers
• rfc-2268: Available ciphers
• Rijndael: Available ciphers
• RIPE-MD-160: Available hash algorithms
• Seed (cipher): Available ciphers
• Serpent: Available ciphers
• SHA-1: Available hash algorithms
• SHA-224, SHA-256, SHA-384, SHA-512: Available hash algorithms
• sync mode (OpenPGP): Working with cipher handles
• TIGER, TIGER1, TIGER2: Available hash algorithms
• Triple-DES: Available ciphers
• Twofish: Available ciphers
• Whirlpool: Available hash algorithms
• X9.31: Public-Key Subsystem Architecture
• X9.31: General public-key related Functions

Function and Data Index

• AM_PATH_LIBGCRYPT: Building sources using Automake
• gcry_ac_close: Working with handles
• gcry_ac_data_clear: Working with sets of data
• gcry_ac_data_copy: Working with sets of data
• gcry_ac_data_decode: Using cryptographic functions
• gcry_ac_data_decrypt: Using cryptographic functions
• gcry_ac_data_decrypt_scheme: Using cryptographic functions
• gcry_ac_data_destroy: Working with sets of data
• gcry_ac_data_encode: Using cryptographic functions
• gcry_ac_data_encrypt: Using cryptographic functions
• gcry_ac_data_encrypt_scheme: Using cryptographic functions
• gcry_ac_data_from_sexp: Working with sets of data
• gcry_ac_data_get_index: Working with sets of data
• gcry_ac_data_get_name: Working with sets of data
• gcry_ac_data_length: Working with sets of data
• gcry_ac_data_new: Working with sets of data
• gcry_ac_data_set: Working with sets of data
• gcry_ac_data_sign: Using cryptographic functions
• gcry_ac_data_sign_scheme: Using cryptographic functions
• gcry_ac_data_t: Working with sets of data
• gcry_ac_data_to_sexp: Working with sets of data
• gcry_ac_data_verify: Using cryptographic functions
• gcry_ac_data_verify_scheme: Using cryptographic functions
• gcry_ac_id_t: Available asymmetric algorithms
• gcry_ac_id_to_name: Handle-independent functions
• gcry_ac_io_init: Working with IO objects
• gcry_ac_io_init_va: Working with IO objects
• gcry_ac_io_t: Working with IO objects
• gcry_ac_key_data_get: Working with keys
• gcry_ac_key_destroy: Working with keys
• gcry_ac_key_get_grip: Working with keys
• gcry_ac_key_get_nbits: Working with keys
• gcry_ac_key_init: Working with keys
• gcry_ac_key_pair_destroy: Working with keys
• gcry_ac_key_pair_extract: Working with keys
• gcry_ac_key_pair_generate: Working with keys
• gcry_ac_key_pair_t: Working with keys
• gcry_ac_key_t: Working with keys
• gcry_ac_key_test: Working with keys
• gcry_ac_key_type_t: Working with keys
• gcry_ac_name_to_id: Handle-independent functions
• gcry_ac_open: Working with handles
• gcry_calloc: Memory allocation
• gcry_calloc_secure: Memory allocation
• gcry_check_version: Initializing the library
• gcry_cipher_algo_info: General cipher functions
• gcry_cipher_algo_name: General cipher functions
• gcry_cipher_close: Working with cipher handles
• gcry_cipher_ctl: Working with cipher handles
• gcry_cipher_decrypt: Working with cipher handles
• gcry_cipher_decrypt_t: Cipher modules
• gcry_cipher_encrypt: Working with cipher handles
• gcry_cipher_encrypt_t: Cipher modules
• gcry_cipher_get_algo_blklen: General cipher functions
• gcry_cipher_get_algo_keylen: General cipher functions
• gcry_cipher_info: Working with cipher handles
• gcry_cipher_list: Cipher modules
• gcry_cipher_map_name: General cipher functions
• gcry_cipher_mode_from_oid: General cipher functions
• gcry_cipher_oid_spec_t: Cipher modules
• gcry_cipher_open: Working with cipher handles
• gcry_cipher_register: Cipher modules
• gcry_cipher_reset: Working with cipher handles
• gcry_cipher_setctr: Working with cipher handles
• gcry_cipher_setiv: Working with cipher handles
• gcry_cipher_setkey: Working with cipher handles
• gcry_cipher_setkey_t: Cipher modules
• gcry_cipher_spec_t: Cipher modules
• gcry_cipher_stdecrypt_t: Cipher modules
• gcry_cipher_stencrypt_t: Cipher modules
• gcry_cipher_sync: Working with cipher handles
• gcry_cipher_unregister: Cipher modules
• gcry_control: Controlling the library
• gcry_create_nonce: Retrieving random numbers
• gcry_err_code: Error Values
• gcry_err_code_from_errno: Error Values
• gcry_err_code_t: Error Values
• gcry_err_code_to_errno: Error Values
• gcry_err_make: Error Values
• gcry_err_make_from_errno: Error Values
• gcry_err_source: Error Values
• gcry_err_source_t: Error Values
• gcry_error: Error Values
• gcry_error_from_errno: Error Values
• gcry_error_t: Error Values
• gcry_fips_mode_active: Controlling the library
• gcry_free: Memory allocation
• gcry_handler_alloc_t: Allocation handler
• gcry_handler_error_t: Error handler
• gcry_handler_free_t: Allocation handler
• gcry_handler_log_t: Logging handler
• gcry_handler_no_mem_t: Error handler
• gcry_handler_progress_t: Progress handler
• gcry_handler_realloc_t: Allocation handler
• gcry_handler_secure_check_t: Allocation handler
• gcry_kdf_derive: Key Derivation
• gcry_malloc: Memory allocation
• gcry_malloc_secure: Memory allocation
• gcry_md_algo_name: Working with hash algorithms
• gcry_md_close: Working with hash algorithms
• gcry_md_copy: Working with hash algorithms
• gcry_md_debug: Working with hash algorithms
• gcry_md_enable: Working with hash algorithms
• gcry_md_final: Working with hash algorithms
• gcry_md_final_t: Hash algorithm modules
• gcry_md_get_algo: Working with hash algorithms
• gcry_md_get_algo_dlen: Working with hash algorithms
• gcry_md_get_asnoid: Working with hash algorithms
• gcry_md_hash_buffer: Working with hash algorithms
• gcry_md_init_t: Hash algorithm modules
• gcry_md_is_enabled: Working with hash algorithms
• gcry_md_is_secure: Working with hash algorithms
• gcry_md_list: Hash algorithm modules
• gcry_md_map_name: Working with hash algorithms
• gcry_md_oid_spec_t: Hash algorithm modules
• gcry_md_open: Working with hash algorithms
• gcry_md_putc: Working with hash algorithms
• gcry_md_read: Working with hash algorithms
• gcry_md_read_t: Hash algorithm modules
• gcry_md_register: Hash algorithm modules
• gcry_md_reset: Working with hash algorithms
• gcry_md_setkey: Working with hash algorithms
• gcry_md_spec_t: Hash algorithm modules
• gcry_md_start_debug: Working with hash algorithms
• gcry_md_stop_debug: Working with hash algorithms
• gcry_md_test_algo: Working with hash algorithms
• gcry_md_unregister: Hash algorithm modules
• gcry_md_write: Working with hash algorithms
• gcry_md_write_t: Hash algorithm modules
• gcry_module_t: Modules
• gcry_mpi_add: Calculations
• gcry_mpi_add_ui: Calculations
• gcry_mpi_addm: Calculations
• gcry_mpi_aprint: MPI formats
• gcry_mpi_clear_bit: Bit manipulations
• gcry_mpi_clear_flag: Miscellaneous
• gcry_mpi_clear_highbit: Bit manipulations
• gcry_mpi_cmp: Comparisons
• gcry_mpi_cmp_ui: Comparisons
• gcry_mpi_copy: Basic functions
• gcry_mpi_div: Calculations
• gcry_mpi_dump: MPI formats
• gcry_mpi_gcd: Calculations
• gcry_mpi_get_flag: Miscellaneous
• gcry_mpi_get_nbits: Bit manipulations
• gcry_mpi_get_opaque: Miscellaneous
• gcry_mpi_invm: Calculations
• gcry_mpi_lshift: Bit manipulations
• gcry_mpi_mod: Calculations
• gcry_mpi_mul: Calculations
• gcry_mpi_mul_2exp: Calculations
• gcry_mpi_mul_ui: Calculations
• gcry_mpi_mulm: Calculations
• gcry_mpi_new: Basic functions
• gcry_mpi_powm: Calculations
• gcry_mpi_print: MPI formats
• gcry_mpi_randomize: Miscellaneous
• gcry_mpi_release: Basic functions
• gcry_mpi_rshift: Bit manipulations
• gcry_mpi_scan: MPI formats
• gcry_mpi_set: Basic functions
• gcry_mpi_set_bit: Bit manipulations
• gcry_mpi_set_flag: Miscellaneous
• gcry_mpi_set_highbit: Bit manipulations
• gcry_mpi_set_opaque: Miscellaneous
• gcry_mpi_set_ui: Basic functions
• gcry_mpi_snew: Basic functions
• gcry_mpi_sub: Calculations
• gcry_mpi_sub_ui: Calculations
• gcry_mpi_subm: Calculations
• gcry_mpi_swap: Basic functions
• gcry_mpi_t: Data types
• gcry_mpi_test_bit: Bit manipulations
• gcry_pk_algo_info: General public-key related Functions
• gcry_pk_algo_name: General public-key related Functions
• gcry_pk_check_secret_key_t: Public key modules
• gcry_pk_ctl: General public-key related Functions
• gcry_pk_decrypt: Cryptographic Functions
• gcry_pk_decrypt_t: Public key modules
• gcry_pk_encrypt: Cryptographic Functions
• gcry_pk_encrypt_t: Public key modules
• gcry_pk_generate_t: Public key modules
• gcry_pk_genkey: General public-key related Functions
• gcry_pk_get_keygrip: General public-key related Functions
• gcry_pk_get_nbits: General public-key related Functions
• gcry_pk_get_nbits_t: Public key modules
• gcry_pk_list: Public key modules
• gcry_pk_map_name: General public-key related Functions
• gcry_pk_register: Public key modules
• gcry_pk_sign: Cryptographic Functions
• gcry_pk_sign_t: Public key modules
• gcry_pk_spec_t: Public key modules
• gcry_pk_test_algo: General public-key related Functions
• gcry_pk_testkey: General public-key related Functions
• gcry_pk_unregister: Public key modules
• gcry_pk_verify: Cryptographic Functions
• gcry_pk_verify_t: Public key modules
• gcry_prime_check: Checking
• gcry_prime_generate: Generation
• gcry_prime_group_generator: Generation
• gcry_prime_release_factors: Generation
• gcry_random_bytes: Retrieving random numbers
• gcry_random_bytes_secure: Retrieving random numbers
• gcry_random_level_t: Quality of random numbers
• gcry_randomize: Retrieving random numbers
• gcry_realloc: Memory allocation
• gcry_set_allocation_handler: Allocation handler
• gcry_set_fatalerror_handler: Error handler
• gcry_set_log_handler: Logging handler
• gcry_set_outofcore_handler: Error handler
• gcry_set_progress_handler: Progress handler
• gcry_sexp_build: Working with S-expressions
• gcry_sexp_canon_len: Working with S-expressions
• gcry_sexp_car: Working with S-expressions
• gcry_sexp_cdr: Working with S-expressions
• gcry_sexp_create: Working with S-expressions
• gcry_sexp_dump: Working with S-expressions
• gcry_sexp_find_token: Working with S-expressions
• gcry_sexp_length: Working with S-expressions
• gcry_sexp_new: Working with S-expressions
• gcry_sexp_nth: Working with S-expressions
• gcry_sexp_nth_data: Working with S-expressions
• gcry_sexp_nth_mpi: Working with S-expressions
• gcry_sexp_nth_string: Working with S-expressions
• gcry_sexp_release: Working with S-expressions
• gcry_sexp_sprint: Working with S-expressions
• gcry_sexp_sscan: Working with S-expressions
• gcry_sexp_t: Data types for S-expressions
• gcry_strerror: Error Strings
• gcry_strsource: Error Strings