diff options
Diffstat (limited to 'plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi')
| -rw-r--r-- | plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi | 5867 |
1 files changed, 5867 insertions, 0 deletions
diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi b/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi new file mode 100644 index 0000000000..a2993df97e --- /dev/null +++ b/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi @@ -0,0 +1,5867 @@ +\input texinfo @c -*- Texinfo -*- +@c %**start of header +@setfilename gcrypt.info +@include version.texi +@settitle The Libgcrypt Reference Manual +@c Unify some of the indices. +@syncodeindex tp fn +@syncodeindex pg fn +@c %**end of header +@copying +This manual is for Libgcrypt +(version @value{VERSION}, @value{UPDATED}), +which is GNU's library of cryptographic building blocks. + +Copyright @copyright{} 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 2 of the License, or (at your +option) any later version. The text of the license can be found in the +section entitled ``GNU General Public License''. +@end quotation +@end copying + +@dircategory GNU Libraries +@direntry +* libgcrypt: (gcrypt). Cryptographic function library. +@end direntry + + + +@c +@c Titlepage +@c +@setchapternewpage odd +@titlepage +@title The Libgcrypt Reference Manual +@subtitle Version @value{VERSION} +@subtitle @value{UPDATED} +@author Werner Koch (@email{wk@@gnupg.org}) +@author Moritz Schulte (@email{mo@@g10code.com}) + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@ifnothtml +@summarycontents +@contents +@page +@end ifnothtml + + +@ifnottex +@node Top +@top The Libgcrypt Library +@insertcopying +@end ifnottex + + +@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. + +@end menu + +@ifhtml +@page +@summarycontents +@contents +@end ifhtml + + +@c ********************************************************** +@c ******************* Introduction *********************** +@c ********************************************************** +@node Introduction +@chapter 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. +@end menu + +@node Getting Started +@section Getting Started + +This manual documents the Libgcrypt library application programming +interface (API). All functions and data types provided by the library +are explained. + +@noindent +The reader is assumed to possess basic knowledge about applied +cryptography. + +This manual can be used in several ways. If read from the beginning +to the end, it gives a good introduction into the library and how it +can be used in an application. Forward references are included where +necessary. Later on, the manual can be used as a reference manual to +get just the information needed about any particular interface of the +library. Experienced programmers might want to start looking at the +examples at the end of the manual, and then only read up those parts +of the interface which are unclear. + + +@node Features +@section Features + +Libgcrypt might have a couple of advantages over other libraries doing +a similar job. + +@table @asis +@item It's Free Software +Anybody can use, modify, and redistribute it under the terms of the GNU +Lesser General Public License (@pxref{Library Copying}). Note, that +some parts (which are in general not needed by applications) are subject +to the terms of the GNU General Public License (@pxref{Copying}); please +see the README file of the distribution for of list of these parts. + +@item It encapsulates the low level cryptography +Libgcrypt provides a high level interface to cryptographic +building blocks using an extensible and flexible API. + +@end table + +@node Overview +@section Overview + +@noindent +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. + +@c ********************************************************** +@c ******************* Preparation ************************ +@c ********************************************************** +@node Preparation +@chapter 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. +@end menu + + +@node Header +@section Header + +All interfaces (data types and functions) of the library are defined +in the header file @file{gcrypt.h}. You must include this in all source +files using the library, either directly or through some other header +file, like this: + +@example +#include <gcrypt.h> +@end example + +The name space of Libgcrypt is @code{gcry_*} for function +and type names and @code{GCRY*} for other symbols. In addition the +same name prefixes with one prepended underscore are reserved for +internal use and should never be used by an application. Note that +Libgcrypt uses libgpg-error, which uses @code{gpg_*} as +name space for function and type names and @code{GPG_*} for other +symbols, including all the error codes. + +@noindent +Certain parts of gcrypt.h may be excluded by defining these macros: + +@table @code +@item GCRYPT_NO_MPI_MACROS +Do not define the shorthand macros @code{mpi_*} for @code{gcry_mpi_*}. + +@item GCRYPT_NO_DEPRECATED +Do not include defintions for deprecated features. This is useful to +make sure that no deprecated features are used. +@end table + +@node Building sources +@section Building sources + +If you want to compile a source file including the `gcrypt.h' header +file, you must make sure that the compiler can find it in the +directory hierarchy. This is accomplished by adding the path to the +directory in which the header file is located to the compilers include +file search path (via the @option{-I} option). + +However, the path to the include file is determined at the time the +source is configured. To solve this problem, Libgcrypt ships with a small +helper program @command{libgcrypt-config} that knows the path to the +include file and other configuration options. The options that need +to be added to the compiler invocation at compile time are output by +the @option{--cflags} option to @command{libgcrypt-config}. The following +example shows how it can be used at the command line: + +@example +gcc -c foo.c `libgcrypt-config --cflags` +@end example + +Adding the output of @samp{libgcrypt-config --cflags} to the compilers +command line will ensure that the compiler can find the Libgcrypt header +file. + +A similar problem occurs when linking the program with the library. +Again, the compiler has to find the library files. For this to work, +the path to the library files has to be added to the library search path +(via the @option{-L} option). For this, the option @option{--libs} to +@command{libgcrypt-config} can be used. For convenience, this option +also outputs all other options that are required to link the program +with the Libgcrypt libraries (in particular, the @samp{-lgcrypt} +option). The example shows how to link @file{foo.o} with the Libgcrypt +library to a program @command{foo}. + +@example +gcc -o foo foo.o `libgcrypt-config --libs` +@end example + +Of course you can also combine both examples to a single command by +specifying both options to @command{libgcrypt-config}: + +@example +gcc -o foo foo.c `libgcrypt-config --cflags --libs` +@end example + +@node Building sources using Automake +@section Building sources using Automake + +It is much easier if you use GNU Automake instead of writing your own +Makefiles. If you do that, you do not have to worry about finding and +invoking the @command{libgcrypt-config} script at all. +Libgcrypt provides an extension to Automake that does all +the work for you. + +@c A simple macro for optional variables. +@macro ovar{varname} +@r{[}@var{\varname\}@r{]} +@end macro +@defmac AM_PATH_LIBGCRYPT (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) +Check whether Libgcrypt (at least version +@var{minimum-version}, if given) exists on the host system. If it is +found, execute @var{action-if-found}, otherwise do +@var{action-if-not-found}, if given. + +Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the +flags needed for compilation of the program to find the +@file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker +flags needed to link the program to the Libgcrypt library. +@end defmac + +You can use the defined Autoconf variables like this in your +@file{Makefile.am}: + +@example +AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS) +LDADD = $(LIBGCRYPT_LIBS) +@end example + +@node Initializing the library +@section Initializing the library + +Before the library can be used, it must initialize itself. This is +achieved by invoking the function @code{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. + +@deftypefun {const char *} gcry_check_version (const char *@var{req_version}) + +The function @code{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 @code{GCRYCTL_SET_THREAD_CBS} command +(called via the @code{gcry_control} function). +@xref{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 @var{req_version}, if this value is not a null +pointer. +@end deftypefun + +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: + +@example + /* 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); +@end example + + +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: + +@example + /* 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); + @} + +@anchor{sample-use-suspend-secmem} + /* 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); + +@anchor{sample-use-resume-secmem} + /* 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); +@end example + +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: + +@example + if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P)) + @{ + fputs ("libgcrypt has not been initialized\n", stderr); + abort (); + @} +@end example + +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. + + + +@node Multi-Threading +@section Multi-Threading + +As mentioned earlier, the Libgcrypt library is +thread-safe if you adhere to the following requirements: + +@itemize @bullet +@item +If your application is multi-threaded, you must set the thread support +callbacks with the @code{GCRYCTL_SET_THREAD_CBS} command +@strong{before} any other function in the library. + +This is easy enough if you are indeed writing an application using +Libgcrypt. It is rather problematic if you are writing a library +instead. Here are some tips what to do if you are writing a library: + +If your library requires a certain thread package, just initialize +Libgcrypt to use this thread package. If your library supports multiple +thread packages, but needs to be configured, you will have to +implement a way to determine which thread package the application +wants to use with your library anyway. Then configure Libgcrypt to use +this thread package. + +If your library is fully reentrant without any special support by a +thread package, then you are lucky indeed. Unfortunately, this does +not relieve you from doing either of the two above, or use a third +option. The third option is to let the application initialize Libgcrypt +for you. Then you are not using Libgcrypt transparently, though. + +As if this was not difficult enough, a conflict may arise if two +libraries try to initialize Libgcrypt independently of each others, and +both such libraries are then linked into the same application. To +make it a bit simpler for you, this will probably work, but only if +both libraries have the same requirement for the thread package. This +is currently only supported for the non-threaded case, GNU Pth and +pthread. Support for more thread packages is easy to add, so contact +us if you require it. + +@item +The function @code{gcry_check_version} must be called before any other +function in the library, except the @code{GCRYCTL_SET_THREAD_CBS} +command (called via the @code{gcry_control} function), because it +initializes the thread support subsystem in 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 +@code{gcry_check_version} before creating the other threads using +Libgcrypt@footnote{At least this is true for POSIX threads, +as @code{pthread_create} is a function that synchronizes memory with +respects to other threads. There are many functions which have this +property, a complete list can be found in POSIX, IEEE Std 1003.1-2003, +Base Definitions, Issue 6, in the definition of the term ``Memory +Synchronization''. For other thread packages, more relaxed or more +strict rules may apply.}. + +@item +Just like the function @code{gpg_strerror}, the function +@code{gcry_strerror} is not thread safe. You have to use +@code{gpg_strerror_r} instead. + +@end itemize + + +Libgcrypt contains convenient macros, which define the +necessary thread callbacks for PThread and for GNU Pth: + +@table @code +@item GCRY_THREAD_OPTION_PTH_IMPL + +This macro defines the following (static) symbols: +@code{gcry_pth_init}, @code{gcry_pth_mutex_init}, +@code{gcry_pth_mutex_destroy}, @code{gcry_pth_mutex_lock}, +@code{gcry_pth_mutex_unlock}, @code{gcry_pth_read}, +@code{gcry_pth_write}, @code{gcry_pth_select}, +@code{gcry_pth_waitpid}, @code{gcry_pth_accept}, +@code{gcry_pth_connect}, @code{gcry_threads_pth}. + +After including this macro, @code{gcry_control()} shall be used with a +command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the +thread callback structure named ``gcry_threads_pth''. + +@item GCRY_THREAD_OPTION_PTHREAD_IMPL + +This macro defines the following (static) symbols: +@code{gcry_pthread_mutex_init}, @code{gcry_pthread_mutex_destroy}, +@code{gcry_pthread_mutex_lock}, @code{gcry_pthread_mutex_unlock}, +@code{gcry_threads_pthread}. + +After including this macro, @code{gcry_control()} shall be used with a +command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the +thread callback structure named ``gcry_threads_pthread''. +@end table + +Note that these macros need to be terminated with a semicolon. Keep +in mind that these are convenient macros for C programmers; C++ +programmers might have to wrap these macros in an ``extern C'' body. + + +@node Enabling FIPS mode +@section How to enable the FIPS mode +@cindex FIPS mode +@cindex FIPS 140 + +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 @url{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: + +@itemize +@item +If the file @file{/proc/sys/crypto/fips_enabled} exists and contains a +numeric value other than @code{0}, Libgcrypt is put into FIPS mode at +initialization time. Obviously this works only on systems with a +@code{proc} file system (i.e. GNU/Linux). + +@item +If the file @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. + +@item +If the application requests FIPS mode using the control command +@code{GCRYCTL_FORCE_FIPS_MODE}. This must be done prior to any +initialization (i.e. before @code{gcry_check_version}). + +@end itemize + +@cindex Enforced FIPS mode + +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 +@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 (@pxref{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. + + + +@c ********************************************************** +@c ******************* General **************************** +@c ********************************************************** +@node Generalities +@chapter Generalities + +@menu +* Controlling the library:: Controlling Libgcrypt's behavior. +* Modules:: Description of extension modules. +* Error Handling:: Error codes and such. +@end menu + +@node Controlling the library +@section Controlling the library + +@deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...) + +This function can be used to influence the general behavior of +Libgcrypt in several ways. Depending on @var{cmd}, more +arguments can or have to be provided. + +@table @code +@item 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. + +@item GCRYCTL_ENABLE_QUICK_RANDOM; Arguments: none +This command inhibits the use the very secure random quality level +(@code{GCRY_VERY_STRONG_RANDOM}) and degrades all request down to +@code{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. + + +@item GCRYCTL_DUMP_RANDOM_STATS; Arguments: none +This command dumps randum number generator related statistics to the +library's logging stream. + +@item GCRYCTL_DUMP_MEMORY_STATS; Arguments: none +This command dumps memory managment related statistics to the library's +logging stream. + +@item GCRYCTL_DUMP_SECMEM_STATS; Arguments: none +This command dumps secure memory manamgent related statistics to the +library's logging stream. + +@item 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 @code{GCRYCTL_DISABLE_SECMEM} right +after initialization. + +@item 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 +@code{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 +@code{gcry_check_version}. + +@item 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 +@var{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. + +@item 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. + +@item GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none +Disable warning messages about problems with the secure memory +subsystem. This command should be run right after +@code{gcry_check_version}. + +@item GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none +Postpone warning messages from the secure memory subsystem. +@xref{sample-use-suspend-secmem,,the initialization example}, on how to +use it. + +@item GCRYCTL_RESUME_SECMEM_WARN; Arguments: none +Resume warning messages from the secure memory subsystem. +@xref{sample-use-resume-secmem,,the initialization example}, on how to +use it. + +@item 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 @code{gcry_check_version} and not +later than the command GCRYCTL_INIT_SECMEM. Note that in FIPS mode the +secure memory is always used. + +@item 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. + + +@item 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 @code{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. + +@item 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 @code{gcry_check_version}. + +@item 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 +@code{gcry_check_version}. + +@item 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 @code{gcry_check_version}. + +@item GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none +This command does nothing. It exists only for backward compatibility. + +@item 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. + +@item GCRYCTL_INITIALIZATION_FINISHED; Arguments: none +This command tells the libray that the application has finished the +intialization. + +@item GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none +This command returns true if the command@* +GCRYCTL_INITIALIZATION_FINISHED has already been run. + +@item GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops +This command registers a thread-callback structure. +@xref{Multi-Threading}. + +@item GCRYCTL_FAST_POLL; Arguments: none +Run a fast random poll. + +@item 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. + +@item 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 @var{stream}, the log +system is used. This command may be used before the intialization has +been finished but not before a gcry_version_check. + +@item 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. + +@item 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. + +@deftypefun int gcry_fips_mode_active (void) + +Returns true if the FIPS mode is active. Note that this is +implemented as a macro. +@end deftypefun + + + +@item 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. + +@item 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. + + +@end table + +@end deftypefun + +@node Modules +@section Modules + +Libgcrypt supports the use of `extension modules', which +implement algorithms in addition to those already built into the library +directly. + +@deftp {Data type} gcry_module_t +This data type represents a `module'. +@end deftp + +Functions registering modules provided by the user take a `module +specification structure' as input and return a value of +@code{gcry_module_t} and an ID that is unique in the modules' +category. This ID can be used to reference the newly registered +module. After registering a module successfully, the new functionality +should be able to be used through the normal functions provided by +Libgcrypt until it is unregistered again. + +@c ********************************************************** +@c ******************* Errors **************************** +@c ********************************************************** +@node Error Handling +@section 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 @code{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 +@code{libgpg-error}. They usually start with @code{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. +@end menu + + +@node Error Values +@subsection Error Values +@cindex error values +@cindex error codes +@cindex error sources + +@deftp {Data type} {gcry_err_code_t} +The @code{gcry_err_code_t} type is an alias for the +@code{libgpg-error} type @code{gpg_err_code_t}. The error code +indicates the type of an error, or the reason why an operation failed. + +A list of important error codes can be found in the next section. +@end deftp + +@deftp {Data type} {gcry_err_source_t} +The @code{gcry_err_source_t} type is an alias for the +@code{libgpg-error} type @code{gpg_err_source_t}. The error source +has not a precisely defined meaning. Sometimes it is the place where +the error happened, sometimes it is the place where an error was +encoded into an error value. Usually the error source will give an +indication to where to look for the problem. This is not always true, +but it is attempted to achieve this goal. + +A list of important error sources can be found in the next section. +@end deftp + +@deftp {Data type} {gcry_error_t} +The @code{gcry_error_t} type is an alias for the @code{libgpg-error} +type @code{gpg_error_t}. An error value like this has always two +components, an error code and an error source. Both together form the +error value. + +Thus, the error value can not be directly compared against an error +code, but the accessor functions described below must be used. +However, it is guaranteed that only 0 is used to indicate success +(@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of +the error value are set to 0, too. + +Note that in Libgcrypt, the error source is used purely for +diagnostic purposes. Only the error code should be checked to test +for a certain outcome of a function. The manual only documents the +error code part of an error value. The error source is left +unspecified and might be anything. +@end deftp + +@deftypefun {gcry_err_code_t} gcry_err_code (@w{gcry_error_t @var{err}}) +The static inline function @code{gcry_err_code} returns the +@code{gcry_err_code_t} component of the error value @var{err}. This +function must be used to extract the error code from an error value in +order to compare it with the @code{GPG_ERR_*} error code macros. +@end deftypefun + +@deftypefun {gcry_err_source_t} gcry_err_source (@w{gcry_error_t @var{err}}) +The static inline function @code{gcry_err_source} returns the +@code{gcry_err_source_t} component of the error value @var{err}. This +function must be used to extract the error source from an error value in +order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros. +@end deftypefun + +@deftypefun {gcry_error_t} gcry_err_make (@w{gcry_err_source_t @var{source}}, @w{gcry_err_code_t @var{code}}) +The static inline function @code{gcry_err_make} returns the error +value consisting of the error source @var{source} and the error code +@var{code}. + +This function can be used in callback functions to construct an error +value to return it to the library. +@end deftypefun + +@deftypefun {gcry_error_t} gcry_error (@w{gcry_err_code_t @var{code}}) +The static inline function @code{gcry_error} returns the error value +consisting of the default error source and the error code @var{code}. + +For @acronym{GCRY} applications, the default error source is +@code{GPG_ERR_SOURCE_USER_1}. You can define +@code{GCRY_ERR_SOURCE_DEFAULT} before including @file{gcrypt.h} to +change this default. + +This function can be used in callback functions to construct an error +value to return it to the library. +@end deftypefun + +The @code{libgpg-error} library provides error codes for all system +error numbers it knows about. If @var{err} is an unknown error +number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used. The +following functions can be used to construct error values from system +errno numbers. + +@deftypefun {gcry_error_t} gcry_err_make_from_errno (@w{gcry_err_source_t @var{source}}, @w{int @var{err}}) +The function @code{gcry_err_make_from_errno} is like +@code{gcry_err_make}, but it takes a system error like @code{errno} +instead of a @code{gcry_err_code_t} error code. +@end deftypefun + +@deftypefun {gcry_error_t} gcry_error_from_errno (@w{int @var{err}}) +The function @code{gcry_error_from_errno} is like @code{gcry_error}, +but it takes a system error like @code{errno} instead of a +@code{gcry_err_code_t} error code. +@end deftypefun + +Sometimes you might want to map system error numbers to error codes +directly, or map an error code representing a system error back to the +system error number. The following functions can be used to do that. + +@deftypefun {gcry_err_code_t} gcry_err_code_from_errno (@w{int @var{err}}) +The function @code{gcry_err_code_from_errno} returns the error code +for the system error @var{err}. If @var{err} is not a known system +error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}. +@end deftypefun + +@deftypefun {int} gcry_err_code_to_errno (@w{gcry_err_code_t @var{err}}) +The function @code{gcry_err_code_to_errno} returns the system error +for the error code @var{err}. If @var{err} is not an error code +representing a system error, or if this system error is not defined on +this system, the function returns @code{0}. +@end deftypefun + + +@node Error Sources +@subsection Error Sources +@cindex error codes, list of + +The library @code{libgpg-error} defines an error source for every +component of the GnuPG system. The error source part of an error +value is not well defined. As such it is mainly useful to improve the +diagnostic error message for the user. + +If the error code part of an error value is @code{0}, the whole error +value will be @code{0}. In this case the error source part is of +course @code{GPG_ERR_SOURCE_UNKNOWN}. + +The list of error sources that might occur in applications using +@acronym{Libgcrypt} is: + +@table @code +@item GPG_ERR_SOURCE_UNKNOWN +The error source is not known. The value of this error source is +@code{0}. + +@item GPG_ERR_SOURCE_GPGME +The error source is @acronym{GPGME} itself. + +@item GPG_ERR_SOURCE_GPG +The error source is GnuPG, which is the crypto engine used for the +OpenPGP protocol. + +@item GPG_ERR_SOURCE_GPGSM +The error source is GPGSM, which is the crypto engine used for the +OpenPGP protocol. + +@item GPG_ERR_SOURCE_GCRYPT +The error source is @code{libgcrypt}, which is used by crypto engines +to perform cryptographic operations. + +@item GPG_ERR_SOURCE_GPGAGENT +The error source is @command{gpg-agent}, which is used by crypto +engines to perform operations with the secret key. + +@item GPG_ERR_SOURCE_PINENTRY +The error source is @command{pinentry}, which is used by +@command{gpg-agent} to query the passphrase to unlock a secret key. + +@item GPG_ERR_SOURCE_SCD +The error source is the SmartCard Daemon, which is used by +@command{gpg-agent} to delegate operations with the secret key to a +SmartCard. + +@item GPG_ERR_SOURCE_KEYBOX +The error source is @code{libkbx}, a library used by the crypto +engines to manage local keyrings. + +@item GPG_ERR_SOURCE_USER_1 +@item GPG_ERR_SOURCE_USER_2 +@item GPG_ERR_SOURCE_USER_3 +@item GPG_ERR_SOURCE_USER_4 +These error sources are not used by any GnuPG component and can be +used by other software. For example, applications using +Libgcrypt can use them to mark error values coming from callback +handlers. Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors +created with @code{gcry_error} and @code{gcry_error_from_errno}, +unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including +@file{gcrypt.h}. +@end table + + +@node Error Codes +@subsection Error Codes +@cindex error codes, list of + +The library @code{libgpg-error} defines many error values. The +following list includes the most important error codes. + +@table @code +@item GPG_ERR_EOF +This value indicates the end of a list, buffer or file. + +@item GPG_ERR_NO_ERROR +This value indicates success. The value of this error code is +@code{0}. Also, it is guaranteed that an error value made from the +error code @code{0} will be @code{0} itself (as a whole). This means +that the error source information is lost for this error code, +however, as this error code indicates that no error occurred, this is +generally not a problem. + +@item GPG_ERR_GENERAL +This value means that something went wrong, but either there is not +enough information about the problem to return a more useful error +value, or there is no separate error value for this type of problem. + +@item GPG_ERR_ENOMEM +This value means that an out-of-memory condition occurred. + +@item GPG_ERR_E... +System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for +the system error. + +@item GPG_ERR_INV_VALUE +This value means that some user provided data was out of range. + +@item GPG_ERR_UNUSABLE_PUBKEY +This value means that some recipients for a message were invalid. + +@item GPG_ERR_UNUSABLE_SECKEY +This value means that some signers were invalid. + +@item GPG_ERR_NO_DATA +This value means that data was expected where no data was found. + +@item GPG_ERR_CONFLICT +This value means that a conflict of some sort occurred. + +@item GPG_ERR_NOT_IMPLEMENTED +This value indicates that the specific function (or operation) is not +implemented. This error should never happen. It can only occur if +you use certain values or configuration options which do not work, +but for which we think that they should work at some later time. + +@item GPG_ERR_DECRYPT_FAILED +This value indicates that a decryption operation was unsuccessful. + +@item GPG_ERR_WRONG_KEY_USAGE +This value indicates that a key is not used appropriately. + +@item GPG_ERR_NO_SECKEY +This value indicates that no secret key for the user ID is available. + +@item GPG_ERR_UNSUPPORTED_ALGORITHM +This value means a verification failed because the cryptographic +algorithm is not supported by the crypto backend. + +@item GPG_ERR_BAD_SIGNATURE +This value means a verification failed because the signature is bad. + +@item GPG_ERR_NO_PUBKEY +This value means a verification failed because the public key is not +available. + +@item GPG_ERR_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 +@code{gpg_strerror}. The numeric value of this error code is 176. + +@item GPG_ERR_USER_1 +@item GPG_ERR_USER_2 +@item ... +@item GPG_ERR_USER_16 +These error codes are not used by any GnuPG component and can be +freely used by other software. Applications using Libgcrypt +might use them to mark specific errors returned by callback handlers +if no suitable error codes (including the system errors) for these +errors exist already. +@end table + + +@node Error Strings +@subsection Error Strings +@cindex error values, printing of +@cindex error codes, printing of +@cindex error sources, printing of +@cindex error strings + +@deftypefun {const char *} gcry_strerror (@w{gcry_error_t @var{err}}) +The function @code{gcry_strerror} returns a pointer to a statically +allocated string containing a description of the error code contained +in the error value @var{err}. This string can be used to output a +diagnostic message to the user. +@end deftypefun + + +@deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}}) +The function @code{gcry_strerror} returns a pointer to a statically +allocated string containing a description of the error source +contained in the error value @var{err}. This string can be used to +output a diagnostic message to the user. +@end deftypefun + +The following example illustrates the use of the functions described +above: + +@example +@{ + gcry_cipher_hd_t handle; + gcry_error_t err = 0; + + err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, + GCRY_CIPHER_MODE_CBC, 0); + if (err) + @{ + fprintf (stderr, "Failure: %s/%s\n", + gcry_strsource (err), + gcry_strerror (err)); + @} +@} +@end example + +@c ********************************************************** +@c ******************* General **************************** +@c ********************************************************** +@node Handler Functions +@chapter Handler Functions + +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. +@end menu + +@node Progress handler +@section Progress handler + +It is often useful to retrieve some feedback while long running +operations are performed. + +@deftp {Data type} gcry_handler_progress_t +Progress handler functions have to be of the type +@code{gcry_handler_progress_t}, which is defined as: + +@code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)} +@end deftp + +The following function may be used to register a handler function for +this purpose. + +@deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data}) + +This function installs @var{cb} as the `Progress handler' function. +It may be used only during initialization. @var{cb} must be defined +as follows: + +@example +void +my_progress_handler (void *@var{cb_data}, const char *@var{what}, + int @var{printchar}, int @var{current}, int @var{total}) +@{ + /* Do something. */ +@} +@end example + +A description of the arguments of the progress handler function follows. + +@table @var +@item cb_data +The argument provided in the call to @code{gcry_set_progress_handler}. +@item what +A string identifying the type of the progress output. The following +values for @var{what} are defined: + +@table @code +@item need_entropy +Not enough entropy is available. @var{total} holds the number of +required bytes. + +@item primegen +Values for @var{printchar}: +@table @code +@item \n +Prime generated. +@item ! +Need to refresh the pool of prime numbers. +@item <, > +Number of bits adjusted. +@item ^ +Searching for a generator. +@item . +Fermat test on 10 candidates failed. +@item : +Restart with a new random value. +@item + +Rabin Miller test passed. +@end table + +@end table + +@end table +@end deftypefun + +@node Allocation handler +@section Allocation handler + +It is possible to make Libgcrypt use special memory +allocation functions instead of the built-in ones. + +Memory allocation functions are of the following types: +@deftp {Data type} gcry_handler_alloc_t +This type is defined as: @code{void *(*gcry_handler_alloc_t) (size_t n)}. +@end deftp +@deftp {Data type} gcry_handler_secure_check_t +This type is defined as: @code{int *(*gcry_handler_secure_check_t) (const void *)}. +@end deftp +@deftp {Data type} gcry_handler_realloc_t +This type is defined as: @code{void *(*gcry_handler_realloc_t) (void *p, size_t n)}. +@end deftp +@deftp {Data type} gcry_handler_free_t +This type is defined as: @code{void *(*gcry_handler_free_t) (void *)}. +@end deftp + +Special memory allocation functions can be installed with the +following function: + +@deftypefun void gcry_set_allocation_handler (gcry_handler_alloc_t @var{func_alloc}, gcry_handler_alloc_t @var{func_alloc_secure}, gcry_handler_secure_check_t @var{func_secure_check}, gcry_handler_realloc_t @var{func_realloc}, gcry_handler_free_t @var{func_free}) +Install the provided functions and use them instead of the built-in +functions for doing memory allocation. 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. + + +@end deftypefun + +@node Error handler +@section 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 @code{gcry_check_version}. + +@deftp {Data type} gcry_handler_no_mem_t +This type is defined as: @code{int (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)} +@end deftp +@deftypefun void gcry_set_outofcore_handler (gcry_handler_no_mem_t @var{func_no_mem}, void *@var{cb_data}) +This function registers @var{func_no_mem} as `out-of-core handler', +which means that it will be called in the case of not having enough +memory available. The handler is called with 3 arguments: The first +one is the pointer @var{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. +@end deftypefun + +@deftp {Data type} gcry_handler_error_t +This type is defined as: @code{void (*gcry_handler_error_t) (void *, int, const char *)} +@end deftp + +@deftypefun void gcry_set_fatalerror_handler (gcry_handler_error_t @var{func_error}, void *@var{cb_data}) +This function registers @var{func_error} as `error handler', +which means that it will be called in error conditions. +@end deftypefun + +@node Logging handler +@section Logging handler + +@deftp {Data type} gcry_handler_log_t +This type is defined as: @code{void (*gcry_handler_log_t) (void *, int, const char *, va_list)} +@end deftp + +@deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data}) +This function registers @var{func_log} as `logging handler', which means +that it will be called in case Libgcrypt wants to log a message. This +function may and should be used prior to calling +@code{gcry_check_version}. +@end deftypefun + +@c ********************************************************** +@c ******************* Ciphers **************************** +@c ********************************************************** +@c @include cipher-ref.texi +@node Symmetric cryptography +@chapter Symmetric cryptography + +The cipher functions are used for symmetrical cryptography, +i.e. cryptography using a shared key. The programming model follows +an open/process/close paradigm and is in that similar to other +building blocks provided by Libgcrypt. + +@menu +* Available ciphers:: List of ciphers supported by the library. +* Cipher modules:: How to work with cipher modules. +* Available cipher modes:: List of cipher modes supported by the library. +* Working with cipher handles:: How to perform operations related to cipher handles. +* General cipher functions:: General cipher functions independent of cipher handles. +@end menu + +@node Available ciphers +@section Available ciphers + +@table @code +@item GCRY_CIPHER_NONE +This is not a real algorithm but used by some functions as error return. +The value always evaluates to false. + +@item GCRY_CIPHER_IDEA +@cindex IDEA +This is the IDEA algorithm. The constant is provided but there is +currently no implementation for it because the algorithm is patented. + +@item GCRY_CIPHER_3DES +@cindex 3DES +@cindex Triple-DES +@cindex DES-EDE +@cindex Digital Encryption Standard +Triple-DES with 3 Keys as EDE. The key size of this algorithm is 168 but +you have to pass 192 bits because the most significant bits of each byte +are ignored. + +@item GCRY_CIPHER_CAST5 +@cindex CAST5 +CAST128-5 block cipher algorithm. The key size is 128 bits. + +@item GCRY_CIPHER_BLOWFISH +@cindex Blowfish +The blowfish algorithm. The current implementation allows only for a key +size of 128 bits. + +@item GCRY_CIPHER_SAFER_SK128 +Reserved and not currently implemented. + +@item GCRY_CIPHER_DES_SK +Reserved and not currently implemented. + +@item GCRY_CIPHER_AES +@itemx GCRY_CIPHER_AES128 +@itemx GCRY_CIPHER_RIJNDAEL +@itemx GCRY_CIPHER_RIJNDAEL128 +@cindex Rijndael +@cindex AES +@cindex Advanced Encryption Standard +AES (Rijndael) with a 128 bit key. + +@item GCRY_CIPHER_AES192 +@itemx GCRY_CIPHER_RIJNDAEL192 +AES (Rijndael) with a 192 bit key. + +@item GCRY_CIPHER_AES256 +@itemx GCRY_CIPHER_RIJNDAEL256 +AES (Rijndael) with a 256 bit key. + +@item GCRY_CIPHER_TWOFISH +@cindex Twofish +The Twofish algorithm with a 256 bit key. + +@item GCRY_CIPHER_TWOFISH128 +The Twofish algorithm with a 128 bit key. + +@item GCRY_CIPHER_ARCFOUR +@cindex Arcfour +@cindex RC4 +An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm. +Note that this is a stream cipher and must be used very carefully to +avoid a couple of weaknesses. + +@item GCRY_CIPHER_DES +@cindex 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. + +@item GCRY_CIPHER_SERPENT128 +@itemx GCRY_CIPHER_SERPENT192 +@itemx GCRY_CIPHER_SERPENT256 +@cindex Serpent +The Serpent cipher from the AES contest. + +@item GCRY_CIPHER_RFC2268_40 +@itemx GCRY_CIPHER_RFC2268_128 +@cindex rfc-2268 +@cindex RC2 +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. + +@item GCRY_CIPHER_SEED +@cindex Seed (cipher) +A 128 bit cipher as described by RFC4269. + +@item GCRY_CIPHER_CAMELLIA128 +@itemx GCRY_CIPHER_CAMELLIA192 +@itemx GCRY_CIPHER_CAMELLIA256 +@cindex Camellia +The Camellia cipher by NTT. See +@uref{http://info.isl.ntt.co.jp/@/crypt/@/eng/@/camellia/@/specifications.html}. + +@end table + +@node Cipher modules +@section 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 @xref{Modules}. + +@deftp {Data type} gcry_cipher_spec_t +This is the `module specification structure' needed for registering +cipher modules, which has to be filled in by the user before it can be +used to register a module. It contains the following members: + +@table @code +@item const char *name +The primary name of the algorithm. +@item const char **aliases +A list of strings that are `aliases' for the algorithm. The list must +be terminated with a NULL element. +@item gcry_cipher_oid_spec_t *oids +A list of OIDs that are to be associated with the algorithm. The +list's last element must have it's `oid' member set to NULL. See +below for an explanation of this type. +@item size_t blocksize +The block size of the algorithm, in bytes. +@item size_t keylen +The length of the key, in bits. +@item size_t contextsize +The size of the algorithm-specific `context', that should be allocated +for each handle. +@item gcry_cipher_setkey_t setkey +The function responsible for initializing a handle with a provided +key. See below for a description of this type. +@item gcry_cipher_encrypt_t encrypt +The function responsible for encrypting a single block. See below for +a description of this type. +@item gcry_cipher_decrypt_t decrypt +The function responsible for decrypting a single block. See below for +a description of this type. +@item gcry_cipher_stencrypt_t stencrypt +Like `encrypt', for stream ciphers. See below for a description of +this type. +@item gcry_cipher_stdecrypt_t stdecrypt +Like `decrypt', for stream ciphers. See below for a description of +this type. +@end table +@end deftp + +@deftp {Data type} gcry_cipher_oid_spec_t +This type is used for associating a user-provided algorithm +implementation with certain OIDs. It contains the following members: +@table @code +@item const char *oid +Textual representation of the OID. +@item int mode +Cipher mode for which this OID is valid. +@end table +@end deftp + +@deftp {Data type} gcry_cipher_setkey_t +Type for the `setkey' function, defined as: gcry_err_code_t +(*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned +keylen) +@end deftp + +@deftp {Data type} gcry_cipher_encrypt_t +Type for the `encrypt' function, defined as: gcry_err_code_t +(*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const +unsigned char *inbuf) +@end deftp + +@deftp {Data type} gcry_cipher_decrypt_t +Type for the `decrypt' function, defined as: gcry_err_code_t +(*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const +unsigned char *inbuf) +@end deftp + +@deftp {Data type} gcry_cipher_stencrypt_t +Type for the `stencrypt' function, defined as: gcry_err_code_t +(*gcry_@/cipher_@/stencrypt_@/t) (void *c, const unsigned char *outbuf, const +unsigned char *, unsigned int n) +@end deftp + +@deftp {Data type} gcry_cipher_stdecrypt_t +Type for the `stdecrypt' function, defined as: gcry_err_code_t +(*gcry_@/cipher_@/stdecrypt_@/t) (void *c, const unsigned char *outbuf, const +unsigned char *, unsigned int n) +@end deftp + +@deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module}) + +Register a new cipher module whose specification can be found in +@var{cipher}. On success, a new algorithm ID is stored in +@var{algorithm_id} and a pointer representing this module is stored +in @var{module}. +@end deftypefun + +@deftypefun void gcry_cipher_unregister (gcry_module_t @var{module}) +Unregister the cipher identified by @var{module}, which must have been +registered with gcry_cipher_register. +@end deftypefun + +@deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length}) +Get a list consisting of the IDs of the loaded cipher modules. If +@var{list} is zero, write the number of loaded cipher modules to +@var{list_length} and return. If @var{list} is non-zero, the first +*@var{list_length} algorithm IDs are stored in @var{list}, which must +be of according size. In case there are less cipher modules than +*@var{list_length}, *@var{list_length} is updated to the correct +number. +@end deftypefun + +@node Available cipher modes +@section Available cipher modes + +@table @code +@item GCRY_CIPHER_MODE_NONE +No mode specified. 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. + +@item GCRY_CIPHER_MODE_ECB +@cindex ECB, Electronic Codebook mode +Electronic Codebook mode. + +@item GCRY_CIPHER_MODE_CFB +@cindex CFB, Cipher Feedback mode +Cipher Feedback mode. The shift size equals the block size of the +cipher (e.g. for AES it is CFB-128). + +@item GCRY_CIPHER_MODE_CBC +@cindex CBC, Cipher Block Chaining mode +Cipher Block Chaining mode. + +@item GCRY_CIPHER_MODE_STREAM +Stream mode, only to be used with stream cipher algorithms. + +@item GCRY_CIPHER_MODE_OFB +@cindex OFB, Output Feedback mode +Output Feedback mode. + +@item GCRY_CIPHER_MODE_CTR +@cindex CTR, Counter mode +Counter mode. + +@end table + +@node Working with cipher handles +@section Working with cipher handles + +To use a cipher algorithm, you must first allocate an according +handle. This is to be done using the open function: + +@deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd}, int @var{algo}, int @var{mode}, unsigned int @var{flags}) + +This function creates the context handle required for most of the +other cipher functions and returns a handle to it in `hd'. In case of +an error, an according error code is returned. + +The ID of algorithm to use must be specified via @var{algo}. See +@xref{Available ciphers}, for a list of supported ciphers and the +according constants. + +Besides using the constants directly, the function +@code{gcry_cipher_map_name} may be used to convert the textual name of +an algorithm into the according numeric ID. + +The cipher mode to use must be specified via @var{mode}. See +@xref{Available cipher modes}, for a list of supported cipher modes +and the according constants. Note that some modes are incompatible +with some algorithms - in particular, stream mode +(@code{GCRY_CIPHER_MODE_STREAM}) only works with stream ciphers. Any +block cipher mode (@code{GCRY_CIPHER_MODE_ECB}, +@code{GCRY_CIPHER_MODE_CBC}, @code{GCRY_CIPHER_MODE_CFB}, +@code{GCRY_CIPHER_MODE_OFB} or @code{GCRY_CIPHER_MODE_CTR}) will work +with any block cipher algorithm. + +The third argument @var{flags} can either be passed as @code{0} or as +the bit-wise OR of the following constants. + +@table @code +@item GCRY_CIPHER_SECURE +Make sure that all operations are allocated in secure memory. This is +useful when the key material is highly confidential. +@item GCRY_CIPHER_ENABLE_SYNC +@cindex sync mode (OpenPGP) +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 @code{gcry_cipher_sync}. +@item GCRY_CIPHER_CBC_CTS +@cindex cipher text stealing +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). +@item GCRY_CIPHER_CBC_MAC +@cindex CBC-MAC +Compute CBC-MAC keyed checksums. This is the same as CBC mode, but +only output the last block. Cannot be used simultaneous as +GCRY_CIPHER_CBC_CTS. +@end table +@end deftypefun + +Use the following function to release an existing handle: + +@deftypefun void gcry_cipher_close (gcry_cipher_hd_t @var{h}) + +This function releases the context created by @code{gcry_cipher_open}. +It also zeroises all sensitive information associated with this cipher +handle. +@end deftypefun + +In order to use a handle for performing cryptographic operations, a +`key' has to be set first: + +@deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l}) + +Set the key @var{k} used for encryption or decryption in the context +denoted by the handle @var{h}. The length @var{l} (in bytes) of the +key @var{k} must match the required length of the algorithm set for +this context or be in the allowed range for algorithms with variable +key size. The function checks this and returns an error if there is a +problem. A caller should always check for an error. + +@end deftypefun + +Most crypto modes requires an initialization vector (IV), which +usually is a non-secret random string acting as a kind of salt value. +The CTR mode requires a counter, which is also similar to a salt +value. To set the IV or CTR, use these functions: + +@deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l}) + +Set the initialization vector used for encryption or decryption. The +vector is passed as the buffer @var{K} of length @var{l} bytes and +copied to internal data structures. The function checks that the IV +matches the requirement of the selected algorithm and mode. +@end deftypefun + +@deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, const void *@var{c}, size_t @var{l}) + +Set the counter vector used for encryption or decryption. The counter +is passed as the buffer @var{c} of length @var{l} 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). +@end deftypefun + +@deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h}) + +Set the given handle's context back to the state it had after the last +call to gcry_cipher_setkey and clear the initialization vector. + +Note that gcry_cipher_reset is implemented as a macro. +@end deftypefun + +The actual encryption and decryption is done by using one of the +following functions. They may be used as often as required to process +all the data. + +@deftypefun gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen}) + +@code{gcry_cipher_encrypt} is used to encrypt the data. This function +can either work in place or with two buffers. It uses the cipher +context already setup and described by the handle @var{h}. There are 2 +ways to use the function: If @var{in} is passed as @code{NULL} and +@var{inlen} is @code{0}, in-place encryption of the data in @var{out} or +length @var{outsize} takes place. With @var{in} being not @code{NULL}, +@var{inlen} bytes are encrypted to the buffer @var{out} which must have +at least a size of @var{inlen}. @var{outsize} must be set to the +allocated size of @var{out}, so that the function can check that there +is sufficient space. Note that overlapping buffers are not allowed. + +Depending on the selected algorithms and encryption mode, the length of +the buffers must be a multiple of the block size. + +The function returns @code{0} on success or an error code. +@end deftypefun + + +@deftypefun gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen}) + +@code{gcry_cipher_decrypt} is used to decrypt the data. This function +can either work in place or with two buffers. It uses the cipher +context already setup and described by the handle @var{h}. There are 2 +ways to use the function: If @var{in} is passed as @code{NULL} and +@var{inlen} is @code{0}, in-place decryption of the data in @var{out} or +length @var{outsize} takes place. With @var{in} being not @code{NULL}, +@var{inlen} bytes are decrypted to the buffer @var{out} which must have +at least a size of @var{inlen}. @var{outsize} must be set to the +allocated size of @var{out}, so that the function can check that there +is sufficient space. Note that overlapping buffers are not allowed. + +Depending on the selected algorithms and encryption mode, the length of +the buffers must be a multiple of the block size. + +The function returns @code{0} on success or an error code. +@end deftypefun + + +OpenPGP (as defined in RFC-2440) requires a special sync operation in +some places. The following function is used for this: + +@deftypefun gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h}) + +Perform the OpenPGP sync operation on context @var{h}. Note that this +is a no-op unless the context was created with the flag +@code{GCRY_CIPHER_ENABLE_SYNC} +@end deftypefun + +Some of the described functions are implemented as macros utilizing a +catch-all control function. This control function is rarely used +directly but there is nothing which would inhibit it: + +@deftypefun gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen}) + +@code{gcry_cipher_ctl} controls various aspects of the cipher module and +specific cipher contexts. Usually some more specialized functions or +macros are used for this purpose. The semantics of the function and its +parameters depends on the the command @var{cmd} and the passed context +handle @var{h}. Please see the comments in the source code +(@code{src/global.c}) for details. +@end deftypefun + +@deftypefun gcry_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes}) + +@code{gcry_cipher_info} is used to retrieve various +information about a cipher context or the cipher module in general. + +Currently no information is available. +@end deftypefun + +@node General cipher functions +@section General cipher functions + +To work with the algorithms, several functions are available to map +algorithm names to the internal identifiers, as well as ways to +retrieve information about an algorithm or the current cipher context. + +@deftypefun gcry_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes}) + +This function is used to retrieve information on a specific algorithm. +You pass the cipher algorithm ID as @var{algo} and the type of +information requested as @var{what}. The result is either returned as +the return code of the function or copied to the provided @var{buffer} +whose allocated length must be available in an integer variable with the +address passed in @var{nbytes}. This variable will also receive the +actual used length of the buffer. + +Here is a list of supported codes for @var{what}: + +@c begin constants for gcry_cipher_algo_info +@table @code +@item GCRYCTL_GET_KEYLEN: +Return the length of the key. If the algorithm supports multiple key +lengths, the maximum supported value is returned. The length is +returned as number of octets (bytes) and not as number of bits in +@var{nbytes}; @var{buffer} must be zero. + +@item GCRYCTL_GET_BLKLEN: +Return the block length of the algorithm. The length is returned as a +number of octets in @var{nbytes}; @var{buffer} must be zero. + +@item GCRYCTL_TEST_ALGO: +Returns @code{0} when the specified algorithm is available for use. +@var{buffer} and @var{nbytes} must be zero. + +@end table +@c end constants for gcry_cipher_algo_info + +@end deftypefun +@c end gcry_cipher_algo_info + +@deftypefun {const char *} gcry_cipher_algo_name (int @var{algo}) + +@code{gcry_cipher_algo_name} returns a string with the name of the +cipher algorithm @var{algo}. If the algorithm is not known or another +error occurred, the string @code{"?"} is returned. This function should +not be used to test for the availability of an algorithm. +@end deftypefun + +@deftypefun int gcry_cipher_map_name (const char *@var{name}) + +@code{gcry_cipher_map_name} returns the algorithm identifier for the +cipher algorithm described by the string @var{name}. If this algorithm +is not available @code{0} is returned. +@end deftypefun + +@deftypefun int gcry_cipher_mode_from_oid (const char *@var{string}) + +Return the cipher mode associated with an @acronym{ASN.1} object +identifier. The object identifier is expected to be in the +@acronym{IETF}-style dotted decimal notation. The function returns +@code{0} for an unknown object identifier or when no mode is associated +with it. +@end deftypefun + + +@c ********************************************************** +@c ******************* Public Key ************************* +@c ********************************************************** +@node Public Key cryptography +@chapter 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. +@end menu + +@node Available algorithms +@section 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. + +@node Used S-expressions +@section Used S-expressions + +Libgcrypt's API for asymmetric cryptography is based on data structures +called S-expressions (see +@uref{http://people.csail.mit.edu/@/rivest/@/sexp.html}) and does not work +with contexts as most of the other building blocks of Libgcrypt do. + +@noindent +The following information are stored in S-expressions: + +@itemize @asis +@item keys + +@item plain text data + +@item encrypted data + +@item signatures + +@end itemize + +@noindent +To describe how Libgcrypt expect keys, we use examples. Note that +words in +@ifnottex +uppercase +@end ifnottex +@iftex +italics +@end iftex +indicate parameters whereas lowercase words are literals. + +Note that all MPI (multi-precision-integers) values are expected to be in +@code{GCRYMPI_FMT_USG} format. An easy way to create S-expressions is +by using @code{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. +@end menu + +@node RSA key parameters +@subsection RSA key parameters + +@noindent +An RSA private key is described by this S-expression: + +@example +(private-key + (rsa + (n @var{n-mpi}) + (e @var{e-mpi}) + (d @var{d-mpi}) + (p @var{p-mpi}) + (q @var{q-mpi}) + (u @var{u-mpi}))) +@end example + +@noindent +An RSA public key is described by this S-expression: + +@example +(public-key + (rsa + (n @var{n-mpi}) + (e @var{e-mpi}))) +@end example + + +@table @var +@item n-mpi +RSA public modulus @math{n}. +@item e-mpi +RSA public exponent @math{e}. +@item d-mpi +RSA secret exponent @math{d = e^{-1} \bmod (p-1)(q-1)}. +@item p-mpi +RSA secret prime @math{p}. +@item q-mpi +RSA secret prime @math{q} with @math{p < q}. +@item u-mpi +Multiplicative inverse @math{u = p^{-1} \bmod q}. +@end table + +For signing and decryption the parameters @math{(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: @math{q < p} and + @math{u = q^{-1} \bmod p}. To use these parameters you will need to +swap the values and recompute @math{u}. Here is example code to do this: + +@example + if (gcry_mpi_cmp (p, q) > 0) + @{ + gcry_mpi_swap (p, q); + gcry_mpi_invm (u, p, q); + @} +@end example + + + + +@node DSA key parameters +@subsection DSA key parameters + +@noindent +A DSA private key is described by this S-expression: + +@example +(private-key + (dsa + (p @var{p-mpi}) + (q @var{q-mpi}) + (g @var{g-mpi}) + (y @var{y-mpi}) + (x @var{x-mpi}))) +@end example + +@table @var +@item p-mpi +DSA prime @math{p}. +@item q-mpi +DSA group order @math{q} (which is a prime divisor of @math{p-1}). +@item g-mpi +DSA group generator @math{g}. +@item y-mpi +DSA public key value @math{y = g^x \bmod p}. +@item x-mpi +DSA secret exponent x. +@end table + +The public key is similar with "private-key" replaced by "public-key" +and no @var{x-mpi}. + + +@node ECC key parameters +@subsection ECC key parameters + +@noindent +An ECC private key is described by this S-expression: + +@example +(private-key + (ecc + (p @var{p-mpi}) + (a @var{a-mpi}) + (b @var{b-mpi}) + (g @var{g-point}) + (n @var{n-mpi}) + (q @var{q-point}) + (d @var{d-mpi}))) +@end example + +@table @var +@item p-mpi +Prime specifying the field @math{GF(p)}. +@item a-mpi +@itemx b-mpi +The two coefficients of the Weierstrass equation @math{y^2 = x^3 + ax + b} +@item g-point +Base point @math{g}. +@item n-mpi +Order of @math{g} +@item q-point +The point representing the public key @math{Q = dP}. +@item d-mpi +The private key @math{d} +@end table + +All point values are encoded in standard format; Libgcrypt does +currently only support uncompressed points, thus the first byte needs to +be @code{0x04}. + +The public key is similar with "private-key" replaced by "public-key" +and no @var{d-mpi}. + +If the domain parameters are well-known, the name of this curve may be +used. For example + +@example +(private-key + (ecc + (curve "NIST P-192") + (q @var{q-point}) + (d @var{d-mpi}))) +@end example + +The @code{curve} parameter may be given in any case and is used to replace +missing parameters. + +@noindent +Currently implemented curves are: +@table @code +@item NIST P-192 +@itemx 1.2.840.10045.3.1.1 +@itemx prime192v1 +@itemx secp192r1 +The NIST 192 bit curve, its OID, X9.62 and SECP aliases. + +@item NIST P-224 +@itemx secp224r1 +The NIST 224 bit curve and its SECP alias. + +@item NIST P-256 +@itemx 1.2.840.10045.3.1.7 +@itemx prime256v1 +@itemx secp256r1 +The NIST 256 bit curve, its OID, X9.62 and SECP aliases. + +@item NIST P-384 +@itemx secp384r1 +The NIST 384 bit curve and its SECP alias. + +@item NIST P-521 +@itemx secp521r1 +The NIST 521 bit curve and its SECP alias. + +@end table +As usual the OIDs may optionally be prefixed with the string @code{OID.} +or @code{oid.}. + + + +@node Public key modules +@section 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 @xref{Modules}. + +@deftp {Data type} gcry_pk_spec_t +This is the `module specification structure' needed for registering +public key modules, which has to be filled in by the user before it +can be used to register a module. It contains the following members: + +@table @code +@item const char *name +The primary name of this algorithm. +@item char **aliases +A list of strings that are `aliases' for the algorithm. The list +must be terminated with a NULL element. +@item const char *elements_pkey +String containing the one-letter names of the MPI values contained in +a public key. +@item const char *element_skey +String containing the one-letter names of the MPI values contained in +a secret key. +@item const char *elements_enc +String containing the one-letter names of the MPI values that are the +result of an encryption operation using this algorithm. +@item const char *elements_sig +String containing the one-letter names of the MPI values that are the +result of a sign operation using this algorithm. +@item const char *elements_grip +String containing the one-letter names of the MPI values that are to +be included in the `key grip'. +@item int use +The bitwise-OR of the following flags, depending on the abilities of +the algorithm: +@table @code +@item GCRY_PK_USAGE_SIGN +The algorithm supports signing and verifying of data. +@item GCRY_PK_USAGE_ENCR +The algorithm supports the encryption and decryption of data. +@end table +@item gcry_pk_generate_t generate +The function responsible for generating a new key pair. See below for +a description of this type. +@item gcry_pk_check_secret_key_t check_secret_key +The function responsible for checking the sanity of a provided secret +key. See below for a description of this type. +@item gcry_pk_encrypt_t encrypt +The function responsible for encrypting data. See below for a +description of this type. +@item gcry_pk_decrypt_t decrypt +The function responsible for decrypting data. See below for a +description of this type. +@item gcry_pk_sign_t sign +The function responsible for signing data. See below for a description +of this type. +@item gcry_pk_verify_t verify +The function responsible for verifying that the provided signature +matches the provided data. See below for a description of this type. +@item gcry_pk_get_nbits_t get_nbits +The function responsible for returning the number of bits of a provided +key. See below for a description of this type. +@end table +@end deftp + +@deftp {Data type} gcry_pk_generate_t +Type for the `generate' function, defined as: gcry_err_code_t +(*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long +use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors) +@end deftp + +@deftp {Data type} gcry_pk_check_secret_key_t +Type for the `check_secret_key' function, defined as: gcry_err_code_t +(*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey) +@end deftp + +@deftp {Data type} gcry_pk_encrypt_t +Type for the `encrypt' function, defined as: gcry_err_code_t +(*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data, +gcry_mpi_t *pkey, int flags) +@end deftp + +@deftp {Data type} gcry_pk_decrypt_t +Type for the `decrypt' function, defined as: gcry_err_code_t +(*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data, +gcry_mpi_t *skey, int flags) +@end deftp + +@deftp {Data type} gcry_pk_sign_t +Type for the `sign' function, defined as: gcry_err_code_t +(*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data, +gcry_mpi_t *skey) +@end deftp + +@deftp {Data type} gcry_pk_verify_t +Type for the `verify' function, defined as: gcry_err_code_t +(*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data, +gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev) +@end deftp + +@deftp {Data type} gcry_pk_get_nbits_t +Type for the `get_nbits' function, defined as: unsigned +(*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey) +@end deftp + +@deftypefun gcry_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module}) + +Register a new public key module whose specification can be found in +@var{pubkey}. On success, a new algorithm ID is stored in +@var{algorithm_id} and a pointer representing this module is stored +in @var{module}. +@end deftypefun + +@deftypefun void gcry_pk_unregister (gcry_module_t @var{module}) +Unregister the public key module identified by @var{module}, which +must have been registered with gcry_pk_register. +@end deftypefun + +@deftypefun gcry_error_t gcry_pk_list (int *@var{list}, int *@var{list_length}) +Get a list consisting of the IDs of the loaded pubkey modules. If +@var{list} is zero, write the number of loaded pubkey modules to +@var{list_length} and return. If @var{list} is non-zero, the first +*@var{list_length} algorithm IDs are stored in @var{list}, which must +be of according size. In case there are less pubkey modules than +*@var{list_length}, *@var{list_length} is updated to the correct +number. +@end deftypefun + +@node Cryptographic Functions +@section Cryptographic Functions + +@noindent +Note that we will in future allow to use keys without p,q and u +specified and may also support other parameters for performance +reasons. + +@noindent + +Some functions operating on S-expressions support `flags', that +influence the operation. These flags have to be listed in a +sub-S-expression named `flags'; the following flags are known: + +@table @code +@item pkcs1 +Use PKCS#1 block type 2 padding. +@item no-blinding +Do not use a technique called `blinding', which is used by default in +order to prevent leaking of secret information. Blinding is only +implemented by RSA, but it might be implemented by other algorithms in +the future as well, when necessary. +@end table + +@noindent +Now that we know the key basics, we can carry on and explain how to +encrypt and decrypt data. In almost all cases the data is a random +session key which is in turn used for the actual encryption of the real +data. There are 2 functions to do this: + +@deftypefun gcry_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}}) + +Obviously a public key must be provided for encryption. It is +expected as an appropriate S-expression (see above) in @var{pkey}. +The data to be encrypted can either be in the simple old format, which +is a very simple S-expression consisting only of one MPI, or it may be +a more complex S-expression which also allows to specify flags for +operation, like e.g. padding rules. + +@noindent +If you don't want to let Libgcrypt handle the padding, you must pass an +appropriate MPI using this expression for @var{data}: + +@example +(data + (flags raw) + (value @var{mpi})) +@end example + +@noindent +This has the same semantics as the old style MPI only way. @var{MPI} is +the actual data, already padded appropriate for your protocol. Most +systems however use PKCS#1 padding and so you can use this S-expression +for @var{data}: + +@example +(data + (flags pkcs1) + (value @var{block})) +@end example + +@noindent +Here, the "flags" list has the "pkcs1" flag which let the function know +that it should provide PKCS#1 block type 2 padding. The actual data to +be encrypted is passed as a string of octets in @var{block}. The +function checks that this data actually can be used with the given key, +does the padding and encrypts it. + +If the function could successfully perform the encryption, the return +value will be 0 and a new S-expression with the encrypted result is +allocated and assigned to the variable at the address of @var{r_ciph}. +The caller is responsible to release this value using +@code{gcry_sexp_release}. In case of an error, an error code is +returned and @var{r_ciph} will be set to @code{NULL}. + +@noindent +The returned S-expression has this format when used with RSA: + +@example +(enc-val + (rsa + (a @var{a-mpi}))) +@end example + +@noindent +Where @var{a-mpi} is an MPI with the result of the RSA operation. When +using the Elgamal algorithm, the return value will have this format: + +@example +(enc-val + (elg + (a @var{a-mpi}) + (b @var{b-mpi}))) +@end example + +@noindent +Where @var{a-mpi} and @var{b-mpi} are MPIs with the result of the +Elgamal encryption operation. +@end deftypefun +@c end gcry_pk_encrypt + +@deftypefun gcry_error_t gcry_pk_decrypt (@w{gcry_sexp_t *@var{r_plain},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}}) + +Obviously a private key must be provided for decryption. It is expected +as an appropriate S-expression (see above) in @var{skey}. The data to +be decrypted must match the format of the result as returned by +@code{gcry_pk_encrypt}, but should be enlarged with a @code{flags} +element: + +@example +(enc-val + (flags) + (elg + (a @var{a-mpi}) + (b @var{b-mpi}))) +@end example + +@noindent +Note that this function currently does not know of any padding +methods and the caller must do any un-padding on his own. + +@noindent +The function returns 0 on success or an error code. The variable at the +address of @var{r_plain} will be set to NULL on error or receive the +decrypted value on success. The format of @var{r_plain} is a +simple S-expression part (i.e. not a valid one) with just one MPI if +there was no @code{flags} element in @var{data}; if at least an empty +@code{flags} is passed in @var{data}, the format is: + +@example +(value @var{plaintext}) +@end example +@end deftypefun +@c end gcry_pk_decrypt + + +Another operation commonly performed using public key cryptography is +signing data. In some sense this is even more important than +encryption because digital signatures are an important instrument for +key management. Libgcrypt supports digital signatures using +2 functions, similar to the encryption functions: + +@deftypefun gcry_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}}) + +This function creates a digital signature for @var{data} using the +private key @var{skey} and place it into the variable at the address of +@var{r_sig}. @var{data} may either be the simple old style S-expression +with just one MPI or a modern and more versatile S-expression which +allows to let Libgcrypt handle padding: + +@example + (data + (flags pkcs1) + (hash @var{hash-algo} @var{block})) +@end example + +@noindent +This example requests to sign the data in @var{block} after applying +PKCS#1 block type 1 style padding. @var{hash-algo} is a string with the +hash algorithm to be encoded into the signature, this may be any hash +algorithm name as supported by Libgcrypt. Most likely, this will be +"sha256" or "sha1". It is obvious that the length of @var{block} must +match the size of that message digests; the function checks that this +and other constraints are valid. + +@noindent +If PKCS#1 padding is not required (because the caller does already +provide a padded value), either the old format or better the following +format should be used: + +@example +(data + (flags raw) + (value @var{mpi})) +@end example + +@noindent +Here, the data to be signed is directly given as an @var{MPI}. + +@noindent +The signature is returned as a newly allocated S-expression in +@var{r_sig} using this format for RSA: + +@example +(sig-val + (rsa + (s @var{s-mpi}))) +@end example + +Where @var{s-mpi} is the result of the RSA sign operation. For DSA the +S-expression returned is: + +@example +(sig-val + (dsa + (r @var{r-mpi}) + (s @var{s-mpi}))) +@end example + +Where @var{r-mpi} and @var{s-mpi} are the result of the DSA sign +operation. For Elgamal signing (which is slow, yields large numbers +and probably is not as secure as the other algorithms), the same format is +used with "elg" replacing "dsa". +@end deftypefun +@c end gcry_pk_sign + +@noindent +The operation most commonly used is definitely the verification of a +signature. Libgcrypt provides this function: + +@deftypefun gcry_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}}) + +This is used to check whether the signature @var{sig} matches the +@var{data}. The public key @var{pkey} must be provided to perform this +verification. This function is similar in its parameters to +@code{gcry_pk_sign} with the exceptions that the public key is used +instead of the private key and that no signature is created but a +signature, in a format as created by @code{gcry_pk_sign}, is passed to +the function in @var{sig}. + +@noindent +The result is 0 for success (i.e. the data matches the signature), or an +error code where the most relevant code is @code{GCRYERR_BAD_SIGNATURE} +to indicate that the signature does not match the provided data. + +@end deftypefun +@c end gcry_pk_verify + +@node General public-key related Functions +@section General public-key related Functions + +@noindent +A couple of utility functions are available to retrieve the length of +the key, map algorithm identifiers and perform sanity checks: + +@deftypefun {const char *} gcry_pk_algo_name (int @var{algo}) + +Map the public key algorithm id @var{algo} to a string representation of +the algorithm name. For unknown algorithms this functions returns the +string @code{"?"}. This function should not be used to test for the +availability of an algorithm. +@end deftypefun + +@deftypefun int gcry_pk_map_name (const char *@var{name}) + +Map the algorithm @var{name} to a public key algorithm Id. Returns 0 if +the algorithm name is not known. +@end deftypefun + +@deftypefun int gcry_pk_test_algo (int @var{algo}) + +Return 0 if the public key algorithm @var{algo} is available for use. +Note that this is implemented as a macro. +@end deftypefun + + +@deftypefun {unsigned int} gcry_pk_get_nbits (gcry_sexp_t @var{key}) + +Return what is commonly referred as the key length for the given +public or private in @var{key}. +@end deftypefun + +@deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{gcry_sexp_t @var{key}}, @w{unsigned char *@var{array}}) + +Return the so called "keygrip" which is the SHA-1 hash of the public key +parameters expressed in a way depended on the algorithm. @var{array} +must either provide space for 20 bytes or be @code{NULL}. In the latter +case a newly allocated array of that size is returned. On success a +pointer to the newly allocated space or to @var{array} is returned. +@code{NULL} is returned to indicate an error which is most likely an +unknown algorithm or one where a "keygrip" has not yet been defined. +The function accepts public or secret keys in @var{key}. +@end deftypefun + +@deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key}) + +Return zero if the private key @var{key} is `sane', an error code otherwise. +Note that it is not possible to check the `saneness' of a public key. + +@end deftypefun + + +@deftypefun gcry_error_t gcry_pk_algo_info (@w{int @var{algo}}, @w{int @var{what}}, @w{void *@var{buffer}}, @w{size_t *@var{nbytes}}) + +Depending on the value of @var{what} return various information about +the public key algorithm with the id @var{algo}. Note that the +function returns @code{-1} on error and the actual error code must be +retrieved using the function @code{gcry_errno}. The currently defined +values for @var{what} are: + +@table @code +@item GCRYCTL_TEST_ALGO: +Return 0 if the specified algorithm is available for use. +@var{buffer} must be @code{NULL}, @var{nbytes} may be passed as +@code{NULL} or point to a variable with the required usage of the +algorithm. This may be 0 for "don't care" or the bit-wise OR of these +flags: + +@table @code +@item GCRY_PK_USAGE_SIGN +Algorithm is usable for signing. +@item GCRY_PK_USAGE_ENCR +Algorithm is usable for encryption. +@end table + +Unless you need to test for the allowed usage, it is in general better +to use the macro gcry_pk_test_algo instead. + +@item GCRYCTL_GET_ALGO_USAGE: +Return the usage flags for the given algorithm. An invalid algorithm +return 0. Disabled algorithms are ignored here because we +want to know whether the algorithm is at all capable of a certain usage. + +@item GCRYCTL_GET_ALGO_NPKEY +Return the number of elements the public key for algorithm @var{algo} +consist of. Return 0 for an unknown algorithm. + +@item GCRYCTL_GET_ALGO_NSKEY +Return the number of elements the private key for algorithm @var{algo} +consist of. Note that this value is always larger than that of the +public key. Return 0 for an unknown algorithm. + +@item GCRYCTL_GET_ALGO_NSIGN +Return the number of elements a signature created with the algorithm +@var{algo} consists of. Return 0 for an unknown algorithm or for an +algorithm not capable of creating signatures. + +@item GCRYCTL_GET_ALGO_NENC +Return the number of elements a encrypted message created with the algorithm +@var{algo} consists of. Return 0 for an unknown algorithm or for an +algorithm not capable of encryption. +@end table + +@noindent +Please note that parameters not required should be passed as @code{NULL}. +@end deftypefun +@c end gcry_pk_algo_info + + +@deftypefun gcry_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}}) + +This is a general purpose function to perform certain control +operations. @var{cmd} controls what is to be done. The return value is +0 for success or an error code. Currently supported values for +@var{cmd} are: + +@table @code +@item GCRYCTL_DISABLE_ALGO +Disable the algorithm given as an algorithm id in @var{buffer}. +@var{buffer} must point to an @code{int} variable with the algorithm id +and @var{buflen} must have the value @code{sizeof (int)}. + +@end table +@end deftypefun +@c end gcry_pk_ctl + +@noindent +Libgcrypt also provides a function to generate public key +pairs: + +@deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}}) + +This function create a new public key pair using information given in +the S-expression @var{parms} and stores the private and the public key +in one new S-expression at the address given by @var{r_key}. In case of +an error, @var{r_key} is set to @code{NULL}. The return code is 0 for +success or an error code otherwise. + +@noindent +Here is an example for @var{parms} to create an 2048 bit RSA key: + +@example +(genkey + (rsa + (nbits 4:2048))) +@end example + +@noindent +To create an Elgamal key, substitute "elg" for "rsa" and to create a DSA +key use "dsa". Valid ranges for the key length depend on the +algorithms; all commonly used key lengths are supported. Currently +supported parameters are: + +@table @code +@item nbits +This is always required to specify the length of the key. The argument +is a string with a number in C-notation. The value should be a multiple +of 8. + +@item curve @var{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 @code{nbits} has been +given. The available names are listed with the description of the ECC +public key parameters. + +@item rsa-use-e +This is only used with RSA to give a hint for the public exponent. The +value will be used as a base to test for a usable exponent. Some values +are special: + +@table @samp +@item 0 +Use a secure and fast value. This is currently the number 41. +@item 1 +Use a value as required by some crypto policies. This is currently +the number 65537. +@item 2 +Reserved +@item > 2 +Use the given value. +@end table + +@noindent +If this parameter is not used, Libgcrypt uses for historic reasons +65537. + +@item 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: +@table @samp +@item 512 <= N <= 1024 +Q = 160 +@item N = 2048 +Q = 224 +@item N = 3072 +Q = 256 +@item N = 7680 +Q = 384 +@item N = 15360 +Q = 512 +@end table +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. + +@item 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. + +@item 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: + +@example +(genkey + (dsa + (domain + (p @var{p-mpi}) + (q @var{q-mpi}) + (g @var{q-mpi})))) +@end example + +@code{nbits} and @code{qbits} may not be specified because they are +derived from the domain parameters. + +@item derive-parms +This is currently only implemented for RSA and DSA keys. It is not +allowed to use this together with a @code{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. + +@example +(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#)))) +@end example + +@example +(genkey + (dsa + (nbits 4:1024) + (derive-parms + (seed @var{seed-mpi})))) +@end example + + +@item use-x931 +@cindex X9.31 +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 @code{derive-parms} is given or Libgcrypt is in FIPS mode. + +@item use-fips186 +@cindex FIPS 186 +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 +@code{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. + + +@item 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. + + +@end table +@c end table of parameters + +@noindent +The key pair is returned in a format depending on the algorithm. Both +private and public keys are returned in one container and may be +accompanied by some miscellaneous information. + +@noindent +As an example, here is what the Elgamal key generation returns: + +@example +(key-data + (public-key + (elg + (p @var{p-mpi}) + (g @var{g-mpi}) + (y @var{y-mpi}))) + (private-key + (elg + (p @var{p-mpi}) + (g @var{g-mpi}) + (y @var{y-mpi}) + (x @var{x-mpi}))) + (misc-key-info + (pm1-factors @var{n1 n2 ... nn})) +@end example + +@noindent +As you can see, some of the information is duplicated, but this +provides an easy way to extract either the public or the private key. +Note that the order of the elements is not defined, e.g. the private +key may be stored before the public key. @var{n1 n2 ... nn} is a list +of prime numbers used to composite @var{p-mpi}; this is in general not +a very useful information and only available if the key generation +algorithm provides them. +@end deftypefun +@c end gcry_pk_genkey + +@node AC Interface +@section 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. + +@strong{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. +@end menu + +@node Available asymmetric algorithms +@subsection 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. + +@deftp {Data type} gcry_ac_id_t + +The following constants are defined for this type: + +@table @code +@item GCRY_AC_RSA +Rivest-Shamir-Adleman +@item GCRY_AC_DSA +Digital Signature Algorithm +@item GCRY_AC_ELG +Elgamal +@item GCRY_AC_ELG_E +Elgamal, encryption only. +@end table +@end deftp + +@node Working with sets of data +@subsection 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. + +@deftp {Data type} gcry_ac_data_t +A single data set. +@end deftp + +The following flags are supported: + +@table @code +@item GCRY_AC_FLAG_DEALLOC +Used for storing data in a data set. If given, the data will be +released by the library. 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(). + +@item GCRY_AC_FLAG_COPY +Used for storing/retrieving data in/from a data set. If given, the +library will create copies of the provided/contained data, which will +then be given to the user/associated with the data set. +@end table + +@deftypefun gcry_error_t gcry_ac_data_new (gcry_ac_data_t *@var{data}) +Creates a new, empty data set and stores it in @var{data}. +@end deftypefun + +@deftypefun void gcry_ac_data_destroy (gcry_ac_data_t @var{data}) +Destroys the data set @var{data}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_set (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t @var{mpi}) +Add the value @var{mpi} to @var{data} with the label @var{name}. If +@var{flags} contains GCRY_AC_FLAG_COPY, the data set will contain +copies of @var{name} and @var{mpi}. If @var{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. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data}) +Create a copy of the data set @var{data} and store it in +@var{data_cp}. FIXME: exact semantics undefined. +@end deftypefun + +@deftypefun {unsigned int} gcry_ac_data_length (gcry_ac_data_t @var{data}) +Returns the number of named MPI values inside of the data set +@var{data}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t *@var{mpi}) +Store the value labelled with @var{name} found in @var{data} in +@var{mpi}. If @var{flags} contains GCRY_AC_FLAG_COPY, store a copy of +the @var{mpi} value contained in the data set. @var{mpi} may be NULL +(this might be useful for checking the existence of an MPI with +extracting it). +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t @var{data}, unsigned int flags, unsigned int @var{index}, const char **@var{name}, gcry_mpi_t *@var{mpi}) +Stores in @var{name} and @var{mpi} the named @var{mpi} value contained +in the data set @var{data} with the index @var{idx}. If @var{flags} +contains GCRY_AC_FLAG_COPY, store copies of the values contained in +the data set. @var{name} or @var{mpi} may be NULL. +@end deftypefun + +@deftypefun void gcry_ac_data_clear (gcry_ac_data_t @var{data}) +Destroys any values contained in the data set @var{data}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_to_sexp (gcry_ac_data_t @var{data}, gcry_sexp_t *@var{sexp}, const char **@var{identifiers}) +This function converts the data set @var{data} into a newly created +S-Expression, which is to be stored in @var{sexp}; @var{identifiers} +is a NULL terminated list of C strings, which specifies the structure +of the S-Expression. + +Example: + +If @var{identifiers} is a list of pointers to the strings ``foo'' and +``bar'' and if @var{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))). +@end deftypefun + +@deftypefun gcry_error gcry_ac_data_from_sexp (gcry_ac_data_t *@var{data}, gcry_sexp_t @var{sexp}, const char **@var{identifiers}) +This function converts the S-Expression @var{sexp} into a newly +created data set, which is to be stored in @var{data}; +@var{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. +@end deftypefun + +@node Working with IO objects +@subsection Working with IO objects + +Note: IO objects are currently only used in the context of message +encoding/decoding and encryption/signature schemes. + +@deftp {Data type} {gcry_ac_io_t} +@code{gcry_ac_io_t} is the type to be used for IO objects. +@end deftp + +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: + +@deftypefun void gcry_ac_io_init (gcry_ac_io_t *@var{ac_io}, gcry_ac_io_mode_t @var{mode}, gcry_ac_io_type_t @var{type}, ...); +Initialize @var{ac_io} according to @var{mode}, @var{type} and the +variable list of arguments. The list of variable arguments to specify +depends on the given @var{type}. +@end deftypefun + +@deftypefun void gcry_ac_io_init_va (gcry_ac_io_t *@var{ac_io}, gcry_ac_io_mode_t @var{mode}, gcry_ac_io_type_t @var{type}, va_list @var{ap}); +Initialize @var{ac_io} according to @var{mode}, @var{type} and the +variable list of arguments @var{ap}. The list of variable arguments +to specify depends on the given @var{type}. +@end deftypefun + +The following types of IO objects exist: + +@table @code +@item 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: +@table @code +@item unsigned char * +Pointer to the beginning of the memory string +@item size_t +Size of the memory string +@end table +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: +@table @code +@item unsigned char ** +Pointer to address, at which the pointer to the newly created memory +string is to be stored +@item size_t * +Pointer to address, at which the size of the newly created memory +string is to be stored +@end table + +@item 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: +@table @code +@item gcry_ac_data_read_cb_t +Callback function to use +@item void * +Opaque argument to provide to the callback function +@end table +In case of GCRY_AC_IO_WRITABLE the object will forward write requests +to a provided callback function. Arguments to specify at +initialization time: +@table @code +@item gcry_ac_data_write_cb_t +Callback function to use +@item void * +Opaque argument to provide to the callback function +@end table +@end table + +@node Working with handles +@subsection Working with handles + +In order to use an algorithm, an according handle must be created. +This is done using the following function: + +@deftypefun gcry_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle}, int @var{algorithm}, int @var{flags}) + +Creates a new handle for the algorithm @var{algorithm} and stores it +in @var{handle}. @var{flags} is not used currently. + +@var{algorithm} must be a valid algorithm ID, see @xref{Available +asymmetric algorithms}, for a list of supported algorithms and the +according constants. Besides using the listed constants directly, the +functions @code{gcry_pk_name_to_id} may be used to convert the textual +name of an algorithm into the according numeric ID. +@end deftypefun + +@deftypefun void gcry_ac_close (gcry_ac_handle_t @var{handle}) +Destroys the handle @var{handle}. +@end deftypefun + +@node Working with keys +@subsection Working with keys + +@deftp {Data type} gcry_ac_key_type_t +Defined constants: + +@table @code +@item GCRY_AC_KEY_SECRET +Specifies a secret key. +@item GCRY_AC_KEY_PUBLIC +Specifies a public key. +@end table +@end deftp + +@deftp {Data type} gcry_ac_key_t +This type represents a single `key', either a secret one or a public +one. +@end deftp + +@deftp {Data type} gcry_ac_key_pair_t +This type represents a `key pair' containing a secret and a public key. +@end deftp + +Key data structures can be created in two different ways; a new key +pair can be generated, resulting in ready-to-use key. Alternatively a +key can be initialized from a given data set. + +@deftypefun gcry_error_t gcry_ac_key_init (gcry_ac_key_t *@var{key}, gcry_ac_handle_t @var{handle}, gcry_ac_key_type_t @var{type}, gcry_ac_data_t @var{data}) +Creates a new key of type @var{type}, consisting of the MPI values +contained in the data set @var{data} and stores it in @var{key}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t @var{handle}, unsigned int @var{nbits}, void *@var{key_spec}, gcry_ac_key_pair_t *@var{key_pair}, gcry_mpi_t **@var{misc_data}) + +Generates a new key pair via the handle @var{handle} of @var{NBITS} +bits and stores it in @var{key_pair}. + +In case non-standard settings are wanted, a pointer to a structure of +type @code{gcry_ac_key_spec_<algorithm>_t}, matching the selected +algorithm, can be given as @var{key_spec}. @var{misc_data} is not +used yet. Such a structure does only exist for RSA. A description +of the members of the supported structures follows. + +@table @code +@item gcry_ac_key_spec_rsa_t +@table @code +@item gcry_mpi_t e +Generate the key pair using a special @code{e}. The value of @code{e} +has the following meanings: +@table @code +@item = 0 +Let Libgcrypt decide what exponent should be used. +@item = 1 +Request the use of a ``secure'' exponent; this is required by some +specification to be 65537. +@item > 2 +Try starting at this value until a working exponent is found. Note +that the current implementation leaks some information about the +private key because the incrementation used is not randomized. Thus, +this function will be changed in the future to return a random +exponent of the given size. +@end table +@end table +@end table + +Example code: +@example +@{ + gcry_ac_key_pair_t key_pair; + gcry_ac_key_spec_rsa_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); +@} +@end example +@end deftypefun + + +@deftypefun gcry_ac_key_t gcry_ac_key_pair_extract (gcry_ac_key_pair_t @var{key_pair}, gcry_ac_key_type_t @var{which}) +Returns the key of type @var{which} out of the key pair +@var{key_pair}. +@end deftypefun + +@deftypefun void gcry_ac_key_destroy (gcry_ac_key_t @var{key}) +Destroys the key @var{key}. +@end deftypefun + +@deftypefun void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t @var{key_pair}) +Destroys the key pair @var{key_pair}. +@end deftypefun + +@deftypefun gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t @var{key}) +Returns the data set contained in the key @var{key}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_key_test (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}) +Verifies that the private key @var{key} is sane via @var{handle}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned int *@var{nbits}) +Stores the number of bits of the key @var{key} in @var{nbits} via @var{handle}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned char *@var{key_grip}) +Writes the 20 byte long key grip of the key @var{key} to +@var{key_grip} via @var{handle}. +@end deftypefun + +@node Using cryptographic functions +@subsection Using cryptographic functions + +The following flags might be relevant: + +@table @code +@item GCRY_AC_FLAG_NO_BLINDING +Disable any blinding, which might be supported by the chosen +algorithm; blinding is the default. +@end table + +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. + +@deftypefun gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data_plain}, gcry_ac_data_t *@var{data_encrypted}) +Encrypts the plain text MPI value @var{data_plain} with the key public +@var{key} under the control of the flags @var{flags} and stores the +resulting data set into @var{data_encrypted}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t *@var{data_plain}, gcry_ac_data_t @var{data_encrypted}) +Decrypts the encrypted data contained in the data set +@var{data_encrypted} with the secret key KEY under the control of the +flags @var{flags} and stores the resulting plain text MPI value in +@var{DATA_PLAIN}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t *@var{data_signature}) +Signs the data contained in @var{data} with the secret key @var{key} +and stores the resulting signature in the data set +@var{data_signature}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t @var{data_signature}) +Verifies that the signature contained in the data set +@var{data_signature} is indeed the result of signing the data +contained in @var{data} with the secret key belonging to the public +key @var{key}. +@end deftypefun + +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: + +@table @code +@item 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. + +@item 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. +@end table + +Option structure types: + +@table @code +@item gcry_ac_eme_pkcs_v1_5_t +@table @code +@item gcry_ac_key_t key +@item gcry_ac_handle_t handle +@end table +@item gcry_ac_emsa_pkcs_v1_5_t +@table @code +@item gcry_md_algo_t md +@item size_t em_n +@end table +@end table + +Encoding methods can be used directly through the following functions: + +@deftypefun gcry_error_t gcry_ac_data_encode (gcry_ac_em_t @var{method}, unsigned int @var{flags}, void *@var{options}, unsigned char *@var{m}, size_t @var{m_n}, unsigned char **@var{em}, size_t *@var{em_n}) +Encodes the message contained in @var{m} of size @var{m_n} according +to @var{method}, @var{flags} and @var{options}. The newly created +encoded message is stored in @var{em} and @var{em_n}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_decode (gcry_ac_em_t @var{method}, unsigned int @var{flags}, void *@var{options}, unsigned char *@var{em}, size_t @var{em_n}, unsigned char **@var{m}, size_t *@var{m_n}) +Decodes the message contained in @var{em} of size @var{em_n} according +to @var{method}, @var{flags} and @var{options}. The newly created +decoded message is stored in @var{m} and @var{m_n}. +@end deftypefun + +The type ``gcry_ac_scheme_t'' is used for specifying schemes; the +following schemes are supported: + +@table @code +@item GCRY_AC_ES_PKCS_V1_5 +PKCS-V1_5 Encryption Scheme. No options can be provided. +@item 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. +@end table + +Option structure types: + +@table @code +@item gcry_ac_ssa_pkcs_v1_5_t +@table @code +@item gcry_md_algo_t md +@end table +@end table + +The functions implementing schemes: + +@deftypefun gcry_error_t gcry_ac_data_encrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_cipher}) +Encrypts the plain text readable from @var{io_message} through +@var{handle} with the public key @var{key} according to @var{scheme}, +@var{flags} and @var{opts}. If @var{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 @var{io_cipher}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_decrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_cipher}, gcry_ac_io_t *@var{io_message}) +Decrypts the cipher text readable from @var{io_cipher} through +@var{handle} with the secret key @var{key} according to @var{scheme}, +@var{flags} and @var{opts}. If @var{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 @var{io_message}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_sign_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_signature}) +Signs the message readable from @var{io_message} through @var{handle} +with the secret key @var{key} according to @var{scheme}, @var{flags} +and @var{opts}. If @var{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 @var{io_signature}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_data_verify_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_signature}) +Verifies through @var{handle} that the signature readable from +@var{io_signature} is indeed the result of signing the message +readable from @var{io_message} with the secret key belonging to the +public key @var{key} according to @var{scheme} and @var{opts}. If +@var{opts} is not NULL, it has to be an anonymous structure +(gcry_ac_ssa_*_t) specific to the chosen scheme. +@end deftypefun + +@node Handle-independent functions +@subsection Handle-independent functions + +These two functions are deprecated; do not use them for new code. + +@deftypefun gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t @var{algorithm}, const char **@var{name}) +Stores the textual representation of the algorithm whose id is given +in @var{algorithm} in @var{name}. Deprecated; use @code{gcry_pk_algo_name}. +@end deftypefun + +@deftypefun gcry_error_t gcry_ac_name_to_id (const char *@var{name}, gcry_ac_id_t *@var{algorithm}) +Stores the numeric ID of the algorithm whose textual representation is +contained in @var{name} in @var{algorithm}. Deprecated; use +@code{gcry_pk_map_name}. +@end deftypefun + +@c ********************************************************** +@c ******************* Hash Functions ********************* +@c ********************************************************** +@node Hashing +@chapter 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. +@end menu + +@node Available hash algorithms +@section Available hash algorithms + +@c begin table of hash algorithms +@cindex SHA-1 +@cindex SHA-224, SHA-256, SHA-384, SHA-512 +@cindex RIPE-MD-160 +@cindex MD2, MD4, MD5 +@cindex TIGER +@cindex HAVAL +@cindex Whirlpool +@cindex CRC32 +@table @code +@item GCRY_MD_NONE +This is not a real algorithm but used by some functions as an error +return value. This constant is guaranteed to have the value @code{0}. + +@item GCRY_MD_SHA1 +This is the SHA-1 algorithm which yields a message digest of 20 bytes. +Note that SHA-1 begins to show some weaknesses and it is suggested to +fade out its use if strong cryptographic properties are required. + +@item GCRY_MD_RMD160 +This is the 160 bit version of the RIPE message digest (RIPE-MD-160). +Like SHA-1 it also yields a digest of 20 bytes. This algorithm share a +lot of design properties with SHA-1 and thus it is advisable not to use +it for new protocols. + +@item 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. + + +@item 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. + +@item 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. + +@item GCRY_MD_TIGER +This is the TIGER/192 algorithm which yields a message digest of 24 bytes. + +@item GCRY_MD_HAVAL +This is an reserved 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. + +@item 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. + +@item GCRY_MD_SHA256 +This is the SHA-256 algorithm which yields a message digest of 32 bytes. +See FIPS 180-2 for the specification. + +@item GCRY_MD_SHA384 +This is the SHA-384 algorithm which yields a message digest of 48 bytes. +See FIPS 180-2 for the specification. + +@item GCRY_MD_SHA512 +This is the SHA-384 algorithm which yields a message digest of 64 bytes. +See FIPS 180-2 for the specification. + +@item 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. + +@item GCRY_MD_CRC32_RFC1510 +This is the above cyclic redundancy check function, as modified by RFC +1510. It yields an output of 4 bytes. Note that this is not a hash +algorithm in the cryptographic sense. + +@item 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. + +@item GCRY_MD_WHIRLPOOL +This is the Whirlpool algorithm which yields a message digest of 64 +bytes. + +@end table +@c end table of hash algorithms + +@node Hash algorithm modules +@section 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 @xref{Modules}. + +@deftp {Data type} gcry_md_spec_t +This is the `module specification structure' needed for registering +message digest modules, which has to be filled in by the user before +it can be used to register a module. It contains the following +members: + +@table @code +@item const char *name +The primary name of this algorithm. +@item unsigned char *asnoid +Array of bytes that form the ASN OID. +@item int asnlen +Length of bytes in `asnoid'. +@item gcry_md_oid_spec_t *oids +A list of OIDs that are to be associated with the algorithm. The +list's last element must have it's `oid' member set to NULL. See +below for an explanation of this type. See below for an explanation +of this type. +@item int mdlen +Length of the message digest algorithm. See below for an explanation +of this type. +@item gcry_md_init_t init +The function responsible for initializing a handle. See below for an +explanation of this type. +@item gcry_md_write_t write +The function responsible for writing data into a message digest +context. See below for an explanation of this type. +@item gcry_md_final_t final +The function responsible for `finalizing' a message digest context. +See below for an explanation of this type. +@item gcry_md_read_t read +The function responsible for reading out a message digest result. See +below for an explanation of this type. +@item size_t contextsize +The size of the algorithm-specific `context', that should be +allocated for each handle. +@end table +@end deftp + +@deftp {Data type} gcry_md_oid_spec_t +This type is used for associating a user-provided algorithm +implementation with certain OIDs. It contains the following members: + +@table @code +@item const char *oidstring +Textual representation of the OID. +@end table +@end deftp + +@deftp {Data type} gcry_md_init_t +Type for the `init' function, defined as: void (*gcry_md_init_t) (void +*c) +@end deftp + +@deftp {Data type} gcry_md_write_t +Type for the `write' function, defined as: void (*gcry_md_write_t) +(void *c, unsigned char *buf, size_t nbytes) +@end deftp + +@deftp {Data type} gcry_md_final_t +Type for the `final' function, defined as: void (*gcry_md_final_t) +(void *c) +@end deftp + +@deftp {Data type} gcry_md_read_t +Type for the `read' function, defined as: unsigned char +*(*gcry_md_read_t) (void *c) +@end deftp + +@deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module}) + +Register a new digest module whose specification can be found in +@var{digest}. On success, a new algorithm ID is stored in +@var{algorithm_id} and a pointer representing this module is stored +in @var{module}. +@end deftypefun + +@deftypefun void gcry_md_unregister (gcry_module_t @var{module}) +Unregister the digest identified by @var{module}, which must have been +registered with gcry_md_register. +@end deftypefun + +@deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length}) +Get a list consisting of the IDs of the loaded message digest modules. +If @var{list} is zero, write the number of loaded message digest +modules to @var{list_length} and return. If @var{list} is non-zero, +the first *@var{list_length} algorithm IDs are stored in @var{list}, +which must be of according size. In case there are less message +digests modules than *@var{list_length}, *@var{list_length} is updated +to the correct number. +@end deftypefun + +@node Working with hash algorithms +@section Working with hash algorithms + +To use most of these function it is necessary to create a context; +this is done using: + +@deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags}) + +Create a message digest object for algorithm @var{algo}. @var{flags} +may be given as an bitwise OR of constants described below. @var{algo} +may be given as @code{0} if the algorithms to use are later set using +@code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid +handle or NULL. + +For a list of supported algorithms, see @xref{Available hash +algorithms}. + +The flags allowed for @var{mode} are: + +@c begin table of hash flags +@table @code +@item GCRY_MD_FLAG_SECURE +Allocate all buffers and the resulting digest in "secure memory". Use +this is the hashed data is highly confidential. + +@item GCRY_MD_FLAG_HMAC +@cindex 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 @code{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 @xref{Working with cipher handles}. + +@end table +@c begin table of hash flags + +You may use the function @code{gcry_md_is_enabled} to later check +whether an algorithm has been enabled. + +@end deftypefun +@c end function gcry_md_open + +If you want to calculate several hash algorithms at the same time, you +have to use the following function right after the @code{gcry_md_open}: + +@deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo}) + +Add the message digest algorithm @var{algo} to the digest object +described by handle @var{h}. Duplicated enabling of algorithms is +detected and ignored. +@end deftypefun + +If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must +be set using the function: + +@deftypefun gcry_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key}, size_t @var{keylen}) + +For use with the HMAC feature, set the MAC key to the value of +@var{key} of length @var{keylen} bytes. There is no restriction on +the length of the key. +@end deftypefun + + +After you are done with the hash calculation, you should release the +resources by using: + +@deftypefun void gcry_md_close (gcry_md_hd_t @var{h}) + +Release all resources of hash context @var{h}. @var{h} should not be +used after a call to this function. A @code{NULL} passed as @var{h} is +ignored. The function also zeroises all sensitive information +associated with this handle. + + +@end deftypefun + +Often you have to do several hash operations using the same algorithm. +To avoid the overhead of creating and releasing context, a reset function +is provided: + +@deftypefun void gcry_md_reset (gcry_md_hd_t @var{h}) + +Reset the current context to its initial state. This is effectively +identical to a close followed by an open and enabling all currently +active algorithms. +@end deftypefun + + +Often it is necessary to start hashing some data and 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: + +@deftypefun gcry_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src}) + +Create a new digest object as an exact copy of the object described by +handle @var{handle_src} and store it in @var{handle_dst}. The context +is not reset and you can continue to hash data using this context and +independently using the original context. +@end deftypefun + + +Now that we have prepared everything to calculate hashes, 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. + +@deftypefun void gcry_md_write (gcry_md_hd_t @var{h}, const void *@var{buffer}, size_t @var{length}) + +Pass @var{length} bytes of the data in @var{buffer} to the digest object +with handle @var{h} to update the digest values. This +function should be used for large blocks of data. +@end deftypefun + +@deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c}) + +Pass the byte in @var{c} to the digest object with handle @var{h} to +update the digest value. This is an efficient function, implemented as +a macro to buffer the data before an actual update. +@end deftypefun + +The semantics of the hash functions 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. + +@deftypefun void gcry_md_final (gcry_md_hd_t @var{h}) + +Finalize the message digest calculation. This is not really needed +because @code{gcry_md_read} does this implicitly. After this has been +done no further updates (by means of @code{gcry_md_write} or +@code{gcry_md_putc} are allowed. Only the first call to this function +has an effect. It is implemented as a macro. +@end deftypefun + +The way to read out the calculated message digest is by using the +function: + +@deftypefun {unsigned char *} gcry_md_read (gcry_md_hd_t @var{h}, int @var{algo}) + +@code{gcry_md_read} returns the message digest after finalizing the +calculation. This function may be used as often as required but it will +always return the same value for one handle. The returned message digest +is allocated within the message context and therefore valid until the +handle is released or reseted (using @code{gcry_md_close} or +@code{gcry_md_reset}. @var{algo} may be given as 0 to return the only +enabled message digest or it may specify one of the enabled algorithms. +The function does return @code{NULL} if the requested algorithm has not +been enabled. +@end deftypefun + +Because it is often necessary to get the message digest of one block of +memory, a fast convenience function is available for this task: + +@deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const void *@var{buffer}, size_t @var{length}); + +@code{gcry_md_hash_buffer} is a shortcut function to calculate a message +digest of a buffer. This function does not require a context and +immediately returns the message digest of the @var{length} bytes at +@var{buffer}. @var{digest} must be allocated by the caller, large +enough to hold the message digest yielded by the the specified algorithm +@var{algo}. This required size may be obtained by using the function +@code{gcry_md_get_algo_dlen}. + +Note that this function will abort the process if an unavailable +algorithm is used. +@end deftypefun + +@c *********************************** +@c ***** MD info functions *********** +@c *********************************** + +Hash algorithms are identified by internal algorithm numbers (see +@code{gcry_md_open} for a list). However, in most applications they are +used by names, so two functions are available to map between string +representations and hash algorithm identifiers. + +@deftypefun {const char *} gcry_md_algo_name (int @var{algo}) + +Map the digest algorithm id @var{algo} to a string representation of the +algorithm name. For unknown algorithms this function returns the +string @code{"?"}. This function should not be used to test for the +availability of an algorithm. +@end deftypefun + +@deftypefun int gcry_md_map_name (const char *@var{name}) + +Map the algorithm with @var{name} to a digest algorithm identifier. +Returns 0 if the algorithm name is not known. Names representing +@acronym{ASN.1} object identifiers are recognized if the @acronym{IETF} +dotted format is used and the OID is prefixed with either "@code{oid.}" +or "@code{OID.}". For a list of supported OIDs, see the source code at +@file{cipher/md.c}. This function should not be used to test for the +availability of an algorithm. +@end deftypefun + +@deftypefun gcry_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length}) + +Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the +user allocated @var{buffer}. @var{length} must point to variable with +the available size of @var{buffer} and receives after return the +actual size of the returned OID. The returned error code may be +@code{GPG_ERR_TOO_SHORT} if the provided buffer is to short to receive +the OID; it is possible to call the function with @code{NULL} for +@var{buffer} to have it only return the required size. The function +returns 0 on success. + +@end deftypefun + + +To test whether an algorithm is actually available for use, the +following macro should be used: + +@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo}) + +The macro returns 0 if the algorithm @var{algo} is available for use. +@end deftypefun + +If the length of a message digest is not known, it can be retrieved +using the following function: + +@deftypefun {unsigned int} gcry_md_get_algo_dlen (int @var{algo}) + +Retrieve the length in bytes of the digest yielded by algorithm +@var{algo}. This is often used prior to @code{gcry_md_read} to allocate +sufficient memory for the digest. +@end deftypefun + + +In some situations it might be hard to remember the algorithm used for +the ongoing hashing. The following function might be used to get that +information: + +@deftypefun int gcry_md_get_algo (gcry_md_hd_t @var{h}) + +Retrieve the algorithm used with the handle @var{h}. Note that this +does not work reliable if more than one algorithm is enabled in @var{h}. +@end deftypefun + +The following macro might also be useful: + +@deftypefun int gcry_md_is_secure (gcry_md_hd_t @var{h}) + +This function returns true when the digest object @var{h} is allocated +in "secure memory"; i.e. @var{h} was created with the +@code{GCRY_MD_FLAG_SECURE}. +@end deftypefun + +@deftypefun int gcry_md_is_enabled (gcry_md_hd_t @var{h}, int @var{algo}) + +This function returns true when the algorithm @var{algo} has been +enabled for the digest object @var{h}. +@end deftypefun + + + +Tracking bugs related to hashing is often a cumbersome task which +requires to add a lot of printf statements into the code. +Libgcrypt provides an easy way to avoid this. The actual data +hashed can be written to files on request. + +@deftypefun void gcry_md_debug (gcry_md_hd_t @var{h}, const char *@var{suffix}) + +Enable debugging for the digest object with handle @var{h}. This +creates create files named @file{dbgmd-<n>.<string>} while doing the +actual hashing. @var{suffix} is the string part in the filename. The +number is a counter incremented for each new hashing. The data in the +file is the raw data as passed to @code{gcry_md_write} or +@code{gcry_md_putc}. If @code{NULL} is used for @var{suffix}, the +debugging is stopped and the file closed. This is only rarely required +because @code{gcry_md_close} implicitly stops debugging. +@end deftypefun + + +The following two deprecated macros are used for debugging by old code. +They shopuld be replaced by @code{gcry_md_debug}. + +@deftypefun void gcry_md_start_debug (gcry_md_hd_t @var{h}, const char *@var{suffix}) + +Enable debugging for the digest object with handle @var{h}. This +creates create files named @file{dbgmd-<n>.<string>} while doing the +actual hashing. @var{suffix} is the string part in the filename. The +number is a counter incremented for each new hashing. The data in the +file is the raw data as passed to @code{gcry_md_write} or +@code{gcry_md_putc}. +@end deftypefun + + +@deftypefun void gcry_md_stop_debug (gcry_md_hd_t @var{h}, int @var{reserved}) + +Stop debugging on handle @var{h}. @var{reserved} should be specified as +0. This function is usually not required because @code{gcry_md_close} +does implicitly stop debugging. +@end deftypefun + + +@c ********************************************************** +@c ******************* Random ***************************** +@c ********************************************************** +@node Random Numbers +@chapter Random Numbers + +@menu +* Quality of random numbers:: Libgcrypt uses different quality levels. +* Retrieving random numbers:: How to retrieve random numbers. +@end menu + +@node Quality of random numbers +@section Quality of random numbers + +@acronym{Libgcypt} offers random numbers of different quality levels: + +@deftp {Data type} gcry_random_level_t +The constants for the random quality levels are of this enum type. +@end deftp + +@table @code +@item GCRY_WEAK_RANDOM +For all functions, except for @code{gcry_mpi_randomize}, this level maps +to GCRY_STRONG_RANDOM. If you do not want this, consider using +@code{gcry_create_nonce}. +@item GCRY_STRONG_RANDOM +Use this level for session keys and similar purposes. +@item GCRY_VERY_STRONG_RANDOM +Use this level for long term key material. +@end table + +@node Retrieving random numbers +@section Retrieving random numbers + +@deftypefun void gcry_randomize (unsigned char *@var{buffer}, size_t @var{length}, enum gcry_random_level @var{level}) + +Fill @var{buffer} with @var{length} random bytes using a random quality +as defined by @var{level}. +@end deftypefun + +@deftypefun {void *} gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level}) + +Convenience function to allocate a memory block consisting of +@var{nbytes} fresh random bytes using a random quality as defined by +@var{level}. +@end deftypefun + +@deftypefun {void *} gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level}) + +Convenience function to allocate a memory block consisting of +@var{nbytes} fresh random bytes using a random quality as defined by +@var{level}. This function differs from @code{gcry_random_bytes} in +that the returned buffer is allocated in a ``secure'' area of the +memory. +@end deftypefun + +@deftypefun void gcry_create_nonce (unsigned char *@var{buffer}, size_t @var{length}) + +Fill @var{buffer} with @var{length} unpredictable bytes. This is +commonly called a nonce and may also be used for initialization +vectors and padding. This is an extra function nearly independent of +the other random function for 3 reasons: It better protects the +regular random generator's internal state, provides better performance +and does not drain the precious entropy pool. + +@end deftypefun + + + +@c ********************************************************** +@c ******************* S-Expressions *********************** +@c ********************************************************** +@node S-expressions +@chapter S-expressions + +S-expressions are used by the public key functions to pass complex data +structures around. These LISP like objects are used by some +cryptographic protocols (cf. RFC-2692) and Libgcrypt provides functions +to parse and construct them. For detailed information, see +@cite{Ron Rivest, code and description of S-expressions, +@uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}. + +@menu +* Data types for S-expressions:: Data types related with S-expressions. +* Working with S-expressions:: How to work with S-expressions. +@end menu + +@node Data types for S-expressions +@section Data types for S-expressions + +@deftp {Data type} gcry_sexp_t +The @code{gcry_sexp_t} type describes an object with the Libgcrypt internal +representation of an S-expression. +@end deftp + +@node Working with S-expressions +@section Working with S-expressions + +@noindent +There are several functions to create an Libgcrypt S-expression object +from its external representation or from a string template. There is +also a function to convert the internal representation back into one of +the external formats: + + +@deftypefun gcry_error_t gcry_sexp_new (@w{gcry_sexp_t *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}) + +This is the generic function to create an new S-expression object from +its external representation in @var{buffer} of @var{length} bytes. On +success the result is stored at the address given by @var{r_sexp}. +With @var{autodetect} set to 0, the data in @var{buffer} is expected to +be in canonized format, with @var{autodetect} set to 1 the parses any of +the defined external formats. If @var{buffer} does not hold a valid +S-expression an error code is returned and @var{r_sexp} set to +@code{NULL}. +Note that the caller is responsible for releasing the newly allocated +S-expression using @code{gcry_sexp_release}. +@end deftypefun + +@deftypefun gcry_error_t gcry_sexp_create (@w{gcry_sexp_t *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)}) + +This function is identical to @code{gcry_sexp_new} but has an extra +argument @var{freefnc}, which, when not set to @code{NULL}, is expected +to be a function to release the @var{buffer}; most likely the standard +@code{free} function is used for this argument. This has the effect of +transferring the ownership of @var{buffer} to the created object in +@var{r_sexp}. The advantage of using this function is that Libgcrypt +might decide to directly use the provided buffer and thus avoid extra +copying. +@end deftypefun + +@deftypefun gcry_error_t gcry_sexp_sscan (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}}) + +This is another variant of the above functions. It behaves nearly +identical but provides an @var{erroff} argument which will receive the +offset into the buffer where the parsing stopped on error. +@end deftypefun + +@deftypefun gcry_error_t gcry_sexp_build (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...}) + +This function creates an internal S-expression from the string template +@var{format} and stores it at the address of @var{r_sexp}. If there is a +parsing error, the function returns an appropriate error code and stores +the offset into @var{format} where the parsing stopped in @var{erroff}. +The function supports a couple of printf-like formatting characters and +expects arguments for some of these escape sequences right after +@var{format}. The following format characters are defined: + +@table @samp +@item %m +The next argument is expected to be of type @code{gcry_mpi_t} and a copy of +its value is inserted into the resulting S-expression. +@item %s +The next argument is expected to be of type @code{char *} and that +string is inserted into the resulting S-expression. +@item %d +The next argument is expected to be of type @code{int} and its value is +inserted into the resulting S-expression. +@item %b +The next argument is expected to be of type @code{int} directly +followed by an argument of type @code{char *}. This represents a +buffer of given length to be inserted into the resulting S-expression. +@item %S +The next argument is expected to be of type @code{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. + +@end table + +@noindent +No other format characters are defined and would return an error. Note +that the format character @samp{%%} does not exists, because a percent +sign is not a valid character in an S-expression. +@end deftypefun + +@deftypefun void gcry_sexp_release (@w{gcry_sexp_t @var{sexp}}) + +Release the S-expression object @var{sexp}. 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. +@end deftypefun + + +@noindent +The next 2 functions are used to convert the internal representation +back into a regular external S-expression format and to show the +structure for debugging. + +@deftypefun size_t gcry_sexp_sprint (@w{gcry_sexp_t @var{sexp}}, @w{int @var{mode}}, @w{char *@var{buffer}}, @w{size_t @var{maxlength}}) + +Copies the S-expression object @var{sexp} into @var{buffer} using the +format specified in @var{mode}. @var{maxlength} must be set to the +allocated length of @var{buffer}. The function returns the actual +length of valid bytes put into @var{buffer} or 0 if the provided buffer +is too short. Passing @code{NULL} for @var{buffer} returns the required +length for @var{buffer}. For convenience reasons an extra byte with +value 0 is appended to the buffer. + +@noindent +The following formats are supported: + +@table @code +@item GCRYSEXP_FMT_DEFAULT +Returns a convenient external S-expression representation. + +@item GCRYSEXP_FMT_CANON +Return the S-expression in canonical format. + +@item GCRYSEXP_FMT_BASE64 +Not currently supported. + +@item GCRYSEXP_FMT_ADVANCED +Returns the S-expression in advanced format. +@end table +@end deftypefun + +@deftypefun void gcry_sexp_dump (@w{gcry_sexp_t @var{sexp}}) + +Dumps @var{sexp} in a format suitable for debugging to Libgcrypt's +logging stream. +@end deftypefun + +@noindent +Often canonical encoding is used in the external representation. The +following function can be used to check for valid encoding and to learn +the length of the S-expression" + +@deftypefun size_t gcry_sexp_canon_len (@w{const unsigned char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{erroff}}, @w{int *@var{errcode}}) + +Scan the canonical encoded @var{buffer} with implicit length values and +return the actual length this S-expression uses. For a valid S-expression +it should never return 0. If @var{length} is not 0, the maximum +length to scan is given; this can be used for syntax checks of +data passed from outside. @var{errcode} and @var{erroff} may both be +passed as @code{NULL}. + +@end deftypefun + + +@noindent +There are functions to parse S-expressions and retrieve elements: + +@deftypefun gcry_sexp_t gcry_sexp_find_token (@w{const gcry_sexp_t @var{list}}, @w{const char *@var{token}}, @w{size_t @var{toklen}}) + +Scan the S-expression for a sublist with a type (the car of the list) +matching the string @var{token}. If @var{toklen} is not 0, the token is +assumed to be raw memory of this length. The function returns a newly +allocated S-expression consisting of the found sublist or @code{NULL} +when not found. +@end deftypefun + + +@deftypefun int gcry_sexp_length (@w{const gcry_sexp_t @var{list}}) + +Return the length of the @var{list}. For a valid S-expression this +should be at least 1. +@end deftypefun + + +@deftypefun gcry_sexp_t gcry_sexp_nth (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}}) + +Create and return a new S-expression from the element with index @var{number} in +@var{list}. Note that the first element has the index 0. If there is +no such element, @code{NULL} is returned. +@end deftypefun + +@deftypefun gcry_sexp_t gcry_sexp_car (@w{const gcry_sexp_t @var{list}}) + +Create and return a new S-expression from the first element in +@var{list}; this called the "type" and should always exist and be a +string. @code{NULL} is returned in case of a problem. +@end deftypefun + +@deftypefun gcry_sexp_t gcry_sexp_cdr (@w{const gcry_sexp_t @var{list}}) + +Create and return a new list form all elements except for the first one. +Note that this function may return an invalid S-expression because it +is not guaranteed, that the type exists and is a string. However, for +parsing a complex S-expression it might be useful for intermediate +lists. Returns @code{NULL} on error. +@end deftypefun + + +@deftypefun {const char *} gcry_sexp_nth_data (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{size_t *@var{datalen}}) + +This function is used to get data from a @var{list}. A pointer to the +actual data with index @var{number} is returned and the length of this +data will be stored to @var{datalen}. If there is no data at the given +index or the index represents another list, @code{NULL} is returned. +@strong{Caution:} The returned pointer is valid as long as @var{list} is +not modified or released. + +@noindent +Here is an example on how to extract and print the surname (Meier) from +the S-expression @samp{(Name Otto Meier (address Burgplatz 3))}: + +@example +size_t len; +const char *name; + +name = gcry_sexp_nth_data (list, 2, &len); +printf ("my name is %.*s\n", (int)len, name); +@end example +@end deftypefun + +@deftypefun {char *} gcry_sexp_nth_string (@w{gcry_sexp_t @var{list}}, @w{int @var{number}}) + +This function is used to get and convert data from a @var{list}. The +data is assumed to be a Nul terminated string. The caller must +release this returned value using @code{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, @code{NULL} is returned. +@end deftypefun + +@deftypefun gcry_mpi_t gcry_sexp_nth_mpi (@w{gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{int @var{mpifmt}}) + +This function is used to get and convert data from a @var{list}. This +data is assumed to be an MPI stored in the format described by +@var{mpifmt} and returned as a standard Libgcrypt MPI. The caller must +release this returned value using @code{gcry_mpi_release}. If there is +no data at the given index, the index represents a list or the value +can't be converted to an MPI, @code{NULL} is returned. +@end deftypefun + + +@c ********************************************************** +@c ******************* MPIs ******** *********************** +@c ********************************************************** +@node MPI library +@chapter MPI library + +@menu +* Data types:: MPI related data types. +* Basic functions:: First steps with MPI numbers. +* MPI formats:: External representation of MPIs. +* Calculations:: Performing MPI calculations. +* Comparisons:: How to compare MPI values. +* Bit manipulations:: How to access single bits of MPI values. +* Miscellaneous:: Miscellaneous MPI functions. +@end menu + +Public key cryptography is based on mathematics with large numbers. To +implement the public key functions, a library for handling these large +numbers is required. Because of the general usefulness of such a +library, its interface is exposed by Libgcrypt. +In the context of Libgcrypt and in most other applications, these large +numbers are called MPIs (multi-precision-integers). + +@node Data types +@section Data types + +@deftp {Data type} {gcry_mpi_t} +This type represents an object to hold an MPI. +@end deftp + +@node Basic functions +@section Basic functions + +@noindent +To work with MPIs, storage must be allocated and released for the +numbers. This can be done with one of these functions: + +@deftypefun gcry_mpi_t gcry_mpi_new (@w{unsigned int @var{nbits}}) + +Allocate a new MPI object, initialize it to 0 and initially allocate +enough memory for a number of at least @var{nbits}. This pre-allocation is +only a small performance issue and not actually necessary because +Libgcrypt automatically re-allocates the required memory. +@end deftypefun + +@deftypefun gcry_mpi_t gcry_mpi_snew (@w{unsigned int @var{nbits}}) + +This is identical to @code{gcry_mpi_new} but allocates the MPI in the so +called "secure memory" which in turn will take care that all derived +values will also be stored in this "secure memory". Use this for highly +confidential data like private key parameters. +@end deftypefun + +@deftypefun gcry_mpi_t gcry_mpi_copy (@w{const gcry_mpi_t @var{a}}) + +Create a new MPI as the exact copy of @var{a}. +@end deftypefun + + +@deftypefun void gcry_mpi_release (@w{gcry_mpi_t @var{a}}) + +Release the MPI @var{a} and free all associated resources. Passing +@code{NULL} is allowed and ignored. When a MPI stored in the "secure +memory" is released, that memory gets wiped out immediately. +@end deftypefun + +@noindent +The simplest operations are used to assign a new value to an MPI: + +@deftypefun gcry_mpi_t gcry_mpi_set (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{u}}) + +Assign the value of @var{u} to @var{w} and return @var{w}. If +@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the +value of @var{u} and returned. +@end deftypefun + +@deftypefun gcry_mpi_t gcry_mpi_set_ui (@w{gcry_mpi_t @var{w}}, @w{unsigned long @var{u}}) + +Assign the value of @var{u} to @var{w} and return @var{w}. If +@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the +value of @var{u} and returned. This function takes an @code{unsigned +int} as type for @var{u} and thus it is only possible to set @var{w} to +small values (usually up to the word size of the CPU). +@end deftypefun + +@deftypefun void gcry_mpi_swap (@w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}}) + +Swap the values of @var{a} and @var{b}. +@end deftypefun + +@node MPI formats +@section MPI formats + +@noindent +The following functions are used to convert between an external +representation of an MPI and the internal one of Libgcrypt. + +@deftypefun gcry_error_t gcry_mpi_scan (@w{gcry_mpi_t *@var{r_mpi}}, @w{enum gcry_mpi_format @var{format}}, @w{const unsigned char *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nscanned}}) + +Convert the external representation of an integer stored in @var{buffer} +with a length of @var{buflen} into a newly created MPI returned which +will be stored at the address of @var{r_mpi}. For certain formats the +length argument is not required and should be passed as @code{0}. After a +successful operation the variable @var{nscanned} receives the number of +bytes actually scanned unless @var{nscanned} was given as +@code{NULL}. @var{format} describes the format of the MPI as stored in +@var{buffer}: + +@table @code +@item GCRYMPI_FMT_STD +2-complement stored without a length header. + +@item GCRYMPI_FMT_PGP +As used by OpenPGP (only defined as unsigned). This is basically +@code{GCRYMPI_FMT_STD} with a 2 byte big endian length header. + +@item GCRYMPI_FMT_SSH +As used in the Secure Shell protocol. This is @code{GCRYMPI_FMT_STD} +with a 4 byte big endian header. + +@item GCRYMPI_FMT_HEX +Stored as a C style string with each byte of the MPI encoded as 2 hex +digits. When using this format, @var{buflen} must be zero. + +@item GCRYMPI_FMT_USG +Simple unsigned integer. +@end table + +@noindent +Note that all of the above formats store the integer in big-endian +format (MSB first). +@end deftypefun + + +@deftypefun gcry_error_t gcry_mpi_print (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nwritten}}, @w{const gcry_mpi_t @var{a}}) + +Convert the MPI @var{a} into an external representation described by +@var{format} (see above) and store it in the provided @var{buffer} +which has a usable length of at least the @var{buflen} bytes. If +@var{nwritten} is not NULL, it will receive the number of bytes +actually stored in @var{buffer} after a successful operation. +@end deftypefun + +@deftypefun gcry_error_t gcry_mpi_aprint (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char **@var{buffer}}, @w{size_t *@var{nbytes}}, @w{const gcry_mpi_t @var{a}}) + +Convert the MPI @var{a} into an external representation described by +@var{format} (see above) and store it in a newly allocated buffer which +address will be stored in the variable @var{buffer} points to. The +number of bytes stored in this buffer will be stored in the variable +@var{nbytes} points to, unless @var{nbytes} is @code{NULL}. +@end deftypefun + +@deftypefun void gcry_mpi_dump (@w{const gcry_mpi_t @var{a}}) + +Dump the value of @var{a} in a format suitable for debugging to +Libgcrypt's logging stream. Note that one leading space but no trailing +space or linefeed will be printed. It is okay to pass @code{NULL} for +@var{a}. +@end deftypefun + + +@node Calculations +@section Calculations + +@noindent +Basic arithmetic operations: + +@deftypefun void gcry_mpi_add (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}) + +@math{@var{w} = @var{u} + @var{v}}. +@end deftypefun + + +@deftypefun void gcry_mpi_add_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}}) + +@math{@var{w} = @var{u} + @var{v}}. Note that @var{v} is an unsigned integer. +@end deftypefun + + +@deftypefun void gcry_mpi_addm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}}) + +@math{@var{w} = @var{u} + @var{v} \bmod @var{m}}. +@end deftypefun + +@deftypefun void gcry_mpi_sub (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}) + +@math{@var{w} = @var{u} - @var{v}}. +@end deftypefun + +@deftypefun void gcry_mpi_sub_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}}) + +@math{@var{w} = @var{u} - @var{v}}. @var{v} is an unsigned integer. +@end deftypefun + +@deftypefun void gcry_mpi_subm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}}) + +@math{@var{w} = @var{u} - @var{v} \bmod @var{m}}. +@end deftypefun + +@deftypefun void gcry_mpi_mul (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}) + +@math{@var{w} = @var{u} * @var{v}}. +@end deftypefun + +@deftypefun void gcry_mpi_mul_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}}) + +@math{@var{w} = @var{u} * @var{v}}. @var{v} is an unsigned integer. +@end deftypefun + +@deftypefun void gcry_mpi_mulm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}}) + +@math{@var{w} = @var{u} * @var{v} \bmod @var{m}}. +@end deftypefun + +@deftypefun void gcry_mpi_mul_2exp (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{e}}) + +@c FIXME: I am in need for a real TeX{info} guru: +@c I don't know why TeX can grok @var{e} here. +@math{@var{w} = @var{u} * 2^e}. +@end deftypefun + +@deftypefun void gcry_mpi_div (@w{gcry_mpi_t @var{q}}, @w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}}, @w{int @var{round}}) + +@math{@var{q} = @var{dividend} / @var{divisor}}, @math{@var{r} = +@var{dividend} \bmod @var{divisor}}. @var{q} and @var{r} may be passed +as @code{NULL}. @var{round} should be negative or 0. +@end deftypefun + +@deftypefun void gcry_mpi_mod (@w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}}) + +@math{@var{r} = @var{dividend} \bmod @var{divisor}}. +@end deftypefun + +@deftypefun void gcry_mpi_powm (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{b}}, @w{const gcry_mpi_t @var{e}}, @w{const gcry_mpi_t @var{m}}) + +@c I don't know why TeX can grok @var{e} here. +@math{@var{w} = @var{b}^e \bmod @var{m}}. +@end deftypefun + +@deftypefun int gcry_mpi_gcd (@w{gcry_mpi_t @var{g}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}}) + +Set @var{g} to the greatest common divisor of @var{a} and @var{b}. +Return true if the @var{g} is 1. +@end deftypefun + +@deftypefun int gcry_mpi_invm (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{m}}) + +Set @var{x} to the multiplicative inverse of @math{@var{a} \bmod @var{m}}. +Return true if the inverse exists. +@end deftypefun + + +@node Comparisons +@section Comparisons + +@noindent +The next 2 functions are used to compare MPIs: + + +@deftypefun int gcry_mpi_cmp (@w{const gcry_mpi_t @var{u}}, @w{const gcry_mpi_t @var{v}}) + +Compare the multi-precision-integers number @var{u} and @var{v} +returning 0 for equality, a positive value for @var{u} > @var{v} and a +negative for @var{u} < @var{v}. +@end deftypefun + +@deftypefun int gcry_mpi_cmp_ui (@w{const gcry_mpi_t @var{u}}, @w{unsigned long @var{v}}) + +Compare the multi-precision-integers number @var{u} with the unsigned +integer @var{v} returning 0 for equality, a positive value for @var{u} > +@var{v} and a negative for @var{u} < @var{v}. +@end deftypefun + + +@node Bit manipulations +@section Bit manipulations + +@noindent +There are a couple of functions to get information on arbitrary bits +in an MPI and to set or clear them: + +@deftypefun {unsigned int} gcry_mpi_get_nbits (@w{gcry_mpi_t @var{a}}) + +Return the number of bits required to represent @var{a}. +@end deftypefun + +@deftypefun int gcry_mpi_test_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}}) + +Return true if bit number @var{n} (counting from 0) is set in @var{a}. +@end deftypefun + +@deftypefun void gcry_mpi_set_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}}) + +Set bit number @var{n} in @var{a}. +@end deftypefun + +@deftypefun void gcry_mpi_clear_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}}) + +Clear bit number @var{n} in @var{a}. +@end deftypefun + +@deftypefun void gcry_mpi_set_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}}) + +Set bit number @var{n} in @var{a} and clear all bits greater than @var{n}. +@end deftypefun + +@deftypefun void gcry_mpi_clear_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}}) + +Clear bit number @var{n} in @var{a} and all bits greater than @var{n}. +@end deftypefun + +@deftypefun void gcry_mpi_rshift (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}}) + +Shift the value of @var{a} by @var{n} bits to the right and store the +result in @var{x}. +@end deftypefun + +@deftypefun void gcry_mpi_lshift (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}}) + +Shift the value of @var{a} by @var{n} bits to the left and store the +result in @var{x}. +@end deftypefun + +@node Miscellaneous +@section Miscellaneous + +@deftypefun gcry_mpi_t gcry_mpi_set_opaque (@w{gcry_mpi_t @var{a}}, @w{void *@var{p}}, @w{unsigned int @var{nbits}}) + +Store @var{nbits} of the value @var{p} points to in @var{a} and mark +@var{a} as an opaque value (i.e. an value that can't be used for any +math calculation and is only used to store an arbitrary bit pattern in +@var{a}). + +WARNING: Never use an opaque MPI for actual math operations. The only +valid functions are gcry_mpi_get_opaque and gcry_mpi_release. Use +gcry_mpi_scan to convert a string of arbitrary bytes into an MPI. + +@end deftypefun + +@deftypefun {void *} gcry_mpi_get_opaque (@w{gcry_mpi_t @var{a}}, @w{unsigned int *@var{nbits}}) + +Return a pointer to an opaque value stored in @var{a} and return its +size in @var{nbits}. Note that the returned pointer is still owned by +@var{a} and that the function should never be used for an non-opaque +MPI. +@end deftypefun + +@deftypefun void gcry_mpi_set_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}}) + +Set the @var{flag} for the MPI @var{a}. Currently only the flag +@code{GCRYMPI_FLAG_SECURE} is allowed to convert @var{a} into an MPI +stored in "secure memory". +@end deftypefun + +@deftypefun void gcry_mpi_clear_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}}) + +Clear @var{flag} for the multi-precision-integers @var{a}. Note that +this function is currently useless as no flags are allowed. +@end deftypefun + +@deftypefun int gcry_mpi_get_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}}) + +Return true when the @var{flag} is set for @var{a}. +@end deftypefun + +@deftypefun void gcry_mpi_randomize (@w{gcry_mpi_t @var{w}}, @w{unsigned int @var{nbits}}, @w{enum gcry_random_level @var{level}}) + +Set the multi-precision-integers @var{w} to a random value of +@var{nbits}, using random data quality of level @var{level}. In case +@var{nbits} is not a multiple of a byte, @var{nbits} is rounded up to +the next byte boundary. When using a @var{level} of +@code{GCRY_WEAK_RANDOM} this function makes use of +@code{gcry_create_nonce}. +@end deftypefun + +@c ********************************************************** +@c ******************** Prime numbers *********************** +@c ********************************************************** +@node Prime numbers +@chapter Prime numbers + +@menu +* Generation:: Generation of new prime numbers. +* Checking:: Checking if a given number is prime. +@end menu + +@node Generation +@section Generation + +@deftypefun gcry_error_t gcry_prime_generate (gcry_mpi_t *@var{prime},unsigned int @var{prime_bits}, unsigned int @var{factor_bits}, gcry_mpi_t **@var{factors}, gcry_prime_check_func_t @var{cb_func}, void *@var{cb_arg}, gcry_random_level_t @var{random_level}, unsigned int @var{flags}) + +Generate a new prime number of @var{prime_bits} bits and store it in +@var{prime}. If @var{factor_bits} is non-zero, one of the prime factors +of (@var{prime} - 1) / 2 must be @var{factor_bits} bits long. If +@var{factors} is non-zero, allocate a new, @code{NULL}-terminated array +holding the prime factors and store it in @var{factors}. @var{flags} +might be used to influence the prime number generation process. +@end deftypefun + +@deftypefun gcry_error_t gcry_prime_group_generator (gcry_mpi_t *@var{r_g}, gcry_mpi_t @var{prime}, gcry_mpi_t *@var{factors}, gcry_mpi_t @var{start_g}) + +Find a generator for @var{prime} where the factorization of +(@var{prime}-1) is in the @code{NULL} terminated array @var{factors}. +Return the generator as a newly allocated MPI in @var{r_g}. If +@var{start_g} is not NULL, use this as the start for the search. +@end deftypefun + +@deftypefun void gcry_prime_release_factors (gcry_mpi_t *@var{factors}) + +Convenience function to release the @var{factors} array. +@end deftypefun + +@node Checking +@section Checking + +@deftypefun gcry_error_t gcry_prime_check (gcry_mpi_t @var{p}, unsigned int @var{flags}) + +Check wether the number @var{p} is prime. Returns zero in case @var{p} +is indeed a prime, returns @code{GPG_ERR_NO_PRIME} in case @var{p} is +not a prime and a different error code in case something went horribly +wrong. +@end deftypefun + +@c ********************************************************** +@c ******************** Utilities *************************** +@c ********************************************************** +@node Utilities +@chapter Utilities + +@menu +* Memory allocation:: Functions related with memory allocation. +@end menu + +@node Memory allocation +@section Memory allocation + +@deftypefun {void *} gcry_malloc (size_t @var{n}) + +This function tries to allocate @var{n} bytes of memory. On success +it returns a pointer to the memory area, in an out-of-core condition, +it returns NULL. +@end deftypefun + +@deftypefun {void *} gcry_malloc_secure (size_t @var{n}) +Like @code{gcry_malloc}, but uses secure memory. +@end deftypefun + +@deftypefun {void *} gcry_calloc (size_t @var{n}, size_t @var{m}) + +This function allocates a cleared block of memory (i.e. initialized with +zero bytes) long enough to contain a vector of @var{n} elements, each of +size @var{m} bytes. On success it returns a pointer to the memory +block; in an out-of-core condition, it returns NULL. +@end deftypefun + +@deftypefun {void *} gcry_calloc_secure (size_t @var{n}, size_t @var{m}) +Like @code{gcry_calloc}, but uses secure memory. +@end deftypefun + +@deftypefun {void *} gcry_realloc (void *@var{p}, size_t @var{n}) + +This function tries to resize the memory area pointed to by @var{p} to +@var{n} bytes. On success it returns a pointer to the new memory +area, in an out-of-core condition, it returns NULL. Depending on +whether the memory pointed to by @var{p} is secure memory or not, +gcry_realloc tries to use secure memory as well. +@end deftypefun + +@deftypefun void gcry_free (void *@var{p}) +Release the memory area pointed to by @var{p}. +@end deftypefun + +@c ********************************************************** +@c ***************** Architecure Overview ***************** +@c ********************************************************** +@node Architecture +@chapter 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 @code{./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 +(@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 +@file{INSTALL} and @file{README} in the source distribution on how to do +this. + +Libgcrypt is developed using a Subversion@footnote{A version control +system available for many platforms} 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 @indicateurl{ftp://ftp.gnupg.org/gcrypt/libgcrypt/}. +Announcements of new releases are posted to the +@indicateurl{gnupg-announce@@gnupg.org} mailing list@footnote{See +@url{http://www.gnupg.org/documentation/mailing-lists.en.html} for +details.}. + + +@float Figure,fig:subsystems +@caption{Libgcrypt subsystems} +@center @image{libgcrypt-modules, 150mm,,Libgcrypt subsystems} +@end float + +Libgcrypt consists of several subsystems (@pxref{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. +@c * Helper Subsystems Architecture:: About other stuff. +@end menu + + + +@node Public-Key Subsystem Architecture +@section Public-Key Architecture + +Libgcrypt implements two interfaces for public key cryptography: The +standard interface is PK interface using functions in the +@code{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. +@c see @xref{S-expression Subsystem Architecture}. + +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: + +@table @code + +@item gcry_pk_encrypt +Encrypt data using a public key. + +@item gcry_pk_decrypt +Decrypt data using a private key. + +@item gcry_pk_sign +Sign data using a private key. + +@item gcry_pk_verify +Verify that a signature matches the data. + +@item gcry_pk_testkey +Perform a consistency over a public or private key. + +@item gcry_pk_genkey +Create a new public/private key pair. + +@end table + +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 (@file{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 +(@file{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 @math{y = x r^{e} \bmod n} +is decrypted and the unblinded value @math{x' = y' r^{-1} \bmod n} +returned. The blinding value @math{r} is a random value with the size +of the modulus @math{n} and generated with @code{GCRY_WEAK_RANDOM} +random level. + +@cindex X9.31 +@cindex FIPS 186 +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. + + + +@node Symmetric Encryption Subsystem Architecture +@section Symmetric Encryption Subsystem Architecture + +The interface to work with symmetric encryption algorithms is made up +of functions from the @code{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 +(@file{cipher/cipher.c}) implements the modes and calls the core +algorithm functions to process each block. + +The most important functions are: + +@table @code + +@item gcry_cipher_open +Create a new instance to encrypt or decrypt using a specified +algorithm and mode. + +@item gcry_cipher_close +Release an instance. + +@item gcry_cipher_setkey +Set a key to be used for encryption or decryption. + +@item gcry_cipher_setiv +Set an initialization vector to be used for encryption or decryption. + +@item gcry_cipher_encrypt +@itemx 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. + +@end table + +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. + + + +@node Hashing and MACing Subsystem Architecture +@section Hashing and MACing Subsystem Architecture + +The interface to work with message digests and CRC algorithms is made +up of functions from the @code{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: + +@table @code +@item 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. + +@item gcry_md_enable +Enable an additional algorithm for the instance. + +@item gcry_md_setkey +Set the key for the MAC. + +@item gcry_md_write +Pass more data for computing the message digest to an instance. + +@item gcry_md_putc +Buffered version of @code{gcry_md_write} implemented as a macro. + +@item gcry_md_read +Finalize the computation of the message digest or HMAC and return the +result. + +@item gcry_md_close +Release an instance + +@item gcry_md_hash_buffer +Convenience function to directly compute a message digest over a +memory buffer without the need to create an instance first. + +@end table + +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. + + + +@node Multi-Precision-Integer Subsystem Architecture +@section 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. + +@noindent +Major features of Libgcrypt's multi-precision-integer code compared to +GMP are: + +@itemize +@item +Avoidance of stack based allocations to allow protection against +swapping out of sensitive data and for easy zeroing of sensitive +intermediate results. + +@item +Optional use of secure memory and tracking of its use so that results +are also put into secure memory. + +@item +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. + +@item +Removal of unnecessary code to reduce complexity. + +@item +Functions specialized for public key cryptography. + +@end itemize + + + +@node Prime-Number-Generator Subsystem Architecture +@section 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.@footnote{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.} +This algorithm creates a pool of smaller primes, select a few of them +to create candidate primes of the form @math{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 @code{save_pool_prime} and +@code{get_pool_prime} in @file{cipher/primegen.c}). The prime +generator optionally supports the finding of an appropriate generator. + +@noindent +The primality test works in three steps: + +@enumerate +@item +The standard sieve algorithm using the primes up to 4999 is used as a +quick first check. + +@item +A Fermat test filters out almost all non-primes. + +@item +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. + +@end enumerate + +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: @code{_gcry_derive_x931_prime} and +@code{_gcry_generate_fips186_2_prime}. These functions are internal +and not available through the public API. + + + +@node Random-Number Subsystem Architecture +@section Random-Number Subsystem Architecture + +Libgcrypt provides 3 levels or random quality: The level +@code{GCRY_VERY_STRONG_RANDOM} usually used for key generation, the +level @code{GCRY_STRONG_RANDOM} for all other strong random +requirements and the function @code{gcry_create_nonce} which is used +for weaker usages like nonces. There is also a level +@code{GCRY_WEAK_RANDOM} which in general maps to +@code{GCRY_STRONG_RANDOM} except when used with the function +@code{gcry_mpi_randomize}, where it randomizes an +multi-precision-integer using the @code{gcry_create_nonce} function. + +@noindent +There are two distinct random generators available: + +@itemize +@item +The Continuously Seeded Pseudo Random Number Generator (CSPRNG), which +is based on the classic GnuPG derived big pool implementation. +Implemented in @code{random/random-csprng.c} and used by default. +@item +A FIPS approved ANSI X9.31 PRNG using AES with a 128 bit key. Implemented in +@code{random/random-fips.c} and used if Libgcrypt is in FIPS mode. +@end itemize + +@noindent +Both generators make use of so-called entropy gathering modules: + +@table @asis +@item rndlinux +Uses the operating system provided +@file{/dev/random} and @file{/dev/urandom} devices. + +@item 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 @code{/dev/random} implementation. It is not available in +FIPS mode. + +@item 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. + +@item rndw32 +Targeted for the Microsoft Windows OS. It uses certain properties of +that system and is the only gathering module available for that OS. + +@item 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. + +@end table + + +@menu +* CSPRNG Description:: Description of the CSPRNG. +* FIPS PRNG Description:: Description of the FIPS X9.31 PRNG. +@end menu + + +@node CSPRNG Description +@subsection 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".@footnote{Also described in chapter +6 of his book "Cryptographic Security Architecture", New York, 2004, +ISBN 0-387-95387-6.} + +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. + +@c FIXME: The design and implementaion needs a more verbose description. + +The implementation of the nonce generator (for +@code{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 @code{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. + + +@node FIPS PRNG Description +@subsection 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 @code{GCRY_VERY_STRONG_RANDOM} and +@code{GCRY_STRONG_RANDOM} generators are keyed and seeded using the +rndlinux module with the @file{/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 @code{gcry_create_nonce} is keyed and seeded +from the @code{GCRY_STRONG_RANDOM} generator. Thus is may also block +if the @code{GCRY_STRONG_RANDOM} generator has not yet been used +before and thus gets initialized on the first use by +@code{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. + +@c @node Helper Subsystems Architecture +@c @section Helper Subsystems Architecture +@c +@c There are a few smaller subsystems which are mainly used internally by +@c Libgcrypt but also available to applications. +@c +@c @menu +@c * S-expression Subsystem Architecture:: Details about the S-expression architecture. +@c * Memory Subsystem Architecture:: Details about the memory allocation architecture. +@c * Miscellaneous Subsystems Architecture:: Details about other subsystems. +@c @end menu +@c +@c @node S-expression Subsystem Architecture +@c @subsection S-expression Subsystem Architecture +@c +@c Libgcrypt provides an interface to S-expression to create and parse +@c them. To use an S-expression with Libgcrypt it needs first be +@c converted into the internal representation used by Libgcrypt (the type +@c @code{gcry_sexp_t}). The conversion functions support a large subset +@c of the S-expression specification and further fature a printf like +@c function to convert a list of big integers or other binary data into +@c an S-expression. +@c +@c Libgcrypt currently implements S-expressions using a tagged linked +@c list. However this is not exposed to an application and may be +@c changed in future releases to reduce overhead when already working +@c with canonically encoded S-expressions. Secure memory is supported by +@c this S-expressions implementation. +@c +@c @node Memory Subsystem Architecture +@c @subsection Memory Subsystem Architecture +@c +@c TBD. +@c +@c +@c @node Miscellaneous Subsystems Architecture +@c @subsection Miscellaneous Subsystems Architecture +@c +@c TBD. +@c +@c + + + +@c ********************************************************** +@c ******************* Appendices ************************* +@c ********************************************************** + +@c ******************************************** +@node Self-Tests +@appendix 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 @code{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. + +@c -------------------------------- +@section Power-Up Tests + +Power-up tests are only performed if Libgcrypt is in FIPS mode. + +@subsection Symmetric Cipher Algorithm Power-Up Tests + +The following symmetric encryption algorithm tests are run during +power-up: + +@table @asis +@item 3DES +To test the 3DES 3-key EDE encryption in ECB mode these tests are +run: +@enumerate +@item +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. +@item +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. +@item +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. +@end enumerate +(@code{cipher/des.c:selftest}) + +@item AES-128 +A known answer tests is run using one test vector and one test +key with AES in ECB mode. (@code{cipher/rijndael.c:selftest_basic_128}) + +@item AES-192 +A known answer tests is run using one test vector and one test +key with AES in ECB mode. (@code{cipher/rijndael.c:selftest_basic_192}) + +@item AES-256 +A known answer tests is run using one test vector and one test key +with AES in ECB mode. (@code{cipher/rijndael.c:selftest_basic_256}) +@end table + +@subsection Hash Algorithm Power-Up Tests + +The following hash algorithm tests are run during power-up: + +@table @asis +@item SHA-1 +A known answer test using the string @code{"abc"} is run. +(@code{cipher/@/sha1.c:@/selftests_sha1}) +@item SHA-224 +A known answer test using the string @code{"abc"} is run. +(@code{cipher/@/sha256.c:@/selftests_sha224}) +@item SHA-256 +A known answer test using the string @code{"abc"} is run. +(@code{cipher/@/sha256.c:@/selftests_sha256}) +@item SHA-384 +A known answer test using the string @code{"abc"} is run. +(@code{cipher/@/sha512.c:@/selftests_sha384}) +@item SHA-512 +A known answer test using the string @code{"abc"} is run. +(@code{cipher/@/sha512.c:@/selftests_sha512}) +@end table + +@subsection MAC Algorithm Power-Up Tests + +The following MAC algorithm tests are run during power-up: + +@table @asis +@item HMAC SHA-1 +A known answer test using 9 byte of data and a 64 byte key is run. +(@code{cipher/hmac-tests.c:selftests_sha1}) +@item HMAC SHA-224 +A known answer test using 28 byte of data and a 4 byte key is run. +(@code{cipher/hmac-tests.c:selftests_sha224}) +@item HMAC SHA-256 +A known answer test using 28 byte of data and a 4 byte key is run. +(@code{cipher/hmac-tests.c:selftests_sha256}) +@item HMAC SHA-384 +A known answer test using 28 byte of data and a 4 byte key is run. +(@code{cipher/hmac-tests.c:selftests_sha384}) +@item HMAC SHA-512 +A known answer test using 28 byte of data and a 4 byte key is run. +(@code{cipher/hmac-tests.c:selftests_sha512}) +@end table + +@subsection Random Number Power-Up Test + +The DRNG is tested during power-up this way: + +@enumerate +@item +Requesting one block of random using the public interface to check +general working and the duplicated block detection. +@item +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. +@end enumerate + +@subsection Public Key Algorithm Power-Up Tests + +The public key algorithms are tested during power-up: + +@table @asis +@item RSA +A pre-defined 1024 bit RSA key is used and these tests are run +in turn: +@enumerate +@item +Conversion of S-expression to internal format. +(@code{cipher/@/rsa.c:@/selftests_rsa}) +@item +Private key consistency check. +(@code{cipher/@/rsa.c:@/selftests_rsa}) +@item +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. (@code{cipher/@/rsa.c:@/selftest_sign_1024}) +@item +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. +(@code{cipher/@/rsa.c:@/selftest_encr_1024}) +@end enumerate + +@item DSA +A pre-defined 1024 bit DSA key is used and these tests are run in turn: +@enumerate +@item +Conversion of S-expression to internal format. +(@code{cipher/@/dsa.c:@/selftests_dsa}) +@item +Private key consistency check. +(@code{cipher/@/dsa.c:@/selftests_dsa}) +@item +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. +(@code{cipher/@/dsa.c:@/selftest_sign_1024}) +@end enumerate +@end table + +@subsection 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 +@file{.hmac}. + + +@subsection 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. +(@code{cipher/@/des.c:@/selftest}) + + + +@c -------------------------------- +@section 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. + +@subsection 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. + +@table @asis +@item 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. +(@code{cipher/@/rsa.c:@/test_keys}) +@item 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. (@code{cipher/@/dsa.c:@/test_keys}) +@end table + + +@subsection Software Load Tests + +Loading of extra modules into libgcrypt is disabled in FIPS mode and +thus no tests are +implemented. (@code{cipher/@/cipher.c:@/_gcry_cipher_register}, +@code{cipher/@/md.c:@/_gcry_md_register}, +@code{cipher/@/pubkey.c:@/_gcry_pk_register}) + + +@subsection Manual Key Entry Tests + +A manual key entry feature is not implemented in Libgcrypt. + + +@subsection 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. +(@code{random/@/random-fips.c:@/x931_aes_driver}) + + + +@c -------------------------------- +@section Application Requested Tests + +The application may requests tests at any time by means of the +@code{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. + +@subsection Symmetric Cipher Algorithm Tests + +The following symmetric encryption algorithm tests are run in addition +to the power-up tests: + +@table @asis +@item 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. + +@end table + +@subsection Hash Algorithm Tests + +The following hash algorithm tests are run in addition to the +power-up tests: + +@table @asis +@item SHA-1 +@itemx SHA-224 +@itemx SHA-256 +@enumerate +@item +A known answer test using a 56 byte string is run. +@item +A known answer test using a string of one million letters "a" is run. +@end enumerate +(@code{cipher/@/sha1.c:@/selftests_sha1}, +@code{cipher/@/sha256.c:@/selftests_sha224}, +@code{cipher/@/sha256.c:@/selftests_sha256}) +@item SHA-384 +@item SHA-512 +@enumerate +@item +A known answer test using a 112 byte string is run. +@item +A known answer test using a string of one million letters "a" is run. +@end enumerate +(@code{cipher/@/sha512.c:@/selftests_sha384}, +@code{cipher/@/sha512.c:@/selftests_sha512}) +@end table + +@subsection MAC Algorithm Tests + +The following MAC algorithm tests are run in addition to the power-up +tests: + +@table @asis +@item HMAC SHA-1 +@enumerate +@item +A known answer test using 9 byte of data and a 20 byte key is run. +@item +A known answer test using 9 byte of data and a 100 byte key is run. +@item +A known answer test using 9 byte of data and a 49 byte key is run. +@end enumerate +(@code{cipher/hmac-tests.c:selftests_sha1}) +@item HMAC SHA-224 +@itemx HMAC SHA-256 +@itemx HMAC SHA-384 +@itemx HMAC SHA-512 +@enumerate +@item +A known answer test using 9 byte of data and a 20 byte key is run. +@item +A known answer test using 50 byte of data and a 20 byte key is run. +@item +A known answer test using 50 byte of data and a 26 byte key is run. +@item +A known answer test using 54 byte of data and a 131 byte key is run. +@item +A known answer test using 152 byte of data and a 131 byte key is run. +@end enumerate +(@code{cipher/@/hmac-tests.c:@/selftests_sha224}, +@code{cipher/@/hmac-tests.c:@/selftests_sha256}, +@code{cipher/@/hmac-tests.c:@/selftests_sha384}, +@code{cipher/@/hmac-tests.c:@/selftests_sha512}) +@end table + + +@c ******************************************** +@node FIPS Mode +@appendix 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. + +@c ------------------------------- +@section Restrictions in FIPS Mode + +@noindent +If Libgcrypt is used in FIPS mode these restrictions are effective: + +@itemize +@item +The cryptographic algorithms are restricted to this list: + +@table @asis +@item GCRY_CIPHER_3DES +3 key EDE Triple-DES symmetric encryption. +@item GCRY_CIPHER_AES128 +AES 128 bit symmetric encryption. +@item GCRY_CIPHER_AES192 +AES 192 bit symmetric encryption. +@item GCRY_CIPHER_AES256 +AES 256 bit symmetric encryption. +@item GCRY_MD_SHA1 +SHA-1 message digest. +@item GCRY_MD_SHA224 +SHA-224 message digest. +@item GCRY_MD_SHA256 +SHA-256 message digest. +@item GCRY_MD_SHA384 +SHA-384 message digest. +@item GCRY_MD_SHA512 +SHA-512 message digest. +@item GCRY_MD_SHA1,GCRY_MD_FLAG_HMAC +HMAC using a SHA-1 message digest. +@item GCRY_MD_SHA224,GCRY_MD_FLAG_HMAC +HMAC using a SHA-224 message digest. +@item GCRY_MD_SHA256,GCRY_MD_FLAG_HMAC +HMAC using a SHA-256 message digest. +@item GCRY_MD_SHA384,GCRY_MD_FLAG_HMAC +HMAC using a SHA-384 message digest. +@item GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC +HMAC using a SHA-512 message digest. +@item GCRY_PK_RSA +RSA encryption and signing. +@item GCRY_PK_DSA +DSA signing. +@end table + +Note that the CRC algorithms are not considered cryptographic algorithms +and thus are in addition available. + +@item +RSA key generation refuses to create a key with a keysize of +less than 1024 bits. + +@item +DSA key generation refuses to create a key with a keysize other +than 1024 bits. + +@item +The @code{transient-key} flag for RSA and DSA key generation is ignored. + +@item +Support for the VIA Padlock engine is disabled. + +@item +FIPS mode may only be used on systems with a /dev/random device. +Switching into FIPS mode on other systems will fail at runtime. + +@item +Saving and loading a random seed file is ignored. + +@item +An X9.31 style random number generator is used in place of the +large-pool-CSPRNG generator. + +@item +The command @code{GCRYCTL_ENABLE_QUICK_RANDOM} is ignored. + +@item +The Alternative Public Key Interface (@code{gcry_ac_xxx}) is not +supported and all API calls return an error. + +@item +Registration of external modules is not supported. + +@item +Message digest debugging is disabled. + +@item +All debug output related to cryptographic data is suppressed. + +@item +On-the-fly self-tests are not performed, instead self-tests are run +before entering operational state. + +@item +The function @code{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. + +@item +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. + +@item +In Enforced FIPS mode the command @code{GCRYCTL_DISABLE_SECMEM} is +ignored. In standard FIPS mode it disables FIPS mode. + +@item +A handler set by @code{gcry_set_outofcore_handler} is ignored. +@item +A handler set by @code{gcry_set_fatalerror_handler} is ignored. + +@end itemize + +Note that when we speak about disabling FIPS mode, it merely means +that the function @code{gcry_fips_mode_active} returns false; it does +not mean that any non FIPS algorithms are allowed. + +@c ******************************************** +@section FIPS Finite State Machine + +The FIPS mode of libgcrypt implements a finite state machine (FSM) using +8 states (@pxref{tbl:fips-states}) and checks at runtime that only valid +transitions (@pxref{tbl:fips-state-transitions}) may happen. + +@float Figure,fig:fips-fsm +@caption{FIPS mode state diagram} +@center @image{fips-fsm,150mm,,FIPS FSM Diagram} +@end float + +@float Table,tbl:fips-states +@caption{FIPS mode states} +@noindent +States used by the FIPS FSM: +@table @asis + +@item 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. + +@item 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 + +@item Init +The Libgcrypt initialization functions are performed and the library has +not yet run any self-test. + +@item Self-Test +Libgcrypt is performing self-tests. + +@item Operational +Libgcrypt is in the operational state and all interfaces may be used. + +@item Error +Libgrypt is in the error state. When calling any FIPS relevant +interfaces they either return an error (@code{GPG_ERR_NOT_OPERATIONAL}) +or put Libgcrypt into the Fatal-Error state and won't return. + +@item Fatal-Error +Libgcrypt is in a non-recoverable error state and +will automatically transit into the Shutdown state. + +@item Shutdown +Libgcrypt is about to be terminated and removed from the memory. The +application may at this point still runing cleanup handlers. + +@end table +@end float + + +@float Table,tbl:fips-state-transitions +@caption{FIPS mode state transitions} +@noindent +The valid state transitions (@pxref{fig:fips-fsm}) are: +@table @code +@item 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. + +@item 2 +Power-On to Init is triggered by the application calling the +Libgcrypt intialization function @code{gcry_check_version}. + +@item 3 +Init to Self-Test is either triggred by a dedicated API call or implicit +by invoking a libgrypt service conrolled by the FSM. + +@item 4 +Self-Test to Operational is triggered after all self-tests passed +successfully. + +@item 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. + +@item 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. + +@item 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. + +@item 8 +Error to Shutdown is similar to the Operational to Shutdown transition +(5). + +@item 9 +Error to Fatal-Error is triggred if Libgrypt detects an fatal error +while already being in Error state. + +@item 10 +Fatal-Error to Shutdown is automatically entered by Libgcrypt +after having reported the error. + +@item 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. + +@item 12 +Power-On to Fatal-Error will be triggerd if certain Libgcrypt functions +are used without having reached the Init state. + +@item 13 +Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt while +running self-tests. + +@item 14 +Self-Test to Error is triggred by a failed self-test. + +@item 15 +Operational to Fatal-Error is triggered if Libcrypt encountered a +non-recoverable error. + +@item 16 +Operational to Self-Test is triggred if the application requested to run +the self-tests again. + +@item 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. + +@item 18 +Init to Error is triggered by errors in the initialization code. + +@item 19 +Init to Fatal-Error is triggered by non-recoverable errors in the +initialization code. + +@item 20 +Error to Error is triggered by errors while already in the Error +state. + + +@end table +@end float + +@c ******************************************** +@section 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 +@code{gcry_malloc_secure} and @code{gcry_calloc_secure}. By calling +@code{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 @code{GCRYCTL_TERM_SECMEM} +before process termination. This will zero out the entire secure +memory and thus also the encryption contexts with these keys. + + + +@c ********************************************************** +@c ************* Appendices (license etc.) **************** +@c ********************************************************** +@include lgpl.texi + +@include gpl.texi + +@node Figures and Tables +@unnumbered List of Figures and Tables + +@listoffloats Figure + +@listoffloats Table + +@node Concept Index +@unnumbered Concept Index + +@printindex cp + +@node Function and Data Index +@unnumbered Function and Data Index + +@printindex fn + + + +@bye + +GCRYCTL_SET_RANDOM_DAEMON_SOCKET +GCRYCTL_USE_RANDOM_DAEMON +The random damon is still a bit experimental, thus we do not document +them. Note that they should be used during initialization and that +these functions are not really thread safe. + + + + +@c LocalWords: int HD + + + + |