Handle opaque MPIs in gcry_mpi_cmp
[libgcrypt.git] / doc / gcrypt.texi
index 26a9f69..886c396 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 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -77,8 +77,8 @@ section entitled ``GNU General Public License''.
 
 Appendices
 
-* FIPS Restrictions::           Restrictions in FIPS mode.
-* FIPS Finite State Machine::   Description of the FIPS FSM.
+* Self-Tests::                  Description of the self-tests.
+* FIPS Mode::                   Description of the FIPS mode.
 * Library Copying::             The GNU Lesser General Public License
                                 says how you can copy and share Libgcrypt.
 * Copying::                     The GNU General Public License says how you
@@ -187,7 +187,7 @@ of the library are verified.
 * Building sources using Automake::  How to build sources with the help of Automake.
 * Initializing the library::    How to initialize the library.
 * Multi-Threading::             How Libgcrypt can be used in a MT environment.
-* FIPS mode::                   How to enable the FIPS mode.
+* Enabling FIPS mode::          How to enable the FIPS mode.
 @end menu
 
 
@@ -391,8 +391,8 @@ and freed memory, you need to initialize Libgcrypt this way:
   gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
 
 @anchor{sample-use-resume-secmem}
-  /* It is now okay to let Libgcrypt complain when there was/is a problem
-     with the secure memory. */
+  /* It is now okay to let Libgcrypt complain when there was/is
+     a problem with the secure memory. */
   gcry_control (GCRYCTL_RESUME_SECMEM_WARN);
 
   /* ... If required, other initialization goes here.  */
@@ -488,25 +488,39 @@ necessary thread callbacks for PThread and for GNU Pth:
 @table @code
 @item GCRY_THREAD_OPTION_PTH_IMPL
 
-This macro defines the following (static) symbols: gcry_pth_init,
-gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock,
-gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write, gcry_pth_select,
-gcry_pth_waitpid, gcry_pth_accept, gcry_pth_connect, gcry_threads_pth.
+This macro defines the following (static) symbols:
+@code{gcry_pth_init}, @code{gcry_pth_mutex_init},
+@code{gcry_pth_mutex_destroy}, @code{gcry_pth_mutex_lock},
+@code{gcry_pth_mutex_unlock}, @code{gcry_pth_read},
+@code{gcry_pth_write}, @code{gcry_pth_select},
+@code{gcry_pth_waitpid}, @code{gcry_pth_accept},
+@code{gcry_pth_connect}, @code{gcry_threads_pth}.
+
+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''.  Example:
+
+@smallexample
+  ret = gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pth);
+@end smallexample
 
-After including this macro, gcry_control() shall be used with a
-command of GCRYCTL_SET_THREAD_CBS in order to register the thread
-callback structure named ``gcry_threads_pth''.
 
 @item GCRY_THREAD_OPTION_PTHREAD_IMPL
 
 This macro defines the following (static) symbols:
-gcry_pthread_mutex_init, gcry_pthread_mutex_destroy,
-gcry_pthread_mutex_lock, gcry_pthread_mutex_unlock,
-gcry_threads_pthread.
+@code{gcry_pthread_mutex_init}, @code{gcry_pthread_mutex_destroy},
+@code{gcry_pthread_mutex_lock}, @code{gcry_pthread_mutex_unlock},
+@code{gcry_threads_pthread}.
+
+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''.  Example:
+
+@smallexample
+  ret = gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pthread);
+@end smallexample
+
 
-After including this macro, gcry_control() shall be used with a
-command of GCRYCTL_SET_THREAD_CBS in order to register the thread
-callback structure named ``gcry_threads_pthread''.
 @end table
 
 Note that these macros need to be terminated with a semicolon.  Keep
@@ -514,9 +528,10 @@ in mind that these are convenient macros for C programmers; C++
 programmers might have to wrap these macros in an ``extern C'' body.
 
 
-
-@node FIPS mode
-@section FIPS Mode
+@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
@@ -536,7 +551,7 @@ initialization time.  Obviously this works only on systems with a
 @code{proc} file system (i.e. GNU/Linux).
 
 @item 
-If the file @file{/etc/gcrypt/fips140.force} exists, Libgcrypt is put
+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.
 
@@ -547,10 +562,18 @@ initialization (i.e. before @code{gcry_check_version}).
 
 @end itemize
 
+@cindex Enforced FIPS mode
+
+In addition to the standard FIPS mode, Libgcrypt may also be put into
+an Enforced FIPS mode by writing a non-zero value into the file
+@file{/etc/gcrypt/fips_enabled}.  The Enforced FIPS mode helps to
+detect applications which don't fulfill all requirements for using
+Libgcrypt in FIPS mode (@pxref{FIPS Mode}).
+
 Once Libgcrypt has been put into FIPS mode, it is not possible to
 switch back to standard mode without terminating the process first.
 If the logging verbosity level of Libgcrypt has been set to at least
-2, the state transitions and the selftests are logged.
+2, the state transitions and the self-tests are logged.
 
 
 
@@ -577,11 +600,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
@@ -614,13 +638,14 @@ to disable secure memory is to use @code{GCRYCTL_DISABLE_SECMEM} right
 after initialization.
 
 @item GCRYCTL_DISABLE_SECMEM; Arguments: none
-This command disables the use of secure memory. 
+This command disables the use of secure memory.  If this command is
+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.  There won't be a problem if not disabling it unless one
-makes use of a feature which requires secure memory - in that case the
-process will abort because the secmem is not initialized.  This command
-should be executed right after @code{gcry_check_version}.
+it right away.  This command should be executed right after
+@code{gcry_check_version}. 
 
 @item GCRYCTL_INIT_SECMEM; Arguments: int nbytes
 This command is used to allocate a pool of secure memory and thus
@@ -723,7 +748,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
@@ -764,11 +789,21 @@ the intialization has been finished but not before a gcry_version_check.
 This command returns true if the library is in FIPS mode.  Note, that
 this is no indication about the current state of the library.  This
 command may be used before the intialization has been finished but not
-before a gcry_version_check.
+before a gcry_version_check.  An application may use this command or
+the convenience macro below to check whether FIPS mode is actually
+active.
+
+@deftypefun int gcry_fips_mode_active (void)
+
+Returns true if the FIPS mode is active.  Note that this is
+implemented as a macro.
+@end deftypefun
+
+
 
 @item GCRYCTL_FORCE_FIPS_MODE; Arguments: none
 Running this command puts the library into FIPS mode.  If the library is
-already in FIPS mode, a selftest is triggered and thus the library will
+already in FIPS mode, a self-test is triggered and thus the library will
 be put into operational state.  This command may be used before a call
 to gcry_check_version and that is actually the recommended way to let an
 application switch the library into FIPS mode.  Note that Libgcrypt will
@@ -776,7 +811,7 @@ reject an attempt to switch to fips mode during or after the intialization.
 
 @item GCRYCTL_SELFTEST; Arguments: none
 This may be used at anytime to have the library run all implemented
-selftests.  It works in standard and in FIPS mode.  Returns 0 on
+self-tests.  It works in standard and in FIPS mode.  Returns 0 on
 success or an error code on failure.
 
 
@@ -1167,7 +1202,8 @@ above:
   gcry_cipher_hd_t handle;
   gcry_error_t err = 0;
 
-  err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0);
+  err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, 
+                          GCRY_CIPHER_MODE_CBC, 0);
   if (err)
     @{
       fprintf (stderr, "Failure: %s/%s\n",
@@ -1184,7 +1220,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.
@@ -1212,7 +1248,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
@@ -1286,7 +1323,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
@@ -1297,12 +1341,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
@@ -1357,18 +1407,25 @@ This is not a real algorithm but used by some functions as error return.
 The value always evaluates to false.
 
 @item GCRY_CIPHER_IDEA
+@cindex IDEA
 This is the IDEA algorithm.  The constant is provided but there is
 currently no implementation for it because the algorithm is patented.
 
 @item GCRY_CIPHER_3DES
+@cindex 3DES
+@cindex Triple-DES
+@cindex DES-EDE
+@cindex Digital Encryption Standard
 Triple-DES with 3 Keys as EDE.  The key size of this algorithm is 168 but
 you have to pass 192 bits because the most significant bits of each byte
 are ignored.
 
 @item GCRY_CIPHER_CAST5
+@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
 size of 128 bits.
 
@@ -1382,6 +1439,9 @@ Reserved and not currently implemented.
 @itemx GCRY_CIPHER_AES128
 @itemx GCRY_CIPHER_RIJNDAEL
 @itemx GCRY_CIPHER_RIJNDAEL128
+@cindex Rijndael
+@cindex AES
+@cindex Advanced Encryption Standard
 AES (Rijndael) with a 128 bit key.
 
 @item  GCRY_CIPHER_AES192     
@@ -1393,17 +1453,21 @@ AES (Rijndael) with a 192 bit key.
 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   
+@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. 
 
-@item  GCRY_CIPHER_DES       
+@item  GCRY_CIPHER_DES
+@cindex DES
 Standard DES with a 56 bit key. You need to pass 64 bit but the high
 bits of each byte are ignored.  Note, that this is a weak algorithm
 which can be broken in reasonable time using a brute force approach.
@@ -1411,20 +1475,25 @@ which can be broken in reasonable time using a brute force approach.
 @item  GCRY_CIPHER_SERPENT128
 @itemx GCRY_CIPHER_SERPENT192
 @itemx GCRY_CIPHER_SERPENT256
+@cindex Serpent
 The Serpent cipher from the AES contest.
 
 @item  GCRY_CIPHER_RFC2268_40
 @itemx GCRY_CIPHER_RFC2268_128
+@cindex rfc-2268
+@cindex RC2
 Ron's Cipher 2 in the 40 and 128 bit variants.  Note, that we currently
 only support the 40 bit variant.  The identifier for 128 is reserved for
 future use.
 
 @item GCRY_CIPHER_SEED
+@cindex Seed (cipher)
 A 128 bit cipher as described by RFC4269.
 
 @item  GCRY_CIPHER_CAMELLIA128
 @itemx GCRY_CIPHER_CAMELLIA192
 @itemx GCRY_CIPHER_CAMELLIA256
+@cindex Camellia
 The Camellia cipher by NTT.  See
 @uref{http://info.isl.ntt.co.jp/@/crypt/@/eng/@/camellia/@/specifications.html}.
 
@@ -1509,13 +1578,13 @@ unsigned char *inbuf)
 
 @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
+(*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
+(*gcry_@/cipher_@/stdecrypt_@/t) (void *c, const unsigned char *outbuf, const
 unsigned char *, unsigned int n)
 @end deftp
 
@@ -1552,23 +1621,43 @@ if Libgcrypt is not used in FIPS mode and if any debug flag has been
 set, this mode may be used to bypass the actual encryption.
 
 @item GCRY_CIPHER_MODE_ECB
+@cindex ECB, Electronic Codebook mode
 Electronic Codebook mode.  
 
 @item GCRY_CIPHER_MODE_CFB
-Cipher Feedback mode.
+@cindex CFB, Cipher Feedback mode
+Cipher Feedback mode.  The shift size equals the block size of the
+cipher (e.g. for AES it is CFB-128).
 
 @item  GCRY_CIPHER_MODE_CBC
+@cindex CBC, Cipher Block Chaining mode
 Cipher Block Chaining mode.
 
 @item GCRY_CIPHER_MODE_STREAM
 Stream mode, only to be used with stream cipher algorithms.
 
 @item GCRY_CIPHER_MODE_OFB
+@cindex OFB, Output Feedback mode
 Output Feedback mode.
 
 @item  GCRY_CIPHER_MODE_CTR
+@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
@@ -1609,15 +1698,18 @@ the bit-wise OR of the following constants.
 Make sure that all operations are allocated in secure memory.  This is
 useful when the key material is highly confidential.
 @item GCRY_CIPHER_ENABLE_SYNC
+@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. 
 See @code{gcry_cipher_sync}.
 @item GCRY_CIPHER_CBC_CTS
+@cindex cipher text stealing
 Enable cipher text stealing (CTS) for the CBC mode.  Cannot be used
 simultaneous as GCRY_CIPHER_CBC_MAC.  CTS mode makes it possible to
 transform data of almost arbitrary size (only limitation is that it
 must be greater than the algorithm's block size).
 @item GCRY_CIPHER_CBC_MAC
+@cindex CBC-MAC
 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.
@@ -1629,6 +1721,8 @@ 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
@@ -1637,11 +1731,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
 
@@ -1653,18 +1747,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})
@@ -2365,9 +2459,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
@@ -2561,7 +2655,7 @@ and @var{buflen} must have the value @code{sizeof (int)}.
 @c end gcry_pk_ctl
 
 @noindent
-Libgcrypt also provides a function for generating public key
+Libgcrypt also provides a function to generate public key
 pairs:
 
 @deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
@@ -2573,12 +2667,12 @@ an error, @var{r_key} is set to @code{NULL}.  The return code is 0 for
 success or an error code otherwise.
 
 @noindent
-Here is an example for @var{parms} for creating a 1024 bit RSA key:
+Here is an example for @var{parms} to create an 2048 bit RSA key:
 
 @example
 (genkey
   (rsa
-    (nbits 4:1024)))
+    (nbits 4:2048)))
 @end example
 
 @noindent
@@ -2609,10 +2703,12 @@ are special:
 @item 0
 Use a secure and fast value.  This is currently the number 41.
 @item 1
-Use a secure value as required by some specification.  This is currently
+Use a value as required by some crypto policies.  This is currently
 the number 65537.
 @item 2
 Reserved
+@item > 2
+Use the given value.
 @end table
 
 @noindent
@@ -2640,10 +2736,90 @@ 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
+generated with domain parameters taken from this list.  The exact
+format of this parameter depends on the actual algorithm.  It is
+currently only implemented for DSA using this format:
+
+@example
+(genkey
+  (dsa
+    (domain
+      (p @var{p-mpi})
+      (q @var{q-mpi})
+      (g @var{q-mpi}))))
+@end example
+
+@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
@@ -2671,16 +2847,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
 
@@ -2695,7 +2872,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
@@ -3010,7 +3187,8 @@ Example code:
   err = gcry_ac_open  (&handle, GCRY_AC_RSA, 0);
   assert (! err);
 
-  err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec, &key_pair, NULL);
+  err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec,
+                                   &key_pair, NULL);
   assert (! err);
 @}
 @end example
@@ -3245,6 +3423,14 @@ are also supported.
 @section Available hash algorithms
 
 @c begin table of hash algorithms
+@cindex SHA-1
+@cindex SHA-224, SHA-256, SHA-384, SHA-512
+@cindex RIPE-MD-160
+@cindex MD2, MD4, MD5
+@cindex TIGER, TIGER1, TIGER2
+@cindex HAVAL
+@cindex Whirlpool
+@cindex CRC32
 @table @code
 @item GCRY_MD_NONE
 This is not a real algorithm but used by some functions as an error
@@ -3252,26 +3438,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.
 
@@ -3292,16 +3498,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
@@ -3436,11 +3645,13 @@ Allocate all buffers and the resulting digest in "secure memory".  Use
 this is the hashed data is highly confidential.
 
 @item GCRY_MD_FLAG_HMAC
+@cindex HMAC
 Turn the algorithm into a HMAC message authentication algorithm.  This
-only works if just one algorithm is enabled for the handle.  Note that the function
-@code{gcry_md_setkey} must be used to set the MAC key.  If you want CBC
-message authentication codes based on a cipher, see @xref{Working with
-cipher handles}.
+only works if just one algorithm is enabled for the handle.  Note that
+the function @code{gcry_md_setkey} must be used to set the MAC key.
+The size of the MAC is equal to the message digest of the underlying
+hash algorithm.  If you want CBC message authentication codes based on
+a cipher, see @xref{Working with cipher handles}.
 
 @end table
 @c begin table of hash flags
@@ -3466,8 +3677,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}.
+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
 
 
@@ -3478,7 +3690,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
 
@@ -3864,8 +4078,13 @@ 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
@@ -3876,7 +4095,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
 
 
@@ -3937,8 +4159,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}})
 
@@ -4286,7 +4507,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}})
@@ -4470,15 +4694,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
 
@@ -4618,9 +4842,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.
 
 
 
@@ -4800,6 +5031,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
 
@@ -4932,7 +5171,7 @@ before and thus gets initialized on the first use by
 weaker requirements for a nonce generator and to save precious kernel
 entropy for use by the ``real'' random generators.
 
-A self test facility uses a separate context to check the
+A self-test facility uses a separate context to check the
 functionality of the core X9.31 functions using a known answers test.
 During runtime each output block is compared to the previous one to
 detect a stucked generator.
@@ -4942,8 +5181,6 @@ 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 
@@ -4993,9 +5230,357 @@ incremented on each use.
 @c **********************************************************
 
 @c ********************************************
-@node FIPS Restrictions
-@appendix Restrictions in FIPS mode
+@node Self-Tests
+@appendix Description of the Self-Tests
+
+In addition to the build time regression test suite, Libgcrypt
+implements self-tests to be performed at runtime.  Which self-tests
+are actually used depends on the mode Libgcrypt is used in.  In
+standard mode a limited set of self-tests is run at the time an
+algorithm is first used.  Note that not all algorithms feature a
+self-test in standard mode.  The @code{GCRYCTL_SELFTEST} control
+command may be used to run all implemented self-tests at any time;
+this will even run more tests than those run in FIPS mode.
+
+If any of the self-tests fails, the library immediately returns an
+error code to the caller.  If Libgcrypt is in FIPS mode the self-tests
+will be performed within the ``Self-Test'' state and any failure puts
+the library into the ``Error'' state.
+
+@c --------------------------------
+@section Power-Up Tests
+
+Power-up tests are only performed if Libgcrypt is in FIPS mode.  
+
+@subsection Symmetric Cipher Algorithm Power-Up Tests
+
+The following symmetric encryption algorithm tests are run during
+power-up:
+
+@table @asis
+@item 3DES
+To test the 3DES 3-key EDE encryption in ECB mode these tests are
+run:
+@enumerate
+@item
+A known answer test is run on a 64 bit test vector processed by 64
+rounds of Single-DES block encryption and decryption using a key
+changed with each round.
+@item
+A known answer test is run on a 64 bit test vector processed by 16
+rounds of 2-key and 3-key Triple-DES block encryption and decryptions
+using a key changed with each round.
+@item
+10 known answer tests using 3-key Triple-DES EDE encryption, comparing
+the ciphertext to the known value, then running a decryption and
+comparing it to the initial plaintext.
+@end enumerate
+(@code{cipher/des.c:selftest})
+
+@item AES-128
+A known answer tests is run using one test vector and one test
+key with AES in ECB mode. (@code{cipher/rijndael.c:selftest_basic_128})
+
+@item AES-192
+A known answer tests is run using one test vector and one test
+key with AES in ECB mode. (@code{cipher/rijndael.c:selftest_basic_192})
+
+@item AES-256
+A known answer tests is run using one test vector and one test key
+with AES in ECB mode. (@code{cipher/rijndael.c:selftest_basic_256})
+@end table
+
+@subsection Hash Algorithm Power-Up Tests
+
+The following hash algorithm tests are run during power-up:
+
+@table @asis
+@item SHA-1
+A known answer test using the string @code{"abc"} is run.
+(@code{cipher/@/sha1.c:@/selftests_sha1})
+@item SHA-224
+A known answer test using the string @code{"abc"} is run.
+(@code{cipher/@/sha256.c:@/selftests_sha224})
+@item SHA-256
+A known answer test using the string @code{"abc"} is run.
+(@code{cipher/@/sha256.c:@/selftests_sha256})
+@item SHA-384
+A known answer test using the string @code{"abc"} is run.
+(@code{cipher/@/sha512.c:@/selftests_sha384})
+@item SHA-512
+A known answer test using the string @code{"abc"} is run.
+(@code{cipher/@/sha512.c:@/selftests_sha512})
+@end table
+
+@subsection MAC Algorithm Power-Up Tests
+
+The following MAC algorithm tests are run during power-up:
+
+@table @asis
+@item HMAC SHA-1
+A known answer test using 9 byte of data and a 64 byte key is run.
+(@code{cipher/hmac-tests.c:selftests_sha1})
+@item HMAC SHA-224
+A known answer test using 28 byte of data and a 4 byte key is run.
+(@code{cipher/hmac-tests.c:selftests_sha224})
+@item HMAC SHA-256
+A known answer test using 28 byte of data and a 4 byte key is run.
+(@code{cipher/hmac-tests.c:selftests_sha256})
+@item HMAC SHA-384
+A known answer test using 28 byte of data and a 4 byte key is run.
+(@code{cipher/hmac-tests.c:selftests_sha384})
+@item HMAC SHA-512
+A known answer test using 28 byte of data and a 4 byte key is run.
+(@code{cipher/hmac-tests.c:selftests_sha512})
+@end table
+
+@subsection Random Number Power-Up Test
+
+The DRNG is tested during power-up this way:
+
+@enumerate
+@item 
+Requesting one block of random using the public interface to check
+general working and the duplicated block detection.
+@item
+3 know answer tests using pre-defined keys, seed and initial DT
+values.  For each test 3 blocks of 16 bytes are requested and compared
+to the expected result.  The DT value is incremented for each block.
+@end enumerate
+
+@subsection Public Key Algorithm Power-Up Tests
+
+The public key algorithms are tested during power-up:
+
+@table @asis
+@item RSA
+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. 
+(@code{cipher/@/rsa.c:@/selftests_rsa})
+@item 
+Private key consistency check.
+(@code{cipher/@/rsa.c:@/selftests_rsa})
+@item
+A pre-defined 20 byte value is signed with PKCS#1 padding for SHA-1.
+The result is verified using the public key against the original data
+and against modified data.  (@code{cipher/@/rsa.c:@/selftest_sign_1024})
+@item
+A 1000 bit random value is encrypted and checked that it does not
+match the orginal random value.  The encrtypted result is then
+decrypted and checked that it macthes the original random value.
+(@code{cipher/@/rsa.c:@/selftest_encr_1024})
+@end enumerate
 
+@item DSA
+A pre-defined 1024 bit DSA key is used and these tests are run in turn:
+@enumerate
+@item
+Conversion of S-expression to internal format.
+(@code{cipher/@/dsa.c:@/selftests_dsa})
+@item
+Private key consistency check.
+(@code{cipher/@/dsa.c:@/selftests_dsa})
+@item
+A pre-defined 20 byte value is signed with PKCS#1 padding for
+SHA-1.  The result is verified using the public key against the
+original data and against modified data.
+(@code{cipher/@/dsa.c:@/selftest_sign_1024})
+@end enumerate
+@end table
+
+@subsection Integrity Power-Up Tests
+
+The integrity of the Libgcrypt is tested during power-up but only if
+checking has been enabled at build time.  The check works by computing
+a HMAC SHA-256 checksum over the file used to load Libgcrypt into
+memory.  That checksum is compared against a checksum stored in a file
+of the same name but with a single dot as a prefix and a suffix of
+@file{.hmac}.
+
+
+@subsection Critical Functions Power-Up Tests
+
+The 3DES weak key detection is tested during power-up by calling the
+detection function with keys taken from a table listening all weak
+keys.  The table itself is protected using a SHA-1 hash.
+(@code{cipher/@/des.c:@/selftest})
+
+
+
+@c --------------------------------
+@section Conditional Tests
+
+The conditional tests are performed if a certain contidion is met.
+This may occur at any time; the library does not necessary enter the
+``Self-Test'' state to run these tests but will transit to the
+``Error'' state if a test failed.
+
+@subsection Key-Pair Generation Tests
+
+After an asymmetric key-pair has been generated, Libgcrypt runs a
+pair-wise consistency tests on the generated key.  On failure the
+generated key is not used, an error code is returned and, if in FIPS
+mode, the library is put into the ``Error'' state.
+
+@table @asis
+@item RSA
+The test uses a random number 64 bits less the size of the modulus as
+plaintext and runs an encryption and decryption operation in turn.  The
+encrypted value is checked to not match the plaintext and the result
+of the decryption is checked to match the plaintext.
+
+A new random number of the same size is generated, signed and verified
+to test the correctness of the signing operation.  As a second signing
+test, the signature is modified by incrementing its value and then
+verified with the expected result that the verification fails.
+(@code{cipher/@/rsa.c:@/test_keys})
+@item DSA
+The test uses a random number of the size of the Q parameter to create
+a signature and then checks that the signature verifies.  As a second
+signing test, the data is modified by incrementing its value and then
+verified against the signature with the expected result that the
+verification fails.  (@code{cipher/@/dsa.c:@/test_keys})
+@end table
+
+
+@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/@/pubkey.c:@/_gcry_pk_register})
+
+
+@subsection Manual Key Entry Tests
+
+A manual key entry feature is not implemented in Libgcrypt.
+
+
+@subsection Continuous RNG Tests
+
+The continuous random number test is only used in FIPS mode.  The RNG
+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 library is put into the
+``Fatal-Error'' state.
+(@code{random/@/random-fips.c:@/x931_aes_driver})
+
+
+
+@c --------------------------------
+@section Application Requested Tests
+
+The application may requests tests at any time by means of the
+@code{GCRYCTL_SELFTEST} control command.  Note that using these tests
+is not FIPS conform: Although Libgcrypt rejects all application
+requests for services while running self-tests, it does not ensure
+that no other operations of Libgcrypt are still being executed.  Thus,
+in FIPS mode an application requesting self-tests needs to power-cycle
+Libgcrypt instead.
+
+When self-tests are requested, Libgcrypt runs all the tests it does
+during power-up as well as a few extra checks as described below.
+
+@subsection Symmetric Cipher Algorithm Tests
+
+The following symmetric encryption algorithm tests are run in addition
+to the power-up tests:
+
+@table @asis
+@item AES-128
+A known answer tests with test vectors taken from NIST SP800-38a and
+using the high level functions is run for block modes CFB and OFB.
+
+@end table
+
+@subsection Hash Algorithm Tests
+
+The following hash algorithm tests are run in addition to the 
+power-up tests:
+
+@table @asis
+@item SHA-1
+@itemx SHA-224
+@itemx SHA-256
+@enumerate
+@item
+A known answer test using a 56 byte string is run.
+@item 
+A known answer test using a string of one million letters "a" is run.
+@end enumerate
+(@code{cipher/@/sha1.c:@/selftests_sha1},
+@code{cipher/@/sha256.c:@/selftests_sha224},
+@code{cipher/@/sha256.c:@/selftests_sha256})
+@item SHA-384
+@item SHA-512
+@enumerate
+@item
+A known answer test using a 112 byte string is run.
+@item 
+A known answer test using a string of one million letters "a" is run.
+@end enumerate
+(@code{cipher/@/sha512.c:@/selftests_sha384},
+@code{cipher/@/sha512.c:@/selftests_sha512})
+@end table
+
+@subsection MAC Algorithm Tests
+
+The following MAC algorithm tests are run in addition to the power-up
+tests:
+
+@table @asis
+@item HMAC SHA-1
+@enumerate
+@item
+A known answer test using 9 byte of data and a 20 byte key is run.
+@item
+A known answer test using 9 byte of data and a 100 byte key is run.
+@item
+A known answer test using 9 byte of data and a 49 byte key is run.
+@end enumerate
+(@code{cipher/hmac-tests.c:selftests_sha1})
+@item HMAC SHA-224
+@itemx HMAC SHA-256
+@itemx HMAC SHA-384
+@itemx HMAC SHA-512
+@enumerate
+@item
+A known answer test using 9 byte of data and a 20 byte key is run.
+@item
+A known answer test using 50 byte of data and a 20 byte key is run.
+@item
+A known answer test using 50 byte of data and a 26 byte key is run.
+@item
+A known answer test using 54 byte of data and a 131 byte key is run.
+@item
+A known answer test using 152 byte of data and a 131 byte key is run.
+@end enumerate
+(@code{cipher/@/hmac-tests.c:@/selftests_sha224},
+@code{cipher/@/hmac-tests.c:@/selftests_sha256},
+@code{cipher/@/hmac-tests.c:@/selftests_sha384},
+@code{cipher/@/hmac-tests.c:@/selftests_sha512})
+@end table
+
+
+@c ********************************************
+@node FIPS Mode
+@appendix Description of the FIPS Mode
+
+This appendix gives detailed information pertaining to the FIPS mode.
+In particular, the changes to the standard mode and the finite state
+machine are described.  The self-tests required in this mode are
+described in the appendix on self-tests.
+
+@c -------------------------------
+@section Restrictions in FIPS Mode
+
+@noindent
 If Libgcrypt is used in FIPS mode these restrictions are effective:
 
 @itemize
@@ -5041,11 +5626,15 @@ 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
+RSA key generation refuses to create a key with a keysize of
 less than 1024 bits.  
 
 @item
-The @code{transient-key} flag for RSA key generation is ignored.
+DSA key generation refuses to create a key with a keysize other
+than 1024 bits.
+
+@item
+The @code{transient-key} flag for RSA and DSA key generation is ignored.
 
 @item
 Support for the VIA Padlock engine is disabled.
@@ -5055,17 +5644,21 @@ FIPS mode may only be used on systems with a /dev/random device.
 Switching into FIPS mode on other systems will fail at runtime.
 
 @item
-Saving and loading a random seed file is not ignored.
+Saving and loading a random seed file is ignored.
 
 @item
 An X9.31 style random number generator is used in place of the
 large-pool-CSPRNG generator.
 
 @item
+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
+Registration of external modules is not supported.
 
 @item 
 Message digest debugging is disabled.
@@ -5074,25 +5667,36 @@ Message digest debugging is disabled.
 All debug output related to cryptographic data is suppressed.
 
 @item 
-On-the-fly self-tests are not performed, instead of this self-tests are
-run before entering operational state.
+On-the-fly self-tests are not performed, instead self-tests are run
+before entering operational state.
 
 @item
-The function @code{gcry_set_allocation_handler} may not be used.  If it
-is used Libgcrypt will enter the error state.
+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
+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.
 
 @item
 A handler set by @code{gcry_set_outofcore_handler} is ignored.
 @item
 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 function @code{gcry_fips_mode_active} returns false; it does
+not mean that any non FIPS algorithms are allowed.
 
 @c ********************************************
-@node FIPS Finite State Machine
-@appendix FIPS Finite State Machine
+@section FIPS Finite State Machine
 
 The FIPS mode of libgcrypt implements a finite state machine (FSM) using
 8 states (@pxref{tbl:fips-states}) and checks at runtime that only valid
@@ -5213,7 +5817,7 @@ running self-tests.
 Self-Test to Error is triggred by a failed self-test.
 
 @item 15
-Operational to Fatal-Error is triggred if Libcrypt encountered a
+Operational to Fatal-Error is triggered if Libcrypt encountered a
 non-recoverable error.
 
 @item 16
@@ -5224,9 +5828,40 @@ the self-tests again.
 Error to Self-Test is triggered if the application has requested to run
 self-tests to get to get back into operational state after an error.
 
+@item 18
+Init to Error is triggered by errors in the initialization code.
+
+@item 19
+Init to Fatal-Error is triggered by non-recoverable errors in the
+initialization code.
+
+@item 20
+Error to Error is triggered by errors while already in the Error
+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 **********************************************************