Suggest to use GCRYMPI_FMT_USG with gcry_sexp_nth_mpi.
[libgcrypt.git] / doc / gcrypt.texi
index a1bb696..419dc68 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
@@ -68,6 +68,7 @@ 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.
@@ -219,7 +220,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 +353,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 +384,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 +411,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 +423,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
@@ -498,7 +499,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 +515,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
@@ -520,6 +532,7 @@ programmers might have to wrap these macros in an ``extern C'' body.
 @node Enabling FIPS mode
 @section How to enable the FIPS mode
 @cindex FIPS mode
+@cindex FIPS 140
 
 Libgcrypt may be used in a FIPS 140-2 mode.  Note, that this does not
 necessary mean that Libcgrypt is an appoved FIPS 140-2 module.  Check the
@@ -532,18 +545,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}).
@@ -588,11 +601,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
@@ -626,13 +640,13 @@ after initialization.
 
 @item GCRYCTL_DISABLE_SECMEM; Arguments: none
 This command disables the use of secure memory.  If this command is
-used in FIPS mode, FIPS mode will be disabled and the fucntion
+used in FIPS mode, FIPS mode will be disabled and the function
 @code{gcry_fips_mode_active} returns false.  However, in Enforced FIPS
 mode this command has no effect at all.
 
 Many applications do not require secure memory, so they should disable
 it right away.  This command should be executed right after
-@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
@@ -658,9 +672,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.
@@ -735,7 +749,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
@@ -801,6 +815,15 @@ 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
 
@@ -1189,7 +1212,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)
     @{
@@ -1235,7 +1258,8 @@ 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:
+It may be used only during initialization.  @var{cb} must be defined
+as follows:
 
 @example
 void
@@ -1309,7 +1333,14 @@ 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.
+functions for doing memory allocation.  Using this function is in
+general not recommended because the standard Libgcrypt allocation
+functions are guaranteed to zeroize memory if needed.
+
+This function may be used only during initialization and may not be
+used in fips mode.
+
+
 @end deftypefun
 
 @node Error handler
@@ -1320,12 +1351,18 @@ are called by Libgcrypt in case certain error conditions occur.  They
 may and should be registered prior to calling @code{gcry_check_version}.
 
 @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)}
+This type is defined as: @code{int (*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.
+memory available.  The handler is called with 3 arguments: The first
+one is the pointer @var{cb_data} as set with this function, the second
+is the requested memory size and the last being a flag.  If bit 0 of
+the flag is set, secure memory has been requested.  The handler should
+either return true to indicate that Libgcrypt should try again
+allocating memory or return false to let Libgcrypt use its default
+fatal error handler.
 @end deftypefun
 
 @deftp {Data type} gcry_handler_error_t
@@ -1396,7 +1433,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
@@ -1405,10 +1442,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
@@ -1417,27 +1454,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
@@ -1566,7 +1603,8 @@ unsigned char *, unsigned int n)
 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}.
+in @var{module}.  Deprecated; the module register interface will be
+removed in a future version.
 @end deftypefun
 
 @deftypefun void gcry_cipher_unregister (gcry_module_t @var{module})
@@ -1595,7 +1633,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
@@ -1617,6 +1655,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
@@ -1659,7 +1711,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
@@ -1673,13 +1725,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
@@ -1688,11 +1742,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
 
@@ -1704,18 +1758,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})
@@ -1817,7 +1871,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}:
 
@@ -1836,8 +1890,8 @@ number of octets in @var{nbytes}; @var{buffer} must be zero.
 @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
@@ -1989,7 +2043,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:
 
@@ -2236,8 +2290,10 @@ Type for the `get_nbits' function, defined as: unsigned
 
 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}.
+@var{algorithm_id} and a pointer representing this module is stored in
+@var{module}.  Deprecated; the module register interface will be
+removed in a future version.
+
 @end deftypefun
 
 @deftypefun void gcry_pk_unregister (gcry_module_t @var{module})
@@ -2261,7 +2317,7 @@ number.
 @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
 
@@ -2271,7 +2327,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
@@ -2298,19 +2359,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}))
@@ -2373,8 +2434,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
@@ -2405,7 +2475,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}))
@@ -2416,9 +2486,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
@@ -2554,9 +2624,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
 
@@ -2674,7 +2744,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
@@ -2693,10 +2763,11 @@ 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 keys.  This is a flag with no value.  If
-given the RSA key is created using a faster and a somewhat less secure
-random number generator.  This flag may be used for keys which are only
-used for a short time and do not require full cryptographic strength.
+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
 This is only meaningful for DLP algorithms.  If specified keys are
@@ -2710,14 +2781,73 @@ currently only implemented for DSA using this format:
     (domain
       (p @var{p-mpi})
       (q @var{q-mpi})
-      (g @var{q-mpi})
-      (seed @var{seed-mpi})
-      (counter @var{counter-mpi})
-      (h @var{h-mpi}))))
+      (g @var{q-mpi}))))
 @end example
 
-The @code{seed}, @code{counter} and @code{h} domain parameters are
-optional and currently not used.
+@code{nbits} and @code{qbits} may not be specified because they are
+derived from the domain parameters.
+
+@item derive-parms
+This is currently only implemented for RSA and DSA keys.  It is not
+allowed to use this together with a @code{domain} specification.  If
+given, it is used to derive the keys using the given parameters.
+
+If given for an RSA key the X9.31 key generation algorithm is used
+even if libgcrypt is not in FIPS mode.  If given for a DSA key, the
+FIPS 186 algorithm is used even if libgcrypt is not in FIPS mode.
+
+@example
+(genkey
+  (rsa
+    (nbits 4:1024)
+    (rsa-use-e 1:3)
+    (derive-parms
+      (Xp1 #1A1916DDB29B4EB7EB6732E128#)
+      (Xp2 #192E8AAC41C576C822D93EA433#)
+      (Xp  #D8CD81F035EC57EFE822955149D3BFF70C53520D
+            769D6D76646C7A792E16EBD89FE6FC5B605A6493
+            39DFC925A86A4C6D150B71B9EEA02D68885F5009
+            B98BD984#)
+      (Xq1 #1A5CF72EE770DE50CB09ACCEA9#)
+      (Xq2 #134E4CAA16D2350A21D775C404#)
+      (Xq  #CC1092495D867E64065DEE3E7955F2EBC7D47A2D
+            7C9953388F97DDDC3E1CA19C35CA659EDC2FC325
+            6D29C2627479C086A699A49C4C9CEE7EF7BD1B34
+            321DE34A#))))
+@end example
+
+@example
+(genkey
+  (dsa
+    (nbits 4:1024)
+    (derive-parms
+      (seed @var{seed-mpi}))))
+@end example
+
+
+@item use-x931
+@cindex X9.31
+Force the use of the ANSI X9.31 key generation algorithm instead of
+the default algorithm. This flag is only meaningful for RSA and
+usually not required.  Note that this algorithm is implicitly used if
+either @code{derive-parms} is given or Libgcrypt is in FIPS mode.
+
+@item use-fips186
+@cindex FIPS 186
+Force the use of the FIPS 186 key generation algorithm instead of the
+default algorithm.  This flag is only meaningful for DSA and usually
+not required.  Note that this algorithm is implicitly used if either
+@code{derive-parms} is given or Libgcrypt is in FIPS mode.  As of now
+FIPS 186-2 is implemented; after the approval of FIPS 186-3 the code
+will be changed to implement 186-3.
+
+
+@item use-fips186-2
+Force the use of the FIPS 186-2 key generation algorithm instead of
+the default algorithm.  This algorithm is slighlty different from
+FIPS 186-3 and allows only 1024 bit keys.  This flag is only meaningful
+for DSA and only required for FIPS testing backward compatibility.
+
 
 @end table
 @c end table of parameters
@@ -2744,16 +2874,17 @@ As an example, here is what the Elgamal key generation returns:
       (y @var{y-mpi})
       (x @var{x-mpi})))
   (misc-key-info
-    (pm1-factors @var{n1 n2 ... nn})))
+    (pm1-factors @var{n1 n2 ... nn}))
 @end example
 
 @noindent
-As you can see, some of the information is duplicated, but this provides
-an easy way to extract either the public or the private key.  Note that
-the order of the elements is not defined, e.g. the private key may be
-stored before the public key. @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.
+As you can see, some of the information is duplicated, but this
+provides an easy way to extract either the public or the private key.
+Note that the order of the elements is not defined, e.g. the private
+key may be stored before the public key. @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.
 @end deftypefun
 @c end gcry_pk_genkey
 
@@ -2768,7 +2899,7 @@ 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 Libgcrypt.}
+forthcoming versions of Libgcrypt.}
 
 
 @menu
@@ -3323,7 +3454,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
@@ -3334,26 +3465,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.
 
@@ -3374,16 +3525,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
@@ -3474,7 +3628,8 @@ Type for the `read' function, defined as: unsigned char
 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}.
+in @var{module}.  Deprecated; the module register interface will be
+removed in a future version.
 @end deftypefun
 
 @deftypefun void gcry_md_unregister (gcry_module_t @var{module})
@@ -3550,8 +3705,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
 
 
@@ -3562,7 +3718,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
 
@@ -3609,7 +3767,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
@@ -3643,7 +3801,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});
 
@@ -3704,7 +3862,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
@@ -3787,6 +3945,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 **********************************************************
@@ -3896,7 +4113,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
@@ -3938,18 +4155,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
@@ -3960,7 +4190,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
 
 
@@ -4021,8 +4254,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}})
 
@@ -4103,7 +4335,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
 
 
@@ -4126,7 +4360,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).
 
@@ -4348,7 +4582,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
 
@@ -4370,7 +4604,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}})
@@ -4554,15 +4791,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
 
@@ -4664,13 +4901,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
@@ -4702,9 +4939,16 @@ mitigate real world timing attacks over a network: Instead of using
 the RSA decryption directly, a blinded value @math{y = x r^{e} \bmod n}
 is decrypted and the unblinded value @math{x' = y' r^{-1} \bmod n}
 returned.  The blinding value @math{r} is a random value with the size
-of the modulus @math{n} and generated with @code{GCRY_STRONG_RANDOM}
+of the modulus @math{n} and generated with @code{GCRY_WEAK_RANDOM}
 random level.
 
+@cindex X9.31
+@cindex FIPS 186
+The algorithm used for RSA and DSA key generation depends on whether
+Libgcrypt is operated in standard or in FIPS mode.  In standard mode
+an algorithm based on the Lim-Lee prime number generator is used.  In
+FIPS mode RSA keys are generated as specified in ANSI X9.31 (1998) and
+DSA keys as specified in FIPS 186-2.
 
 
 
@@ -4731,13 +4975,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.
 
@@ -4819,7 +5063,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.
@@ -4884,6 +5128,14 @@ witness of 2, whereas the next rounds use a random witness.
 
 @end enumerate
 
+To support the generation of RSA and DSA keys in FIPS mode according
+to X9.31 and FIPS 186-2, Libgcrypt implements two additional prime
+generation functions: @code{_gcry_derive_x931_prime} and
+@code{_gcry_generate_fips186_2_prime}.  These functions are internal
+and not available through the public API.
+
+
+
 @node Random-Number Subsystem Architecture
 @section Random-Number Subsystem Architecture
 
@@ -4898,10 +5150,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.
@@ -5026,23 +5278,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
@@ -5050,25 +5300,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
 
 
 
@@ -5097,7 +5347,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
 
@@ -5186,7 +5436,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
@@ -5204,10 +5454,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
@@ -5297,9 +5547,9 @@ verification fails.  (@code{cipher/@/dsa.c:@/test_keys})
 
 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})
+implemented. (@code{cipher/@/cipher.c:@/_gcry_cipher_register},
+@code{cipher/@/md.c:@/_gcry_md_register},
+@code{cipher/@/pubkey.c:@/_gcry_pk_register})
 
 
 @subsection Manual Key Entry Tests
@@ -5314,7 +5564,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})
 
@@ -5348,7 +5598,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
@@ -5358,7 +5608,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},
@@ -5369,7 +5619,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},
@@ -5464,7 +5714,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
@@ -5473,16 +5723,20 @@ Note that the CRC algorithms are not considered cryptographic algorithms
 and thus are in addition available.
 
 @item
-RSA and DSA key generation refuses to create a key with a keysize of
-less than 1024 bits.  
+RSA key generation refuses to create a key with a keysize of
+less than 1024 bits.
+
+@item
+DSA key generation refuses to create a key with a keysize other
+than 1024 bits.
 
 @item
-The @code{transient-key} flag for RSA key generation is ignored.
+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.
 
@@ -5503,13 +5757,13 @@ supported and all API calls return an error.
 @item
 Registration of external modules is not supported.
 
-@item 
+@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.
 
@@ -5518,7 +5772,12 @@ The function @code{gcry_set_allocation_handler} may not be used.  If
 it is used Libgcrypt disables FIPS mode unless Enforced FIPS mode is
 enabled, in which case Libgcrypt will enter the error state.
 
-@item 
+@item
+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
 In Enforced FIPS mode the command @code{GCRYCTL_DISABLE_SECMEM} is
 ignored.  In standard FIPS mode it disables FIPS mode.
 
@@ -5530,10 +5789,9 @@ A handler set by @code{gcry_set_fatalerror_handler} is ignored.
 @end itemize
 
 Note that when we speak about disabling FIPS mode, it merely means
-that the fucntion @code{gcry_fips_mode_active} returns false; it does
+that the function @code{gcry_fips_mode_active} returns false; it does
 not mean that any non FIPS algorithms are allowed.
 
-
 @c ********************************************
 @section FIPS Finite State Machine
 
@@ -5552,7 +5810,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.
@@ -5568,7 +5826,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.
@@ -5576,11 +5834,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
@@ -5595,7 +5853,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.
 
@@ -5607,9 +5865,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
@@ -5637,7 +5895,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
@@ -5682,6 +5940,25 @@ state.
 @end table
 @end float
 
+@c ********************************************
+@section FIPS Miscellaneous Information
+
+Libgcrypt does not do any key management on itself; the application
+needs to care about it.  Keys which are passed to Libgcrypt should be
+allocated in secure memory as available with the functions
+@code{gcry_malloc_secure} and @code{gcry_calloc_secure}.  By calling
+@code{gcry_free} on this memory, the memory and thus the keys are
+overwritten with zero bytes before releasing the memory.
+
+For use with the random number generator, Libgcrypt generates 3
+internal keys which are stored in the encryption contexts used by the
+RNG.  These keys are stored in secure memory for the lifetime of the
+process.  Application are required to use @code{GCRYCTL_TERM_SECMEM}
+before process termination.  This will zero out the entire secure
+memory and thus also the encryption contexts with these keys.
+
+
+
 @c **********************************************************
 @c *************  Appendices (license etc.)  ****************
 @c **********************************************************
@@ -5720,7 +5997,3 @@ these functions are not really thread safe.
 
 
 @c  LocalWords:  int HD
-
-
-
-