Removed the module registration interface
[libgcrypt.git] / doc / gcrypt.texi
index e328994..14f6fd1 100644 (file)
@@ -12,7 +12,7 @@ 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, 2006, 2007, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -28,6 +28,23 @@ section entitled ``GNU General Public License''.
 * libgcrypt: (gcrypt).  Cryptographic function library.
 @end direntry
 
+@c A couple of macros with no effect on texinfo
+@c but used by the yat2m processor.
+@macro manpage {a}
+@end macro
+@macro mansect {a}
+@end macro
+@macro manpause
+@end macro
+@macro mancont
+@end macro
+
+@c
+@c Printing stuff taken from gcc.
+@c
+@macro gnupgtabopt{body}
+@code{\body\}
+@end macro
 
 
 @c
@@ -68,11 +85,13 @@ section entitled ``GNU General Public License''.
 * Symmetric cryptography::       How to use symmetric cryptography.
 * Public Key cryptography::      How to use public key cryptography.
 * Hashing::                      How to use hash and MAC algorithms.
+* Key Derivation::               How to derive keys from strings
 * Random Numbers::               How to work with random numbers.
 * S-expressions::                How to manage S-expressions.
 * MPI library::                  How to work with multi-precision-integers.
 * Prime numbers::                How to use the Prime number related functions.
 * Utilities::                    Utility functions.
+* Tools::                        Utility tools
 * Architecture::                 How Libgcrypt works internally.
 
 Appendices
@@ -219,7 +238,7 @@ Certain parts of gcrypt.h may be excluded by defining these macros:
 Do not define the shorthand macros @code{mpi_*} for @code{gcry_mpi_*}.
 
 @item GCRYPT_NO_DEPRECATED
-Do not include defintions for deprecated features.  This is useful to
+Do not include definitions for deprecated features.  This is useful to
 make sure that no deprecated features are used.
 @end table
 
@@ -352,7 +371,7 @@ memory is not a problem, you should initialize Libgcrypt this way:
       fputs ("libgcrypt version mismatch\n", stderr);
       exit (2);
     @}
-        
+
   /* Disable secure memory.  */
   gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
 
@@ -383,7 +402,7 @@ and freed memory, you need to initialize Libgcrypt this way:
   gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
 
   /* ... If required, other initialization goes here.  Note that the
-     process might still be running with increased privileges and that 
+     process might still be running with increased privileges and that
      the secure memory has not been intialized.  */
 
   /* Allocate a pool of 16k secure memory.  This make the secure memory
@@ -410,7 +429,7 @@ want to check for finished initialization using:
     @{
       fputs ("libgcrypt has not been initialized\n", stderr);
       abort ();
-    @}       
+    @}
 @end example
 
 Instead of terminating the process, the library may instead print a
@@ -422,7 +441,7 @@ multi-threading below for more pitfalls.
 @node Multi-Threading
 @section Multi-Threading
 
-As mentioned earlier, the Libgcrypt library is 
+As mentioned earlier, the Libgcrypt library is
 thread-safe if you adhere to the following requirements:
 
 @itemize @bullet
@@ -454,8 +473,18 @@ 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.
+pthread.
+
+If you use pthread and your applications forks and does not directly
+call exec (even calling stdio functions), all kind of problems may
+occur.  Future versions of Libgcrypt will try to cleanup using
+pthread_atfork but even that may lead to problems.  This is a common
+problem with almost all applications using pthread and fork.
+
+Note that future versions of Libgcrypt will drop this flexible thread
+support and instead only support the platforms standard thread
+implementation.
+
 
 @item
 The function @code{gcry_check_version} must be called before any other
@@ -498,7 +527,12 @@ This macro defines the following (static) symbols:
 
 After including this macro, @code{gcry_control()} shall be used with a
 command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the
-thread callback structure named ``gcry_threads_pth''.
+thread callback structure named ``gcry_threads_pth''.  Example:
+
+@smallexample
+  ret = gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pth);
+@end smallexample
+
 
 @item GCRY_THREAD_OPTION_PTHREAD_IMPL
 
@@ -509,7 +543,13 @@ This macro defines the following (static) symbols:
 
 After including this macro, @code{gcry_control()} shall be used with a
 command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the
-thread callback structure named ``gcry_threads_pthread''.
+thread callback structure named ``gcry_threads_pthread''.  Example:
+
+@smallexample
+  ret = gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pthread);
+@end smallexample
+
+
 @end table
 
 Note that these macros need to be terminated with a semicolon.  Keep
@@ -533,18 +573,18 @@ explicitly.  Three alternative mechanisms are provided to switch
 Libgcrypt into this mode:
 
 @itemize
-@item 
+@item
 If the file @file{/proc/sys/crypto/fips_enabled} exists and contains a
 numeric value other than @code{0}, Libgcrypt is put into FIPS mode at
 initialization time.  Obviously this works only on systems with a
 @code{proc} file system (i.e. GNU/Linux).
 
-@item 
+@item
 If the file @file{/etc/gcrypt/fips_enabled} exists, Libgcrypt is put
 into FIPS mode at initialization time.  Note that this filename is
 hardwired and does not depend on any configuration options.
 
-@item 
+@item
 If the application requests FIPS mode using the control command
 @code{GCRYCTL_FORCE_FIPS_MODE}.  This must be done prior to any
 initialization (i.e. before @code{gcry_check_version}).
@@ -574,7 +614,6 @@ If the logging verbosity level of Libgcrypt has been set to at least
 
 @menu
 * Controlling the library::     Controlling Libgcrypt's behavior.
-* Modules::                     Description of extension modules.
 * Error Handling::              Error codes and such.
 @end menu
 
@@ -589,11 +628,12 @@ arguments can or have to be provided.
 
 @table @code
 @item GCRYCTL_ENABLE_M_GUARD; Arguments: none
-This command enables the built-in memory guard.  It must not be used to
-activate the memory guard after the memory management has already been
-used; therefore it can ONLY be used at initialization time.  Note that
-the memory guard is NOT used when the user of the library has set his
-own memory management callbacks.
+This command enables the built-in memory guard.  It must not be used
+to activate the memory guard after the memory management has already
+been used; therefore it can ONLY be used before
+@code{gcry_check_version}.  Note that the memory guard is NOT used
+when the user of the library has set his own memory management
+callbacks.
 
 @item GCRYCTL_ENABLE_QUICK_RANDOM; Arguments: none
 This command inhibits the use the very secure random quality level
@@ -633,7 +673,7 @@ mode this command has no effect at all.
 
 Many applications do not require secure memory, so they should disable
 it right away.  This command should be executed right after
-@code{gcry_check_version}. 
+@code{gcry_check_version}.
 
 @item GCRYCTL_INIT_SECMEM; Arguments: int nbytes
 This command is used to allocate a pool of secure memory and thus
@@ -659,9 +699,9 @@ subsystem. This command should be run right after
 @code{gcry_check_version}.
 
 @item GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none
-Postpone warning messages from the secure memory subsystem. 
+Postpone warning messages from the secure memory subsystem.
 @xref{sample-use-suspend-secmem,,the initialization example}, on how to
-use it. 
+use it.
 
 @item GCRYCTL_RESUME_SECMEM_WARN; Arguments: none
 Resume warning messages from the secure memory subsystem.
@@ -736,7 +776,7 @@ certain internal subsystems running.  The common and suggested way to
 do this basic intialization is by calling gcry_check_version.
 
 @item GCRYCTL_INITIALIZATION_FINISHED; Arguments: none
-This command tells the libray that the application has finished the
+This command tells the library that the application has finished the
 intialization.
 
 @item GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none
@@ -802,30 +842,20 @@ This may be used at anytime to have the library run all implemented
 self-tests.  It works in standard and in FIPS mode.  Returns 0 on
 success or an error code on failure.
 
+@item GCRYCTL_DISABLE_HWF; Arguments: const char *name
+
+Libgcrypt detects certain features of the CPU at startup time.  For
+performace tests it is sometimes required not to use such a feature.
+This option may be used to disabale a certain feature; i.e. Libgcrypt
+behaves as if this feature has not been detected.  Note that the
+detection code might be run if the feature has been disabled.  This
+command must be used at initialization time; i.e. before calling
+@code{gcry_check_version}.
 
 @end table
 
 @end deftypefun
 
-@node Modules
-@section Modules
-
-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
-Libgcrypt until it is unregistered again.
-
 @c **********************************************************
 @c *******************  Errors  ****************************
 @c **********************************************************
@@ -1176,7 +1206,7 @@ diagnostic message to the user.
 
 
 @deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}})
-The function @code{gcry_strerror} returns a pointer to a statically
+The function @code{gcry_strsource} 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.
@@ -1190,7 +1220,7 @@ above:
   gcry_cipher_hd_t handle;
   gcry_error_t err = 0;
 
-  err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, 
+  err = gcry_cipher_open (&handle, GCRY_CIPHER_AES,
                           GCRY_CIPHER_MODE_CBC, 0);
   if (err)
     @{
@@ -1208,7 +1238,7 @@ above:
 @chapter Handler Functions
 
 Libgcrypt makes it possible to install so called `handler functions',
-which get called by Libgcrypt in case of certain events. 
+which get called by Libgcrypt in case of certain events.
 
 @menu
 * Progress handler::            Using a progress handler function.
@@ -1380,7 +1410,6 @@ building blocks provided by Libgcrypt.
 
 @menu
 * Available ciphers::           List of ciphers supported by the library.
-* Cipher modules::              How to work with cipher modules.
 * Available cipher modes::      List of cipher modes supported by the library.
 * Working with cipher handles::  How to perform operations related to cipher handles.
 * General cipher functions::    General cipher functions independent of cipher handles.
@@ -1411,7 +1440,7 @@ are ignored.
 @item GCRY_CIPHER_CAST5
 @cindex CAST5
 CAST128-5 block cipher algorithm.  The key size is 128 bits.
-       
+
 @item GCRY_CIPHER_BLOWFISH
 @cindex Blowfish
 The blowfish algorithm. The current implementation allows only for a key
@@ -1420,10 +1449,10 @@ size of 128 bits.
 @item GCRY_CIPHER_SAFER_SK128
 Reserved and not currently implemented.
 
-@item GCRY_CIPHER_DES_SK         
+@item GCRY_CIPHER_DES_SK
 Reserved and not currently implemented.
-@item  GCRY_CIPHER_AES        
+
+@item  GCRY_CIPHER_AES
 @itemx GCRY_CIPHER_AES128
 @itemx GCRY_CIPHER_RIJNDAEL
 @itemx GCRY_CIPHER_RIJNDAEL128
@@ -1432,27 +1461,27 @@ Reserved and not currently implemented.
 @cindex Advanced Encryption Standard
 AES (Rijndael) with a 128 bit key.
 
-@item  GCRY_CIPHER_AES192     
+@item  GCRY_CIPHER_AES192
 @itemx GCRY_CIPHER_RIJNDAEL192
 AES (Rijndael) with a 192 bit key.
 
-@item  GCRY_CIPHER_AES256 
+@item  GCRY_CIPHER_AES256
 @itemx GCRY_CIPHER_RIJNDAEL256
 AES (Rijndael) with a 256 bit key.
-    
+
 @item  GCRY_CIPHER_TWOFISH
 @cindex 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   
+
+@item  GCRY_CIPHER_ARCFOUR
 @cindex Arcfour
 @cindex RC4
 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. 
+avoid a couple of weaknesses.
 
 @item  GCRY_CIPHER_DES
 @cindex DES
@@ -1487,118 +1516,6 @@ The Camellia cipher by NTT.  See
 
 @end table
 
-@node Cipher modules
-@section Cipher modules
-
-Libgcrypt makes it possible to load additional `cipher modules'; these
-ciphers can be used just like the cipher algorithms that are built
-into the library directly.  For an introduction into extension
-modules, see @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
 
@@ -1610,7 +1527,7 @@ set, this mode may be used to bypass the actual encryption.
 
 @item GCRY_CIPHER_MODE_ECB
 @cindex ECB, Electronic Codebook mode
-Electronic Codebook mode.  
+Electronic Codebook mode.
 
 @item GCRY_CIPHER_MODE_CFB
 @cindex CFB, Cipher Feedback mode
@@ -1632,6 +1549,20 @@ Output Feedback mode.
 @cindex CTR, Counter mode
 Counter mode.
 
+@item  GCRY_CIPHER_MODE_AESWRAP
+@cindex AES-Wrap mode
+This mode is used to implement the AES-Wrap algorithm according to
+RFC-3394.  It may be used with any 128 bit block length algorithm,
+however the specs require one of the 3 AES algorithms.  These special
+conditions apply: If @code{gcry_cipher_setiv} has not been used the
+standard IV is used; if it has been used the lower 64 bit of the IV
+are used as the Alternative Initial Value.  On encryption the provided
+output buffer must be 64 bit (8 byte) larger than the input buffer;
+in-place encryption is still allowed.  On decryption the output buffer
+may be specified 64 bit (8 byte) shorter than then input buffer.  As
+per specs the input length must be at least 128 bits and the length
+must be a multiple of 64 bits.
+
 @end table
 
 @node Working with cipher handles
@@ -1674,7 +1605,7 @@ useful when the key material is highly confidential.
 @item GCRY_CIPHER_ENABLE_SYNC
 @cindex sync mode (OpenPGP)
 This flag enables the CFB sync mode, which is a special feature of
-Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant. 
+Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant.
 See @code{gcry_cipher_sync}.
 @item GCRY_CIPHER_CBC_CTS
 @cindex cipher text stealing
@@ -1688,13 +1619,15 @@ 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
-@end deftypefun 
+@end deftypefun
 
 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}.
+It also zeroises all sensitive information associated with this cipher
+handle.
 @end deftypefun
 
 In order to use a handle for performing cryptographic operations, a
@@ -1703,11 +1636,11 @@ In order to use a handle for performing cryptographic operations, a
 @deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l})
 
 Set the key @var{k} used for encryption or decryption in the context
-denoted by the handle @var{h}.  The length @var{l} of the key @var{k}
-must match the required length of the algorithm set for this context or
-be in the allowed range for algorithms with variable key size.  The
-function checks this and returns an error if there is a problem.  A
-caller should always check for an error.
+denoted by the handle @var{h}.  The length @var{l} (in bytes) of the
+key @var{k} must match the required length of the algorithm set for
+this context or be in the allowed range for algorithms with variable
+key size.  The function checks this and returns an error if there is a
+problem.  A caller should always check for an error.
 
 @end deftypefun
 
@@ -1719,18 +1652,18 @@ value.  To set the IV or CTR, use these functions:
 @deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l})
 
 Set the initialization vector used for encryption or decryption. The
-vector is passed as the buffer @var{K} of length @var{l} and copied to
-internal data structures.  The function checks that the IV matches the
-requirement of the selected algorithm and mode. 
+vector is passed as the buffer @var{K} of length @var{l} bytes and
+copied to internal data structures.  The function checks that the IV
+matches the requirement of the selected algorithm and mode.
 @end deftypefun
 
 @deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, const void *@var{c}, size_t @var{l})
 
 Set the counter vector used for encryption or decryption. The counter
-is passed as the buffer @var{c} of length @var{l} and copied to
+is passed as the buffer @var{c} of length @var{l} bytes and copied to
 internal data structures.  The function checks that the counter
 matches the requirement of the selected algorithm (i.e., it must be
-the same size as the block size).  
+the same size as the block size).
 @end deftypefun
 
 @deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
@@ -1832,7 +1765,7 @@ information requested as @var{what}. The result is either returned as
 the return code of the function or copied to the provided @var{buffer}
 whose allocated length must be available in an integer variable with the
 address passed in @var{nbytes}.  This variable will also receive the
-actual used length of the buffer. 
+actual used length of the buffer.
 
 Here is a list of supported codes for @var{what}:
 
@@ -1842,22 +1775,51 @@ Here is a list of supported codes for @var{what}:
 Return the length of the key. If the algorithm supports multiple key
 lengths, the maximum supported value is returned.  The length is
 returned as number of octets (bytes) and not as number of bits in
-@var{nbytes}; @var{buffer} must be zero.
+@var{nbytes}; @var{buffer} must be zero.  Note that it is usually
+better to use the convenience function
+@code{gcry_cipher_get_algo_keylen}.
 
 @item GCRYCTL_GET_BLKLEN:
 Return the block length of the algorithm.  The length is returned as a
-number of octets in @var{nbytes}; @var{buffer} must be zero.
+number of octets in @var{nbytes}; @var{buffer} must be zero.  Note
+that it is usually better to use the convenience function
+@code{gcry_cipher_get_algo_blklen}.
 
 @item GCRYCTL_TEST_ALGO:
 Returns @code{0} when the specified algorithm is available for use.
 @var{buffer} and @var{nbytes} must be zero.
-@end table  
+
+@end table
 @c end constants for gcry_cipher_algo_info
 
 @end deftypefun
 @c end gcry_cipher_algo_info
 
+@deftypefun size_t gcry_cipher_get_algo_keylen (@var{algo})
+
+This function returns length of the key for algorithm @var{algo}.  If
+the algorithm supports multiple key lengths, the maximum supported key
+length is returned.  On error @code{0} is returned.  The key length is
+returned as number of octets.
+
+This is a convenience functions which should be preferred over
+@code{gcry_cipher_algo_info} because it allows for proper type
+checking.
+@end deftypefun
+@c end gcry_cipher_get_algo_keylen
+
+@deftypefun size_t gcry_cipher_get_algo_blklen (int @var{algo})
+
+This functions returns the blocklength of the algorithm @var{algo}
+counted in octets.  On error @code{0} is returned.
+
+This is a convenience functions which should be preferred over
+@code{gcry_cipher_algo_info} because it allows for proper type
+checking.
+@end deftypefun
+@c end gcry_cipher_get_algo_blklen
+
+
 @deftypefun {const char *} gcry_cipher_algo_name (int @var{algo})
 
 @code{gcry_cipher_algo_name} returns a string with the name of the
@@ -1898,11 +1860,8 @@ S-expressions.
 @menu
 * Available algorithms::        Algorithms supported by the library.
 * Used S-expressions::          Introduction into the used S-expression.
-* Public key modules::          How to work with public key modules.
 * Cryptographic Functions::     Functions for performing the cryptographic actions.
 * General public-key related Functions::  General functions, not implementing any cryptography.
-
-* AC Interface::                Alternative interface to public key functions.
 @end menu
 
 @node Available algorithms
@@ -2004,7 +1963,7 @@ but greatly improve the performance.  Either all of these optional
 parameters must be given or none of them.  They are mandatory for
 gcry_pk_testkey.
 
-Note that OpenSSL uses slighly different parameters: @math{q < p} and 
+Note that OpenSSL uses slighly different parameters: @math{q < p} and
  @math{u = q^{-1} \bmod p}.  To use these parameters you will need to
 swap the values and recompute @math{u}.  Here is example code to do this:
 
@@ -2139,144 +2098,13 @@ As usual the OIDs may optionally be prefixed with the string @code{OID.}
 or @code{oid.}.
 
 
-
-@node Public key modules
-@section Public key modules
-
-Libgcrypt makes it possible to load additional `public key
-modules'; these public key algorithms can be used just like the
-algorithms that are built into the library directly.  For an
-introduction into extension modules, see @xref{Modules}.
-
-@deftp {Data type} gcry_pk_spec_t
-This is the `module specification structure' needed for registering
-public key modules, which has to be filled in by the user before it
-can be used to register a module.  It contains the following members:
-
-@table @code
-@item const char *name
-The primary name of this algorithm.
-@item char **aliases
-A list of strings that are `aliases' for the algorithm.  The list
-must be terminated with a NULL element.
-@item const char *elements_pkey
-String containing the one-letter names of the MPI values contained in
-a public key.
-@item const char *element_skey
-String containing the one-letter names of the MPI values contained in
-a secret key.
-@item const char *elements_enc
-String containing the one-letter names of the MPI values that are the
-result of an encryption operation using this algorithm.
-@item const char *elements_sig
-String containing the one-letter names of the MPI values that are the
-result of a sign operation using this algorithm.
-@item const char *elements_grip
-String containing the one-letter names of the MPI values that are to
-be included in the `key grip'.
-@item int use
-The bitwise-OR of the following flags, depending on the abilities of
-the algorithm:
-@table @code
-@item GCRY_PK_USAGE_SIGN
-The algorithm supports signing and verifying of data.
-@item GCRY_PK_USAGE_ENCR
-The algorithm supports the encryption and decryption of data.
-@end table
-@item gcry_pk_generate_t generate
-The function responsible for generating a new key pair.  See below for
-a description of this type.
-@item gcry_pk_check_secret_key_t check_secret_key
-The function responsible for checking the sanity of a provided secret
-key.  See below for a description of this type.
-@item gcry_pk_encrypt_t encrypt
-The function responsible for encrypting data.  See below for a
-description of this type.
-@item gcry_pk_decrypt_t decrypt
-The function responsible for decrypting data.  See below for a
-description of this type.
-@item gcry_pk_sign_t sign
-The function responsible for signing data.  See below for a description
-of this type.
-@item gcry_pk_verify_t verify
-The function responsible for verifying that the provided signature
-matches the provided data.  See below for a description of this type.
-@item gcry_pk_get_nbits_t get_nbits
-The function responsible for returning the number of bits of a provided
-key.  See below for a description of this type.
-@end table
-@end deftp
-
-@deftp {Data type} gcry_pk_generate_t
-Type for the `generate' function, defined as: gcry_err_code_t
-(*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long
-use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors)
-@end deftp
-
-@deftp {Data type} gcry_pk_check_secret_key_t
-Type for the `check_secret_key' function, defined as: gcry_err_code_t
-(*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey)
-@end deftp
-
-@deftp {Data type} gcry_pk_encrypt_t
-Type for the `encrypt' function, defined as: gcry_err_code_t
-(*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
-gcry_mpi_t *pkey, int flags)
-@end deftp
-
-@deftp {Data type} gcry_pk_decrypt_t
-Type for the `decrypt' function, defined as: gcry_err_code_t
-(*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data,
-gcry_mpi_t *skey, int flags)
-@end deftp
-
-@deftp {Data type} gcry_pk_sign_t
-Type for the `sign' function, defined as: gcry_err_code_t
-(*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
-gcry_mpi_t *skey)
-@end deftp
-
-@deftp {Data type} gcry_pk_verify_t
-Type for the `verify' function, defined as: gcry_err_code_t
-(*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data,
-gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev)
-@end deftp
-
-@deftp {Data type} gcry_pk_get_nbits_t
-Type for the `get_nbits' function, defined as: unsigned
-(*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey)
-@end deftp
-
-@deftypefun gcry_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module})
-
-Register a new public key module whose specification can be found in
-@var{pubkey}.  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_pk_unregister (gcry_module_t @var{module})
-Unregister the public key module identified by @var{module}, which
-must have been registered with gcry_pk_register.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_pk_list (int *@var{list}, int *@var{list_length})
-Get a list consisting of the IDs of the loaded pubkey modules.  If
-@var{list} is zero, write the number of loaded pubkey 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 pubkey modules than
-*@var{list_length}, *@var{list_length} is updated to the correct
-number.
-@end deftypefun
-
 @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
-reasons. 
+reasons.
 
 @noindent
 
@@ -2286,7 +2114,12 @@ sub-S-expression named `flags'; the following flags are known:
 
 @table @code
 @item pkcs1
-Use PKCS#1 block type 2 padding.
+Use PKCS#1 block type 2 padding for encryption, block type 1 padding
+for signing.
+@item oaep
+Use RSA-OAEP padding for encryption.
+@item pss
+Use RSA-PSS padding for signing.
 @item no-blinding
 Do not use a technique called `blinding', which is used by default in
 order to prevent leaking of secret information.  Blinding is only
@@ -2313,19 +2146,19 @@ operation, like e.g. padding rules.
 If you don't want to let Libgcrypt handle the padding, you must pass an
 appropriate MPI using this expression for @var{data}:
 
-@example 
+@example
 (data
   (flags raw)
   (value @var{mpi}))
 @end example
 
 @noindent
-This has the same semantics as the old style MPI only way.  @var{MPI} is
-the actual data, already padded appropriate for your protocol.  Most
-systems however use PKCS#1 padding and so you can use this S-expression
-for @var{data}:
+This has the same semantics as the old style MPI only way.  @var{MPI}
+is the actual data, already padded appropriate for your protocol.
+Most RSA based systems however use PKCS#1 padding and so you can use
+this S-expression for @var{data}:
 
-@example 
+@example
 (data
   (flags pkcs1)
   (value @var{block}))
@@ -2388,8 +2221,17 @@ element:
 @end example
 
 @noindent
-Note that this function currently does not know of any padding
-methods and the caller must do any un-padding on his own.
+This function does not remove padding from the data by default.  To
+let Libgcrypt remove padding, give a hint in `flags' telling which
+padding method was used when encrypting:
+
+@example
+(flags @var{padding-method})
+@end example
+
+@noindent
+Currently @var{padding-method} is either @code{pkcs1} for PKCS#1 block
+type 2 padding, or @code{oaep} for RSA-OAEP padding.
 
 @noindent
 The function returns 0 on success or an error code.  The variable at the
@@ -2420,7 +2262,7 @@ private key @var{skey} and place it into the variable at the address of
 with just one MPI or a modern and more versatile S-expression which
 allows to let Libgcrypt handle padding:
 
-@example 
+@example
  (data
   (flags pkcs1)
   (hash @var{hash-algo} @var{block}))
@@ -2431,9 +2273,9 @@ This example requests to sign the data in @var{block} after applying
 PKCS#1 block type 1 style padding.  @var{hash-algo} is a string with the
 hash algorithm to be encoded into the signature, this may be any hash
 algorithm name as supported by Libgcrypt.  Most likely, this will be
-"sha1", "rmd160" or "md5".  It is obvious that the length of @var{block}
-must match the size of that message digests; the function checks that
-this and other constraints are valid.
+"sha256" or "sha1".  It is obvious that the length of @var{block} must
+match the size of that message digests; the function checks that this
+and other constraints are valid.
 
 @noindent
 If PKCS#1 padding is not required (because the caller does already
@@ -2492,7 +2334,7 @@ the function in @var{sig}.
 
 @noindent
 The result is 0 for success (i.e. the data matches the signature), or an
-error code where the most relevant code is @code{GCRYERR_BAD_SIGNATURE}
+error code where the most relevant code is @code{GCRY_ERR_BAD_SIGNATURE}
 to indicate that the signature does not match the provided data.
 
 @end deftypefun
@@ -2569,9 +2411,9 @@ algorithm. This may be 0 for "don't care" or the bit-wise OR of these
 flags:
 
 @table @code
-@item GCRY_PK_USAGE_SIGN 
+@item GCRY_PK_USAGE_SIGN
 Algorithm is usable for signing.
-@item GCRY_PK_USAGE_ENCR 
+@item GCRY_PK_USAGE_ENCR
 Algorithm is usable for encryption.
 @end table
 
@@ -2689,7 +2531,7 @@ If this parameter is not used, Libgcrypt uses for historic reasons
 
 @item qbits
 This is only meanigful for DSA keys.  If it is given the DSA key is
-generated with a Q parameyer of this size.  If it is not given or zero 
+generated with a Q parameyer of this size.  If it is not given or zero
 Q is deduced from NBITS in this way:
 @table @samp
 @item 512 <= N <= 1024
@@ -2708,10 +2550,10 @@ are allowed.  When specifying Q all values of N in the range 512 to
 15680 are valid as long as they are multiples of 8.
 
 @item transient-key
-This is only meaningful for RSA and DSA keys.  This is a flag with no
-value.  If given the RSA or DSA key is created using a faster and a
-somewhat less secure random number generator.  This flag may be used
-for keys which are only used for a short time and do not require full
+This is only meaningful for RSA, DSA, ECDSA, and ECDH keys.  This is a flag
+with no value.  If given the key is created using a faster and a
+somewhat less secure random number generator.  This flag may be used for
+keys which are only used for a short time or per-message and do not require full
 cryptographic strength.
 
 @item domain
@@ -2829,547 +2671,10 @@ Note that the order of the elements is not defined, e.g. the private
 key may be stored before the public key. @var{n1 n2 ... nn} is a list
 of prime numbers used to composite @var{p-mpi}; this is in general not
 a very useful information and only available if the key generation
-algorithm provides them.  
+algorithm provides them.
 @end deftypefun
 @c end gcry_pk_genkey
 
-@node AC Interface
-@section Alternative Public Key Interface
-
-This section documents the alternative interface to asymmetric
-cryptography (ac) that is not based on S-expressions, but on native C
-data structures.  As opposed to the pk interface described in the
-former chapter, this one follows an open/use/close paradigm like other
-building blocks of the library.
-
-@strong{This interface has a few known problems; most noteworthy an
-inherent tendency to leak memory.  It might not be available in
-forthcoming versions of Libgcrypt.}
-
-
-@menu
-* Available asymmetric algorithms::  List of algorithms supported by the library.
-* Working with sets of data::   How to work with sets of data.
-* Working with IO objects::     How to work with IO objects.
-* Working with handles::        How to use handles.
-* Working with keys::           How to work with keys.
-* Using cryptographic functions::  How to perform cryptographic operations.
-* Handle-independent functions::  General functions independent of handles.
-@end menu
-
-@node Available asymmetric algorithms
-@subsection Available asymmetric algorithms
-
-Libgcrypt supports the RSA (Rivest-Shamir-Adleman)
-algorithms as well as DSA (Digital Signature Algorithm) and Elgamal.
-The versatile interface allows to add more algorithms in the future.
-
-@deftp {Data type} gcry_ac_id_t
-
-The following constants are defined for this type:
-
-@table @code
-@item GCRY_AC_RSA
-Rivest-Shamir-Adleman
-@item GCRY_AC_DSA
-Digital Signature Algorithm
-@item GCRY_AC_ELG
-Elgamal
-@item GCRY_AC_ELG_E
-Elgamal, encryption only.
-@end table
-@end deftp
-
-@node Working with sets of data
-@subsection Working with sets of data
-
-In the context of this interface the term `data set' refers to a list
-of `named MPI values' that is used by functions performing
-cryptographic operations; a named MPI value is a an MPI value,
-associated with a label.
-
-Such data sets are used for representing keys, since keys simply
-consist of a variable amount of numbers.  Furthermore some functions
-return data sets to the caller that are to be provided to other
-functions.
-
-This section documents the data types, symbols and functions that are
-relevant for working with data sets.
-
-@deftp {Data type} gcry_ac_data_t
-A single data set.
-@end deftp
-
-The following flags are supported:
-
-@table @code
-@item GCRY_AC_FLAG_DEALLOC
-Used for storing data in a data set.  If given, the data will be
-released by the library.  Note that whenever one of the ac functions
-is about to release objects because of this flag, the objects are
-expected to be stored in memory allocated through the Libgcrypt memory
-management.  In other words: gcry_free() is used instead of free().
-
-@item GCRY_AC_FLAG_COPY
-Used for storing/retrieving data in/from a data set.  If given, the
-library will create copies of the provided/contained data, which will
-then be given to the user/associated with the data set.
-@end table
-
-@deftypefun gcry_error_t gcry_ac_data_new (gcry_ac_data_t *@var{data})
-Creates a new, empty data set and stores it in @var{data}.
-@end deftypefun
-
-@deftypefun void gcry_ac_data_destroy (gcry_ac_data_t @var{data})
-Destroys the data set @var{data}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_set (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t @var{mpi})
-Add the value @var{mpi} to @var{data} with the label @var{name}.  If
-@var{flags} contains GCRY_AC_FLAG_COPY, the data set will contain
-copies of @var{name} and @var{mpi}.  If @var{flags} contains
-GCRY_AC_FLAG_DEALLOC or GCRY_AC_FLAG_COPY, the values
-contained in the data set will be deallocated when they are to be
-removed from the data set.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data})
-Create a copy of the data set @var{data} and store it in
-@var{data_cp}.  FIXME: exact semantics undefined.
-@end deftypefun
-
-@deftypefun {unsigned int} gcry_ac_data_length (gcry_ac_data_t @var{data})
-Returns the number of named MPI values inside of the data set
-@var{data}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t *@var{mpi})
-Store the value labelled with @var{name} found in @var{data} in
-@var{mpi}.  If @var{flags} contains GCRY_AC_FLAG_COPY, store a copy of
-the @var{mpi} value contained in the data set.  @var{mpi} may be NULL
-(this might be useful for checking the existence of an MPI with
-extracting it).
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t @var{data}, unsigned int flags, unsigned int @var{index}, const char **@var{name}, gcry_mpi_t *@var{mpi})
-Stores in @var{name} and @var{mpi} the named @var{mpi} value contained
-in the data set @var{data} with the index @var{idx}.  If @var{flags}
-contains GCRY_AC_FLAG_COPY, store copies of the values contained in
-the data set. @var{name} or @var{mpi} may be NULL.
-@end deftypefun
-
-@deftypefun void gcry_ac_data_clear (gcry_ac_data_t @var{data})
-Destroys any values contained in the data set @var{data}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_to_sexp (gcry_ac_data_t @var{data}, gcry_sexp_t *@var{sexp}, const char **@var{identifiers})
-This function converts the data set @var{data} into a newly created
-S-Expression, which is to be stored in @var{sexp}; @var{identifiers}
-is a NULL terminated list of C strings, which specifies the structure
-of the S-Expression.
-
-Example:
-
-If @var{identifiers} is a list of pointers to the strings ``foo'' and
-``bar'' and if @var{data} is a data set containing the values ``val1 =
-0x01'' and ``val2 = 0x02'', then the resulting S-Expression will look
-like this: (foo (bar ((val1 0x01) (val2 0x02))).
-@end deftypefun
-
-@deftypefun gcry_error gcry_ac_data_from_sexp (gcry_ac_data_t *@var{data}, gcry_sexp_t @var{sexp}, const char **@var{identifiers})
-This function converts the S-Expression @var{sexp} into a newly
-created data set, which is to be stored in @var{data};
-@var{identifiers} is a NULL terminated list of C strings, which
-specifies the structure of the S-Expression.  If the list of
-identifiers does not match the structure of the S-Expression, the
-function fails.
-@end deftypefun
-
-@node Working with IO objects
-@subsection Working with IO objects
-
-Note: IO objects are currently only used in the context of message
-encoding/decoding and encryption/signature schemes.
-
-@deftp {Data type} {gcry_ac_io_t}
-@code{gcry_ac_io_t} is the type to be used for IO objects.
-@end deftp
-
-IO objects provide an uniform IO layer on top of different underlying
-IO mechanisms; either they can be used for providing data to the
-library (mode is GCRY_AC_IO_READABLE) or they can be used for
-retrieving data from the library (mode is GCRY_AC_IO_WRITABLE).
-
-IO object need to be initialized by calling on of the following
-functions:
-
-@deftypefun void gcry_ac_io_init (gcry_ac_io_t *@var{ac_io}, gcry_ac_io_mode_t @var{mode}, gcry_ac_io_type_t @var{type}, ...);
-Initialize @var{ac_io} according to @var{mode}, @var{type} and the
-variable list of arguments.  The list of variable arguments to specify
-depends on the given @var{type}.
-@end deftypefun
-
-@deftypefun void gcry_ac_io_init_va (gcry_ac_io_t *@var{ac_io}, gcry_ac_io_mode_t @var{mode}, gcry_ac_io_type_t @var{type}, va_list @var{ap});
-Initialize @var{ac_io} according to @var{mode}, @var{type} and the
-variable list of arguments @var{ap}.  The list of variable arguments
-to specify depends on the given @var{type}.
-@end deftypefun
-
-The following types of IO objects exist:
-
-@table @code
-@item GCRY_AC_IO_STRING
-In case of GCRY_AC_IO_READABLE the IO object will provide data from a
-memory string.  Arguments to specify at initialization time:
-@table @code
-@item unsigned char *
-Pointer to the beginning of the memory string
-@item size_t
-Size of the memory string
-@end table
-In case of GCRY_AC_IO_WRITABLE the object will store retrieved data in
-a newly allocated memory string.  Arguments to specify at
-initialization time:
-@table @code
-@item unsigned char **
-Pointer to address, at which the pointer to the newly created memory
-string is to be stored
-@item size_t *
-Pointer to address, at which the size of the newly created memory
-string is to be stored
-@end table
-
-@item GCRY_AC_IO_CALLBACK
-In case of GCRY_AC_IO_READABLE the object will forward read requests
-to a provided callback function.  Arguments to specify at
-initialization time:
-@table @code
-@item gcry_ac_data_read_cb_t
-Callback function to use
-@item void *
-Opaque argument to provide to the callback function
-@end table
-In case of GCRY_AC_IO_WRITABLE the object will forward write requests
-to a provided callback function.  Arguments to specify at
-initialization time:
-@table @code
-@item gcry_ac_data_write_cb_t
-Callback function to use
-@item void *
-Opaque argument to provide to the callback function
-@end table
-@end table
-
-@node Working with handles
-@subsection Working with handles
-
-In order to use an algorithm, an according handle must be created.
-This is done using the following function:
-
-@deftypefun gcry_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle}, int @var{algorithm}, int @var{flags})
-
-Creates a new handle for the algorithm @var{algorithm} and stores it
-in @var{handle}.  @var{flags} is not used currently.
-
-@var{algorithm} must be a valid algorithm ID, see @xref{Available
-asymmetric algorithms}, for a list of supported algorithms and the
-according constants.  Besides using the listed constants directly, the
-functions @code{gcry_pk_name_to_id} may be used to convert the textual
-name of an algorithm into the according numeric ID.
-@end deftypefun
-
-@deftypefun void gcry_ac_close (gcry_ac_handle_t @var{handle})
-Destroys the handle @var{handle}.
-@end deftypefun
-
-@node Working with keys
-@subsection Working with keys
-
-@deftp {Data type} gcry_ac_key_type_t
-Defined constants:
-
-@table @code
-@item GCRY_AC_KEY_SECRET
-Specifies a secret key.
-@item GCRY_AC_KEY_PUBLIC
-Specifies a public key.
-@end table
-@end deftp
-
-@deftp {Data type} gcry_ac_key_t
-This type represents a single `key', either a secret one or a public
-one.
-@end deftp
-
-@deftp {Data type} gcry_ac_key_pair_t
-This type represents a `key pair' containing a secret and a public key.
-@end deftp
-
-Key data structures can be created in two different ways; a new key
-pair can be generated, resulting in ready-to-use key.  Alternatively a
-key can be initialized from a given data set.
-
-@deftypefun gcry_error_t gcry_ac_key_init (gcry_ac_key_t *@var{key}, gcry_ac_handle_t @var{handle}, gcry_ac_key_type_t @var{type}, gcry_ac_data_t @var{data})
-Creates a new key of type @var{type}, consisting of the MPI values
-contained in the data set @var{data} and stores it in @var{key}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t @var{handle}, unsigned int @var{nbits}, void *@var{key_spec}, gcry_ac_key_pair_t *@var{key_pair}, gcry_mpi_t **@var{misc_data})
-
-Generates a new key pair via the handle @var{handle} of @var{NBITS}
-bits and stores it in @var{key_pair}.
-
-In case non-standard settings are wanted, a pointer to a structure of
-type @code{gcry_ac_key_spec_<algorithm>_t}, matching the selected
-algorithm, can be given as @var{key_spec}.  @var{misc_data} is not
-used yet.  Such a structure does only exist for RSA.  A description
-of the members of the supported structures follows.
-
-@table @code
-@item gcry_ac_key_spec_rsa_t
-@table @code
-@item gcry_mpi_t e
-Generate the key pair using a special @code{e}.  The value of @code{e}
-has the following meanings:
-@table @code
-@item = 0
-Let Libgcrypt decide what exponent should be used.
-@item = 1
-Request the use of a ``secure'' exponent; this is required by some
-specification to be 65537.
-@item > 2
-Try starting at this value until a working exponent is found.  Note
-that the current implementation leaks some information about the
-private key because the incrementation used is not randomized.  Thus,
-this function will be changed in the future to return a random
-exponent of the given size.
-@end table
-@end table
-@end table
-
-Example code:
-@example
-@{
-  gcry_ac_key_pair_t key_pair;
-  gcry_ac_key_spec_rsa_t rsa_spec;
-
-  rsa_spec.e = gcry_mpi_new (0);
-  gcry_mpi_set_ui (rsa_spec.e, 1);
-
-  err = gcry_ac_open  (&handle, GCRY_AC_RSA, 0);
-  assert (! err);
-
-  err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec,
-                                   &key_pair, NULL);
-  assert (! err);
-@}
-@end example
-@end deftypefun
-
-
-@deftypefun gcry_ac_key_t gcry_ac_key_pair_extract (gcry_ac_key_pair_t @var{key_pair}, gcry_ac_key_type_t @var{which})
-Returns the key of type @var{which} out of the key pair
-@var{key_pair}.
-@end deftypefun
-
-@deftypefun void gcry_ac_key_destroy (gcry_ac_key_t @var{key})
-Destroys the key @var{key}.
-@end deftypefun
-
-@deftypefun void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t @var{key_pair})
-Destroys the key pair @var{key_pair}.
-@end deftypefun
-
-@deftypefun gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t @var{key})
-Returns the data set contained in the key @var{key}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_key_test (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key})
-Verifies that the private key @var{key} is sane via @var{handle}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned int *@var{nbits})
-Stores the number of bits of the key @var{key} in @var{nbits} via @var{handle}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned char *@var{key_grip})
-Writes the 20 byte long key grip of the key @var{key} to
-@var{key_grip} via @var{handle}.
-@end deftypefun
-
-@node Using cryptographic functions
-@subsection Using cryptographic functions
-
-The following flags might be relevant:
-
-@table @code
-@item GCRY_AC_FLAG_NO_BLINDING
-Disable any blinding, which might be supported by the chosen
-algorithm; blinding is the default.
-@end table
-
-There exist two kinds of cryptographic functions available through the
-ac interface: primitives, and high-level functions.
-
-Primitives deal with MPIs (data sets) directly; what they provide is
-direct access to the cryptographic operations provided by an algorithm
-implementation.
-
-High-level functions deal with octet strings, according to a specified
-``scheme''.  Schemes make use of ``encoding methods'', which are
-responsible for converting the provided octet strings into MPIs, which
-are then forwared to the cryptographic primitives.  Since schemes are
-to be used for a special purpose in order to achieve a particular
-security goal, there exist ``encryption schemes'' and ``signature
-schemes''.  Encoding methods can be used seperately or implicitly
-through schemes.
-
-What follows is a description of the cryptographic primitives.
-
-@deftypefun gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data_plain}, gcry_ac_data_t *@var{data_encrypted})
-Encrypts the plain text MPI value @var{data_plain} with the key public
-@var{key} under the control of the flags @var{flags} and stores the
-resulting data set into @var{data_encrypted}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t *@var{data_plain}, gcry_ac_data_t @var{data_encrypted})
-Decrypts the encrypted data contained in the data set
-@var{data_encrypted} with the secret key KEY under the control of the
-flags @var{flags} and stores the resulting plain text MPI value in
-@var{DATA_PLAIN}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t *@var{data_signature})
-Signs the data contained in @var{data} with the secret key @var{key}
-and stores the resulting signature in the data set
-@var{data_signature}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t @var{data_signature})
-Verifies that the signature contained in the data set
-@var{data_signature} is indeed the result of signing the data
-contained in @var{data} with the secret key belonging to the public
-key @var{key}.
-@end deftypefun
-
-What follows is a description of the high-level functions.
-
-The type ``gcry_ac_em_t'' is used for specifying encoding methods; the
-following methods are supported:
-
-@table @code
-@item GCRY_AC_EME_PKCS_V1_5
-PKCS-V1_5 Encoding Method for Encryption.  Options must be provided
-through a pointer to a correctly initialized object of type
-gcry_ac_eme_pkcs_v1_5_t.
-
-@item GCRY_AC_EMSA_PKCS_V1_5
-PKCS-V1_5 Encoding Method for Signatures with Appendix.  Options must
-be provided through a pointer to a correctly initialized object of
-type gcry_ac_emsa_pkcs_v1_5_t.
-@end table
-
-Option structure types:
-
-@table @code
-@item gcry_ac_eme_pkcs_v1_5_t
-@table @code
-@item gcry_ac_key_t key
-@item gcry_ac_handle_t handle
-@end table
-@item gcry_ac_emsa_pkcs_v1_5_t
-@table @code
-@item gcry_md_algo_t md
-@item size_t em_n
-@end table
-@end table
-
-Encoding methods can be used directly through the following functions:
-
-@deftypefun gcry_error_t gcry_ac_data_encode (gcry_ac_em_t @var{method}, unsigned int @var{flags}, void *@var{options}, unsigned char *@var{m}, size_t @var{m_n}, unsigned char **@var{em}, size_t *@var{em_n})
-Encodes the message contained in @var{m} of size @var{m_n} according
-to @var{method}, @var{flags} and @var{options}.  The newly created
-encoded message is stored in @var{em} and @var{em_n}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_decode (gcry_ac_em_t @var{method}, unsigned int @var{flags}, void *@var{options}, unsigned char *@var{em}, size_t @var{em_n}, unsigned char **@var{m}, size_t *@var{m_n})
-Decodes the message contained in @var{em} of size @var{em_n} according
-to @var{method}, @var{flags} and @var{options}.  The newly created
-decoded message is stored in @var{m} and @var{m_n}.
-@end deftypefun
-
-The type ``gcry_ac_scheme_t'' is used for specifying schemes; the
-following schemes are supported:
-
-@table @code
-@item GCRY_AC_ES_PKCS_V1_5
-PKCS-V1_5 Encryption Scheme.  No options can be provided.
-@item GCRY_AC_SSA_PKCS_V1_5
-PKCS-V1_5 Signature Scheme (with Appendix).  Options can be provided
-through a pointer to a correctly initialized object of type
-gcry_ac_ssa_pkcs_v1_5_t.
-@end table
-
-Option structure types:
-
-@table @code
-@item gcry_ac_ssa_pkcs_v1_5_t
-@table @code
-@item gcry_md_algo_t md
-@end table
-@end table
-
-The functions implementing schemes:
-
-@deftypefun gcry_error_t gcry_ac_data_encrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_cipher})
-Encrypts the plain text readable from @var{io_message} through
-@var{handle} with the public key @var{key} according to @var{scheme},
-@var{flags} and @var{opts}.  If @var{opts} is not NULL, it has to be a
-pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t).
-The encrypted message is written to @var{io_cipher}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_decrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_cipher}, gcry_ac_io_t *@var{io_message})
-Decrypts the cipher text readable from @var{io_cipher} through
-@var{handle} with the secret key @var{key} according to @var{scheme},
-@var{flags} and @var{opts}.  If @var{opts} is not NULL, it has to be a
-pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t).
-The decrypted message is written to @var{io_message}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_sign_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_signature})
-Signs the message readable from @var{io_message} through @var{handle}
-with the secret key @var{key} according to @var{scheme}, @var{flags}
-and @var{opts}.  If @var{opts} is not NULL, it has to be a pointer to
-a structure specific to the chosen scheme (gcry_ac_ssa_*_t).  The
-signature is written to @var{io_signature}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_data_verify_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_signature})
-Verifies through @var{handle} that the signature readable from
-@var{io_signature} is indeed the result of signing the message
-readable from @var{io_message} with the secret key belonging to the
-public key @var{key} according to @var{scheme} and @var{opts}.  If
-@var{opts} is not NULL, it has to be an anonymous structure
-(gcry_ac_ssa_*_t) specific to the chosen scheme.
-@end deftypefun
-
-@node Handle-independent functions
-@subsection Handle-independent functions
-
-These two functions are deprecated; do not use them for new code.
-
-@deftypefun gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t @var{algorithm}, const char **@var{name})
-Stores the textual representation of the algorithm whose id is given
-in @var{algorithm} in @var{name}.  Deprecated; use @code{gcry_pk_algo_name}.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_ac_name_to_id (const char *@var{name}, gcry_ac_id_t *@var{algorithm})
-Stores the numeric ID of the algorithm whose textual representation is
-contained in @var{name} in @var{algorithm}. Deprecated; use
-@code{gcry_pk_map_name}.
-@end deftypefun
-
 @c **********************************************************
 @c *******************  Hash Functions  *********************
 @c **********************************************************
@@ -3387,7 +2692,6 @@ are also supported.
 
 @menu
 * Available hash algorithms::   List of hash algorithms supported by the library.
-* Hash algorithm modules::      How to work with hash algorithm modules.
 * Working with hash algorithms::  List of functions related to hashing.
 @end menu
 
@@ -3399,7 +2703,7 @@ are also supported.
 @cindex SHA-224, SHA-256, SHA-384, SHA-512
 @cindex RIPE-MD-160
 @cindex MD2, MD4, MD5
-@cindex TIGER
+@cindex TIGER, TIGER1, TIGER2
 @cindex HAVAL
 @cindex Whirlpool
 @cindex CRC32
@@ -3410,26 +2714,46 @@ return value.  This constant is guaranteed to have the value @code{0}.
 
 @item GCRY_MD_SHA1
 This is the SHA-1 algorithm which yields a message digest of 20 bytes.
+Note that SHA-1 begins to show some weaknesses and it is suggested to
+fade out its use if strong cryptographic properties are required.
 
 @item GCRY_MD_RMD160
 This is the 160 bit version of the RIPE message digest (RIPE-MD-160).
-Like SHA-1 it also yields a digest of 20 bytes.
+Like SHA-1 it also yields a digest of 20 bytes.  This algorithm share a
+lot of design properties with SHA-1 and thus it is advisable not to use
+it for new protocols.
 
 @item GCRY_MD_MD5
 This is the well known MD5 algorithm, which yields a message digest of
-16 bytes. 
+16 bytes.  Note that the MD5 algorithm has severe weaknesses, for
+example it is easy to compute two messages yielding the same hash
+(collision attack).  The use of this algorithm is only justified for
+non-cryptographic application.
+
 
 @item GCRY_MD_MD4
 This is the MD4 algorithm, which yields a message digest of 16 bytes.
+This algorithms ha severe weaknesses and should not be used.
 
 @item GCRY_MD_MD2
 This is an reserved identifier for MD-2; there is no implementation yet.
+This algorithm has severe weaknesses and should not be used.
 
 @item GCRY_MD_TIGER
-This is the TIGER/192 algorithm which yields a message digest of 24 bytes.
+This is the TIGER/192 algorithm which yields a message digest of 24
+bytes.  Actually this is a variant of TIGER with a different output
+print order as used by GnuPG up to version 1.3.2.
+
+@item GCRY_MD_TIGER1
+This is the TIGER variant as used by the NESSIE project.  It uses the
+most commonly used output print order.
+
+@item GCRY_MD_TIGER2
+This is another variant of TIGER with a different padding scheme.
+
 
 @item GCRY_MD_HAVAL
-This is an reserved for the HAVAL algorithm with 5 passes and 160
+This is an reserved value for the HAVAL algorithm with 5 passes and 160
 bit. It yields a message digest of 20 bytes.  Note that there is no
 implementation yet available.
 
@@ -3450,16 +2774,19 @@ This is the SHA-384 algorithm which yields a message digest of 64 bytes.
 See FIPS 180-2 for the specification.
 
 @item GCRY_MD_CRC32
-This is the ISO 3309 and ITU-T V.42 cyclic redundancy check.  It
-yields an output of 4 bytes.
+This is the ISO 3309 and ITU-T V.42 cyclic redundancy check.  It yields
+an output of 4 bytes.  Note that this is not a hash algorithm in the
+cryptographic sense.
 
 @item GCRY_MD_CRC32_RFC1510
 This is the above cyclic redundancy check function, as modified by RFC
-1510.  It yields an output of 4 bytes.
+1510.  It yields an output of 4 bytes.  Note that this is not a hash
+algorithm in the cryptographic sense.
 
 @item GCRY_MD_CRC24_RFC2440
 This is the OpenPGP cyclic redundancy check function.  It yields an
-output of 3 bytes.
+output of 3 bytes.  Note that this is not a hash algorithm in the
+cryptographic sense.
 
 @item GCRY_MD_WHIRLPOOL
 This is the Whirlpool algorithm which yields a message digest of 64
@@ -3468,106 +2795,6 @@ bytes.
 @end table
 @c end table of hash algorithms
 
-@node Hash algorithm modules
-@section Hash algorithm modules
-
-Libgcrypt makes it possible to load additional `message
-digest modules'; these digests can be used just like the message digest
-algorithms that are built into the library directly.  For an
-introduction into extension modules, see @xref{Modules}.
-
-@deftp {Data type} gcry_md_spec_t
-This is the `module specification structure' needed for registering
-message digest modules, which has to be filled in by the user before
-it can be used to register a module.  It contains the following
-members:
-
-@table @code
-@item const char *name
-The primary name of this algorithm.
-@item unsigned char *asnoid
-Array of bytes that form the ASN OID.
-@item int asnlen
-Length of bytes in `asnoid'.
-@item gcry_md_oid_spec_t *oids
-A list of OIDs that are to be associated with the algorithm.  The
-list's last element must have it's `oid' member set to NULL.  See
-below for an explanation of this type.  See below for an explanation
-of this type.
-@item int mdlen
-Length of the message digest algorithm.  See below for an explanation
-of this type.
-@item gcry_md_init_t init
-The function responsible for initializing a handle.  See below for an
-explanation of this type.
-@item gcry_md_write_t write
-The function responsible for writing data into a message digest
-context.  See below for an explanation of this type.
-@item gcry_md_final_t final
-The function responsible for `finalizing' a message digest context.
-See below for an explanation of this type.
-@item gcry_md_read_t read
-The function responsible for reading out a message digest result.  See
-below for an explanation of this type.
-@item size_t contextsize
-The size of the algorithm-specific `context', that should be
-allocated for each handle.
-@end table
-@end deftp
-
-@deftp {Data type} gcry_md_oid_spec_t
-This type is used for associating a user-provided algorithm
-implementation with certain OIDs.  It contains the following members:
-
-@table @code
-@item const char *oidstring
-Textual representation of the OID.
-@end table
-@end deftp
-
-@deftp {Data type} gcry_md_init_t
-Type for the `init' function, defined as: void (*gcry_md_init_t) (void
-*c)
-@end deftp
-
-@deftp {Data type} gcry_md_write_t
-Type for the `write' function, defined as: void (*gcry_md_write_t)
-(void *c, unsigned char *buf, size_t nbytes)
-@end deftp
-
-@deftp {Data type} gcry_md_final_t
-Type for the `final' function, defined as: void (*gcry_md_final_t)
-(void *c)
-@end deftp
-
-@deftp {Data type} gcry_md_read_t
-Type for the `read' function, defined as: unsigned char
-*(*gcry_md_read_t) (void *c)
-@end deftp
-
-@deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})
-
-Register a new digest module whose specification can be found in
-@var{digest}.  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_md_unregister (gcry_module_t @var{module})
-Unregister the digest identified by @var{module}, which must have been
-registered with gcry_md_register.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length})
-Get a list consisting of the IDs of the loaded message digest modules.
-If @var{list} is zero, write the number of loaded message digest
-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 message
-digests modules than *@var{list_length}, *@var{list_length} is updated
-to the correct number.
-@end deftypefun
-
 @node Working with hash algorithms
 @section Working with hash algorithms
 
@@ -3626,8 +2853,9 @@ be set using the function:
 
 @deftypefun gcry_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key}, size_t @var{keylen})
 
-For use with the HMAC feature, set the MAC key to the value of @var{key}
-of length @var{keylen}.  There is no restriction on the length of the key.
+For use with the HMAC feature, set the MAC key to the value of
+@var{key} of length @var{keylen} bytes.  There is no restriction on
+the length of the key.
 @end deftypefun
 
 
@@ -3638,7 +2866,9 @@ resources by using:
 
 Release all resources of hash context @var{h}.  @var{h} should not be
 used after a call to this function.  A @code{NULL} passed as @var{h} is
-ignored.
+ignored.  The function also zeroises all sensitive information
+associated with this handle.
+
 
 @end deftypefun
 
@@ -3685,7 +2915,7 @@ function should be used for large blocks of data.
 
 Pass the byte in @var{c} to the digest object with handle @var{h} to
 update the digest value.  This is an efficient function, implemented as
-a macro to buffer the data before an actual update. 
+a macro to buffer the data before an actual update.
 @end deftypefun
 
 The semantics of the hash functions do not provide for reading out intermediate
@@ -3719,7 +2949,7 @@ been enabled.
 @end deftypefun
 
 Because it is often necessary to get the message digest of one block of
-memory, a fast convenience function is available for this task: 
+memory, a fast convenience function is available for this task:
 
 @deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const void *@var{buffer}, size_t @var{length});
 
@@ -3780,7 +3010,7 @@ returns 0 on success.
 To test whether an algorithm is actually available for use, the
 following macro should be used:
 
-@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo}) 
+@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo})
 
 The macro returns 0 if the algorithm @var{algo} is available for use.
 @end deftypefun
@@ -3863,6 +3093,65 @@ does implicitly stop debugging.
 @end deftypefun
 
 
+@c *******************************************************
+@c *******************  KDF  *****************************
+@c *******************************************************
+@node Key Derivation
+@chapter Key Derivation
+
+@acronym{Libgcypt} provides a general purpose function to derive keys
+from strings.
+
+@deftypefun gpg_error_t gcry_kdf_derive ( @
+            @w{const void *@var{passphrase}}, @w{size_t @var{passphraselen}}, @
+            @w{int @var{algo}}, @w{int @var{subalgo}}, @
+            @w{const void *@var{salt}}, @w{size_t @var{saltlen}}, @
+            @w{unsigned long @var{iterations}}, @
+            @w{size_t @var{keysize}}, @w{void *@var{keybuffer}} )
+
+
+Derive a key from a passphrase.  @var{keysize} gives the requested
+size of the keys in octets.  @var{keybuffer} is a caller provided
+buffer filled on success with the derived key.  The input passphrase
+is taken from @var{passphrase} which is an arbitrary memory buffer of
+@var{passphraselen} octets.  @var{algo} specifies the KDF algorithm to
+use; see below.  @var{subalgo} specifies an algorithm used internally
+by the KDF algorithms; this is usually a hash algorithm but certain
+KDF algorithms may use it differently.  @var{salt} is a salt of length
+@var{saltlen} octets, as needed by most KDF algorithms.
+@var{iterations} is a positive integer parameter to most KDFs.
+
+@noindent
+On success 0 is returned; on failure an error code.
+
+@noindent
+Currently supported KDFs (parameter @var{algo}):
+
+@table @code
+@item GCRY_KDF_SIMPLE_S2K
+The OpenPGP simple S2K algorithm (cf. RFC4880).  Its use is strongly
+deprecated.  @var{salt} and @var{iterations} are not needed and may be
+passed as @code{NULL}/@code{0}.
+
+@item GCRY_KDF_SALTED_S2K
+The OpenPGP salted S2K algorithm (cf. RFC4880).  Usually not used.
+@var{iterations} is not needed and may be passed as @code{0}.  @var{saltlen}
+must be given as 8.
+
+@item GCRY_KDF_ITERSALTED_S2K
+The OpenPGP iterated+salted S2K algorithm (cf. RFC4880).  This is the
+default for most OpenPGP applications.  @var{saltlen} must be given as
+8.  Note that OpenPGP defines a special encoding of the
+@var{iterations}; however this function takes the plain decoded
+iteration count.
+
+@item GCRY_KDF_PBKDF2
+The PKCS#5 Passphrase Based Key Derivation Function number 2.
+
+@end table
+@end deftypefun
+
+
 @c **********************************************************
 @c *******************  Random  *****************************
 @c **********************************************************
@@ -3972,7 +3261,7 @@ the external formats:
 
 This is the generic function to create an new S-expression object from
 its external representation in @var{buffer} of @var{length} bytes.  On
-success the result is stored at the address given by @var{r_sexp}. 
+success the result is stored at the address given by @var{r_sexp}.
 With @var{autodetect} set to 0, the data in @var{buffer} is expected to
 be in canonized format, with @var{autodetect} set to 1 the parses any of
 the defined external formats.  If @var{buffer} does not hold a valid
@@ -4014,18 +3303,31 @@ expects arguments for some of these escape sequences right after
 @table @samp
 @item %m
 The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
-its value is inserted into the resulting S-expression.
+its value is inserted into the resulting S-expression.  The MPI is
+stored as a signed integer.
+@item %M
+The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
+its value is inserted into the resulting S-expression.  The MPI is
+stored as an unsigned integer.
 @item %s
 The next argument is expected to be of type @code{char *} and that
 string is inserted into the resulting S-expression.
 @item %d
 The next argument is expected to be of type @code{int} and its value is
 inserted into the resulting S-expression.
+@item %u
+The next argument is expected to be of type @code{unsigned int} and
+its value is inserted into the resulting S-expression.
 @item %b
 The next argument is expected to be of type @code{int} directly
 followed by an argument of type @code{char *}.  This represents a
-buffer of given length to be inserted into the resulting regular
-expression.
+buffer of given length to be inserted into the resulting S-expression.
+@item %S
+The next argument is expected to be of type @code{gcry_sexp_t} and a
+copy of that S-expression is embedded in the resulting S-expression.
+The argument needs to be a regular S-expression, starting with a
+parenthesis.
+
 @end table
 
 @noindent
@@ -4036,7 +3338,10 @@ sign is not a valid character in an S-expression.
 
 @deftypefun void gcry_sexp_release (@w{gcry_sexp_t @var{sexp}})
 
-Release the S-expression object @var{sexp}.
+Release the S-expression object @var{sexp}.  If the S-expression is
+stored in secure memory it explicitly zeroises that memory; note that
+this is done in addition to the zeroisation always done when freeing
+secure memory.
 @end deftypefun
 
 
@@ -4097,8 +3402,7 @@ passed as @code{NULL}.
 
 
 @noindent
-There are a couple of functions to parse S-expressions and retrieve
-elements:
+There are functions to parse S-expressions and retrieve elements:
 
 @deftypefun gcry_sexp_t gcry_sexp_find_token (@w{const gcry_sexp_t @var{list}}, @w{const char *@var{token}}, @w{size_t @var{toklen}})
 
@@ -4179,7 +3483,9 @@ data is assumed to be an MPI stored in the format described by
 @var{mpifmt} and returned as a standard Libgcrypt MPI.  The caller must
 release this returned value using @code{gcry_mpi_release}.  If there is
 no data at the given index, the index represents a list or the value
-can't be converted to an MPI, @code{NULL} is returned.
+can't be converted to an MPI, @code{NULL} is returned.  If you use
+this function to parse results of a public key function, you most
+likely want to use @code{GCRYMPI_FMT_USG}.
 @end deftypefun
 
 
@@ -4202,7 +3508,7 @@ can't be converted to an MPI, @code{NULL} is returned.
 Public key cryptography is based on mathematics with large numbers.  To
 implement the public key functions, a library for handling these large
 numbers is required.  Because of the general usefulness of such a
-library, its interface is exposed by Libgcrypt. 
+library, its interface is exposed by Libgcrypt.
 In the context of Libgcrypt and in most other applications, these large
 numbers are called MPIs (multi-precision-integers).
 
@@ -4424,7 +3730,7 @@ as @code{NULL}.  @var{round} should be negative or 0.
 
 @deftypefun int gcry_mpi_gcd (@w{gcry_mpi_t @var{g}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
 
-Set @var{g} to the greatest common divisor of @var{a} and @var{b}.  
+Set @var{g} to the greatest common divisor of @var{a} and @var{b}.
 Return true if the @var{g} is 1.
 @end deftypefun
 
@@ -4446,7 +3752,10 @@ The next 2 functions are used to compare MPIs:
 
 Compare the multi-precision-integers number @var{u} and @var{v}
 returning 0 for equality, a positive value for @var{u} > @var{v} and a
-negative for @var{u} < @var{v}.
+negative for @var{u} < @var{v}.  If both numbers are opaque values
+(cf, gcry_mpi_set_opaque) the comparison is done by checking the bit
+sizes using memcmp.  If only one number is an opaque value, the opaque
+value is less than the other number.
 @end deftypefun
 
 @deftypefun int gcry_mpi_cmp_ui (@w{const gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
@@ -4630,15 +3939,15 @@ it returns NULL.
 Like @code{gcry_malloc}, but uses secure memory.
 @end deftypefun
 
-@deftypefun {void *} gcry_calloc (size_t @var{n})
+@deftypefun {void *} gcry_calloc (size_t @var{n}, size_t @var{m})
 
-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.
+This function allocates a cleared block of memory (i.e. initialized with
+zero bytes) long enough to contain a vector of @var{n} elements, each of
+size @var{m} bytes.  On success it returns a pointer to the memory
+block; in an out-of-core condition, it returns NULL.
 @end deftypefun
 
-@deftypefun {void *} gcry_calloc_secure (size_t @var{n})
+@deftypefun {void *} gcry_calloc_secure (size_t @var{n}, size_t @var{m})
 Like @code{gcry_calloc}, but uses secure memory.
 @end deftypefun
 
@@ -4656,6 +3965,75 @@ Release the memory area pointed to by @var{p}.
 @end deftypefun
 
 @c **********************************************************
+@c *********************  Tools  ****************************
+@c **********************************************************
+@node Tools
+@chapter Tools
+
+@menu
+* hmac256:: A standalone HMAC-SHA-256 implementation
+@end menu
+
+@manpage hmac256.1
+@node hmac256
+@section A HMAC-SHA-256 tool
+@ifset manverb
+.B hmac256
+\- Compute an HMAC-SHA-256 MAC
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B  hmac256
+.RB [ \-\-binary ]
+.I key
+.I [FILENAME]
+@end ifset
+
+@mansect description
+This is a standalone HMAC-SHA-256 implementation used to compute an
+HMAC-SHA-256 message authentication code.  The tool has originally
+been developed as a second implementation for Libgcrypt to allow
+comparing against the primary implementation and to be used for
+internal consistency checks.  It should not be used for sensitive data
+because no mechanisms to clear the stack etc are used.
+
+The code has been written in a highly portable manner and requires
+only a few standard definitions to be provided in a config.h file.
+
+@noindent
+@command{hmac256} is commonly invoked as
+
+@example
+hmac256 "This is my key" foo.txt
+@end example
+
+@noindent
+This compute the MAC on the file @file{foo.txt} using the key given on
+the command line.
+
+@mansect options
+@noindent
+@command{hmac256} understands these options:
+
+@table @gnupgtabopt
+
+@item --binary
+Print the MAC as a binary string.  The default is to print the MAC
+encoded has lower case hex digits.
+
+@item --version
+Print version of the program and exit.
+
+@end table
+
+@mansect see also
+@ifset isman
+@command{sha256sum}(1)
+@end ifset
+@manpause
+
+@c **********************************************************
 @c *****************  Architecure Overview  *****************
 @c **********************************************************
 @node Architecture
@@ -4719,12 +4097,6 @@ final close function releases all resources associated with the handle.
 @node Public-Key Subsystem Architecture
 @section Public-Key Architecture
 
-Libgcrypt implements two interfaces for public key cryptography: The
-standard interface is PK interface using functions in the
-@code{gcry_pk_} name space.  The AC interface in an alternative one
-which is now deprecated and will not be further described.  The AC
-interface is also disabled in FIPS mode.
-
 Because public key cryptography is almost always used to process small
 amounts of data (hash values or session keys), the interface is not
 implemented using the open-use-close paradigm, but with single
@@ -4740,13 +4112,13 @@ following main functions are available:
 
 @table @code
 
-@item gcry_pk_encrypt 
+@item gcry_pk_encrypt
 Encrypt data using a public key.
 
-@item gcry_pk_decrypt 
+@item gcry_pk_decrypt
 Decrypt data using a private key.
 
-@item gcry_pk_sign 
+@item gcry_pk_sign
 Sign data using a private key.
 
 @item gcry_pk_verify
@@ -4760,18 +4132,13 @@ Create a new public/private key pair.
 
 @end table
 
-With the help of the module registration system all these functions
+All these functions
 lookup the module implementing the algorithm and pass the actual work
 to that module.  The parsing of the S-expression input and the
 construction of S-expression for the return values is done by the high
 level code (@file{cipher/pubkey.c}).  Thus the internal interface
 between the algorithm modules and the high level functions passes data
-in a custom format.  The interface to the modules is published
-(@file{gcrypt-modules.h}) so that it can used to register external
-implementations of algorithms with Libgcrypt.  However, for some
-algorithms this module interface is to limited and thus for the
-internal modules an extra interface is sometimes used to convey more
-information.
+in a custom format.
 
 By default Libgcrypt uses a blinding technique for RSA decryption to
 mitigate real world timing attacks over a network: Instead of using
@@ -4814,13 +4181,13 @@ algorithm and mode.
 Release an instance.
 
 @item gcry_cipher_setkey
-Set a key to be used for encryption or decryption. 
+Set a key to be used for encryption or decryption.
 
 @item gcry_cipher_setiv
 Set an initialization vector to be used for encryption or decryption.
 
 @item gcry_cipher_encrypt
-@itemx gcry_cipher_decrypt 
+@itemx gcry_cipher_decrypt
 Encrypt or decrypt data.  These functions may be called with arbitrary
 amounts of data and as often as needed to encrypt or decrypt all data.
 
@@ -4902,7 +4269,7 @@ Major features of Libgcrypt's multi-precision-integer code compared to
 GMP are:
 
 @itemize
-@item 
+@item
 Avoidance of stack based allocations to allow protection against
 swapping out of sensitive data and for easy zeroing of sensitive
 intermediate results.
@@ -4989,10 +4356,10 @@ for weaker usages like nonces.  There is also a level
 multi-precision-integer using the @code{gcry_create_nonce} function.
 
 @noindent
-There are two distinct random generators available: 
+There are two distinct random generators available:
 
 @itemize
-@item 
+@item
 The Continuously Seeded Pseudo Random Number Generator (CSPRNG), which
 is based on the classic GnuPG derived big pool implementation.
 Implemented in @code{random/random-csprng.c} and used by default.
@@ -5117,23 +4484,21 @@ microseconds (if available) and a free running 64 bit counter.  When
 used with the test context the DT value is taken from the context and
 incremented on each use.
 
-
-
 @c @node Helper Subsystems Architecture
 @c @section Helper Subsystems Architecture
-@c 
+@c
 @c There are a few smaller subsystems which are mainly used internally by
 @c Libgcrypt but also available to applications.
-@c 
+@c
 @c @menu
 @c * S-expression Subsystem Architecture::   Details about the S-expression architecture.
 @c * Memory Subsystem Architecture::         Details about the memory allocation architecture.
 @c * Miscellaneous Subsystems Architecture:: Details about other subsystems.
 @c @end menu
-@c 
+@c
 @c @node S-expression Subsystem Architecture
 @c @subsection S-expression Subsystem Architecture
-@c 
+@c
 @c Libgcrypt provides an interface to S-expression to create and parse
 @c them.  To use an S-expression with Libgcrypt it needs first be
 @c converted into the internal representation used by Libgcrypt (the type
@@ -5141,25 +4506,25 @@ incremented on each use.
 @c of the S-expression specification and further fature a printf like
 @c function to convert a list of big integers or other binary data into
 @c an S-expression.
-@c 
+@c
 @c Libgcrypt currently implements S-expressions using a tagged linked
 @c list.  However this is not exposed to an application and may be
 @c changed in future releases to reduce overhead when already working
 @c with canonically encoded S-expressions.  Secure memory is supported by
 @c this S-expressions implementation.
-@c 
-@c @node Memory Subsystem Architecture 
-@c @subsection Memory Subsystem Architecture 
-@c 
+@c
+@c @node Memory Subsystem Architecture
+@c @subsection Memory Subsystem Architecture
+@c
 @c TBD.
-@c 
-@c 
+@c
+@c
 @c @node Miscellaneous Subsystems Architecture
 @c @subsection Miscellaneous Subsystems Architecture
-@c 
+@c
 @c TBD.
-@c 
-@c 
+@c
+@c
 
 
 
@@ -5188,7 +4553,7 @@ the library into the ``Error'' state.
 @c --------------------------------
 @section Power-Up Tests
 
-Power-up tests are only performed if Libgcrypt is in FIPS mode.  
+Power-up tests are only performed if Libgcrypt is in FIPS mode.
 
 @subsection Symmetric Cipher Algorithm Power-Up Tests
 
@@ -5277,7 +4642,7 @@ A known answer test using 28 byte of data and a 4 byte key is run.
 The DRNG is tested during power-up this way:
 
 @enumerate
-@item 
+@item
 Requesting one block of random using the public interface to check
 general working and the duplicated block detection.
 @item
@@ -5295,10 +4660,10 @@ The public key algorithms are tested during power-up:
 A pre-defined 1024 bit RSA key is used and these tests are run
 in turn:
 @enumerate
-@item 
-Conversion of S-expression to internal format. 
+@item
+Conversion of S-expression to internal format.
 (@code{cipher/@/rsa.c:@/selftests_rsa})
-@item 
+@item
 Private key consistency check.
 (@code{cipher/@/rsa.c:@/selftests_rsa})
 @item
@@ -5386,12 +4751,7 @@ verification fails.  (@code{cipher/@/dsa.c:@/test_keys})
 
 @subsection Software Load Tests
 
-Loading of extra modules into libgcrypt is disabled in FIPS mode and
-thus no tests are
-implemented. (@code{cipher/@/cipher.c:@/gcry_cipher_register},
-@code{cipher/@/md.c:@/gcry_md_register},
-@code{cipher/@/md.c:@/gcry_pk_register})
-
+No code is loaded at runtime.
 
 @subsection Manual Key Entry Tests
 
@@ -5405,7 +4765,7 @@ generates blocks of 128 bit size; the first block generated per
 context is saved in the context and another block is generated to be
 returned to the caller.  Each block is compared against the saved
 block and then stored in the context.  If a duplicated block is
-detected an error is signaled and the libray is put into the
+detected an error is signaled and the library is put into the
 ``Fatal-Error'' state.
 (@code{random/@/random-fips.c:@/x931_aes_driver})
 
@@ -5439,7 +4799,7 @@ using the high level functions is run for block modes CFB and OFB.
 
 @subsection Hash Algorithm Tests
 
-The following hash algorithm tests are run in addition to the 
+The following hash algorithm tests are run in addition to the
 power-up tests:
 
 @table @asis
@@ -5449,7 +4809,7 @@ power-up tests:
 @enumerate
 @item
 A known answer test using a 56 byte string is run.
-@item 
+@item
 A known answer test using a string of one million letters "a" is run.
 @end enumerate
 (@code{cipher/@/sha1.c:@/selftests_sha1},
@@ -5460,7 +4820,7 @@ A known answer test using a string of one million letters "a" is run.
 @enumerate
 @item
 A known answer test using a 112 byte string is run.
-@item 
+@item
 A known answer test using a string of one million letters "a" is run.
 @end enumerate
 (@code{cipher/@/sha512.c:@/selftests_sha384},
@@ -5555,7 +4915,7 @@ HMAC using a SHA-384 message digest.
 @item GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC
 HMAC using a SHA-512 message digest.
 @item GCRY_PK_RSA
-RSA encryption and signing.         
+RSA encryption and signing.
 @item GCRY_PK_DSA
 DSA signing.
 @end table
@@ -5565,7 +4925,7 @@ and thus are in addition available.
 
 @item
 RSA key generation refuses to create a key with a keysize of
-less than 1024 bits.  
+less than 1024 bits.
 
 @item
 DSA key generation refuses to create a key with a keysize other
@@ -5577,7 +4937,7 @@ The @code{transient-key} flag for RSA and DSA key generation is ignored.
 @item
 Support for the VIA Padlock engine is disabled.
 
-@item 
+@item
 FIPS mode may only be used on systems with a /dev/random device.
 Switching into FIPS mode on other systems will fail at runtime.
 
@@ -5592,19 +4952,12 @@ large-pool-CSPRNG generator.
 The command @code{GCRYCTL_ENABLE_QUICK_RANDOM} is ignored.
 
 @item
-The Alternative Public Key Interface (@code{gcry_ac_xxx}) is not
-supported and all API calls return an error.
-
-@item
-Registration of external modules is not supported.
-
-@item 
 Message digest debugging is disabled.
 
 @item
 All debug output related to cryptographic data is suppressed.
 
-@item 
+@item
 On-the-fly self-tests are not performed, instead self-tests are run
 before entering operational state.
 
@@ -5618,7 +4971,7 @@ The digest algorithm MD5 may not be used.  If it is used Libgcrypt
 disables FIPS mode unless Enforced FIPS mode is enabled, in which case
 Libgcrypt will enter the error state.
 
-@item 
+@item
 In Enforced FIPS mode the command @code{GCRYCTL_DISABLE_SECMEM} is
 ignored.  In standard FIPS mode it disables FIPS mode.
 
@@ -5651,7 +5004,7 @@ transitions (@pxref{tbl:fips-state-transitions}) may happen.
 States used by the FIPS FSM:
 @table @asis
 
-@item Power-Off 
+@item Power-Off
 Libgcrypt is not runtime linked to another application.  This usually
 means that the library is not loaded into main memory.  This state is
 documentation only.
@@ -5667,7 +5020,7 @@ The Libgcrypt initialization functions are performed and the library has
 not yet run any self-test.
 
 @item Self-Test
-Libgcrypt is performing self-tests.               
+Libgcrypt is performing self-tests.
 
 @item Operational
 Libgcrypt is in the operational state and all interfaces may be used.
@@ -5675,11 +5028,11 @@ Libgcrypt is in the operational state and all interfaces may be used.
 @item Error
 Libgrypt is in the error state.  When calling any FIPS relevant
 interfaces they either return an error (@code{GPG_ERR_NOT_OPERATIONAL})
-or put Libgcrypt into the Fatal-Error state and won't return.  
+or put Libgcrypt into the Fatal-Error state and won't return.
 
 @item Fatal-Error
-Libgcrypt is in a non-recoverable error state and 
-will automatically transit into the  Shutdown state.        
+Libgcrypt is in a non-recoverable error state and
+will automatically transit into the  Shutdown state.
 
 @item Shutdown
 Libgcrypt is about to be terminated and removed from the memory. The
@@ -5694,7 +5047,7 @@ application may at this point still runing cleanup handlers.
 @noindent
 The valid state transitions (@pxref{fig:fips-fsm}) are:
 @table @code
-@item 1 
+@item 1
 Power-Off to Power-On is implicitly done by the OS loading Libgcrypt as
 a shared library and having it linked to an application.
 
@@ -5706,9 +5059,9 @@ Libgcrypt intialization function @code{gcry_check_version}.
 Init to Self-Test is either triggred by a dedicated API call or implicit
 by invoking a libgrypt service conrolled by the FSM.
 
-@item 4 
+@item 4
 Self-Test to Operational is triggered after all self-tests passed
-successfully.  
+successfully.
 
 @item 5
 Operational to Shutdown is an artifical state without any direct action
@@ -5736,7 +5089,7 @@ Error to Fatal-Error is triggred if Libgrypt detects an fatal error
 while already being in Error state.
 
 @item 10
-Fatal-Error to Shutdown is automatically entered by Libgcrypt 
+Fatal-Error to Shutdown is automatically entered by Libgcrypt
 after having reported the error.
 
 @item 11
@@ -5838,7 +5191,3 @@ these functions are not really thread safe.
 
 
 @c  LocalWords:  int HD
-
-
-
-