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