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, 0 insertions, 5867 deletions
diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi b/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi deleted file mode 100644 index a2993df97e..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi +++ /dev/null @@ -1,5867 +0,0 @@ -\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 - - - - |