diff options
author | Moritz Schulte <mo@g10code.com> | 2003-06-15 00:57:20 +0000 |
---|---|---|
committer | Moritz Schulte <mo@g10code.com> | 2003-06-15 00:57:20 +0000 |
commit | 92e27f51425ae44a321bd6c05b89cb03238d3153 (patch) | |
tree | f5e2e7249bf0ee83c2d08f8421f13cf5a48008d0 /doc | |
parent | 41a949abaa5a285331fc123ad575ef539b807240 (diff) | |
download | libgcrypt-92e27f51425ae44a321bd6c05b89cb03238d3153.tar.gz |
2003-06-15 Moritz Schulte <moritz@g10code.com>
* gcrypt.texi: Documented several parts of the library, merged
some documentation from GPGME's manual, re-structured the whole
manual, added more menus.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ChangeLog | 6 | ||||
-rw-r--r-- | doc/gcrypt.texi | 944 |
2 files changed, 596 insertions, 354 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 3425c6d9..03e6de8c 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,9 @@ +2003-06-15 Moritz Schulte <moritz@g10code.com> + + * gcrypt.texi: Documented several parts of the library, merged + some documentation from GPGME's manual, re-structured the whole + manual, added more menus. + 2003-06-14 Moritz Schulte <moritz@g10code.com> * gcrypt.texi (Hash Functions): Adjusteded description of diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi index 29b3c983..d358e79a 100644 --- a/doc/gcrypt.texi +++ b/doc/gcrypt.texi @@ -76,17 +76,17 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of @end ifnottex @menu -* Introduction:: How to use this manual. +* Introduction:: What is @acronym{Libgcrypt}. * Preparation:: What you should do before using the library. * General Functions:: General library functions. * Handler Functions:: Working with handler functions. -* Cipher Functions:: All about ciphers. -* Hash Functions:: How to use cryptographic hash functions. -* Public Key Functions:: How to use asymmetric encryption. -* Random Numbers:: How to create random. +* Symmetric cryptography:: How to use symmetric crytography. +* Hashing:: How to use hashing. +* Public Key cryptography:: How to use public key cryptography. +* Random Numbers:: How to work with random numbers. * S-expressions:: How to manage S-expressions. -* MPI Functions:: How to work with big integers. -* Utilities:: Helper functions. +* MPI library:: How to work with multi-precision-integers. +* Utilities:: Utility functions. * Error Handling:: Error codes and such. Appendices @@ -104,7 +104,71 @@ Indices * 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 auf Automake. +* Initializing the library:: How to initialize the library. +* Multi Threading:: How Libgcrypt can be used in a MT environment. + +General Functions +* Controlling the library:: Controlling @acronym{Libgcrypt}'s behaviour. + +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. +* 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. +* Working with hash algorithms:: List of functions related to hashing. + +Public Key cryptography +* Used S-expressions:: Introduction into the used S-expression. +* Available algorithms:: Algorithms supported by the library. +* Cryptographic Functions:: Functions for performing the cryptographic actions. +* General public-key related Functions:: General functions, not implementing any cryptography. + +Random Numbers +* Quality of random numbers:: @acronym{Libgcrypt} differentiates between 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. +* Misc:: Misc, fixme. + +Utilities +* Memory allocation:: Functions related with memory allocation. + +Error handling +* Error values:: A list of all error values used. +* Error strings:: How to get a descriptive string from a value. + @end detailmenu + @end menu @c ********************************************************** @@ -112,12 +176,12 @@ Indices @c ********************************************************** @node Introduction @chapter Introduction -`Libgcrypt' is a library to provide cryptographic building blocks. +`Libgcrypt' is a library providing cryptographic building blocks. @menu -* Getting Started:: -* Features:: -* Overview:: +* 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 @@ -167,12 +231,11 @@ blocks using an extendable and flexible API. @section Overview @noindent -The `Libgcrypt' library is thread-safe. Well, we hope so ;-). Frankly, -@code{gcry_errno} is not yet thread-safe. Most others are believed to -be. Libgcrypt automagically detects whether an applications uses no -threading, pthreads or GNU Pth. +The `Libgcrypt' library is fully thread-safe; the library +automagically detects whether an applications uses no threading, +pthreads or GNU Pth. -Libgcrypt depends on the library `libgpg-error' [FIXME: REF], which +Libgcrypt depends on the library `libgpg-error' [FIXME: REF?], which contains common error handling code for GnuPG components. @c ********************************************************** @@ -188,9 +251,11 @@ library is initialized, and how the requirements of the library are verified. @menu -* Header:: -* Version Check:: -* Building the source:: +* 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 auf Automake. +* Initializing the library:: How to initialize the library. +* Multi Threading:: How Libgcrypt can be used in a MT environment. @end menu @@ -198,9 +263,9 @@ verified. @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 programs -using the library, either directly or through some other header file, -like this: +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> @@ -211,31 +276,12 @@ 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 libgcrypt uses libgpg-error, +symbols prefixed with `GPG_'. Note that 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 Version Check -@section Version Check - -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. - -@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 Libgcrypt. -@end deftypefun - -@node Building the source -@section Building the source +@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 @@ -280,19 +326,140 @@ specifying both options to @command{libgcrypt-config}: 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 `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 Libgcrypt. +@end deftypefun + +@node Multi Threading +@section Multi Threading + +As mentioned earlier, the `Libgcrypt' library is fully thread-safe; +the library automagically detects whether an applications uses no +threading, pthreads or GNU Pth. + +If you link your program dynamically to @acronym{Libgcrypt} and your +supported thread library, @acronym{Libgcrypt} will automatically +detect the presence of this library and activate its use. You must +link to the thread library before linking to @acronym{Libgcrypt}. If +you link to both pthread and GNU Pth, @acronym{Libgcrypt} will use the +pthread support. This feature requires weak symbol support. + +If you link your program statically to @acronym{Libgcrypt}, or your +system does not support weak symbols, there is currently no easy way +to make sure that @acronym{Libgcrypt} detects the presence of the +thread library. This will be solved in a future version. + +The function @code{gcry_check_version} must be called before any other +function in the library, because it initializes the thread support +subsystem in @acronym{Libgcrypt}. To achieve this in all generality, +it is necessary to synchronize the call to this function with all +other calls to functions in the library, using the synchronization +mechanisms available in your thread library. Otherwise, specific +compiler or CPU memory cache optimizations could lead to the situation +where a thread is started and uses @acronym{Libgcrypt} before the +effects of the initialization are visible for this thread. It doesn't +even suffice to call @code{gcry_check_version} before creating this +other thread@footnote{In SMP systems the new thread could be started +on another CPU before the effects of the initialization are seen by +that CPU's memory cache. Not doing proper synchronization here leads +to the same problems the double-checked locking idiom has. You might +find that if you don't do proper synchronization, it still works in +most configurations. Don't let this fool you. Someday it might lead +to subtle bugs when someone tries it on a DEC Alpha or an SMP +machine.}. + +For example, if you are using POSIX threads, each thread that wants to +call functions in @acronym{Libgcrypt} could call the following +function before any function in the library: + +@example +#include <pthread.h> + +void +initialize_gcrypt (void) +@{ + static int gcrypt_init; + static pthread_mutext_t gcrypt_init_lock = PTHREAD_MUTEX_INITIALIZER; + + pthread_mutex_lock (&gcrypt_init_lock); + if (! gcrypt_init) + @{ + gcry_check_version (); + gcrypt_init = 1; + @} + pthread_mutex_unlock (&gcrypt_init_lock); +@} +@end example + @c ********************************************************** @c ******************* General **************************** @c ********************************************************** @node General Functions @chapter General Functions +@menu +* Controlling the library:: Controlling @acronym{Libgcrypt}'s behaviour. +@end menu + +@node Controlling the library +@section Controlling the library + @deftypefun gpg_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...) This function can be used to influence the general behaviour of Libgcrypt in several ways. Depending on @var{cmd}, more arguments can or have to be provided. -FIXME. @end deftypefun @c ********************************************************** @@ -304,33 +471,169 @@ FIXME. Libgcrypt makes it possible to install so called `handler functions', which get called by Libgcrypt in case of certain events. +@menu +* Progress handler:: Using a progress handler function. +* Allocation handler:: Using special memory allocation functions. +* Error handler:: Using error handler functions. +* Logging handler:: Using a special logging function. +@end menu + +@node Progress handler +@section Progress handler + +It is often useful to retrieve some feedback while long running +operations are performed. + +@deftp {Data type} gcry_handler_progress_t +Progress handler functions have to be of the type +@code{gcry_handler_progress_t}, which is defined as: + +@code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)} +@end deftp + +The following function may be used to register a handler function for +this purpose. + +@deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data}) + +This function installs @var{cb} as the `Progress handler' function. +@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{void *(*gcry_handler_secure_check_t) (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 Cipher Functions -@chapter Cipher Functions +@node Symmetric cryptography +@chapter Symmetric cryptography -The cipher functions are used for symmetrical encryption, -i.e. encryption using a shared key. The programming model follows an -open/process/close paradigm and in that similar to the other building -blocks provided by Libgcrypt. +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}. -To use a cipher algorithm, you must first allocate an handle for -this. This can is to be done using the open function: - -@deftypefun gpg_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd}, -int @var{algo}, int @var{mode}, unsigned int @var{flags}) +@menu +* Available ciphers:: List of ciphers supported by the library. +* 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 -This function creates the context 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. You must tell this -function which algorithm and what mode you want to use. The function -@code{gcry_cipher_map_name} may be used to get the a value for the -@var{algo} from a textual name or one of the predefined constants can -be used: +@node Available ciphers +@section Available ciphers -@c begin cipher algorithm constants @table @code @item GCRY_CIPHER_NONE This is not a real algorithm but used by some functions as error return. @@ -386,12 +689,9 @@ 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 -@c end cipher algorithm constants -@c begin cipher modes constants -The second argument is @var{mode} which describes the mode the -algorithm is to be used in. Note, that some modes do not work -together with all algorithms. The following modes are available: +@node Available cipher modes +@section Available cipher modes @table @code @item GCRY_CIPHER_MODE_NONE @@ -417,7 +717,32 @@ Outer Feedback mode. Counter mode. @end table -@c end cipher modes constants + +@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 gpg_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. @@ -438,20 +763,18 @@ Compute CBC-MAC keyed checksums. This is the same as CBC mode, but only output the last block. Cannot be used simultaneous as GCRY_CIPHER_CBC_CTS. @end table - +@item @end deftypefun -@c end gcry_cipher_open -To release the context allocated with this function, -@code{gcry_cipher_close} should be used: +Use the following function to release an existing handle: @deftypefun void gcry_cipher_close (gcry_cipher_hd_t @var{h}) This function releases the context created by @code{gcry_cipher_open}. @end deftypefun -Now that a context has been allocated, the key to be used for decryption -or encryption must be set. This is done with the following function: +In order to use a handle for performing cryptographic operations, a +`key' has to be set first: @deftypefun gpg_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l}) @@ -462,8 +785,8 @@ be in the allowed range for algorithms with variable key size. The function checks this and returns an error if there is a problem. A caller should always check for an error. -Note, this is currently implemented as a -macro but may be changed to a function in the future. +Note, this is currently implemented as a macro but may be changed to a +function in the future. @end deftypefun Most crypto modes requires an initialization vector (IV), which @@ -566,15 +889,6 @@ handle @var{h}. Please see the comments in the source code (@code{src/global.c}) for details. @end deftypefun - -@c *********************************************** -@c *********** cipher info ******************** -@c *********************************************** - -To work with the algorithms, several functions are available to map -algorithm names to the internal identifiers, as well as ways to retrieve -information about an algorithm or the current cipher context. - @deftypefun gpg_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes}) @code{gcry_cipher_info} is used to retrieve various @@ -583,6 +897,12 @@ information about a cipher context or the cipher module in general. Currently no information is available. @end deftypefun +@node General cipher functions +@section General cipher functions + +To work with the algorithms, several functions are available to map +algorithm names to the internal identifiers, as well as ways to +retrieve information about an algorithm or the current cipher context. @deftypefun gpg_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes}) @@ -646,29 +966,26 @@ with it. @c ********************************************************** @c ******************* Hash Functions ********************* @c ********************************************************** -@node Hash Functions -@chapter Hash Functions +@node Hashing +@chapter Hashing -How to use cryptographic hash functions. Libgcrypt provides an easy and -consistent to use interface to hash functions. Hashing is buffered and -several hash algorithms can be updated at once. It is possible to -calculate a MAC using the same routines. +@acronym{Libgcrypt} provides an easy and consistent to use interface +for hashing. Hashing is buffered and several hash algorithms can be +updated at once. It is possible to calculate a MAC using the same +routines. The programming model follows an open/process/close +paradigm and is in that similar to other building blocks provided by +@acronym{Libgcrypt}. -For convenience reasons, a few cyclic redudance check value operations +For convenience reasons, a few cyclic redudancy check value operations are also supported. -To use most of these function it is necessary to create a context; this -is done using: - -@deftypefun gpg_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags}) - -Create a message digest object for algorithm @var{algo}. @var{flags} -may be given as an bitwise OR of constants described below. @var{algo} -may be given as @code{0} if the algorithms to use are later set using -@code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid -handle or NULL. +@menu +* Available hash algorithms:: List of hash algorithms supported by the library. +* Working with hash algorithms:: List of functions related to hashing. +@end menu -The following algorithms are supported: +@node Available hash algorithms +@section Available hash algorithms @c begin table of hash algorithms @table @code @@ -728,6 +1045,23 @@ output of 3 bytes. @end table @c end table of hash algorithms +@node Working with hash algorithms +@section Working with hash algorithms + +To use most of these function it is necessary to create a context; +this is done using: + +@deftypefun gpg_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags}) + +Create a message digest object for algorithm @var{algo}. @var{flags} +may be given as an bitwise OR of constants described below. @var{algo} +may be given as @code{0} if the algorithms to use are later set using +@code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid +handle or NULL. + +For a list of supported algorithms, see @xref{Available hash +algorithms}. + The flags allowed for @var{mode} are: @c begin table of hash flags @@ -739,8 +1073,8 @@ this is the hashed data is highly confidential. @item GCRY_MD_FLAG_HMAC Turn the algorithm into a HMAC message authentication algorithm. Note that the function @code{gcry_md_setkey} must be used set the MAC key. -If you want CBC message authenentication codes based on a cipher, see -@xref{Cipher Functions}. +If you want CBC message authentication codes based on a cipher, see +@xref{Working with cipher handles}. @end table @c begin table of hash flags @@ -958,8 +1292,8 @@ in "secure memory"; i.e. @var{h} was created with the @deftypefun int gcry_md_is_enabled (gcry_md_hd_t @var{h}, int @var{algo}) -This function returns true when the agorithm @var{algo} has been enabled -for the digest object @var{h}. +This function returns true when the algorithm @var{algo} has been +enabled for the digest object @var{h}. @end deftypefun @@ -992,18 +1326,47 @@ does implicitly stop debugging. @c ********************************************************** @c ******************* Public Key ************************* @c ********************************************************** -@node Public Key Functions -@chapter Public Key Functions +@node Public Key cryptography +@chapter Public Key cryptography Public key cryptography, also known as asymmetric cryptography, is an easy way for key management and to provide digital signatures. + +@menu +* Used S-expressions:: Introduction into the used S-expression. +* Available algorithms:: Algorithms supported by the library. +* Cryptographic Functions:: Functions for performing the cryptographic actions. +* General public-key related Functions:: General functions, not implementing any cryptography. +@end menu + +@node Available algorithms +@section Available algorithms + Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well as DSA (Digital Signature Algorithm) and ElGamal. The versatile interface allows to add more algorithms in the future. -The API is based on data structures called S-expressions (see XXXX) -and does not work with contexts as most of the other building blocks -Libgcrypt provides. +@node Used S-expressions +@section Used S-expressions + +@acronym{Libgcrypt}'s API for asymmetric cryptography is based on data +structures called S-expressions (see XXXX) and does not work with +contexts as most of the other building blocks of @acronym{Libgcrypt} +do. + +The following information are stored in S-expressions: + +@table @asis +@item Keys + +@item plain text data + +@item encrypted data + +@item signatures +... + +@end table @noindent To describe how Libgcrypt expect keys, we use some examples. Note that @@ -1082,6 +1445,10 @@ RSA secret prime @math{q} with @math{q > p}. multiplicative inverse @math{u = p^{-1} \bmod q}. @end table + +@node Cryptographic Functions +@section Cryptographic Functions + @noindent Note, that we will in future allow to use keys without p,q and u specified and may also support other parameters for performance @@ -1307,6 +1674,8 @@ to indicate that the signature does not match the provided data. @end deftypefun @c end gcry_pk_verify +@node General public-key related Functions +@section General public-key related Functions @noindent A couple of utility functions are available to retrieve the length of @@ -1527,6 +1896,32 @@ useful information. @node Random Numbers @chapter Random Numbers +@menu +* Quality of random numbers:: @acronym{Libgcrypt} differentiates between different quality levels. +* Retrieving random numbers:: How to retrieve random numbers. +@end menu + +@node Quality of random numbers +@section Quality of random numbers + +@acronym{Libgcypt} offers random numbers of different quality levels: + +@deftp {Data type} enum gcry_random_level +The constants for the random quality levels are of this type. +@end deftp + +@table @code +@item GCRY_WEAK_RANDOM +Use this level for random numbers that do not need to be +`cryptographically strong'. +@item GCRY_STRONG_RANDOM +Use this level for e.g. session keys and similar purposes. +@item GCRY_VERY_STRONG_RANDOM +Use this level for e.g. key material. +@end table + +@node Retrieving random numbers +@section Retrieving random numbers @deftypefun void gcry_randomize (unsigned char *@var{buffer}, size_t @var{length}, enum gcry_random_level @var{level}) @@ -1562,11 +1957,22 @@ to parse and construct them. For detailed information, see @cite{Ron Rivest, code and description of S-expressions, @uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}. +@menu +* Data types for S-expressions:: Data types related with S-expressions. +* Working with S-expressions:: How to work with S-expressions. +@end menu + +@node Data types for S-expressions +@section Data types for S-expressions + @deftp {Data type} gcry_sexp_t The @code{gcry_sexp_t} type describes an object with the Libgcrypt internal representation of an S-expression. @end deftp +@node Working with S-expressions +@section Working with S-expressions + @noindent There are several functions to create an Libgcrypt S-expression object from its external representation or from a string template. There is @@ -1778,8 +2184,18 @@ can't be converted to an MPI, @code{NULL} is returned. @c ********************************************************** @c ******************* MPIs ******** *********************** @c ********************************************************** -@node MPI Functions -@chapter MPI Functions +@node MPI library +@chapter MPI library + +@menu +* Data types:: MPI related data types. +* Basic functions:: First steps with MPI numbers. +* MPI formats:: External representation of MPIs. +* Calculations:: Performing MPI calculations. +* Comparisons:: How to compare MPI values. +* Bit manipulations:: How to access single bits of MPI values. +* Misc:: Misc, fixme. +@end menu Public key cryptography is based on mathematics with large numbers. To implement the public key functions, a library for handling these large @@ -1795,15 +2211,20 @@ better performance than with the standard C implementation. In the context of Libgcrypt and in most other applications, these large numbers are called MPIs (multi-precision-integers). +@node Data types +@section Data types + @deftp {Data type} gcry_mpi_t The @code{gcry_mpi_t} type represents an object to hold an MPI. @end deftp +@node Basic functions +@section Basic functions + @noindent To work with MPIs, storage must be allocated and released for the numbers. This can be done with one of these functions: - @deftypefun gcry_mpi_t gcry_mpi_new (@w{unsigned int @var{nbits}}) Allocate a new MPI object, initialize it to 0 and initially allocate @@ -1857,6 +2278,9 @@ small values (usually up to the word size of the CPU). Swap the values of @var{a} and @var{b}. @end deftypefun +@node MPI formats +@section MPI formats + @noindent The following functions are used to convert between an external representation of an MPI and the internal one of Libgcrypt. @@ -1915,6 +2339,9 @@ number of bytes stored in this buffer will be stored in the variable @var{nbytes} points to, unless @var{nbytes} is @code{NULL}. @end deftypefun +@node Calculations +@section Calculations + @noindent Basic arithmetic operations: @@ -2003,6 +2430,8 @@ Return true if the inverse exists. @end deftypefun +@node Comparisons +@section Comparisons @noindent The next 2 functions are used to compare MPIs: @@ -2023,11 +2452,13 @@ negative for @var{u} < @var{v}. @end deftypefun +@node Bit manipulations +@section Bit manipulations + @noindent There are a couple of functions to get information on arbitrary bits in an MPI and to set or clear them: - @deftypefun {unsigned int} gcry_mpi_get_nbits (@w{gcry_mpi_t @var{a}}) Return the number of bits required to represent @var{a}. @@ -2064,6 +2495,8 @@ Shift the value of @var{a} by @var{n} bits to the right and store the result in @var{x}. @end deftypefun +@node Misc +@section Misc @noindent The remaining MPI functions take care of very special properties of the @@ -2103,242 +2536,51 @@ currently useless as no flags are allowed. Return true when the @var{flag} is set for @var{a}. @end deftypefun +@node Utilities +@chapter Utilities +@menu +* Memory allocation:: Functions related with memory allocation. +@end menu +@node Memory allocation +@section Memory allocation -@c ********************************************************** -@c ******************* Utilities ************************** -@c ********************************************************** -@node Utilities -@chapter Utilities +@deftypefun void *gcry_malloc (size_t @var{n}) -Helper functions. +This function tries to allocate @var{n} bytes of memory. On success +it returns a pointer to the memory area, in an out-of-core condition, +it returns NULL. +@end deftypefun -@c <funcprototype> -@c <funcdef>int <function>gcry_control</function></funcdef> -@c <paramdef>enum gcry_ctl_cmds<parameter>cmd</parameter></paramdef> -@c <paramdef><parameter>...</parameter></paramdef> -@c </funcprototype> -@c </funcsynopsis> -@c </refsynopsisdiv> -@c -@c <refsect1><title>Description</title> -@c <para> -@c <indexterm><primary>gcry_control</primary></indexterm> -@c This function is used to control various aspects of &libgcrypt; -@c FIXME: Explain all commands here. -@c </para> -@c </refentry> -@c -@c -@c -@c -@c -@c <refentry> -@c <refnamediv> -@c <refname>gcry_set_allocation_handler</refname> -@c <refname>gcry_set_outofcore_handler</refname> -@c <refpurpose>Use application defined malloc functions</refpurpose> -@c </refnamediv> -@c -@c <refsynopsisdiv> -@c <funcsynopsis> -@c <funcsynopsisinfo> -@c #include <gcrypt.h> -@c </funcsynopsisinfo> -@c <funcprototype> -@c <funcdef>void <function>gcry_set_allocation_handler</></funcdef> -@c <paramdef>void *(*<parameter>alloc_func</>)(size_t n)</paramdef> -@c <paramdef>void *(*<parameter>alloc_secure_func</>)(size_t n)</paramdef> -@c <paramdef>int (*<parameter>is_secure_func</>)(const void *p)</paramdef> -@c <paramdef>void *(*<parameter>realloc_func</>)(void *p, size_t n)</paramdef> -@c <paramdef>void (*<parameter>free_func</>)(void *p)</paramdef> -@c </funcprototype> -@c <funcprototype> -@c <funcdef>void <function>gcry_set_outofcore_handler</></funcdef> -@c -@c <paramdef>int (*<parameter>h</>)( void*, size_t, unsigned int ), -@c void *opaque )</paramdef> -@c </funcprototype> -@c </funcsynopsis> -@c </refsynopsisdiv> -@c -@c <refsect1><title>Description</title> -@c <para> -@c <indexterm><primary>gcry_set_allocation_handler</primary></indexterm> -@c <indexterm><primary>gcry_set_outofcore_handler</primary></indexterm> -@c -@c FIXME -@c </para> -@c </refentry> -@c -@c -@c <refentry> -@c <refnamediv> -@c <refname>gcry_set_fatalerror_handler</refname> -@c <refpurpose>change the default fatal error handler</refpurpose> -@c </refnamediv> -@c -@c <refsynopsisdiv> -@c <funcsynopsis> -@c <funcsynopsisinfo> -@c #include <gcrypt.h> -@c </funcsynopsisinfo> -@c <funcprototype> -@c <funcdef>void <function>gcry_set_fatalerror_handler</></funcdef> -@c <paramdef>void (*<parameter>func</>)( -@c void *, int, const char*)</paramdef> -@c <paramdef>void *<parameter>opaque</></paramdef> -@c </funcprototype> -@c </funcsynopsis> -@c </refsynopsisdiv> -@c -@c <refsect1><title>Description</title> -@c <para> -@c <indexterm><primary>gcry_set_fatalerror_handler</primary></indexterm> -@c At certain places the &libgcrypt; may need to call a fatal error function -@c which does terminate the process. To allow an application to do -@c some emergency cleanup, it may register a fatal error handler with -@c the library. This handler is assumed to terminate the application; -@c however if it returns &libgcrypt; will abort anyway. -@c </para> -@c <para> -@c The handler is called with the opaque value registered here, an -@c errorcode from &libgcrypt; and some descriptive text string. -@c </para> -@c </refentry> -@c -@c -@c <refentry> -@c <refnamediv> -@c <refname>gcry_set_gettext_handler</refname> -@c <refpurpose>Change the default gettext function</refpurpose> -@c </refnamediv> -@c -@c <refsynopsisdiv> -@c <funcsynopsis> -@c <funcsynopsisinfo> -@c #include <gcrypt.h> -@c </funcsynopsisinfo> -@c <funcprototype> -@c <funcdef>void <function>gcry_set_gettext_handler</></funcdef> -@c <paramdef>const char *(*<parameter>func</>)(const char*)</paramdef> -@c <paramdef>void *<parameter>opaque</></paramdef> -@c </funcprototype> -@c </funcsynopsis> -@c </refsynopsisdiv> -@c -@c <refsect1><title>Description</title> -@c <para> -@c <indexterm><primary>gcry_set_log_handler</primary></indexterm> -@c FIXME!! -@c </para> -@c </refentry> -@c -@c -@c -@c <!-- -@c void gcry_set_log_handler( void (*f)(void*,int, const char*, va_list ), -@c void -@c *opaque -@c ); -@c --> -@c -@c <refentry> -@c <refnamediv> -@c <refname>gcry_set_log_handler</refname> -@c <refpurpose>Change the default logging function</refpurpose> -@c </refnamediv> -@c -@c <refsynopsisdiv> -@c <funcsynopsis> -@c <funcsynopsisinfo> -@c #include <gcrypt.h> -@c </funcsynopsisinfo> -@c <funcprototype> -@c <funcdef>void <function>gcry_set_log_handler</></funcdef> -@c <paramdef>void (*<parameter>func</>) -@c (void*, int, const char*, va_list)</paramdef> -@c <paramdef>void *<parameter>opaque</></paramdef> -@c </funcprototype> -@c </funcsynopsis> -@c </refsynopsisdiv> -@c -@c <refsect1><title>Description</title> -@c <para> -@c <indexterm><primary>gcry_set_log_handler</primary></indexterm> -@c &libgcrypt; has it;s own logging functions. Applications which -@c need to use their own, should provide a log function to &libgcrypt; -@c so that it will use this function instead. -@c -@c Fixme: Describe how this is intended to work. -@c </para> -@c </refentry> -@c -@c <!-- -@c void *gcry_malloc( size_t n ); -@c void *gcry_calloc( size_t n, size_t m ); -@c void *gcry_malloc_secure( size_t n ); -@c void *gcry_calloc_secure( size_t n, size_t m ); -@c void *gcry_realloc( void *a, size_t n ); -@c void *gcry_xmalloc( size_t n ); -@c void *gcry_xcalloc( size_t n, size_t m ); -@c void *gcry_xmalloc_secure( size_t n ); -@c void *gcry_xcalloc_secure( size_t n, size_t m ); -@c void *gcry_xrealloc( void *a, size_t n ); -@c char *gcry_xstrdup( const char * a); -@c void gcry_free( void *a ); -@c int gcry_is_secure( const void *a ); -@c --> -@c -@c <refentry> -@c <refnamediv> -@c <refname>gcry_malloc</refname> -@c <refname>gcry_calloc</refname> -@c <refname>gcry_malloc_secure</refname> -@c <refname>gcry_calloc_secure</refname> -@c <refname>gcry_realloc</refname> -@c <refname>gcry_xmalloc</refname> -@c <refname>gcry_xcalloc</refname> -@c <refname>gcry_xmalloc_secure</refname> -@c <refname>gcry_xcalloc_secure</refname> -@c <refname>gcry_xrealloc</refname> -@c <refname>gcry_xstrdup</refname> -@c -@c <!-- WORk WORK --> -@c <refname>gcry_malloc</refname> -@c <refname>gcry_malloc</refname> -@c -@c <refpurpose>Change the default logging function</refpurpose> -@c </refnamediv> -@c -@c <refsynopsisdiv> -@c <funcsynopsis> -@c <funcsynopsisinfo> -@c #include <gcrypt.h> -@c </funcsynopsisinfo> -@c <funcprototype> -@c <funcdef>void <function>gcry_set_log_handler</></funcdef> -@c <paramdef>void (*<parameter>func</>) -@c (void*, int, const char*, va_list)</paramdef> -@c <paramdef>void *<parameter>opaque</></paramdef> -@c </funcprototype> -@c </funcsynopsis> -@c </refsynopsisdiv> -@c -@c <refsect1><title>Description</title> -@c <para> -@c <indexterm><primary>gcry_set_log_handler</primary></indexterm> -@c &libgcrypt; has it;s own logging functions. Applications which -@c need to use their own, should provide a log function to &libgcrypt; -@c so that it will use this function instead. -@c -@c Fixme: Describe how this is intended to work. -@c </para> -@c </refentry> -@c -@c +@deftypefun void *gcry_malloc_secure (size_t @var{n}) +Like @code{gcry_malloc}, but uses secure memory. +@end deftypefun + +@deftypefun void *gcry_calloc (size_t @var{n}) + +This function tries to allocate @var{n} bytes of cleared memory +(i.e. memory that is initialized with zero bytes). On success it +returns a pointer to the memory area, in an out-of-core condition, it +returns NULL. +@end deftypefun + +@deftypefun void *gcry_calloc_secure (size_t @var{n}) +Like @code{gcry_calloc}, but uses secure memory. +@end deftypefun + +@deftypefun void *gcry_realloc (void *@var{p}, size_t @var{n}) +This function tries to resize the memory area pointed to by @var{p} to +@var{n} bytes. On success it returns a pointer to the new memory +area, in an out-of-core condition, it returns NULL. Depending on +wether the memory pointed to by @var{p} is secure memory or not, +gcry_realloc tries to use secure memory as well. +@end deftypefun + +@deftypefun void gcry_free (void *@var{p}) +Release the memory area pointed to by @var{p}. +@end deftypefun @c ********************************************************** @c ******************* Errors **************************** @@ -2384,9 +2626,6 @@ 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_EOF -This value indicates the end of a list, buffer or file. - @item GPG_ERR_PUBKEY_ALGO Invalid public key algorithm. @@ -2433,9 +2672,6 @@ Out of core; not enough memory available to perform operation. Internal error. This is most likely a bug in Libgcrypt or due to an incomplete build or installation. -@item GPG_ERR_EOF = 64 FIXME -End-of-file condition. - @item GPG_ERR_INV_OBJ An object is not valid. |