| 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). |
| |
| [image src="libgcrypt-modules.png" alt="Libgcrypt subsystems"] |
| 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. |
| |
| [image src="fips-fsm.png" alt="FIPS FSM Diagram"] |
| 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 |
| ************* |
| |
| [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 |
| *********************** |
| |
| [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 |