build: Convince gcc not to delete NULL ptr checks.
[libgcrypt.git] / doc / gcrypt.texi
index 410c45d..967745f 100644 (file)
@@ -14,7 +14,7 @@ which is GNU's library of cryptographic building blocks.
 
 @noindent
 Copyright @copyright{} 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011, 2012 Free Software Foundation, Inc. @*
-Copyright @copyright{} 2012, 2013 g10 Code GmbH
+Copyright @copyright{} 2012, 2013, 2016, 2017 g10 Code GmbH
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -94,7 +94,8 @@ section entitled ``GNU General Public License''.
 * MPI library::                  How to work with multi-precision-integers.
 * Prime numbers::                How to use the Prime number related functions.
 * Utilities::                    Utility functions.
-* Tools::                        Utility tools
+* Tools::                        Utility tools.
+* Configuration::                Configuration files and environment variables.
 * Architecture::                 How Libgcrypt works internally.
 
 Appendices
@@ -188,8 +189,8 @@ the same handle, he has to take care of the serialization of such
 functions himself.  If not described otherwise, every function is
 thread-safe.
 
-Libgcrypt depends on the library `libgpg-error', which
-contains common error handling related code for GnuPG components.
+Libgcrypt depends on the library `libgpg-error', which contains some
+common code used by other GnuPG components.
 
 @c **********************************************************
 @c *******************  Preparation  ************************
@@ -267,9 +268,9 @@ example shows how it can be used at the command line:
 gcc -c foo.c `libgcrypt-config --cflags`
 @end example
 
-Adding the output of @samp{libgcrypt-config --cflags} to the compilers
-command line will ensure that the compiler can find the Libgcrypt header
-file.
+Adding the output of @samp{libgcrypt-config --cflags} to the
+compiler’s command line will ensure that the compiler can find the
+Libgcrypt header file.
 
 A similar problem occurs when linking the program with the library.
 Again, the compiler has to find the library files.  For this to work,
@@ -314,7 +315,20 @@ found, execute @var{action-if-found}, otherwise do
 Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the
 flags needed for compilation of the program to find the
 @file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker
-flags needed to link the program to the Libgcrypt library.
+flags needed to link the program to the Libgcrypt library.  If the
+used helper script does not match the target type you are building for
+a warning is printed and the string @code{libgcrypt} is appended to the
+variable @code{gpg_config_script_warn}.
+
+This macro searches for @command{libgcrypt-config} along the PATH.  If
+you are cross-compiling, it is useful to set the environment variable
+@code{SYSROOT} to the top directory of your target.  The macro will
+then first look for the helper program in the @file{bin} directory
+below that top directory.  An absolute directory name must be used for
+@code{SYSROOT}.  Finally, if the configure command line option
+@code{--with-libgcrypt-prefix} is used, only its value is used for the top
+directory below which the helper script is expected.
+
 @end defmac
 
 You can use the defined Autoconf variables like this in your
@@ -343,8 +357,7 @@ after program startup.
 
 The function @code{gcry_check_version} initializes some subsystems used
 by Libgcrypt and must be invoked before any other function in the
-library, with the exception of the @code{GCRYCTL_SET_THREAD_CBS} command
-(called via the @code{gcry_control} function).
+library.
 @xref{Multi-Threading}.
 
 Furthermore, this function returns the version number of the library.
@@ -369,7 +382,7 @@ memory is not a problem, you should initialize Libgcrypt this way:
 
 @example
   /* Version check should be the very first call because it
-     makes sure that important subsystems are intialized. */
+     makes sure that important subsystems are initialized. */
   if (!gcry_check_version (GCRYPT_VERSION))
     @{
       fputs ("libgcrypt version mismatch\n", stderr);
@@ -409,8 +422,11 @@ and freed memory, you need to initialize Libgcrypt this way:
      process might still be running with increased privileges and that
      the secure memory has not been initialized.  */
 
-  /* Allocate a pool of 16k secure memory.  This make the secure memory
-     available and also drops privileges where needed.  */
+  /* Allocate a pool of 16k secure memory.  This makes the secure memory
+     available and also drops privileges where needed.  Note that by
+     using functions like gcry_xmalloc_secure and gcry_mpi_snew Libgcrypt
+     may expand the secure memory pool with memory which lacks the
+     property of not being swapped out to disk.   */
   gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
 
 @anchor{sample-use-resume-secmem}
@@ -450,51 +466,16 @@ thread-safe if you adhere to the following requirements:
 
 @itemize @bullet
 @item
-If your application is multi-threaded, you must set the thread support
-callbacks with the @code{GCRYCTL_SET_THREAD_CBS} command
-@strong{before} any other function in the library.
-
-This is easy enough if you are indeed writing an application using
-Libgcrypt.  It is rather problematic if you are writing a library
-instead.  Here are some tips what to do if you are writing a library:
-
-If your library requires a certain thread package, just initialize
-Libgcrypt to use this thread package.  If your library supports multiple
-thread packages, but needs to be configured, you will have to
-implement a way to determine which thread package the application
-wants to use with your library anyway.  Then configure Libgcrypt to use
-this thread package.
-
-If your library is fully reentrant without any special support by a
-thread package, then you are lucky indeed.  Unfortunately, this does
-not relieve you from doing either of the two above, or use a third
-option.  The third option is to let the application initialize Libgcrypt
-for you.  Then you are not using Libgcrypt transparently, though.
-
-As if this was not difficult enough, a conflict may arise if two
-libraries try to initialize Libgcrypt independently of each others, and
-both such libraries are then linked into the same application.  To
-make it a bit simpler for you, this will probably work, but only if
-both libraries have the same requirement for the thread package.  This
-is currently only supported for the non-threaded case, GNU Pth and
-pthread.
-
 If you use pthread and your applications forks and does not directly
 call exec (even calling stdio functions), all kind of problems may
 occur.  Future versions of Libgcrypt will try to cleanup using
 pthread_atfork but even that may lead to problems.  This is a common
 problem with almost all applications using pthread and fork.
 
-Note that future versions of Libgcrypt will drop this flexible thread
-support and instead only support the platforms standard thread
-implementation.
-
 
 @item
 The function @code{gcry_check_version} must be called before any other
-function in the library, except the @code{GCRYCTL_SET_THREAD_CBS}
-command (called via the @code{gcry_control} function), because it
-initializes the thread support subsystem in Libgcrypt.  To
+function in the library.  To
 achieve this in multi-threaded programs, you must synchronize the
 memory with respect to other threads that also want to use
 Libgcrypt.  For this, it is sufficient to call
@@ -515,57 +496,12 @@ Just like the function @code{gpg_strerror}, the function
 @end itemize
 
 
-Libgcrypt contains convenient macros, which define the
-necessary thread callbacks for PThread and for GNU Pth:
-
-@table @code
-@item GCRY_THREAD_OPTION_PTH_IMPL
-
-This macro defines the following (static) symbols:
-@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
-
-
-@item GCRY_THREAD_OPTION_PTHREAD_IMPL
-
-This macro defines the following (static) symbols:
-@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
-
-
-@end table
-
-Note that these macros need to be terminated with a semicolon.  Keep
-in mind that these are convenient macros for C programmers; C++
-programmers might have to wrap these macros in an ``extern C'' body.
-
-
 @node Enabling FIPS mode
 @section How to enable the FIPS mode
 @cindex FIPS mode
 @cindex FIPS 140
 
+@anchor{enabling fips mode}
 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
 NIST database at @url{http://csrc.nist.gov/groups/STM/cmvp/} to see what
@@ -614,6 +550,7 @@ If the logging verbosity level of Libgcrypt has been set to at least
 @section How to disable hardware features
 @cindex hardware features
 
+@anchor{hardware features}
 Libgcrypt makes use of certain hardware features.  If the use of a
 feature is not desired it may be either be disabled by a program or
 globally using a configuration file.  The currently supported features
@@ -625,6 +562,7 @@ are
 @item padlock-sha
 @item padlock-mmul
 @item intel-cpu
+@item intel-fast-shld
 @item intel-bmi2
 @item intel-ssse3
 @item intel-pclmul
@@ -632,6 +570,7 @@ are
 @item intel-rdrand
 @item intel-avx
 @item intel-avx2
+@item intel-rdtsc
 @item arm-neon
 @end table
 
@@ -732,7 +671,10 @@ it right away.  This command should be executed right after
 This command disables the use of the mlock call for secure memory.
 Disabling the use of mlock may for example be done if an encrypted
 swap space is in use.  This command should be executed right after
-@code{gcry_check_version}.
+@code{gcry_check_version}.  Note that by using functions like
+gcry_xmalloc_secure and gcry_mpi_snew Libgcrypt may expand the secure
+memory pool with memory which lacks the property of not being swapped
+out to disk (but will still be zeroed out on free).
 
 @item GCRYCTL_DISABLE_PRIV_DROP; Arguments: none
 This command sets a global flag to tell the secure memory subsystem
@@ -746,7 +688,7 @@ code should drop these extra privileges as soon as possible.  If this
 command has been used the caller is responsible for dropping the
 privileges.
 
-@item GCRYCTL_INIT_SECMEM; Arguments: int nbytes
+@item GCRYCTL_INIT_SECMEM; Arguments: unsigned int nbytes
 This command is used to allocate a pool of secure memory and thus
 enabling the use of secure memory.  It also drops all extra privileges
 the process has (i.e. if it is run as setuid (root)).  If the argument
@@ -754,6 +696,17 @@ the process has (i.e. if it is run as setuid (root)).  If the argument
 of secure memory allocated is currently 16384 bytes; you may thus use a
 value of 1 to request that default size.
 
+@item GCRYCTL_AUTO_EXPAND_SECMEM; Arguments: unsigned int chunksize
+This command enables on-the-fly expanding of the secure memory area.
+Note that by using functions like @code{gcry_xmalloc_secure} and
+@code{gcry_mpi_snew} will do this auto expanding anyway.  The argument
+to this option is the suggested size for new secure memory areas.  A
+larger size improves performance of all memory allocation and
+releasing functions.  The given chunksize is rounded up to the next
+32KiB.  The drawback of auto expanding is that memory might be swapped
+out to disk; this can be fixed by configuring the system to use an
+encrypted swap space.
+
 @item GCRYCTL_TERM_SECMEM; Arguments: none
 This command zeroises the secure memory and destroys the handler.  The
 secure memory pool may not be used anymore after running this command.
@@ -863,8 +816,7 @@ This command returns true if the command@*
 GCRYCTL_INITIALIZATION_FINISHED has already been run.
 
 @item GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops
-This command registers a thread-callback structure.
-@xref{Multi-Threading}.
+This command is obsolete since version 1.6.
 
 @item GCRYCTL_FAST_POLL; Arguments: none
 Run a fast random poll.
@@ -883,7 +835,8 @@ proper random device.
 This command dumps information pertaining to the configuration of the
 library to the given stream.  If NULL is given for @var{stream}, the log
 system is used.  This command may be used before the initialization has
-been finished but not before a @code{gcry_check_version}.
+been finished but not before a @code{gcry_check_version}.  Note that
+the macro @code{estream_t} can be used instead of @code{gpgrt_stream_t}.
 
 @item GCRYCTL_OPERATIONAL_P; Arguments: none
 This command returns true if the library is in an operational state.
@@ -951,7 +904,7 @@ The default is @code{GCRY_RNG_TYPE_STANDARD} unless FIPS mode as been
 enabled; in which case @code{GCRY_RNG_TYPE_FIPS} is used and locked
 against further changes.
 
-@item GCRYCTL_GETT_CURRENT_RNG_TYPE; Arguments: int *
+@item GCRYCTL_GET_CURRENT_RNG_TYPE; Arguments: int *
 This command stores the type of the currently used RNG as an integer
 value at the provided address.
 
@@ -966,10 +919,29 @@ success or an error code on failure.
 Libgcrypt detects certain features of the CPU at startup time.  For
 performance tests it is sometimes required not to use such a feature.
 This option may be used to disable 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}.
+behaves as if this feature has not been detected.  This call can be
+used several times to disable a set of features, or features may be
+given as a colon or comma delimited string.  The special feature
+"all" can be used to disable all available features.
+
+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}.
+
+@item GCRYCTL_REINIT_SYSCALL_CLAMP; Arguments: none
+
+Libgcrypt wraps blocking system calls with two functions calls
+(``system call clamp'') to give user land threading libraries a hook
+for re-scheduling.  This works by reading the system call clamp from
+Libgpg-error at initialization time.  However sometimes Libgcrypt
+needs to be initialized before the user land threading systems and at
+that point the system call clamp has not been registered with
+Libgpg-error and in turn Libgcrypt would not use them.  The control
+code can be used to tell Libgcrypt that a system call clamp has now
+been registered with Libgpg-error and advised it to read the clamp
+again.  Obviously this control code may only be used before a second
+thread is started in a process.
+
 
 @end table
 
@@ -1647,6 +1619,10 @@ This is the Salsa20/12 - reduced round version of Salsa20 stream cipher.
 The GOST 28147-89 cipher, defined in the respective GOST standard.
 Translation of this GOST into English is provided in the RFC-5830.
 
+@item GCRY_CIPHER_CHACHA20
+@cindex ChaCha20
+This is the ChaCha20 stream cipher.
+
 @end table
 
 @node Available cipher modes
@@ -1663,9 +1639,12 @@ set, this mode may be used to bypass the actual encryption.
 Electronic Codebook mode.
 
 @item GCRY_CIPHER_MODE_CFB
+@item GCRY_CIPHER_MODE_CFB8
 @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).
+Cipher Feedback mode.  For GCRY_CIPHER_MODE_CFB the shift size equals
+the block size of the cipher (e.g. for AES it is CFB-128).  For
+GCRY_CIPHER_MODE_CFB8 the shift size is 8 bit but that variant is not
+yet available.
 
 @item  GCRY_CIPHER_MODE_CBC
 @cindex CBC, Cipher Block Chaining mode
@@ -1708,6 +1687,47 @@ Galois/Counter Mode (GCM) is an Authenticated Encryption with
 Associated Data (AEAD) block cipher mode, which is specified in
 'NIST Special Publication 800-38D'.
 
+@item  GCRY_CIPHER_MODE_POLY1305
+@cindex Poly1305 based AEAD mode with ChaCha20
+This mode implements the Poly1305 Authenticated Encryption with Associated
+Data (AEAD) mode according to RFC-7539. This mode can be used with ChaCha20
+stream cipher.
+
+@item  GCRY_CIPHER_MODE_OCB
+@cindex OCB, OCB3
+OCB is an Authenticated Encryption with Associated Data (AEAD) block
+cipher mode, which is specified in RFC-7253.  Supported tag lengths
+are 128, 96, and 64 bit with the default being 128 bit.  To switch to
+a different tag length @code{gcry_cipher_ctl} using the command
+@code{GCRYCTL_SET_TAGLEN} and the address of an @code{int} variable
+set to 12 (for 96 bit) or 8 (for 64 bit) provided for the
+@code{buffer} argument and @code{sizeof(int)} for @code{buflen}.
+
+Note that the use of @code{gcry_cipher_final} is required.
+
+@item  GCRY_CIPHER_MODE_XTS
+@cindex XTS, XTS mode
+XEX-based tweaked-codebook mode with ciphertext stealing (XTS) mode
+is used to implement the AES-XTS as specified in IEEE 1619 Standard
+Architecture for Encrypted Shared Storage Media and NIST SP800-38E.
+
+The XTS mode requires doubling key-length, for example, using 512-bit
+key with AES-256 (@code{GCRY_CIPHER_AES256}). The 128-bit tweak value
+is feed to XTS mode as little-endian byte array using
+@code{gcry_cipher_setiv} function. When encrypting or decrypting,
+full-sized data unit buffers needs to be passed to
+@code{gcry_cipher_encrypt} or @code{gcry_cipher_decrypt}. The tweak
+value is automatically incremented after each call of
+@code{gcry_cipher_encrypt} and @code{gcry_cipher_decrypt}.
+Auto-increment allows avoiding need of setting IV between processing
+of sequential data units.
+
+@item  GCRY_CIPHER_MODE_EAX
+@cindex EAX, EAX mode
+EAX is an Authenticated Encryption with Associated Data (AEAD) block cipher
+mode by Bellare, Rogaway, and Wagner (see
+@uref{http://web.cs.ucdavis.edu/~rogaway/papers/eax.html}).
+
 @end table
 
 @node Working with cipher handles
@@ -1723,7 +1743,7 @@ other cipher functions and returns a handle to it in `hd'.  In case of
 an error, an according error code is returned.
 
 The ID of algorithm to use must be specified via @var{algo}.  See
-@xref{Available ciphers}, for a list of supported ciphers and the
+@ref{Available ciphers}, for a list of supported ciphers and the
 according constants.
 
 Besides using the constants directly, the function
@@ -1731,16 +1751,20 @@ Besides using the constants directly, the function
 an algorithm into the according numeric ID.
 
 The cipher mode to use must be specified via @var{mode}.  See
-@xref{Available cipher modes}, for a list of supported cipher modes
+@ref{Available cipher modes}, for a list of supported cipher modes
 and the according constants.  Note that some modes are incompatible
 with some algorithms - in particular, stream mode
-(@code{GCRY_CIPHER_MODE_STREAM}) only works with stream ciphers. The
-block cipher modes (@code{GCRY_CIPHER_MODE_ECB},
-@code{GCRY_CIPHER_MODE_CBC}, @code{GCRY_CIPHER_MODE_CFB},
-@code{GCRY_CIPHER_MODE_OFB} and @code{GCRY_CIPHER_MODE_CTR}) will work
-with any block cipher algorithm. @code{GCRY_CIPHER_MODE_CCM} and
-@code{GCRY_CIPHER_MODE_GCM} modes will only work with block cipher algorithms
-which have the block size of 16 bytes.
+(@code{GCRY_CIPHER_MODE_STREAM}) only works with stream ciphers.
+Poly1305 AEAD mode (@code{GCRY_CIPHER_MODE_POLY1305}) only works with
+ChaCha20 stream cipher. The block cipher modes
+(@code{GCRY_CIPHER_MODE_ECB}, @code{GCRY_CIPHER_MODE_CBC},
+@code{GCRY_CIPHER_MODE_CFB}, @code{GCRY_CIPHER_MODE_OFB},
+@code{GCRY_CIPHER_MODE_CTR} and @code{GCRY_CIPHER_MODE_EAX}) will work
+with any block cipher algorithm.  GCM mode
+(@code{GCRY_CIPHER_MODE_CCM}), CCM mode (@code{GCRY_CIPHER_MODE_GCM}),
+OCB mode (@code{GCRY_CIPHER_MODE_OCB}), and XTS mode
+(@code{GCRY_CIPHER_MODE_XTS}) will only work with block cipher
+algorithms which have the block size of 16 bytes.
 
 The third argument @var{flags} can either be passed as @code{0} or as
 the bit-wise OR of the following constants.
@@ -1803,12 +1827,9 @@ 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.
 
-This function is also used with the Salsa20 stream cipher to set or
-update the required nonce.  In this case it needs to be called after
-setting the key.
-
-This function is also used with the AEAD cipher modes to set or
-update the required nonce.
+This function is also used by AEAD modes and with Salsa20 and ChaCha20
+stream ciphers to set or update the required nonce.  In these cases it
+needs to be called after setting the key.
 
 @end deftypefun
 
@@ -1841,15 +1862,23 @@ authenticated data (AAD) for AEAD cipher modes.
 
 @end deftypefun
 
-@deftypefun gcry_error_t gcry_cipher_gettag (gcry_cipher_hd_t @var{h}, void *@var{tag}, size_t @var{taglen})
+@deftypefun {gcry_error_t} gcry_cipher_gettag @
+            (@w{gcry_cipher_hd_t @var{h}}, @
+            @w{void *@var{tag}}, @w{size_t @var{taglen}})
 
 This function is used to read the authentication tag after encryption.
 The function finalizes and outputs the authentication tag to the buffer
 @var{tag} of length @var{taglen} bytes.
 
+Depending on the used mode certain restrictions for @var{taglen} are
+enforced:  For GCM @var{taglen} must be at least 16 or one of the
+allowed truncated lengths (4, 8, 12, 13, 14, or 15).
+
 @end deftypefun
 
-@deftypefun gcry_error_t gcry_cipher_checktag (gcry_cipher_hd_t @var{h}, const void *@var{tag}, size_t @var{taglen})
+@deftypefun {gcry_error_t} gcry_cipher_checktag @
+            (@w{gcry_cipher_hd_t @var{h}}, @
+            @w{const void *@var{tag}}, @w{size_t @var{taglen}})
 
 Check the authentication tag after decryption. The authentication
 tag is passed as the buffer @var{tag} of length @var{taglen} bytes
@@ -1858,6 +1887,10 @@ decryption.  Error code @code{GPG_ERR_CHECKSUM} is returned if
 the authentication tag in the buffer @var{tag} does not match
 the authentication tag calculated during decryption.
 
+Depending on the used mode certain restrictions for @var{taglen} are
+enforced: For GCM @var{taglen} must either be 16 or one of the allowed
+truncated lengths (4, 8, 12, 13, 14, or 15).
+
 @end deftypefun
 
 The actual encryption and decryption is done by using one of the
@@ -1870,7 +1903,7 @@ all the data.
 can either work in place or with two buffers.  It uses the cipher
 context already setup and described by the handle @var{h}.  There are 2
 ways to use the function: If @var{in} is passed as @code{NULL} and
-@var{inlen} is @code{0}, in-place encryption of the data in @var{out} or
+@var{inlen} is @code{0}, in-place encryption of the data in @var{out} of
 length @var{outsize} takes place.  With @var{in} being not @code{NULL},
 @var{inlen} bytes are encrypted to the buffer @var{out} which must have
 at least a size of @var{inlen}.  @var{outsize} must be set to the
@@ -1880,6 +1913,9 @@ is sufficient space. Note that overlapping buffers are not allowed.
 Depending on the selected algorithms and encryption mode, the length of
 the buffers must be a multiple of the block size.
 
+Some encryption modes require that @code{gcry_cipher_final} is used
+before the final data chunk is passed to this function.
+
 The function returns @code{0} on success or an error code.
 @end deftypefun
 
@@ -1900,11 +1936,27 @@ is sufficient space.  Note that overlapping buffers are not allowed.
 Depending on the selected algorithms and encryption mode, the length of
 the buffers must be a multiple of the block size.
 
+Some encryption modes require that @code{gcry_cipher_final} is used
+before the final data chunk is passed to this function.
+
 The function returns @code{0} on success or an error code.
 @end deftypefun
 
 
-OpenPGP (as defined in RFC-2440) requires a special sync operation in
+The OCB mode features integrated padding and must thus be told about
+the end of the input data. This is done with:
+
+@deftypefun gcry_error_t gcry_cipher_final (gcry_cipher_hd_t @var{h})
+
+Set a flag in the context to tell the encrypt and decrypt functions
+that their next call will provide the last chunk of data.  Only the
+first call to this function has an effect and only for modes which
+support it.  Checking the error is in general not necessary.  This is
+implemented as a macro.
+@end deftypefun
+
+
+OpenPGP (as defined in RFC-4880) requires a special sync operation in
 some places.  The following function is used for this:
 
 @deftypefun gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})
@@ -1928,12 +1980,24 @@ handle @var{h}.  Please see the comments in the source code
 (@code{src/global.c}) for details.
 @end deftypefun
 
-@deftypefun gcry_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
+@deftypefun gcry_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, @
+              int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
 
 @code{gcry_cipher_info} is used to retrieve various
 information about a cipher context or the cipher module in general.
 
-Currently no information is available.
+@c begin constants for gcry_cipher_info
+@table @code
+
+@item GCRYCTL_GET_TAGLEN:
+Return the length of the tag for an AE algorithm mode.  An error is
+returned for modes which do not support a tag.  @var{buffer} must be
+given as NULL.  On success the result is stored @var{nbytes}.  The
+taglen is returned in bytes.
+
+@end table
+@c end constants for gcry_cipher_info
+
 @end deftypefun
 
 @node General cipher functions
@@ -2235,7 +2299,9 @@ The private key @math{d}
 All point values are encoded in standard format; Libgcrypt does in
 general only support uncompressed points, thus the first byte needs to
 be @code{0x04}.  However ``EdDSA'' describes its own compression
-scheme which is used by default.
+scheme which is used by default; the non-standard first byte
+@code{0x40} may optionally be used to explicit flag the use of the
+algorithm’s native compression method.
 
 The public key is similar with "private-key" replaced by "public-key"
 and no @var{d-mpi}.
@@ -2305,9 +2371,11 @@ are known:
 If supported by the algorithm and curve the @code{comp} flag requests
 that points are returned in compact (compressed) representation.  The
 @code{nocomp} flag requests that points are returned with full
-coordinates.  The default depends on the the algorithm and curve.
-The compact representation requires a small overhead before a point
-can be used but halves the size of a to be conveyed public key.
+coordinates.  The default depends on the the algorithm and curve.  The
+compact representation requires a small overhead before a point can be
+used but halves the size of a to be conveyed public key.  If
+@code{comp} is used with the ``EdDSA'' algorithm the key generation
+prefix the public key with a @code{0x40} byte.
 
 @item pkcs1
 @cindex PKCS1
@@ -2352,6 +2420,13 @@ 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 no-keytest
+@cindex no-keytest
+This flag skips internal failsafe tests to assert that a generated key
+is properly working.  It currently has an effect only for standard ECC
+key generation.  It is mostly useful along with transient-key to
+achieve fastest ECC key generation.
+
 @item use-x931
 @cindex X9.31
 Force the use of the ANSI X9.31 key generation algorithm instead of
@@ -2762,7 +2837,7 @@ operations.  @var{cmd} controls what is to be done. The return value is
 Disable the algorithm given as an algorithm id in @var{buffer}.
 @var{buffer} must point to an @code{int} variable with the algorithm
 id and @var{buflen} must have the value @code{sizeof (int)}.  This
-fucntion is not thread safe and should thus be used before any other
+function is not thread safe and should thus be used before any other
 threads are started.
 
 @end table
@@ -2798,9 +2873,11 @@ supported parameters are:
 
 @table @code
 @item nbits
-This is always required to specify the length of the key.  The argument
-is a string with a number in C-notation.  The value should be a multiple
-of 8.
+This is always required to specify the length of the key.  The
+argument is a string with a number in C-notation.  The value should be
+a multiple of 8.  Note that the S-expression syntax requires that a
+number is prefixed with its string length; thus the @code{4:} in the
+above example.
 
 @item curve @var{name}
 For ECC a named curve may be used instead of giving the number of
@@ -2828,7 +2905,9 @@ Use the given value.
 
 @noindent
 If this parameter is not used, Libgcrypt uses for historic reasons
-65537.
+65537.  Note that the value must fit into a 32 bit unsigned variable
+and that the usual C prefixes are considered (e.g. 017 gives 15).
+
 
 @item qbits @var{n}
 This is only meanigful for DSA keys.  If it is given the DSA key is
@@ -3052,11 +3131,14 @@ are also supported.
 @c begin table of hash algorithms
 @cindex SHA-1
 @cindex SHA-224, SHA-256, SHA-384, SHA-512
+@cindex SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256
 @cindex RIPE-MD-160
 @cindex MD2, MD4, MD5
 @cindex TIGER, TIGER1, TIGER2
 @cindex HAVAL
 @cindex Whirlpool
+@cindex BLAKE2b-512, BLAKE2b-384, BLAKE2b-256, BLAKE2b-160
+@cindex BLAKE2s-256, BLAKE2s-224, BLAKE2s-160, BLAKE2s-128
 @cindex CRC32
 @table @code
 @item GCRY_MD_NONE
@@ -3124,6 +3206,32 @@ See FIPS 180-2 for the specification.
 This is the SHA-384 algorithm which yields a message digest of 64 bytes.
 See FIPS 180-2 for the specification.
 
+@item GCRY_MD_SHA3_224
+This is the SHA3-224 algorithm which yields a message digest of 28 bytes.
+See FIPS 202 for the specification.
+
+@item GCRY_MD_SHA3_256
+This is the SHA3-256 algorithm which yields a message digest of 32 bytes.
+See FIPS 202 for the specification.
+
+@item GCRY_MD_SHA3_384
+This is the SHA3-384 algorithm which yields a message digest of 48 bytes.
+See FIPS 202 for the specification.
+
+@item GCRY_MD_SHA3_512
+This is the SHA3-384 algorithm which yields a message digest of 64 bytes.
+See FIPS 202 for the specification.
+
+@item GCRY_MD_SHAKE128
+This is the SHAKE128 extendable-output function (XOF) algorithm with 128 bit
+security strength.
+See FIPS 202 for the specification.
+
+@item GCRY_MD_SHAKE256
+This is the SHAKE256 extendable-output function (XOF) algorithm with 256 bit
+security strength.
+See FIPS 202 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.  Note that this is not a hash algorithm in the
@@ -3155,6 +3263,38 @@ which yields a message digest of 32 bytes.
 This is the 512-bit version of hash algorithm described in GOST R 34.11-2012
 which yields a message digest of 64 bytes.
 
+@item GCRY_MD_BLAKE2B_512
+This is the BLAKE2b-512 algorithm which yields a message digest of 64 bytes.
+See RFC 7693 for the specification.
+
+@item GCRY_MD_BLAKE2B_384
+This is the BLAKE2b-384 algorithm which yields a message digest of 48 bytes.
+See RFC 7693 for the specification.
+
+@item GCRY_MD_BLAKE2B_256
+This is the BLAKE2b-256 algorithm which yields a message digest of 32 bytes.
+See RFC 7693 for the specification.
+
+@item GCRY_MD_BLAKE2B_160
+This is the BLAKE2b-160 algorithm which yields a message digest of 20 bytes.
+See RFC 7693 for the specification.
+
+@item GCRY_MD_BLAKE2S_256
+This is the BLAKE2s-256 algorithm which yields a message digest of 32 bytes.
+See RFC 7693 for the specification.
+
+@item GCRY_MD_BLAKE2S_224
+This is the BLAKE2s-224 algorithm which yields a message digest of 28 bytes.
+See RFC 7693 for the specification.
+
+@item GCRY_MD_BLAKE2S_160
+This is the BLAKE2s-160 algorithm which yields a message digest of 20 bytes.
+See RFC 7693 for the specification.
+
+@item GCRY_MD_BLAKE2S_128
+This is the BLAKE2s-128 algorithm which yields a message digest of 16 bytes.
+See RFC 7693 for the specification.
+
 @end table
 @c end table of hash algorithms
 
@@ -3172,7 +3312,7 @@ may be given as @code{0} if the algorithms to use are later set using
 @code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid
 handle or NULL.
 
-For a list of supported algorithms, see @xref{Available hash
+For a list of supported algorithms, see @ref{Available hash
 algorithms}.
 
 The flags allowed for @var{mode} are:
@@ -3186,11 +3326,28 @@ 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.
-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}.
+only works if just one algorithm is enabled for the handle and that
+algorithm is not an extendable-output function.  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 @ref{Working with cipher handles}.
+
+@item GCRY_MD_FLAG_BUGEMU1
+@cindex bug emulation
+Versions of Libgcrypt before 1.6.0 had a bug in the Whirlpool code
+which led to a wrong result for certain input sizes and write
+patterns.  Using this flag emulates that bug.  This may for example be
+useful for applications which use Whirlpool as part of their key
+generation.  It is strongly suggested to use this flag only if really
+needed and if possible to the data should be re-processed using the
+regular Whirlpool algorithm.
+
+Note that this flag works for the entire hash context.  If needed
+arises it may be used to enable bug emulation for other hash
+algorithms.  Thus you should not use this flag for a multi-algorithm
+hash context.
+
 
 @end table
 @c begin table of hash flags
@@ -3216,9 +3373,12 @@ 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} bytes.  There is no restriction on
-the length of the key.
+For use with the HMAC feature or BLAKE2 keyed hash, set the MAC key to
+the value of @var{key} of length @var{keylen} bytes.  For HMAC, there
+is no restriction on the length of the key.  For keyed BLAKE2b hash,
+length of the key must be 64 bytes or less.  For keyed BLAKE2s hash,
+length of the key must be 32 bytes or less.
+
 @end deftypefun
 
 
@@ -3271,7 +3431,11 @@ by just one character.  Both methods can be used on the same hash context.
 
 Pass @var{length} bytes of the data in @var{buffer} to the digest object
 with handle @var{h} to update the digest values. This
-function should be used for large blocks of data.
+function should be used for large blocks of data.  If this function is
+used after the context has been finalized, it will keep on pushing
+the data through the algorithm specific transform function and change
+the context; however the results are not meaningful and this feature
+is only available to mitigate timing attacks.
 @end deftypefun
 
 @deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c})
@@ -3289,9 +3453,11 @@ message digest or some padding.
 @deftypefun void gcry_md_final (gcry_md_hd_t @var{h})
 
 Finalize the message digest calculation.  This is not really needed
-because @code{gcry_md_read} does this implicitly.  After this has been
-done no further updates (by means of @code{gcry_md_write} or
-@code{gcry_md_putc} are allowed.  Only the first call to this function
+because @code{gcry_md_read} and @code{gcry_md_extract} do this implicitly.
+After this has been done no further updates (by means of @code{gcry_md_write}
+or @code{gcry_md_putc} should be done; However, to mitigate timing
+attacks it is sometimes useful to keep on updating the context after
+having stored away the actual digest.  Only the first call to this function
 has an effect. It is implemented as a macro.
 @end deftypefun
 
@@ -3304,13 +3470,30 @@ function:
 calculation.  This function may be used as often as required but it will
 always return the same value for one handle.  The returned message digest
 is allocated within the message context and therefore valid until the
-handle is released or reseted (using @code{gcry_md_close} or
-@code{gcry_md_reset}.  @var{algo} may be given as 0 to return the only
+handle is released or reset-ed (using @code{gcry_md_close} or
+@code{gcry_md_reset} or it has been updated as a mitigation measure
+against timing attacks.  @var{algo} may be given as 0 to return the only
 enabled message digest or it may specify one of the enabled algorithms.
 The function does return @code{NULL} if the requested algorithm has not
 been enabled.
 @end deftypefun
 
+The way to read output of extendable-output function is by using the
+function:
+
+@deftypefun gpg_err_code_t gcry_md_extract (gcry_md_hd_t @var{h}, @
+  int @var{algo}, void *@var{buffer}, size_t @var{length})
+
+@code{gcry_mac_read} returns output from extendable-output function.
+This function may be used as often as required to generate more output
+byte stream from the algorithm.  Function extracts the new output bytes
+to @var{buffer} of the length @var{length}.  Buffer will be fully
+populated with new output.  @var{algo} may be given as 0 to return the only
+enabled message digest or it may specify one of the enabled algorithms.
+The function does return non-zero value if the requested algorithm has not
+been enabled.
+@end deftypefun
+
 Because it is often necessary to get the message digest of blocks of
 memory, two fast convenience function are available for this task:
 
@@ -3321,7 +3504,7 @@ memory, two fast convenience function are available for this task:
 
 @code{gcry_md_hash_buffers} is a shortcut function to calculate a
 message digest from several buffers.  This function does not require a
-context and immediately returns the message digest of of the data
+context and immediately returns the message digest of the data
 described by @var{iov} and @var{iovcnt}.  @var{digest} must be
 allocated by the caller, large enough to hold the message digest
 yielded by the the specified algorithm @var{algo}.  This required size
@@ -3452,7 +3635,7 @@ hashed can be written to files on request.
 @deftypefun void gcry_md_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
 
 Enable debugging for the digest object with handle @var{h}.  This
-creates create files named @file{dbgmd-<n>.<string>} while doing the
+creates files named @file{dbgmd-<n>.<string>} while doing the
 actual hashing.  @var{suffix} is the string part in the filename.  The
 number is a counter incremented for each new hashing.  The data in the
 file is the raw data as passed to @code{gcry_md_write} or
@@ -3486,6 +3669,7 @@ provided by Libgcrypt.
 @c begin table of MAC algorithms
 @cindex HMAC-SHA-1
 @cindex HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, HMAC-SHA-512
+@cindex HMAC-SHA3-224, HMAC-SHA3-256, HMAC-SHA3-384, HMAC-SHA3-512
 @cindex HMAC-RIPE-MD-160
 @cindex HMAC-MD2, HMAC-MD4, HMAC-MD5
 @cindex HMAC-TIGER1
@@ -3513,6 +3697,22 @@ algorithm.
 This is HMAC message authentication algorithm based on the SHA-384 hash
 algorithm.
 
+@item GCRY_MAC_HMAC_SHA3_256
+This is HMAC message authentication algorithm based on the SHA3-384 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_SHA3_224
+This is HMAC message authentication algorithm based on the SHA3-224 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_SHA3_512
+This is HMAC message authentication algorithm based on the SHA3-512 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_SHA3_384
+This is HMAC message authentication algorithm based on the SHA3-384 hash
+algorithm.
+
 @item GCRY_MAC_HMAC_SHA1
 This is HMAC message authentication algorithm based on the SHA-1 hash
 algorithm.
@@ -3609,6 +3809,30 @@ block cipher algorithm.
 This is GMAC message authentication algorithm based on the SEED
 block cipher algorithm.
 
+@item GCRY_MAC_POLY1305
+This is plain Poly1305 message authentication algorithm, used with
+one-time key.
+
+@item GCRY_MAC_POLY1305_AES
+This is Poly1305-AES message authentication algorithm, used with
+key and one-time nonce.
+
+@item GCRY_MAC_POLY1305_CAMELLIA
+This is Poly1305-Camellia message authentication algorithm, used with
+key and one-time nonce.
+
+@item GCRY_MAC_POLY1305_TWOFISH
+This is Poly1305-Twofish message authentication algorithm, used with
+key and one-time nonce.
+
+@item GCRY_MAC_POLY1305_SERPENT
+This is Poly1305-Serpent message authentication algorithm, used with
+key and one-time nonce.
+
+@item GCRY_MAC_POLY1305_SEED
+This is Poly1305-SEED message authentication algorithm, used with
+key and one-time nonce.
+
 @end table
 @c end table of MAC algorithms
 
@@ -3625,7 +3849,7 @@ bitwise OR of constants described below. @var{hd} is guaranteed to either
 receive a valid handle or NULL. @var{ctx} is context object to associate MAC
 object with. @var{ctx} maybe set to NULL.
 
-For a list of supported algorithms, see @xref{Available MAC algorithms}.
+For a list of supported algorithms, see @ref{Available MAC algorithms}.
 
 The flags allowed for @var{mode} are:
 
@@ -3654,8 +3878,8 @@ underlying block cipher.
 @end deftypefun
 
 
-GMAC algorithms need initialization vector to be set, which can be
-performed with function:
+GMAC algorithms and Poly1305-with-cipher algorithms need initialization vector to be set,
+which can be performed with function:
 
 @deftypefun gcry_error_t gcry_mac_setiv (gcry_mac_hd_t @var{h}, const void *@var{iv}, size_t @var{ivlen})
 
@@ -3694,10 +3918,13 @@ see how it is actually done.
 @deftypefun gcry_error_t gcry_mac_write (gcry_mac_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
 
 Pass @var{length} bytes of the data in @var{buffer} to the MAC object
-with handle @var{h} to update the MAC values.
+with handle @var{h} to update the MAC values.  If this function is
+used after the context has been finalized, it will keep on pushing the
+data through the algorithm specific transform function and thereby
+change the context; however the results are not meaningful and this
+feature is only available to mitigate timing attacks.
 @end deftypefun
 
-
 The way to read out the calculated MAC is by using the function:
 
 @deftypefun gcry_error_t gcry_mac_read (gcry_mac_hd_t @var{h}, void *@var{buffer}, size_t *@var{length})
@@ -3708,7 +3935,6 @@ Function copies the resulting MAC value to @var{buffer} of the length
 then length of MAC is returned through @var{length}.
 @end deftypefun
 
-
 To compare existing MAC value with recalculated MAC, one is to use the function:
 
 @deftypefun gcry_error_t gcry_mac_verify (gcry_mac_hd_t @var{h}, void *@var{buffer}, size_t @var{length})
@@ -3720,6 +3946,16 @@ the MAC calculated in object @var{h}.
 @end deftypefun
 
 
+In some situations it might be hard to remember the algorithm used for
+the MAC calculation. The following function might be used to get that
+information:
+
+@deftypefun {int} gcry_mac_get_algo (gcry_mac_hd_t @var{h})
+
+Retrieve the algorithm used with the handle @var{h}.
+@end deftypefun
+
+
 @c ***********************************
 @c ***** MAC info functions **********
 @c ***********************************
@@ -3765,7 +4001,7 @@ for the MAC value. On error @code{0} is returned.
 @end deftypefun
 
 
-@deftypefun unsigned int gcry_mac_get_algo_keylen (@var{algo})
+@deftypefun {unsigned int} gcry_mac_get_algo_keylen (@var{algo})
 
 This function returns length of the key for MAC algorithm @var{algo}.  If
 the algorithm supports multiple key lengths, the default supported key
@@ -4075,7 +4311,7 @@ logging stream.
 @noindent
 Often canonical encoding is used in the external representation.  The
 following function can be used to check for valid encoding and to learn
-the length of the S-expression"
+the length of the S-expression.
 
 @deftypefun size_t gcry_sexp_canon_len (@w{const unsigned char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{erroff}}, @w{int *@var{errcode}})
 
@@ -4119,8 +4355,9 @@ no such element, @code{NULL} is returned.
 @deftypefun gcry_sexp_t gcry_sexp_car (@w{const gcry_sexp_t @var{list}})
 
 Create and return a new S-expression from the first element in
-@var{list}; this called the "type" and should always exist and be a
-string. @code{NULL} is returned in case of a problem.
+@var{list}; this is called the "type" and should always exist per
+S-expression specification and in general be a string.  @code{NULL} is
+returned in case of a problem.
 @end deftypefun
 
 @deftypefun gcry_sexp_t gcry_sexp_cdr (@w{const gcry_sexp_t @var{list}})
@@ -4230,8 +4467,10 @@ In general parameter names are single letters.  To use a string for a
 parameter name, enclose the name in single quotes.
 
 Unless in buffer descriptor mode for each parameter name a pointer to
-an @code{gcry_mpi_t} variable is expected finally followed by a @code{NULL}.
-For example
+an @code{gcry_mpi_t} variable is expected that must be set to
+@code{NULL} prior to invoking this function, and finally a @code{NULL}
+is expected.  For example
+
 @example
   _gcry_sexp_extract_param (key, NULL, "n/x+e d-'foo'",
                             &mpi_n, &mpi_x, &mpi_e, &mpi_foo, NULL)
@@ -4260,8 +4499,11 @@ number of bytes copied to that buffer; in case the buffer is too
 small, the function immediately returns with an error code (and
 @var{len} is set to 0).
 
-The function returns NULL on success.  On error an error code is
-returned and the passed MPIs are either unchanged or set to NULL.
+The function returns 0 on success.  On error an error code is
+returned, all passed MPIs that might have been allocated up to this
+point are deallocated and set to @code{NULL}, and all passed buffers
+are either truncated if the caller supplied the buffer, or deallocated
+if the function allocated the buffer.
 @end deftypefun
 
 
@@ -4356,6 +4598,18 @@ int} as type for @var{u} and thus it is only possible to set @var{w} to
 small values (usually up to the word size of the CPU).
 @end deftypefun
 
+@deftypefun gcry_error_t gcry_mpi_get_ui (@w{unsigned int *@var{w}}, @w{gcry_mpi_t @var{u}})
+
+If @var{u} is not negative and small enough to be stored in an
+@code{unsigned int} variable, store its value at @var{w}.  If the
+value does not fit or is negative return GPG_ERR_ERANGE and do not
+change the value stored at @var{w}.  Note that this function returns
+an @code{unsigned int} so that this value can immediately be used with
+the bit test functions.  This is in contrast to the other "_ui"
+functions which allow for values up to an @code{unsigned long}.
+@end deftypefun
+
+
 @deftypefun void gcry_mpi_swap (@w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
 
 Swap the values of @var{a} and @var{b}.
@@ -4391,7 +4645,8 @@ representation of an MPI and the internal one of Libgcrypt.
 Convert the external representation of an integer stored in @var{buffer}
 with a length of @var{buflen} into a newly created MPI returned which
 will be stored at the address of @var{r_mpi}.  For certain formats the
-length argument is not required and should be passed as @code{0}.  After a
+length argument is not required and should be passed as @code{0}. A
+@var{buflen} larger than 16 MiByte will be rejected.  After a
 successful operation the variable @var{nscanned} receives the number of
 bytes actually scanned unless @var{nscanned} was given as
 @code{NULL}. @var{format} describes the format of the MPI as stored in
@@ -4405,6 +4660,7 @@ bytes actually scanned unless @var{nscanned} was given as
 @item GCRYMPI_FMT_PGP
 As used by OpenPGP (only defined as unsigned). This is basically
 @code{GCRYMPI_FMT_STD} with a 2 byte big endian length header.
+A length header indicating a length of more than 16384 is not allowed.
 
 @item GCRYMPI_FMT_SSH
 As used in the Secure Shell protocol.  This is @code{GCRYMPI_FMT_STD}
@@ -4523,7 +4779,9 @@ Basic arithmetic operations:
 
 @math{@var{q} = @var{dividend} / @var{divisor}}, @math{@var{r} =
 @var{dividend} \bmod @var{divisor}}.  @var{q} and @var{r} may be passed
-as @code{NULL}.  @var{round} should be negative or 0.
+as @code{NULL}.  @var{round} is either negative for floored division
+(rounds towards the next lower integer) or zero for truncated division
+(rounds towards zero).
 @end deftypefun
 
 @deftypefun void gcry_mpi_mod (@w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}})
@@ -4652,6 +4910,13 @@ Release @var{point} and free all associated resources.  Passing
 @code{NULL} is allowed and ignored.
 @end deftypefun
 
+@deftypefun gcry_mpi_point_t gcry_mpi_point_copy (@w{gcry_mpi_point_t @var{point}})
+
+Allocate and return a new point object and initialize it with
+@var{point}.  If @var{point} is NULL the function is identical to
+@code{gcry_mpi_point_new(0)}.
+@end deftypefun
+
 @deftypefun void gcry_mpi_point_get (@w{gcry_mpi_t @var{x}}, @
  @w{gcry_mpi_t @var{y}}, @w{gcry_mpi_t @var{z}}, @
  @w{gcry_mpi_point_t @var{point}})
@@ -4699,7 +4964,7 @@ newly allocated point object.
 @end deftypefun
 
 @anchor{gcry_mpi_ec_new}
-@deftypefun gpg_error_t gcry_mpi_ec_p_new (@w{gpg_ctx_t *@var{r_ctx}}, @
+@deftypefun gpg_error_t gcry_mpi_ec_new (@w{gcry_ctx_t *@var{r_ctx}}, @
  @w{gcry_sexp_t @var{keyparam}}, @w{const char *@var{curvename}})
 
 Allocate a new context for elliptic curve operations.  If
@@ -4776,6 +5041,19 @@ Valid names are the point parameters of an elliptic curve
 (@pxref{ecc_keyparam}).
 @end deftypefun
 
+@deftypefun gpg_err_code_t gcry_mpi_ec_decode_point ( @
+ @w{mpi_point_t @var{result}}, @w{gcry_mpi_t @var{value}}, @
+ @w{gcry_ctx_t @var{ctx}})
+
+Decode the point given as an MPI in @var{value} and store at
+@var{result}.  To decide which encoding is used the function takes a
+context @var{ctx} which can be created with @code{gcry_mpi_ec_new}.
+If @code{NULL} is given for the context the function assumes a 0x04
+prefixed uncompressed encoding.  On error an error code is returned
+and @var{result} might be changed.
+@end deftypefun
+
+
 @deftypefun int gcry_mpi_ec_get_affine ( @
  @w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{y}}, @
  @w{gcry_mpi_point_t @var{point}}, @w{gcry_ctx_t @var{ctx}})
@@ -4809,6 +5087,15 @@ Add the points @var{u} and @var{v} of the elliptic curve described by
 @var{ctx} and store the result into @var{w}.
 @end deftypefun
 
+@deftypefun void gcry_mpi_ec_sub ( @
+ @w{gcry_mpi_point_t @var{w}}, @w{gcry_mpi_point_t @var{u}}, @
+ @w{gcry_mpi_point_t @var{v}}, @w{gcry_ctx_t @var{ctx}})
+
+Subtracts the point @var{v} from the point @var{u} of the elliptic
+curve described by @var{ctx} and store the result into @var{w}. Only
+Twisted Edwards curves are supported for now.
+@end deftypefun
+
 @deftypefun void gcry_mpi_ec_mul ( @
  @w{gcry_mpi_point_t @var{w}}, @w{gcry_mpi_t @var{n}}, @
  @w{gcry_mpi_point_t @var{u}}, @w{gcry_ctx_t @var{ctx}})
@@ -4869,7 +5156,7 @@ currently defined flags are:
 Setting this flag converts @var{a} into an MPI stored in "secure
 memory".  Clearing this flag is not allowed.
 @item GCRYMPI_FLAG_OPAQUE
-This is an interanl flag, indicating the an opaque valuue and not an
+This is an internal flag, indicating the an opaque valuue and not an
 integer is stored.  This is an read-only flag; it may not be set or
 cleared.
 @item GCRYMPI_FLAG_IMMUTABLE
@@ -4922,7 +5209,7 @@ may be used:
 
 @deftypefun void gcry_mpi_randomize (@w{gcry_mpi_t @var{w}}, @w{unsigned int @var{nbits}}, @w{enum gcry_random_level @var{level}})
 
-Set the multi-precision-integers @var{w} to a random value of
+Set the multi-precision-integers @var{w} to a random non-negative number of
 @var{nbits}, using random data quality of level @var{level}.  In case
 @var{nbits} is not a multiple of a byte, @var{nbits} is rounded up to
 the next byte boundary.  When using a @var{level} of
@@ -4988,6 +5275,7 @@ wrong.
 * Memory allocation::   Functions related with memory allocation.
 * Context management::  Functions related with context management.
 * Buffer description::  A data type to describe buffers.
+* Config reporting::    How to return Libgcrypt's configuration.
 @end menu
 
 
@@ -5072,6 +5360,27 @@ of this structure are:
   @end table
 @end deftp
 
+@node Config reporting
+@section How to return Libgcrypt's configuration.
+
+Although @code{GCRYCTL_PRINT_CONFIG} can be used to print
+configuration options, it is sometimes necessary to check them in a
+program.  This can be accomplished by using this function:
+
+@deftypefun {char *} gcry_get_config @
+             (@w{int @var{mode}}, @
+             @w{const char *@var{what}})
+
+This function returns a malloced string with colon delimited configure
+options.  With a value of 0 for @var{mode} this string resembles the
+output of @code{GCRYCTL_PRINT_CONFIG}.  However, if @var{what} is not
+NULL, only the line where the first field (e.g. "cpu-arch") matches
+@var{what} is returned.
+
+Other values than 0 for @var{mode} are not defined.  The caller shall
+free the string using @code{gcry_free}.  On error NULL is returned and
+ERRNO is set; if a value for WHAT is unknow ERRNO will be set to 0.
+@end deftypefun
 
 
 @c **********************************************************
@@ -5144,6 +5453,111 @@ Print version of the program and exit.
 @manpause
 
 @c **********************************************************
+@c ****************  Environment Variables  *****************
+@c **********************************************************
+@node Configuration
+@chapter Configuration files and environment variables
+
+This chapter describes which files and environment variables can be
+used to change the behaviour of Libgcrypt.
+
+@noindent
+The environment variables considered by Libgcrypt are:
+
+@table @code
+
+@item GCRYPT_BARRETT
+@cindex GCRYPT_BARRETT
+By setting this variable to any value a different algorithm for
+modular reduction is used for ECC.
+
+@item GCRYPT_RNDUNIX_DBG
+@item GCRYPT_RNDUNIX_DBGALL
+@cindex GCRYPT_RNDUNIX_DBG
+@cindex GCRYPT_RNDUNIX_DBGALL
+These two environment variables are used to enable debug output for
+the rndunix entropy gatherer, which is used on systems lacking a
+/dev/random device.  The value of @code{GCRYPT_RNDUNIX_DBG} is a file
+name or @code{-} for stdout.  Debug output is the written to this
+file.  By setting @code{GCRYPT_RNDUNIX_DBGALL} to any value the debug
+output will be more verbose.
+
+@item GCRYPT_RNDW32_NOPERF
+@cindex GCRYPT_RNDW32_NOPERF
+Setting this environment variable on Windows to any value disables
+the use of performance data (@code{HKEY_PERFORMANCE_DATA}) as source
+for entropy.  On some older Windows systems this could help to speed
+up the creation of random numbers but also decreases the amount of
+data used to init the random number generator.
+
+@item GCRYPT_RNDW32_DBG
+@cindex GCRYPT_RNDW32_DBG
+Setting the value of this variable to a positive integer logs
+information about the Windows entropy gatherer using the standard log
+interface.
+
+
+@item HOME
+@cindex HOME
+This is used to locate the socket to connect to the EGD random
+daemon.  The EGD can be used on system without a /dev/random to speed
+up the random number generator.  It is not needed on the majority of
+today's operating systems and support for EGD requires the use of a
+configure option at build time.
+
+@end table
+
+@noindent
+The files which Libgcrypt uses to retrieve system information and the
+files which can be created by the user to modify Libgcrypt's behavior
+are:
+
+@table @file
+
+@item /etc/gcrypt/hwf.deny
+@cindex /etc/gcrypt/hwf.deny
+This file can be used to disable the use of hardware based
+optimizations, @pxref{hardware features}.
+
+
+@item /etc/gcrypt/random.conf
+@cindex /etc/gcrypt/random.conf
+This file can be used to globally change parameters of the random
+generator.  The file is a simple text file where empty lines and
+lines with the first non white-space character being '#' are
+ignored.  Supported options are
+
+@table @file
+@item disable-jent
+@cindex disable-jent
+Disable the use of the jitter based entropy generator.
+
+@item only-urandom
+@cindex only-urandom
+Always use the non-blocking /dev/urandom or the respective system call
+instead of the blocking /dev/random.  If Libgcrypt is used early in
+the boot process of the system, this option should only be used if the
+system also supports the getrandom system call.
+
+@end table
+
+@item /etc/gcrypt/fips_enabled
+@itemx /proc/sys/crypto/fips_enabled
+@cindex /etc/gcrypt/fips_enabled
+@cindex fips_enabled
+On Linux these files are used to enable FIPS mode, @pxref{enabling fips mode}.
+
+@item /proc/cpuinfo
+@itemx /proc/self/auxv
+@cindex /proc/cpuinfo
+@cindex /proc/self/auxv
+On Linux running on the ARM architecture, these files are used to read
+hardware capabilities of the CPU.
+
+@end table
+
+
+@c **********************************************************
 @c *****************  Architecure Overview  *****************
 @c **********************************************************
 @node Architecture
@@ -5214,7 +5628,7 @@ self-contained functions.  Due to the wide variety of parameters
 required by different algorithms S-expressions, as flexible way to
 convey these parameters, are used.  There is a set of helper functions
 to work with these S-expressions.
-@c see @xref{S-expression Subsystem Architecture}.
+@c see @ref{S-expression Subsystem Architecture}.
 
 Aside of functions to register new algorithms, map algorithms names to
 algorithms identifiers and to lookup properties of a key, the
@@ -5483,8 +5897,10 @@ Both generators make use of so-called entropy gathering modules:
 
 @table @asis
 @item rndlinux
-Uses the operating system provided
-@file{/dev/random} and @file{/dev/urandom} devices.
+Uses the operating system provided @file{/dev/random} and
+@file{/dev/urandom} devices.  The @file{/dev/gcrypt/random.conf}
+config option @option{only-urandom} can be used to inhibit the use of
+the blocking @file{/dev/random} device.
 
 @item rndunix
 Runs several operating system commands to collect entropy from sources
@@ -5506,9 +5922,15 @@ that system and is the only gathering module available for that OS.
 
 @item rndhw
 Extra module to collect additional entropy by utilizing a hardware
-random number generator.  As of now the only supported hardware RNG is
-the Padlock engine of VIA (Centaur) CPUs.  It is not available in FIPS
-mode.
+random number generator.  As of now the supported hardware RNG is
+the Padlock engine of VIA (Centaur) CPUs and x86 CPUs with the RDRAND
+instruction.  It is not available in FIPS mode.
+
+@item rndjent
+Extra module to collect additional entropy using a CPU jitter based
+approach.  This is only used on X86 hardware where the RDTSC opcode is
+available.  The @file{/dev/gcrypt/random.conf} config option
+@option{disable-jent} can be used to inhibit the use of this module.
 
 @end table
 
@@ -5528,7 +5950,7 @@ Practically Strong Random Numbers".@footnote{Also described in chapter
 6 of his book "Cryptographic Security Architecture", New York, 2004,
 ISBN 0-387-95387-6.}
 
-A pool of 600 bytes is used and mixed using the core RIPE-MD160 hash
+A pool of 600 bytes is used and mixed using the core SHA-1 hash
 transform function.  Several extra features are used to make the
 robust against a wide variety of attacks and to protect against
 failures of subsystems.  The state of the generator may be saved to a
@@ -5542,7 +5964,7 @@ to mix in enough data from the gather modules before returning the
 actual random output.  Process fork detection and protection is
 implemented.
 
-@c FIXME:  The design and implementaion needs a more verbose description.
+@c FIXME:  The design and implementation needs a more verbose description.
 
 The implementation of the nonce generator (for
 @code{gcry_create_nonce}) is a straightforward repeated hash design: A