/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.texi
Unknown | 3756 lines | 2904 code | 852 blank | 0 comment | 0 complexity | 24b2b163fa8a26f44910b45e9aff279d 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
- \input texinfo @c -*- Texinfo -*-
- @c %**start of header
- @setfilename gcrypt.info
- @include version.texi
- @settitle The Libgcrypt Reference Manual
- @c Unify some of the indices.
- @syncodeindex tp fn
- @syncodeindex pg fn
- @c %**end of header
- @copying
- This manual is for Libgcrypt
- (version @value{VERSION}, @value{UPDATED}),
- which is GNU's library of cryptographic building blocks.
-
- Copyright @copyright{} 2000, 2002, 2003, 2004 Free Software Foundation, Inc.
-
- @quotation
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; either version 2 of the License, or (at your
- option) any later version. The text of the license can be found in the
- section entitled ``Copying''.
- @end quotation
- @end copying
-
- @dircategory GNU Libraries
- @direntry
- * libgcrypt: (gcrypt). Cryptographic function library.
- @end direntry
-
-
-
- @c
- @c Titlepage
- @c
- @setchapternewpage odd
- @titlepage
- @title The Libgcrypt Reference Manual
- @subtitle Version @value{VERSION}
- @subtitle @value{UPDATED}
- @author Werner Koch (@email{wk@@gnupg.org})
- @author Moritz Schulte (@email{mo@@g10code.com})
-
- @page
- @vskip 0pt plus 1filll
- @insertcopying
- @end titlepage
-
-
- @summarycontents
- @contents
- @page
-
-
- @ifnottex
- @node Top
- @top The Libgcrypt Library
- @insertcopying
- @end ifnottex
-
-
- @menu
- * Introduction:: What is @acronym{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.
-
- @detailmenu
- --- The Detailed Node Listing ---
-
- Introduction
- * Getting Started:: How to use this manual.
- * Features:: A glance at @acronym{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 @acronym{Libgcrypt} can be used in a MT environment.
-
- Generalities
- * Controlling the library:: Controlling @acronym{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:: @acronym{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.
-
- @end detailmenu
-
- @end menu
-
-
-
- @c **********************************************************
- @c ******************* Introduction ***********************
- @c **********************************************************
- @node Introduction
- @chapter Introduction
- `@acronym{Libgcrypt}' is a library providing cryptographic building blocks.
-
- @menu
- * Getting Started:: How to use this manual.
- * Features:: A glance at @acronym{Libgcrypt}'s features.
- * Overview:: Overview about the library.
- @end menu
-
- @node Getting Started
- @section Getting Started
-
- This manual documents the `@acronym{Libgcrypt}' library application programming
- interface (API). All functions and data types provided by the library
- are explained.
-
- @noindent
- The reader is assumed to possess basic knowledge about applied
- cryptography.
-
- This manual can be used in several ways. If read from the beginning
- to the end, it gives a good introduction into the library and how it
- can be used in an application. Forward references are included where
- necessary. Later on, the manual can be used as a reference manual to
- get just the information needed about any particular interface of the
- library. Experienced programmers might want to start looking at the
- examples at the end of the manual, and then only read up those parts
- of the interface which are unclear.
-
-
- @node Features
- @section Features
-
- `Libgcrypt' might have a couple of advantages over other libraries doing
- a similar job.
-
- @table @asis
- @item It's Free Software
- Anybody can use, modify, and redistribute it under the terms of the GNU
- Lesser General Public License (@pxref{Library Copying}). Note, that
- some parts (which are not needed on a GNU or GNU/Linux system) are
- subject to the terms of the GNU General Public License
- (@pxref{Copying}); please see the README file of the distribution for of
- list of these parts.
-
- @item It encapsulates the low level cryptography
- `@acronym{Libgcrypt}' provides a high level interface to cryptographic building
- blocks using an extendable and flexible API.
-
- @end table
-
- @node Overview
- @section Overview
-
- @noindent
- The `@acronym{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.
-
- @acronym{Libgcrypt} depends on the library `libgpg-error', which
- contains common error handling related code for GnuPG components.
-
- @c **********************************************************
- @c ******************* Preparation ************************
- @c **********************************************************
- @node Preparation
- @chapter Preparation
-
- To use `@acronym{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 @acronym{Libgcrypt} can be used in a MT environment.
- @end menu
-
-
- @node Header
- @section 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:
-
- @example
- #include <gcrypt.h>
- @end example
-
- The name space of `@acronym{Libgcrypt}' is @code{gcry_*} for function
- and type names and @code{GCRY*} for other symbols. In addition the
- same name prefixes with one prepended underscore are reserved for
- internal use and should never be used by an application. Furthermore
- `libgpg-error' defines functions prefixed with `gpg_' and preprocessor
- symbols prefixed with `GPG_'. Note that @acronym{Libgcrypt} uses
- libgpg-error, which uses @code{gpg_err_*} as name space for function
- and type names and @code{GPG_ERR_*} for other symbols, including all
- the error codes.
-
- @node Building sources
- @section Building sources
-
- If you want to compile a source file including the `gcrypt.h' header
- file, you must make sure that the compiler can find it in the
- directory hierarchy. This is accomplished by adding the path to the
- directory in which the header file is located to the compilers include
- file search path (via the @option{-I} option).
-
- However, the path to the include file is determined at the time the
- source is configured. To solve this problem, `@acronym{Libgcrypt}' ships with a small
- helper program @command{libgcrypt-config} that knows the path to the
- include file and other configuration options. The options that need
- to be added to the compiler invocation at compile time are output by
- the @option{--cflags} option to @command{libgcrypt-config}. The following
- example shows how it can be used at the command line:
-
- @example
- gcc -c foo.c `libgcrypt-config --cflags`
- @end example
-
- Adding the output of @samp{libgcrypt-config --cflags} to the compilers
- command line will ensure that the compiler can find the `@acronym{Libgcrypt}' header
- file.
-
- A similar problem occurs when linking the program with the library.
- Again, the compiler has to find the library files. For this to work,
- the path to the library files has to be added to the library search path
- (via the @option{-L} option). For this, the option @option{--libs} to
- @command{libgcrypt-config} can be used. For convenience, this option
- also outputs all other options that are required to link the program
- with the `@acronym{Libgcrypt}' libraries (in particular, the @samp{-lgcrypt}
- option). The example shows how to link @file{foo.o} with the `@acronym{Libgcrypt}'
- library to a program @command{foo}.
-
- @example
- gcc -o foo foo.o `libgcrypt-config --libs`
- @end example
-
- Of course you can also combine both examples to a single command by
- specifying both options to @command{libgcrypt-config}:
-
- @example
- gcc -o foo foo.c `libgcrypt-config --cflags --libs`
- @end example
-
- @node Building sources using Automake
- @section Building sources using Automake
-
- It is much easier if you use GNU Automake instead of writing your own
- Makefiles. If you do that you do not have to worry about finding and
- invoking the @command{libgcrypt-config} script at all.
- @acronym{Libgcrypt} provides an extension to Automake that does all
- the work for you.
-
- @c A simple macro for optional variables.
- @macro ovar{varname}
- @r{[}@var{\varname\}@r{]}
- @end macro
- @defmac AM_PATH_LIBGCRYPT (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
- Check whether @acronym{Libgcrypt} (at least version
- @var{minimum-version}, if given) exists on the host system. If it is
- found, execute @var{action-if-found}, otherwise do
- @var{action-if-not-found}, if given.
-
- Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the
- flags needed for compilation of the program to find the
- @file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker
- flags needed to link the program to the @acronym{Libgcrypt} library.
- @end defmac
-
- You can use the defined Autoconf variables like this in your
- @file{Makefile.am}:
-
- @example
- AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
- LDADD = $(LIBGCRYPT_LIBS)
- @end example
-
- @node Initializing the library
- @section Initializing the library
-
- It is often desirable to check that the version of `@acronym{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.
-
- @deftypefun const char *gcry_check_version (const char *@var{req_version})
-
- The function @code{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 @acronym{Libgcrypt}.
- @end deftypefun
-
- @node Multi Threading
- @section Multi Threading
-
- As mentioned earlier, the `@acronym{Libgcrypt}' library is
- thread-safe if you adhere to the following requirements:
-
- @itemize @bullet
- @item
- If your application is multi-threaded, you must set the thread support
- callbacks with the @code{GCRYCTL_SET_THREAD_CBS} command
- @strong{before} any other function in the library.
-
- This is easy enough if you are indeed writing an application using
- Libgcrypt. It is rather problematic if you are writing a library
- instead. Here are some tips what to do if you are writing a library:
-
- If your library requires a certain thread package, just initialize
- Libgcrypt to use this thread package. If your library supports multiple
- thread packages, but needs to be configured, you will have to
- implement a way to determine which thread package the application
- wants to use with your library anyway. Then configure Libgcrypt to use
- this thread package.
-
- If your library is fully reentrant without any special support by a
- thread package, then you are lucky indeed. Unfortunately, this does
- not relieve you from doing either of the two above, or use a third
- option. The third option is to let the application initialize Libgcrypt
- for you. Then you are not using Libgcrypt transparently, though.
-
- As if this was not difficult enough, a conflict may arise if two
- libraries try to initialize Libgcrypt independently of each others, and
- both such libraries are then linked into the same application. To
- make it a bit simpler for you, this will probably work, but only if
- both libraries have the same requirement for the thread package. This
- is currently only supported for the non-threaded case, GNU Pth and
- pthread. Support for more thread packages is easy to add, so contact
- us if you require it.
-
- @item
- The function @code{gcry_check_version} must be called before any other
- function in the library, except the @code{GCRYCTL_SET_THREAD_CBS}
- command (called via the @code{gcry_control} function), because it
- initializes the thread support subsystem in @acronym{Libgcrypt}. To
- achieve this in multi-threaded programs, you must synchronize the
- memory with respect to other threads that also want to use
- @acronym{Libgcrypt}. For this, it is sufficient to call
- @code{gcry_check_version} before creating the other threads using
- @acronym{Libgcrypt}@footnote{At least this is true for POSIX threads,
- as @code{pthread_create} is a function that synchronizes memory with
- respects to other threads. There are many functions which have this
- property, a complete list can be found in POSIX, IEEE Std 1003.1-2003,
- Base Definitions, Issue 6, in the definition of the term ``Memory
- Synchronization''. For other thread packages, more relaxed or more
- strict rules may apply.}.
-
- @item
-
- As with the function @code{gpg_strerror}, @code{gcry_strerror} is not
- thread safe. You have to use @code{gpg_strerror_r} instead.
- @end itemize
-
-
- @acronym{Libgcrypt} contains convenient macros, which define the
- necessary thread callbacks for PThread and for GNU Pth:
-
- @table @code
- @item GCRY_THREAD_OPTION_PTH_IMPL
-
- This macro defines the following (static) symbols: 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''.
-
- @item 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''.
- @end table
-
- Note that these macros need to be terminated with a semicolon. Keep
- in mind that these are convenient macros for C programmers; C++
- programmers might have to wrap these macros in an ``extern C'' body.
-
- @c **********************************************************
- @c ******************* General ****************************
- @c **********************************************************
- @node Generalities
- @chapter Generalities
-
- @menu
- * Controlling the library:: Controlling @acronym{Libgcrypt}'s behavior.
- * Modules:: Description of extension modules.
- * Error Handling:: Error codes and such.
- @end menu
-
- @node Controlling the library
- @section Controlling the library
-
- @deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
-
- This function can be used to influence the general behavior of
- @acronym{Libgcrypt} in several ways. Depending on @var{cmd}, more
- arguments can or have to be provided.
-
- @end deftypefun
-
- @node Modules
- @section Modules
-
- @acronym{Libgcrypt} supports the use of `extension modules', which
- implement algorithms in addition to those already built into the
- library directly.
-
- @deftp {Data type} gcry_module_t
- This data type represents a `module'.
- @end deftp
-
- Functions registering modules provided by the user take a `module
- specification structure' as input and return a value of
- @code{gcry_module_t} and an ID that is unique in the modules'
- category. This ID can be used to reference the newly registered
- module. After registering a module successfully, the new functionality
- should be able to be used through the normal functions provided by
- @acronym{Libgcrypt} until it is unregistered again.
-
- @c **********************************************************
- @c ******************* Errors ****************************
- @c **********************************************************
- @node Error Handling
- @section Error Handling
-
- Many functions in @acronym{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.
-
- @acronym{Libgcrypt} uses the @code{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, @acronym{Libgcrypt} does
- not use its own identifiers for error codes, but uses those provided
- by @code{libgpg-error}. They usually start with @code{GPG_ERR_}.
-
- However, @acronym{Libgcrypt} does provide aliases for the functions
- defined in libgpg-error, which might be preferred for name space
- consistency.
-
-
- Most functions in @acronym{Libgcrypt} return an error code in the case
- of failure. For this reason, the application should always catch the
- error condition and take appropriate measures, for example by
- releasing the resources and passing the error up to the caller, or by
- displaying a descriptive message to the user and canceling the
- operation.
-
- Some error values do not indicate a system error or an error in the
- operation, but the result of an operation that failed properly.
-
- GnuPG components, including Libgcrypt, use an extra library named
- libgpg-error to provide a common error handling scheme. For more
- information on libgpg-error, see the according manual.
-
- @menu
- * Error Values:: The error value and what it means.
- * Error Sources:: A list of important error sources.
- * Error Codes:: A list of important error codes.
- * Error Strings:: How to get a descriptive string from a value.
- @end menu
-
-
- @node Error Values
- @subsection Error Values
- @cindex error values
- @cindex error codes
- @cindex error sources
-
- @deftp {Data type} {gcry_err_code_t}
- The @code{gcry_err_code_t} type is an alias for the
- @code{libgpg-error} type @code{gpg_err_code_t}. The error code
- indicates the type of an error, or the reason why an operation failed.
-
- A list of important error codes can be found in the next section.
- @end deftp
-
- @deftp {Data type} {gcry_err_source_t}
- The @code{gcry_err_source_t} type is an alias for the
- @code{libgpg-error} type @code{gpg_err_source_t}. The error source
- has not a precisely defined meaning. Sometimes it is the place where
- the error happened, sometimes it is the place where an error was
- encoded into an error value. Usually the error source will give an
- indication to where to look for the problem. This is not always true,
- but it is attempted to achieve this goal.
-
- A list of important error sources can be found in the next section.
- @end deftp
-
- @deftp {Data type} {gcry_error_t}
- The @code{gcry_error_t} type is an alias for the @code{libgpg-error}
- type @code{gpg_error_t}. An error value like this has always two
- components, an error code and an error source. Both together form the
- error value.
-
- Thus, the error value can not be directly compared against an error
- code, but the accessor functions described below must be used.
- However, it is guaranteed that only 0 is used to indicate success
- (@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
- the error value are set to 0, too.
-
- Note that in @acronym{Libgcrypt}, the error source is used purely for
- diagnostic purposes. Only the error code should be checked to test
- for a certain outcome of a function. The manual only documents the
- error code part of an error value. The error source is left
- unspecified and might be anything.
- @end deftp
-
- @deftypefun {gcry_err_code_t} gcry_err_code (@w{gcry_error_t @var{err}})
- The static inline function @code{gcry_err_code} returns the
- @code{gcry_err_code_t} component of the error value @var{err}. This
- function must be used to extract the error code from an error value in
- order to compare it with the @code{GPG_ERR_*} error code macros.
- @end deftypefun
-
- @deftypefun {gcry_err_source_t} gcry_err_source (@w{gcry_error_t @var{err}})
- The static inline function @code{gcry_err_source} returns the
- @code{gcry_err_source_t} component of the error value @var{err}. This
- function must be used to extract the error source from an error value in
- order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
- @end deftypefun
-
- @deftypefun {gcry_error_t} gcry_err_make (@w{gcry_err_source_t @var{source}}, @w{gcry_err_code_t @var{code}})
- The static inline function @code{gcry_err_make} returns the error
- value consisting of the error source @var{source} and the error code
- @var{code}.
-
- This function can be used in callback functions to construct an error
- value to return it to the library.
- @end deftypefun
-
- @deftypefun {gcry_error_t} gcry_error (@w{gcry_err_code_t @var{code}})
- The static inline function @code{gcry_error} returns the error value
- consisting of the default error source and the error code @var{code}.
-
- For @acronym{GCRY} applications, the default error source is
- @code{GPG_ERR_SOURCE_USER_1}. You can define
- @code{GCRY_ERR_SOURCE_DEFAULT} before including @file{gcrypt.h} to
- change this default.
-
- This function can be used in callback functions to construct an error
- value to return it to the library.
- @end deftypefun
-
- The @code{libgpg-error} library provides error codes for all system
- error numbers it knows about. If @var{err} is an unknown error
- number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used. The
- following functions can be used to construct error values from system
- errno numbers.
-
- @deftypefun {gcry_error_t} gcry_err_make_from_errno (@w{gcry_err_source_t @var{source}}, @w{int @var{err}})
- The function @code{gcry_err_make_from_errno} is like
- @code{gcry_err_make}, but it takes a system error like @code{errno}
- instead of a @code{gcry_err_code_t} error code.
- @end deftypefun
-
- @deftypefun {gcry_error_t} gcry_error_from_errno (@w{int @var{err}})
- The function @code{gcry_error_from_errno} is like @code{gcry_error},
- but it takes a system error like @code{errno} instead of a
- @code{gcry_err_code_t} error code.
- @end deftypefun
-
- Sometimes you might want to map system error numbers to error codes
- directly, or map an error code representing a system error back to the
- system error number. The following functions can be used to do that.
-
- @deftypefun {gcry_err_code_t} gcry_err_code_from_errno (@w{int @var{err}})
- The function @code{gcry_err_code_from_errno} returns the error code
- for the system error @var{err}. If @var{err} is not a known system
- error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
- @end deftypefun
-
- @deftypefun {int} gcry_err_code_to_errno (@w{gcry_err_code_t @var{err}})
- The function @code{gcry_err_code_to_errno} returns the system error
- for the error code @var{err}. If @var{err} is not an error code
- representing a system error, or if this system error is not defined on
- this system, the function returns @code{0}.
- @end deftypefun
-
-
- @node Error Sources
- @subsection Error Sources
- @cindex error codes, list of
-
- The library @code{libgpg-error} defines an error source for every
- component of the GnuPG system. The error source part of an error
- value is not well defined. As such it is mainly useful to improve the
- diagnostic error message for the user.
-
- If the error code part of an error value is @code{0}, the whole error
- value will be @code{0}. In this case the error source part is of
- course @code{GPG_ERR_SOURCE_UNKNOWN}.
-
- The list of error sources that might occur in applications using
- @acronym{Libgctypt} is:
-
- @table @code
- @item GPG_ERR_SOURCE_UNKNOWN
- The error source is not known. The value of this error source is
- @code{0}.
-
- @item GPG_ERR_SOURCE_GPGME
- The error source is @acronym{GPGME} itself.
-
- @item GPG_ERR_SOURCE_GPG
- The error source is GnuPG, which is the crypto engine used for the
- OpenPGP protocol.
-
- @item GPG_ERR_SOURCE_GPGSM
- The error source is GPGSM, which is the crypto engine used for the
- OpenPGP protocol.
-
- @item GPG_ERR_SOURCE_GCRYPT
- The error source is @code{libgcrypt}, which is used by crypto engines
- to perform cryptographic operations.
-
- @item GPG_ERR_SOURCE_GPGAGENT
- The error source is @command{gpg-agent}, which is used by crypto
- engines to perform operations with the secret key.
-
- @item GPG_ERR_SOURCE_PINENTRY
- The error source is @command{pinentry}, which is used by
- @command{gpg-agent} to query the passphrase to unlock a secret key.
-
- @item GPG_ERR_SOURCE_SCD
- The error source is the SmartCard Daemon, which is used by
- @command{gpg-agent} to delegate operations with the secret key to a
- SmartCard.
-
- @item GPG_ERR_SOURCE_KEYBOX
- The error source is @code{libkbx}, a library used by the crypto
- engines to manage local keyrings.
-
- @item GPG_ERR_SOURCE_USER_1
- @item GPG_ERR_SOURCE_USER_2
- @item GPG_ERR_SOURCE_USER_3
- @item GPG_ERR_SOURCE_USER_4
- These error sources are not used by any GnuPG component and can be
- used by other software. For example, applications using
- @acronym{Libgcrypt} can use them to mark error values coming from callback
- handlers. Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
- created with @code{gcry_error} and @code{gcry_error_from_errno},
- unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including
- @file{gcrypt.h}.
- @end table
-
-
- @node Error Codes
- @subsection Error Codes
- @cindex error codes, list of
-
- The library @code{libgpg-error} defines many error values. The
- following list includes the most important error codes.
-
- @table @code
- @item GPG_ERR_EOF
- This value indicates the end of a list, buffer or file.
-
- @item GPG_ERR_NO_ERROR
- This value indicates success. The value of this error code is
- @code{0}. Also, it is guaranteed that an error value made from the
- error code @code{0} will be @code{0} itself (as a whole). This means
- that the error source information is lost for this error code,
- however, as this error code indicates that no error occured, this is
- generally not a problem.
-
- @item GPG_ERR_GENERAL
- This value means that something went wrong, but either there is not
- enough information about the problem to return a more useful error
- value, or there is no separate error value for this type of problem.
-
- @item GPG_ERR_ENOMEM
- This value means that an out-of-memory condition occurred.
-
- @item GPG_ERR_E...
- System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for
- the system error.
-
- @item GPG_ERR_INV_VALUE
- This value means that some user provided data was out of range.
-
- @item GPG_ERR_UNUSABLE_PUBKEY
- This value means that some recipients for a message were invalid.
-
- @item GPG_ERR_UNUSABLE_SECKEY
- This value means that some signers were invalid.
-
- @item GPG_ERR_NO_DATA
- This value means that data was expected where no data was found.
-
- @item GPG_ERR_CONFLICT
- This value means that a conflict of some sort occurred.
-
- @item GPG_ERR_NOT_IMPLEMENTED
- This value indicates that the specific function (or operation) is not
- implemented. This error should never happen. It can only occur if
- you use certain values or configuration options which do not work,
- but for which we think that they should work at some later time.
-
- @item GPG_ERR_DECRYPT_FAILED
- This value indicates that a decryption operation was unsuccessful.
-
- @item GPG_ERR_WRONG_KEY_USAGE
- This value indicates that a key is not used appropriately.
-
- @item GPG_ERR_NO_SECKEY
- This value indicates that no secret key for the user ID is available.
-
- @item GPG_ERR_UNSUPPORTED_ALGORITHM
- This value means a verification failed because the cryptographic
- algorithm is not supported by the crypto backend.
-
- @item GPG_ERR_BAD_SIGNATURE
- This value means a verification failed because the signature is bad.
-
- @item GPG_ERR_NO_PUBKEY
- This value means a verification failed because the public key is not
- available.
-
- @item GPG_ERR_USER_1
- @item GPG_ERR_USER_2
- @item ...
- @item GPG_ERR_USER_16
- These error codes are not used by any GnuPG component and can be
- freely used by other software. Applications using @acronym{Libgcrypt}
- might use them to mark specific errors returned by callback handlers
- if no suitable error codes (including the system errors) for these
- errors exist already.
- @end table
-
-
- @node Error Strings
- @subsection Error Strings
- @cindex error values, printing of
- @cindex error codes, printing of
- @cindex error sources, printing of
- @cindex error strings
-
- @deftypefun {const char *} gcry_strerror (@w{gcry_error_t @var{err}})
- The function @code{gcry_strerror} returns a pointer to a statically
- allocated string containing a description of the error code contained
- in the error value @var{err}. This string can be used to output a
- diagnostic message to the user.
- @end deftypefun
-
-
- @deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}})
- The function @code{gcry_strerror} returns a pointer to a statically
- allocated string containing a description of the error source
- contained in the error value @var{err}. This string can be used to
- output a diagnostic message to the user.
- @end deftypefun
-
- The following example illustrates the use of the functions described
- above:
-
- @example
- @{
- gcry_cipher_hd_t handle;
- gcry_error_t err = 0;
-
- err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0);
- if (err)
- @{
- fprintf (stderr, "Failure: %s/%s\n",
- gcry_strsource (err),
- gcry_strerror (err));
- @}
- @}
- @end example
-
- @c **********************************************************
- @c ******************* General ****************************
- @c **********************************************************
- @node Handler Functions
- @chapter Handler Functions
-
- @acronym{Libgcrypt} makes it possible to install so called `handler functions',
- which get called by @acronym{Libgcrypt} in case of certain events.
-
- @menu
- * Progress handler:: Using a progress handler function.
- * Allocation handler:: Using special memory allocation functions.
- * Error handler:: Using error handler functions.
- * Logging handler:: Using a special logging function.
- @end menu
-
- @node Progress handler
- @section Progress handler
-
- It is often useful to retrieve some feedback while long running
- operations are performed.
-
- @deftp {Data type} gcry_handler_progress_t
- Progress handler functions have to be of the type
- @code{gcry_handler_progress_t}, which is defined as:
-
- @code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)}
- @end deftp
-
- The following function may be used to register a handler function for
- this purpose.
-
- @deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data})
-
- This function installs @var{cb} as the `Progress handler' function.
- @var{cb} must be defined as follows:
-
- @example
- void
- my_progress_handler (void *@var{cb_data}, const char *@var{what},
- int @var{printchar}, int @var{current}, int @var{total})
- @{
- /* Do something. */
- @}
- @end example
-
- A description of the arguments of the progress handler function follows.
-
- @table @var
- @item cb_data
- The argument provided in the call to @code{gcry_set_progress_handler}.
- @item what
- A string identifying the type of the progress output. The following
- values for @var{what} are defined:
-
- @table @code
- @item need_entropy
- Not enough entropy is available. @var{total} holds the number of
- required bytes.
-
- @item primegen
- Values for @var{printchar}:
- @table @code
- @item \n
- Prime generated.
- @item !
- Need to refresh the pool of prime numbers.
- @item <, >
- Number of bits adjusted.
- @item ^
- Searching for a generator.
- @item .
- Fermat test on 10 candidates failed.
- @item :
- Restart with a new random value.
- @item +
- Rabin Miller test passed.
- @end table
-
- @end table
-
- @end table
- @end deftypefun
-
- @node Allocation handler
- @section Allocation handler
-
- It is possible to make @acronym{Libgcrypt} use special memory
- allocation functions instead of the built-in ones.
-
- Memory allocation functions are of the following types:
- @deftp {Data type} gcry_handler_alloc_t
- This type is defined as: @code{void *(*gcry_handler_alloc_t) (size_t n)}.
- @end deftp
- @deftp {Data type} gcry_handler_secure_check_t
- This type is defined as: @code{int *(*gcry_handler_secure_check_t) (const void *)}.
- @end deftp
- @deftp {Data type} gcry_handler_realloc_t
- This type is defined as: @code{void *(*gcry_handler_realloc_t) (void *p, size_t n)}.
- @end deftp
- @deftp {Data type} gcry_handler_free_t
- This type is defined as: @code{void *(*gcry_handler_free_t) (void *)}.
- @end deftp
-
- Special memory allocation functions can be installed with the
- following function:
-
- @deftypefun void gcry_set_allocation_handler (gcry_handler_alloc_t @var{func_alloc}, gcry_handler_alloc_t @var{func_alloc_secure}, gcry_handler_secure_check_t @var{func_secure_check}, gcry_handler_realloc_t @var{func_realloc}, gcry_handler_free_t @var{func_free})
- Install the provided functions and use them instead of the built-in
- functions for doing memory allocation.
- @end deftypefun
-
- @node Error handler
- @section Error handler
-
- The following functions may be used to register handler functions that
- are called by @acronym{Libgcrypt} in case certain error conditions
- occur.
-
- @deftp {Data type} gcry_handler_no_mem_t
- This type is defined as: @code{void (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)}
- @end deftp
- @deftypefun void gcry_set_outofcore_handler (gcry_handler_no_mem_t @var{func_no_mem}, void *@var{cb_data})
- This function registers @var{func_no_mem} as `out-of-core handler',
- which means that it will be called in the case of not having enough
- memory available.
- @end deftypefun
-
- @deftp {Data type} gcry_handler_error_t
- This type is defined as: @code{void (*gcry_handler_error_t) (void *, int, const char *)}
- @end deftp
-
- @deftypefun void gcry_set_fatalerror_handler (gcry_handler_error_t @var{func_error}, void *@var{cb_data})
- This function registers @var{func_error} as `error handler',
- which means that it will be called in error conditions.
- @end deftypefun
-
- @node Logging handler
- @section Logging handler
-
- @deftp {Data type} gcry_handler_log_t
- This type is defined as: @code{void (*gcry_handler_log_t) (void *, int, const char *, va_list)}
- @end deftp
-
- @deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})
- This function registers @var{func_log} as `logging handler', which
- means that it will be called in case @acronym{Libgcrypt} wants to log
- a message.
- @end deftypefun
-
- @c **********************************************************
- @c ******************* Ciphers ****************************
- @c **********************************************************
- @c @include cipher-ref.texi
- @node Symmetric cryptography
- @chapter Symmetric cryptography
-
- The cipher functions are used for symmetrical cryptography,
- i.e. cryptography using a shared key. The programming model follows
- an open/process/close paradigm and is in that similar to other
- building blocks provided by @acronym{Libgcrypt}.
-
- @menu
- * Available ciphers:: List of ciphers supported by the library.
- * Cipher modules:: How to work with cipher modules.
- * Available cipher modes:: List of cipher modes supported by the library.
- * Working with cipher handles:: How to perform operations related to cipher handles.
- * General cipher functions:: General cipher functions independent of cipher handles.
- @end menu
-
- @node Available ciphers
- @section Available ciphers
-
- @table @code
- @item GCRY_CIPHER_NONE
- This is not a real algorithm but used by some functions as error return.
- The value always evaluates to false.
-
- @item GCRY_CIPHER_IDEA
- This is the IDEA algorithm. The constant is provided but there is
- currently no implementation for it because the algorithm is patented.
-
- @item GCRY_CIPHER_3DES
- Triple-DES with 3 Keys as EDE. The key size of this algorithm is 168 but
- you have to pass 192 bits because the most significant bits of each byte
- are ignored.
-
- @item GCRY_CIPHER_CAST5
- CAST128-5 block cipher algorithm. The key size is 128 bits.
-
- @item GCRY_CIPHER_BLOWFISH
- The blowfish algorithm. The current implementation allows only for a key
- size of 128 bits.
-
- @item GCRY_CIPHER_SAFER_SK128
- Reserved and not currently implemented.
-
- @item GCRY_CIPHER_DES_SK
- Reserved and not currently implemented.
-
- @item GCRY_CIPHER_AES
- @itemx GCRY_CIPHER_AES128
- @itemx GCRY_CIPHER_RIJNDAEL
- @itemx GCRY_CIPHER_RIJNDAEL128
- AES (Rijndael) with a 128 bit key.
-
- @item GCRY_CIPHER_AES192
- @itemx GCRY_CIPHER_RIJNDAEL128
- AES (Rijndael) with a 192 bit key.
-
- @item GCRY_CIPHER_AES256
- @itemx GCRY_CIPHER_RIJNDAEL256
- AES (Rijndael) with a 256 bit key.
-
- @item GCRY_CIPHER_TWOFISH
- The Twofish algorithm with a 256 bit key.
-
- @item GCRY_CIPHER_TWOFISH128
- The Twofish algorithm with a 128 bit key.
-
- @item 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.
-
- @item 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.
-
- @end table
-
- @node Cipher modules
- @section Cipher modules
-
- @acronym{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 @xref{Modules}.
-
- @deftp {Data type} gcry_cipher_spec_t
- This is the `module specification structure' needed for registering
- cipher modules, which has to be filled in by the user before it can be
- used to register a module. It contains the following members:
-
- @table @code
- @item const char *name
- The primary name of the algorithm.
- @item const char **aliases
- A list of strings that are `aliases' for the algorithm. The list must
- be terminated with a NULL element.
- @item gcry_cipher_oid_spec_t *oids
- A list of OIDs that are to be associated with the algorithm. The
- list's last element must have it's `oid' member set to NULL. See
- below for an explanation of this type.
- @item size_t blocksize
- The block size of the algorithm, in bytes.
- @item size_t keylen
- The length of the key, in bits.
- @item size_t contextsize
- The size of the algorithm-specific `context', that should be allocated
- for each handle.
- @item gcry_cipher_setkey_t setkey
- The function responsible for initializing a handle with a provided
- key. See below for a description of this type.
- @item gcry_cipher_encrypt_t encrypt
- The function responsible for encrypting a single block. See below for
- a description of this type.
- @item gcry_cipher_decrypt_t decrypt
- The function responsible for decrypting a single block. See below for
- a description of this type.
- @item gcry_cipher_stencrypt_t stencrypt
- Like `encrypt', for stream ciphers. See below for a description of
- this type.
- @item gcry_cipher_stdecrypt_t stdecrypt
- Like `decrypt', for stream ciphers. See below for a description of
- this type.
- @end table
- @end deftp
-
- @deftp {Data type} gcry_cipher_oid_spec_t
- This type is used for associating a user-provided algorithm
- implementation with certain OIDs. It contains the following members:
- @table @code
- @item const char *oid
- Textual representation of the OID.
- @item int mode
- Cipher mode for which this OID is valid.
- @end table
- @end deftp
-
- @deftp {Data type} gcry_cipher_setkey_t
- Type for the `setkey' function, defined as: gcry_err_code_t
- (*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned
- keylen)
- @end deftp
-
- @deftp {Data type} gcry_cipher_encrypt_t
- Type for the `encrypt' function, defined as: gcry_err_code_t
- (*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const
- unsigned char *inbuf)
- @end deftp
-
- @deftp {Data type} gcry_cipher_decrypt_t
- Type for the `decrypt' function, defined as: gcry_err_code_t
- (*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const
- unsigned char *inbuf)
- @end deftp
-
- @deftp {Data type} gcry_cipher_stencrypt_t
- Type for the `stencrypt' function, defined as: gcry_err_code_t
- (*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, const
- unsigned char *, unsigned int n)
- @end deftp
-
- @deftp {Data type} gcry_cipher_stdecrypt_t
- Type for the `stdecrypt' function, defined as: gcry_err_code_t
- (*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, const
- unsigned char *, unsigned int n)
- @end deftp
-
- @deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module})
-
- Register a new cipher module whose specification can be found in
- @var{cipher}. On success, a new algorithm ID is stored in
- @var{algorithm_id} and a pointer representing this module is stored
- in @var{module}.
- @end deftypefun
-
- @deftypefun void gcry_cipher_unregister (gcry_module_t @var{module})
- Unregister the cipher identified by @var{module}, which must have been
- registered with gcry_cipher_register.
- @end deftypefun
-
- @deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length})
- Get a list consisting of the IDs of the loaded cipher modules. If
- @var{list} is zero, write the number of loaded cipher modules to
- @var{list_length} and return. If @var{list} is non-zero, the first
- *@var{list_length} algorithm IDs are stored in @var{list}, which must
- be of according size. In case there are less cipher modules than
- *@var{list_length}, *@var{list_length} is updated to the correct
- number.
- @end deftypefun
-
- @node Available cipher modes
- @section Available cipher modes
-
- @table @code
- @item GCRY_CIPHER_MODE_NONE
- No mode specified, may be set later using other functions. The value
- of this constant is always 0.
-
- @item GCRY_CIPHER_MODE_ECB
- Electronic Codebook mode.
-
- @item GCRY_CIPHER_MODE_CFB
- Cipher Feedback mode.
-
- @item GCRY_CIPHER_MODE_CBC
- Cipher Block Chaining mode.
-
- @item GCRY_CIPHER_MODE_STREAM
- Stream mode, only to be used with stream cipher algorithms.
-
- @item GCRY_CIPHER_MODE_OFB
- Outer Feedback mode.
-
- @item GCRY_CIPHER_MODE_CTR
- Counter mode.
-
- @end table
-
- @node Working with cipher handles
- @section Working with cipher handles
-
- To use a cipher algorithm, you must first allocate an according
- handle. This is to be done using the open function:
-
- @deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd}, int @var{algo}, int @var{mode}, unsigned int @var{flags})
-
- This function creates the context handle required for most of the
- other cipher functions and returns a handle to it in `hd'. In case of
- an error, an according error code is returned.
-
- The ID of algorithm to use must be specified via @var{algo}. See
- @xref{Available ciphers}, for a list of supported ciphers and the
- according constants.
-
- Besides using the constants directly, the function
- @code{gcry_cipher_map_name} may be used to convert the textual name of
- an algorithm into the according numeric ID.
-
- The cipher mode to use must be specified via @var{mode}. See
- @xref{Available cipher modes}, for a list of supported cipher modes
- and the according constants. Note, that some modes do not work
- together with all algorithms.
-
- The third argument @var{flags} can either be passed as @code{0} or as
- the bit-wise OR of the following constants.
-
- @table @code
- @item GCRY_CIPHER_SECURE
- Make sure that all operations are allocated in secure memory. This is
- useful, when the key material is highly confidential.
- @item GCRY_CIPHER_ENABLE_SYNC
- This flag enables the CFB sync mode, which is a special feature of
- @acronym{Libgcrypt}'s CFB mode implementation to allow for OpenPGP's CFB variant.
- See @code{gcry_cipher_sync}.
- @i…
Large files files are truncated, but you can click here to view the full file