/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.info
Unknown | 4698 lines | 3737 code | 961 blank | 0 comment | 0 complexity | 20c855858e53f0cbed0617a6e61e1af9 MD5 | raw file
Possible License(s): LGPL-2.1, LGPL-2.0, BSD-3-Clause, GPL-2.0
Large files files are truncated, but you can click here to view the full file
- This is gcrypt.info, produced by makeinfo version 4.7 from gcrypt.texi.
-
- This manual is for Libgcrypt (version 1.2.2, 29 July 2005), which is
- GNU's library of cryptographic building blocks.
-
- Copyright (C) 2000, 2002, 2003, 2004 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 "Copying".
-
- 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.2.2, 29 July 2005), which is
- GNU's library of cryptographic building blocks.
-
- Copyright (C) 2000, 2002, 2003, 2004 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 "Copying".
-
- * 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.
- * Hashing:: How to use hashing.
- * Public Key cryptography (I):: How to use public key cryptography.
- * Public Key cryptography (II):: How to use public key cryptography, alternatively.
- * Random Numbers:: How to work with random numbers.
- * S-expressions:: How to manage S-expressions.
- * MPI library:: How to work with multi-precision-integers.
- * Utilities:: Utility functions.
-
- Appendices
-
- * 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
-
- * Concept Index:: Index of concepts and programs.
- * Function and Data Index:: Index of functions, variables and data types.
-
- --- The Detailed Node Listing ---
-
- Introduction
- * Getting Started:: How to use this manual.
- * Features:: A glance at Libgcrypt's features.
- * Overview:: Overview about the library.
-
- Preparation
- * 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.
-
- Generalities
- * Controlling the library:: Controlling Libgcrypt's behavior.
- * Modules:: Description of extension modules.
- * Error Handling:: Error codes and such.
-
- Handler Functions
- * 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.
-
- Symmetric cryptography
- * 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.
-
- Hashing
- * 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.
-
- Public Key cryptography (I)
- * Used S-expressions:: Introduction into the used S-expression.
- * Available algorithms:: Algorithms supported by the library.
- * 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.
-
- Public Key cryptography (II)
- * Available asymmetric algorithms:: List of algorithms supported by the library.
- * Working with sets of data:: How to work with sets of data.
- * 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.
-
- Random Numbers
- * Quality of random numbers:: Libgcrypt uses different quality levels.
- * Retrieving random numbers:: How to retrieve random numbers.
-
- S-expressions
- * Data types for S-expressions:: Data types related with S-expressions.
- * Working with S-expressions:: How to work with S-expressions.
-
- MPI library
- * 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.
-
- Utilities
- * Memory allocation:: Functions related with memory allocation.
-
-
- 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 not needed on a GNU or GNU/Linux
- system) 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 extendable 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. An exception for thread-safety 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.
-
-
- 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. Furthermore `libgpg-error'
- defines functions prefixed with `gpg_' and preprocessor symbols
- prefixed with `GPG_'. Note that Libgcrypt uses libgpg-error, which
- uses `gpg_err_*' as name space for function and type names and
- `GPG_ERR_*' for other symbols, including all the error codes.
-
-
- 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
- ============================
-
- 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 is actually 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' has three purposes. It can be
- used to retrieve the version number of the library. In addition it
- can verify that the version number is higher than a certain
- required version number.
-
- In either case, the function initializes some sub-systems, and for
- this reason alone it must be invoked early in your program, before
- you make use of the other functions of Libgcrypt.
-
-
- File: gcrypt.info, Node: Multi Threading, 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).
-
- * As with the function `gpg_strerror', `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_mutex_lock, gcry_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: 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.
-
-
-
- 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 thus 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
- Libgctypt 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 occured, 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_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. 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.
-
-
- 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.
-
- -- Data type: gcry_handler_no_mem_t
- This type is defined as: `void (*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.
-
- -- 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.
-
-
- File: gcrypt.info, Node: Symmetric cryptography, Next: Hashing, 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_RIJNDAEL128'
- 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.
-
-
-
- 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
- cipher 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, may be set later using other functions. The
- value of this constant is always 0.
-
- `GCRY_CIPHER_MODE_ECB'
- Electronic Codebook mode.
-
- `GCRY_CIPHER_MODE_CFB'
- Cipher Feedback mode.
-
- `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'
- Outer 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 m…
Large files files are truncated, but you can click here to view the full file