diff options
Diffstat (limited to 'plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.info')
| -rw-r--r-- | plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.info | 6839 |
1 files changed, 6839 insertions, 0 deletions
diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.info b/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.info new file mode 100644 index 0000000000..0c6c6ee847 --- /dev/null +++ b/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.info @@ -0,0 +1,6839 @@ +This is gcrypt.info, produced by makeinfo version 4.13 from gcrypt.texi. + +This manual is for Libgcrypt (version 1.4.6, 9 July 2009), which is +GNU's library of cryptographic building blocks. + + Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free +Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "GNU General Public + License". + +INFO-DIR-SECTION GNU Libraries +START-INFO-DIR-ENTRY +* libgcrypt: (gcrypt). Cryptographic function library. +END-INFO-DIR-ENTRY + + +File: gcrypt.info, Node: Top, Next: Introduction, Up: (dir) + +The Libgcrypt Library +********************* + +This manual is for Libgcrypt (version 1.4.6, 9 July 2009), which is +GNU's library of cryptographic building blocks. + + Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free +Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of the + License, or (at your option) any later version. The text of the + license can be found in the section entitled "GNU General Public + License". + +* Menu: + +* Introduction:: What is Libgcrypt. +* Preparation:: What you should do before using the library. +* Generalities:: General library functions and data types. +* Handler Functions:: Working with handler functions. +* Symmetric cryptography:: How to use symmetric cryptography. +* Public Key cryptography:: How to use public key cryptography. +* Hashing:: How to use hash and MAC algorithms. +* Random Numbers:: How to work with random numbers. +* S-expressions:: How to manage S-expressions. +* MPI library:: How to work with multi-precision-integers. +* Prime numbers:: How to use the Prime number related functions. +* Utilities:: Utility functions. +* Architecture:: How Libgcrypt works internally. + +Appendices + +* Self-Tests:: Description of the self-tests. +* FIPS Mode:: Description of the FIPS mode. +* Library Copying:: The GNU Lesser General Public License + says how you can copy and share Libgcrypt. +* Copying:: The GNU General Public License says how you + can copy and share some parts of Libgcrypt. + +Indices + +* Figures and Tables:: Index of figures and tables. +* Concept Index:: Index of concepts and programs. +* Function and Data Index:: Index of functions, variables and data types. + + +File: gcrypt.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top + +1 Introduction +************** + +Libgcrypt is a library providing cryptographic building blocks. + +* Menu: + +* Getting Started:: How to use this manual. +* Features:: A glance at Libgcrypt's features. +* Overview:: Overview about the library. + + +File: gcrypt.info, Node: Getting Started, Next: Features, Up: Introduction + +1.1 Getting Started +=================== + +This manual documents the Libgcrypt library application programming +interface (API). All functions and data types provided by the library +are explained. + +The reader is assumed to possess basic knowledge about applied +cryptography. + + This manual can be used in several ways. If read from the beginning +to the end, it gives a good introduction into the library and how it +can be used in an application. Forward references are included where +necessary. Later on, the manual can be used as a reference manual to +get just the information needed about any particular interface of the +library. Experienced programmers might want to start looking at the +examples at the end of the manual, and then only read up those parts of +the interface which are unclear. + + +File: gcrypt.info, Node: Features, Next: Overview, Prev: Getting Started, Up: Introduction + +1.2 Features +============ + +Libgcrypt might have a couple of advantages over other libraries doing +a similar job. + +It's Free Software + Anybody can use, modify, and redistribute it under the terms of + the GNU Lesser General Public License (*note Library Copying::). + Note, that some parts (which are in general not needed by + applications) are subject to the terms of the GNU General Public + License (*note Copying::); please see the README file of the + distribution for of list of these parts. + +It encapsulates the low level cryptography + Libgcrypt provides a high level interface to cryptographic + building blocks using an extensible and flexible API. + + + +File: gcrypt.info, Node: Overview, Prev: Features, Up: Introduction + +1.3 Overview +============ + +The Libgcrypt library is fully thread-safe, where it makes sense to be +thread-safe. Not thread-safe are some cryptographic functions that +modify a certain context stored in handles. If the user really intents +to use such functions from different threads on the same handle, he has +to take care of the serialization of such functions himself. If not +described otherwise, every function is thread-safe. + + Libgcrypt depends on the library `libgpg-error', which contains +common error handling related code for GnuPG components. + + +File: gcrypt.info, Node: Preparation, Next: Generalities, Prev: Introduction, Up: Top + +2 Preparation +************* + +To use Libgcrypt, you have to perform some changes to your sources and +the build system. The necessary changes are small and explained in the +following sections. At the end of this chapter, it is described how +the library is initialized, and how the requirements of the library are +verified. + +* Menu: + +* Header:: What header file you need to include. +* Building sources:: How to build sources using the library. +* Building sources using Automake:: How to build sources with the help of Automake. +* Initializing the library:: How to initialize the library. +* Multi-Threading:: How Libgcrypt can be used in a MT environment. +* Enabling FIPS mode:: How to enable the FIPS mode. + + +File: gcrypt.info, Node: Header, Next: Building sources, Up: Preparation + +2.1 Header +========== + +All interfaces (data types and functions) of the library are defined in +the header file `gcrypt.h'. You must include this in all source files +using the library, either directly or through some other header file, +like this: + + #include <gcrypt.h> + + The name space of Libgcrypt is `gcry_*' for function and type names +and `GCRY*' for other symbols. In addition the same name prefixes with +one prepended underscore are reserved for internal use and should never +be used by an application. Note that Libgcrypt uses libgpg-error, +which uses `gpg_*' as name space for function and type names and +`GPG_*' for other symbols, including all the error codes. + +Certain parts of gcrypt.h may be excluded by defining these macros: + +`GCRYPT_NO_MPI_MACROS' + Do not define the shorthand macros `mpi_*' for `gcry_mpi_*'. + +`GCRYPT_NO_DEPRECATED' + Do not include defintions for deprecated features. This is useful + to make sure that no deprecated features are used. + + +File: gcrypt.info, Node: Building sources, Next: Building sources using Automake, Prev: Header, Up: Preparation + +2.2 Building sources +==================== + +If you want to compile a source file including the `gcrypt.h' header +file, you must make sure that the compiler can find it in the directory +hierarchy. This is accomplished by adding the path to the directory in +which the header file is located to the compilers include file search +path (via the `-I' option). + + However, the path to the include file is determined at the time the +source is configured. To solve this problem, Libgcrypt ships with a +small helper program `libgcrypt-config' that knows the path to the +include file and other configuration options. The options that need to +be added to the compiler invocation at compile time are output by the +`--cflags' option to `libgcrypt-config'. The following example shows +how it can be used at the command line: + + gcc -c foo.c `libgcrypt-config --cflags` + + Adding the output of `libgcrypt-config --cflags' to the compilers +command line will ensure that the compiler can find the Libgcrypt header +file. + + A similar problem occurs when linking the program with the library. +Again, the compiler has to find the library files. For this to work, +the path to the library files has to be added to the library search path +(via the `-L' option). For this, the option `--libs' to +`libgcrypt-config' can be used. For convenience, this option also +outputs all other options that are required to link the program with +the Libgcrypt libraries (in particular, the `-lgcrypt' option). The +example shows how to link `foo.o' with the Libgcrypt library to a +program `foo'. + + gcc -o foo foo.o `libgcrypt-config --libs` + + Of course you can also combine both examples to a single command by +specifying both options to `libgcrypt-config': + + gcc -o foo foo.c `libgcrypt-config --cflags --libs` + + +File: gcrypt.info, Node: Building sources using Automake, Next: Initializing the library, Prev: Building sources, Up: Preparation + +2.3 Building sources using Automake +=================================== + +It is much easier if you use GNU Automake instead of writing your own +Makefiles. If you do that, you do not have to worry about finding and +invoking the `libgcrypt-config' script at all. Libgcrypt provides an +extension to Automake that does all the work for you. + + -- Macro: AM_PATH_LIBGCRYPT ([MINIMUM-VERSION], [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Check whether Libgcrypt (at least version MINIMUM-VERSION, if + given) exists on the host system. If it is found, execute + ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given. + + Additionally, the function defines `LIBGCRYPT_CFLAGS' to the flags + needed for compilation of the program to find the `gcrypt.h' + header file, and `LIBGCRYPT_LIBS' to the linker flags needed to + link the program to the Libgcrypt library. + + You can use the defined Autoconf variables like this in your +`Makefile.am': + + AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS) + LDADD = $(LIBGCRYPT_LIBS) + + +File: gcrypt.info, Node: Initializing the library, Next: Multi-Threading, Prev: Building sources using Automake, Up: Preparation + +2.4 Initializing the library +============================ + +Before the library can be used, it must initialize itself. This is +achieved by invoking the function `gcry_check_version' described below. + + Also, it is often desirable to check that the version of Libgcrypt +used is indeed one which fits all requirements. Even with binary +compatibility, new features may have been introduced, but due to +problem with the dynamic linker an old version may actually be used. +So you may want to check that the version is okay right after program +startup. + + -- Function: const char * gcry_check_version (const char *REQ_VERSION) + The function `gcry_check_version' initializes some subsystems used + by Libgcrypt and must be invoked before any other function in the + library, with the exception of the `GCRYCTL_SET_THREAD_CBS' command + (called via the `gcry_control' function). *Note Multi-Threading::. + + Furthermore, this function returns the version number of the + library. It can also verify that the version number is higher + than a certain required version number REQ_VERSION, if this value + is not a null pointer. + + Libgcrypt uses a concept known as secure memory, which is a region of +memory set aside for storing sensitive data. Because such memory is a +scarce resource, it needs to be setup in advanced to a fixed size. +Further, most operating systems have special requirements on how that +secure memory can be used. For example, it might be required to install +an application as "setuid(root)" to allow allocating such memory. +Libgcrypt requires a sequence of initialization steps to make sure that +this works correctly. The following examples show the necessary steps. + + If you don't have a need for secure memory, for example if your +application does not use secret keys or other confidential data or it +runs in a controlled environment where key material floating around in +memory is not a problem, you should initialize Libgcrypt this way: + + /* Version check should be the very first call because it + makes sure that important subsystems are intialized. */ + if (!gcry_check_version (GCRYPT_VERSION)) + { + fputs ("libgcrypt version mismatch\n", stderr); + exit (2); + } + + /* Disable secure memory. */ + gcry_control (GCRYCTL_DISABLE_SECMEM, 0); + + /* ... If required, other initialization goes here. */ + + /* Tell Libgcrypt that initialization has completed. */ + gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0); + + If you have to protect your keys or other information in memory +against being swapped out to disk and to enable an automatic overwrite +of used and freed memory, you need to initialize Libgcrypt this way: + + /* Version check should be the very first call because it + makes sure that important subsystems are intialized. */ + if (!gcry_check_version (GCRYPT_VERSION)) + { + fputs ("libgcrypt version mismatch\n", stderr); + exit (2); + } + + /* We don't want to see any warnings, e.g. because we have not yet + parsed program options which might be used to suppress such + warnings. */ + gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN); + + /* ... If required, other initialization goes here. Note that the + process might still be running with increased privileges and that + the secure memory has not been intialized. */ + + /* Allocate a pool of 16k secure memory. This make the secure memory + available and also drops privileges where needed. */ + gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0); + + /* It is now okay to let Libgcrypt complain when there was/is + a problem with the secure memory. */ + gcry_control (GCRYCTL_RESUME_SECMEM_WARN); + + /* ... If required, other initialization goes here. */ + + /* Tell Libgcrypt that initialization has completed. */ + gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0); + + It is important that these initialization steps are not done by a +library but by the actual application. A library using Libgcrypt might +want to check for finished initialization using: + + if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P)) + { + fputs ("libgcrypt has not been initialized\n", stderr); + abort (); + } + + Instead of terminating the process, the library may instead print a +warning and try to initialize Libgcrypt itself. See also the section on +multi-threading below for more pitfalls. + + +File: gcrypt.info, Node: Multi-Threading, Next: Enabling FIPS mode, Prev: Initializing the library, Up: Preparation + +2.5 Multi-Threading +=================== + +As mentioned earlier, the Libgcrypt library is thread-safe if you +adhere to the following requirements: + + * If your application is multi-threaded, you must set the thread + support callbacks with the `GCRYCTL_SET_THREAD_CBS' command + *before* any other function in the library. + + This is easy enough if you are indeed writing an application using + Libgcrypt. It is rather problematic if you are writing a library + instead. Here are some tips what to do if you are writing a + library: + + If your library requires a certain thread package, just initialize + Libgcrypt to use this thread package. If your library supports + multiple thread packages, but needs to be configured, you will + have to implement a way to determine which thread package the + application wants to use with your library anyway. Then configure + Libgcrypt to use this thread package. + + If your library is fully reentrant without any special support by a + thread package, then you are lucky indeed. Unfortunately, this + does not relieve you from doing either of the two above, or use a + third option. The third option is to let the application + initialize Libgcrypt for you. Then you are not using Libgcrypt + transparently, though. + + As if this was not difficult enough, a conflict may arise if two + libraries try to initialize Libgcrypt independently of each + others, and both such libraries are then linked into the same + application. To make it a bit simpler for you, this will probably + work, but only if both libraries have the same requirement for the + thread package. This is currently only supported for the + non-threaded case, GNU Pth and pthread. Support for more thread + packages is easy to add, so contact us if you require it. + + * The function `gcry_check_version' must be called before any other + function in the library, except the `GCRYCTL_SET_THREAD_CBS' + command (called via the `gcry_control' function), because it + initializes the thread support subsystem in Libgcrypt. To achieve + this in multi-threaded programs, you must synchronize the memory + with respect to other threads that also want to use Libgcrypt. + For this, it is sufficient to call `gcry_check_version' before + creating the other threads using Libgcrypt(1). + + * Just like the function `gpg_strerror', the function + `gcry_strerror' is not thread safe. You have to use + `gpg_strerror_r' instead. + + + Libgcrypt contains convenient macros, which define the necessary +thread callbacks for PThread and for GNU Pth: + +`GCRY_THREAD_OPTION_PTH_IMPL' + This macro defines the following (static) symbols: + `gcry_pth_init', `gcry_pth_mutex_init', `gcry_pth_mutex_destroy', + `gcry_pth_mutex_lock', `gcry_pth_mutex_unlock', `gcry_pth_read', + `gcry_pth_write', `gcry_pth_select', `gcry_pth_waitpid', + `gcry_pth_accept', `gcry_pth_connect', `gcry_threads_pth'. + + After including this macro, `gcry_control()' shall be used with a + command of `GCRYCTL_SET_THREAD_CBS' in order to register the + thread callback structure named "gcry_threads_pth". + +`GCRY_THREAD_OPTION_PTHREAD_IMPL' + This macro defines the following (static) symbols: + `gcry_pthread_mutex_init', `gcry_pthread_mutex_destroy', + `gcry_pthread_mutex_lock', `gcry_pthread_mutex_unlock', + `gcry_threads_pthread'. + + After including this macro, `gcry_control()' shall be used with a + command of `GCRYCTL_SET_THREAD_CBS' in order to register the + thread callback structure named "gcry_threads_pthread". + + Note that these macros need to be terminated with a semicolon. Keep +in mind that these are convenient macros for C programmers; C++ +programmers might have to wrap these macros in an "extern C" body. + + ---------- Footnotes ---------- + + (1) At least this is true for POSIX threads, as `pthread_create' is +a function that synchronizes memory with respects to other threads. +There are many functions which have this property, a complete list can +be found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in +the definition of the term "Memory Synchronization". For other thread +packages, more relaxed or more strict rules may apply. + + +File: gcrypt.info, Node: Enabling FIPS mode, Prev: Multi-Threading, Up: Preparation + +2.6 How to enable the FIPS mode +=============================== + +Libgcrypt may be used in a FIPS 140-2 mode. Note, that this does not +necessary mean that Libcgrypt is an appoved FIPS 140-2 module. Check +the NIST database at `http://csrc.nist.gov/groups/STM/cmvp/' to see what +versions of Libgcrypt are approved. + + Because FIPS 140 has certain restrictions on the use of cryptography +which are not always wanted, Libgcrypt needs to be put into FIPS mode +explicitly. Three alternative mechanisms are provided to switch +Libgcrypt into this mode: + + * If the file `/proc/sys/crypto/fips_enabled' exists and contains a + numeric value other than `0', Libgcrypt is put into FIPS mode at + initialization time. Obviously this works only on systems with a + `proc' file system (i.e. GNU/Linux). + + * If the file `/etc/gcrypt/fips_enabled' exists, Libgcrypt is put + into FIPS mode at initialization time. Note that this filename is + hardwired and does not depend on any configuration options. + + * If the application requests FIPS mode using the control command + `GCRYCTL_FORCE_FIPS_MODE'. This must be done prior to any + initialization (i.e. before `gcry_check_version'). + + + In addition to the standard FIPS mode, Libgcrypt may also be put into +an Enforced FIPS mode by writing a non-zero value into the file +`/etc/gcrypt/fips_enabled'. The Enforced FIPS mode helps to detect +applications which don't fulfill all requirements for using Libgcrypt +in FIPS mode (*note FIPS Mode::). + + Once Libgcrypt has been put into FIPS mode, it is not possible to +switch back to standard mode without terminating the process first. If +the logging verbosity level of Libgcrypt has been set to at least 2, +the state transitions and the self-tests are logged. + + +File: gcrypt.info, Node: Generalities, Next: Handler Functions, Prev: Preparation, Up: Top + +3 Generalities +************** + +* Menu: + +* Controlling the library:: Controlling Libgcrypt's behavior. +* Modules:: Description of extension modules. +* Error Handling:: Error codes and such. + + +File: gcrypt.info, Node: Controlling the library, Next: Modules, Up: Generalities + +3.1 Controlling the library +=========================== + + -- Function: gcry_error_t gcry_control (enum gcry_ctl_cmds CMD, ...) + This function can be used to influence the general behavior of + Libgcrypt in several ways. Depending on CMD, more arguments can + or have to be provided. + + `GCRYCTL_ENABLE_M_GUARD; Arguments: none' + This command enables the built-in memory guard. It must not + be used to activate the memory guard after the memory + management has already been used; therefore it can ONLY be + used at initialization time. Note that the memory guard is + NOT used when the user of the library has set his own memory + management callbacks. + + `GCRYCTL_ENABLE_QUICK_RANDOM; Arguments: none' + This command inhibits the use the very secure random quality + level (`GCRY_VERY_STRONG_RANDOM') and degrades all request + down to `GCRY_STRONG_RANDOM'. In general this is not + recommened. However, for some applications the extra quality + random Libgcrypt tries to create is not justified and this + option may help to get better performace. Please check with + a crypto expert whether this option can be used for your + application. + + This option can only be used at initialization time. + + `GCRYCTL_DUMP_RANDOM_STATS; Arguments: none' + This command dumps randum number generator related statistics + to the library's logging stream. + + `GCRYCTL_DUMP_MEMORY_STATS; Arguments: none' + This command dumps memory managment related statistics to the + library's logging stream. + + `GCRYCTL_DUMP_SECMEM_STATS; Arguments: none' + This command dumps secure memory manamgent related statistics + to the library's logging stream. + + `GCRYCTL_DROP_PRIVS; Arguments: none' + This command disables the use of secure memory and drops the + priviliges of the current process. This command has not much + use; the suggested way to disable secure memory is to use + `GCRYCTL_DISABLE_SECMEM' right after initialization. + + `GCRYCTL_DISABLE_SECMEM; Arguments: none' + This command disables the use of secure memory. If this + command is used in FIPS mode, FIPS mode will be disabled and + the function `gcry_fips_mode_active' returns false. However, + in Enforced FIPS mode this command has no effect at all. + + Many applications do not require secure memory, so they + should disable it right away. This command should be + executed right after `gcry_check_version'. + + `GCRYCTL_INIT_SECMEM; Arguments: int nbytes' + This command is used to allocate a pool of secure memory and + thus enabling the use of secure memory. It also drops all + extra privileges the process has (i.e. if it is run as setuid + (root)). If the argument NBYTES is 0, secure memory will be + disabled. The minimum amount of secure memory allocated is + currently 16384 bytes; you may thus use a value of 1 to + request that default size. + + `GCRYCTL_TERM_SECMEM; Arguments: none' + This command zeroises the secure memory and destroys the + handler. The secure memory pool may not be used anymore + after running this command. If the secure memory pool as + already been destroyed, this command has no effect. + Applications might want to run this command from their exit + handler to make sure that the secure memory gets properly + destroyed. This command is not necessarily thread-safe but + that should not be needed in cleanup code. It may be called + from a signal handler. + + `GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none' + Disable warning messages about problems with the secure memory + subsystem. This command should be run right after + `gcry_check_version'. + + `GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none' + Postpone warning messages from the secure memory subsystem. + *Note the initialization example: sample-use-suspend-secmem, + on how to use it. + + `GCRYCTL_RESUME_SECMEM_WARN; Arguments: none' + Resume warning messages from the secure memory subsystem. + *Note the initialization example: sample-use-resume-secmem, + on how to use it. + + `GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none' + This command tells the PRNG to store random numbers in secure + memory. This command should be run right after + `gcry_check_version' and not later than the command + GCRYCTL_INIT_SECMEM. Note that in FIPS mode the secure + memory is always used. + + `GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename' + This command specifies the file, which is to be used as seed + file for the PRNG. If the seed file is registered prior to + initialization of the PRNG, the seed file's content (if it + exists and seems to be valid) is fed into the PRNG pool. + After the seed file has been registered, the PRNG can be + signalled to write out the PRNG pool's content into the seed + file with the following command. + + `GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none' + Write out the PRNG pool's content into the registered seed + file. + + Multiple instances of the applications sharing the same + random seed file can be started in parallel, in which case + they will read out the same pool and then race for updating + it (the last update overwrites earlier updates). They will + differentiate only by the weak entropy that is added in + read_seed_file based on the PID and clock, and up to 16 bytes + of weak random non-blockingly. The consequence is that the + output of these different instances is correlated to some + extent. In a perfect attack scenario, the attacker can + control (or at least guess) the PID and clock of the + application, and drain the system's entropy pool to reduce + the "up to 16 bytes" above to 0. Then the dependencies of the + inital states of the pools are completely known. Note that + this is not an issue if random of `GCRY_VERY_STRONG_RANDOM' + quality is requested as in this case enough extra entropy + gets mixed. It is also not an issue when using Linux + (rndlinux driver), because this one guarantees to read full + 16 bytes from /dev/urandom and thus there is no way for an + attacker without kernel access to control these 16 bytes. + + `GCRYCTL_SET_VERBOSITY; Arguments: int level' + This command sets the verbosity of the logging. A level of 0 + disables all extra logging whereas positive numbers enable + more verbose logging. The level may be changed at any time + but be aware that no memory synchronization is done so the + effect of this command might not immediately show up in other + threads. This command may even be used prior to + `gcry_check_version'. + + `GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags' + Set the debug flag bits as given by the argument. Be aware + that that no memory synchronization is done so the effect of + this command might not immediately show up in other threads. + The debug flags are not considered part of the API and thus + may change without notice. As of now bit 0 enables debugging + of cipher functions and bit 1 debugging of + multi-precision-integers. This command may even be used + prior to `gcry_check_version'. + + `GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags' + Set the debug flag bits as given by the argument. Be aware + that that no memory synchronization is done so the effect of + this command might not immediately show up in other threads. + This command may even be used prior to `gcry_check_version'. + + `GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none' + This command does nothing. It exists only for backward + compatibility. + + `GCRYCTL_ANY_INITIALIZATION_P; Arguments: none' + This command returns true if the library has been basically + initialized. Such a basic initialization happens implicitly + with many commands to get certain internal subsystems + running. The common and suggested way to do this basic + intialization is by calling gcry_check_version. + + `GCRYCTL_INITIALIZATION_FINISHED; Arguments: none' + This command tells the libray that the application has + finished the intialization. + + `GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none' + This command returns true if the command + GCRYCTL_INITIALIZATION_FINISHED has already been run. + + `GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops' + This command registers a thread-callback structure. *Note + Multi-Threading::. + + `GCRYCTL_FAST_POLL; Arguments: none' + Run a fast random poll. + + `GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename' + This command may be used to override the default name of the + EGD socket to connect to. It may be used only during + initialization as it is not thread safe. Changing the socket + name again is not supported. The function may return an + error if the given filename is too long for a local socket + name. + + EGD is an alternative random gatherer, used only on systems + lacking a proper random device. + + `GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream' + This command dumps information pertaining to the + configuration of the library to the given stream. If NULL is + given for STREAM, the log system is used. This command may + be used before the intialization has been finished but not + before a gcry_version_check. + + `GCRYCTL_OPERATIONAL_P; Arguments: none' + This command returns true if the library is in an operational + state. This information makes only sense in FIPS mode. In + contrast to other functions, this is a pure test function and + won't put the library into FIPS mode or change the internal + state. This command may be used before the intialization has + been finished but not before a gcry_version_check. + + `GCRYCTL_FIPS_MODE_P; Arguments: none' + This command returns true if the library is in FIPS mode. + Note, that this is no indication about the current state of + the library. This command may be used before the + intialization has been finished but not before a + gcry_version_check. An application may use this command or + the convenience macro below to check whether FIPS mode is + actually active. + + -- Function: int gcry_fips_mode_active (void) + Returns true if the FIPS mode is active. Note that this + is implemented as a macro. + + `GCRYCTL_FORCE_FIPS_MODE; Arguments: none' + Running this command puts the library into FIPS mode. If the + library is already in FIPS mode, a self-test is triggered and + thus the library will be put into operational state. This + command may be used before a call to gcry_check_version and + that is actually the recommended way to let an application + switch the library into FIPS mode. Note that Libgcrypt will + reject an attempt to switch to fips mode during or after the + intialization. + + `GCRYCTL_SELFTEST; Arguments: none' + This may be used at anytime to have the library run all + implemented self-tests. It works in standard and in FIPS + mode. Returns 0 on success or an error code on failure. + + + + +File: gcrypt.info, Node: Modules, Next: Error Handling, Prev: Controlling the library, Up: Generalities + +3.2 Modules +=========== + +Libgcrypt supports the use of `extension modules', which implement +algorithms in addition to those already built into the library directly. + + -- Data type: gcry_module_t + This data type represents a `module'. + + Functions registering modules provided by the user take a `module +specification structure' as input and return a value of `gcry_module_t' +and an ID that is unique in the modules' category. This ID can be used +to reference the newly registered module. After registering a module +successfully, the new functionality should be able to be used through +the normal functions provided by Libgcrypt until it is unregistered +again. + + +File: gcrypt.info, Node: Error Handling, Prev: Modules, Up: Generalities + +3.3 Error Handling +================== + +Many functions in Libgcrypt can return an error if they fail. For this +reason, the application should always catch the error condition and +take appropriate measures, for example by releasing the resources and +passing the error up to the caller, or by displaying a descriptive +message to the user and cancelling the operation. + + Some error values do not indicate a system error or an error in the +operation, but the result of an operation that failed properly. For +example, if you try to decrypt a tempered message, the decryption will +fail. Another error value actually means that the end of a data buffer +or list has been reached. The following descriptions explain for many +error codes what they mean usually. Some error values have specific +meanings if returned by a certain functions. Such cases are described +in the documentation of those functions. + + Libgcrypt uses the `libgpg-error' library. This allows to share the +error codes with other components of the GnuPG system, and to pass +error values transparently from the crypto engine, or some helper +application of the crypto engine, to the user. This way no information +is lost. As a consequence, Libgcrypt does not use its own identifiers +for error codes, but uses those provided by `libgpg-error'. They +usually start with `GPG_ERR_'. + + However, Libgcrypt does provide aliases for the functions defined in +libgpg-error, which might be preferred for name space consistency. + + Most functions in Libgcrypt return an error code in the case of +failure. For this reason, the application should always catch the +error condition and take appropriate measures, for example by releasing +the resources and passing the error up to the caller, or by displaying +a descriptive message to the user and canceling the operation. + + Some error values do not indicate a system error or an error in the +operation, but the result of an operation that failed properly. + + GnuPG components, including Libgcrypt, use an extra library named +libgpg-error to provide a common error handling scheme. For more +information on libgpg-error, see the according manual. + +* Menu: + +* Error Values:: The error value and what it means. +* Error Sources:: A list of important error sources. +* Error Codes:: A list of important error codes. +* Error Strings:: How to get a descriptive string from a value. + + +File: gcrypt.info, Node: Error Values, Next: Error Sources, Up: Error Handling + +3.3.1 Error Values +------------------ + + -- Data type: gcry_err_code_t + The `gcry_err_code_t' type is an alias for the `libgpg-error' type + `gpg_err_code_t'. The error code indicates the type of an error, + or the reason why an operation failed. + + A list of important error codes can be found in the next section. + + -- Data type: gcry_err_source_t + The `gcry_err_source_t' type is an alias for the `libgpg-error' + type `gpg_err_source_t'. The error source has not a precisely + defined meaning. Sometimes it is the place where the error + happened, sometimes it is the place where an error was encoded + into an error value. Usually the error source will give an + indication to where to look for the problem. This is not always + true, but it is attempted to achieve this goal. + + A list of important error sources can be found in the next section. + + -- Data type: gcry_error_t + The `gcry_error_t' type is an alias for the `libgpg-error' type + `gpg_error_t'. An error value like this has always two + components, an error code and an error source. Both together form + the error value. + + Thus, the error value can not be directly compared against an error + code, but the accessor functions described below must be used. + However, it is guaranteed that only 0 is used to indicate success + (`GPG_ERR_NO_ERROR'), and that in this case all other parts of the + error value are set to 0, too. + + Note that in Libgcrypt, the error source is used purely for + diagnostic purposes. Only the error code should be checked to test + for a certain outcome of a function. The manual only documents the + error code part of an error value. The error source is left + unspecified and might be anything. + + -- Function: gcry_err_code_t gcry_err_code (gcry_error_t ERR) + The static inline function `gcry_err_code' returns the + `gcry_err_code_t' component of the error value ERR. This function + must be used to extract the error code from an error value in + order to compare it with the `GPG_ERR_*' error code macros. + + -- Function: gcry_err_source_t gcry_err_source (gcry_error_t ERR) + The static inline function `gcry_err_source' returns the + `gcry_err_source_t' component of the error value ERR. This + function must be used to extract the error source from an error + value in order to compare it with the `GPG_ERR_SOURCE_*' error + source macros. + + -- Function: gcry_error_t gcry_err_make (gcry_err_source_t SOURCE, + gcry_err_code_t CODE) + The static inline function `gcry_err_make' returns the error value + consisting of the error source SOURCE and the error code CODE. + + This function can be used in callback functions to construct an + error value to return it to the library. + + -- Function: gcry_error_t gcry_error (gcry_err_code_t CODE) + The static inline function `gcry_error' returns the error value + consisting of the default error source and the error code CODE. + + For GCRY applications, the default error source is + `GPG_ERR_SOURCE_USER_1'. You can define `GCRY_ERR_SOURCE_DEFAULT' + before including `gcrypt.h' to change this default. + + This function can be used in callback functions to construct an + error value to return it to the library. + + The `libgpg-error' library provides error codes for all system error +numbers it knows about. If ERR is an unknown error number, the error +code `GPG_ERR_UNKNOWN_ERRNO' is used. The following functions can be +used to construct error values from system errno numbers. + + -- Function: gcry_error_t gcry_err_make_from_errno + (gcry_err_source_t SOURCE, int ERR) + The function `gcry_err_make_from_errno' is like `gcry_err_make', + but it takes a system error like `errno' instead of a + `gcry_err_code_t' error code. + + -- Function: gcry_error_t gcry_error_from_errno (int ERR) + The function `gcry_error_from_errno' is like `gcry_error', but it + takes a system error like `errno' instead of a `gcry_err_code_t' + error code. + + Sometimes you might want to map system error numbers to error codes +directly, or map an error code representing a system error back to the +system error number. The following functions can be used to do that. + + -- Function: gcry_err_code_t gcry_err_code_from_errno (int ERR) + The function `gcry_err_code_from_errno' returns the error code for + the system error ERR. If ERR is not a known system error, the + function returns `GPG_ERR_UNKNOWN_ERRNO'. + + -- Function: int gcry_err_code_to_errno (gcry_err_code_t ERR) + The function `gcry_err_code_to_errno' returns the system error for + the error code ERR. If ERR is not an error code representing a + system error, or if this system error is not defined on this + system, the function returns `0'. + + +File: gcrypt.info, Node: Error Sources, Next: Error Codes, Prev: Error Values, Up: Error Handling + +3.3.2 Error Sources +------------------- + +The library `libgpg-error' defines an error source for every component +of the GnuPG system. The error source part of an error value is not +well defined. As such it is mainly useful to improve the diagnostic +error message for the user. + + If the error code part of an error value is `0', the whole error +value will be `0'. In this case the error source part is of course +`GPG_ERR_SOURCE_UNKNOWN'. + + The list of error sources that might occur in applications using +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'. + + +File: gcrypt.info, Node: Error Codes, Next: Error Strings, Prev: Error Sources, Up: Error Handling + +3.3.3 Error Codes +----------------- + +The library `libgpg-error' defines many error values. The following +list includes the most important error codes. + +`GPG_ERR_EOF' + This value indicates the end of a list, buffer or file. + +`GPG_ERR_NO_ERROR' + This value indicates success. The value of this error code is + `0'. Also, it is guaranteed that an error value made from the + error code `0' will be `0' itself (as a whole). This means that + the error source information is lost for this error code, however, + as this error code indicates that no error occurred, this is + generally not a problem. + +`GPG_ERR_GENERAL' + This value means that something went wrong, but either there is not + enough information about the problem to return a more useful error + value, or there is no separate error value for this type of + problem. + +`GPG_ERR_ENOMEM' + This value means that an out-of-memory condition occurred. + +`GPG_ERR_E...' + System errors are mapped to GPG_ERR_EFOO where FOO is the symbol + for the system error. + +`GPG_ERR_INV_VALUE' + This value means that some user provided data was out of range. + +`GPG_ERR_UNUSABLE_PUBKEY' + This value means that some recipients for a message were invalid. + +`GPG_ERR_UNUSABLE_SECKEY' + This value means that some signers were invalid. + +`GPG_ERR_NO_DATA' + This value means that data was expected where no data was found. + +`GPG_ERR_CONFLICT' + This value means that a conflict of some sort occurred. + +`GPG_ERR_NOT_IMPLEMENTED' + This value indicates that the specific function (or operation) is + not implemented. This error should never happen. It can only + occur if you use certain values or configuration options which do + not work, but for which we think that they should work at some + later time. + +`GPG_ERR_DECRYPT_FAILED' + This value indicates that a decryption operation was unsuccessful. + +`GPG_ERR_WRONG_KEY_USAGE' + This value indicates that a key is not used appropriately. + +`GPG_ERR_NO_SECKEY' + This value indicates that no secret key for the user ID is + available. + +`GPG_ERR_UNSUPPORTED_ALGORITHM' + This value means a verification failed because the cryptographic + algorithm is not supported by the crypto backend. + +`GPG_ERR_BAD_SIGNATURE' + This value means a verification failed because the signature is + bad. + +`GPG_ERR_NO_PUBKEY' + This value means a verification failed because the public key is + not available. + +`GPG_ERR_NOT_OPERATIONAL' + This value means that the library is not yet in state which allows + to use this function. This error code is in particular returned if + Libgcrypt is operated in FIPS mode and the internal state of the + library does not yet or not anymore allow the use of a service. + + This error code is only available with newer libgpg-error + versions, thus you might see "invalid error code" when passing + this to `gpg_strerror'. The numeric value of this error code is + 176. + +`GPG_ERR_USER_1' + +`GPG_ERR_USER_2' + +`...' + +`GPG_ERR_USER_16' + These error codes are not used by any GnuPG component and can be + freely used by other software. Applications using Libgcrypt might + use them to mark specific errors returned by callback handlers if + no suitable error codes (including the system errors) for these + errors exist already. + + +File: gcrypt.info, Node: Error Strings, Prev: Error Codes, Up: Error Handling + +3.3.4 Error Strings +------------------- + + -- Function: const char * gcry_strerror (gcry_error_t ERR) + The function `gcry_strerror' returns a pointer to a statically + allocated string containing a description of the error code + contained in the error value ERR. This string can be used to + output a diagnostic message to the user. + + -- Function: const char * gcry_strsource (gcry_error_t ERR) + The function `gcry_strerror' returns a pointer to a statically + allocated string containing a description of the error source + contained in the error value ERR. This string can be used to + output a diagnostic message to the user. + + The following example illustrates the use of the functions described +above: + + { + gcry_cipher_hd_t handle; + gcry_error_t err = 0; + + err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, + GCRY_CIPHER_MODE_CBC, 0); + if (err) + { + fprintf (stderr, "Failure: %s/%s\n", + gcry_strsource (err), + gcry_strerror (err)); + } + } + + +File: gcrypt.info, Node: Handler Functions, Next: Symmetric cryptography, Prev: Generalities, Up: Top + +4 Handler Functions +******************* + +Libgcrypt makes it possible to install so called `handler functions', +which get called by Libgcrypt in case of certain events. + +* Menu: + +* Progress handler:: Using a progress handler function. +* Allocation handler:: Using special memory allocation functions. +* Error handler:: Using error handler functions. +* Logging handler:: Using a special logging function. + + +File: gcrypt.info, Node: Progress handler, Next: Allocation handler, Up: Handler Functions + +4.1 Progress handler +==================== + +It is often useful to retrieve some feedback while long running +operations are performed. + + -- Data type: gcry_handler_progress_t + Progress handler functions have to be of the type + `gcry_handler_progress_t', which is defined as: + + `void (*gcry_handler_progress_t) (void *, const char *, int, int, + int)' + + The following function may be used to register a handler function for +this purpose. + + -- Function: void gcry_set_progress_handler (gcry_handler_progress_t + CB, void *CB_DATA) + This function installs CB as the `Progress handler' function. It + may be used only during initialization. CB must be defined as + follows: + + void + my_progress_handler (void *CB_DATA, const char *WHAT, + int PRINTCHAR, int CURRENT, int TOTAL) + { + /* Do something. */ + } + + A description of the arguments of the progress handler function + follows. + + CB_DATA + The argument provided in the call to + `gcry_set_progress_handler'. + + WHAT + A string identifying the type of the progress output. The + following values for WHAT are defined: + + `need_entropy' + Not enough entropy is available. TOTAL holds the number + of required bytes. + + `primegen' + Values for PRINTCHAR: + `\n' + Prime generated. + + `!' + Need to refresh the pool of prime numbers. + + `<, >' + Number of bits adjusted. + + `^' + Searching for a generator. + + `.' + Fermat test on 10 candidates failed. + + `:' + Restart with a new random value. + + `+' + Rabin Miller test passed. + + + + +File: gcrypt.info, Node: Allocation handler, Next: Error handler, Prev: Progress handler, Up: Handler Functions + +4.2 Allocation handler +====================== + +It is possible to make Libgcrypt use special memory allocation +functions instead of the built-in ones. + + Memory allocation functions are of the following types: + + -- Data type: gcry_handler_alloc_t + This type is defined as: `void *(*gcry_handler_alloc_t) (size_t + n)'. + + -- Data type: gcry_handler_secure_check_t + This type is defined as: `int *(*gcry_handler_secure_check_t) + (const void *)'. + + -- Data type: gcry_handler_realloc_t + This type is defined as: `void *(*gcry_handler_realloc_t) (void + *p, size_t n)'. + + -- Data type: gcry_handler_free_t + This type is defined as: `void *(*gcry_handler_free_t) (void *)'. + + Special memory allocation functions can be installed with the +following function: + + -- Function: void gcry_set_allocation_handler (gcry_handler_alloc_t + FUNC_ALLOC, gcry_handler_alloc_t FUNC_ALLOC_SECURE, + gcry_handler_secure_check_t FUNC_SECURE_CHECK, + gcry_handler_realloc_t FUNC_REALLOC, gcry_handler_free_t + FUNC_FREE) + Install the provided functions and use them instead of the built-in + functions for doing memory allocation. Using this function is in + general not recommended because the standard Libgcrypt allocation + functions are guaranteed to zeroize memory if needed. + + This function may be used only during initialization and may not be + used in fips mode. + + + +File: gcrypt.info, Node: Error handler, Next: Logging handler, Prev: Allocation handler, Up: Handler Functions + +4.3 Error handler +================= + +The following functions may be used to register handler functions that +are called by Libgcrypt in case certain error conditions occur. They +may and should be registered prior to calling `gcry_check_version'. + + -- Data type: gcry_handler_no_mem_t + This type is defined as: `int (*gcry_handler_no_mem_t) (void *, + size_t, unsigned int)' + + -- Function: void gcry_set_outofcore_handler (gcry_handler_no_mem_t + FUNC_NO_MEM, void *CB_DATA) + This function registers FUNC_NO_MEM as `out-of-core handler', + which means that it will be called in the case of not having enough + memory available. The handler is called with 3 arguments: The + first one is the pointer CB_DATA as set with this function, the + second is the requested memory size and the last being a flag. If + bit 0 of the flag is set, secure memory has been requested. The + handler should either return true to indicate that Libgcrypt + should try again allocating memory or return false to let + Libgcrypt use its default fatal error handler. + + -- Data type: gcry_handler_error_t + This type is defined as: `void (*gcry_handler_error_t) (void *, + int, const char *)' + + -- Function: void gcry_set_fatalerror_handler (gcry_handler_error_t + FUNC_ERROR, void *CB_DATA) + This function registers FUNC_ERROR as `error handler', which means + that it will be called in error conditions. + + +File: gcrypt.info, Node: Logging handler, Prev: Error handler, Up: Handler Functions + +4.4 Logging handler +=================== + + -- Data type: gcry_handler_log_t + This type is defined as: `void (*gcry_handler_log_t) (void *, int, + const char *, va_list)' + + -- Function: void gcry_set_log_handler (gcry_handler_log_t FUNC_LOG, + void *CB_DATA) + This function registers FUNC_LOG as `logging handler', which means + that it will be called in case Libgcrypt wants to log a message. + This function may and should be used prior to calling + `gcry_check_version'. + + +File: gcrypt.info, Node: Symmetric cryptography, Next: Public Key cryptography, Prev: Handler Functions, Up: Top + +5 Symmetric cryptography +************************ + +The cipher functions are used for symmetrical cryptography, i.e. +cryptography using a shared key. The programming model follows an +open/process/close paradigm and is in that similar to other building +blocks provided by Libgcrypt. + +* Menu: + +* Available ciphers:: List of ciphers supported by the library. +* Cipher modules:: How to work with cipher modules. +* Available cipher modes:: List of cipher modes supported by the library. +* Working with cipher handles:: How to perform operations related to cipher handles. +* General cipher functions:: General cipher functions independent of cipher handles. + + +File: gcrypt.info, Node: Available ciphers, Next: Cipher modules, Up: Symmetric cryptography + +5.1 Available ciphers +===================== + +`GCRY_CIPHER_NONE' + This is not a real algorithm but used by some functions as error + return. The value always evaluates to false. + +`GCRY_CIPHER_IDEA' + This is the IDEA algorithm. The constant is provided but there is + currently no implementation for it because the algorithm is + patented. + +`GCRY_CIPHER_3DES' + Triple-DES with 3 Keys as EDE. The key size of this algorithm is + 168 but you have to pass 192 bits because the most significant + bits of each byte are ignored. + +`GCRY_CIPHER_CAST5' + CAST128-5 block cipher algorithm. The key size is 128 bits. + +`GCRY_CIPHER_BLOWFISH' + The blowfish algorithm. The current implementation allows only for + a key size of 128 bits. + +`GCRY_CIPHER_SAFER_SK128' + Reserved and not currently implemented. + +`GCRY_CIPHER_DES_SK' + Reserved and not currently implemented. + +`GCRY_CIPHER_AES' +`GCRY_CIPHER_AES128' +`GCRY_CIPHER_RIJNDAEL' +`GCRY_CIPHER_RIJNDAEL128' + AES (Rijndael) with a 128 bit key. + +`GCRY_CIPHER_AES192' +`GCRY_CIPHER_RIJNDAEL192' + AES (Rijndael) with a 192 bit key. + +`GCRY_CIPHER_AES256' +`GCRY_CIPHER_RIJNDAEL256' + AES (Rijndael) with a 256 bit key. + +`GCRY_CIPHER_TWOFISH' + The Twofish algorithm with a 256 bit key. + +`GCRY_CIPHER_TWOFISH128' + The Twofish algorithm with a 128 bit key. + +`GCRY_CIPHER_ARCFOUR' + An algorithm which is 100% compatible with RSA Inc.'s RC4 + algorithm. Note that this is a stream cipher and must be used + very carefully to avoid a couple of weaknesses. + +`GCRY_CIPHER_DES' + Standard DES with a 56 bit key. You need to pass 64 bit but the + high bits of each byte are ignored. Note, that this is a weak + algorithm which can be broken in reasonable time using a brute + force approach. + +`GCRY_CIPHER_SERPENT128' +`GCRY_CIPHER_SERPENT192' +`GCRY_CIPHER_SERPENT256' + The Serpent cipher from the AES contest. + +`GCRY_CIPHER_RFC2268_40' +`GCRY_CIPHER_RFC2268_128' + Ron's Cipher 2 in the 40 and 128 bit variants. Note, that we + currently only support the 40 bit variant. The identifier for 128 + is reserved for future use. + +`GCRY_CIPHER_SEED' + A 128 bit cipher as described by RFC4269. + +`GCRY_CIPHER_CAMELLIA128' +`GCRY_CIPHER_CAMELLIA192' +`GCRY_CIPHER_CAMELLIA256' + The Camellia cipher by NTT. See + `http://info.isl.ntt.co.jp/crypt/eng/camellia/specifications.html'. + + + +File: gcrypt.info, Node: Cipher modules, Next: Available cipher modes, Prev: Available ciphers, Up: Symmetric cryptography + +5.2 Cipher modules +================== + +Libgcrypt makes it possible to load additional `cipher modules'; these +ciphers can be used just like the cipher algorithms that are built into +the library directly. For an introduction into extension modules, see +*Note Modules::. + + -- Data type: gcry_cipher_spec_t + This is the `module specification structure' needed for registering + cipher modules, which has to be filled in by the user before it + can be used to register a module. It contains the following + members: + + `const char *name' + The primary name of the algorithm. + + `const char **aliases' + A list of strings that are `aliases' for the algorithm. The + list must be terminated with a NULL element. + + `gcry_cipher_oid_spec_t *oids' + A list of OIDs that are to be associated with the algorithm. + The list's last element must have it's `oid' member set to + NULL. See below for an explanation of this type. + + `size_t blocksize' + The block size of the algorithm, in bytes. + + `size_t keylen' + The length of the key, in bits. + + `size_t contextsize' + The size of the algorithm-specific `context', that should be + allocated for each handle. + + `gcry_cipher_setkey_t setkey' + The function responsible for initializing a handle with a + provided key. See below for a description of this type. + + `gcry_cipher_encrypt_t encrypt' + The function responsible for encrypting a single block. See + below for a description of this type. + + `gcry_cipher_decrypt_t decrypt' + The function responsible for decrypting a single block. See + below for a description of this type. + + `gcry_cipher_stencrypt_t stencrypt' + Like `encrypt', for stream ciphers. See below for a + description of this type. + + `gcry_cipher_stdecrypt_t stdecrypt' + Like `decrypt', for stream ciphers. See below for a + description of this type. + + -- Data type: gcry_cipher_oid_spec_t + This type is used for associating a user-provided algorithm + implementation with certain OIDs. It contains the following + members: + `const char *oid' + Textual representation of the OID. + + `int mode' + Cipher mode for which this OID is valid. + + -- Data type: gcry_cipher_setkey_t + Type for the `setkey' function, defined as: gcry_err_code_t + (*gcry_cipher_setkey_t) (void *c, const unsigned char *key, + unsigned keylen) + + -- Data type: gcry_cipher_encrypt_t + Type for the `encrypt' function, defined as: gcry_err_code_t + (*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, + const unsigned char *inbuf) + + -- Data type: gcry_cipher_decrypt_t + Type for the `decrypt' function, defined as: gcry_err_code_t + (*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, + const unsigned char *inbuf) + + -- Data type: gcry_cipher_stencrypt_t + Type for the `stencrypt' function, defined as: gcry_err_code_t + (*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, + const unsigned char *, unsigned int n) + + -- Data type: gcry_cipher_stdecrypt_t + Type for the `stdecrypt' function, defined as: gcry_err_code_t + (*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, + const unsigned char *, unsigned int n) + + -- Function: gcry_error_t gcry_cipher_register (gcry_cipher_spec_t + *CIPHER, unsigned int *algorithm_id, gcry_module_t *MODULE) + Register a new cipher module whose specification can be found in + CIPHER. On success, a new algorithm ID is stored in ALGORITHM_ID + and a pointer representing this module is stored in MODULE. + + -- Function: void gcry_cipher_unregister (gcry_module_t MODULE) + Unregister the cipher identified by MODULE, which must have been + registered with gcry_cipher_register. + + -- Function: gcry_error_t gcry_cipher_list (int *LIST, int + *LIST_LENGTH) + Get a list consisting of the IDs of the loaded cipher modules. If + LIST is zero, write the number of loaded cipher modules to + LIST_LENGTH and return. If LIST is non-zero, the first + *LIST_LENGTH algorithm IDs are stored in LIST, which must be of + according size. In case there are less cipher modules than + *LIST_LENGTH, *LIST_LENGTH is updated to the correct number. + + +File: gcrypt.info, Node: Available cipher modes, Next: Working with cipher handles, Prev: Cipher modules, Up: Symmetric cryptography + +5.3 Available cipher modes +========================== + +`GCRY_CIPHER_MODE_NONE' + No mode specified. This should not be used. The only exception + is that if Libgcrypt is not used in FIPS mode and if any debug + flag has been set, this mode may be used to bypass the actual + encryption. + +`GCRY_CIPHER_MODE_ECB' + Electronic Codebook mode. + +`GCRY_CIPHER_MODE_CFB' + Cipher Feedback mode. The shift size equals the block size of the + cipher (e.g. for AES it is CFB-128). + +`GCRY_CIPHER_MODE_CBC' + Cipher Block Chaining mode. + +`GCRY_CIPHER_MODE_STREAM' + Stream mode, only to be used with stream cipher algorithms. + +`GCRY_CIPHER_MODE_OFB' + Output Feedback mode. + +`GCRY_CIPHER_MODE_CTR' + Counter mode. + + + +File: gcrypt.info, Node: Working with cipher handles, Next: General cipher functions, Prev: Available cipher modes, Up: Symmetric cryptography + +5.4 Working with cipher handles +=============================== + +To use a cipher algorithm, you must first allocate an according handle. +This is to be done using the open function: + + -- Function: gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *HD, int + ALGO, int MODE, unsigned int FLAGS) + This function creates the context handle required for most of the + other cipher functions and returns a handle to it in `hd'. In + case of an error, an according error code is returned. + + The ID of algorithm to use must be specified via ALGO. See *Note + Available ciphers::, for a list of supported ciphers and the + according constants. + + Besides using the constants directly, the function + `gcry_cipher_map_name' may be used to convert the textual name of + an algorithm into the according numeric ID. + + The cipher mode to use must be specified via MODE. See *Note + Available cipher modes::, for a list of supported cipher modes and + the according constants. Note that some modes are incompatible + with some algorithms - in particular, stream mode + (`GCRY_CIPHER_MODE_STREAM') only works with stream ciphers. Any + block cipher mode (`GCRY_CIPHER_MODE_ECB', `GCRY_CIPHER_MODE_CBC', + `GCRY_CIPHER_MODE_CFB', `GCRY_CIPHER_MODE_OFB' or + `GCRY_CIPHER_MODE_CTR') will work with any block cipher algorithm. + + The third argument FLAGS can either be passed as `0' or as the + bit-wise OR of the following constants. + + `GCRY_CIPHER_SECURE' + Make sure that all operations are allocated in secure memory. + This is useful when the key material is highly confidential. + + `GCRY_CIPHER_ENABLE_SYNC' + This flag enables the CFB sync mode, which is a special + feature of Libgcrypt's CFB mode implementation to allow for + OpenPGP's CFB variant. See `gcry_cipher_sync'. + + `GCRY_CIPHER_CBC_CTS' + Enable cipher text stealing (CTS) for the CBC mode. Cannot + be used simultaneous as GCRY_CIPHER_CBC_MAC. CTS mode makes + it possible to transform data of almost arbitrary size (only + limitation is that it must be greater than the algorithm's + block size). + + `GCRY_CIPHER_CBC_MAC' + Compute CBC-MAC keyed checksums. This is the same as CBC + mode, but only output the last block. Cannot be used + simultaneous as GCRY_CIPHER_CBC_CTS. + + Use the following function to release an existing handle: + + -- Function: void gcry_cipher_close (gcry_cipher_hd_t H) + This function releases the context created by `gcry_cipher_open'. + It also zeroises all sensitive information associated with this + cipher handle. + + In order to use a handle for performing cryptographic operations, a +`key' has to be set first: + + -- Function: gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t H, + const void *K, size_t L) + Set the key K used for encryption or decryption in the context + denoted by the handle H. The length L (in bytes) of the key K + must match the required length of the algorithm set for this + context or be in the allowed range for algorithms with variable + key size. The function checks this and returns an error if there + is a problem. A caller should always check for an error. + + + Most crypto modes requires an initialization vector (IV), which +usually is a non-secret random string acting as a kind of salt value. +The CTR mode requires a counter, which is also similar to a salt value. +To set the IV or CTR, use these functions: + + -- Function: gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t H, const + void *K, size_t L) + Set the initialization vector used for encryption or decryption. + The vector is passed as the buffer K of length L bytes and copied + to internal data structures. The function checks that the IV + matches the requirement of the selected algorithm and mode. + + -- Function: gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t H, + const void *C, size_t L) + Set the counter vector used for encryption or decryption. The + counter is passed as the buffer C of length L bytes and copied to + internal data structures. The function checks that the counter + matches the requirement of the selected algorithm (i.e., it must be + the same size as the block size). + + -- Function: gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t H) + Set the given handle's context back to the state it had after the + last call to gcry_cipher_setkey and clear the initialization + vector. + + Note that gcry_cipher_reset is implemented as a macro. + + The actual encryption and decryption is done by using one of the +following functions. They may be used as often as required to process +all the data. + + -- Function: gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t H, + unsigned char *out, size_t OUTSIZE, const unsigned char *IN, + size_t INLEN) + `gcry_cipher_encrypt' is used to encrypt the data. This function + can either work in place or with two buffers. It uses the cipher + context already setup and described by the handle H. There are 2 + ways to use the function: If IN is passed as `NULL' and INLEN is + `0', in-place encryption of the data in OUT or length OUTSIZE + takes place. With IN being not `NULL', INLEN bytes are encrypted + to the buffer OUT which must have at least a size of INLEN. + OUTSIZE must be set to the allocated size of OUT, so that the + function can check that there is sufficient space. Note that + overlapping buffers are not allowed. + + Depending on the selected algorithms and encryption mode, the + length of the buffers must be a multiple of the block size. + + The function returns `0' on success or an error code. + + -- Function: gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t H, + unsigned char *out, size_t OUTSIZE, const unsigned char *IN, + size_t INLEN) + `gcry_cipher_decrypt' is used to decrypt the data. This function + can either work in place or with two buffers. It uses the cipher + context already setup and described by the handle H. There are 2 + ways to use the function: If IN is passed as `NULL' and INLEN is + `0', in-place decryption of the data in OUT or length OUTSIZE + takes place. With IN being not `NULL', INLEN bytes are decrypted + to the buffer OUT which must have at least a size of INLEN. + OUTSIZE must be set to the allocated size of OUT, so that the + function can check that there is sufficient space. Note that + overlapping buffers are not allowed. + + Depending on the selected algorithms and encryption mode, the + length of the buffers must be a multiple of the block size. + + The function returns `0' on success or an error code. + + OpenPGP (as defined in RFC-2440) requires a special sync operation in +some places. The following function is used for this: + + -- Function: gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t H) + Perform the OpenPGP sync operation on context H. Note that this + is a no-op unless the context was created with the flag + `GCRY_CIPHER_ENABLE_SYNC' + + Some of the described functions are implemented as macros utilizing a +catch-all control function. This control function is rarely used +directly but there is nothing which would inhibit it: + + -- Function: gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t H, int + CMD, void *BUFFER, size_t BUFLEN) + `gcry_cipher_ctl' controls various aspects of the cipher module and + specific cipher contexts. Usually some more specialized functions + or macros are used for this purpose. The semantics of the + function and its parameters depends on the the command CMD and the + passed context handle H. Please see the comments in the source + code (`src/global.c') for details. + + -- Function: gcry_error_t gcry_cipher_info (gcry_cipher_hd_t H, int + WHAT, void *BUFFER, size_t *NBYTES) + `gcry_cipher_info' is used to retrieve various information about a + cipher context or the cipher module in general. + + Currently no information is available. + + +File: gcrypt.info, Node: General cipher functions, Prev: Working with cipher handles, Up: Symmetric cryptography + +5.5 General cipher functions +============================ + +To work with the algorithms, several functions are available to map +algorithm names to the internal identifiers, as well as ways to +retrieve information about an algorithm or the current cipher context. + + -- Function: gcry_error_t gcry_cipher_algo_info (int ALGO, int WHAT, + void *BUFFER, size_t *NBYTES) + This function is used to retrieve information on a specific + algorithm. You pass the cipher algorithm ID as ALGO and the type + of information requested as WHAT. The result is either returned as + the return code of the function or copied to the provided BUFFER + whose allocated length must be available in an integer variable + with the address passed in NBYTES. This variable will also + receive the actual used length of the buffer. + + Here is a list of supported codes for WHAT: + + `GCRYCTL_GET_KEYLEN:' + Return the length of the key. If the algorithm supports + multiple key lengths, the maximum supported value is + returned. The length is returned as number of octets (bytes) + and not as number of bits in NBYTES; BUFFER must be zero. + + `GCRYCTL_GET_BLKLEN:' + Return the block length of the algorithm. The length is + returned as a number of octets in NBYTES; BUFFER must be zero. + + `GCRYCTL_TEST_ALGO:' + Returns `0' when the specified algorithm is available for use. + BUFFER and NBYTES must be zero. + + + + -- Function: const char * gcry_cipher_algo_name (int ALGO) + `gcry_cipher_algo_name' returns a string with the name of the + cipher algorithm ALGO. If the algorithm is not known or another + error occurred, the string `"?"' is returned. This function should + not be used to test for the availability of an algorithm. + + -- Function: int gcry_cipher_map_name (const char *NAME) + `gcry_cipher_map_name' returns the algorithm identifier for the + cipher algorithm described by the string NAME. If this algorithm + is not available `0' is returned. + + -- Function: int gcry_cipher_mode_from_oid (const char *STRING) + Return the cipher mode associated with an ASN.1 object identifier. + The object identifier is expected to be in the IETF-style dotted + decimal notation. The function returns `0' for an unknown object + identifier or when no mode is associated with it. + + +File: gcrypt.info, Node: Public Key cryptography, Next: Hashing, Prev: Symmetric cryptography, Up: Top + +6 Public Key cryptography +************************* + +Public key cryptography, also known as asymmetric cryptography, is an +easy way for key management and to provide digital signatures. +Libgcrypt provides two completely different interfaces to public key +cryptography, this chapter explains the one based on S-expressions. + +* Menu: + +* Available algorithms:: Algorithms supported by the library. +* Used S-expressions:: Introduction into the used S-expression. +* Public key modules:: How to work with public key modules. +* Cryptographic Functions:: Functions for performing the cryptographic actions. +* General public-key related Functions:: General functions, not implementing any cryptography. + +* AC Interface:: Alternative interface to public key functions. + + +File: gcrypt.info, Node: Available algorithms, Next: Used S-expressions, Up: Public Key cryptography + +6.1 Available algorithms +======================== + +Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well +as DSA (Digital Signature Algorithm) and Elgamal. The versatile +interface allows to add more algorithms in the future. + + +File: gcrypt.info, Node: Used S-expressions, Next: Public key modules, Prev: Available algorithms, Up: Public Key cryptography + +6.2 Used S-expressions +====================== + +Libgcrypt's API for asymmetric cryptography is based on data structures +called S-expressions (see +`http://people.csail.mit.edu/rivest/sexp.html') and does not work with +contexts as most of the other building blocks of Libgcrypt do. + +The following information are stored in S-expressions: + + keys + + plain text data + + encrypted data + + signatures + + +To describe how Libgcrypt expect keys, we use examples. Note that words +in uppercase indicate parameters whereas lowercase words are literals. + + Note that all MPI (multi-precision-integers) values are expected to +be in `GCRYMPI_FMT_USG' format. An easy way to create S-expressions is +by using `gcry_sexp_build' which allows to pass a string with +printf-like escapes to insert MPI values. + +* Menu: + +* RSA key parameters:: Parameters used with an RSA key. +* DSA key parameters:: Parameters used with a DSA key. +* ECC key parameters:: Parameters used with ECC keys. + + +File: gcrypt.info, Node: RSA key parameters, Next: DSA key parameters, Up: Used S-expressions + +6.2.1 RSA key parameters +------------------------ + +An RSA private key is described by this S-expression: + + (private-key + (rsa + (n N-MPI) + (e E-MPI) + (d D-MPI) + (p P-MPI) + (q Q-MPI) + (u U-MPI))) + +An RSA public key is described by this S-expression: + + (public-key + (rsa + (n N-MPI) + (e E-MPI))) + +N-MPI + RSA public modulus n. + +E-MPI + RSA public exponent e. + +D-MPI + RSA secret exponent d = e^-1 \bmod (p-1)(q-1). + +P-MPI + RSA secret prime p. + +Q-MPI + RSA secret prime q with p < q. + +U-MPI + Multiplicative inverse u = p^-1 \bmod q. + + For signing and decryption the parameters (p, q, u) are optional but +greatly improve the performance. Either all of these optional +parameters must be given or none of them. They are mandatory for +gcry_pk_testkey. + + Note that OpenSSL uses slighly different parameters: q < p and u = +q^-1 \bmod p. To use these parameters you will need to swap the values +and recompute u. Here is example code to do this: + + if (gcry_mpi_cmp (p, q) > 0) + { + gcry_mpi_swap (p, q); + gcry_mpi_invm (u, p, q); + } + + +File: gcrypt.info, Node: DSA key parameters, Next: ECC key parameters, Prev: RSA key parameters, Up: Used S-expressions + +6.2.2 DSA key parameters +------------------------ + +A DSA private key is described by this S-expression: + + (private-key + (dsa + (p P-MPI) + (q Q-MPI) + (g G-MPI) + (y Y-MPI) + (x X-MPI))) + +P-MPI + DSA prime p. + +Q-MPI + DSA group order q (which is a prime divisor of p-1). + +G-MPI + DSA group generator g. + +Y-MPI + DSA public key value y = g^x \bmod p. + +X-MPI + DSA secret exponent x. + + The public key is similar with "private-key" replaced by "public-key" +and no X-MPI. + + +File: gcrypt.info, Node: ECC key parameters, Prev: DSA key parameters, Up: Used S-expressions + +6.2.3 ECC key parameters +------------------------ + +An ECC private key is described by this S-expression: + + (private-key + (ecc + (p P-MPI) + (a A-MPI) + (b B-MPI) + (g G-POINT) + (n N-MPI) + (q Q-POINT) + (d D-MPI))) + +P-MPI + Prime specifying the field GF(p). + +A-MPI +B-MPI + The two coefficients of the Weierstrass equation y^2 = x^3 + ax + b + +G-POINT + Base point g. + +N-MPI + Order of g + +Q-POINT + The point representing the public key Q = dP. + +D-MPI + The private key d + + All point values are encoded in standard format; Libgcrypt does +currently only support uncompressed points, thus the first byte needs to +be `0x04'. + + The public key is similar with "private-key" replaced by "public-key" +and no D-MPI. + + If the domain parameters are well-known, the name of this curve may +be used. For example + + (private-key + (ecc + (curve "NIST P-192") + (q Q-POINT) + (d D-MPI))) + + The `curve' parameter may be given in any case and is used to replace +missing parameters. + +Currently implemented curves are: +`NIST P-192' +`1.2.840.10045.3.1.1' +`prime192v1' +`secp192r1' + The NIST 192 bit curve, its OID, X9.62 and SECP aliases. + +`NIST P-224' +`secp224r1' + The NIST 224 bit curve and its SECP alias. + +`NIST P-256' +`1.2.840.10045.3.1.7' +`prime256v1' +`secp256r1' + The NIST 256 bit curve, its OID, X9.62 and SECP aliases. + +`NIST P-384' +`secp384r1' + The NIST 384 bit curve and its SECP alias. + +`NIST P-521' +`secp521r1' + The NIST 521 bit curve and its SECP alias. + + As usual the OIDs may optionally be prefixed with the string `OID.' +or `oid.'. + + +File: gcrypt.info, Node: Public key modules, Next: Cryptographic Functions, Prev: Used S-expressions, Up: Public Key cryptography + +6.3 Public key modules +====================== + +Libgcrypt makes it possible to load additional `public key modules'; +these public key algorithms can be used just like the algorithms that +are built into the library directly. For an introduction into +extension modules, see *Note Modules::. + + -- Data type: gcry_pk_spec_t + This is the `module specification structure' needed for registering + public key modules, which has to be filled in by the user before it + can be used to register a module. It contains the following + members: + + `const char *name' + The primary name of this algorithm. + + `char **aliases' + A list of strings that are `aliases' for the algorithm. The + list must be terminated with a NULL element. + + `const char *elements_pkey' + String containing the one-letter names of the MPI values + contained in a public key. + + `const char *element_skey' + String containing the one-letter names of the MPI values + contained in a secret key. + + `const char *elements_enc' + String containing the one-letter names of the MPI values that + are the result of an encryption operation using this + algorithm. + + `const char *elements_sig' + String containing the one-letter names of the MPI values that + are the result of a sign operation using this algorithm. + + `const char *elements_grip' + String containing the one-letter names of the MPI values that + are to be included in the `key grip'. + + `int use' + The bitwise-OR of the following flags, depending on the + abilities of the algorithm: + `GCRY_PK_USAGE_SIGN' + The algorithm supports signing and verifying of data. + + `GCRY_PK_USAGE_ENCR' + The algorithm supports the encryption and decryption of + data. + + `gcry_pk_generate_t generate' + The function responsible for generating a new key pair. See + below for a description of this type. + + `gcry_pk_check_secret_key_t check_secret_key' + The function responsible for checking the sanity of a + provided secret key. See below for a description of this + type. + + `gcry_pk_encrypt_t encrypt' + The function responsible for encrypting data. See below for a + description of this type. + + `gcry_pk_decrypt_t decrypt' + The function responsible for decrypting data. See below for a + description of this type. + + `gcry_pk_sign_t sign' + The function responsible for signing data. See below for a + description of this type. + + `gcry_pk_verify_t verify' + The function responsible for verifying that the provided + signature matches the provided data. See below for a + description of this type. + + `gcry_pk_get_nbits_t get_nbits' + The function responsible for returning the number of bits of + a provided key. See below for a description of this type. + + -- Data type: gcry_pk_generate_t + Type for the `generate' function, defined as: gcry_err_code_t + (*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long + use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors) + + -- Data type: gcry_pk_check_secret_key_t + Type for the `check_secret_key' function, defined as: + gcry_err_code_t (*gcry_pk_check_secret_key_t) (int algo, + gcry_mpi_t *skey) + + -- Data type: gcry_pk_encrypt_t + Type for the `encrypt' function, defined as: gcry_err_code_t + (*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t + data, gcry_mpi_t *pkey, int flags) + + -- Data type: gcry_pk_decrypt_t + Type for the `decrypt' function, defined as: gcry_err_code_t + (*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t + *data, gcry_mpi_t *skey, int flags) + + -- Data type: gcry_pk_sign_t + Type for the `sign' function, defined as: gcry_err_code_t + (*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data, + gcry_mpi_t *skey) + + -- Data type: gcry_pk_verify_t + Type for the `verify' function, defined as: gcry_err_code_t + (*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data, + gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev) + + -- Data type: gcry_pk_get_nbits_t + Type for the `get_nbits' function, defined as: unsigned + (*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey) + + -- Function: gcry_error_t gcry_pk_register (gcry_pk_spec_t *PUBKEY, + unsigned int *algorithm_id, gcry_module_t *MODULE) + Register a new public key module whose specification can be found + in PUBKEY. On success, a new algorithm ID is stored in + ALGORITHM_ID and a pointer representing this module is stored in + MODULE. + + -- Function: void gcry_pk_unregister (gcry_module_t MODULE) + Unregister the public key module identified by MODULE, which must + have been registered with gcry_pk_register. + + -- Function: gcry_error_t gcry_pk_list (int *LIST, int *LIST_LENGTH) + Get a list consisting of the IDs of the loaded pubkey modules. If + LIST is zero, write the number of loaded pubkey modules to + LIST_LENGTH and return. If LIST is non-zero, the first + *LIST_LENGTH algorithm IDs are stored in LIST, which must be of + according size. In case there are less pubkey modules than + *LIST_LENGTH, *LIST_LENGTH is updated to the correct number. + + +File: gcrypt.info, Node: Cryptographic Functions, Next: General public-key related Functions, Prev: Public key modules, Up: Public Key cryptography + +6.4 Cryptographic Functions +=========================== + +Note that we will in future allow to use keys without p,q and u +specified and may also support other parameters for performance reasons. + +Some functions operating on S-expressions support `flags', that +influence the operation. These flags have to be listed in a +sub-S-expression named `flags'; the following flags are known: + +`pkcs1' + Use PKCS#1 block type 2 padding. + +`no-blinding' + Do not use a technique called `blinding', which is used by default + in order to prevent leaking of secret information. Blinding is + only implemented by RSA, but it might be implemented by other + algorithms in the future as well, when necessary. + +Now that we know the key basics, we can carry on and explain how to +encrypt and decrypt data. In almost all cases the data is a random +session key which is in turn used for the actual encryption of the real +data. There are 2 functions to do this: + + -- Function: gcry_error_t gcry_pk_encrypt (gcry_sexp_t *R_CIPH, + gcry_sexp_t DATA, gcry_sexp_t PKEY) + Obviously a public key must be provided for encryption. It is + expected as an appropriate S-expression (see above) in PKEY. The + data to be encrypted can either be in the simple old format, which + is a very simple S-expression consisting only of one MPI, or it + may be a more complex S-expression which also allows to specify + flags for operation, like e.g. padding rules. + + If you don't want to let Libgcrypt handle the padding, you must + pass an appropriate MPI using this expression for DATA: + + (data + (flags raw) + (value MPI)) + + This has the same semantics as the old style MPI only way. MPI is + the actual data, already padded appropriate for your protocol. + Most systems however use PKCS#1 padding and so you can use this + S-expression for DATA: + + (data + (flags pkcs1) + (value BLOCK)) + + Here, the "flags" list has the "pkcs1" flag which let the function + know that it should provide PKCS#1 block type 2 padding. The + actual data to be encrypted is passed as a string of octets in + BLOCK. The function checks that this data actually can be used + with the given key, does the padding and encrypts it. + + If the function could successfully perform the encryption, the + return value will be 0 and a new S-expression with the encrypted + result is allocated and assigned to the variable at the address of + R_CIPH. The caller is responsible to release this value using + `gcry_sexp_release'. In case of an error, an error code is + returned and R_CIPH will be set to `NULL'. + + The returned S-expression has this format when used with RSA: + + (enc-val + (rsa + (a A-MPI))) + + Where A-MPI is an MPI with the result of the RSA operation. When + using the Elgamal algorithm, the return value will have this + format: + + (enc-val + (elg + (a A-MPI) + (b B-MPI))) + + Where A-MPI and B-MPI are MPIs with the result of the Elgamal + encryption operation. + + -- Function: gcry_error_t gcry_pk_decrypt (gcry_sexp_t *R_PLAIN, + gcry_sexp_t DATA, gcry_sexp_t SKEY) + Obviously a private key must be provided for decryption. It is + expected as an appropriate S-expression (see above) in SKEY. The + data to be decrypted must match the format of the result as + returned by `gcry_pk_encrypt', but should be enlarged with a + `flags' element: + + (enc-val + (flags) + (elg + (a A-MPI) + (b B-MPI))) + + Note that this function currently does not know of any padding + methods and the caller must do any un-padding on his own. + + The function returns 0 on success or an error code. The variable + at the address of R_PLAIN will be set to NULL on error or receive + the decrypted value on success. The format of R_PLAIN is a simple + S-expression part (i.e. not a valid one) with just one MPI if + there was no `flags' element in DATA; if at least an empty `flags' + is passed in DATA, the format is: + + (value PLAINTEXT) + + Another operation commonly performed using public key cryptography is +signing data. In some sense this is even more important than +encryption because digital signatures are an important instrument for +key management. Libgcrypt supports digital signatures using 2 +functions, similar to the encryption functions: + + -- Function: gcry_error_t gcry_pk_sign (gcry_sexp_t *R_SIG, + gcry_sexp_t DATA, gcry_sexp_t SKEY) + This function creates a digital signature for DATA using the + private key SKEY and place it into the variable at the address of + R_SIG. DATA may either be the simple old style S-expression with + just one MPI or a modern and more versatile S-expression which + allows to let Libgcrypt handle padding: + + (data + (flags pkcs1) + (hash HASH-ALGO BLOCK)) + + This example requests to sign the data in BLOCK after applying + PKCS#1 block type 1 style padding. HASH-ALGO is a string with the + hash algorithm to be encoded into the signature, this may be any + hash algorithm name as supported by Libgcrypt. Most likely, this + will be "sha256" or "sha1". It is obvious that the length of + BLOCK must match the size of that message digests; the function + checks that this and other constraints are valid. + + If PKCS#1 padding is not required (because the caller does already + provide a padded value), either the old format or better the + following format should be used: + + (data + (flags raw) + (value MPI)) + + Here, the data to be signed is directly given as an MPI. + + The signature is returned as a newly allocated S-expression in + R_SIG using this format for RSA: + + (sig-val + (rsa + (s S-MPI))) + + Where S-MPI is the result of the RSA sign operation. For DSA the + S-expression returned is: + + (sig-val + (dsa + (r R-MPI) + (s S-MPI))) + + Where R-MPI and S-MPI are the result of the DSA sign operation. + For Elgamal signing (which is slow, yields large numbers and + probably is not as secure as the other algorithms), the same + format is used with "elg" replacing "dsa". + +The operation most commonly used is definitely the verification of a +signature. Libgcrypt provides this function: + + -- Function: gcry_error_t gcry_pk_verify (gcry_sexp_t SIG, + gcry_sexp_t DATA, gcry_sexp_t PKEY) + This is used to check whether the signature SIG matches the DATA. + The public key PKEY must be provided to perform this verification. + This function is similar in its parameters to `gcry_pk_sign' with + the exceptions that the public key is used instead of the private + key and that no signature is created but a signature, in a format + as created by `gcry_pk_sign', is passed to the function in SIG. + + The result is 0 for success (i.e. the data matches the signature), + or an error code where the most relevant code is + `GCRYERR_BAD_SIGNATURE' to indicate that the signature does not + match the provided data. + + + +File: gcrypt.info, Node: General public-key related Functions, Next: AC Interface, Prev: Cryptographic Functions, Up: Public Key cryptography + +6.5 General public-key related Functions +======================================== + +A couple of utility functions are available to retrieve the length of +the key, map algorithm identifiers and perform sanity checks: + + -- Function: const char * gcry_pk_algo_name (int ALGO) + Map the public key algorithm id ALGO to a string representation of + the algorithm name. For unknown algorithms this functions returns + the string `"?"'. This function should not be used to test for the + availability of an algorithm. + + -- Function: int gcry_pk_map_name (const char *NAME) + Map the algorithm NAME to a public key algorithm Id. Returns 0 if + the algorithm name is not known. + + -- Function: int gcry_pk_test_algo (int ALGO) + Return 0 if the public key algorithm ALGO is available for use. + Note that this is implemented as a macro. + + -- Function: unsigned int gcry_pk_get_nbits (gcry_sexp_t KEY) + Return what is commonly referred as the key length for the given + public or private in KEY. + + -- Function: unsigned char * gcry_pk_get_keygrip (gcry_sexp_t KEY, + unsigned char *ARRAY) + Return the so called "keygrip" which is the SHA-1 hash of the + public key parameters expressed in a way depended on the + algorithm. ARRAY must either provide space for 20 bytes or be + `NULL'. In the latter case a newly allocated array of that size is + returned. On success a pointer to the newly allocated space or to + ARRAY is returned. `NULL' is returned to indicate an error which + is most likely an unknown algorithm or one where a "keygrip" has + not yet been defined. The function accepts public or secret keys + in KEY. + + -- Function: gcry_error_t gcry_pk_testkey (gcry_sexp_t KEY) + Return zero if the private key KEY is `sane', an error code + otherwise. Note that it is not possible to check the `saneness' + of a public key. + + + -- Function: gcry_error_t gcry_pk_algo_info (int ALGO, int WHAT, + void *BUFFER, size_t *NBYTES) + Depending on the value of WHAT return various information about + the public key algorithm with the id ALGO. Note that the function + returns `-1' on error and the actual error code must be retrieved + using the function `gcry_errno'. The currently defined values for + WHAT are: + + `GCRYCTL_TEST_ALGO:' + Return 0 if the specified algorithm is available for use. + BUFFER must be `NULL', NBYTES may be passed as `NULL' or + point to a variable with the required usage of the algorithm. + This may be 0 for "don't care" or the bit-wise OR of these + flags: + + `GCRY_PK_USAGE_SIGN' + Algorithm is usable for signing. + + `GCRY_PK_USAGE_ENCR' + Algorithm is usable for encryption. + + Unless you need to test for the allowed usage, it is in + general better to use the macro gcry_pk_test_algo instead. + + `GCRYCTL_GET_ALGO_USAGE:' + Return the usage flags for the given algorithm. An invalid + algorithm return 0. Disabled algorithms are ignored here + because we want to know whether the algorithm is at all + capable of a certain usage. + + `GCRYCTL_GET_ALGO_NPKEY' + Return the number of elements the public key for algorithm + ALGO consist of. Return 0 for an unknown algorithm. + + `GCRYCTL_GET_ALGO_NSKEY' + Return the number of elements the private key for algorithm + ALGO consist of. Note that this value is always larger than + that of the public key. Return 0 for an unknown algorithm. + + `GCRYCTL_GET_ALGO_NSIGN' + Return the number of elements a signature created with the + algorithm ALGO consists of. Return 0 for an unknown + algorithm or for an algorithm not capable of creating + signatures. + + `GCRYCTL_GET_ALGO_NENC' + Return the number of elements a encrypted message created + with the algorithm ALGO consists of. Return 0 for an unknown + algorithm or for an algorithm not capable of encryption. + + Please note that parameters not required should be passed as + `NULL'. + + -- Function: gcry_error_t gcry_pk_ctl (int CMD, void *BUFFER, + size_t BUFLEN) + This is a general purpose function to perform certain control + operations. CMD controls what is to be done. The return value is + 0 for success or an error code. Currently supported values for + CMD are: + + `GCRYCTL_DISABLE_ALGO' + Disable the algorithm given as an algorithm id in BUFFER. + BUFFER must point to an `int' variable with the algorithm id + and BUFLEN must have the value `sizeof (int)'. + + +Libgcrypt also provides a function to generate public key pairs: + + -- Function: gcry_error_t gcry_pk_genkey (gcry_sexp_t *R_KEY, + gcry_sexp_t PARMS) + This function create a new public key pair using information given + in the S-expression PARMS and stores the private and the public key + in one new S-expression at the address given by R_KEY. In case of + an error, R_KEY is set to `NULL'. The return code is 0 for + success or an error code otherwise. + + Here is an example for PARMS to create an 2048 bit RSA key: + + (genkey + (rsa + (nbits 4:2048))) + + To create an Elgamal key, substitute "elg" for "rsa" and to create + a DSA key use "dsa". Valid ranges for the key length depend on the + algorithms; all commonly used key lengths are supported. Currently + supported parameters are: + + `nbits' + This is always required to specify the length of the key. + The argument is a string with a number in C-notation. The + value should be a multiple of 8. + + `curve NAME' + For ECC a named curve may be used instead of giving the + number of requested bits. This allows to request a specific + curve to override a default selection Libgcrypt would have + taken if `nbits' has been given. The available names are + listed with the description of the ECC public key parameters. + + `rsa-use-e' + This is only used with RSA to give a hint for the public + exponent. The value will be used as a base to test for a + usable exponent. Some values are special: + + `0' + Use a secure and fast value. This is currently the + number 41. + + `1' + Use a value as required by some crypto policies. This + is currently the number 65537. + + `2' + Reserved + + `> 2' + Use the given value. + + If this parameter is not used, Libgcrypt uses for historic + reasons 65537. + + `qbits' + This is only meanigful for DSA keys. If it is given the DSA + key is generated with a Q parameyer of this size. If it is + not given or zero Q is deduced from NBITS in this way: + `512 <= N <= 1024' + Q = 160 + + `N = 2048' + Q = 224 + + `N = 3072' + Q = 256 + + `N = 7680' + Q = 384 + + `N = 15360' + Q = 512 + Note that in this case only the values for N, as given in the + table, are allowed. When specifying Q all values of N in the + range 512 to 15680 are valid as long as they are multiples of + 8. + + `transient-key' + This is only meaningful for RSA and DSA keys. This is a flag + with no value. If given the RSA or DSA key is created using + a faster and a somewhat less secure random number generator. + This flag may be used for keys which are only used for a + short time and do not require full cryptographic strength. + + `domain' + This is only meaningful for DLP algorithms. If specified + keys are generated with domain parameters taken from this + list. The exact format of this parameter depends on the + actual algorithm. It is currently only implemented for DSA + using this format: + + (genkey + (dsa + (domain + (p P-MPI) + (q Q-MPI) + (g Q-MPI)))) + + `nbits' and `qbits' may not be specified because they are + derived from the domain parameters. + + `derive-parms' + This is currently only implemented for RSA and DSA keys. It + is not allowed to use this together with a `domain' + specification. If given, it is used to derive the keys using + the given parameters. + + If given for an RSA key the X9.31 key generation algorithm is + used even if libgcrypt is not in FIPS mode. If given for a + DSA key, the FIPS 186 algorithm is used even if libgcrypt is + not in FIPS mode. + + (genkey + (rsa + (nbits 4:1024) + (rsa-use-e 1:3) + (derive-parms + (Xp1 #1A1916DDB29B4EB7EB6732E128#) + (Xp2 #192E8AAC41C576C822D93EA433#) + (Xp #D8CD81F035EC57EFE822955149D3BFF70C53520D + 769D6D76646C7A792E16EBD89FE6FC5B605A6493 + 39DFC925A86A4C6D150B71B9EEA02D68885F5009 + B98BD984#) + (Xq1 #1A5CF72EE770DE50CB09ACCEA9#) + (Xq2 #134E4CAA16D2350A21D775C404#) + (Xq #CC1092495D867E64065DEE3E7955F2EBC7D47A2D + 7C9953388F97DDDC3E1CA19C35CA659EDC2FC325 + 6D29C2627479C086A699A49C4C9CEE7EF7BD1B34 + 321DE34A#)))) + + (genkey + (dsa + (nbits 4:1024) + (derive-parms + (seed SEED-MPI)))) + + `use-x931' + Force the use of the ANSI X9.31 key generation algorithm + instead of the default algorithm. This flag is only + meaningful for RSA and usually not required. Note that this + algorithm is implicitly used if either `derive-parms' is + given or Libgcrypt is in FIPS mode. + + `use-fips186' + Force the use of the FIPS 186 key generation algorithm + instead of the default algorithm. This flag is only + meaningful for DSA and usually not required. Note that this + algorithm is implicitly used if either `derive-parms' is + given or Libgcrypt is in FIPS mode. As of now FIPS 186-2 is + implemented; after the approval of FIPS 186-3 the code will + be changed to implement 186-3. + + `use-fips186-2' + Force the use of the FIPS 186-2 key generation algorithm + instead of the default algorithm. This algorithm is slighlty + different from FIPS 186-3 and allows only 1024 bit keys. + This flag is only meaningful for DSA and only required for + FIPS testing backward compatibility. + + + The key pair is returned in a format depending on the algorithm. + Both private and public keys are returned in one container and may + be accompanied by some miscellaneous information. + + As an example, here is what the Elgamal key generation returns: + + (key-data + (public-key + (elg + (p P-MPI) + (g G-MPI) + (y Y-MPI))) + (private-key + (elg + (p P-MPI) + (g G-MPI) + (y Y-MPI) + (x X-MPI))) + (misc-key-info + (pm1-factors N1 N2 ... NN)) + + As you can see, some of the information is duplicated, but this + provides an easy way to extract either the public or the private + key. Note that the order of the elements is not defined, e.g. the + private key may be stored before the public key. N1 N2 ... NN is a + list of prime numbers used to composite P-MPI; this is in general + not a very useful information and only available if the key + generation algorithm provides them. + + +File: gcrypt.info, Node: AC Interface, Prev: General public-key related Functions, Up: Public Key cryptography + +6.6 Alternative Public Key Interface +==================================== + +This section documents the alternative interface to asymmetric +cryptography (ac) that is not based on S-expressions, but on native C +data structures. As opposed to the pk interface described in the +former chapter, this one follows an open/use/close paradigm like other +building blocks of the library. + + *This interface has a few known problems; most noteworthy an +inherent tendency to leak memory. It might not be available in +forthcoming versions of Libgcrypt.* + +* Menu: + +* Available asymmetric algorithms:: List of algorithms supported by the library. +* Working with sets of data:: How to work with sets of data. +* Working with IO objects:: How to work with IO objects. +* Working with handles:: How to use handles. +* Working with keys:: How to work with keys. +* Using cryptographic functions:: How to perform cryptographic operations. +* Handle-independent functions:: General functions independent of handles. + + +File: gcrypt.info, Node: Available asymmetric algorithms, Next: Working with sets of data, Up: AC Interface + +6.6.1 Available asymmetric algorithms +------------------------------------- + +Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well +as DSA (Digital Signature Algorithm) and Elgamal. The versatile +interface allows to add more algorithms in the future. + + -- Data type: gcry_ac_id_t + The following constants are defined for this type: + + `GCRY_AC_RSA' + Rivest-Shamir-Adleman + + `GCRY_AC_DSA' + Digital Signature Algorithm + + `GCRY_AC_ELG' + Elgamal + + `GCRY_AC_ELG_E' + Elgamal, encryption only. + + +File: gcrypt.info, Node: Working with sets of data, Next: Working with IO objects, Prev: Available asymmetric algorithms, Up: AC Interface + +6.6.2 Working with sets of data +------------------------------- + +In the context of this interface the term `data set' refers to a list +of `named MPI values' that is used by functions performing +cryptographic operations; a named MPI value is a an MPI value, +associated with a label. + + Such data sets are used for representing keys, since keys simply +consist of a variable amount of numbers. Furthermore some functions +return data sets to the caller that are to be provided to other +functions. + + This section documents the data types, symbols and functions that are +relevant for working with data sets. + + -- Data type: gcry_ac_data_t + A single data set. + + The following flags are supported: + +`GCRY_AC_FLAG_DEALLOC' + Used for storing data in a data set. If given, the data will be + released by the library. Note that whenever one of the ac + functions is about to release objects because of this flag, the + objects are expected to be stored in memory allocated through the + Libgcrypt memory management. In other words: gcry_free() is used + instead of free(). + +`GCRY_AC_FLAG_COPY' + Used for storing/retrieving data in/from a data set. If given, the + library will create copies of the provided/contained data, which + will then be given to the user/associated with the data set. + + -- Function: gcry_error_t gcry_ac_data_new (gcry_ac_data_t *DATA) + Creates a new, empty data set and stores it in DATA. + + -- Function: void gcry_ac_data_destroy (gcry_ac_data_t DATA) + Destroys the data set DATA. + + -- Function: gcry_error_t gcry_ac_data_set (gcry_ac_data_t DATA, + unsigned int FLAGS, char *NAME, gcry_mpi_t MPI) + Add the value MPI to DATA with the label NAME. If FLAGS contains + GCRY_AC_FLAG_COPY, the data set will contain copies of NAME and + MPI. If FLAGS contains GCRY_AC_FLAG_DEALLOC or GCRY_AC_FLAG_COPY, + the values contained in the data set will be deallocated when they + are to be removed from the data set. + + -- Function: gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *DATA_CP, + gcry_ac_data_t DATA) + Create a copy of the data set DATA and store it in DATA_CP. + FIXME: exact semantics undefined. + + -- Function: unsigned int gcry_ac_data_length (gcry_ac_data_t DATA) + Returns the number of named MPI values inside of the data set DATA. + + -- Function: gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t DATA, + unsigned int FLAGS, char *NAME, gcry_mpi_t *MPI) + Store the value labelled with NAME found in DATA in MPI. If FLAGS + contains GCRY_AC_FLAG_COPY, store a copy of the MPI value + contained in the data set. MPI may be NULL (this might be useful + for checking the existence of an MPI with extracting it). + + -- Function: gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t DATA, + unsigned int flags, unsigned int INDEX, const char **NAME, + gcry_mpi_t *MPI) + Stores in NAME and MPI the named MPI value contained in the data + set DATA with the index IDX. If FLAGS contains GCRY_AC_FLAG_COPY, + store copies of the values contained in the data set. NAME or MPI + may be NULL. + + -- Function: void gcry_ac_data_clear (gcry_ac_data_t DATA) + Destroys any values contained in the data set DATA. + + -- Function: gcry_error_t gcry_ac_data_to_sexp (gcry_ac_data_t DATA, + gcry_sexp_t *SEXP, const char **IDENTIFIERS) + This function converts the data set DATA into a newly created + S-Expression, which is to be stored in SEXP; IDENTIFIERS is a NULL + terminated list of C strings, which specifies the structure of the + S-Expression. + + Example: + + If IDENTIFIERS is a list of pointers to the strings "foo" and + "bar" and if DATA is a data set containing the values "val1 = + 0x01" and "val2 = 0x02", then the resulting S-Expression will look + like this: (foo (bar ((val1 0x01) (val2 0x02))). + + -- Function: gcry_error gcry_ac_data_from_sexp (gcry_ac_data_t *DATA, + gcry_sexp_t SEXP, const char **IDENTIFIERS) + This function converts the S-Expression SEXP into a newly created + data set, which is to be stored in DATA; IDENTIFIERS is a NULL + terminated list of C strings, which specifies the structure of the + S-Expression. If the list of identifiers does not match the + structure of the S-Expression, the function fails. + + +File: gcrypt.info, Node: Working with IO objects, Next: Working with handles, Prev: Working with sets of data, Up: AC Interface + +6.6.3 Working with IO objects +----------------------------- + +Note: IO objects are currently only used in the context of message +encoding/decoding and encryption/signature schemes. + + -- Data type: gcry_ac_io_t + `gcry_ac_io_t' is the type to be used for IO objects. + + IO objects provide an uniform IO layer on top of different underlying +IO mechanisms; either they can be used for providing data to the +library (mode is GCRY_AC_IO_READABLE) or they can be used for +retrieving data from the library (mode is GCRY_AC_IO_WRITABLE). + + IO object need to be initialized by calling on of the following +functions: + + -- Function: void gcry_ac_io_init (gcry_ac_io_t *AC_IO, + gcry_ac_io_mode_t MODE, gcry_ac_io_type_t TYPE, ...); + Initialize AC_IO according to MODE, TYPE and the variable list of + arguments. The list of variable arguments to specify depends on + the given TYPE. + + -- Function: void gcry_ac_io_init_va (gcry_ac_io_t *AC_IO, + gcry_ac_io_mode_t MODE, gcry_ac_io_type_t TYPE, va_list AP); + Initialize AC_IO according to MODE, TYPE and the variable list of + arguments AP. The list of variable arguments to specify depends + on the given TYPE. + + The following types of IO objects exist: + +`GCRY_AC_IO_STRING' + In case of GCRY_AC_IO_READABLE the IO object will provide data + from a memory string. Arguments to specify at initialization time: + `unsigned char *' + Pointer to the beginning of the memory string + + `size_t' + Size of the memory string + In case of GCRY_AC_IO_WRITABLE the object will store retrieved + data in a newly allocated memory string. Arguments to specify at + initialization time: + `unsigned char **' + Pointer to address, at which the pointer to the newly created + memory string is to be stored + + `size_t *' + Pointer to address, at which the size of the newly created + memory string is to be stored + +`GCRY_AC_IO_CALLBACK' + In case of GCRY_AC_IO_READABLE the object will forward read + requests to a provided callback function. Arguments to specify at + initialization time: + `gcry_ac_data_read_cb_t' + Callback function to use + + `void *' + Opaque argument to provide to the callback function + In case of GCRY_AC_IO_WRITABLE the object will forward write + requests to a provided callback function. Arguments to specify at + initialization time: + `gcry_ac_data_write_cb_t' + Callback function to use + + `void *' + Opaque argument to provide to the callback function + + +File: gcrypt.info, Node: Working with handles, Next: Working with keys, Prev: Working with IO objects, Up: AC Interface + +6.6.4 Working with handles +-------------------------- + +In order to use an algorithm, an according handle must be created. +This is done using the following function: + + -- Function: gcry_error_t gcry_ac_open (gcry_ac_handle_t *HANDLE, int + ALGORITHM, int FLAGS) + Creates a new handle for the algorithm ALGORITHM and stores it in + HANDLE. FLAGS is not used currently. + + ALGORITHM must be a valid algorithm ID, see *Note Available + asymmetric algorithms::, for a list of supported algorithms and the + according constants. Besides using the listed constants directly, + the functions `gcry_pk_name_to_id' may be used to convert the + textual name of an algorithm into the according numeric ID. + + -- Function: void gcry_ac_close (gcry_ac_handle_t HANDLE) + Destroys the handle HANDLE. + + +File: gcrypt.info, Node: Working with keys, Next: Using cryptographic functions, Prev: Working with handles, Up: AC Interface + +6.6.5 Working with keys +----------------------- + + -- Data type: gcry_ac_key_type_t + Defined constants: + + `GCRY_AC_KEY_SECRET' + Specifies a secret key. + + `GCRY_AC_KEY_PUBLIC' + Specifies a public key. + + -- Data type: gcry_ac_key_t + This type represents a single `key', either a secret one or a + public one. + + -- Data type: gcry_ac_key_pair_t + This type represents a `key pair' containing a secret and a public + key. + + Key data structures can be created in two different ways; a new key +pair can be generated, resulting in ready-to-use key. Alternatively a +key can be initialized from a given data set. + + -- Function: gcry_error_t gcry_ac_key_init (gcry_ac_key_t *KEY, + gcry_ac_handle_t HANDLE, gcry_ac_key_type_t TYPE, + gcry_ac_data_t DATA) + Creates a new key of type TYPE, consisting of the MPI values + contained in the data set DATA and stores it in KEY. + + -- Function: gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t + HANDLE, unsigned int NBITS, void *KEY_SPEC, + gcry_ac_key_pair_t *KEY_PAIR, gcry_mpi_t **MISC_DATA) + Generates a new key pair via the handle HANDLE of NBITS bits and + stores it in KEY_PAIR. + + In case non-standard settings are wanted, a pointer to a structure + of type `gcry_ac_key_spec_<algorithm>_t', matching the selected + algorithm, can be given as KEY_SPEC. MISC_DATA is not used yet. + Such a structure does only exist for RSA. A description of the + members of the supported structures follows. + + `gcry_ac_key_spec_rsa_t' + + `gcry_mpi_t e' + Generate the key pair using a special `e'. The value of + `e' has the following meanings: + `= 0' + Let Libgcrypt decide what exponent should be used. + + `= 1' + Request the use of a "secure" exponent; this is + required by some specification to be 65537. + + `> 2' + Try starting at this value until a working exponent + is found. Note that the current implementation + leaks some information about the private key + because the incrementation used is not randomized. + Thus, this function will be changed in the future + to return a random exponent of the given size. + + Example code: + { + gcry_ac_key_pair_t key_pair; + gcry_ac_key_spec_rsa_t rsa_spec; + + rsa_spec.e = gcry_mpi_new (0); + gcry_mpi_set_ui (rsa_spec.e, 1); + + err = gcry_ac_open (&handle, GCRY_AC_RSA, 0); + assert (! err); + + err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec, + &key_pair, NULL); + assert (! err); + } + + -- Function: gcry_ac_key_t gcry_ac_key_pair_extract + (gcry_ac_key_pair_t KEY_PAIR, gcry_ac_key_type_t WHICH) + Returns the key of type WHICH out of the key pair KEY_PAIR. + + -- Function: void gcry_ac_key_destroy (gcry_ac_key_t KEY) + Destroys the key KEY. + + -- Function: void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t + KEY_PAIR) + Destroys the key pair KEY_PAIR. + + -- Function: gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t KEY) + Returns the data set contained in the key KEY. + + -- Function: gcry_error_t gcry_ac_key_test (gcry_ac_handle_t HANDLE, + gcry_ac_key_t KEY) + Verifies that the private key KEY is sane via HANDLE. + + -- Function: gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t + HANDLE, gcry_ac_key_t KEY, unsigned int *NBITS) + Stores the number of bits of the key KEY in NBITS via HANDLE. + + -- Function: gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t + HANDLE, gcry_ac_key_t KEY, unsigned char *KEY_GRIP) + Writes the 20 byte long key grip of the key KEY to KEY_GRIP via + HANDLE. + + +File: gcrypt.info, Node: Using cryptographic functions, Next: Handle-independent functions, Prev: Working with keys, Up: AC Interface + +6.6.6 Using cryptographic functions +----------------------------------- + +The following flags might be relevant: + +`GCRY_AC_FLAG_NO_BLINDING' + Disable any blinding, which might be supported by the chosen + algorithm; blinding is the default. + + There exist two kinds of cryptographic functions available through +the ac interface: primitives, and high-level functions. + + Primitives deal with MPIs (data sets) directly; what they provide is +direct access to the cryptographic operations provided by an algorithm +implementation. + + High-level functions deal with octet strings, according to a +specified "scheme". Schemes make use of "encoding methods", which are +responsible for converting the provided octet strings into MPIs, which +are then forwared to the cryptographic primitives. Since schemes are +to be used for a special purpose in order to achieve a particular +security goal, there exist "encryption schemes" and "signature +schemes". Encoding methods can be used seperately or implicitly +through schemes. + + What follows is a description of the cryptographic primitives. + + -- Function: gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t + HANDLE, unsigned int FLAGS, gcry_ac_key_t KEY, gcry_mpi_t + DATA_PLAIN, gcry_ac_data_t *DATA_ENCRYPTED) + Encrypts the plain text MPI value DATA_PLAIN with the key public + KEY under the control of the flags FLAGS and stores the resulting + data set into DATA_ENCRYPTED. + + -- Function: gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t + HANDLE, unsigned int FLAGS, gcry_ac_key_t KEY, gcry_mpi_t + *DATA_PLAIN, gcry_ac_data_t DATA_ENCRYPTED) + Decrypts the encrypted data contained in the data set + DATA_ENCRYPTED with the secret key KEY under the control of the + flags FLAGS and stores the resulting plain text MPI value in + DATA_PLAIN. + + -- Function: gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t HANDLE, + gcry_ac_key_t KEY, gcry_mpi_t DATA, gcry_ac_data_t + *DATA_SIGNATURE) + Signs the data contained in DATA with the secret key KEY and + stores the resulting signature in the data set DATA_SIGNATURE. + + -- Function: gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t + HANDLE, gcry_ac_key_t KEY, gcry_mpi_t DATA, gcry_ac_data_t + DATA_SIGNATURE) + Verifies that the signature contained in the data set + DATA_SIGNATURE is indeed the result of signing the data contained + in DATA with the secret key belonging to the public key KEY. + + What follows is a description of the high-level functions. + + The type "gcry_ac_em_t" is used for specifying encoding methods; the +following methods are supported: + +`GCRY_AC_EME_PKCS_V1_5' + PKCS-V1_5 Encoding Method for Encryption. Options must be provided + through a pointer to a correctly initialized object of type + gcry_ac_eme_pkcs_v1_5_t. + +`GCRY_AC_EMSA_PKCS_V1_5' + PKCS-V1_5 Encoding Method for Signatures with Appendix. Options + must be provided through a pointer to a correctly initialized + object of type gcry_ac_emsa_pkcs_v1_5_t. + + Option structure types: + +`gcry_ac_eme_pkcs_v1_5_t' + + `gcry_ac_key_t key' + + `gcry_ac_handle_t handle' + +`gcry_ac_emsa_pkcs_v1_5_t' + + `gcry_md_algo_t md' + + `size_t em_n' + + Encoding methods can be used directly through the following +functions: + + -- Function: gcry_error_t gcry_ac_data_encode (gcry_ac_em_t METHOD, + unsigned int FLAGS, void *OPTIONS, unsigned char *M, size_t + M_N, unsigned char **EM, size_t *EM_N) + Encodes the message contained in M of size M_N according to + METHOD, FLAGS and OPTIONS. The newly created encoded message is + stored in EM and EM_N. + + -- Function: gcry_error_t gcry_ac_data_decode (gcry_ac_em_t METHOD, + unsigned int FLAGS, void *OPTIONS, unsigned char *EM, size_t + EM_N, unsigned char **M, size_t *M_N) + Decodes the message contained in EM of size EM_N according to + METHOD, FLAGS and OPTIONS. The newly created decoded message is + stored in M and M_N. + + The type "gcry_ac_scheme_t" is used for specifying schemes; the +following schemes are supported: + +`GCRY_AC_ES_PKCS_V1_5' + PKCS-V1_5 Encryption Scheme. No options can be provided. + +`GCRY_AC_SSA_PKCS_V1_5' + PKCS-V1_5 Signature Scheme (with Appendix). Options can be + provided through a pointer to a correctly initialized object of + type gcry_ac_ssa_pkcs_v1_5_t. + + Option structure types: + +`gcry_ac_ssa_pkcs_v1_5_t' + + `gcry_md_algo_t md' + + The functions implementing schemes: + + -- Function: gcry_error_t gcry_ac_data_encrypt_scheme + (gcry_ac_handle_t HANDLE, gcry_ac_scheme_t SCHEME, unsigned + int FLAGS, void *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t + *IO_MESSAGE, gcry_ac_io_t *IO_CIPHER) + Encrypts the plain text readable from IO_MESSAGE through HANDLE + with the public key KEY according to SCHEME, FLAGS and OPTS. If + OPTS is not NULL, it has to be a pointer to a structure specific + to the chosen scheme (gcry_ac_es_*_t). The encrypted message is + written to IO_CIPHER. + + -- Function: gcry_error_t gcry_ac_data_decrypt_scheme + (gcry_ac_handle_t HANDLE, gcry_ac_scheme_t SCHEME, unsigned + int FLAGS, void *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t + *IO_CIPHER, gcry_ac_io_t *IO_MESSAGE) + Decrypts the cipher text readable from IO_CIPHER through HANDLE + with the secret key KEY according to SCHEME, FLAGS and OPTS. If + OPTS is not NULL, it has to be a pointer to a structure specific + to the chosen scheme (gcry_ac_es_*_t). The decrypted message is + written to IO_MESSAGE. + + -- Function: gcry_error_t gcry_ac_data_sign_scheme (gcry_ac_handle_t + HANDLE, gcry_ac_scheme_t SCHEME, unsigned int FLAGS, void + *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t *IO_MESSAGE, + gcry_ac_io_t *IO_SIGNATURE) + Signs the message readable from IO_MESSAGE through HANDLE with the + secret key KEY according to SCHEME, FLAGS and OPTS. If OPTS is + not NULL, it has to be a pointer to a structure specific to the + chosen scheme (gcry_ac_ssa_*_t). The signature is written to + IO_SIGNATURE. + + -- Function: gcry_error_t gcry_ac_data_verify_scheme (gcry_ac_handle_t + HANDLE, gcry_ac_scheme_t SCHEME, unsigned int FLAGS, void + *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t *IO_MESSAGE, + gcry_ac_io_t *IO_SIGNATURE) + Verifies through HANDLE that the signature readable from + IO_SIGNATURE is indeed the result of signing the message readable + from IO_MESSAGE with the secret key belonging to the public key + KEY according to SCHEME and OPTS. If OPTS is not NULL, it has to + be an anonymous structure (gcry_ac_ssa_*_t) specific to the chosen + scheme. + + +File: gcrypt.info, Node: Handle-independent functions, Prev: Using cryptographic functions, Up: AC Interface + +6.6.7 Handle-independent functions +---------------------------------- + +These two functions are deprecated; do not use them for new code. + + -- Function: gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t ALGORITHM, + const char **NAME) + Stores the textual representation of the algorithm whose id is + given in ALGORITHM in NAME. Deprecated; use `gcry_pk_algo_name'. + + -- Function: gcry_error_t gcry_ac_name_to_id (const char *NAME, + gcry_ac_id_t *ALGORITHM) + Stores the numeric ID of the algorithm whose textual + representation is contained in NAME in ALGORITHM. Deprecated; use + `gcry_pk_map_name'. + + +File: gcrypt.info, Node: Hashing, Next: Random Numbers, Prev: Public Key cryptography, Up: Top + +7 Hashing +********* + +Libgcrypt provides an easy and consistent to use interface for hashing. +Hashing is buffered and several hash algorithms can be updated at once. +It is possible to compute a MAC using the same routines. The +programming model follows an open/process/close paradigm and is in that +similar to other building blocks provided by Libgcrypt. + + For convenience reasons, a few cyclic redundancy check value +operations are also supported. + +* Menu: + +* Available hash algorithms:: List of hash algorithms supported by the library. +* Hash algorithm modules:: How to work with hash algorithm modules. +* Working with hash algorithms:: List of functions related to hashing. + + +File: gcrypt.info, Node: Available hash algorithms, Next: Hash algorithm modules, Up: Hashing + +7.1 Available hash algorithms +============================= + +`GCRY_MD_NONE' + This is not a real algorithm but used by some functions as an error + return value. This constant is guaranteed to have the value `0'. + +`GCRY_MD_SHA1' + This is the SHA-1 algorithm which yields a message digest of 20 + bytes. 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. + +`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. + + + +File: gcrypt.info, Node: Hash algorithm modules, Next: Working with hash algorithms, Prev: Available hash algorithms, Up: Hashing + +7.2 Hash algorithm modules +========================== + +Libgcrypt makes it possible to load additional `message digest +modules'; these digests can be used just like the message digest +algorithms that are built into the library directly. For an +introduction into extension modules, see *Note Modules::. + + -- Data type: gcry_md_spec_t + This is the `module specification structure' needed for registering + message digest modules, which has to be filled in by the user + before it can be used to register a module. It contains the + following members: + + `const char *name' + The primary name of this algorithm. + + `unsigned char *asnoid' + Array of bytes that form the ASN OID. + + `int asnlen' + Length of bytes in `asnoid'. + + `gcry_md_oid_spec_t *oids' + A list of OIDs that are to be associated with the algorithm. + The list's last element must have it's `oid' member set to + NULL. See below for an explanation of this type. See below + for an explanation of this type. + + `int mdlen' + Length of the message digest algorithm. See below for an + explanation of this type. + + `gcry_md_init_t init' + The function responsible for initializing a handle. See + below for an explanation of this type. + + `gcry_md_write_t write' + The function responsible for writing data into a message + digest context. See below for an explanation of this type. + + `gcry_md_final_t final' + The function responsible for `finalizing' a message digest + context. See below for an explanation of this type. + + `gcry_md_read_t read' + The function responsible for reading out a message digest + result. See below for an explanation of this type. + + `size_t contextsize' + The size of the algorithm-specific `context', that should be + allocated for each handle. + + -- Data type: gcry_md_oid_spec_t + This type is used for associating a user-provided algorithm + implementation with certain OIDs. It contains the following + members: + + `const char *oidstring' + Textual representation of the OID. + + -- Data type: gcry_md_init_t + Type for the `init' function, defined as: void (*gcry_md_init_t) + (void *c) + + -- Data type: gcry_md_write_t + Type for the `write' function, defined as: void (*gcry_md_write_t) + (void *c, unsigned char *buf, size_t nbytes) + + -- Data type: gcry_md_final_t + Type for the `final' function, defined as: void (*gcry_md_final_t) + (void *c) + + -- Data type: gcry_md_read_t + Type for the `read' function, defined as: unsigned char + *(*gcry_md_read_t) (void *c) + + -- Function: gcry_error_t gcry_md_register (gcry_md_spec_t *DIGEST, + unsigned int *algorithm_id, gcry_module_t *MODULE) + Register a new digest module whose specification can be found in + DIGEST. On success, a new algorithm ID is stored in ALGORITHM_ID + and a pointer representing this module is stored in MODULE. + + -- Function: void gcry_md_unregister (gcry_module_t MODULE) + Unregister the digest identified by MODULE, which must have been + registered with gcry_md_register. + + -- Function: gcry_error_t gcry_md_list (int *LIST, int *LIST_LENGTH) + Get a list consisting of the IDs of the loaded message digest + modules. If LIST is zero, write the number of loaded message + digest modules to LIST_LENGTH and return. If LIST is non-zero, + the first *LIST_LENGTH algorithm IDs are stored in LIST, which + must be of according size. In case there are less message digests + modules than *LIST_LENGTH, *LIST_LENGTH is updated to the correct + number. + + +File: gcrypt.info, Node: Working with hash algorithms, Prev: Hash algorithm modules, Up: Hashing + +7.3 Working with hash algorithms +================================ + +To use most of these function it is necessary to create a context; this +is done using: + + -- Function: gcry_error_t gcry_md_open (gcry_md_hd_t *HD, int ALGO, + unsigned int FLAGS) + Create a message digest object for algorithm ALGO. FLAGS may be + given as an bitwise OR of constants described below. ALGO may be + given as `0' if the algorithms to use are later set using + `gcry_md_enable'. HD is guaranteed to either receive a valid + handle or NULL. + + For a list of supported algorithms, see *Note Available hash + algorithms::. + + The flags allowed for MODE are: + + `GCRY_MD_FLAG_SECURE' + Allocate all buffers and the resulting digest in "secure + memory". Use this is the hashed data is highly confidential. + + `GCRY_MD_FLAG_HMAC' + Turn the algorithm into a HMAC message authentication + algorithm. This only works if just one algorithm is enabled + for the handle. Note that the function `gcry_md_setkey' must + be used to set the MAC key. The size of the MAC is equal to + the message digest of the underlying hash algorithm. If you + want CBC message authentication codes based on a cipher, see + *Note Working with cipher handles::. + + + You may use the function `gcry_md_is_enabled' to later check + whether an algorithm has been enabled. + + + If you want to calculate several hash algorithms at the same time, +you have to use the following function right after the `gcry_md_open': + + -- Function: gcry_error_t gcry_md_enable (gcry_md_hd_t H, int ALGO) + Add the message digest algorithm ALGO to the digest object + described by handle H. Duplicated enabling of algorithms is + detected and ignored. + + If the flag `GCRY_MD_FLAG_HMAC' was used, the key for the MAC must +be set using the function: + + -- Function: gcry_error_t gcry_md_setkey (gcry_md_hd_t H, const void + *KEY, size_t KEYLEN) + For use with the HMAC feature, set the MAC key to the value of KEY + of length KEYLEN bytes. There is no restriction on the length of + the key. + + After you are done with the hash calculation, you should release the +resources by using: + + -- Function: void gcry_md_close (gcry_md_hd_t H) + Release all resources of hash context H. H should not be used + after a call to this function. A `NULL' passed as H is ignored. + The function also zeroises all sensitive information associated + with this handle. + + + Often you have to do several hash operations using the same +algorithm. To avoid the overhead of creating and releasing context, a +reset function is provided: + + -- Function: void gcry_md_reset (gcry_md_hd_t H) + Reset the current context to its initial state. This is + effectively identical to a close followed by an open and enabling + all currently active algorithms. + + Often it is necessary to start hashing some data and then continue to +hash different data. To avoid hashing the same data several times +(which might not even be possible if the data is received from a pipe), +a snapshot of the current hash context can be taken and turned into a +new context: + + -- Function: gcry_error_t gcry_md_copy (gcry_md_hd_t *HANDLE_DST, + gcry_md_hd_t HANDLE_SRC) + Create a new digest object as an exact copy of the object + described by handle HANDLE_SRC and store it in HANDLE_DST. The + context is not reset and you can continue to hash data using this + context and independently using the original context. + + Now that we have prepared everything to calculate hashes, it is time +to see how it is actually done. There are two ways for this, one to +update the hash with a block of memory and one macro to update the hash +by just one character. Both methods can be used on the same hash +context. + + -- Function: void gcry_md_write (gcry_md_hd_t H, const void *BUFFER, + size_t LENGTH) + Pass LENGTH bytes of the data in BUFFER to the digest object with + handle H to update the digest values. This function should be used + for large blocks of data. + + -- Function: void gcry_md_putc (gcry_md_hd_t H, int C) + Pass the byte in C to the digest object with handle H to update + the digest value. This is an efficient function, implemented as a + macro to buffer the data before an actual update. + + The semantics of the hash functions do not provide for reading out +intermediate message digests because the calculation must be finalized +first. This finalization may for example include the number of bytes +hashed in the message digest or some padding. + + -- Function: void gcry_md_final (gcry_md_hd_t H) + Finalize the message digest calculation. This is not really needed + because `gcry_md_read' does this implicitly. After this has been + done no further updates (by means of `gcry_md_write' or + `gcry_md_putc' are allowed. Only the first call to this function + has an effect. It is implemented as a macro. + + The way to read out the calculated message digest is by using the +function: + + -- Function: unsigned char * gcry_md_read (gcry_md_hd_t H, int ALGO) + `gcry_md_read' returns the message digest after finalizing the + calculation. This function may be used as often as required but + it will always return the same value for one handle. The returned + message digest is allocated within the message context and + therefore valid until the handle is released or reseted (using + `gcry_md_close' or `gcry_md_reset'. ALGO may be given as 0 to + return the only enabled message digest or it may specify one of + the enabled algorithms. The function does return `NULL' if the + requested algorithm has not been enabled. + + Because it is often necessary to get the message digest of one block +of memory, a fast convenience function is available for this task: + + -- Function: void gcry_md_hash_buffer (int ALGO, void *DIGEST, const + void *BUFFER, size_t LENGTH); + `gcry_md_hash_buffer' is a shortcut function to calculate a message + digest of a buffer. This function does not require a context and + immediately returns the message digest of the LENGTH bytes at + BUFFER. DIGEST must be allocated by the caller, large enough to + hold the message digest yielded by the the specified algorithm + ALGO. This required size may be obtained by using the function + `gcry_md_get_algo_dlen'. + + Note that this function will abort the process if an unavailable + algorithm is used. + + Hash algorithms are identified by internal algorithm numbers (see +`gcry_md_open' for a list). However, in most applications they are +used by names, so two functions are available to map between string +representations and hash algorithm identifiers. + + -- Function: const char * gcry_md_algo_name (int ALGO) + Map the digest algorithm id ALGO to a string representation of the + algorithm name. For unknown algorithms this function returns the + string `"?"'. This function should not be used to test for the + availability of an algorithm. + + -- Function: int gcry_md_map_name (const char *NAME) + Map the algorithm with NAME to a digest algorithm identifier. + Returns 0 if the algorithm name is not known. Names representing + ASN.1 object identifiers are recognized if the IETF dotted format + is used and the OID is prefixed with either "`oid.'" or "`OID.'". + For a list of supported OIDs, see the source code at + `cipher/md.c'. This function should not be used to test for the + availability of an algorithm. + + -- Function: gcry_error_t gcry_md_get_asnoid (int ALGO, void *BUFFER, + size_t *LENGTH) + Return an DER encoded ASN.1 OID for the algorithm ALGO in the user + allocated BUFFER. LENGTH must point to variable with the available + size of BUFFER and receives after return the actual size of the + returned OID. The returned error code may be `GPG_ERR_TOO_SHORT' + if the provided buffer is to short to receive the OID; it is + possible to call the function with `NULL' for BUFFER to have it + only return the required size. The function returns 0 on success. + + + To test whether an algorithm is actually available for use, the +following macro should be used: + + -- Function: gcry_error_t gcry_md_test_algo (int ALGO) + The macro returns 0 if the algorithm ALGO is available for use. + + If the length of a message digest is not known, it can be retrieved +using the following function: + + -- Function: unsigned int gcry_md_get_algo_dlen (int ALGO) + Retrieve the length in bytes of the digest yielded by algorithm + ALGO. This is often used prior to `gcry_md_read' to allocate + sufficient memory for the digest. + + In some situations it might be hard to remember the algorithm used +for the ongoing hashing. The following function might be used to get +that information: + + -- Function: int gcry_md_get_algo (gcry_md_hd_t H) + Retrieve the algorithm used with the handle H. Note that this + does not work reliable if more than one algorithm is enabled in H. + + The following macro might also be useful: + + -- Function: int gcry_md_is_secure (gcry_md_hd_t H) + This function returns true when the digest object H is allocated + in "secure memory"; i.e. H was created with the + `GCRY_MD_FLAG_SECURE'. + + -- Function: int gcry_md_is_enabled (gcry_md_hd_t H, int ALGO) + This function returns true when the algorithm ALGO has been + enabled for the digest object H. + + Tracking bugs related to hashing is often a cumbersome task which +requires to add a lot of printf statements into the code. Libgcrypt +provides an easy way to avoid this. The actual data hashed can be +written to files on request. + + -- Function: void gcry_md_debug (gcry_md_hd_t H, const char *SUFFIX) + Enable debugging for the digest object with handle H. This + creates create files named `dbgmd-<n>.<string>' while doing the + actual hashing. SUFFIX is the string part in the filename. The + number is a counter incremented for each new hashing. The data in + the file is the raw data as passed to `gcry_md_write' or + `gcry_md_putc'. If `NULL' is used for SUFFIX, the debugging is + stopped and the file closed. This is only rarely required because + `gcry_md_close' implicitly stops debugging. + + The following two deprecated macros are used for debugging by old +code. They shopuld be replaced by `gcry_md_debug'. + + -- Function: void gcry_md_start_debug (gcry_md_hd_t H, const char + *SUFFIX) + Enable debugging for the digest object with handle H. This + creates create files named `dbgmd-<n>.<string>' while doing the + actual hashing. SUFFIX is the string part in the filename. The + number is a counter incremented for each new hashing. The data in + the file is the raw data as passed to `gcry_md_write' or + `gcry_md_putc'. + + -- Function: void gcry_md_stop_debug (gcry_md_hd_t H, int RESERVED) + Stop debugging on handle H. RESERVED should be specified as 0. + This function is usually not required because `gcry_md_close' does + implicitly stop debugging. + + +File: gcrypt.info, Node: Random Numbers, Next: S-expressions, Prev: Hashing, Up: Top + +8 Random Numbers +**************** + +* Menu: + +* Quality of random numbers:: Libgcrypt uses different quality levels. +* Retrieving random numbers:: How to retrieve random numbers. + + +File: gcrypt.info, Node: Quality of random numbers, Next: Retrieving random numbers, Up: Random Numbers + +8.1 Quality of random numbers +============================= + +Libgcypt offers random numbers of different quality levels: + + -- Data type: gcry_random_level_t + The constants for the random quality levels are of this enum type. + +`GCRY_WEAK_RANDOM' + For all functions, except for `gcry_mpi_randomize', this level maps + to GCRY_STRONG_RANDOM. If you do not want this, consider using + `gcry_create_nonce'. + +`GCRY_STRONG_RANDOM' + Use this level for session keys and similar purposes. + +`GCRY_VERY_STRONG_RANDOM' + Use this level for long term key material. + + +File: gcrypt.info, Node: Retrieving random numbers, Prev: Quality of random numbers, Up: Random Numbers + +8.2 Retrieving random numbers +============================= + + -- Function: void gcry_randomize (unsigned char *BUFFER, size_t + LENGTH, enum gcry_random_level LEVEL) + Fill BUFFER with LENGTH random bytes using a random quality as + defined by LEVEL. + + -- Function: void * gcry_random_bytes (size_t NBYTES, enum + gcry_random_level LEVEL) + Convenience function to allocate a memory block consisting of + NBYTES fresh random bytes using a random quality as defined by + LEVEL. + + -- Function: void * gcry_random_bytes_secure (size_t NBYTES, enum + gcry_random_level LEVEL) + Convenience function to allocate a memory block consisting of + NBYTES fresh random bytes using a random quality as defined by + LEVEL. This function differs from `gcry_random_bytes' in that the + returned buffer is allocated in a "secure" area of the memory. + + -- Function: void gcry_create_nonce (unsigned char *BUFFER, size_t + LENGTH) + Fill BUFFER with LENGTH unpredictable bytes. This is commonly + called a nonce and may also be used for initialization vectors and + padding. This is an extra function nearly independent of the + other random function for 3 reasons: It better protects the + regular random generator's internal state, provides better + performance and does not drain the precious entropy pool. + + + +File: gcrypt.info, Node: S-expressions, Next: MPI library, Prev: Random Numbers, Up: Top + +9 S-expressions +*************** + +S-expressions are used by the public key functions to pass complex data +structures around. These LISP like objects are used by some +cryptographic protocols (cf. RFC-2692) and Libgcrypt provides functions +to parse and construct them. For detailed information, see `Ron +Rivest, code and description of S-expressions, +`http://theory.lcs.mit.edu/~rivest/sexp.html''. + +* Menu: + +* Data types for S-expressions:: Data types related with S-expressions. +* Working with S-expressions:: How to work with S-expressions. + + +File: gcrypt.info, Node: Data types for S-expressions, Next: Working with S-expressions, Up: S-expressions + +9.1 Data types for S-expressions +================================ + + -- Data type: gcry_sexp_t + The `gcry_sexp_t' type describes an object with the Libgcrypt + internal representation of an S-expression. + + +File: gcrypt.info, Node: Working with S-expressions, Prev: Data types for S-expressions, Up: S-expressions + +9.2 Working with S-expressions +============================== + +There are several functions to create an Libgcrypt S-expression object +from its external representation or from a string template. There is +also a function to convert the internal representation back into one of +the external formats: + + -- Function: gcry_error_t gcry_sexp_new (gcry_sexp_t *R_SEXP, + const void *BUFFER, size_t LENGTH, int AUTODETECT) + This is the generic function to create an new S-expression object + from its external representation in BUFFER of LENGTH bytes. On + success the result is stored at the address given by R_SEXP. With + AUTODETECT set to 0, the data in BUFFER is expected to be in + canonized format, with AUTODETECT set to 1 the parses any of the + defined external formats. If BUFFER does not hold a valid + S-expression an error code is returned and R_SEXP set to `NULL'. + Note that the caller is responsible for releasing the newly + allocated S-expression using `gcry_sexp_release'. + + -- Function: gcry_error_t gcry_sexp_create (gcry_sexp_t *R_SEXP, + void *BUFFER, size_t LENGTH, int AUTODETECT, + void (*FREEFNC)(void*)) + This function is identical to `gcry_sexp_new' but has an extra + argument FREEFNC, which, when not set to `NULL', is expected to be + a function to release the BUFFER; most likely the standard `free' + function is used for this argument. This has the effect of + transferring the ownership of BUFFER to the created object in + R_SEXP. The advantage of using this function is that Libgcrypt + might decide to directly use the provided buffer and thus avoid + extra copying. + + -- Function: gcry_error_t gcry_sexp_sscan (gcry_sexp_t *R_SEXP, + size_t *ERROFF, const char *BUFFER, size_t LENGTH) + This is another variant of the above functions. It behaves nearly + identical but provides an ERROFF argument which will receive the + offset into the buffer where the parsing stopped on error. + + -- Function: gcry_error_t gcry_sexp_build (gcry_sexp_t *R_SEXP, + size_t *ERROFF, const char *FORMAT, ...) + This function creates an internal S-expression from the string + template FORMAT and stores it at the address of R_SEXP. If there + is a parsing error, the function returns an appropriate error code + and stores the offset into FORMAT where the parsing stopped in + ERROFF. The function supports a couple of printf-like formatting + characters and expects arguments for some of these escape + sequences right after FORMAT. The following format characters are + defined: + + `%m' + The next argument is expected to be of type `gcry_mpi_t' and + a copy of its value is inserted into the resulting + S-expression. + + `%s' + The next argument is expected to be of type `char *' and that + string is inserted into the resulting S-expression. + + `%d' + The next argument is expected to be of type `int' and its + value is inserted into the resulting S-expression. + + `%b' + The next argument is expected to be of type `int' directly + followed by an argument of type `char *'. This represents a + buffer of given length to be inserted into the resulting + S-expression. + + `%S' + The next argument is expected to be of type `gcry_sexp_t' and + a copy of that S-expression is embedded in the resulting + S-expression. The argument needs to be a regular + S-expression, starting with a parenthesis. + + + No other format characters are defined and would return an error. + Note that the format character `%%' does not exists, because a + percent sign is not a valid character in an S-expression. + + -- Function: void gcry_sexp_release (gcry_sexp_t SEXP) + Release the S-expression object SEXP. If the S-expression is + stored in secure memory it explicitly zeroises that memory; note + that this is done in addition to the zeroisation always done when + freeing secure memory. + +The next 2 functions are used to convert the internal representation +back into a regular external S-expression format and to show the +structure for debugging. + + -- Function: size_t gcry_sexp_sprint (gcry_sexp_t SEXP, int MODE, + char *BUFFER, size_t MAXLENGTH) + Copies the S-expression object SEXP into BUFFER using the format + specified in MODE. MAXLENGTH must be set to the allocated length + of BUFFER. The function returns the actual length of valid bytes + put into BUFFER or 0 if the provided buffer is too short. Passing + `NULL' for BUFFER returns the required length for BUFFER. For + convenience reasons an extra byte with value 0 is appended to the + buffer. + + The following formats are supported: + + `GCRYSEXP_FMT_DEFAULT' + Returns a convenient external S-expression representation. + + `GCRYSEXP_FMT_CANON' + Return the S-expression in canonical format. + + `GCRYSEXP_FMT_BASE64' + Not currently supported. + + `GCRYSEXP_FMT_ADVANCED' + Returns the S-expression in advanced format. + + -- Function: void gcry_sexp_dump (gcry_sexp_t SEXP) + Dumps SEXP in a format suitable for debugging to Libgcrypt's + logging stream. + +Often canonical encoding is used in the external representation. The +following function can be used to check for valid encoding and to learn +the length of the S-expression" + + -- Function: size_t gcry_sexp_canon_len (const unsigned char *BUFFER, + size_t LENGTH, size_t *ERROFF, int *ERRCODE) + Scan the canonical encoded BUFFER with implicit length values and + return the actual length this S-expression uses. For a valid + S-expression it should never return 0. If LENGTH is not 0, the + maximum length to scan is given; this can be used for syntax + checks of data passed from outside. ERRCODE and ERROFF may both be + passed as `NULL'. + + +There are functions to parse S-expressions and retrieve elements: + + -- Function: gcry_sexp_t gcry_sexp_find_token (const gcry_sexp_t LIST, + const char *TOKEN, size_t TOKLEN) + Scan the S-expression for a sublist with a type (the car of the + list) matching the string TOKEN. If TOKLEN is not 0, the token is + assumed to be raw memory of this length. The function returns a + newly allocated S-expression consisting of the found sublist or + `NULL' when not found. + + -- Function: int gcry_sexp_length (const gcry_sexp_t LIST) + Return the length of the LIST. For a valid S-expression this + should be at least 1. + + -- Function: gcry_sexp_t gcry_sexp_nth (const gcry_sexp_t LIST, + int NUMBER) + Create and return a new S-expression from the element with index + NUMBER in LIST. Note that the first element has the index 0. If + there is no such element, `NULL' is returned. + + -- Function: gcry_sexp_t gcry_sexp_car (const gcry_sexp_t LIST) + Create and return a new S-expression from the first element in + LIST; this called the "type" and should always exist and be a + string. `NULL' is returned in case of a problem. + + -- Function: gcry_sexp_t gcry_sexp_cdr (const gcry_sexp_t LIST) + Create and return a new list form all elements except for the + first one. Note that this function may return an invalid + S-expression because it is not guaranteed, that the type exists + and is a string. However, for parsing a complex S-expression it + might be useful for intermediate lists. Returns `NULL' on error. + + -- Function: const char * gcry_sexp_nth_data (const gcry_sexp_t LIST, + int NUMBER, size_t *DATALEN) + This function is used to get data from a LIST. A pointer to the + actual data with index NUMBER is returned and the length of this + data will be stored to DATALEN. If there is no data at the given + index or the index represents another list, `NULL' is returned. + *Caution:* The returned pointer is valid as long as LIST is not + modified or released. + + Here is an example on how to extract and print the surname (Meier) + from the S-expression `(Name Otto Meier (address Burgplatz 3))': + + size_t len; + const char *name; + + name = gcry_sexp_nth_data (list, 2, &len); + printf ("my name is %.*s\n", (int)len, name); + + -- Function: char * gcry_sexp_nth_string (gcry_sexp_t LIST, int NUMBER) + This function is used to get and convert data from a LIST. The + data is assumed to be a Nul terminated string. The caller must + release this returned value using `gcry_free'. If there is no + data at the given index, the index represents a list or the value + can't be converted to a string, `NULL' is returned. + + -- Function: gcry_mpi_t gcry_sexp_nth_mpi (gcry_sexp_t LIST, + int NUMBER, int MPIFMT) + This function is used to get and convert data from a LIST. This + data is assumed to be an MPI stored in the format described by + MPIFMT and returned as a standard Libgcrypt MPI. The caller must + release this returned value using `gcry_mpi_release'. If there is + no data at the given index, the index represents a list or the + value can't be converted to an MPI, `NULL' is returned. + + +File: gcrypt.info, Node: MPI library, Next: Prime numbers, Prev: S-expressions, Up: Top + +10 MPI library +************** + +* Menu: + +* Data types:: MPI related data types. +* Basic functions:: First steps with MPI numbers. +* MPI formats:: External representation of MPIs. +* Calculations:: Performing MPI calculations. +* Comparisons:: How to compare MPI values. +* Bit manipulations:: How to access single bits of MPI values. +* Miscellaneous:: Miscellaneous MPI functions. + + Public key cryptography is based on mathematics with large numbers. +To implement the public key functions, a library for handling these +large numbers is required. Because of the general usefulness of such a +library, its interface is exposed by Libgcrypt. In the context of +Libgcrypt and in most other applications, these large numbers are +called MPIs (multi-precision-integers). + + +File: gcrypt.info, Node: Data types, Next: Basic functions, Up: MPI library + +10.1 Data types +=============== + + -- Data type: gcry_mpi_t + This type represents an object to hold an MPI. + + +File: gcrypt.info, Node: Basic functions, Next: MPI formats, Prev: Data types, Up: MPI library + +10.2 Basic functions +==================== + +To work with MPIs, storage must be allocated and released for the +numbers. This can be done with one of these functions: + + -- Function: gcry_mpi_t gcry_mpi_new (unsigned int NBITS) + Allocate a new MPI object, initialize it to 0 and initially + allocate enough memory for a number of at least NBITS. This + pre-allocation is only a small performance issue and not actually + necessary because Libgcrypt automatically re-allocates the + required memory. + + -- Function: gcry_mpi_t gcry_mpi_snew (unsigned int NBITS) + This is identical to `gcry_mpi_new' but allocates the MPI in the so + called "secure memory" which in turn will take care that all + derived values will also be stored in this "secure memory". Use + this for highly confidential data like private key parameters. + + -- Function: gcry_mpi_t gcry_mpi_copy (const gcry_mpi_t A) + Create a new MPI as the exact copy of A. + + -- Function: void gcry_mpi_release (gcry_mpi_t A) + Release the MPI A and free all associated resources. Passing + `NULL' is allowed and ignored. When a MPI stored in the "secure + memory" is released, that memory gets wiped out immediately. + +The simplest operations are used to assign a new value to an MPI: + + -- Function: gcry_mpi_t gcry_mpi_set (gcry_mpi_t W, const gcry_mpi_t U) + Assign the value of U to W and return W. If `NULL' is passed for + W, a new MPI is allocated, set to the value of U and returned. + + -- Function: gcry_mpi_t gcry_mpi_set_ui (gcry_mpi_t W, unsigned long U) + Assign the value of U to W and return W. If `NULL' is passed for + W, a new MPI is allocated, set to the value of U and returned. + This function takes an `unsigned int' as type for U and thus it is + only possible to set W to small values (usually up to the word + size of the CPU). + + -- Function: void gcry_mpi_swap (gcry_mpi_t A, gcry_mpi_t B) + Swap the values of A and B. + + +File: gcrypt.info, Node: MPI formats, Next: Calculations, Prev: Basic functions, Up: MPI library + +10.3 MPI formats +================ + +The following functions are used to convert between an external +representation of an MPI and the internal one of Libgcrypt. + + -- Function: gcry_error_t gcry_mpi_scan (gcry_mpi_t *R_MPI, + enum gcry_mpi_format FORMAT, const unsigned char *BUFFER, + size_t BUFLEN, size_t *NSCANNED) + Convert the external representation of an integer stored in BUFFER + with a length of BUFLEN into a newly created MPI returned which + will be stored at the address of R_MPI. For certain formats the + length argument is not required and should be passed as `0'. + After a successful operation the variable NSCANNED receives the + number of bytes actually scanned unless NSCANNED was given as + `NULL'. FORMAT describes the format of the MPI as stored in BUFFER: + + `GCRYMPI_FMT_STD' + 2-complement stored without a length header. + + `GCRYMPI_FMT_PGP' + As used by OpenPGP (only defined as unsigned). This is + basically `GCRYMPI_FMT_STD' with a 2 byte big endian length + header. + + `GCRYMPI_FMT_SSH' + As used in the Secure Shell protocol. This is + `GCRYMPI_FMT_STD' with a 4 byte big endian header. + + `GCRYMPI_FMT_HEX' + Stored as a C style string with each byte of the MPI encoded + as 2 hex digits. When using this format, BUFLEN must be zero. + + `GCRYMPI_FMT_USG' + Simple unsigned integer. + + Note that all of the above formats store the integer in big-endian + format (MSB first). + + -- Function: gcry_error_t gcry_mpi_print (enum gcry_mpi_format FORMAT, + unsigned char *BUFFER, size_t BUFLEN, size_t *NWRITTEN, + const gcry_mpi_t A) + Convert the MPI A into an external representation described by + FORMAT (see above) and store it in the provided BUFFER which has a + usable length of at least the BUFLEN bytes. If NWRITTEN is not + NULL, it will receive the number of bytes actually stored in + BUFFER after a successful operation. + + -- Function: gcry_error_t gcry_mpi_aprint + (enum gcry_mpi_format FORMAT, unsigned char **BUFFER, + size_t *NBYTES, const gcry_mpi_t A) + Convert the MPI A into an external representation described by + FORMAT (see above) and store it in a newly allocated buffer which + address will be stored in the variable BUFFER points to. The + number of bytes stored in this buffer will be stored in the + variable NBYTES points to, unless NBYTES is `NULL'. + + -- Function: void gcry_mpi_dump (const gcry_mpi_t A) + Dump the value of A in a format suitable for debugging to + Libgcrypt's logging stream. Note that one leading space but no + trailing space or linefeed will be printed. It is okay to pass + `NULL' for A. + + +File: gcrypt.info, Node: Calculations, Next: Comparisons, Prev: MPI formats, Up: MPI library + +10.4 Calculations +================= + +Basic arithmetic operations: + + -- Function: void gcry_mpi_add (gcry_mpi_t W, gcry_mpi_t U, + gcry_mpi_t V) + W = U + V. + + -- Function: void gcry_mpi_add_ui (gcry_mpi_t W, gcry_mpi_t U, + unsigned long V) + W = U + V. Note that V is an unsigned integer. + + -- Function: void gcry_mpi_addm (gcry_mpi_t W, gcry_mpi_t U, + gcry_mpi_t V, gcry_mpi_t M) + W = U + V \bmod M. + + -- Function: void gcry_mpi_sub (gcry_mpi_t W, gcry_mpi_t U, + gcry_mpi_t V) + W = U - V. + + -- Function: void gcry_mpi_sub_ui (gcry_mpi_t W, gcry_mpi_t U, + unsigned long V) + W = U - V. V is an unsigned integer. + + -- Function: void gcry_mpi_subm (gcry_mpi_t W, gcry_mpi_t U, + gcry_mpi_t V, gcry_mpi_t M) + W = U - V \bmod M. + + -- Function: void gcry_mpi_mul (gcry_mpi_t W, gcry_mpi_t U, + gcry_mpi_t V) + W = U * V. + + -- Function: void gcry_mpi_mul_ui (gcry_mpi_t W, gcry_mpi_t U, + unsigned long V) + W = U * V. V is an unsigned integer. + + -- Function: void gcry_mpi_mulm (gcry_mpi_t W, gcry_mpi_t U, + gcry_mpi_t V, gcry_mpi_t M) + W = U * V \bmod M. + + -- Function: void gcry_mpi_mul_2exp (gcry_mpi_t W, gcry_mpi_t U, + unsigned long E) + W = U * 2^e. + + -- Function: void gcry_mpi_div (gcry_mpi_t Q, gcry_mpi_t R, + gcry_mpi_t DIVIDEND, gcry_mpi_t DIVISOR, int ROUND) + Q = DIVIDEND / DIVISOR, R = DIVIDEND \bmod DIVISOR. Q and R may + be passed as `NULL'. ROUND should be negative or 0. + + -- Function: void gcry_mpi_mod (gcry_mpi_t R, gcry_mpi_t DIVIDEND, + gcry_mpi_t DIVISOR) + R = DIVIDEND \bmod DIVISOR. + + -- Function: void gcry_mpi_powm (gcry_mpi_t W, const gcry_mpi_t B, + const gcry_mpi_t E, const gcry_mpi_t M) + W = B^e \bmod M. + + -- Function: int gcry_mpi_gcd (gcry_mpi_t G, gcry_mpi_t A, + gcry_mpi_t B) + Set G to the greatest common divisor of A and B. Return true if + the G is 1. + + -- Function: int gcry_mpi_invm (gcry_mpi_t X, gcry_mpi_t A, + gcry_mpi_t M) + Set X to the multiplicative inverse of A \bmod M. Return true if + the inverse exists. + + +File: gcrypt.info, Node: Comparisons, Next: Bit manipulations, Prev: Calculations, Up: MPI library + +10.5 Comparisons +================ + +The next 2 functions are used to compare MPIs: + + -- Function: int gcry_mpi_cmp (const gcry_mpi_t U, const gcry_mpi_t V) + Compare the multi-precision-integers number U and V returning 0 + for equality, a positive value for U > V and a negative for U < V. + + -- Function: int gcry_mpi_cmp_ui (const gcry_mpi_t U, unsigned long V) + Compare the multi-precision-integers number U with the unsigned + integer V returning 0 for equality, a positive value for U > V and + a negative for U < V. + + +File: gcrypt.info, Node: Bit manipulations, Next: Miscellaneous, Prev: Comparisons, Up: MPI library + +10.6 Bit manipulations +====================== + +There are a couple of functions to get information on arbitrary bits in +an MPI and to set or clear them: + + -- Function: unsigned int gcry_mpi_get_nbits (gcry_mpi_t A) + Return the number of bits required to represent A. + + -- Function: int gcry_mpi_test_bit (gcry_mpi_t A, unsigned int N) + Return true if bit number N (counting from 0) is set in A. + + -- Function: void gcry_mpi_set_bit (gcry_mpi_t A, unsigned int N) + Set bit number N in A. + + -- Function: void gcry_mpi_clear_bit (gcry_mpi_t A, unsigned int N) + Clear bit number N in A. + + -- Function: void gcry_mpi_set_highbit (gcry_mpi_t A, unsigned int N) + Set bit number N in A and clear all bits greater than N. + + -- Function: void gcry_mpi_clear_highbit (gcry_mpi_t A, unsigned int N) + Clear bit number N in A and all bits greater than N. + + -- Function: void gcry_mpi_rshift (gcry_mpi_t X, gcry_mpi_t A, + unsigned int N) + Shift the value of A by N bits to the right and store the result + in X. + + -- Function: void gcry_mpi_lshift (gcry_mpi_t X, gcry_mpi_t A, + unsigned int N) + Shift the value of A by N bits to the left and store the result in + X. + + +File: gcrypt.info, Node: Miscellaneous, Prev: Bit manipulations, Up: MPI library + +10.7 Miscellaneous +================== + + -- Function: gcry_mpi_t gcry_mpi_set_opaque (gcry_mpi_t A, void *P, + unsigned int NBITS) + Store NBITS of the value P points to in A and mark A as an opaque + value (i.e. an value that can't be used for any math calculation + and is only used to store an arbitrary bit pattern in A). + + WARNING: Never use an opaque MPI for actual math operations. The + only valid functions are gcry_mpi_get_opaque and gcry_mpi_release. + Use gcry_mpi_scan to convert a string of arbitrary bytes into an + MPI. + + + -- Function: void * gcry_mpi_get_opaque (gcry_mpi_t A, + unsigned int *NBITS) + Return a pointer to an opaque value stored in A and return its + size in NBITS. Note that the returned pointer is still owned by A + and that the function should never be used for an non-opaque MPI. + + -- Function: void gcry_mpi_set_flag (gcry_mpi_t A, + enum gcry_mpi_flag FLAG) + Set the FLAG for the MPI A. Currently only the flag + `GCRYMPI_FLAG_SECURE' is allowed to convert A into an MPI stored + in "secure memory". + + -- Function: void gcry_mpi_clear_flag (gcry_mpi_t A, + enum gcry_mpi_flag FLAG) + Clear FLAG for the multi-precision-integers A. Note that this + function is currently useless as no flags are allowed. + + -- Function: int gcry_mpi_get_flag (gcry_mpi_t A, + enum gcry_mpi_flag FLAG) + Return true when the FLAG is set for A. + + -- Function: void gcry_mpi_randomize (gcry_mpi_t W, + unsigned int NBITS, enum gcry_random_level LEVEL) + Set the multi-precision-integers W to a random value of NBITS, + using random data quality of level LEVEL. In case NBITS is not a + multiple of a byte, NBITS is rounded up to the next byte boundary. + When using a LEVEL of `GCRY_WEAK_RANDOM' this function makes use of + `gcry_create_nonce'. + + +File: gcrypt.info, Node: Prime numbers, Next: Utilities, Prev: MPI library, Up: Top + +11 Prime numbers +**************** + +* Menu: + +* Generation:: Generation of new prime numbers. +* Checking:: Checking if a given number is prime. + + +File: gcrypt.info, Node: Generation, Next: Checking, Up: Prime numbers + +11.1 Generation +=============== + + -- Function: gcry_error_t gcry_prime_generate (gcry_mpi_t + *PRIME,unsigned int PRIME_BITS, unsigned int FACTOR_BITS, + gcry_mpi_t **FACTORS, gcry_prime_check_func_t CB_FUNC, void + *CB_ARG, gcry_random_level_t RANDOM_LEVEL, unsigned int FLAGS) + Generate a new prime number of PRIME_BITS bits and store it in + PRIME. If FACTOR_BITS is non-zero, one of the prime factors of + (PRIME - 1) / 2 must be FACTOR_BITS bits long. If FACTORS is + non-zero, allocate a new, `NULL'-terminated array holding the + prime factors and store it in FACTORS. FLAGS might be used to + influence the prime number generation process. + + -- Function: gcry_error_t gcry_prime_group_generator (gcry_mpi_t *R_G, + gcry_mpi_t PRIME, gcry_mpi_t *FACTORS, gcry_mpi_t START_G) + Find a generator for PRIME where the factorization of (PRIME-1) is + in the `NULL' terminated array FACTORS. Return the generator as a + newly allocated MPI in R_G. If START_G is not NULL, use this as + the start for the search. + + -- Function: void gcry_prime_release_factors (gcry_mpi_t *FACTORS) + Convenience function to release the FACTORS array. + + +File: gcrypt.info, Node: Checking, Prev: Generation, Up: Prime numbers + +11.2 Checking +============= + + -- Function: gcry_error_t gcry_prime_check (gcry_mpi_t P, unsigned int + FLAGS) + Check wether the number P is prime. Returns zero in case P is + indeed a prime, returns `GPG_ERR_NO_PRIME' in case P is not a + prime and a different error code in case something went horribly + wrong. + + +File: gcrypt.info, Node: Utilities, Next: Architecture, Prev: Prime numbers, Up: Top + +12 Utilities +************ + +* Menu: + +* Memory allocation:: Functions related with memory allocation. + + +File: gcrypt.info, Node: Memory allocation, Up: Utilities + +12.1 Memory allocation +====================== + + -- Function: void * gcry_malloc (size_t N) + This function tries to allocate N bytes of memory. On success it + returns a pointer to the memory area, in an out-of-core condition, + it returns NULL. + + -- Function: void * gcry_malloc_secure (size_t N) + Like `gcry_malloc', but uses secure memory. + + -- Function: void * gcry_calloc (size_t N, size_t M) + This function allocates a cleared block of memory (i.e. + initialized with zero bytes) long enough to contain a vector of N + elements, each of size M bytes. On success it returns a pointer + to the memory block; in an out-of-core condition, it returns NULL. + + -- Function: void * gcry_calloc_secure (size_t N, size_t M) + Like `gcry_calloc', but uses secure memory. + + -- Function: void * gcry_realloc (void *P, size_t N) + This function tries to resize the memory area pointed to by P to N + bytes. On success it returns a pointer to the new memory area, in + an out-of-core condition, it returns NULL. Depending on whether + the memory pointed to by P is secure memory or not, gcry_realloc + tries to use secure memory as well. + + -- Function: void gcry_free (void *P) + Release the memory area pointed to by P. + + +File: gcrypt.info, Node: Architecture, Next: Self-Tests, Prev: Utilities, Up: Top + +13 Architecture +*************** + +This chapter describes the internal architecture of Libgcrypt. + + Libgcrypt is a function library written in ISO C-90. Any compliant +compiler should be able to build Libgcrypt as long as the target is +either a POSIX platform or compatible to the API used by Windows NT. +Provisions have been take so that the library can be directly used from +C++ applications; however building with a C++ compiler is not supported. + + Building Libgcrypt is done by using the common `./configure && make' +approach. The configure command is included in the source distribution +and as a portable shell script it works on any Unix-alike system. The +result of running the configure script are a C header file +(`config.h'), customized Makefiles, the setup of symbolic links and a +few other things. After that the make tool builds and optionally +installs the library and the documentation. See the files `INSTALL' +and `README' in the source distribution on how to do this. + + Libgcrypt is developed using a Subversion(1) repository. Although +all released versions are tagged in this repository, they should not be +used to build production versions of Libgcrypt. Instead released +tarballs should be used. These tarballs are available from several +places with the master copy at <ftp://ftp.gnupg.org/gcrypt/libgcrypt/>. +Announcements of new releases are posted to the +<gnupg-announce@gnupg.org> mailing list(2). + + +Figure 13.1: Libgcrypt subsystems + + Libgcrypt consists of several subsystems (*note Figure 13.1: +fig:subsystems.) and all these subsystems provide a public API; this +includes the helper subsystems like the one for S-expressions. The API +style depends on the subsystem; in general an open-use-close approach +is implemented. The open returns a handle to a context used for all +further operations on this handle, several functions may then be used +on this handle and a final close function releases all resources +associated with the handle. + +* Menu: + +* Public-Key Subsystem Architecture:: About public keys. +* Symmetric Encryption Subsystem Architecture:: About standard ciphers. +* Hashing and MACing Subsystem Architecture:: About hashing. +* Multi-Precision-Integer Subsystem Architecture:: About big integers. +* Prime-Number-Generator Subsystem Architecture:: About prime numbers. +* Random-Number Subsystem Architecture:: About random stuff. + + ---------- Footnotes ---------- + + (1) A version control system available for many platforms + + (2) See `http://www.gnupg.org/documentation/mailing-lists.en.html' +for details. + + +File: gcrypt.info, Node: Public-Key Subsystem Architecture, Next: Symmetric Encryption Subsystem Architecture, Up: Architecture + +13.1 Public-Key Architecture +============================ + +Libgcrypt implements two interfaces for public key cryptography: The +standard interface is PK interface using functions in the `gcry_pk_' +name space. The AC interface in an alternative one which is now +deprecated and will not be further described. The AC interface is also +disabled in FIPS mode. + + Because public key cryptography is almost always used to process +small amounts of data (hash values or session keys), the interface is +not implemented using the open-use-close paradigm, but with single +self-contained functions. Due to the wide variety of parameters +required by different algorithms S-expressions, as flexible way to +convey these parameters, are used. There is a set of helper functions +to work with these S-expressions. + + Aside of functions to register new algorithms, map algorithms names +to algorithms identifiers and to lookup properties of a key, the +following main functions are available: + +`gcry_pk_encrypt' + Encrypt data using a public key. + +`gcry_pk_decrypt' + Decrypt data using a private key. + +`gcry_pk_sign' + Sign data using a private key. + +`gcry_pk_verify' + Verify that a signature matches the data. + +`gcry_pk_testkey' + Perform a consistency over a public or private key. + +`gcry_pk_genkey' + Create a new public/private key pair. + + + With the help of the module registration system all these functions +lookup the module implementing the algorithm and pass the actual work +to that module. The parsing of the S-expression input and the +construction of S-expression for the return values is done by the high +level code (`cipher/pubkey.c'). Thus the internal interface between +the algorithm modules and the high level functions passes data in a +custom format. The interface to the modules is published +(`gcrypt-modules.h') so that it can used to register external +implementations of algorithms with Libgcrypt. However, for some +algorithms this module interface is to limited and thus for the +internal modules an extra interface is sometimes used to convey more +information. + + By default Libgcrypt uses a blinding technique for RSA decryption to +mitigate real world timing attacks over a network: Instead of using the +RSA decryption directly, a blinded value y = x r^e \bmod n is decrypted +and the unblinded value x' = y' r^-1 \bmod n returned. The blinding +value r is a random value with the size of the modulus n and generated +with `GCRY_WEAK_RANDOM' random level. + + The algorithm used for RSA and DSA key generation depends on whether +Libgcrypt is operated in standard or in FIPS mode. In standard mode an +algorithm based on the Lim-Lee prime number generator is used. In FIPS +mode RSA keys are generated as specified in ANSI X9.31 (1998) and DSA +keys as specified in FIPS 186-2. + + +File: gcrypt.info, Node: Symmetric Encryption Subsystem Architecture, Next: Hashing and MACing Subsystem Architecture, Prev: Public-Key Subsystem Architecture, Up: Architecture + +13.2 Symmetric Encryption Subsystem Architecture +================================================ + +The interface to work with symmetric encryption algorithms is made up +of functions from the `gcry_cipher_' name space. The implementation +follows the open-use-close paradigm and uses registered algorithm +modules for the actual work. Unless a module implements optimized +cipher mode implementations, the high level code (`cipher/cipher.c') +implements the modes and calls the core algorithm functions to process +each block. + + The most important functions are: + +`gcry_cipher_open' + Create a new instance to encrypt or decrypt using a specified + algorithm and mode. + +`gcry_cipher_close' + Release an instance. + +`gcry_cipher_setkey' + Set a key to be used for encryption or decryption. + +`gcry_cipher_setiv' + Set an initialization vector to be used for encryption or + decryption. + +`gcry_cipher_encrypt' +`gcry_cipher_decrypt' + Encrypt or decrypt data. These functions may be called with + arbitrary amounts of data and as often as needed to encrypt or + decrypt all data. + + + There are also functions to query properties of algorithms or +context, like block length, key length, map names or to enable features +like padding methods. + + +File: gcrypt.info, Node: Hashing and MACing Subsystem Architecture, Next: Multi-Precision-Integer Subsystem Architecture, Prev: Symmetric Encryption Subsystem Architecture, Up: Architecture + +13.3 Hashing and MACing Subsystem Architecture +============================================== + +The interface to work with message digests and CRC algorithms is made +up of functions from the `gcry_md_' name space. The implementation +follows the open-use-close paradigm and uses registered algorithm +modules for the actual work. Although CRC algorithms are not +considered cryptographic hash algorithms, they share enough properties +so that it makes sense to handle them in the same way. It is possible +to use several algorithms at once with one context and thus compute +them all on the same data. + + The most important functions are: + +`gcry_md_open' + Create a new message digest instance and optionally enable one + algorithm. A flag may be used to turn the message digest algorithm + into a HMAC algorithm. + +`gcry_md_enable' + Enable an additional algorithm for the instance. + +`gcry_md_setkey' + Set the key for the MAC. + +`gcry_md_write' + Pass more data for computing the message digest to an instance. + +`gcry_md_putc' + Buffered version of `gcry_md_write' implemented as a macro. + +`gcry_md_read' + Finalize the computation of the message digest or HMAC and return + the result. + +`gcry_md_close' + Release an instance + +`gcry_md_hash_buffer' + Convenience function to directly compute a message digest over a + memory buffer without the need to create an instance first. + + + There are also functions to query properties of algorithms or the +instance, like enabled algorithms, digest length, map algorithm names. +it is also possible to reset an instance or to copy the current state +of an instance at any time. Debug functions to write the hashed data +to files are available as well. + + +File: gcrypt.info, Node: Multi-Precision-Integer Subsystem Architecture, Next: Prime-Number-Generator Subsystem Architecture, Prev: Hashing and MACing Subsystem Architecture, Up: Architecture + +13.4 Multi-Precision-Integer Subsystem Architecture +=================================================== + +The implementation of Libgcrypt's big integer computation code is based +on an old release of GNU Multi-Precision Library (GMP). The decision +not to use the GMP library directly was due to stalled development at +that time and due to security requirements which could not be provided +by the code in GMP. As GMP does, Libgcrypt provides high performance +assembler implementations of low level code for several CPUS to gain +much better performance than with a generic C implementation. + +Major features of Libgcrypt's multi-precision-integer code compared to +GMP are: + + * Avoidance of stack based allocations to allow protection against + swapping out of sensitive data and for easy zeroing of sensitive + intermediate results. + + * Optional use of secure memory and tracking of its use so that + results are also put into secure memory. + + * MPIs are identified by a handle (implemented as a pointer) to give + better control over allocations and to augment them with extra + properties like opaque data. + + * Removal of unnecessary code to reduce complexity. + + * Functions specialized for public key cryptography. + + + +File: gcrypt.info, Node: Prime-Number-Generator Subsystem Architecture, Next: Random-Number Subsystem Architecture, Prev: Multi-Precision-Integer Subsystem Architecture, Up: Architecture + +13.5 Prime-Number-Generator Subsystem Architecture +================================================== + +Libgcrypt provides an interface to its prime number generator. These +functions make use of the internal prime number generator which is +required for the generation for public key key pairs. The plain prime +checking function is exported as well. + + The generation of random prime numbers is based on the Lim and Lee +algorithm to create practically save primes.(1) This algorithm creates +a pool of smaller primes, select a few of them to create candidate +primes of the form 2 * p_0 * p_1 * ... * p_n + 1, tests the candidate +for primality and permutates the pool until a prime has been found. It +is possible to clamp one of the small primes to a certain size to help +DSA style algorithms. Because most of the small primes in the pool are +not used for the resulting prime number, they are saved for later use +(see `save_pool_prime' and `get_pool_prime' in `cipher/primegen.c'). +The prime generator optionally supports the finding of an appropriate +generator. + +The primality test works in three steps: + + 1. The standard sieve algorithm using the primes up to 4999 is used + as a quick first check. + + 2. A Fermat test filters out almost all non-primes. + + 3. A 5 round Rabin-Miller test is finally used. The first round uses + a witness of 2, whereas the next rounds use a random witness. + + + To support the generation of RSA and DSA keys in FIPS mode according +to X9.31 and FIPS 186-2, Libgcrypt implements two additional prime +generation functions: `_gcry_derive_x931_prime' and +`_gcry_generate_fips186_2_prime'. These functions are internal and not +available through the public API. + + ---------- Footnotes ---------- + + (1) Chae Hoon Lim and Pil Joong Lee. A key recovery attack on +discrete log-based shemes using a prime order subgroup. In Burton S. +Kaliski Jr., editor, Advances in Cryptology: Crypto '97, pages +249Â-263, Berlin / Heidelberg / New York, 1997. Springer-Verlag. +Described on page 260. + + +File: gcrypt.info, Node: Random-Number Subsystem Architecture, Prev: Prime-Number-Generator Subsystem Architecture, Up: Architecture + +13.6 Random-Number Subsystem Architecture +========================================= + +Libgcrypt provides 3 levels or random quality: The level +`GCRY_VERY_STRONG_RANDOM' usually used for key generation, the level +`GCRY_STRONG_RANDOM' for all other strong random requirements and the +function `gcry_create_nonce' which is used for weaker usages like +nonces. There is also a level `GCRY_WEAK_RANDOM' which in general maps +to `GCRY_STRONG_RANDOM' except when used with the function +`gcry_mpi_randomize', where it randomizes an multi-precision-integer +using the `gcry_create_nonce' function. + +There are two distinct random generators available: + + * The Continuously Seeded Pseudo Random Number Generator (CSPRNG), + which is based on the classic GnuPG derived big pool + implementation. Implemented in `random/random-csprng.c' and used + by default. + + * A FIPS approved ANSI X9.31 PRNG using AES with a 128 bit key. + Implemented in `random/random-fips.c' and used if Libgcrypt is in + FIPS mode. + +Both generators make use of so-called entropy gathering modules: + +rndlinux + Uses the operating system provided `/dev/random' and + `/dev/urandom' devices. + +rndunix + Runs several operating system commands to collect entropy from + sources like virtual machine and process statistics. It is a kind + of poor-man's `/dev/random' implementation. It is not available in + FIPS mode. + +rndegd + Uses the operating system provided Entropy Gathering Daemon (EGD). + The EGD basically uses the same algorithms as rndunix does. + However as a system daemon it keeps on running and thus can serve + several processes requiring entropy input and does not waste + collected entropy if the application does not need all the + collected entropy. It is not available in FIPS mode. + +rndw32 + Targeted for the Microsoft Windows OS. It uses certain properties + of that system and is the only gathering module available for that + OS. + +rndhw + Extra module to collect additional entropy by utilizing a hardware + random number generator. As of now the only supported hardware + RNG is the Padlock engine of VIA (Centaur) CPUs. It is not + available in FIPS mode. + + +* Menu: + +* CSPRNG Description:: Description of the CSPRNG. +* FIPS PRNG Description:: Description of the FIPS X9.31 PRNG. + + +File: gcrypt.info, Node: CSPRNG Description, Next: FIPS PRNG Description, Up: Random-Number Subsystem Architecture + +13.6.1 Description of the CSPRNG +-------------------------------- + +This random number generator is loosely modelled after the one +described in Peter Gutmann's paper: "Software Generation of Practically +Strong Random Numbers".(1) + + A pool of 600 bytes is used and mixed using the core RIPE-MD160 hash +transform function. Several extra features are used to make the robust +against a wide variety of attacks and to protect against failures of +subsystems. The state of the generator may be saved to a file and +initially seed form a file. + + Depending on how Libgcrypt was build the generator is able to select +the best working entropy gathering module. It makes use of the slow +and fast collection methods and requires the pool to initially seeded +form the slow gatherer or a seed file. An entropy estimation is used +to mix in enough data from the gather modules before returning the +actual random output. Process fork detection and protection is +implemented. + + The implementation of the nonce generator (for `gcry_create_nonce') +is a straightforward repeated hash design: A 28 byte buffer is +initially seeded with the PID and the time in seconds in the first 20 +bytes and with 8 bytes of random taken from the `GCRY_STRONG_RANDOM' +generator. Random numbers are then created by hashing all the 28 bytes +with SHA-1 and saving that again in the first 20 bytes. The hash is +also returned as result. + + ---------- Footnotes ---------- + + (1) Also described in chapter 6 of his book "Cryptographic Security +Architecture", New York, 2004, ISBN 0-387-95387-6. + + +File: gcrypt.info, Node: FIPS PRNG Description, Prev: CSPRNG Description, Up: Random-Number Subsystem Architecture + +13.6.2 Description of the FIPS X9.31 PRNG +----------------------------------------- + +The core of this deterministic random number generator is implemented +according to the document "NIST-Recommended Random Number Generator +Based on ANSI X9.31 Appendix A.2.4 Using the 3-Key Triple DES and AES +Algorithms", dated 2005-01-31. This implementation uses the AES +variant. + + The generator is based on contexts to utilize the same core functions +for all random levels as required by the high-level interface. All +random generators return their data in 128 bit blocks. If the caller +requests less bits, the extra bits are not used. The key for each +generator is only set once at the first time a generator context is +used. The seed value is set along with the key and again after 1000 +output blocks. + + On Unix like systems the `GCRY_VERY_STRONG_RANDOM' and +`GCRY_STRONG_RANDOM' generators are keyed and seeded using the rndlinux +module with the `/dev/radnom' device. Thus these generators may block +until the OS kernel has collected enough entropy. When used with +Microsoft Windows the rndw32 module is used instead. + + The generator used for `gcry_create_nonce' is keyed and seeded from +the `GCRY_STRONG_RANDOM' generator. Thus is may also block if the +`GCRY_STRONG_RANDOM' generator has not yet been used before and thus +gets initialized on the first use by `gcry_create_nonce'. This special +treatment is justified by the weaker requirements for a nonce generator +and to save precious kernel entropy for use by the "real" random +generators. + + A self-test facility uses a separate context to check the +functionality of the core X9.31 functions using a known answers test. +During runtime each output block is compared to the previous one to +detect a stucked generator. + + The DT value for the generator is made up of the current time down to +microseconds (if available) and a free running 64 bit counter. When +used with the test context the DT value is taken from the context and +incremented on each use. + + +File: gcrypt.info, Node: Self-Tests, Next: FIPS Mode, Prev: Architecture, Up: Top + +Appendix A Description of the Self-Tests +**************************************** + +In addition to the build time regression test suite, Libgcrypt +implements self-tests to be performed at runtime. Which self-tests are +actually used depends on the mode Libgcrypt is used in. In standard +mode a limited set of self-tests is run at the time an algorithm is +first used. Note that not all algorithms feature a self-test in +standard mode. The `GCRYCTL_SELFTEST' control command may be used to +run all implemented self-tests at any time; this will even run more +tests than those run in FIPS mode. + + If any of the self-tests fails, the library immediately returns an +error code to the caller. If Libgcrypt is in FIPS mode the self-tests +will be performed within the "Self-Test" state and any failure puts the +library into the "Error" state. + +A.1 Power-Up Tests +================== + +Power-up tests are only performed if Libgcrypt is in FIPS mode. + +A.1.1 Symmetric Cipher Algorithm Power-Up Tests +----------------------------------------------- + +The following symmetric encryption algorithm tests are run during +power-up: + +3DES + To test the 3DES 3-key EDE encryption in ECB mode these tests are + run: + 1. A known answer test is run on a 64 bit test vector processed + by 64 rounds of Single-DES block encryption and decryption + using a key changed with each round. + + 2. A known answer test is run on a 64 bit test vector processed + by 16 rounds of 2-key and 3-key Triple-DES block encryption + and decryptions using a key changed with each round. + + 3. 10 known answer tests using 3-key Triple-DES EDE encryption, + comparing the ciphertext to the known value, then running a + decryption and comparing it to the initial plaintext. + (`cipher/des.c:selftest') + +AES-128 + A known answer tests is run using one test vector and one test key + with AES in ECB mode. (`cipher/rijndael.c:selftest_basic_128') + +AES-192 + A known answer tests is run using one test vector and one test key + with AES in ECB mode. (`cipher/rijndael.c:selftest_basic_192') + +AES-256 + A known answer tests is run using one test vector and one test key + with AES in ECB mode. (`cipher/rijndael.c:selftest_basic_256') + +A.1.2 Hash Algorithm Power-Up Tests +----------------------------------- + +The following hash algorithm tests are run during power-up: + +SHA-1 + A known answer test using the string `"abc"' is run. + (`cipher/sha1.c:selftests_sha1') + +SHA-224 + A known answer test using the string `"abc"' is run. + (`cipher/sha256.c:selftests_sha224') + +SHA-256 + A known answer test using the string `"abc"' is run. + (`cipher/sha256.c:selftests_sha256') + +SHA-384 + A known answer test using the string `"abc"' is run. + (`cipher/sha512.c:selftests_sha384') + +SHA-512 + A known answer test using the string `"abc"' is run. + (`cipher/sha512.c:selftests_sha512') + +A.1.3 MAC Algorithm Power-Up Tests +---------------------------------- + +The following MAC algorithm tests are run during power-up: + +HMAC SHA-1 + A known answer test using 9 byte of data and a 64 byte key is run. + (`cipher/hmac-tests.c:selftests_sha1') + +HMAC SHA-224 + A known answer test using 28 byte of data and a 4 byte key is run. + (`cipher/hmac-tests.c:selftests_sha224') + +HMAC SHA-256 + A known answer test using 28 byte of data and a 4 byte key is run. + (`cipher/hmac-tests.c:selftests_sha256') + +HMAC SHA-384 + A known answer test using 28 byte of data and a 4 byte key is run. + (`cipher/hmac-tests.c:selftests_sha384') + +HMAC SHA-512 + A known answer test using 28 byte of data and a 4 byte key is run. + (`cipher/hmac-tests.c:selftests_sha512') + +A.1.4 Random Number Power-Up Test +--------------------------------- + +The DRNG is tested during power-up this way: + + 1. Requesting one block of random using the public interface to check + general working and the duplicated block detection. + + 2. 3 know answer tests using pre-defined keys, seed and initial DT + values. For each test 3 blocks of 16 bytes are requested and + compared to the expected result. The DT value is incremented for + each block. + +A.1.5 Public Key Algorithm Power-Up Tests +----------------------------------------- + +The public key algorithms are tested during power-up: + +RSA + A pre-defined 1024 bit RSA key is used and these tests are run in + turn: + 1. Conversion of S-expression to internal format. + (`cipher/rsa.c:selftests_rsa') + + 2. Private key consistency check. (`cipher/rsa.c:selftests_rsa') + + 3. A pre-defined 20 byte value is signed with PKCS#1 padding for + SHA-1. The result is verified using the public key against + the original data and against modified data. + (`cipher/rsa.c:selftest_sign_1024') + + 4. A 1000 bit random value is encrypted and checked that it does + not match the orginal random value. The encrtypted result is + then decrypted and checked that it macthes the original + random value. (`cipher/rsa.c:selftest_encr_1024') + +DSA + A pre-defined 1024 bit DSA key is used and these tests are run in + turn: + 1. Conversion of S-expression to internal format. + (`cipher/dsa.c:selftests_dsa') + + 2. Private key consistency check. (`cipher/dsa.c:selftests_dsa') + + 3. A pre-defined 20 byte value is signed with PKCS#1 padding for + SHA-1. The result is verified using the public key against + the original data and against modified data. + (`cipher/dsa.c:selftest_sign_1024') + +A.1.6 Integrity Power-Up Tests +------------------------------ + +The integrity of the Libgcrypt is tested during power-up but only if +checking has been enabled at build time. The check works by computing +a HMAC SHA-256 checksum over the file used to load Libgcrypt into +memory. That checksum is compared against a checksum stored in a file +of the same name but with a single dot as a prefix and a suffix of +`.hmac'. + +A.1.7 Critical Functions Power-Up Tests +--------------------------------------- + +The 3DES weak key detection is tested during power-up by calling the +detection function with keys taken from a table listening all weak +keys. The table itself is protected using a SHA-1 hash. +(`cipher/des.c:selftest') + +A.2 Conditional Tests +===================== + +The conditional tests are performed if a certain contidion is met. +This may occur at any time; the library does not necessary enter the +"Self-Test" state to run these tests but will transit to the "Error" +state if a test failed. + +A.2.1 Key-Pair Generation Tests +------------------------------- + +After an asymmetric key-pair has been generated, Libgcrypt runs a +pair-wise consistency tests on the generated key. On failure the +generated key is not used, an error code is returned and, if in FIPS +mode, the library is put into the "Error" state. + +RSA + The test uses a random number 64 bits less the size of the modulus + as plaintext and runs an encryption and decryption operation in + turn. The encrypted value is checked to not match the plaintext + and the result of the decryption is checked to match the plaintext. + + A new random number of the same size is generated, signed and + verified to test the correctness of the signing operation. As a + second signing test, the signature is modified by incrementing its + value and then verified with the expected result that the + verification fails. (`cipher/rsa.c:test_keys') + +DSA + The test uses a random number of the size of the Q parameter to + create a signature and then checks that the signature verifies. + As a second signing test, the data is modified by incrementing its + value and then verified against the signature with the expected + result that the verification fails. (`cipher/dsa.c:test_keys') + +A.2.2 Software Load Tests +------------------------- + +Loading of extra modules into libgcrypt is disabled in FIPS mode and +thus no tests are implemented. (`cipher/cipher.c:_gcry_cipher_register', +`cipher/md.c:_gcry_md_register', `cipher/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 libray is put into the "Fatal-Error" state. +(`random/random-fips.c:x931_aes_driver') + +A.3 Application Requested Tests +=============================== + +The application may requests tests at any time by means of the +`GCRYCTL_SELFTEST' control command. Note that using these tests is not +FIPS conform: Although Libgcrypt rejects all application requests for +services while running self-tests, it does not ensure that no other +operations of Libgcrypt are still being executed. Thus, in FIPS mode +an application requesting self-tests needs to power-cycle Libgcrypt +instead. + + When self-tests are requested, Libgcrypt runs all the tests it does +during power-up as well as a few extra checks as described below. + +A.3.1 Symmetric Cipher Algorithm Tests +-------------------------------------- + +The following symmetric encryption algorithm tests are run in addition +to the power-up tests: + +AES-128 + A known answer tests with test vectors taken from NIST SP800-38a + and using the high level functions is run for block modes CFB and + OFB. + + +A.3.2 Hash Algorithm Tests +-------------------------- + +The following hash algorithm tests are run in addition to the power-up +tests: + +SHA-1 +SHA-224 +SHA-256 + 1. A known answer test using a 56 byte string is run. + + 2. A known answer test using a string of one million letters "a" + is run. + (`cipher/sha1.c:selftests_sha1', + `cipher/sha256.c:selftests_sha224', + `cipher/sha256.c:selftests_sha256') + +SHA-384 + +SHA-512 + 1. A known answer test using a 112 byte string is run. + + 2. A known answer test using a string of one million letters "a" + is run. + (`cipher/sha512.c:selftests_sha384', + `cipher/sha512.c:selftests_sha512') + +A.3.3 MAC Algorithm Tests +------------------------- + +The following MAC algorithm tests are run in addition to the power-up +tests: + +HMAC SHA-1 + 1. A known answer test using 9 byte of data and a 20 byte key is + run. + + 2. A known answer test using 9 byte of data and a 100 byte key + is run. + + 3. A known answer test using 9 byte of data and a 49 byte key is + run. + (`cipher/hmac-tests.c:selftests_sha1') + +HMAC SHA-224 +HMAC SHA-256 +HMAC SHA-384 +HMAC SHA-512 + 1. A known answer test using 9 byte of data and a 20 byte key is + run. + + 2. A known answer test using 50 byte of data and a 20 byte key + is run. + + 3. A known answer test using 50 byte of data and a 26 byte key + is run. + + 4. A known answer test using 54 byte of data and a 131 byte key + is run. + + 5. A known answer test using 152 byte of data and a 131 byte key + is run. + (`cipher/hmac-tests.c:selftests_sha224', + `cipher/hmac-tests.c:selftests_sha256', + `cipher/hmac-tests.c:selftests_sha384', + `cipher/hmac-tests.c:selftests_sha512') + + +File: gcrypt.info, Node: FIPS Mode, Next: Library Copying, Prev: Self-Tests, Up: Top + +Appendix B Description of the FIPS Mode +*************************************** + +This appendix gives detailed information pertaining to the FIPS mode. +In particular, the changes to the standard mode and the finite state +machine are described. The self-tests required in this mode are +described in the appendix on self-tests. + +B.1 Restrictions in FIPS Mode +============================= + +If Libgcrypt is used in FIPS mode these restrictions are effective: + + * The cryptographic algorithms are restricted to this list: + + GCRY_CIPHER_3DES + 3 key EDE Triple-DES symmetric encryption. + + GCRY_CIPHER_AES128 + AES 128 bit symmetric encryption. + + GCRY_CIPHER_AES192 + AES 192 bit symmetric encryption. + + GCRY_CIPHER_AES256 + AES 256 bit symmetric encryption. + + GCRY_MD_SHA1 + SHA-1 message digest. + + GCRY_MD_SHA224 + SHA-224 message digest. + + GCRY_MD_SHA256 + SHA-256 message digest. + + GCRY_MD_SHA384 + SHA-384 message digest. + + GCRY_MD_SHA512 + SHA-512 message digest. + + GCRY_MD_SHA1,GCRY_MD_FLAG_HMAC + HMAC using a SHA-1 message digest. + + GCRY_MD_SHA224,GCRY_MD_FLAG_HMAC + HMAC using a SHA-224 message digest. + + GCRY_MD_SHA256,GCRY_MD_FLAG_HMAC + HMAC using a SHA-256 message digest. + + GCRY_MD_SHA384,GCRY_MD_FLAG_HMAC + HMAC using a SHA-384 message digest. + + GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC + HMAC using a SHA-512 message digest. + + GCRY_PK_RSA + RSA encryption and signing. + + GCRY_PK_DSA + DSA signing. + + Note that the CRC algorithms are not considered cryptographic + algorithms and thus are in addition available. + + * RSA key generation refuses to create a key with a keysize of less + than 1024 bits. + + * DSA key generation refuses to create a key with a keysize other + than 1024 bits. + + * The `transient-key' flag for RSA and DSA key generation is ignored. + + * Support for the VIA Padlock engine is disabled. + + * FIPS mode may only be used on systems with a /dev/random device. + Switching into FIPS mode on other systems will fail at runtime. + + * Saving and loading a random seed file is ignored. + + * An X9.31 style random number generator is used in place of the + large-pool-CSPRNG generator. + + * The command `GCRYCTL_ENABLE_QUICK_RANDOM' is ignored. + + * The Alternative Public Key Interface (`gcry_ac_xxx') is not + supported and all API calls return an error. + + * Registration of external modules is not supported. + + * Message digest debugging is disabled. + + * All debug output related to cryptographic data is suppressed. + + * On-the-fly self-tests are not performed, instead self-tests are run + before entering operational state. + + * The function `gcry_set_allocation_handler' may not be used. If it + is used Libgcrypt disables FIPS mode unless Enforced FIPS mode is + enabled, in which case Libgcrypt will enter the error state. + + * The digest algorithm MD5 may not be used. If it is used Libgcrypt + disables FIPS mode unless Enforced FIPS mode is enabled, in which + case Libgcrypt will enter the error state. + + * In Enforced FIPS mode the command `GCRYCTL_DISABLE_SECMEM' is + ignored. In standard FIPS mode it disables FIPS mode. + + * A handler set by `gcry_set_outofcore_handler' is ignored. + + * A handler set by `gcry_set_fatalerror_handler' is ignored. + + + Note that when we speak about disabling FIPS mode, it merely means +that the function `gcry_fips_mode_active' returns false; it does not +mean that any non FIPS algorithms are allowed. + +B.2 FIPS Finite State Machine +============================= + +The FIPS mode of libgcrypt implements a finite state machine (FSM) using +8 states (*note tbl:fips-states::) and checks at runtime that only valid +transitions (*note tbl:fips-state-transitions::) may happen. + + +Figure B.1: FIPS mode state diagram + +States used by the FIPS FSM: +Power-Off + Libgcrypt is not runtime linked to another application. This + usually means that the library is not loaded into main memory. + This state is documentation only. + +Power-On + Libgcrypt is loaded into memory and API calls may be made. + Compiler introducted constructor functions may be run. Note that + Libgcrypt does not implement any arbitrary constructor functions + to be called by the operating system + +Init + The Libgcrypt initialization functions are performed and the + library has not yet run any self-test. + +Self-Test + Libgcrypt is performing self-tests. + +Operational + Libgcrypt is in the operational state and all interfaces may be + used. + +Error + Libgrypt is in the error state. When calling any FIPS relevant + interfaces they either return an error (`GPG_ERR_NOT_OPERATIONAL') + or put Libgcrypt into the Fatal-Error state and won't return. + +Fatal-Error + Libgcrypt is in a non-recoverable error state and will + automatically transit into the Shutdown state. + +Shutdown + Libgcrypt is about to be terminated and removed from the memory. + The application may at this point still runing cleanup handlers. + + +Table B.1: FIPS mode states + +The valid state transitions (*note Figure B.1: fig:fips-fsm.) are: +`1' + Power-Off to Power-On is implicitly done by the OS loading + Libgcrypt as a shared library and having it linked to an + application. + +`2' + Power-On to Init is triggered by the application calling the + Libgcrypt intialization function `gcry_check_version'. + +`3' + Init to Self-Test is either triggred by a dedicated API call or + implicit by invoking a libgrypt service conrolled by the FSM. + +`4' + Self-Test to Operational is triggered after all self-tests passed + successfully. + +`5' + Operational to Shutdown is an artifical state without any direct + action in Libgcrypt. When reaching the Shutdown state the library + is deinitialized and can't return to any other state again. + +`6' + Shutdown to Power-off is the process of removing Libgcrypt from the + computer's memory. For obvious reasons the Power-Off state can't + be represented within Libgcrypt and thus this transition is for + documentation only. + +`7' + Operational to Error is triggered if Libgcrypt detected an + application error which can't be returned to the caller but still + allows Libgcrypt to properly run. In the Error state all FIPS + relevant interfaces return an error code. + +`8' + Error to Shutdown is similar to the Operational to Shutdown + transition (5). + +`9' + Error to Fatal-Error is triggred if Libgrypt detects an fatal error + while already being in Error state. + +`10' + Fatal-Error to Shutdown is automatically entered by Libgcrypt + after having reported the error. + +`11' + Power-On to Shutdown is an artifical state to document that + Libgcrypt has not ye been initializaed but the process is about to + terminate. + +`12' + Power-On to Fatal-Error will be triggerd if certain Libgcrypt + functions are used without having reached the Init state. + +`13' + Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt + while running self-tests. + +`14' + Self-Test to Error is triggred by a failed self-test. + +`15' + Operational to Fatal-Error is triggered if Libcrypt encountered a + non-recoverable error. + +`16' + Operational to Self-Test is triggred if the application requested + to run the self-tests again. + +`17' + Error to Self-Test is triggered if the application has requested + to run self-tests to get to get back into operational state after + an error. + +`18' + Init to Error is triggered by errors in the initialization code. + +`19' + Init to Fatal-Error is triggered by non-recoverable errors in the + initialization code. + +`20' + Error to Error is triggered by errors while already in the Error + state. + + +Table B.2: FIPS mode state transitions + +B.3 FIPS Miscellaneous Information +================================== + +Libgcrypt does not do any key management on itself; the application +needs to care about it. Keys which are passed to Libgcrypt should be +allocated in secure memory as available with the functions +`gcry_malloc_secure' and `gcry_calloc_secure'. By calling `gcry_free' +on this memory, the memory and thus the keys are overwritten with zero +bytes before releasing the memory. + + For use with the random number generator, Libgcrypt generates 3 +internal keys which are stored in the encryption contexts used by the +RNG. These keys are stored in secure memory for the lifetime of the +process. Application are required to use `GCRYCTL_TERM_SECMEM' before +process termination. This will zero out the entire secure memory and +thus also the encryption contexts with these keys. + + +File: gcrypt.info, Node: Library Copying, Next: Copying, Prev: FIPS Mode, Up: Top + +GNU Lesser General Public License +********************************* + + Version 2.1, February 1999 + + Copyright (C) 1991, 1999 Free Software Foundation, Inc. + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + [This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence the + version number 2.1.] + +Preamble +======== + +The licenses for most software are designed to take away your freedom +to share and change it. By contrast, the GNU General Public Licenses +are intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software--typically libraries--of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of it +in new free programs; and that you are informed that you can do these +things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know that +what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and is +quite different from the ordinary General Public License. We use this +license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the "Lesser" General Public License because it +does _Less_ to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it +becomes a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of free +software. For example, permission to use the GNU C Library in non-free +programs enables many more people to use the whole GNU operating +system, as well as its variant, the GNU/Linux operating system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run that +program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + + GNU LESSER GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + 0. This License Agreement applies to any software library or other + program which contains a notice placed by the copyright holder or + other authorized party saying it may be distributed under the + terms of this Lesser General Public License (also called "this + License"). Each licensee is addressed as "you". + + A "library" means a collection of software functions and/or data + prepared so as to be conveniently linked with application programs + (which use some of those functions and data) to form executables. + + The "Library", below, refers to any such software library or work + which has been distributed under these terms. A "work based on the + Library" means either the Library or any derivative work under + copyright law: that is to say, a work containing the Library or a + portion of it, either verbatim or with modifications and/or + translated straightforwardly into another language. (Hereinafter, + translation is included without limitation in the term + "modification".) + + "Source code" for a work means the preferred form of the work for + making modifications to it. For a library, complete source code + means all the source code for all modules it contains, plus any + associated interface definition files, plus the scripts used to + control compilation and installation of the library. + + Activities other than copying, distribution and modification are + not covered by this License; they are outside its scope. The act + of running a program using the Library is not restricted, and + output from such a program is covered only if its contents + constitute a work based on the Library (independent of the use of + the Library in a tool for writing it). Whether that is true + depends on what the Library does and what the program that uses + the Library does. + + 1. You may copy and distribute verbatim copies of the Library's + complete source code as you receive it, in any medium, provided + that you conspicuously and appropriately publish on each copy an + appropriate copyright notice and disclaimer of warranty; keep + intact all the notices that refer to this License and to the + absence of any warranty; and distribute a copy of this License + along with the Library. + + You may charge a fee for the physical act of transferring a copy, + and you may at your option offer warranty protection in exchange + for a fee. + + 2. You may modify your copy or copies of the Library or any portion + of it, thus forming a work based on the Library, and copy and + distribute such modifications or work under the terms of Section 1 + above, provided that you also meet all of these conditions: + + a. The modified work must itself be a software library. + + b. You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c. You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + d. If a facility in the modified Library refers to a function or + a table of data to be supplied by an application program that + uses the facility, other than as an argument passed when the + facility is invoked, then you must make a good faith effort + to ensure that, in the event an application does not supply + such function or table, the facility still operates, and + performs whatever part of its purpose remains meaningful. + + (For example, a function in a library to compute square roots + has a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function + must be optional: if the application does not supply it, the + square root function must still compute square roots.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the + Library, and can be reasonably considered independent and separate + works in themselves, then this License, and its terms, do not + apply to those sections when you distribute them as separate + works. But when you distribute the same sections as part of a + whole which is a work based on the Library, the distribution of + the whole must be on the terms of this License, whose permissions + for other licensees extend to the entire whole, and thus to each + and every part regardless of who wrote it. + + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Library. + + In addition, mere aggregation of another work not based on the + Library with the Library (or with a work based on the Library) on + a volume of a storage or distribution medium does not bring the + other work under the scope of this License. + + 3. You may opt to apply the terms of the ordinary GNU General Public + License instead of this License to a given copy of the Library. + To do this, you must alter all the notices that refer to this + License, so that they refer to the ordinary GNU General Public + License, version 2, instead of to this License. (If a newer + version than version 2 of the ordinary GNU General Public License + has appeared, then you can specify that version instead if you + wish.) Do not make any other change in these notices. + + Once this change is made in a given copy, it is irreversible for + that copy, so the ordinary GNU General Public License applies to + all subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of + the Library into a program that is not a library. + + 4. You may copy and distribute the Library (or a portion or + derivative of it, under Section 2) in object code or executable + form under the terms of Sections 1 and 2 above provided that you + accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software + interchange. + + If distribution of object code is made by offering access to copy + from a designated place, then offering equivalent access to copy + the source code from the same place satisfies the requirement to + distribute the source code, even though third parties are not + compelled to copy the source along with the object code. + + 5. A program that contains no derivative of any portion of the + Library, but is designed to work with the Library by being + compiled or linked with it, is called a "work that uses the + Library". Such a work, in isolation, is not a derivative work of + the Library, and therefore falls outside the scope of this License. + + However, linking a "work that uses the Library" with the Library + creates an executable that is a derivative of the Library (because + it contains portions of the Library), rather than a "work that + uses the library". The executable is therefore covered by this + License. Section 6 states terms for distribution of such + executables. + + When a "work that uses the Library" uses material from a header + file that is part of the Library, the object code for the work may + be a derivative work of the Library even though the source code is + not. Whether this is true is especially significant if the work + can be linked without the Library, or if the work is itself a + library. The threshold for this to be true is not precisely + defined by law. + + If such an object file uses only numerical parameters, data + structure layouts and accessors, and small macros and small inline + functions (ten lines or less in length), then the use of the object + file is unrestricted, regardless of whether it is legally a + derivative work. (Executables containing this object code plus + portions of the Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may + distribute the object code for the work under the terms of Section + 6. Any executables containing that work also fall under Section 6, + whether or not they are linked directly with the Library itself. + + 6. As an exception to the Sections above, you may also combine or + link a "work that uses the Library" with the Library to produce a + work containing portions of the Library, and distribute that work + under terms of your choice, provided that the terms permit + modification of the work for the customer's own use and reverse + engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the + Library is used in it and that the Library and its use are covered + by this License. You must supply a copy of this License. If the + work during execution displays copyright notices, you must include + the copyright notice for the Library among them, as well as a + reference directing the user to the copy of this License. Also, + you must do one of these things: + + a. Accompany the work with the complete corresponding + machine-readable source code for the Library including + whatever changes were used in the work (which must be + distributed under Sections 1 and 2 above); and, if the work + is an executable linked with the Library, with the complete + machine-readable "work that uses the Library", as object code + and/or source code, so that the user can modify the Library + and then relink to produce a modified executable containing + the modified Library. (It is understood that the user who + changes the contents of definitions files in the Library will + not necessarily be able to recompile the application to use + the modified definitions.) + + b. Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run + time a copy of the library already present on the user's + computer system, rather than copying library functions into + the executable, and (2) will operate properly with a modified + version of the library, if the user installs one, as long as + the modified version is interface-compatible with the version + that the work was made with. + + c. Accompany the work with a written offer, valid for at least + three years, to give the same user the materials specified in + Subsection 6a, above, for a charge no more than the cost of + performing this distribution. + + d. If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the + above specified materials from the same place. + + e. Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the "work that uses the + Library" must include any data and utility programs needed for + reproducing the executable from it. However, as a special + exception, the materials to be distributed need not include + anything that is normally distributed (in either source or binary + form) with the major components (compiler, kernel, and so on) of + the operating system on which the executable runs, unless that + component itself accompanies the executable. + + It may happen that this requirement contradicts the license + restrictions of other proprietary libraries that do not normally + accompany the operating system. Such a contradiction means you + cannot use both them and the Library together in an executable + that you distribute. + + 7. You may place library facilities that are a work based on the + Library side-by-side in a single library together with other + library facilities not covered by this License, and distribute + such a combined library, provided that the separate distribution + of the work based on the Library and of the other library + facilities is otherwise permitted, and provided that you do these + two things: + + a. Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + b. Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same + work. + + 8. You may not copy, modify, sublicense, link with, or distribute the + Library except as expressly provided under this License. Any + attempt otherwise to copy, modify, sublicense, link with, or + distribute the Library is void, and will automatically terminate + your rights under this License. However, parties who have + received copies, or rights, from you under this License will not + have their licenses terminated so long as such parties remain in + full compliance. + + 9. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify + or distribute the Library or its derivative works. These actions + are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Library (or any work + based on the Library), you indicate your acceptance of this + License to do so, and all its terms and conditions for copying, + distributing or modifying the Library or works based on it. + + 10. Each time you redistribute the Library (or any work based on the + Library), the recipient automatically receives a license from the + original licensor to copy, distribute, link with or modify the + Library subject to these terms and conditions. You may not impose + any further restrictions on the recipients' exercise of the rights + granted herein. You are not responsible for enforcing compliance + by third parties with this License. + + 11. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent + issues), conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot distribute so as to satisfy simultaneously + your obligations under this License and any other pertinent + obligations, then as a consequence you may not distribute the + Library at all. For example, if a patent license would not permit + royalty-free redistribution of the Library by all those who + receive copies directly or indirectly through you, then the only + way you could satisfy both it and this License would be to refrain + entirely from distribution of the Library. + + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply, and the section as a whole is intended to apply + in other circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of + any such claims; this section has the sole purpose of protecting + the integrity of the free software distribution system which is + implemented by public license practices. Many people have made + generous contributions to the wide range of software distributed + through that system in reliance on consistent application of that + system; it is up to the author/donor to decide if he or she is + willing to distribute software through any other system and a + licensee cannot impose that choice. + + This section is intended to make thoroughly clear what is believed + to be a consequence of the rest of this License. + + 12. If the distribution and/or use of the Library is restricted in + certain countries either by patents or by copyrighted interfaces, + the original copyright holder who places the Library under this + License may add an explicit geographical distribution limitation + excluding those countries, so that distribution is permitted only + in or among countries not thus excluded. In such case, this + License incorporates the limitation as if written in the body of + this License. + + 13. The Free Software Foundation may publish revised and/or new + versions of the Lesser General Public License from time to time. + Such new versions will be similar in spirit to the present version, + but may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Library specifies a version number of this License which applies + to it and "any later version", you have the option of following + the terms and conditions either of that version or of any later + version published by the Free Software Foundation. If the Library + does not specify a license version number, you may choose any + version ever published by the Free Software Foundation. + + 14. If you wish to incorporate parts of the Library into other free + programs whose distribution conditions are incompatible with these, + write to the author to ask for permission. For software which is + copyrighted by the Free Software Foundation, write to the Free + Software Foundation; we sometimes make exceptions for this. Our + decision will be guided by the two goals of preserving the free + status of all derivatives of our free software and of promoting + the sharing and reuse of software generally. + + NO WARRANTY + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT + WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT + NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE + QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE + LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY + SERVICING, REPAIR OR CORRECTION. + + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY + MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF + DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU + OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY + OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS +How to Apply These Terms to Your New Libraries +============================================== + +If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of +the ordinary General Public License). + + To apply these terms, attach the following notices to the library. +It is safest to attach them to the start of each source file to most +effectively convey the exclusion of warranty; and each file should have +at least the "copyright" line and a pointer to where the full notice is +found. + + ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version. + + This library is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, + USA. + + Also add information on how to contact you by electronic and paper +mail. + + You should also get your employer (if you work as a programmer) or +your school, if any, to sign a "copyright disclaimer" for the library, +if necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the library + `Frob' (a library for tweaking knobs) written by James Random Hacker. + + SIGNATURE OF TY COON, 1 April 1990 + Ty Coon, President of Vice + + That's all there is to it! + + +File: gcrypt.info, Node: Copying, Next: Figures and Tables, Prev: Library Copying, Up: Top + +GNU General Public License +************************** + + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +Preamble +======== + +The licenses for most software are designed to take away your freedom +to share and change it. By contrast, the GNU General Public License is +intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it in +new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, +and (2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + 1. This License applies to any program or other work which contains a + notice placed by the copyright holder saying it may be distributed + under the terms of this General Public License. The "Program", + below, refers to any such program or work, and a "work based on + the Program" means either the Program or any derivative work under + copyright law: that is to say, a work containing the Program or a + portion of it, either verbatim or with modifications and/or + translated into another language. (Hereinafter, translation is + included without limitation in the term "modification".) Each + licensee is addressed as "you". + + Activities other than copying, distribution and modification are + not covered by this License; they are outside its scope. The act + of running the Program is not restricted, and the output from the + Program is covered only if its contents constitute a work based on + the Program (independent of having been made by running the + Program). Whether that is true depends on what the Program does. + + 2. You may copy and distribute verbatim copies of the Program's + source code as you receive it, in any medium, provided that you + conspicuously and appropriately publish on each copy an appropriate + copyright notice and disclaimer of warranty; keep intact all the + notices that refer to this License and to the absence of any + warranty; and give any other recipients of the Program a copy of + this License along with the Program. + + You may charge a fee for the physical act of transferring a copy, + and you may at your option offer warranty protection in exchange + for a fee. + + 3. You may modify your copy or copies of the Program or any portion + of it, thus forming a work based on the Program, and copy and + distribute such modifications or work under the terms of Section 1 + above, provided that you also meet all of these conditions: + + a. You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b. You must cause any work that you distribute or publish, that + in whole or in part contains or is derived from the Program + or any part thereof, to be licensed as a whole at no charge + to all third parties under the terms of this License. + + c. If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display + an announcement including an appropriate copyright notice and + a notice that there is no warranty (or else, saying that you + provide a warranty) and that users may redistribute the + program under these conditions, and telling the user how to + view a copy of this License. (Exception: if the Program + itself is interactive but does not normally print such an + announcement, your work based on the Program is not required + to print an announcement.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the + Program, and can be reasonably considered independent and separate + works in themselves, then this License, and its terms, do not + apply to those sections when you distribute them as separate + works. But when you distribute the same sections as part of a + whole which is a work based on the Program, the distribution of + the whole must be on the terms of this License, whose permissions + for other licensees extend to the entire whole, and thus to each + and every part regardless of who wrote it. + + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Program. + + In addition, mere aggregation of another work not based on the + Program with the Program (or with a work based on the Program) on + a volume of a storage or distribution medium does not bring the + other work under the scope of this License. + + 4. You may copy and distribute the Program (or a work based on it, + under Section 2) in object code or executable form under the terms + of Sections 1 and 2 above provided that you also do one of the + following: + + a. Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of + Sections 1 and 2 above on a medium customarily used for + software interchange; or, + + b. Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a + medium customarily used for software interchange; or, + + c. Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with + such an offer, in accord with Subsection b above.) + + The source code for a work means the preferred form of the work for + making modifications to it. For an executable work, complete + source code means all the source code for all modules it contains, + plus any associated interface definition files, plus the scripts + used to control compilation and installation of the executable. + However, as a special exception, the source code distributed need + not include anything that is normally distributed (in either + source or binary form) with the major components (compiler, + kernel, and so on) of the operating system on which the executable + runs, unless that component itself accompanies the executable. + + If distribution of executable or object code is made by offering + access to copy from a designated place, then offering equivalent + access to copy the source code from the same place counts as + distribution of the source code, even though third parties are not + compelled to copy the source along with the object code. + + 5. You may not copy, modify, sublicense, or distribute the Program + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense or distribute the Program is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 6. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify + or distribute the Program or its derivative works. These actions + are prohibited by law if you do not accept this License. + Therefore, by modifying or distributing the Program (or any work + based on the Program), you indicate your acceptance of this + License to do so, and all its terms and conditions for copying, + distributing or modifying the Program or works based on it. + + 7. Each time you redistribute the Program (or any work based on the + Program), the recipient automatically receives a license from the + original licensor to copy, distribute or modify the Program + subject to these terms and conditions. You may not impose any + further restrictions on the recipients' exercise of the rights + granted herein. You are not responsible for enforcing compliance + by third parties to this License. + + 8. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent + issues), conditions are imposed on you (whether by court order, + agreement or otherwise) that contradict the conditions of this + License, they do not excuse you from the conditions of this + License. If you cannot distribute so as to satisfy simultaneously + your obligations under this License and any other pertinent + obligations, then as a consequence you may not distribute the + Program at all. For example, if a patent license would not permit + royalty-free redistribution of the Program by all those who + receive copies directly or indirectly through you, then the only + way you could satisfy both it and this License would be to refrain + entirely from distribution of the Program. + + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply and the section as a whole is intended to apply + in other circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of + any such claims; this section has the sole purpose of protecting + the integrity of the free software distribution system, which is + implemented by public license practices. Many people have made + generous contributions to the wide range of software distributed + through that system in reliance on consistent application of that + system; it is up to the author/donor to decide if he or she is + willing to distribute software through any other system and a + licensee cannot impose that choice. + + This section is intended to make thoroughly clear what is believed + to be a consequence of the rest of this License. + + 9. If the distribution and/or use of the Program is restricted in + certain countries either by patents or by copyrighted interfaces, + the original copyright holder who places the Program under this + License may add an explicit geographical distribution limitation + excluding those countries, so that distribution is permitted only + in or among countries not thus excluded. In such case, this + License incorporates the limitation as if written in the body of + this License. + + 10. The Free Software Foundation may publish revised and/or new + versions of the General Public License from time to time. Such + new versions will be similar in spirit to the present version, but + may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Program specifies a version number of this License which applies + to it and "any later version", you have the option of following + the terms and conditions either of that version or of any later + version published by the Free Software Foundation. If the Program + does not specify a version number of this License, you may choose + any version ever published by the Free Software Foundation. + + 11. If you wish to incorporate parts of the Program into other free + programs whose distribution conditions are different, write to the + author to ask for permission. For software which is copyrighted + by the Free Software Foundation, write to the Free Software + Foundation; we sometimes make exceptions for this. Our decision + will be guided by the two goals of preserving the free status of + all derivatives of our free software and of promoting the sharing + and reuse of software generally. + + NO WARRANTY + 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE + LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT + WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT + NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE + QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE + PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY + SERVICING, REPAIR OR CORRECTION. + + 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY + MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE + LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, + INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR + INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF + DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU + OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY + OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS +How to Apply These Terms to Your New Programs +============================================= + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES. + Copyright (C) 19YY NAME OF AUTHOR + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either version 2 + of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + + Also add information on how to contact you by electronic and paper +mail. + + If the program is interactive, make it output a short notice like +this when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details + type `show w'. This is free software, and you are welcome + to redistribute it under certain conditions; type `show c' + for details. + + The hypothetical commands `show w' and `show c' should show the +appropriate parts of the General Public License. Of course, the +commands you use may be called something other than `show w' and `show +c'; they could even be mouse-clicks or menu items--whatever suits your +program. + + You should also get your employer (if you work as a programmer) or +your school, if any, to sign a "copyright disclaimer" for the program, +if necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright + interest in the program `Gnomovision' + (which makes passes at compilers) written + by James Hacker. + + SIGNATURE OF TY COON, 1 April 1989 + Ty Coon, President of Vice + + This General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Library General Public License instead of this License. + + +File: gcrypt.info, Node: Figures and Tables, Next: Concept Index, Prev: Copying, Up: Top + +List of Figures and Tables +************************** + +* Menu: + +* Figure 13.1: Libgcrypt subsystems: fig:subsystems. +* Figure B.1: FIPS mode state ...: fig:fips-fsm. + +* Menu: + +* Table B.1: FIPS mode states: tbl:fips-states. +* Table B.2: FIPS mode state ...: tbl:fips-state-transitions. + + +File: gcrypt.info, Node: Concept Index, Next: Function and Data Index, Prev: Figures and Tables, Up: Top + +Concept Index +************* + + +* Menu: + +* 3DES: Available ciphers. (line 16) +* Advanced Encryption Standard: Available ciphers. (line 37) +* AES: Available ciphers. (line 37) +* Arcfour: Available ciphers. (line 54) +* Blowfish: Available ciphers. (line 24) +* Camellia: Available ciphers. (line 81) +* CAST5: Available ciphers. (line 21) +* CBC, Cipher Block Chaining mode: Available cipher modes. + (line 20) +* CBC-MAC: Working with cipher handles. + (line 52) +* CFB, Cipher Feedback mode: Available cipher modes. + (line 16) +* cipher text stealing: Working with cipher handles. + (line 45) +* CRC32: Available hash algorithms. + (line 6) +* CTR, Counter mode: Available cipher modes. + (line 29) +* DES: Available ciphers. (line 59) +* DES-EDE: Available ciphers. (line 16) +* Digital Encryption Standard: Available ciphers. (line 16) +* ECB, Electronic Codebook mode: Available cipher modes. + (line 13) +* Enforced FIPS mode: Enabling FIPS mode. (line 30) +* error codes: Error Values. (line 6) +* error codes, list of <1>: Error Codes. (line 6) +* error codes, list of: Error Sources. (line 6) +* error codes, printing of: Error Strings. (line 6) +* error sources: Error Values. (line 6) +* error sources, printing of: Error Strings. (line 6) +* error strings: Error Strings. (line 6) +* error values: Error Values. (line 6) +* error values, printing of: Error Strings. (line 6) +* FIPS 140: Enabling FIPS mode. (line 6) +* FIPS 186 <1>: Public-Key Subsystem Architecture. + (line 63) +* FIPS 186: General public-key related Functions. + (line 256) +* FIPS mode: Enabling FIPS mode. (line 6) +* GPL, GNU General Public License: Copying. (line 6) +* HAVAL: Available hash algorithms. + (line 6) +* HMAC: Working with hash algorithms. + (line 27) +* IDEA: Available ciphers. (line 11) +* LGPL, GNU Lesser General Public License: Library Copying. (line 6) +* MD2, MD4, MD5: Available hash algorithms. + (line 6) +* OFB, Output Feedback mode: Available cipher modes. + (line 26) +* RC2: Available ciphers. (line 71) +* RC4: Available ciphers. (line 54) +* rfc-2268: Available ciphers. (line 71) +* Rijndael: Available ciphers. (line 37) +* RIPE-MD-160: Available hash algorithms. + (line 6) +* Seed (cipher): Available ciphers. (line 76) +* Serpent: Available ciphers. (line 67) +* SHA-1: Available hash algorithms. + (line 6) +* SHA-224, SHA-256, SHA-384, SHA-512: Available hash algorithms. + (line 6) +* sync mode (OpenPGP): Working with cipher handles. + (line 40) +* TIGER: Available hash algorithms. + (line 6) +* Triple-DES: Available ciphers. (line 16) +* Twofish: Available ciphers. (line 48) +* Whirlpool: Available hash algorithms. + (line 6) +* X9.31 <1>: Public-Key Subsystem Architecture. + (line 63) +* X9.31: General public-key related Functions. + (line 249) + + +File: gcrypt.info, Node: Function and Data Index, Prev: Concept Index, Up: Top + +Function and Data Index +*********************** + + +* Menu: + +* AM_PATH_LIBGCRYPT: Building sources using Automake. + (line 13) +* gcry_ac_close: Working with handles. + (line 21) +* gcry_ac_data_clear: Working with sets of data. + (line 75) +* gcry_ac_data_copy: Working with sets of data. + (line 53) +* gcry_ac_data_decode: Using cryptographic functions. + (line 100) +* gcry_ac_data_decrypt: Using cryptographic functions. + (line 40) +* gcry_ac_data_decrypt_scheme: Using cryptographic functions. + (line 137) +* gcry_ac_data_destroy: Working with sets of data. + (line 41) +* gcry_ac_data_encode: Using cryptographic functions. + (line 93) +* gcry_ac_data_encrypt: Using cryptographic functions. + (line 33) +* gcry_ac_data_encrypt_scheme: Using cryptographic functions. + (line 127) +* gcry_ac_data_from_sexp: Working with sets of data. + (line 93) +* gcry_ac_data_get_index: Working with sets of data. + (line 69) +* gcry_ac_data_get_name: Working with sets of data. + (line 61) +* gcry_ac_data_length: Working with sets of data. + (line 57) +* gcry_ac_data_new: Working with sets of data. + (line 38) +* gcry_ac_data_set: Working with sets of data. + (line 45) +* gcry_ac_data_sign: Using cryptographic functions. + (line 48) +* gcry_ac_data_sign_scheme: Using cryptographic functions. + (line 147) +* gcry_ac_data_t: Working with sets of data. + (line 20) +* gcry_ac_data_to_sexp: Working with sets of data. + (line 79) +* gcry_ac_data_verify: Using cryptographic functions. + (line 54) +* gcry_ac_data_verify_scheme: Using cryptographic functions. + (line 157) +* gcry_ac_id_t: Available asymmetric algorithms. + (line 11) +* gcry_ac_id_to_name: Handle-independent functions. + (line 10) +* gcry_ac_io_init: Working with IO objects. + (line 22) +* gcry_ac_io_init_va: Working with IO objects. + (line 28) +* gcry_ac_io_t: Working with IO objects. + (line 10) +* gcry_ac_key_data_get: Working with keys. (line 93) +* gcry_ac_key_destroy: Working with keys. (line 86) +* gcry_ac_key_get_grip: Working with keys. (line 105) +* gcry_ac_key_get_nbits: Working with keys. (line 101) +* gcry_ac_key_init: Working with keys. (line 30) +* gcry_ac_key_pair_destroy: Working with keys. (line 90) +* gcry_ac_key_pair_extract: Working with keys. (line 83) +* gcry_ac_key_pair_generate: Working with keys. (line 36) +* gcry_ac_key_pair_t: Working with keys. (line 20) +* gcry_ac_key_t: Working with keys. (line 16) +* gcry_ac_key_test: Working with keys. (line 97) +* gcry_ac_key_type_t: Working with keys. (line 7) +* gcry_ac_name_to_id: Handle-independent functions. + (line 15) +* gcry_ac_open: Working with handles. + (line 11) +* gcry_calloc: Memory allocation. (line 15) +* gcry_calloc_secure: Memory allocation. (line 21) +* gcry_check_version: Initializing the library. + (line 17) +* gcry_cipher_algo_info: General cipher functions. + (line 12) +* gcry_cipher_algo_name: General cipher functions. + (line 39) +* gcry_cipher_close: Working with cipher handles. + (line 59) +* gcry_cipher_ctl: Working with cipher handles. + (line 159) +* gcry_cipher_decrypt: Working with cipher handles. + (line 129) +* gcry_cipher_decrypt_t: Cipher modules. (line 80) +* gcry_cipher_encrypt: Working with cipher handles. + (line 110) +* gcry_cipher_encrypt_t: Cipher modules. (line 75) +* gcry_cipher_info: Working with cipher handles. + (line 168) +* gcry_cipher_list: Cipher modules. (line 106) +* gcry_cipher_map_name: General cipher functions. + (line 45) +* gcry_cipher_mode_from_oid: General cipher functions. + (line 50) +* gcry_cipher_oid_spec_t: Cipher modules. (line 60) +* gcry_cipher_open: Working with cipher handles. + (line 11) +* gcry_cipher_register: Cipher modules. (line 96) +* gcry_cipher_reset: Working with cipher handles. + (line 97) +* gcry_cipher_setctr: Working with cipher handles. + (line 90) +* gcry_cipher_setiv: Working with cipher handles. + (line 83) +* gcry_cipher_setkey: Working with cipher handles. + (line 68) +* gcry_cipher_setkey_t: Cipher modules. (line 70) +* gcry_cipher_spec_t: Cipher modules. (line 12) +* gcry_cipher_stdecrypt_t: Cipher modules. (line 90) +* gcry_cipher_stencrypt_t: Cipher modules. (line 85) +* gcry_cipher_sync: Working with cipher handles. + (line 149) +* gcry_cipher_unregister: Cipher modules. (line 101) +* gcry_control: Controlling the library. + (line 7) +* gcry_create_nonce: Retrieving random numbers. + (line 26) +* gcry_err_code: Error Values. (line 43) +* gcry_err_code_from_errno: Error Values. (line 95) +* gcry_err_code_t: Error Values. (line 7) +* gcry_err_code_to_errno: Error Values. (line 100) +* gcry_err_make: Error Values. (line 57) +* gcry_err_make_from_errno: Error Values. (line 81) +* gcry_err_source: Error Values. (line 49) +* gcry_err_source_t: Error Values. (line 14) +* gcry_error: Error Values. (line 64) +* gcry_error_from_errno: Error Values. (line 86) +* gcry_error_t: Error Values. (line 25) +* gcry_fips_mode_active: Controlling the library. + (line 221) +* gcry_free: Memory allocation. (line 31) +* gcry_handler_alloc_t: Allocation handler. (line 12) +* gcry_handler_error_t: Error handler. (line 27) +* gcry_handler_free_t: Allocation handler. (line 24) +* gcry_handler_log_t: Logging handler. (line 7) +* gcry_handler_no_mem_t: Error handler. (line 11) +* gcry_handler_progress_t: Progress handler. (line 10) +* gcry_handler_realloc_t: Allocation handler. (line 20) +* gcry_handler_secure_check_t: Allocation handler. (line 16) +* gcry_malloc: Memory allocation. (line 7) +* gcry_malloc_secure: Memory allocation. (line 12) +* gcry_md_algo_name: Working with hash algorithms. + (line 154) +* gcry_md_close: Working with hash algorithms. + (line 61) +* gcry_md_copy: Working with hash algorithms. + (line 84) +* gcry_md_debug: Working with hash algorithms. + (line 218) +* gcry_md_enable: Working with hash algorithms. + (line 44) +* gcry_md_final: Working with hash algorithms. + (line 112) +* gcry_md_final_t: Hash algorithm modules. + (line 73) +* gcry_md_get_algo: Working with hash algorithms. + (line 198) +* gcry_md_get_algo_dlen: Working with hash algorithms. + (line 189) +* gcry_md_get_asnoid: Working with hash algorithms. + (line 170) +* gcry_md_hash_buffer: Working with hash algorithms. + (line 137) +* gcry_md_init_t: Hash algorithm modules. + (line 65) +* gcry_md_is_enabled: Working with hash algorithms. + (line 209) +* gcry_md_is_secure: Working with hash algorithms. + (line 204) +* gcry_md_list: Hash algorithm modules. + (line 91) +* gcry_md_map_name: Working with hash algorithms. + (line 160) +* gcry_md_oid_spec_t: Hash algorithm modules. + (line 57) +* gcry_md_open: Working with hash algorithms. + (line 11) +* gcry_md_putc: Working with hash algorithms. + (line 102) +* gcry_md_read: Working with hash algorithms. + (line 122) +* gcry_md_read_t: Hash algorithm modules. + (line 77) +* gcry_md_register: Hash algorithm modules. + (line 82) +* gcry_md_reset: Working with hash algorithms. + (line 72) +* gcry_md_setkey: Working with hash algorithms. + (line 53) +* gcry_md_spec_t: Hash algorithm modules. + (line 12) +* gcry_md_start_debug: Working with hash algorithms. + (line 232) +* gcry_md_stop_debug: Working with hash algorithms. + (line 240) +* gcry_md_test_algo: Working with hash algorithms. + (line 183) +* gcry_md_unregister: Hash algorithm modules. + (line 87) +* gcry_md_write: Working with hash algorithms. + (line 97) +* gcry_md_write_t: Hash algorithm modules. + (line 69) +* gcry_module_t: Modules. (line 10) +* gcry_mpi_add: Calculations. (line 10) +* gcry_mpi_add_ui: Calculations. (line 14) +* gcry_mpi_addm: Calculations. (line 18) +* gcry_mpi_aprint: MPI formats. (line 54) +* gcry_mpi_clear_bit: Bit manipulations. (line 19) +* gcry_mpi_clear_flag: Miscellaneous. (line 32) +* gcry_mpi_clear_highbit: Bit manipulations. (line 25) +* gcry_mpi_cmp: Comparisons. (line 9) +* gcry_mpi_cmp_ui: Comparisons. (line 13) +* gcry_mpi_copy: Basic functions. (line 23) +* gcry_mpi_div: Calculations. (line 50) +* gcry_mpi_dump: MPI formats. (line 61) +* gcry_mpi_gcd: Calculations. (line 63) +* gcry_mpi_get_flag: Miscellaneous. (line 37) +* gcry_mpi_get_nbits: Bit manipulations. (line 10) +* gcry_mpi_get_opaque: Miscellaneous. (line 20) +* gcry_mpi_invm: Calculations. (line 68) +* gcry_mpi_lshift: Bit manipulations. (line 34) +* gcry_mpi_mod: Calculations. (line 55) +* gcry_mpi_mul: Calculations. (line 34) +* gcry_mpi_mul_2exp: Calculations. (line 46) +* gcry_mpi_mul_ui: Calculations. (line 38) +* gcry_mpi_mulm: Calculations. (line 42) +* gcry_mpi_new: Basic functions. (line 10) +* gcry_mpi_powm: Calculations. (line 59) +* gcry_mpi_print: MPI formats. (line 45) +* gcry_mpi_randomize: Miscellaneous. (line 41) +* gcry_mpi_release: Basic functions. (line 26) +* gcry_mpi_rshift: Bit manipulations. (line 29) +* gcry_mpi_scan: MPI formats. (line 12) +* gcry_mpi_set: Basic functions. (line 33) +* gcry_mpi_set_bit: Bit manipulations. (line 16) +* gcry_mpi_set_flag: Miscellaneous. (line 26) +* gcry_mpi_set_highbit: Bit manipulations. (line 22) +* gcry_mpi_set_opaque: Miscellaneous. (line 8) +* gcry_mpi_set_ui: Basic functions. (line 37) +* gcry_mpi_snew: Basic functions. (line 17) +* gcry_mpi_sub: Calculations. (line 22) +* gcry_mpi_sub_ui: Calculations. (line 26) +* gcry_mpi_subm: Calculations. (line 30) +* gcry_mpi_swap: Basic functions. (line 44) +* gcry_mpi_t: Data types. (line 7) +* gcry_mpi_test_bit: Bit manipulations. (line 13) +* gcry_pk_algo_info: General public-key related Functions. + (line 47) +* gcry_pk_algo_name: General public-key related Functions. + (line 10) +* gcry_pk_check_secret_key_t: Public key modules. (line 91) +* gcry_pk_ctl: General public-key related Functions. + (line 100) +* gcry_pk_decrypt: Cryptographic Functions. + (line 85) +* gcry_pk_decrypt_t: Public key modules. (line 101) +* gcry_pk_encrypt: Cryptographic Functions. + (line 29) +* gcry_pk_encrypt_t: Public key modules. (line 96) +* gcry_pk_generate_t: Public key modules. (line 86) +* gcry_pk_genkey: General public-key related Functions. + (line 115) +* gcry_pk_get_keygrip: General public-key related Functions. + (line 29) +* gcry_pk_get_nbits: General public-key related Functions. + (line 24) +* gcry_pk_get_nbits_t: Public key modules. (line 116) +* gcry_pk_list: Public key modules. (line 131) +* gcry_pk_map_name: General public-key related Functions. + (line 16) +* gcry_pk_register: Public key modules. (line 121) +* gcry_pk_sign: Cryptographic Functions. + (line 117) +* gcry_pk_sign_t: Public key modules. (line 106) +* gcry_pk_spec_t: Public key modules. (line 12) +* gcry_pk_test_algo: General public-key related Functions. + (line 20) +* gcry_pk_testkey: General public-key related Functions. + (line 40) +* gcry_pk_unregister: Public key modules. (line 127) +* gcry_pk_verify: Cryptographic Functions. + (line 170) +* gcry_pk_verify_t: Public key modules. (line 111) +* gcry_prime_check: Checking. (line 8) +* gcry_prime_generate: Generation. (line 10) +* gcry_prime_group_generator: Generation. (line 19) +* gcry_prime_release_factors: Generation. (line 25) +* gcry_random_bytes: Retrieving random numbers. + (line 13) +* gcry_random_bytes_secure: Retrieving random numbers. + (line 19) +* gcry_random_level_t: Quality of random numbers. + (line 9) +* gcry_randomize: Retrieving random numbers. + (line 8) +* gcry_realloc: Memory allocation. (line 24) +* gcry_set_allocation_handler: Allocation handler. (line 34) +* gcry_set_fatalerror_handler: Error handler. (line 32) +* gcry_set_log_handler: Logging handler. (line 12) +* gcry_set_outofcore_handler: Error handler. (line 16) +* gcry_set_progress_handler: Progress handler. (line 21) +* gcry_sexp_build: Working with S-expressions. + (line 43) +* gcry_sexp_canon_len: Working with S-expressions. + (line 126) +* gcry_sexp_car: Working with S-expressions. + (line 155) +* gcry_sexp_cdr: Working with S-expressions. + (line 160) +* gcry_sexp_create: Working with S-expressions. + (line 26) +* gcry_sexp_dump: Working with S-expressions. + (line 117) +* gcry_sexp_find_token: Working with S-expressions. + (line 138) +* gcry_sexp_length: Working with S-expressions. + (line 145) +* gcry_sexp_new: Working with S-expressions. + (line 13) +* gcry_sexp_nth: Working with S-expressions. + (line 150) +* gcry_sexp_nth_data: Working with S-expressions. + (line 168) +* gcry_sexp_nth_mpi: Working with S-expressions. + (line 193) +* gcry_sexp_nth_string: Working with S-expressions. + (line 185) +* gcry_sexp_release: Working with S-expressions. + (line 83) +* gcry_sexp_sprint: Working with S-expressions. + (line 94) +* gcry_sexp_sscan: Working with S-expressions. + (line 37) +* gcry_sexp_t: Data types for S-expressions. + (line 7) +* gcry_strerror: Error Strings. (line 7) +* gcry_strsource: Error Strings. (line 13) + + + +Tag Table: +Node: Top775 +Node: Introduction2994 +Node: Getting Started3366 +Node: Features4247 +Node: Overview5031 +Node: Preparation5662 +Node: Header6519 +Node: Building sources7589 +Node: Building sources using Automake9503 +Node: Initializing the library10685 +Ref: sample-use-suspend-secmem13860 +Ref: sample-use-resume-secmem14480 +Node: Multi-Threading15376 +Ref: Multi-Threading-Footnote-119389 +Node: Enabling FIPS mode19797 +Node: Generalities21663 +Node: Controlling the library21988 +Node: Modules34155 +Node: Error Handling34934 +Node: Error Values37457 +Node: Error Sources42397 +Node: Error Codes44668 +Node: Error Strings48153 +Node: Handler Functions49336 +Node: Progress handler49895 +Node: Allocation handler51891 +Node: Error handler53442 +Node: Logging handler55009 +Node: Symmetric cryptography55601 +Node: Available ciphers56406 +Node: Cipher modules58913 +Node: Available cipher modes63437 +Node: Working with cipher handles64316 +Node: General cipher functions72631 +Node: Public Key cryptography75149 +Node: Available algorithms76064 +Node: Used S-expressions76413 +Node: RSA key parameters77525 +Node: DSA key parameters78800 +Node: ECC key parameters79458 +Node: Public key modules81223 +Node: Cryptographic Functions86807 +Node: General public-key related Functions94287 +Node: AC Interface106576 +Node: Available asymmetric algorithms107711 +Node: Working with sets of data108380 +Node: Working with IO objects112882 +Node: Working with handles115602 +Node: Working with keys116549 +Node: Using cryptographic functions120631 +Node: Handle-independent functions127538 +Node: Hashing128286 +Node: Available hash algorithms129077 +Node: Hash algorithm modules132184 +Node: Working with hash algorithms136032 +Node: Random Numbers147334 +Node: Quality of random numbers147608 +Node: Retrieving random numbers148292 +Node: S-expressions149776 +Node: Data types for S-expressions150418 +Node: Working with S-expressions150742 +Node: MPI library160113 +Node: Data types161071 +Node: Basic functions161265 +Node: MPI formats163333 +Node: Calculations166216 +Node: Comparisons168470 +Node: Bit manipulations169114 +Node: Miscellaneous170429 +Node: Prime numbers172398 +Node: Generation172668 +Node: Checking173952 +Node: Utilities174365 +Node: Memory allocation174558 +Node: Architecture175885 +Ref: fig:subsystems177405 +Ref: Architecture-Footnote-1178490 +Ref: Architecture-Footnote-2178552 +Node: Public-Key Subsystem Architecture178636 +Node: Symmetric Encryption Subsystem Architecture181577 +Node: Hashing and MACing Subsystem Architecture183024 +Node: Multi-Precision-Integer Subsystem Architecture184948 +Node: Prime-Number-Generator Subsystem Architecture186389 +Ref: Prime-Number-Generator Subsystem Architecture-Footnote-1188320 +Node: Random-Number Subsystem Architecture188607 +Node: CSPRNG Description191096 +Ref: CSPRNG Description-Footnote-1192658 +Node: FIPS PRNG Description192781 +Node: Self-Tests194916 +Node: FIPS Mode206607 +Ref: fig:fips-fsm210587 +Ref: tbl:fips-states210689 +Ref: tbl:fips-state-transitions211942 +Node: Library Copying215556 +Node: Copying243674 +Node: Figures and Tables262848 +Node: Concept Index263258 +Node: Function and Data Index268823 + +End Tag Table |