Add libotr/etc sources

author: SoniEx2 <endermoneymod@gmail.com> 2021-04-09 07:19:03 -0300
committer: SoniEx2 <endermoneymod@gmail.com> 2021-04-09 07:19:03 -0300
commit: 0e752a6e215aee21dc73da097c3225495d54a5b6 (patch)
tree: b81be02cbf2f06aebf322ac4a5d014b44176bba5 /libotr/libgcrypt-1.8.7/doc
parent: 7754076c715285173311a1b6811ce377950e18a6 (diff)
23 files changed, 19547 insertions, 0 deletions
diff --git a/libotr/libgcrypt-1.8.7/doc/ChangeLog-2011 b/libotr/libgcrypt-1.8.7/doc/ChangeLog-2011
new file mode 100644
index 0000000..de837a0
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/ChangeLog-2011
@@ -0,0 +1,488 @@
+2011-12-01  Werner Koch  <wk@g10code.com>
+
+	NB: ChangeLog files are no longer manually maintained.  Starting
+	on December 1st, 2011 we put change information only in the GIT
+	commit log, and generate a top-level ChangeLog file from logs at
+	"make dist".  See doc/HACKING for details.
+
+2011-09-15  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi: Remove the gcry_ac interface
+
+2009-10-28  Werner Koch  <wk@g10code.com>
+
+	* Makefile.am: Add code to build a man page for hmac256.
+	* yat2m.c: New.  Taken from GnuPG.
+	* gcrypt.text (hmac256): New section.
+
+2009-10-28  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Multi-Threading): Add examples.
+
+2009-07-02  Daiki Ueno  <ueno@unixuser.org>
+
+	* gcrypt.texi (Working with S-expressions): Describe format
+	character '%S'.  Typo fixes.  Fixes bug#1079.
+
+2009-05-10  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Working with cipher handles): Clarified that
+	keylengths are in bytes.
+
+2009-04-02  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Self-Tests): Fix register fucntion names.
+
+2009-02-22  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Memory allocation): Fix describion of gcry-calloc.
+	Reported by Sergi Blanch i Torné.
+
+2008-12-10  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Cryptographic Functions): Explain the domain
+	parameter for key generation.
+
+2008-12-05  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi: Updates for pubkey generation.
+
+2008-10-20  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Error handler): Fix description of
+	gcry_handler_no_mem_t.  Reported by Patrick Strateman.  desribe
+	what what the error handler is expected to do.  Fixes bug #961.
+
+2008-09-18  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (FIPS Mode): Add state transition Error to Error.
+	* fips-fsm.fig: Ditto.
+
+2008-09-18  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi: Add a couple of index items.
+	(FIPS Mode): Reflect recent changes.
+	(Controlling the library): Describe gcry_fips_mode_active.
+
+2008-09-16  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (FIPS Mode): Describe new transitions 18 and 19.
+	* fips-fsm.fig: Add new transitions.
+
+2008-09-15  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi: Fold the two FIPS appendices into one.
+
+2008-09-11  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Public-Key Subsystem Architecture): Explain RSA
+	blinding.
+
+2008-09-08  Marcus Brinkmann  <marcus@g10code.com>
+
+	* gcrypt.texi: Some typos fixed.
+
+2008-09-08  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi: Formatting cleanups.
+	* lgpl.texi (Library Copying): Replace @appendix by @unnumbered.
+	* gpl.texi (Copying): Ditto.
+
+2008-08-27  Werner Koch  <wk@g10code.com>
+
+	* Makefile.am (online): Take care of development versions.
+
+2008-08-18  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Top): Remove the detailmenu.
+	(Public Key Cryptographi (II)): Move into a section of the PK
+	interface description.
+	(Hashing): Move after the encryption chapters.
+
+2008-08-15  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Controlling the library): Remove
+	GCRYCTL_DUMP_CONFIG because it is not implemented.
+	(Initializing the library): Describe initialization steps with
+	regard to secure memory.
+
+	* gcrypt.texi (Working with cipher handles): Adjust for
+	implementation changes of gcry_cipher_setkey, gcry_cipher_setiv and
+	gcry_cipher_setctr.
+
+2008-01-04  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Controlling the library): Add remark that the
+	theoritical attack on a seed file is not feasible under Linux.
+
+2007-12-11  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi: Various minor corrections as reported by Elie De
+	Brauer more than a year ago.
+
+2007-06-15  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Controlling the library): Clarified the use of
+	GCRYCTL_ENABLE_QUICK_RANDOM.
+
+2007-04-30  Werner Koch  <wk@g10code.com>
+
+	* HACKING: New.  Two items by Marcus.
+	* README.apichanges: Move from .. to here.
+	* Makefile.am (EXTRA_DIST): Add new files.
+
+2007-04-09  Marcus Brinkmann  <marcus@g10code.de>
+
+	* gcrypt.texi: Fix some typos.
+
+2006-11-05  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (General public-key related Functions): Typo.
+
+2006-09-19  Werner Koch  <wk@g10code.com>
+
+	* Makefile.am (online): New target.
+
+2006-08-29  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi (Available ciphers): Add missing ciphers.
+
+2006-03-10  Brad Hards  <bradh@frogmouth.net> (wk, patch 2005-04-25)
+
+	* gcrypt.texi: Document SHA-224 and typo fixes.
+
+2006-01-18  Brad Hards  <bradh@frogmouth.net> (wk 2006-03-07)
+
+	* gcrypt.texi (Available cipher modes): Typo fix, add a little
+	more detail on cipher modes vs cipher algorithms.
+
+2006-01-08  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Added documentation for more gcry_control commands.
+
+	* gcrypt.texi: Fixed several typos; thanks to Tommi Vainikainen.
+
+2005-12-16  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (MPI formats): Fix return types of functions:
+	gcry_mpi_scan, gcry_mpi_print, gcry_mpi_aprint.
+
+2005-11-26  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: New chapter: Prime numbers.
+
+2005-11-12  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (MPI formats): Document that for gcry_mpi_scan and
+	in the case of GCRYMPI_FMT_HEX, BUFLEN must be zero.
+
+2005-10-31  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Added more gcry_control related descriptions.
+
+2005-10-16  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Controlling the library): Start documenting the
+	existing control commands.
+
+2005-04-11  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Available hash algorithms): Add entry for Whirlpool.
+
+2005-03-30  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Working with IO objects): Document ac io objects;
+	adjust ac scheme functions, which do now use io objects.
+
+2005-03-19  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Working with cipher handles): Clarify CTS mode.
+
+2005-02-08  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi: Fixed direntry.
+
+2005-02-13  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Using cryptographic functions): Document new
+	encoding and scheme crypto functionality.
+
+2005-02-03  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Fixed several typos; thanks to Michele Baldessari.
+
+2005-01-04  Werner Koch  <wk@g10code.com>
+
+	* gcrypt.texi: Updated to use @copying.  Fixed list of copyright
+	years; we had real changes in 2004.  Fixed some formatting issues.
+
+2004-08-24  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Miscellaneous): Document gcry_mpi_randomize.
+
+2004-08-18  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Multi Threading): Document
+	GCRY_THREAD_OPTION_PTH_IMPL, GCRY_THREAD_OPTION_PTHREAD_IMPL.
+
+2004-05-07  Moritz Schulte  <moritz@g10code.de>
+
+	* gcrypt.texi: Merged several fixes reported by Umberto Salsi.
+
+2004-04-08  Moritz Schulte  <moritz@g10code.de>
+
+	* gcrypt.texi (Multi Threading): Typo fix.
+
+2004-03-11  Marcus Brinkmann  <marcus@g10code.de>
+
+	* gcrypt.texi (Multi Threading): Partially document new thread
+	support.
+
+2004-02-24  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi (Calculations): Typo fix.
+
+2004-01-25  Moritz Schulte  <mo@g10code.com>
+
+	* gcrypt.texi (General cipher functions): Fixed descriptions of
+	the arguments for GCRYCTL_GET_KEYLEN, GCRYCTL_GET_BLKLEN; reported
+	by Randy.
+
+2004-01-14  Moritz Schulte  <mo@g10code.com>
+
+	* gcrypt.texi (Public Key cryptography II): Adjusted to new
+	gcry_ac_* API; document flags.
+
+2003-12-04  Werner Koch  <wk@gnupg.org>
+
+	* Makefile.am (gcrypt_TEXINFOS): Removed fdl.texi.
+
+2003-12-03  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi: Changed license from FDL to GPL because this is a
+	reference manual only useful along with actual code.
+	* fdl.texi: Removed.
+
+	* gcrypt.texi: Minor cleanups
+	(Working with keys): Clarified generation of RSA's E parameter.
+	(Multi Threading): Clarified.
+
+2003-11-11  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi (Working with S-expressions): Added "%b".
+
+2003-11-04  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi (Retrieving random numbers): Add gcry_create_nonce.
+
+2003-08-30  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi (Working with hash algorithms): Clarified that HMAC
+	does not work with all algorithms.
+
+2003-07-30  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Available asymmetric algorithms): Mention
+	GCRY_AC_ELG_E.
+
+2003-07-28  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Working with keys): Mention that gcry_pk_testkey
+	and gcry_ac_key_test only verify private keys.
+	(Working with keys): Fix typo.
+	(General public-key related Functions): Fixed some sentences,
+	thanks to Neil Spring.
+
+2003-07-27  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi: Adjusted description of gcry_mpi_scan and
+	gcry_mpi_dump. Add gcry_mpi_dump.
+
+2003-07-22  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Added more documentation for the register
+	mechanism.
+
+2003-07-18  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi (Misc): Add a warning on the use of opaque values.
+
+2003-07-14  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Overview): Mention the non-thread-safe-nature of
+	functions modifying context stored in handles.
+
+2003-07-12  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Available ciphers): Added: TWOFISH128.
+	(Error Handling): Merged a lot of documentation taken from GPGME.
+
+2003-07-08  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Working with sets of data): Documented:
+	gcry_ac_data_copy.
+
+2003-07-07  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Documented module system.
+
+2003-07-05  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Working with cipher handles): Small fix by Simon
+	Josefsson <jas@extundo.com>.
+
+2003-07-02  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Documented ac interface.
+
+2003-06-18  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Small fixes.
+
+2003-06-16  Moritz Schulte  <moritz@g10code.com>
+
+	* cipher-ref.sgml: Removed file.
+	* digest-ref.sgml: Likewise.
+	* misc-ref.sgml: Likewise.
+	* pubkey-ref.sgml: Likewise.
+	* reference.sgml: Likewise.
+	* version.sgml.in: Likewise.
+
+2003-06-15  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Documented several parts of the library, merged
+	some documentation from GPGME's manual, re-structured the whole
+	manual, added more menus.
+
+2003-06-14  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Hash Functions): Adjusteded description of
+	gcry_md_copy.
+
+2003-06-12  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Public Key Functions): Fix example S-Exp, i.e.:
+	added the number of following digits as prefix to the number of
+	bits.
+	(Public Key Functions): Document the general usage of `flags',
+	including the no-blinding flag.
+
+2003-06-11  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi (Hash Functions): Document possible values of HD.
+
+2003-06-09  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Version Check): Changed description of
+	gcry_check_version; the user now *must* call the function to
+	initialize the library.
+
+2003-06-08  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi: Change for libgpg-error.
+
+2003-05-22  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Public Key Functions): Fixed typo.
+
+2003-05-17  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Public Key Functions): Mention that only the
+	checking of secret keys is supported currently.
+
+2003-03-30  Simon Josefsson  <jas@extundo.com>
+
+	* gcrypt.texi: Add CTR.
+
+2003-03-22  Simon Josefsson  <jas@extundo.com>
+
+	* gcrypt.texi: Add CBC-MAC.
+
+2003-03-04  Moritz Schulte  <moritz@g10code.com>
+
+	* gcrypt.texi (Cipher Functions): Added gcry_cipher_reset.
+
+2003-01-23  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi (gcry_pk_decrypt): Described use of FLAGS
+
+2003-01-20  Simon Josefsson  <jas@extundo.com>
+
+	* gcrypt.texi (Hash Functions): Add CRC.
+
+2003-01-19  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi: Most functions are now documented.  Still need to
+	fine tune the menu structure, document some utility functions,
+	mark up indices and references and add examples.
+
+2002-08-14  Werner Koch  <wk@gnupg.org>
+
+	* gcrypt.texi: Typo fixes.
+
+2002-05-14  Werner Koch  <wk@gnupg.org>
+
+	* lgpl.texi: New.
+	* gcrypt.texi: Included lgpl and commented not yet converted text.
+
+2002-04-16  Werner Koch  <wk@gnupg.org>
+
+	* version.sgml.in, cipher-ref.sgml, digest-ref.sgml, misc-ref.sgml
+	* pubkey-ref.sgml, reference.sgml: Removed.
+	* gcrypt.texi: New. Based on the old sgml version.
+	* gpl.texi, fdl.texi: New.
+	* Makefile.am: Adjusted for use with texinfo.
+
+2000-12-21  Werner Koch  <wk@gnupg.org>
+
+	Renamed the gcryptref.sgml files and removed the GnuPG stuff.
+
+Tue Oct 26 14:10:21 CEST 1999  Werner Koch  <wk@gnupg.de>
+
+	* Makefile.am (SUBDIRS): Removed gph from this development series
+
+Mon Sep  6 19:59:08 CEST 1999  Werner Koch  <wk@isil.d.shuttle.de>
+
+	* Makefile.am (SUBDIRS): New subdir gph for the manual.
+
+Thu Jul 22 20:03:03 CEST 1999  Werner Koch  <wk@isil.d.shuttle.de>
+
+	* gpg.sgml (--always-trust): Added.
+
+Wed Jul 14 19:42:08 CEST 1999  Werner Koch  <wk@isil.d.shuttle.de>
+
+	* Makefile.am: Create a dummy man page if docbook-to-man is missing.
+
+Wed Jun 16 20:16:21 CEST 1999  Werner Koch  <wk@isil.d.shuttle.de>
+
+	* gpg1.pod: Removed.
+	* gpg.sgml: New. Replaces the pod file
+	* Makefile.am: Add rule to make a man file from sgml
+
+Tue Jun 15 12:21:08 CEST 1999  Werner Koch  <wk@isil.d.shuttle.de>
+
+	* Makefile.in.in: Use DESTDIR.
+
+Mon May 31 19:41:10 CEST 1999  Werner Koch  <wk@isil.d.shuttle.de>
+
+	* gpg.1pod: Enhanced the Bugs section (Michael).
+
+Wed Feb 10 17:15:39 CET 1999  Werner Koch  <wk@isil.d.shuttle.de>
+
+	* gpg.1pod: Spelling and grammar corrections (John A. Martin)
+	* FAQ: Ditto.
+	* DETAILS: Ditto.
+
+ Copyright 1999, 2000, 2002, 2003, 2008 Free Software Foundation, Inc.
+
+ This file is free software; as a special exception the author gives
+ unlimited permission to copy and/or distribute it, with or without
+ modifications, as long as this notice is preserved.
+
+ This file is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
+ implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+Local Variables:
+buffer-read-only: t
+End:
diff --git a/libotr/libgcrypt-1.8.7/doc/DCO b/libotr/libgcrypt-1.8.7/doc/DCO
new file mode 100644
index 0000000..ee460f6
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/DCO
@@ -0,0 +1,29 @@
+Libgcrypt Developer's Certificate of Origin.  Version 1.0
+=========================================================
+
+By making a contribution to the Libgcrypt project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the free software license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the
+    best of my knowledge, is covered under an appropriate free
+    software license and I have the right under that license to
+    submit that work with modifications, whether created in whole
+    or in part by me, under the same free software license
+    (unless I am permitted to submit under a different license),
+    as indicated in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including
+    all personal information I submit with it, including my
+    sign-off) is maintained indefinitely and may be redistributed
+    consistent with this project or the free software license(s)
+    involved.
+
+Signed-off-by: [Your name and mail address]
diff --git a/libotr/libgcrypt-1.8.7/doc/HACKING b/libotr/libgcrypt-1.8.7/doc/HACKING
new file mode 100644
index 0000000..0cb8d56
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/HACKING
@@ -0,0 +1,143 @@
+# HACKING                                                       -*- org -*-
+#+TITLE: Hacking notes for Libgcrypt
+#+STARTUP: showall
+
+* How to contribute
+
+  The following stuff explains some basic procedures you need to
+  follow if you want to contribute code or documentation.
+
+** No more ChangeLog files
+
+  Do not modify any of the ChangeLog files in Libgcrypt.  Starting on
+  December 1st, 2011 we put change information only in the GIT commit
+  log, and generate a top-level ChangeLog file from logs at "make
+  dist" time.  As such, there are strict requirements on the form of
+  the commit log messages.  The old ChangeLog files have all be
+  renamed to ChangeLog-2011
+
+** Commit log requirements
+
+  Your commit log should always start with a one-line summary, the
+  second line should be blank, and the remaining lines are usually
+  ChangeLog-style entries for all affected files.  However, it's fine
+  -- even recommended -- to write a few lines of prose describing the
+  change, when the summary and ChangeLog entries don't give enough of
+  the big picture.  Omit the leading TABs that you're used to seeing
+  in a "real" ChangeLog file, but keep the maximum line length at 72
+  or smaller, so that the generated ChangeLog lines, each with its
+  leading TAB, will not exceed 80 columns.
+
+** License policy
+
+  Libgcrypt is currently licensed under the LGPLv2+ with tools and the
+  manual being under the GPLv2+.  We may eventually update to a newer
+  version of the licenses or a combination of them.  It is thus
+  important, that all contributed code allows for an update of the
+  license; for example we can't accept code under the LGPLv2(only).
+
+  Libgcrypt used to have a strict policy of requiring copyright
+  assignments to the FSF.  To avoid this major organizational overhead
+  and to allow inclusion of code, not copyrighted by the FSF, this
+  policy has been relaxed.  It is now also possible to contribute code
+  by asserting that the contribution is in accordance to the
+  "Libgcrypt Developer's Certificate of Origin" as found in the file
+  "DCO".  (Except for a slight wording change, this DCO is identical
+  to the one used by the Linux kernel.)
+
+  If your want to contribute code or documentation to Libgcrypt and
+  you didn't signed a copyright assignment with the FSF in the past,
+  you need to take these simple steps:
+
+  - Decide which mail address you want to use.  Please have your real
+    name in the address and not a pseudonym.  Anonymous contributions
+    can only be done if you find a proxy who certifies for you.
+
+  - If your employer or school might claim ownership of code written
+    by you; you need to talk to them to make sure that you have the
+    right to contribute under the DCO.
+
+  - Send an OpenPGP signed mail to the gcrypt-devel@gnupg.org mailing
+    list from your mail address.  Include a copy of the DCO as found
+    in the official master branch.  Insert your name and email address
+    into the DCO in the same way you want to use it later.  Example:
+
+      Signed-off-by: Joe R. Hacker <joe@example.org>
+
+    (If you really need it, you may perform simple transformations of
+    the mail address: Replacing "@" by " at " or "." by " dot ".)
+
+  - That's it.  From now on you only need to add a "Signed-off-by:"
+    line with your name and mail address to the commit message.  It is
+    recommended to send the patches using a PGP/MIME signed mail.
+
+** Coding standards
+
+  Please follow the GNU coding standards.  If you are in doubt consult
+  the existing code as an example.  Do no re-indent code without a
+  need.  If you really need to do it, use a separate commit for such a
+  change.
+
+
+* Porting hints
+** Taking optimized MPI code out of GMP:
+
+  I generated the pentium4/* files by glueing the existing assembler
+  prologues to the GMP 4.2.1 assembler files generated with the m4
+  tool in GMP's build process, for example:
+
+    $ m4 -DHAVE_CONFIG_H -D__GMP_WITHIN_GMP -DOPERATION_rshift -DPIC \
+      rshift.asm >tmp-rshift.s
+
+  Then tmp-rshift will contain the assembler instructions for the
+  configured platform.  Unfortunately, this way the comments are lost.
+  For most files I re-inserted some of the comments, but this is
+  tedious work.
+
+
+* Debug hints
+
+** Debugging math stuff:
+
+  While debugging the ECC code in libgcrypt, I was in need for some
+  computer algebra system which would allow me to verify the numbers
+  in the debugging easily.  I found that PARI (pari-gp package in
+  Debian) has support for elliptic curves.  The below commands shows
+  how they are set up and used with an example.
+
+  ===8<========
+  hextodec(s)=local(v=Vec(s),a=10,b=11,c=12,d=13,e=14,f=15,A=10,B=11,C=12,D=13,E=14,F=15,h);if(#setunion(Set(v),Vec("0123456789ABCDEFabcdef"))>22,error);for(i=1,#v,h=shift(h,4)+eval(v[i]));h
+
+  p = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF")
+  a = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC")
+  b = hextodec("51953EB9618E1C9A1F929A21A0B68540EEA2DA725B99B315F3B8B489918EF109E156193951EC7E937B1652C0BD3BB1BF073573DF883D2C34F1EF451FD46B503F00")
+
+  /* Set up y^2 = x^3 + ax + b mod (p).  */
+  e = ellinit(Mod(1,p)*[0,0,0,a,b]);
+
+  gx = hextodec ("00C6858E06B70404E9CD9E3ECB662395B4429C648139053FB521F828AF606B4D3DBAA14B5E77EFE75928FE1DC127A2FFA8DE3348B3C1856A429BF97E7E31C2E5BD66")
+  gy = hextodec ("011839296A789A3BC0045C8A5FB42C7D1BD998F54449579B446817AFBD17273E662C97EE72995EF42640C550B9013FAD0761353C7086A272C24088BE94769FD16650")
+  g = Mod(1,p)*[gx,gy]
+
+  n = hextodec ("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA51868783BF2F966B7FCC0148F709A5D03BB5C9B8899C47AEBB6FB71E91386409")
+
+  /* Verify that G is on the curve, and that n is the order.  */
+  ellisoncurve (e,g)
+  isprime (n)
+  ellpow (e,g,n)
+
+  d = hextodec ("018F9573F25059571BDF614529953DE2540497CEDABD04F3AF78813BED7BB163A2FD919EECF822848FCA39EF55E500F8CE861C7D53D371857F7774B79428E887F81B")
+
+  qx = hextodec ("00316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B3B")
+  /* Note: WRONG! (It is apparent that this is the same as X shifted by
+     8 bit).  */
+  qy = hextodec ("0000316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B")
+  q = Mod(1,p)*[qx,qy]
+
+  /* Calculate what Q should be given d.  */
+  ellpow (e,g,d)
+
+  /* This is not 0 and thus shows that libgcrypt gave Q and d that do
+  not match.  */
+  ellpow (e,g,d) - q
+  ====8<=====================
diff --git a/libotr/libgcrypt-1.8.7/doc/Makefile.am b/libotr/libgcrypt-1.8.7/doc/Makefile.am
new file mode 100644
index 0000000..6a7cc8e
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/Makefile.am
@@ -0,0 +1,105 @@
+## Process this file with automake to create Makefile.in
+# Copyright (C) 2002 Free Software Foundation, Inc.
+#
+# This file is part of Libgcrypt.
+#
+# Libgcrypt is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation; either version 2.1 of
+# the License, or (at your option) any later version.
+#
+# Libgcrypt is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+
+EXTRA_DIST = README.apichanges HACKING DCO \
+	     libgcrypt-modules.eps fips-fsm.eps \
+	     libgcrypt-modules.png fips-fsm.png \
+             libgcrypt-modules.pdf fips-fsm.pdf \
+	     yat2m.c
+
+DISTCLEANFILES = gcrypt.cps yat2m-stamp.tmp yat2m-stamp $(myman_pages)
+CLEANFILES = yat2m
+
+BUILT_SOURCES = libgcrypt-modules.eps fips-fsm.eps \
+                libgcrypt-modules.png fips-fsm.png \
+                libgcrypt-modules.pdf fips-fsm.pdf
+
+info_TEXINFOS = gcrypt.texi
+gcrypt_TEXINFOS = lgpl.texi gpl.texi libgcrypt-modules.fig fips-fsm.fig
+
+YAT2M_OPTIONS = -I $(srcdir) \
+	--release "Libgcrypt @PACKAGE_VERSION@" --source "Libgcrypt"
+
+myman_sources = gcrypt.texi
+myman_pages   = hmac256.1
+
+man_MANS = $(myman_pages)
+
+yat2m: yat2m.c
+	$(CC_FOR_BUILD) -o $@ $(srcdir)/yat2m.c
+
+.fig.png:
+	fig2dev -L png `test -f '$<' || echo '$(srcdir)/'`$< $@
+
+.fig.jpg:
+	fig2dev -L jpg `test -f '$<' || echo '$(srcdir)/'`$< $@
+
+.fig.eps:
+	fig2dev -L eps `test -f '$<' || echo '$(srcdir)/'`$< $@
+
+.fig.pdf:
+	fig2dev -L pdf `test -f '$<' || echo '$(srcdir)/'`$< $@
+
+yat2m-stamp: $(myman_sources)
+	@rm -f yat2m-stamp.tmp
+	@touch yat2m-stamp.tmp
+	for file in $(myman_sources) ; do \
+              ./yat2m $(YAT2M_OPTIONS) --store \
+	          `test -f '$$file' || echo '$(srcdir)/'`$$file ; done
+	@mv -f yat2m-stamp.tmp $@
+
+yat2m-stamp: yat2m
+
+$(myman_pages) : yat2m-stamp
+	@if test -f $@; then :; else \
+            trap 'rm -rf yat2m-stamp yat2m-lock' 1 2 13 15; \
+               if mkdir yat2m-lock 2>/dev/null; then \
+                 rm -f yat2m-stamp; \
+                 $(MAKE) $(AM_MAKEFLAGS) yat2m-stamp; \
+                 rmdir yat2m-lock; \
+               else \
+                 while test -d yat2m-lock; do sleep 1; done; \
+                 test -f yat2m-stamp; exit $$?; \
+               fi; \
+             fi
+
+
+# Make sure that gcrypt.texi is touched if any other source file has
+# been modified.  This is required so that the version.texi magic
+# updates the release date.
+gcrypt.texi : $(gcrypt_TEXINFOS)
+	touch $(srcdir)/gcrypt.texi
+
+online: gcrypt.html gcrypt.pdf gcrypt.info
+	set -e; \
+	echo "Uploading current manuals to www.gnupg.org ..."; \
+	cp libgcrypt-modules.png gcrypt.html/; \
+	cp fips-fsm.png gcrypt.html/; \
+        user=werner ; dashdevel="" ; \
+        if echo "@PACKAGE_VERSION@" | grep -- "-svn" >/dev/null; then \
+	  dashdevel="-devel" ; \
+	  cp gcrypt.pdf gcrypt.html/; \
+	  cp gcrypt.info gcrypt.html/; \
+	else \
+          rsync -v gcrypt.pdf gcrypt.info \
+               $${user}@trithemius.gnupg.org:webspace/manuals/ ; \
+        fi ; \
+	cd gcrypt.html ; \
+        rsync -vr --exclude='.svn' .  \
+	  $${user}@trithemius.gnupg.org:webspace/manuals/gcrypt$${dashdevel}/
diff --git a/libotr/libgcrypt-1.8.7/doc/Makefile.in b/libotr/libgcrypt-1.8.7/doc/Makefile.in
new file mode 100644
index 0000000..9b7343a
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/Makefile.in
@@ -0,0 +1,979 @@
+# Makefile.in generated by automake 1.16.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2018 Free Software Foundation, Inc.
+
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+# Copyright (C) 2002 Free Software Foundation, Inc.
+#
+# This file is part of Libgcrypt.
+#
+# Libgcrypt is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation; either version 2.1 of
+# the License, or (at your option) any later version.
+#
+# Libgcrypt is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+VPATH = @srcdir@
+am__is_gnu_make = { \
+  if test -z '$(MAKELEVEL)'; then \
+    false; \
+  elif test -n '$(MAKE_HOST)'; then \
+    true; \
+  elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
+    true; \
+  else \
+    false; \
+  fi; \
+}
+am__make_running_with_option = \
+  case $${target_option-} in \
+      ?) ;; \
+      *) echo "am__make_running_with_option: internal error: invalid" \
+              "target option '$${target_option-}' specified" >&2; \
+         exit 1;; \
+  esac; \
+  has_opt=no; \
+  sane_makeflags=$$MAKEFLAGS; \
+  if $(am__is_gnu_make); then \
+    sane_makeflags=$$MFLAGS; \
+  else \
+    case $$MAKEFLAGS in \
+      *\\[\ \	]*) \
+        bs=\\; \
+        sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
+          | sed "s/$$bs$$bs[$$bs $$bs	]*//g"`;; \
+    esac; \
+  fi; \
+  skip_next=no; \
+  strip_trailopt () \
+  { \
+    flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
+  }; \
+  for flg in $$sane_makeflags; do \
+    test $$skip_next = yes && { skip_next=no; continue; }; \
+    case $$flg in \
+      *=*|--*) continue;; \
+        -*I) strip_trailopt 'I'; skip_next=yes;; \
+      -*I?*) strip_trailopt 'I';; \
+        -*O) strip_trailopt 'O'; skip_next=yes;; \
+      -*O?*) strip_trailopt 'O';; \
+        -*l) strip_trailopt 'l'; skip_next=yes;; \
+      -*l?*) strip_trailopt 'l';; \
+      -[dEDm]) skip_next=yes;; \
+      -[JT]) skip_next=yes;; \
+    esac; \
+    case $$flg in \
+      *$$target_option*) has_opt=yes; break;; \
+    esac; \
+  done; \
+  test $$has_opt = yes
+am__make_dryrun = (target_option=n; $(am__make_running_with_option))
+am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkglibexecdir = $(libexecdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = doc
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/m4/gpg-error.m4 \
+	$(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \
+	$(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \
+	$(top_srcdir)/m4/lt~obsolete.m4 \
+	$(top_srcdir)/m4/noexecstack.m4 $(top_srcdir)/m4/onceonly.m4 \
+	$(top_srcdir)/m4/socklen.m4 $(top_srcdir)/m4/sys_socket_h.m4 \
+	$(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+	$(ACLOCAL_M4)
+DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/version.texi \
+	$(srcdir)/stamp-vti $(am__DIST_COMMON)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/config.h
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+AM_V_P = $(am__v_P_@AM_V@)
+am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
+am__v_P_0 = false
+am__v_P_1 = :
+AM_V_GEN = $(am__v_GEN_@AM_V@)
+am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
+am__v_GEN_0 = @echo "  GEN     " $@;
+am__v_GEN_1 = 
+AM_V_at = $(am__v_at_@AM_V@)
+am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
+am__v_at_0 = @
+am__v_at_1 = 
+SOURCES =
+DIST_SOURCES =
+AM_V_DVIPS = $(am__v_DVIPS_@AM_V@)
+am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@)
+am__v_DVIPS_0 = @echo "  DVIPS   " $@;
+am__v_DVIPS_1 = 
+AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@)
+am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@)
+am__v_MAKEINFO_0 = @echo "  MAKEINFO" $@;
+am__v_MAKEINFO_1 = 
+AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@)
+am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@)
+am__v_INFOHTML_0 = @echo "  INFOHTML" $@;
+am__v_INFOHTML_1 = 
+AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@)
+am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@)
+am__v_TEXI2DVI_0 = @echo "  TEXI2DVI" $@;
+am__v_TEXI2DVI_1 = 
+AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@)
+am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@)
+am__v_TEXI2PDF_0 = @echo "  TEXI2PDF" $@;
+am__v_TEXI2PDF_1 = 
+AM_V_texinfo = $(am__v_texinfo_@AM_V@)
+am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@)
+am__v_texinfo_0 = -q
+am__v_texinfo_1 = 
+AM_V_texidevnull = $(am__v_texidevnull_@AM_V@)
+am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@)
+am__v_texidevnull_0 = > /dev/null
+am__v_texidevnull_1 = 
+INFO_DEPS = $(srcdir)/gcrypt.info
+TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex
+am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux
+DVIS = gcrypt.dvi
+PDFS = gcrypt.pdf
+PSS = gcrypt.ps
+HTMLS = gcrypt.html
+TEXINFOS = gcrypt.texi
+TEXI2DVI = texi2dvi
+TEXI2PDF = $(TEXI2DVI) --pdf --batch
+MAKEINFOHTML = $(MAKEINFO) --html
+AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS)
+DVIPS = dvips
+am__can_run_installinfo = \
+  case $$AM_UPDATE_INFO_DIR in \
+    n|no|NO) false;; \
+    *) (install-info --version) >/dev/null 2>&1;; \
+  esac
+am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"
+am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
+am__vpath_adj = case $$p in \
+    $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
+    *) f=$$p;; \
+  esac;
+am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
+am__install_max = 40
+am__nobase_strip_setup = \
+  srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
+am__nobase_strip = \
+  for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
+am__nobase_list = $(am__nobase_strip_setup); \
+  for p in $$list; do echo "$$p $$p"; done | \
+  sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
+  $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
+    if (++n[$$2] == $(am__install_max)) \
+      { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
+    END { for (dir in files) print dir, files[dir] }'
+am__base_list = \
+  sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
+  sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
+am__uninstall_files_from_dir = { \
+  test -z "$$files" \
+    || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \
+    || { echo " ( cd '$$dir' && rm -f" $$files ")"; \
+         $(am__cd) "$$dir" && rm -f $$files; }; \
+  }
+man1dir = $(mandir)/man1
+NROFF = nroff
+MANS = $(man_MANS)
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+am__DIST_COMMON = $(gcrypt_TEXINFOS) $(srcdir)/Makefile.in \
+	$(top_srcdir)/build-aux/mdate-sh \
+	$(top_srcdir)/build-aux/texinfo.tex
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+ACLOCAL = @ACLOCAL@
+AMTAR = @AMTAR@
+AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
+AR = @AR@
+AS = @AS@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BUILD_FILEVERSION = @BUILD_FILEVERSION@
+BUILD_REVISION = @BUILD_REVISION@
+BUILD_TIMESTAMP = @BUILD_TIMESTAMP@
+CC = @CC@
+CCAS = @CCAS@
+CCASDEPMODE = @CCASDEPMODE@
+CCASFLAGS = @CCASFLAGS@
+CCDEPMODE = @CCDEPMODE@
+CC_FOR_BUILD = @CC_FOR_BUILD@
+CFLAGS = @CFLAGS@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DLLTOOL = @DLLTOOL@
+DL_LIBS = @DL_LIBS@
+DSYMUTIL = @DSYMUTIL@
+DUMPBIN = @DUMPBIN@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+EXEEXT = @EXEEXT@
+FALLBACK_SOCKLEN_T = @FALLBACK_SOCKLEN_T@
+FGREP = @FGREP@
+GCRYPT_CIPHERS = @GCRYPT_CIPHERS@
+GCRYPT_DIGESTS = @GCRYPT_DIGESTS@
+GCRYPT_HWF_MODULES = @GCRYPT_HWF_MODULES@
+GCRYPT_KDFS = @GCRYPT_KDFS@
+GCRYPT_PUBKEY_CIPHERS = @GCRYPT_PUBKEY_CIPHERS@
+GCRYPT_RANDOM = @GCRYPT_RANDOM@
+GPG_ERROR_CFLAGS = @GPG_ERROR_CFLAGS@
+GPG_ERROR_CONFIG = @GPG_ERROR_CONFIG@
+GPG_ERROR_LIBS = @GPG_ERROR_LIBS@
+GPG_ERROR_MT_CFLAGS = @GPG_ERROR_MT_CFLAGS@
+GPG_ERROR_MT_LIBS = @GPG_ERROR_MT_LIBS@
+GREP = @GREP@
+INSERT_SYS_SELECT_H = @INSERT_SYS_SELECT_H@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+LD = @LD@
+LDFLAGS = @LDFLAGS@
+LIBGCRYPT_CIPHERS = @LIBGCRYPT_CIPHERS@
+LIBGCRYPT_CONFIG_API_VERSION = @LIBGCRYPT_CONFIG_API_VERSION@
+LIBGCRYPT_CONFIG_CFLAGS = @LIBGCRYPT_CONFIG_CFLAGS@
+LIBGCRYPT_CONFIG_HOST = @LIBGCRYPT_CONFIG_HOST@
+LIBGCRYPT_CONFIG_LIBS = @LIBGCRYPT_CONFIG_LIBS@
+LIBGCRYPT_DIGESTS = @LIBGCRYPT_DIGESTS@
+LIBGCRYPT_LT_AGE = @LIBGCRYPT_LT_AGE@
+LIBGCRYPT_LT_CURRENT = @LIBGCRYPT_LT_CURRENT@
+LIBGCRYPT_LT_REVISION = @LIBGCRYPT_LT_REVISION@
+LIBGCRYPT_PUBKEY_CIPHERS = @LIBGCRYPT_PUBKEY_CIPHERS@
+LIBGCRYPT_THREAD_MODULES = @LIBGCRYPT_THREAD_MODULES@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIPO = @LIPO@
+LN_S = @LN_S@
+LTLIBOBJS = @LTLIBOBJS@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+MANIFEST_TOOL = @MANIFEST_TOOL@
+MKDIR_P = @MKDIR_P@
+MPI_SFLAGS = @MPI_SFLAGS@
+NM = @NM@
+NMEDIT = @NMEDIT@
+NOEXECSTACK_FLAGS = @NOEXECSTACK_FLAGS@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OTOOL = @OTOOL@
+OTOOL64 = @OTOOL64@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PTH_CFLAGS = @PTH_CFLAGS@
+PTH_CONFIG = @PTH_CONFIG@
+PTH_LIBS = @PTH_LIBS@
+RANLIB = @RANLIB@
+RC = @RC@
+RUN_LARGE_DATA_TESTS = @RUN_LARGE_DATA_TESTS@
+SED = @SED@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+STRIP = @STRIP@
+SYSROOT = @SYSROOT@
+SYS_SOCKET_H = @SYS_SOCKET_H@
+VERSION = @VERSION@
+VERSION_NUMBER = @VERSION_NUMBER@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_AR = @ac_ct_AR@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+dvidir = @dvidir@
+emacs_local_vars_begin = @emacs_local_vars_begin@
+emacs_local_vars_end = @emacs_local_vars_end@
+emacs_local_vars_read_only = @emacs_local_vars_read_only@
+exec_prefix = @exec_prefix@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+runstatedir = @runstatedir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+EXTRA_DIST = README.apichanges HACKING DCO \
+	     libgcrypt-modules.eps fips-fsm.eps \
+	     libgcrypt-modules.png fips-fsm.png \
+             libgcrypt-modules.pdf fips-fsm.pdf \
+	     yat2m.c
+
+DISTCLEANFILES = gcrypt.cps yat2m-stamp.tmp yat2m-stamp $(myman_pages)
+CLEANFILES = yat2m
+BUILT_SOURCES = libgcrypt-modules.eps fips-fsm.eps \
+                libgcrypt-modules.png fips-fsm.png \
+                libgcrypt-modules.pdf fips-fsm.pdf
+
+info_TEXINFOS = gcrypt.texi
+gcrypt_TEXINFOS = lgpl.texi gpl.texi libgcrypt-modules.fig fips-fsm.fig
+YAT2M_OPTIONS = -I $(srcdir) \
+	--release "Libgcrypt @PACKAGE_VERSION@" --source "Libgcrypt"
+
+myman_sources = gcrypt.texi
+myman_pages = hmac256.1
+man_MANS = $(myman_pages)
+all: $(BUILT_SOURCES)
+	$(MAKE) $(AM_MAKEFLAGS) all-am
+
+.SUFFIXES:
+.SUFFIXES: .dvi .eps .fig .html .info .jpg .pdf .png .ps .texi
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am  $(am__configure_deps)
+	@for dep in $?; do \
+	  case '$(am__configure_deps)' in \
+	    *$$dep*) \
+	      ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+	        && { if test -f $@; then exit 0; else break; fi; }; \
+	      exit 1;; \
+	  esac; \
+	done; \
+	echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \
+	$(am__cd) $(top_srcdir) && \
+	  $(AUTOMAKE) --gnu doc/Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+	@case '$?' in \
+	  *config.status*) \
+	    cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+	  *) \
+	    echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \
+	    cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \
+	esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+
+mostlyclean-libtool:
+	-rm -f *.lo
+
+clean-libtool:
+	-rm -rf .libs _libs
+
+.texi.info:
+	$(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \
+	am__cwd=`pwd` && $(am__cd) $(srcdir) && \
+	rm -rf $$backupdir && mkdir $$backupdir && \
+	if ($(MAKEINFO) --version) >/dev/null 2>&1; then \
+	  for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \
+	    if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \
+	  done; \
+	else :; fi && \
+	cd "$$am__cwd"; \
+	if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
+	 -o $@ $<; \
+	then \
+	  rc=0; \
+	  $(am__cd) $(srcdir); \
+	else \
+	  rc=$$?; \
+	  $(am__cd) $(srcdir) && \
+	  $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \
+	fi; \
+	rm -rf $$backupdir; exit $$rc
+
+.texi.dvi:
+	$(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+	$(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \
+	$<
+
+.texi.pdf:
+	$(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+	$(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \
+	$<
+
+.texi.html:
+	$(AM_V_MAKEINFO)rm -rf $(@:.html=.htp)
+	$(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
+	 -o $(@:.html=.htp) $<; \
+	then \
+	  rm -rf $@ && mv $(@:.html=.htp) $@; \
+	else \
+	  rm -rf $(@:.html=.htp); exit 1; \
+	fi
+$(srcdir)/gcrypt.info: gcrypt.texi $(srcdir)/version.texi $(gcrypt_TEXINFOS)
+gcrypt.dvi: gcrypt.texi $(srcdir)/version.texi $(gcrypt_TEXINFOS)
+gcrypt.pdf: gcrypt.texi $(srcdir)/version.texi $(gcrypt_TEXINFOS)
+gcrypt.html: gcrypt.texi $(srcdir)/version.texi $(gcrypt_TEXINFOS)
+$(srcdir)/version.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-vti
+$(srcdir)/stamp-vti: gcrypt.texi $(top_srcdir)/configure
+	@(dir=.; test -f ./gcrypt.texi || dir=$(srcdir); \
+	set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/gcrypt.texi`; \
+	echo "@set UPDATED $$1 $$2 $$3"; \
+	echo "@set UPDATED-MONTH $$2 $$3"; \
+	echo "@set EDITION $(VERSION)"; \
+	echo "@set VERSION $(VERSION)") > vti.tmp$$$$ && \
+	(cmp -s vti.tmp$$$$ $(srcdir)/version.texi \
+	  || (echo "Updating $(srcdir)/version.texi" && \
+	      cp vti.tmp$$$$ $(srcdir)/version.texi.tmp$$$$ && \
+	      mv $(srcdir)/version.texi.tmp$$$$ $(srcdir)/version.texi)) && \
+	rm -f vti.tmp$$$$ $(srcdir)/version.texi.$$$$
+	@cp $(srcdir)/version.texi $@
+
+mostlyclean-vti:
+	-rm -f vti.tmp* $(srcdir)/version.texi.tmp*
+
+maintainer-clean-vti:
+@MAINTAINER_MODE_TRUE@	-rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi
+.dvi.ps:
+	$(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	$(DVIPS) $(AM_V_texinfo) -o $@ $<
+
+uninstall-dvi-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(dvidir)/$$f"; \
+	done
+
+uninstall-html-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(HTMLS)'; test -n "$(htmldir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \
+	  rm -rf "$(DESTDIR)$(htmldir)/$$f"; \
+	done
+
+uninstall-info-am:
+	@$(PRE_UNINSTALL)
+	@if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \
+	  list='$(INFO_DEPS)'; \
+	  for file in $$list; do \
+	    relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	    echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \
+	    if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
+	    then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \
+	  done; \
+	else :; fi
+	@$(NORMAL_UNINSTALL)
+	@list='$(INFO_DEPS)'; \
+	for file in $$list; do \
+	  relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	  relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \
+	     echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \
+	     rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \
+	   else :; fi); \
+	done
+
+uninstall-pdf-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(pdfdir)/$$f"; \
+	done
+
+uninstall-ps-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(PSS)'; test -n "$(psdir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(psdir)/$$f"; \
+	done
+
+dist-info: $(INFO_DEPS)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+	list='$(INFO_DEPS)'; \
+	for base in $$list; do \
+	  case $$base in \
+	    $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \
+	  esac; \
+	  if test -f $$base; then d=.; else d=$(srcdir); fi; \
+	  base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \
+	    if test -f $$file; then \
+	      relfile=`expr "$$file" : "$$d/\(.*\)"`; \
+	      test -f "$(distdir)/$$relfile" || \
+		cp -p $$file "$(distdir)/$$relfile"; \
+	    else :; fi; \
+	  done; \
+	done
+
+mostlyclean-aminfo:
+	-rm -rf gcrypt.t2d gcrypt.t2p
+
+clean-aminfo:
+	-test -z "gcrypt.dvi gcrypt.pdf gcrypt.ps gcrypt.html" \
+	|| rm -rf gcrypt.dvi gcrypt.pdf gcrypt.ps gcrypt.html
+
+maintainer-clean-aminfo:
+	@list='$(INFO_DEPS)'; for i in $$list; do \
+	  i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \
+	  rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \
+	done
+install-man1: $(man_MANS)
+	@$(NORMAL_INSTALL)
+	@list1=''; \
+	list2='$(man_MANS)'; \
+	test -n "$(man1dir)" \
+	  && test -n "`echo $$list1$$list2`" \
+	  || exit 0; \
+	echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \
+	$(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \
+	{ for i in $$list1; do echo "$$i"; done;  \
+	if test -n "$$list2"; then \
+	  for i in $$list2; do echo "$$i"; done \
+	    | sed -n '/\.1[a-z]*$$/p'; \
+	fi; \
+	} | while read p; do \
+	  if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; echo "$$p"; \
+	done | \
+	sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
+	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
+	sed 'N;N;s,\n, ,g' | { \
+	list=; while read file base inst; do \
+	  if test "$$base" = "$$inst"; then list="$$list $$file"; else \
+	    echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
+	    $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
+	  fi; \
+	done; \
+	for i in $$list; do echo "$$i"; done | $(am__base_list) | \
+	while read files; do \
+	  test -z "$$files" || { \
+	    echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
+	    $(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
+	done; }
+
+uninstall-man1:
+	@$(NORMAL_UNINSTALL)
+	@list=''; test -n "$(man1dir)" || exit 0; \
+	files=`{ for i in $$list; do echo "$$i"; done; \
+	l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \
+	  sed -n '/\.1[a-z]*$$/p'; \
+	} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
+	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
+	dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir)
+tags TAGS:
+
+ctags CTAGS:
+
+cscope cscopelist:
+
+
+distdir: $(BUILT_SOURCES)
+	$(MAKE) $(AM_MAKEFLAGS) distdir-am
+
+distdir-am: $(DISTFILES)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+	topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+	list='$(DISTFILES)'; \
+	  dist_files=`for file in $$list; do echo $$file; done | \
+	  sed -e "s|^$$srcdirstrip/||;t" \
+	      -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+	case $$dist_files in \
+	  */*) $(MKDIR_P) `echo "$$dist_files" | \
+			   sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+			   sort -u` ;; \
+	esac; \
+	for file in $$dist_files; do \
+	  if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+	  if test -d $$d/$$file; then \
+	    dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+	    if test -d "$(distdir)/$$file"; then \
+	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+	    fi; \
+	    if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+	      cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
+	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+	    fi; \
+	    cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
+	  else \
+	    test -f "$(distdir)/$$file" \
+	    || cp -p $$d/$$file "$(distdir)/$$file" \
+	    || exit 1; \
+	  fi; \
+	done
+	$(MAKE) $(AM_MAKEFLAGS) \
+	  top_distdir="$(top_distdir)" distdir="$(distdir)" \
+	  dist-info
+check-am: all-am
+check: $(BUILT_SOURCES)
+	$(MAKE) $(AM_MAKEFLAGS) check-am
+all-am: Makefile $(INFO_DEPS) $(MANS)
+installdirs:
+	for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \
+	  test -z "$$dir" || $(MKDIR_P) "$$dir"; \
+	done
+install: $(BUILT_SOURCES)
+	$(MAKE) $(AM_MAKEFLAGS) install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+	if test -z '$(STRIP)'; then \
+	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	      install; \
+	else \
+	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	    "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
+	fi
+mostlyclean-generic:
+
+clean-generic:
+	-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+	-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+	-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+	-test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES)
+
+maintainer-clean-generic:
+	@echo "This command is intended for maintainers to use"
+	@echo "it deletes files that may require special tools to rebuild."
+	-test -z "$(BUILT_SOURCES)" || rm -f $(BUILT_SOURCES)
+clean: clean-am
+
+clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-am
+	-rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am: $(DVIS)
+
+html: html-am
+
+html-am: $(HTMLS)
+
+info: info-am
+
+info-am: $(INFO_DEPS)
+
+install-data-am: install-info-am install-man
+
+install-dvi: install-dvi-am
+
+install-dvi-am: $(DVIS)
+	@$(NORMAL_INSTALL)
+	@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \
+	done
+install-exec-am:
+
+install-html: install-html-am
+
+install-html-am: $(HTMLS)
+	@$(NORMAL_INSTALL)
+	@list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  $(am__strip_dir) \
+	  d2=$$d$$p; \
+	  if test -d "$$d2"; then \
+	    echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
+	    echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \
+	  else \
+	    list2="$$list2 $$d2"; \
+	  fi; \
+	done; \
+	test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \
+	done; }
+install-info: install-info-am
+
+install-info-am: $(INFO_DEPS)
+	@$(NORMAL_INSTALL)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+	list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \
+	fi; \
+	for file in $$list; do \
+	  case $$file in \
+	    $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
+	  esac; \
+	  if test -f $$file; then d=.; else d=$(srcdir); fi; \
+	  file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \
+	               $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \
+	    if test -f $$ifile; then \
+	      echo "$$ifile"; \
+	    else : ; fi; \
+	  done; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done
+	@$(POST_INSTALL)
+	@if $(am__can_run_installinfo); then \
+	  list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+	  for file in $$list; do \
+	    relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	    echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\
+	    install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\
+	  done; \
+	else : ; fi
+install-man: install-man1
+
+install-pdf: install-pdf-am
+
+install-pdf-am: $(PDFS)
+	@$(NORMAL_INSTALL)
+	@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done
+install-ps: install-ps-am
+
+install-ps-am: $(PSS)
+	@$(NORMAL_INSTALL)
+	@list='$(PSS)'; test -n "$(psdir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+	-rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-aminfo \
+	maintainer-clean-generic maintainer-clean-vti
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \
+	mostlyclean-libtool mostlyclean-vti
+
+pdf: pdf-am
+
+pdf-am: $(PDFS)
+
+ps: ps-am
+
+ps-am: $(PSS)
+
+uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \
+	uninstall-man uninstall-pdf-am uninstall-ps-am
+
+uninstall-man: uninstall-man1
+
+.MAKE: all check install install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-aminfo clean-generic \
+	clean-libtool cscopelist-am ctags-am dist-info distclean \
+	distclean-generic distclean-libtool distdir dvi dvi-am html \
+	html-am info info-am install install-am install-data \
+	install-data-am install-dvi install-dvi-am install-exec \
+	install-exec-am install-html install-html-am install-info \
+	install-info-am install-man install-man1 install-pdf \
+	install-pdf-am install-ps install-ps-am install-strip \
+	installcheck installcheck-am installdirs maintainer-clean \
+	maintainer-clean-aminfo maintainer-clean-generic \
+	maintainer-clean-vti mostlyclean mostlyclean-aminfo \
+	mostlyclean-generic mostlyclean-libtool mostlyclean-vti pdf \
+	pdf-am ps ps-am tags-am uninstall uninstall-am \
+	uninstall-dvi-am uninstall-html-am uninstall-info-am \
+	uninstall-man uninstall-man1 uninstall-pdf-am uninstall-ps-am
+
+.PRECIOUS: Makefile
+
+
+yat2m: yat2m.c
+	$(CC_FOR_BUILD) -o $@ $(srcdir)/yat2m.c
+
+.fig.png:
+	fig2dev -L png `test -f '$<' || echo '$(srcdir)/'`$< $@
+
+.fig.jpg:
+	fig2dev -L jpg `test -f '$<' || echo '$(srcdir)/'`$< $@
+
+.fig.eps:
+	fig2dev -L eps `test -f '$<' || echo '$(srcdir)/'`$< $@
+
+.fig.pdf:
+	fig2dev -L pdf `test -f '$<' || echo '$(srcdir)/'`$< $@
+
+yat2m-stamp: $(myman_sources)
+	@rm -f yat2m-stamp.tmp
+	@touch yat2m-stamp.tmp
+	for file in $(myman_sources) ; do \
+              ./yat2m $(YAT2M_OPTIONS) --store \
+	          `test -f '$$file' || echo '$(srcdir)/'`$$file ; done
+	@mv -f yat2m-stamp.tmp $@
+
+yat2m-stamp: yat2m
+
+$(myman_pages) : yat2m-stamp
+	@if test -f $@; then :; else \
+            trap 'rm -rf yat2m-stamp yat2m-lock' 1 2 13 15; \
+               if mkdir yat2m-lock 2>/dev/null; then \
+                 rm -f yat2m-stamp; \
+                 $(MAKE) $(AM_MAKEFLAGS) yat2m-stamp; \
+                 rmdir yat2m-lock; \
+               else \
+                 while test -d yat2m-lock; do sleep 1; done; \
+                 test -f yat2m-stamp; exit $$?; \
+               fi; \
+             fi
+
+# Make sure that gcrypt.texi is touched if any other source file has
+# been modified.  This is required so that the version.texi magic
+# updates the release date.
+gcrypt.texi : $(gcrypt_TEXINFOS)
+	touch $(srcdir)/gcrypt.texi
+
+online: gcrypt.html gcrypt.pdf gcrypt.info
+	set -e; \
+	echo "Uploading current manuals to www.gnupg.org ..."; \
+	cp libgcrypt-modules.png gcrypt.html/; \
+	cp fips-fsm.png gcrypt.html/; \
+        user=werner ; dashdevel="" ; \
+        if echo "@PACKAGE_VERSION@" | grep -- "-svn" >/dev/null; then \
+	  dashdevel="-devel" ; \
+	  cp gcrypt.pdf gcrypt.html/; \
+	  cp gcrypt.info gcrypt.html/; \
+	else \
+          rsync -v gcrypt.pdf gcrypt.info \
+               $${user}@trithemius.gnupg.org:webspace/manuals/ ; \
+        fi ; \
+	cd gcrypt.html ; \
+        rsync -vr --exclude='.svn' .  \
+	  $${user}@trithemius.gnupg.org:webspace/manuals/gcrypt$${dashdevel}/
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/libotr/libgcrypt-1.8.7/doc/README.apichanges b/libotr/libgcrypt-1.8.7/doc/README.apichanges
new file mode 100644
index 0000000..63b64da
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/README.apichanges
@@ -0,0 +1,115 @@
+README.apichanges 2003-07-28
+
+  NOTE: THESE ARE API CHANGES DONE BEFORE THE FIRST STABLE RELEASE SO
+  THEY ARE NOT RELEVANT ANYMORE [stable is 1.2.4 right now]
+
+We decided to change a couple of annoying things in Libgcrypt and to
+cleanup the API.  The new API better fits into a multi-threaded
+environment and is more consistent.  One import change is that all
+functions return error codes from a set of error codes shared between
+GnuPG, GPGME and Libgcrypt.
+
+This file contains some hints on how to port your application from
+libgcrypt <= 1.1.12 to the current API as of 1.1.42.  We hope that
+there won't be another need for such a major change.
+
+
+* Types
+
+  All types definitions changed to a foo_t scheme; for some time we
+  will support the old names but you better start to rename them:
+
+  s/GCRY_MPI/gcry_mpi_t/
+  s/GcryMPI/gcry_mpi_t/
+  s/GCRY_SEXP/gcry_sexp_t/
+  s/GcrySexp/gcry_sexp_t/
+  s/GCRY_CIPHER_HD/gcry_cipher_hd_t/
+  s/GcryCipherHd/gcry_cipher_hd_t/
+  s/GCRY_MD_HD/gcry_md_hd_t/
+  s/GcryMDHd/gcry_md_hd_t/
+
+* Initialization
+
+  For proper initialization of the library, you must call
+  gcry_check_version() before calling any other function except for
+  these gcry_control operations:
+     GCRYCTL_SUSPEND_SECMEM_WARN
+     GCRYCTL_DISABLE_INTERNAL_LOCKING
+     GCRYCTL_ANY_INITIALIZATION_P
+     GCRYCTL_INITIALIZATION_FINISHED_P
+
+
+* Handles
+
+  gcry_cipher_open and gcry_md_open do now return an error code
+  instead of a NULL handle; the handle is now returned by
+  asigning it to the first argument.  Example on how to change your
+  code:
+
+  Old:
+
+    hd = gcry_md_open (algo, flags);
+    if (!hd)
+      {
+         fprintf (stderr, "md_open failed: %s\n", gcry_errno (-1));
+         ....
+
+  New:
+
+    rc = gcry_md_open (&hd, algo, flags);
+    if (rc)
+      {
+         fprintf (stderr, "md_open failed: %s\n", gcry_strerror (rc));
+         ....
+
+  If you are not interested in the error code, you can do it in a
+  simplified way:
+ 
+    gcry_md_open (&hd, algo, flags);
+    if (!hd)
+        abort ();
+
+  i.e. the function makes sure that HD points to NULL in case of an error.
+  The required change for gcry_cipher_open is similar.
+
+* Message Digests
+
+  The order of the arguments to gcry_md_copy has been changed in order
+  to be more consistent with other functions of this type.  This means
+  that the new message digest handle will be a copy of the message
+  handle specified by the second argument and stored at the address
+  pointed to by the first argument.
+
+* Error codes
+
+  gcry_errno () has been removed because it is hard to use in
+  multi-threaded environment.  You need to save the error code
+  returned by the functions and use it either numerical or passing it
+  to gcry_strerror (since gcry_strerror is a wrapper function for
+  gpg_strerror, the latter function can also be used).
+
+  Instead of using the error codes GCRYERR_*, you have to use the
+  GPG_ERR_* names. 
+
+* S-expressions
+
+  gcry_sexp_canon_len used to return a `historical' error code in
+  `errcode', this is not the case anymore; the value returned in
+  `errcode' is now a standard Libgcrypt (i.e. gpg-error) error code.
+
+* MPI
+
+  gcry_mpi_scan and gcry_mpi_print need the size of a provided buffer
+  as input and return the number of bytes actually scanned/printed to
+  the user.  The old API used a single size_t Pointer for both tasks,
+  the new API distinguishes between the input and the output values.
+
+* Public Key cryptography
+
+  gcry_pk_decrypt used to return a `simple S-expression part' that
+  contains a single MPI value.  In case the `data' S-expression
+  contains a `flags' element, the result S-expression is filled with a
+  complete S-expression of the following format:
+
+    (value PLAINTEXT)
+
diff --git a/libotr/libgcrypt-1.8.7/doc/fips-fsm.eps b/libotr/libgcrypt-1.8.7/doc/fips-fsm.eps
new file mode 100644
index 0000000..8676147
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/fips-fsm.eps
@@ -0,0 +1,514 @@
+%!PS-Adobe-3.0 EPSF-3.0
+%%Title: /home/wk/s/libgcrypt-1.8/doc/fips-fsm.fig
+%%Creator: fig2dev Version 3.2.7a
+%%CreationDate: 2020-10-23 19:27:38
+%%BoundingBox: 0 0 497 579
+%%Magnification: 1.0000
+%%EndComments
+%%BeginProlog
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col32 {0.612 0.000 0.000 srgb} bind def
+/col33 {0.549 0.549 0.549 srgb} bind def
+/col34 {0.549 0.549 0.549 srgb} bind def
+/col35 {0.259 0.259 0.259 srgb} bind def
+/col36 {0.549 0.549 0.549 srgb} bind def
+/col37 {0.259 0.259 0.259 srgb} bind def
+/col38 {0.549 0.549 0.549 srgb} bind def
+/col39 {0.259 0.259 0.259 srgb} bind def
+/col40 {0.549 0.549 0.549 srgb} bind def
+/col41 {0.259 0.259 0.259 srgb} bind def
+/col42 {0.549 0.549 0.549 srgb} bind def
+/col43 {0.259 0.259 0.259 srgb} bind def
+
+end
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/rl {rlineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+/reencdict 12 dict def /ReEncode { reencdict begin
+/newcodesandnames exch def /newfontname exch def /basefontname exch def
+/basefontdict basefontname findfont def /newfont basefontdict maxlength dict def
+basefontdict { exch dup /FID ne { dup /Encoding eq
+{ exch dup length array copy newfont 3 1 roll put }
+{ exch newfont 3 1 roll put } ifelse } { pop pop } ifelse } forall
+newfont /FontName newfontname put newcodesandnames aload pop
+128 1 255 { newfont /Encoding get exch /.notdef put } for
+newcodesandnames length 2 idiv { newfont /Encoding get 3 1 roll put } repeat
+newfontname newfont definefont pop end } def
+/isovec [
+8#055 /minus 8#200 /grave 8#201 /acute 8#202 /circumflex 8#203 /tilde
+8#204 /macron 8#205 /breve 8#206 /dotaccent 8#207 /dieresis
+8#210 /ring 8#211 /cedilla 8#212 /hungarumlaut 8#213 /ogonek 8#214 /caron
+8#220 /dotlessi 8#230 /oe 8#231 /OE
+8#240 /space 8#241 /exclamdown 8#242 /cent 8#243 /sterling
+8#244 /currency 8#245 /yen 8#246 /brokenbar 8#247 /section 8#250 /dieresis
+8#251 /copyright 8#252 /ordfeminine 8#253 /guillemotleft 8#254 /logicalnot
+8#255 /hyphen 8#256 /registered 8#257 /macron 8#260 /degree 8#261 /plusminus
+8#262 /twosuperior 8#263 /threesuperior 8#264 /acute 8#265 /mu 8#266 /paragraph
+8#267 /periodcentered 8#270 /cedilla 8#271 /onesuperior 8#272 /ordmasculine
+8#273 /guillemotright 8#274 /onequarter 8#275 /onehalf
+8#276 /threequarters 8#277 /questiondown 8#300 /Agrave 8#301 /Aacute
+8#302 /Acircumflex 8#303 /Atilde 8#304 /Adieresis 8#305 /Aring
+8#306 /AE 8#307 /Ccedilla 8#310 /Egrave 8#311 /Eacute
+8#312 /Ecircumflex 8#313 /Edieresis 8#314 /Igrave 8#315 /Iacute
+8#316 /Icircumflex 8#317 /Idieresis 8#320 /Eth 8#321 /Ntilde 8#322 /Ograve
+8#323 /Oacute 8#324 /Ocircumflex 8#325 /Otilde 8#326 /Odieresis 8#327 /multiply
+8#330 /Oslash 8#331 /Ugrave 8#332 /Uacute 8#333 /Ucircumflex
+8#334 /Udieresis 8#335 /Yacute 8#336 /Thorn 8#337 /germandbls 8#340 /agrave
+8#341 /aacute 8#342 /acircumflex 8#343 /atilde 8#344 /adieresis 8#345 /aring
+8#346 /ae 8#347 /ccedilla 8#350 /egrave 8#351 /eacute
+8#352 /ecircumflex 8#353 /edieresis 8#354 /igrave 8#355 /iacute
+8#356 /icircumflex 8#357 /idieresis 8#360 /eth 8#361 /ntilde 8#362 /ograve
+8#363 /oacute 8#364 /ocircumflex 8#365 /otilde 8#366 /odieresis 8#367 /divide
+8#370 /oslash 8#371 /ugrave 8#372 /uacute 8#373 /ucircumflex
+8#374 /udieresis 8#375 /yacute 8#376 /thorn 8#377 /ydieresis] def
+/Courier-Oblique /Courier-Oblique-iso isovec ReEncode
+/Times-Roman /Times-Roman-iso isovec ReEncode
+ /DrawEllipse {
+	/endangle exch def
+	/startangle exch def
+	/yrad exch def
+	/xrad exch def
+	/y exch def
+	/x exch def
+	/savematrix mtrx currentmatrix def
+	x y tr xrad yrad sc 0 0 1 startangle endangle arc
+	closepath
+	savematrix setmatrix
+	} def
+
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+/pageheader {
+sa
+n 0 579 m 0 0 l 497 0 l 497 579 l cp clip
+-56.9 596.0 tr
+1 -1 sc
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+} bind def
+/pagefooter {
+$F2psEnd
+restore
+} bind def
+%%EndProlog
+pageheader
+%
+% Fig objects follow
+%
+% 
+% here starts figure with depth 50
+% Ellipse
+7.500 slw
+n 3238 1735 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 2408 3749 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 1708 5809 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 5848 1685 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 6128 7899 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 7568 4889 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 6008 3879 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 5418 2659 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 4268 3715 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 3208 5865 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 4178 6765 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 4558 7355 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 5208 7365 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 3708 7715 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 3038 7925 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 6568 5895 142 142 0 360 DrawEllipse gs col0 s gr
+% Polyline
+0 slj
+0 slc
+n 3900 8370 m 3600 8370 3600 9150 300 arcto 4 {pop} repeat
+  3600 9450 5670 9450 300 arcto 4 {pop} repeat
+  5970 9450 5970 8670 300 arcto 4 {pop} repeat
+  5970 8370 3900 8370 300 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 1215 4335 m 915 4335 915 5145 300 arcto 4 {pop} repeat
+  915 5445 2640 5445 300 arcto 4 {pop} repeat
+  2940 5445 2940 4635 300 arcto 4 {pop} repeat
+  2940 4335 1215 4335 300 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 1230 6345 m 930 6345 930 7155 300 arcto 4 {pop} repeat
+  930 7455 2655 7455 300 arcto 4 {pop} repeat
+  2955 7455 2955 6645 300 arcto 4 {pop} repeat
+  2955 6345 1230 6345 300 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 7050 6360 m 6750 6360 6750 7170 300 arcto 4 {pop} repeat
+  6750 7470 8475 7470 300 arcto 4 {pop} repeat
+  8775 7470 8775 6660 300 arcto 4 {pop} repeat
+  8775 6360 7050 6360 300 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 4125 4335 m 3825 4335 3825 5145 300 arcto 4 {pop} repeat
+  3825 5445 5550 5445 300 arcto 4 {pop} repeat
+  5850 5445 5850 4635 300 arcto 4 {pop} repeat
+  5850 4335 4125 4335 300 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 7050 2310 m 6750 2310 6750 3120 300 arcto 4 {pop} repeat
+  6750 3420 8475 3420 300 arcto 4 {pop} repeat
+  8775 3420 8775 2610 300 arcto 4 {pop} repeat
+  8775 2310 7050 2310 300 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 2775 2295 m 2475 2295 2475 3105 300 arcto 4 {pop} repeat
+  2475 3405 4200 3405 300 arcto 4 {pop} repeat
+  4500 3405 4500 2595 300 arcto 4 {pop} repeat
+  4500 2295 2775 2295 300 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 2775 285 m 2475 285 2475 1095 300 arcto 4 {pop} repeat
+  2475 1395 4200 1395 300 arcto 4 {pop} repeat
+  4500 1395 4500 585 300 arcto 4 {pop} repeat
+  4500 285 2775 285 300 arcto 4 {pop} repeat
+ cp gs col0 s gr % Ellipse
+n 4192 6338 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 3202 4507 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 3181 5161 142 142 0 360 DrawEllipse gs col0 s gr
+% Ellipse
+n 7709 7996 142 142 0 360 DrawEllipse gs col0 s gr
+% Arc
+15.000 slw
+1 slc
+gs  clippath
+2916 6717 m 2913 6696 l 3183 6599 l 3204 6717 l cp
+eoclip
+n 4837.5 16740.0 10215.6 -79.2098 -100.7902 arcn
+gs col0 s gr
+ gr
+% arrowhead
+0 slc
+n 3183 6599 m 2957 6699 l 3204 6717 l 3183 6599 l  cp gs 0.00 setgray ef gr  col0 s
+% Arc
+1 slc
+gs  clippath
+2914 7255 m 2915 7234 l 3199 7193 l 3195 7313 l cp
+eoclip
+n 3026.1 8399.8 1159.2 -1.4743 -95.0051 arcn
+gs col0 s gr
+ gr
+% arrowhead
+0 slc
+n 3199 7193 m 2957 7246 l 3195 7313 l 3199 7193 l  cp gs 0.00 setgray ef gr  col0 s
+% Arc
+1 slc
+gs  clippath
+6762 6561 m 6759 6582 l 6472 6596 l 6487 6477 l cp
+eoclip
+n 7663.1 -2028.8 8647.1 123.5832 96.0617 arcn
+gs col0 s gr
+ gr
+% arrowhead
+0 slc
+n 6472 6596 m 6718 6566 l 6487 6477 l 6472 6596 l  cp gs 0.00 setgray ef gr  col0 s
+% Arc
+1 slc
+gs  clippath
+8278 7455 m 8295 7468 l 8163 7723 l 8067 7650 l cp
+eoclip
+n 7717.5 7211.2 619.2 155.2976 24.7024 arcn
+gs col0 s gr
+ gr
+% arrowhead
+0 slc
+n 8163 7723 m 8260 7496 l 8067 7650 l 8163 7723 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+3431 2306 m 3410 2306 l 3360 2023 l 3480 2023 l cp
+eoclip
+n 3420 1395 m
+ 3420 2295 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 3360 2023 m 3420 2263 l 3480 2023 l 3360 2023 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+4830 4317 m 4818 4335 l 4555 4219 l 4622 4119 l cp
+eoclip
+n 3465 3420 m
+ 4815 4320 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 4555 4219 m 4788 4302 l 4622 4119 l 4555 4219 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+1901 6356 m 1880 6356 l 1830 6073 l 1950 6073 l cp
+eoclip
+n 1890 5445 m
+ 1890 6345 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 1830 6073 m 1890 6313 l 1950 6073 l 1830 6073 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+3750 8416 m 3734 8430 l 3511 8249 l 3602 8170 l cp
+eoclip
+n 2835 7380 m
+ 3735 8415 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 3511 8249 m 3714 8391 l 3602 8170 l 3511 8249 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+4715 5480 m 4736 5480 l 4785 5762 l 4665 5762 l cp
+eoclip
+n 4725 8370 m
+ 4725 5490 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 4785 5762 m 4725 5522 l 4665 5762 l 4785 5762 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+7330 3406 m 7349 3415 l 7271 3691 l 7163 3639 l cp
+eoclip
+n 4950 8370 m
+ 7335 3420 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 7271 3691 m 7321 3449 l 7163 3639 l 7271 3691 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+6761 6920 m 6761 6941 l 6478 6990 l 6478 6870 l cp
+eoclip
+n 2925 6930 m
+ 6750 6930 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 6478 6990 m 6718 6930 l 6478 6870 l 6478 6990 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+3914 5340 m 3930 5354 l 3775 5596 l 3686 5515 l cp
+eoclip
+n 2880 6480 m
+ 3915 5355 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 3775 5596 m 3893 5379 l 3686 5515 l 3775 5596 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+6761 2825 m 6761 2846 l 6478 2895 l 6478 2775 l cp
+eoclip
+n 4500 2835 m
+ 6750 2835 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 6478 2895 m 6718 2835 l 6478 2775 l 6478 2895 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+7730 3410 m 7751 3410 l 7800 3692 l 7680 3692 l cp
+eoclip
+n 7740 6345 m
+ 7740 3420 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 7800 3692 m 7740 3452 l 7680 3692 l 7800 3692 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+1886 4334 m 1876 4316 l 2092 4128 l 2154 4230 l cp
+eoclip
+n 3375 3420 m
+ 1890 4320 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 2092 4128 m 1918 4303 l 2154 4230 l 2092 4128 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+6840 3315 m 6855 3330 l 6690 3565 l 6605 3480 l cp
+eoclip
+n 5760 4410 m
+ 6840 3330 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 6690 3565 m 6817 3353 l 6605 3480 l 6690 3565 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+4486 860 m 4495 841 l 4773 911 l 4725 1020 l cp
+eoclip
+n 7740 2295 m
+ 4500 855 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 4773 911 m 4530 868 l 4725 1020 l 4773 911 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+5745 5355 m 5760 5340 l 5995 5505 l 5910 5590 l cp
+eoclip
+n 6840 6435 m
+ 5760 5355 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 5995 5505 m 5783 5378 l 5910 5590 l 5995 5505 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+6839 7365 m 6855 7379 l 6706 7624 l 6615 7545 l cp
+eoclip
+n 5895 8460 m
+ 6840 7380 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 6706 7624 m 6819 7404 l 6615 7545 l 6706 7624 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+1 slc
+gs  clippath
+3836 4670 m 3836 4691 l 3553 4740 l 3553 4620 l cp
+eoclip
+n 2925 4680 m
+ 3825 4680 l gs col0 s gr gr
+% arrowhead
+0 slc
+n 3553 4740 m 3793 4680 l 3553 4620 l 3553 4740 l  cp gs 0.00 setgray ef gr  col0 s
+/Courier-Oblique-iso ff 180.00 scf sf
+3157 1805 m
+gs 1 -1 sc (1) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+2327 3819 m
+gs 1 -1 sc (2) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+1627 5879 m
+gs 1 -1 sc (3) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+5767 1755 m
+gs 1 -1 sc (6) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+6047 7969 m
+gs 1 -1 sc (7) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+7487 4959 m
+gs 1 -1 sc (8) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+5882 3940 m
+gs 1 -1 sc (10) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+5292 2720 m
+gs 1 -1 sc (11) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+4142 3776 m
+gs 1 -1 sc (12) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+3082 5926 m
+gs 1 -1 sc (13) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+4052 6826 m
+gs 1 -1 sc (14) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+4432 7416 m
+gs 1 -1 sc (15) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+5127 7435 m
+gs 1 -1 sc (5) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+3582 7776 m
+gs 1 -1 sc (16) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+2957 7995 m
+gs 1 -1 sc (4) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+6487 5965 m
+gs 1 -1 sc (9) col0 sh gr
+/Times-Roman-iso ff 360.00 scf sf
+3870 9000 m
+gs 1 -1 sc (Operational) col0 sh gr
+/Times-Roman-iso ff 360.00 scf sf
+1620 4995 m
+gs 1 -1 sc (Init) col0 sh gr
+/Times-Roman-iso ff 360.00 scf sf
+1215 7020 m
+gs 1 -1 sc (Self-Test) col0 sh gr
+/Times-Roman-iso ff 360.00 scf sf
+7335 7020 m
+gs 1 -1 sc (Error) col0 sh gr
+/Times-Roman-iso ff 360.00 scf sf
+3915 4995 m
+gs 1 -1 sc (Fatal-Error) col0 sh gr
+/Times-Roman-iso ff 360.00 scf sf
+6930 2970 m
+gs 1 -1 sc (Shutdown) col0 sh gr
+/Times-Roman-iso ff 360.00 scf sf
+2655 2970 m
+gs 1 -1 sc (Power-On) col0 sh gr
+/Times-Roman-iso ff 360.00 scf sf
+2565 945 m
+gs 1 -1 sc (Power-Off) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+4066 6399 m
+gs 1 -1 sc (17) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+3076 4568 m
+gs 1 -1 sc (19) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+3055 5222 m
+gs 1 -1 sc (18) col0 sh gr
+/Courier-Oblique-iso ff 180.00 scf sf
+7612 8047 m
+gs 1 -1 sc (20) col0 sh gr
+% here ends figure;
+pagefooter
+showpage
+%%Trailer
+%EOF
diff --git a/libotr/libgcrypt-1.8.7/doc/fips-fsm.fig b/libotr/libgcrypt-1.8.7/doc/fips-fsm.fig
new file mode 100644
index 0000000..a4f0aec
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/fips-fsm.fig
@@ -0,0 +1,199 @@
+#FIG 3.2
+Portrait
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+0 32 #9c0000
+0 33 #8c8c8c
+0 34 #8c8c8c
+0 35 #424242
+0 36 #8c8c8c
+0 37 #424242
+0 38 #8c8c8c
+0 39 #424242
+0 40 #8c8c8c
+0 41 #424242
+0 42 #8c8c8c
+0 43 #424242
+6 900 270 8775 9450
+5 1 0 2 0 7 50 -1 -1 0.000 1 1 1 0 4837.500 16740.000 6750 6705 4725 6525 2925 6705
+	1 1 2.00 120.00 240.00
+5 1 0 2 0 7 50 -1 -1 0.000 1 1 1 0 3026.138 8399.825 4185 8370 3870 7605 2925 7245
+	1 1 2.00 120.00 240.00
+5 1 0 2 0 7 50 -1 -1 0.000 1 1 1 0 7663.125 -2028.750 2880 5175 4770 6120 6750 6570
+	1 1 2.00 120.00 240.00
+5 1 0 2 0 7 50 -1 -1 0.000 1 1 1 0 7717.500 7211.250 7155 7470 7740 7830 8280 7470
+	1 1 2.00 120.00 240.00
+6 3096 1593 3380 1877
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3238 1735 142 142 3238 1735 3103 1690
+4 0 0 50 -1 13 12 0.0000 4 105 105 3157 1805 1\001
+-6
+6 2266 3607 2550 3891
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 2408 3749 142 142 2408 3749 2273 3704
+4 0 0 50 -1 13 12 0.0000 4 105 105 2327 3819 2\001
+-6
+6 1566 5667 1850 5951
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1708 5809 142 142 1708 5809 1573 5764
+4 0 0 50 -1 13 12 0.0000 4 105 105 1627 5879 3\001
+-6
+6 5706 1543 5990 1827
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 5848 1685 142 142 5848 1685 5713 1640
+4 0 0 50 -1 13 12 0.0000 4 105 105 5767 1755 6\001
+-6
+6 5986 7757 6270 8041
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 6128 7899 142 142 6128 7899 5993 7854
+4 0 0 50 -1 13 12 0.0000 4 105 105 6047 7969 7\001
+-6
+6 7426 4747 7710 5031
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 7568 4889 142 142 7568 4889 7433 4844
+4 0 0 50 -1 13 12 0.0000 4 105 105 7487 4959 8\001
+-6
+6 5866 3737 6150 4021
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 6008 3879 142 142 6008 3879 5873 3834
+4 0 0 50 -1 13 12 0.0000 4 105 210 5882 3940 10\001
+-6
+6 5276 2517 5560 2801
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 5418 2659 142 142 5418 2659 5283 2614
+4 0 0 50 -1 13 12 0.0000 4 105 210 5292 2720 11\001
+-6
+6 4126 3573 4410 3857
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 4268 3715 142 142 4268 3715 4133 3670
+4 0 0 50 -1 13 12 0.0000 4 105 210 4142 3776 12\001
+-6
+6 3066 5723 3350 6007
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3208 5865 142 142 3208 5865 3073 5820
+4 0 0 50 -1 13 12 0.0000 4 105 210 3082 5926 13\001
+-6
+6 4036 6623 4320 6907
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 4178 6765 142 142 4178 6765 4043 6720
+4 0 0 50 -1 13 12 0.0000 4 105 210 4052 6826 14\001
+-6
+6 4416 7213 4700 7497
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 4558 7355 142 142 4558 7355 4423 7310
+4 0 0 50 -1 13 12 0.0000 4 105 210 4432 7416 15\001
+-6
+6 5066 7223 5350 7507
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 5208 7365 142 142 5208 7365 5073 7320
+4 0 0 50 -1 13 12 0.0000 4 105 105 5127 7435 5\001
+-6
+6 3566 7573 3850 7857
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3708 7715 142 142 3708 7715 3573 7670
+4 0 0 50 -1 13 12 0.0000 4 105 210 3582 7776 16\001
+-6
+6 2896 7783 3180 8067
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3038 7925 142 142 3038 7925 2903 7880
+4 0 0 50 -1 13 12 0.0000 4 105 105 2957 7995 4\001
+-6
+6 6426 5753 6710 6037
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 6568 5895 142 142 6568 5895 6433 5850
+4 0 0 50 -1 13 12 0.0000 4 105 105 6487 5965 9\001
+-6
+6 3600 8370 5985 9450
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+	 5970 9450 3600 9450 3600 8370 5970 8370 5970 9450
+4 0 0 50 -1 0 24 0.0000 4 330 1725 3870 9000 Operational\001
+-6
+6 900 4320 2970 5445
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+	 2940 5445 915 5445 915 4335 2940 4335 2940 5445
+4 0 0 50 -1 0 24 0.0000 4 240 510 1620 4995 Init\001
+-6
+6 900 6345 2970 7470
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+	 2955 7455 930 7455 930 6345 2955 6345 2955 7455
+4 0 0 50 -1 0 24 0.0000 4 255 1335 1215 7020 Self-Test\001
+-6
+6 6750 6345 8775 7470
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+	 8775 7470 6750 7470 6750 6360 8775 6360 8775 7470
+4 0 0 50 -1 0 24 0.0000 4 240 765 7335 7020 Error\001
+-6
+6 3825 4320 5850 5445
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+	 5850 5445 3825 5445 3825 4335 5850 4335 5850 5445
+4 0 0 50 -1 0 24 0.0000 4 255 1620 3915 4995 Fatal-Error\001
+-6
+6 6750 2295 8775 3420
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+	 8775 3420 6750 3420 6750 2310 8775 2310 8775 3420
+4 0 0 50 -1 0 24 0.0000 4 240 1455 6930 2970 Shutdown\001
+-6
+6 2475 2295 4500 3420
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+	 4500 3405 2475 3405 2475 2295 4500 2295 4500 3405
+4 0 0 50 -1 0 24 0.0000 4 240 1470 2655 2970 Power-On\001
+-6
+6 2475 270 4500 1395
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 20 0 0 5
+	 4500 1395 2475 1395 2475 285 4500 285 4500 1395
+4 0 0 50 -1 0 24 0.0000 4 240 1530 2565 945 Power-Off\001
+-6
+6 4050 6196 4334 6480
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 4192 6338 142 142 4192 6338 4057 6293
+4 0 0 50 -1 13 12 0.0000 4 105 210 4066 6399 17\001
+-6
+6 3053 4358 3351 4656
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3202 4507 142 142 3202 4507 3067 4462
+4 0 0 50 -1 13 12 0.0000 4 105 210 3076 4568 19\001
+-6
+6 3032 5012 3330 5310
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 3181 5161 142 142 3181 5161 3046 5116
+4 0 0 50 -1 13 12 0.0000 4 105 210 3055 5222 18\001
+-6
+6 7560 7847 7858 8145
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 7709 7996 142 142 7709 7996 7574 7951
+4 0 0 50 -1 13 12 0.0000 4 105 210 7612 8047 20\001
+-6
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 3420 1395 3420 2295
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 3465 3420 4815 4320
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 1890 5445 1890 6345
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 2835 7380 3735 8415
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 4725 8370 4725 5490
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 4950 8370 7335 3420
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 2925 6930 6750 6930
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 2880 6480 3915 5355
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 4500 2835 6750 2835
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 7740 6345 7740 3420
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 3375 3420 1890 4320
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 5760 4410 6840 3330
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 7740 2295 4500 855
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 6840 6435 5760 5355
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 5895 8460 6840 7380
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 1 0 2
+	1 1 2.00 120.00 240.00
+	 2925 4680 3825 4680
+-6
diff --git a/libotr/libgcrypt-1.8.7/doc/fips-fsm.pdf b/libotr/libgcrypt-1.8.7/doc/fips-fsm.pdf
new file mode 100644
index 0000000..d6d29da
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/fips-fsm.pdf
Binary files differdiff --git a/libotr/libgcrypt-1.8.7/doc/fips-fsm.png b/libotr/libgcrypt-1.8.7/doc/fips-fsm.png
new file mode 100644
index 0000000..e56aa75
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/fips-fsm.png
Binary files differdiff --git a/libotr/libgcrypt-1.8.7/doc/gcrypt.info b/libotr/libgcrypt-1.8.7/doc/gcrypt.info
new file mode 100644
index 0000000..5cf30f3
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/gcrypt.info
@@ -0,0 +1,133 @@
+This is gcrypt.info, produced by makeinfo version 6.5 from gcrypt.texi.
+
+This manual is for Libgcrypt (version 1.8.7, 30 July 2020), which is
+GNU's library of cryptographic building blocks.
+
+Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011, 2012
+Free Software Foundation, Inc.
+Copyright (C) 2012, 2013, 2016, 2017 g10 Code GmbH
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU General Public License as
+     published by the Free Software Foundation; either version 2 of the
+     License, or (at your option) any later version.  The text of the
+     license can be found in the section entitled "GNU General Public
+     License".
+INFO-DIR-SECTION GNU Libraries
+START-INFO-DIR-ENTRY
+* libgcrypt: (gcrypt).  Cryptographic function library.
+END-INFO-DIR-ENTRY
+
+
+Indirect:
+gcrypt.info-1: 835
+gcrypt.info-2: 301213
+
+Tag Table:
+(Indirect)
+Node: Top835
+Node: Introduction3361
+Node: Getting Started3733
+Node: Features4613
+Node: Overview5397
+Node: Preparation6020
+Node: Header6943
+Node: Building sources8014
+Node: Building sources using Automake9931
+Node: Initializing the library11859
+Ref: sample-use-suspend-secmem15251
+Ref: sample-use-resume-secmem16094
+Node: Multi-Threading16997
+Ref: Multi-Threading-Footnote-118176
+Node: Enabling FIPS mode18585
+Ref: enabling fips mode18766
+Node: Hardware features20578
+Ref: hardware features20745
+Ref: Hardware features-Footnote-121826
+Node: Generalities21987
+Node: Controlling the library22246
+Node: Error Handling40417
+Node: Error Values42956
+Node: Error Sources47896
+Node: Error Codes50164
+Node: Error Strings53640
+Node: Handler Functions54824
+Node: Progress handler55383
+Node: Allocation handler57532
+Node: Error handler59078
+Node: Logging handler60644
+Node: Symmetric cryptography61236
+Node: Available ciphers61976
+Node: Available cipher modes64657
+Node: Working with cipher handles68510
+Node: General cipher functions80014
+Node: Public Key cryptography83540
+Node: Available algorithms84306
+Node: Used S-expressions84655
+Node: RSA key parameters85772
+Node: DSA key parameters87047
+Node: ECC key parameters87701
+Ref: ecc_keyparam87852
+Node: Cryptographic Functions89723
+Node: General public-key related Functions101570
+Node: Hashing115239
+Node: Available hash algorithms115972
+Node: Working with hash algorithms121935
+Node: Message Authentication Codes136067
+Node: Available MAC algorithms136735
+Node: Working with MAC algorithms141897
+Node: Key Derivation147885
+Node: Random Numbers150287
+Node: Quality of random numbers150570
+Node: Retrieving random numbers151253
+Node: S-expressions152742
+Node: Data types for S-expressions153387
+Node: Working with S-expressions153713
+Node: MPI library167423
+Node: Data types168445
+Node: Basic functions168754
+Node: MPI formats171218
+Node: Calculations174742
+Node: Comparisons177011
+Node: Bit manipulations178014
+Node: EC functions179336
+Ref: gcry_mpi_ec_new182285
+Node: Miscellaneous187844
+Node: Prime numbers191988
+Node: Generation192258
+Node: Checking193545
+Node: Utilities193955
+Node: Memory allocation194332
+Node: Context management195688
+Ref: gcry_ctx_release196126
+Node: Buffer description196287
+Node: Config reporting197074
+Node: Tools198024
+Node: hmac256198191
+Node: Configuration199197
+Node: Architecture202250
+Ref: fig:subsystems203774
+Ref: Architecture-Footnote-1204860
+Ref: Architecture-Footnote-2204922
+Node: Public-Key Subsystem Architecture205006
+Node: Symmetric Encryption Subsystem Architecture207284
+Node: Hashing and MACing Subsystem Architecture208730
+Node: Multi-Precision-Integer Subsystem Architecture210653
+Node: Prime-Number-Generator Subsystem Architecture212091
+Ref: Prime-Number-Generator Subsystem Architecture-Footnote-1214022
+Node: Random-Number Subsystem Architecture214313
+Node: CSPRNG Description217262
+Ref: CSPRNG Description-Footnote-1218818
+Node: FIPS PRNG Description218941
+Node: Self-Tests221075
+Node: FIPS Mode232534
+Ref: fig:fips-fsm236360
+Ref: tbl:fips-states236463
+Ref: tbl:fips-state-transitions237715
+Node: Library Copying241336
+Node: Copying269442
+Node: Figures and Tables288618
+Node: Concept Index289043
+Node: Function and Data Index301213
+
+End Tag Table
diff --git a/libotr/libgcrypt-1.8.7/doc/gcrypt.info-1 b/libotr/libgcrypt-1.8.7/doc/gcrypt.info-1
new file mode 100644
index 0000000..145d74a
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/gcrypt.info-1
@@ -0,0 +1,7020 @@
+This is gcrypt.info, produced by makeinfo version 6.5 from gcrypt.texi.
+
+This manual is for Libgcrypt (version 1.8.7, 30 July 2020), which is
+GNU's library of cryptographic building blocks.
+
+Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011, 2012
+Free Software Foundation, Inc.
+Copyright (C) 2012, 2013, 2016, 2017 g10 Code GmbH
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU General Public License as
+     published by the Free Software Foundation; either version 2 of the
+     License, or (at your option) any later version.  The text of the
+     license can be found in the section entitled "GNU General Public
+     License".
+INFO-DIR-SECTION GNU Libraries
+START-INFO-DIR-ENTRY
+* libgcrypt: (gcrypt).  Cryptographic function library.
+END-INFO-DIR-ENTRY
+
+
+File: gcrypt.info,  Node: Top,  Next: Introduction,  Up: (dir)
+
+The Libgcrypt Library
+*********************
+
+This manual is for Libgcrypt (version 1.8.7, 30 July 2020), which is
+GNU's library of cryptographic building blocks.
+
+Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011, 2012
+Free Software Foundation, Inc.
+Copyright (C) 2012, 2013, 2016, 2017 g10 Code GmbH
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU General Public License as
+     published by the Free Software Foundation; either version 2 of the
+     License, or (at your option) any later version.  The text of the
+     license can be found in the section entitled "GNU General Public
+     License".
+
+* Menu:
+
+* Introduction::                 What is Libgcrypt.
+* Preparation::                  What you should do before using the library.
+* Generalities::                 General library functions and data types.
+* Handler Functions::            Working with handler functions.
+* Symmetric cryptography::       How to use symmetric cryptography.
+* Public Key cryptography::      How to use public key cryptography.
+* Hashing::                      How to use hash algorithms.
+* Message Authentication Codes:: How to use MAC algorithms.
+* Key Derivation::               How to derive keys from strings
+* Random Numbers::               How to work with random numbers.
+* S-expressions::                How to manage S-expressions.
+* MPI library::                  How to work with multi-precision-integers.
+* Prime numbers::                How to use the Prime number related functions.
+* Utilities::                    Utility functions.
+* Tools::                        Utility tools.
+* Configuration::                Configuration files and environment variables.
+* Architecture::                 How Libgcrypt works internally.
+
+Appendices
+
+* 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
+                                can copy and share some parts of Libgcrypt.
+
+Indices
+
+* Figures and Tables::          Index of figures and tables.
+* Concept Index::               Index of concepts and programs.
+* Function and Data Index::     Index of functions, variables and data types.
+
+
+File: gcrypt.info,  Node: Introduction,  Next: Preparation,  Prev: Top,  Up: Top
+
+1 Introduction
+**************
+
+Libgcrypt is a library providing cryptographic building blocks.
+
+* Menu:
+
+* Getting Started::             How to use this manual.
+* Features::                    A glance at Libgcrypt's features.
+* Overview::                    Overview about the library.
+
+
+File: gcrypt.info,  Node: Getting Started,  Next: Features,  Up: Introduction
+
+1.1 Getting Started
+===================
+
+This manual documents the Libgcrypt library application programming
+interface (API). All functions and data types provided by the library
+are explained.
+
+The reader is assumed to possess basic knowledge about applied
+cryptography.
+
+   This manual can be used in several ways.  If read from the beginning
+to the end, it gives a good introduction into the library and how it can
+be used in an application.  Forward references are included where
+necessary.  Later on, the manual can be used as a reference manual to
+get just the information needed about any particular interface of the
+library.  Experienced programmers might want to start looking at the
+examples at the end of the manual, and then only read up those parts of
+the interface which are unclear.
+
+
+File: gcrypt.info,  Node: Features,  Next: Overview,  Prev: Getting Started,  Up: Introduction
+
+1.2 Features
+============
+
+Libgcrypt might have a couple of advantages over other libraries doing a
+similar job.
+
+It's Free Software
+     Anybody can use, modify, and redistribute it under the terms of the
+     GNU Lesser General Public License (*note Library Copying::).  Note,
+     that some parts (which are in general not needed by applications)
+     are subject to the terms of the GNU General Public License (*note
+     Copying::); please see the README file of the distribution for of
+     list of these parts.
+
+It encapsulates the low level cryptography
+     Libgcrypt provides a high level interface to cryptographic building
+     blocks using an extensible and flexible API.
+
+
+File: gcrypt.info,  Node: Overview,  Prev: Features,  Up: Introduction
+
+1.3 Overview
+============
+
+The Libgcrypt library is fully thread-safe, where it makes sense to be
+thread-safe.  Not thread-safe are some cryptographic functions that
+modify a certain context stored in handles.  If the user really intents
+to use such functions from different threads on 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 some
+common code used by other GnuPG components.
+
+
+File: gcrypt.info,  Node: Preparation,  Next: Generalities,  Prev: Introduction,  Up: Top
+
+2 Preparation
+*************
+
+To use Libgcrypt, you have to perform some changes to your sources and
+the build system.  The necessary changes are small and explained in the
+following sections.  At the end of this chapter, it is described how the
+library is initialized, and how the requirements of the library are
+verified.
+
+* Menu:
+
+* Header::                      What header file you need to include.
+* Building sources::            How to build sources using the library.
+* Building sources using Automake::  How to build sources with the help of Automake.
+* Initializing the library::    How to initialize the library.
+* Multi-Threading::             How Libgcrypt can be used in a MT environment.
+* Enabling FIPS mode::          How to enable the FIPS mode.
+* Hardware features::           How to disable hardware features.
+
+
+File: gcrypt.info,  Node: Header,  Next: Building sources,  Up: Preparation
+
+2.1 Header
+==========
+
+All interfaces (data types and functions) of the library are defined in
+the header file 'gcrypt.h'.  You must include this in all source files
+using the library, either directly or through some other header file,
+like this:
+
+     #include <gcrypt.h>
+
+   The name space of Libgcrypt is 'gcry_*' for function and type names
+and 'GCRY*' for other symbols.  In addition the same name prefixes with
+one prepended underscore are reserved for internal use and should never
+be used by an application.  Note that Libgcrypt uses libgpg-error, which
+uses 'gpg_*' as name space for function and type names and 'GPG_*' for
+other symbols, including all the error codes.
+
+Certain parts of gcrypt.h may be excluded by defining these macros:
+
+'GCRYPT_NO_MPI_MACROS'
+     Do not define the shorthand macros 'mpi_*' for 'gcry_mpi_*'.
+
+'GCRYPT_NO_DEPRECATED'
+     Do not include definitions for deprecated features.  This is useful
+     to make sure that no deprecated features are used.
+
+
+File: gcrypt.info,  Node: Building sources,  Next: Building sources using Automake,  Prev: Header,  Up: Preparation
+
+2.2 Building sources
+====================
+
+If you want to compile a source file including the 'gcrypt.h' header
+file, you must make sure that the compiler can find it in the directory
+hierarchy.  This is accomplished by adding the path to the directory in
+which the header file is located to the compilers include file search
+path (via the '-I' option).
+
+   However, the path to the include file is determined at the time the
+source is configured.  To solve this problem, Libgcrypt ships with a
+small helper program 'libgcrypt-config' that knows the path to the
+include file and other configuration options.  The options that need to
+be added to the compiler invocation at compile time are output by the
+'--cflags' option to 'libgcrypt-config'.  The following example shows
+how it can be used at the command line:
+
+     gcc -c foo.c `libgcrypt-config --cflags`
+
+   Adding the output of '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,
+the path to the library files has to be added to the library search path
+(via the '-L' option).  For this, the option '--libs' to
+'libgcrypt-config' can be used.  For convenience, this option also
+outputs all other options that are required to link the program with the
+Libgcrypt libraries (in particular, the '-lgcrypt' option).  The example
+shows how to link 'foo.o' with the Libgcrypt library to a program 'foo'.
+
+     gcc -o foo foo.o `libgcrypt-config --libs`
+
+   Of course you can also combine both examples to a single command by
+specifying both options to 'libgcrypt-config':
+
+     gcc -o foo foo.c `libgcrypt-config --cflags --libs`
+
+
+File: gcrypt.info,  Node: Building sources using Automake,  Next: Initializing the library,  Prev: Building sources,  Up: Preparation
+
+2.3 Building sources using Automake
+===================================
+
+It is much easier if you use GNU Automake instead of writing your own
+Makefiles.  If you do that, you do not have to worry about finding and
+invoking the 'libgcrypt-config' script at all.  Libgcrypt provides an
+extension to Automake that does all the work for you.
+
+ -- Macro: AM_PATH_LIBGCRYPT ([MINIMUM-VERSION], [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     Check whether Libgcrypt (at least version MINIMUM-VERSION, if
+     given) exists on the host system.  If it is found, execute
+     ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given.
+
+     Additionally, the function defines 'LIBGCRYPT_CFLAGS' to the flags
+     needed for compilation of the program to find the 'gcrypt.h' header
+     file, and 'LIBGCRYPT_LIBS' to the linker 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 'libgcrypt' is appended to the variable
+     'gpg_config_script_warn'.
+
+     This macro searches for 'libgcrypt-config' along the PATH. If you
+     are cross-compiling, it is useful to set the environment variable
+     'SYSROOT' to the top directory of your target.  The macro will then
+     first look for the helper program in the 'bin' directory below that
+     top directory.  An absolute directory name must be used for
+     'SYSROOT'.  Finally, if the configure command line option
+     '--with-libgcrypt-prefix' is used, only its value is used for the
+     top directory below which the helper script is expected.
+
+   You can use the defined Autoconf variables like this in your
+'Makefile.am':
+
+     AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
+     LDADD = $(LIBGCRYPT_LIBS)
+
+
+File: gcrypt.info,  Node: Initializing the library,  Next: Multi-Threading,  Prev: Building sources using Automake,  Up: Preparation
+
+2.4 Initializing the library
+============================
+
+Before the library can be used, it must initialize itself.  This is
+achieved by invoking the function 'gcry_check_version' described below.
+
+   Also, it is often desirable to check that the version of Libgcrypt
+used is indeed one which fits all requirements.  Even with binary
+compatibility, new features may have been introduced, but due to problem
+with the dynamic linker an old version may actually be used.  So you may
+want to check that the version is okay right after program startup.
+
+ -- Function: const char * gcry_check_version (const char *REQ_VERSION)
+
+     The function 'gcry_check_version' initializes some subsystems used
+     by Libgcrypt and must be invoked before any other function in the
+     library.  *Note Multi-Threading::.
+
+     Furthermore, this function returns the version number of the
+     library.  It can also verify that the version number is higher than
+     a certain required version number REQ_VERSION, if this value is not
+     a null pointer.
+
+   Libgcrypt uses a concept known as secure memory, which is a region of
+memory set aside for storing sensitive data.  Because such memory is a
+scarce resource, it needs to be setup in advanced to a fixed size.
+Further, most operating systems have special requirements on how that
+secure memory can be used.  For example, it might be required to install
+an application as "setuid(root)" to allow allocating such memory.
+Libgcrypt requires a sequence of initialization steps to make sure that
+this works correctly.  The following examples show the necessary steps.
+
+   If you don't have a need for secure memory, for example if your
+application does not use secret keys or other confidential data or it
+runs in a controlled environment where key material floating around in
+memory is not a problem, you should initialize Libgcrypt this way:
+
+       /* Version check should be the very first call because it
+          makes sure that important subsystems are initialized.
+          #define NEED_LIBGCRYPT_VERSION to the minimum required version. */
+       if (!gcry_check_version (NEED_LIBGCRYPT_VERSION))
+         {
+           fprintf (stderr, "libgcrypt is too old (need %s, have %s)\n",
+              NEED_LIBGCRYPT_VERSION, gcry_check_version (NULL));
+           exit (2);
+         }
+
+       /* Disable secure memory.  */
+       gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
+
+       /* ... If required, other initialization goes here.  */
+
+       /* Tell Libgcrypt that initialization has completed. */
+       gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
+
+   If you have to protect your keys or other information in memory
+against being swapped out to disk and to enable an automatic overwrite
+of used and freed memory, you need to initialize Libgcrypt this way:
+
+       /* Version check should be the very first call because it
+          makes sure that important subsystems are initialized.
+          #define NEED_LIBGCRYPT_VERSION to the minimum required version. */
+       if (!gcry_check_version (NEED_LIBGCRYPT_VERSION))
+         {
+           fprintf (stderr, "libgcrypt is too old (need %s, have %s)\n",
+              NEED_LIBGCRYPT_VERSION, gcry_check_version (NULL));
+           exit (2);
+         }
+
+       /* We don't want to see any warnings, e.g. because we have not yet
+          parsed program options which might be used to suppress such
+          warnings. */
+       gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
+
+       /* ... If required, other initialization goes here.  Note that the
+          process might still be running with increased privileges and that
+          the secure memory has not been initialized.  */
+
+       /* 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);
+
+       /* 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.  */
+
+       /* Tell Libgcrypt that initialization has completed. */
+       gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
+
+   It is important that these initialization steps are not done by a
+library but by the actual application.  A library using Libgcrypt might
+want to check for finished initialization using:
+
+       if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))
+         {
+           fputs ("libgcrypt has not been initialized\n", stderr);
+           abort ();
+         }
+
+   Instead of terminating the process, the library may instead print a
+warning and try to initialize Libgcrypt itself.  See also the section on
+multi-threading below for more pitfalls.
+
+
+File: gcrypt.info,  Node: Multi-Threading,  Next: Enabling FIPS mode,  Prev: Initializing the library,  Up: Preparation
+
+2.5 Multi-Threading
+===================
+
+As mentioned earlier, the Libgcrypt library is thread-safe if you adhere
+to the following requirements:
+
+   * 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.
+
+   * The function 'gcry_check_version' must be called before any other
+     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 'gcry_check_version' before creating the other
+     threads using Libgcrypt(1).
+
+   * Just like the function 'gpg_strerror', the function 'gcry_strerror'
+     is not thread safe.  You have to use 'gpg_strerror_r' instead.
+
+   ---------- Footnotes ----------
+
+   (1) At least this is true for POSIX threads, as 'pthread_create' is a
+function that synchronizes memory with respects to other threads.  There
+are many functions which have this property, a complete list can be
+found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the
+definition of the term "Memory Synchronization".  For other thread
+packages, more relaxed or more strict rules may apply.
+
+
+File: gcrypt.info,  Node: Enabling FIPS mode,  Next: Hardware features,  Prev: Multi-Threading,  Up: Preparation
+
+2.6 How to enable the 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 <http://csrc.nist.gov/groups/STM/cmvp/> to see what
+versions of Libgcrypt are approved.
+
+   Because FIPS 140 has certain restrictions on the use of cryptography
+which are not always wanted, Libgcrypt needs to be put into FIPS mode
+explicitly.  Three alternative mechanisms are provided to switch
+Libgcrypt into this mode:
+
+   * If the file '/proc/sys/crypto/fips_enabled' exists and contains a
+     numeric value other than '0', Libgcrypt is put into FIPS mode at
+     initialization time.  Obviously this works only on systems with a
+     'proc' file system (i.e.  GNU/Linux).
+
+   * If the 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.
+
+   * If the application requests FIPS mode using the control command
+     'GCRYCTL_FORCE_FIPS_MODE'.  This must be done prior to any
+     initialization (i.e.  before 'gcry_check_version').
+
+   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
+'/etc/gcrypt/fips_enabled' or by using the control command
+'GCRYCTL_SET_ENFORCED_FIPS_FLAG' before any other calls to libgcrypt.
+The Enforced FIPS mode helps to detect applications which don't fulfill
+all requirements for using Libgcrypt in FIPS mode (*note 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 self-tests are logged.
+
+
+File: gcrypt.info,  Node: Hardware features,  Prev: Enabling FIPS mode,  Up: Preparation
+
+2.7 How to disable 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
+are
+
+'padlock-rng'
+'padlock-aes'
+'padlock-sha'
+'padlock-mmul'
+'intel-cpu'
+'intel-fast-shld'
+'intel-bmi2'
+'intel-ssse3'
+'intel-pclmul'
+'intel-aesni'
+'intel-rdrand'
+'intel-avx'
+'intel-avx2'
+'intel-rdtsc'
+'arm-neon'
+
+   To disable a feature for all processes using Libgcrypt 1.6 or newer,
+create the file '/etc/gcrypt/hwf.deny' and put each feature not to be
+used on a single line.  Empty lines, white space, and lines prefixed
+with a hash mark are ignored.  The file should be world readable.
+
+   To disable a feature specifically for a program that program must
+tell it Libgcrypt before before calling 'gcry_check_version'.
+Example:(1)
+
+       gcry_control (GCRYCTL_DISABLE_HWF, "intel-rdrand", NULL);
+
+To print the list of active features you may use this command:
+
+       mpicalc --print-config | grep ^hwflist: | tr : '\n' | tail -n +2
+
+   ---------- Footnotes ----------
+
+   (1) NB. Libgcrypt uses the RDRAND feature only as one source of
+entropy.  A CPU with a broken RDRAND will thus not compromise of the
+random number generator
+
+
+File: gcrypt.info,  Node: Generalities,  Next: Handler Functions,  Prev: Preparation,  Up: Top
+
+3 Generalities
+**************
+
+* Menu:
+
+* Controlling the library::     Controlling Libgcrypt's behavior.
+* Error Handling::              Error codes and such.
+
+
+File: gcrypt.info,  Node: Controlling the library,  Next: Error Handling,  Up: Generalities
+
+3.1 Controlling the library
+===========================
+
+ -- Function: gcry_error_t gcry_control (enum gcry_ctl_cmds CMD, ...)
+
+     This function can be used to influence the general behavior of
+     Libgcrypt in several ways.  Depending on CMD, more arguments can or
+     have to be provided.
+
+     '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 before 'gcry_check_version'.  Note that the memory guard
+          is NOT used when the user of the library has set his own
+          memory management callbacks.
+
+     'GCRYCTL_ENABLE_QUICK_RANDOM; Arguments: none'
+          This command inhibits the use the very secure random quality
+          level ('GCRY_VERY_STRONG_RANDOM') and degrades all request
+          down to 'GCRY_STRONG_RANDOM'.  In general this is not
+          recommended.  However, for some applications the extra quality
+          random Libgcrypt tries to create is not justified and this
+          option may help to get better performance.  Please check with
+          a crypto expert whether this option can be used for your
+          application.
+
+          This option can only be used at initialization time.
+
+     'GCRYCTL_DUMP_RANDOM_STATS; Arguments: none'
+          This command dumps random number generator related statistics
+          to the library's logging stream.
+
+     'GCRYCTL_DUMP_MEMORY_STATS; Arguments: none'
+          This command dumps memory management related statistics to the
+          library's logging stream.
+
+     'GCRYCTL_DUMP_SECMEM_STATS; Arguments: none'
+          This command dumps secure memory management related statistics
+          to the library's logging stream.
+
+     'GCRYCTL_DROP_PRIVS; Arguments: none'
+          This command disables the use of secure memory and drops the
+          privileges of the current process.  This command has not much
+          use; the suggested way to disable secure memory is to use
+          'GCRYCTL_DISABLE_SECMEM' right after initialization.
+
+     'GCRYCTL_DISABLE_SECMEM; Arguments: none'
+          This command disables the use of secure memory.  If this
+          command is used in FIPS mode, FIPS mode will be disabled and
+          the function 'gcry_fips_mode_active' returns false.  However,
+          in Enforced FIPS mode this command has no effect at all.
+
+          Many applications do not require secure memory, so they should
+          disable it right away.  This command should be executed right
+          after 'gcry_check_version'.
+
+     'GCRYCTL_DISABLE_LOCKED_SECMEM; Arguments: none'
+          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 '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).
+
+     'GCRYCTL_DISABLE_PRIV_DROP; Arguments: none'
+          This command sets a global flag to tell the secure memory
+          subsystem that it shall not drop privileges after secure
+          memory has been allocated.  This command is commonly used
+          right after 'gcry_check_version' but may also be used right
+          away at program startup.  It won't have an effect after the
+          secure memory pool has been initialized.  WARNING: A process
+          running setuid(root) is a severe security risk.  Processes
+          making use of Libgcrypt or other complex code should drop
+          these extra privileges as soon as possible.  If this command
+          has been used the caller is responsible for dropping the
+          privileges.
+
+     '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 NBYTES is 0, secure memory will be
+          disabled.  The minimum amount of secure memory allocated is
+          currently 16384 bytes; you may thus use a value of 1 to
+          request that default size.
+
+     '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.  If the secure memory pool as already
+          been destroyed, this command has no effect.  Applications
+          might want to run this command from their exit handler to make
+          sure that the secure memory gets properly destroyed.  This
+          command is not necessarily thread-safe but that should not be
+          needed in cleanup code.  It may be called from a signal
+          handler.
+
+     'GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none'
+          Disable warning messages about problems with the secure memory
+          subsystem.  This command should be run right after
+          'gcry_check_version'.
+
+     'GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none'
+          Postpone warning messages from the secure memory subsystem.
+          *Note the initialization example: sample-use-suspend-secmem,
+          on how to use it.
+
+     'GCRYCTL_RESUME_SECMEM_WARN; Arguments: none'
+          Resume warning messages from the secure memory subsystem.
+          *Note the initialization example: sample-use-resume-secmem, on
+          how to use it.
+
+     'GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none'
+          This command tells the PRNG to store random numbers in secure
+          memory.  This command should be run right after
+          'gcry_check_version' and not later than the command
+          GCRYCTL_INIT_SECMEM. Note that in FIPS mode the secure memory
+          is always used.
+
+     'GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename'
+          This command specifies the file, which is to be used as seed
+          file for the PRNG. If the seed file is registered prior to
+          initialization of the PRNG, the seed file's content (if it
+          exists and seems to be valid) is fed into the PRNG pool.
+          After the seed file has been registered, the PRNG can be
+          signalled to write out the PRNG pool's content into the seed
+          file with the following command.
+
+     'GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none'
+          Write out the PRNG pool's content into the registered seed
+          file.
+
+          Multiple instances of the applications sharing the same random
+          seed file can be started in parallel, in which case they will
+          read out the same pool and then race for updating it (the last
+          update overwrites earlier updates).  They will differentiate
+          only by the weak entropy that is added in read_seed_file based
+          on the PID and clock, and up to 16 bytes of weak random
+          non-blockingly.  The consequence is that the output of these
+          different instances is correlated to some extent.  In a
+          perfect attack scenario, the attacker can control (or at least
+          guess) the PID and clock of the application, and drain the
+          system's entropy pool to reduce the "up to 16 bytes" above to
+          0.  Then the dependencies of the initial states of the pools
+          are completely known.  Note that this is not an issue if
+          random of 'GCRY_VERY_STRONG_RANDOM' quality is requested as in
+          this case enough extra entropy gets mixed.  It is also not an
+          issue when using Linux (rndlinux driver), because this one
+          guarantees to read full 16 bytes from /dev/urandom and thus
+          there is no way for an attacker without kernel access to
+          control these 16 bytes.
+
+     'GCRYCTL_CLOSE_RANDOM_DEVICE; Arguments: none'
+          Try to close the random device.  If on Unix system you call
+          fork(), the child process does no call exec(), and you do not
+          intend to use Libgcrypt in the child, it might be useful to
+          use this control code to close the inherited file descriptors
+          of the random device.  If Libgcrypt is later used again by the
+          child, the device will be re-opened.  On non-Unix systems this
+          control code is ignored.
+
+     'GCRYCTL_SET_VERBOSITY; Arguments: int level'
+          This command sets the verbosity of the logging.  A level of 0
+          disables all extra logging whereas positive numbers enable
+          more verbose logging.  The level may be changed at any time
+          but be aware that no memory synchronization is done so the
+          effect of this command might not immediately show up in other
+          threads.  This command may even be used prior to
+          'gcry_check_version'.
+
+     'GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags'
+          Set the debug flag bits as given by the argument.  Be aware
+          that that no memory synchronization is done so the effect of
+          this command might not immediately show up in other threads.
+          The debug flags are not considered part of the API and thus
+          may change without notice.  As of now bit 0 enables debugging
+          of cipher functions and bit 1 debugging of
+          multi-precision-integers.  This command may even be used prior
+          to 'gcry_check_version'.
+
+     'GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags'
+          Set the debug flag bits as given by the argument.  Be aware
+          that that no memory synchronization is done so the effect of
+          this command might not immediately show up in other threads.
+          This command may even be used prior to 'gcry_check_version'.
+
+     'GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none'
+          This command does nothing.  It exists only for backward
+          compatibility.
+
+     'GCRYCTL_ANY_INITIALIZATION_P; Arguments: none'
+          This command returns true if the library has been basically
+          initialized.  Such a basic initialization happens implicitly
+          with many commands to get certain internal subsystems running.
+          The common and suggested way to do this basic initialization
+          is by calling gcry_check_version.
+
+     'GCRYCTL_INITIALIZATION_FINISHED; Arguments: none'
+          This command tells the library that the application has
+          finished the initialization.
+
+     'GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none'
+          This command returns true if the command
+          GCRYCTL_INITIALIZATION_FINISHED has already been run.
+
+     'GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops'
+          This command is obsolete since version 1.6.
+
+     'GCRYCTL_FAST_POLL; Arguments: none'
+          Run a fast random poll.
+
+     'GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename'
+          This command may be used to override the default name of the
+          EGD socket to connect to.  It may be used only during
+          initialization as it is not thread safe.  Changing the socket
+          name again is not supported.  The function may return an error
+          if the given filename is too long for a local socket name.
+
+          EGD is an alternative random gatherer, used only on systems
+          lacking a proper random device.
+
+     'GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream'
+          This command dumps information pertaining to the configuration
+          of the library to the given stream.  If NULL is given for
+          STREAM, the log system is used.  This command may be used
+          before the initialization has been finished but not before a
+          'gcry_check_version'.  Note that the macro 'estream_t' can be
+          used instead of 'gpgrt_stream_t'.
+
+     'GCRYCTL_OPERATIONAL_P; Arguments: none'
+          This command returns true if the library is in an operational
+          state.  This information makes only sense in FIPS mode.  In
+          contrast to other functions, this is a pure test function and
+          won't put the library into FIPS mode or change the internal
+          state.  This command may be used before the initialization has
+          been finished but not before a 'gcry_check_version'.
+
+     'GCRYCTL_FIPS_MODE_P; Arguments: none'
+          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
+          initialization has been finished but not before a
+          'gcry_check_version'.  An application may use this command or
+          the convenience macro below to check whether FIPS mode is
+          actually active.
+
+           -- Function: int gcry_fips_mode_active (void)
+
+               Returns true if the FIPS mode is active.  Note that this
+               is implemented as a macro.
+
+     'GCRYCTL_FORCE_FIPS_MODE; Arguments: none'
+          Running this command puts the library into FIPS mode.  If the
+          library is 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
+          reject an attempt to switch to fips mode during or after the
+          initialization.
+
+     'GCRYCTL_SET_ENFORCED_FIPS_FLAG; Arguments: none'
+          Running this command sets the internal flag that puts the
+          library into the enforced FIPS mode during the FIPS mode
+          initialization.  This command does not affect the library if
+          the library is not put into the FIPS mode and it must be used
+          before any other libgcrypt library calls that initialize the
+          library such as 'gcry_check_version'.  Note that Libgcrypt
+          will reject an attempt to switch to the enforced fips mode
+          during or after the initialization.
+
+     'GCRYCTL_SET_PREFERRED_RNG_TYPE; Arguments: int'
+          These are advisory commands to select a certain random number
+          generator.  They are only advisory because libraries may not
+          know what an application actually wants or vice versa.  Thus
+          Libgcrypt employs a priority check to select the actually used
+          RNG. If an applications selects a lower priority RNG but a
+          library requests a higher priority RNG Libgcrypt will switch
+          to the higher priority RNG. Applications and libraries should
+          use these control codes before 'gcry_check_version'.  The
+          available generators are:
+          'GCRY_RNG_TYPE_STANDARD'
+               A conservative standard generator based on the
+               "Continuously Seeded Pseudo Random Number Generator"
+               designed by Peter Gutmann.
+          'GCRY_RNG_TYPE_FIPS'
+               A deterministic random number generator conforming to he
+               document "NIST-Recommended Random Number Generator Based
+               on ANSI X9.31 Appendix A.2.4 Using the 3-Key Triple DES
+               and AES Algorithms" (2005-01-31).  This implementation
+               uses the AES variant.
+          'GCRY_RNG_TYPE_SYSTEM'
+               A wrapper around the system's native RNG. On Unix system
+               these are usually the /dev/random and /dev/urandom
+               devices.
+          The default is 'GCRY_RNG_TYPE_STANDARD' unless FIPS mode as
+          been enabled; in which case 'GCRY_RNG_TYPE_FIPS' is used and
+          locked against further changes.
+
+     '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.
+
+     'GCRYCTL_SELFTEST; Arguments: none'
+          This may be used at anytime to have the library run all
+          implemented self-tests.  It works in standard and in FIPS
+          mode.  Returns 0 on success or an error code on failure.
+
+     'GCRYCTL_DISABLE_HWF; Arguments: const char *name'
+
+          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.  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 'gcry_check_version'.
+
+     '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.
+
+
+File: gcrypt.info,  Node: Error Handling,  Prev: Controlling the library,  Up: Generalities
+
+3.2 Error Handling
+==================
+
+Many functions in Libgcrypt can return an error if they fail.  For this
+reason, the application should always catch the error condition and take
+appropriate measures, for example by releasing the resources and passing
+the error up to the caller, or by displaying a descriptive message to
+the user and cancelling the operation.
+
+   Some error values do not indicate a system error or an error in the
+operation, but the result of an operation that failed properly.  For
+example, if you try to decrypt a tempered message, the decryption will
+fail.  Another error value actually means that the end of a data buffer
+or list has been reached.  The following descriptions explain for many
+error codes what they mean usually.  Some error values have specific
+meanings if returned by a certain functions.  Such cases are described
+in the documentation of those functions.
+
+   Libgcrypt uses the 'libgpg-error' library.  This allows to share the
+error codes with other components of the GnuPG system, and to pass error
+values transparently from the crypto engine, or some helper application
+of the crypto engine, to the user.  This way no information is lost.  As
+a consequence, Libgcrypt does not use its own identifiers for error
+codes, but uses those provided by 'libgpg-error'.  They usually start
+with 'GPG_ERR_'.
+
+   However, Libgcrypt does provide aliases for the functions defined in
+libgpg-error, which might be preferred for name space consistency.
+
+   Most functions in Libgcrypt return an error code in the case of
+failure.  For this reason, the application should always catch the error
+condition and take appropriate measures, for example by releasing the
+resources and passing the error up to the caller, or by displaying a
+descriptive message to the user and canceling the operation.
+
+   Some error values do not indicate a system error or an error in the
+operation, but the result of an operation that failed properly.
+
+   GnuPG components, including Libgcrypt, use an extra library named
+libgpg-error to provide a common error handling scheme.  For more
+information on libgpg-error, see the according manual.
+
+* Menu:
+
+* Error Values::                The error value and what it means.
+* Error Sources::               A list of important error sources.
+* Error Codes::                 A list of important error codes.
+* Error Strings::               How to get a descriptive string from a value.
+
+
+File: gcrypt.info,  Node: Error Values,  Next: Error Sources,  Up: Error Handling
+
+3.2.1 Error Values
+------------------
+
+ -- Data type: gcry_err_code_t
+     The 'gcry_err_code_t' type is an alias for the 'libgpg-error' type
+     'gpg_err_code_t'.  The error code indicates the type of an error,
+     or the reason why an operation failed.
+
+     A list of important error codes can be found in the next section.
+
+ -- Data type: gcry_err_source_t
+     The 'gcry_err_source_t' type is an alias for the 'libgpg-error'
+     type 'gpg_err_source_t'.  The error source has not a precisely
+     defined meaning.  Sometimes it is the place where the error
+     happened, sometimes it is the place where an error was encoded into
+     an error value.  Usually the error source will give an indication
+     to where to look for the problem.  This is not always true, but it
+     is attempted to achieve this goal.
+
+     A list of important error sources can be found in the next section.
+
+ -- Data type: gcry_error_t
+     The 'gcry_error_t' type is an alias for the 'libgpg-error' type
+     'gpg_error_t'.  An error value like this has always two components,
+     an error code and an error source.  Both together form the error
+     value.
+
+     Thus, the error value can not be directly compared against an error
+     code, but the accessor functions described below must be used.
+     However, it is guaranteed that only 0 is used to indicate success
+     ('GPG_ERR_NO_ERROR'), and that in this case all other parts of the
+     error value are set to 0, too.
+
+     Note that in Libgcrypt, the error source is used purely for
+     diagnostic purposes.  Only the error code should be checked to test
+     for a certain outcome of a function.  The manual only documents the
+     error code part of an error value.  The error source is left
+     unspecified and might be anything.
+
+ -- Function: gcry_err_code_t gcry_err_code (gcry_error_t ERR)
+     The static inline function 'gcry_err_code' returns the
+     'gcry_err_code_t' component of the error value ERR.  This function
+     must be used to extract the error code from an error value in order
+     to compare it with the 'GPG_ERR_*' error code macros.
+
+ -- Function: gcry_err_source_t gcry_err_source (gcry_error_t ERR)
+     The static inline function 'gcry_err_source' returns the
+     'gcry_err_source_t' component of the error value ERR.  This
+     function must be used to extract the error source from an error
+     value in order to compare it with the 'GPG_ERR_SOURCE_*' error
+     source macros.
+
+ -- Function: gcry_error_t gcry_err_make (gcry_err_source_t SOURCE,
+          gcry_err_code_t CODE)
+     The static inline function 'gcry_err_make' returns the error value
+     consisting of the error source SOURCE and the error code CODE.
+
+     This function can be used in callback functions to construct an
+     error value to return it to the library.
+
+ -- Function: gcry_error_t gcry_error (gcry_err_code_t CODE)
+     The static inline function 'gcry_error' returns the error value
+     consisting of the default error source and the error code CODE.
+
+     For GCRY applications, the default error source is
+     'GPG_ERR_SOURCE_USER_1'.  You can define 'GCRY_ERR_SOURCE_DEFAULT'
+     before including 'gcrypt.h' to change this default.
+
+     This function can be used in callback functions to construct an
+     error value to return it to the library.
+
+   The 'libgpg-error' library provides error codes for all system error
+numbers it knows about.  If ERR is an unknown error number, the error
+code 'GPG_ERR_UNKNOWN_ERRNO' is used.  The following functions can be
+used to construct error values from system errno numbers.
+
+ -- Function: gcry_error_t gcry_err_make_from_errno
+          (gcry_err_source_t SOURCE, int ERR)
+     The function 'gcry_err_make_from_errno' is like 'gcry_err_make',
+     but it takes a system error like 'errno' instead of a
+     'gcry_err_code_t' error code.
+
+ -- Function: gcry_error_t gcry_error_from_errno (int ERR)
+     The function 'gcry_error_from_errno' is like 'gcry_error', but it
+     takes a system error like 'errno' instead of a 'gcry_err_code_t'
+     error code.
+
+   Sometimes you might want to map system error numbers to error codes
+directly, or map an error code representing a system error back to the
+system error number.  The following functions can be used to do that.
+
+ -- Function: gcry_err_code_t gcry_err_code_from_errno (int ERR)
+     The function 'gcry_err_code_from_errno' returns the error code for
+     the system error ERR.  If ERR is not a known system error, the
+     function returns 'GPG_ERR_UNKNOWN_ERRNO'.
+
+ -- Function: int gcry_err_code_to_errno (gcry_err_code_t ERR)
+     The function 'gcry_err_code_to_errno' returns the system error for
+     the error code ERR.  If ERR is not an error code representing a
+     system error, or if this system error is not defined on this
+     system, the function returns '0'.
+
+
+File: gcrypt.info,  Node: Error Sources,  Next: Error Codes,  Prev: Error Values,  Up: Error Handling
+
+3.2.2 Error Sources
+-------------------
+
+The library 'libgpg-error' defines an error source for every component
+of the GnuPG system.  The error source part of an error value is not
+well defined.  As such it is mainly useful to improve the diagnostic
+error message for the user.
+
+   If the error code part of an error value is '0', the whole error
+value will be '0'.  In this case the error source part is of course
+'GPG_ERR_SOURCE_UNKNOWN'.
+
+   The list of error sources that might occur in applications using
+Libgcrypt is:
+
+'GPG_ERR_SOURCE_UNKNOWN'
+     The error source is not known.  The value of this error source is
+     '0'.
+
+'GPG_ERR_SOURCE_GPGME'
+     The error source is GPGME itself.
+
+'GPG_ERR_SOURCE_GPG'
+     The error source is GnuPG, which is the crypto engine used for the
+     OpenPGP protocol.
+
+'GPG_ERR_SOURCE_GPGSM'
+     The error source is GPGSM, which is the crypto engine used for the
+     OpenPGP protocol.
+
+'GPG_ERR_SOURCE_GCRYPT'
+     The error source is 'libgcrypt', which is used by crypto engines to
+     perform cryptographic operations.
+
+'GPG_ERR_SOURCE_GPGAGENT'
+     The error source is 'gpg-agent', which is used by crypto engines to
+     perform operations with the secret key.
+
+'GPG_ERR_SOURCE_PINENTRY'
+     The error source is 'pinentry', which is used by 'gpg-agent' to
+     query the passphrase to unlock a secret key.
+
+'GPG_ERR_SOURCE_SCD'
+     The error source is the SmartCard Daemon, which is used by
+     'gpg-agent' to delegate operations with the secret key to a
+     SmartCard.
+
+'GPG_ERR_SOURCE_KEYBOX'
+     The error source is 'libkbx', a library used by the crypto engines
+     to manage local keyrings.
+
+'GPG_ERR_SOURCE_USER_1'
+'GPG_ERR_SOURCE_USER_2'
+'GPG_ERR_SOURCE_USER_3'
+'GPG_ERR_SOURCE_USER_4'
+     These error sources are not used by any GnuPG component and can be
+     used by other software.  For example, applications using Libgcrypt
+     can use them to mark error values coming from callback handlers.
+     Thus 'GPG_ERR_SOURCE_USER_1' is the default for errors created with
+     'gcry_error' and 'gcry_error_from_errno', unless you define
+     'GCRY_ERR_SOURCE_DEFAULT' before including 'gcrypt.h'.
+
+
+File: gcrypt.info,  Node: Error Codes,  Next: Error Strings,  Prev: Error Sources,  Up: Error Handling
+
+3.2.3 Error Codes
+-----------------
+
+The library 'libgpg-error' defines many error values.  The following
+list includes the most important error codes.
+
+'GPG_ERR_EOF'
+     This value indicates the end of a list, buffer or file.
+
+'GPG_ERR_NO_ERROR'
+     This value indicates success.  The value of this error code is '0'.
+     Also, it is guaranteed that an error value made from the error code
+     '0' will be '0' itself (as a whole).  This means that the error
+     source information is lost for this error code, however, as this
+     error code indicates that no error occurred, this is generally not
+     a problem.
+
+'GPG_ERR_GENERAL'
+     This value means that something went wrong, but either there is not
+     enough information about the problem to return a more useful error
+     value, or there is no separate error value for this type of
+     problem.
+
+'GPG_ERR_ENOMEM'
+     This value means that an out-of-memory condition occurred.
+
+'GPG_ERR_E...'
+     System errors are mapped to GPG_ERR_EFOO where FOO is the symbol
+     for the system error.
+
+'GPG_ERR_INV_VALUE'
+     This value means that some user provided data was out of range.
+
+'GPG_ERR_UNUSABLE_PUBKEY'
+     This value means that some recipients for a message were invalid.
+
+'GPG_ERR_UNUSABLE_SECKEY'
+     This value means that some signers were invalid.
+
+'GPG_ERR_NO_DATA'
+     This value means that data was expected where no data was found.
+
+'GPG_ERR_CONFLICT'
+     This value means that a conflict of some sort occurred.
+
+'GPG_ERR_NOT_IMPLEMENTED'
+     This value indicates that the specific function (or operation) is
+     not implemented.  This error should never happen.  It can only
+     occur if you use certain values or configuration options which do
+     not work, but for which we think that they should work at some
+     later time.
+
+'GPG_ERR_DECRYPT_FAILED'
+     This value indicates that a decryption operation was unsuccessful.
+
+'GPG_ERR_WRONG_KEY_USAGE'
+     This value indicates that a key is not used appropriately.
+
+'GPG_ERR_NO_SECKEY'
+     This value indicates that no secret key for the user ID is
+     available.
+
+'GPG_ERR_UNSUPPORTED_ALGORITHM'
+     This value means a verification failed because the cryptographic
+     algorithm is not supported by the crypto backend.
+
+'GPG_ERR_BAD_SIGNATURE'
+     This value means a verification failed because the signature is
+     bad.
+
+'GPG_ERR_NO_PUBKEY'
+     This value means a verification failed because the public key is
+     not available.
+
+'GPG_ERR_NOT_OPERATIONAL'
+     This value means that the library is not yet in state which allows
+     to use this function.  This error code is in particular returned if
+     Libgcrypt is operated in FIPS mode and the internal state of the
+     library does not yet or not anymore allow the use of a service.
+
+     This error code is only available with newer libgpg-error versions,
+     thus you might see "invalid error code" when passing this to
+     'gpg_strerror'.  The numeric value of this error code is 176.
+
+'GPG_ERR_USER_1'
+'GPG_ERR_USER_2'
+'...'
+'GPG_ERR_USER_16'
+     These error codes are not used by any GnuPG component and can be
+     freely used by other software.  Applications using Libgcrypt might
+     use them to mark specific errors returned by callback handlers if
+     no suitable error codes (including the system errors) for these
+     errors exist already.
+
+
+File: gcrypt.info,  Node: Error Strings,  Prev: Error Codes,  Up: Error Handling
+
+3.2.4 Error Strings
+-------------------
+
+ -- Function: const char * gcry_strerror (gcry_error_t ERR)
+     The function 'gcry_strerror' returns a pointer to a statically
+     allocated string containing a description of the error code
+     contained in the error value ERR.  This string can be used to
+     output a diagnostic message to the user.
+
+ -- Function: const char * gcry_strsource (gcry_error_t ERR)
+     The function 'gcry_strsource' returns a pointer to a statically
+     allocated string containing a description of the error source
+     contained in the error value ERR.  This string can be used to
+     output a diagnostic message to the user.
+
+   The following example illustrates the use of the functions described
+above:
+
+     {
+       gcry_cipher_hd_t handle;
+       gcry_error_t err = 0;
+
+       err = gcry_cipher_open (&handle, GCRY_CIPHER_AES,
+                               GCRY_CIPHER_MODE_CBC, 0);
+       if (err)
+         {
+           fprintf (stderr, "Failure: %s/%s\n",
+                    gcry_strsource (err),
+                    gcry_strerror (err));
+         }
+     }
+
+
+File: gcrypt.info,  Node: Handler Functions,  Next: Symmetric cryptography,  Prev: Generalities,  Up: Top
+
+4 Handler Functions
+*******************
+
+Libgcrypt makes it possible to install so called 'handler functions',
+which get called by Libgcrypt in case of certain events.
+
+* Menu:
+
+* Progress handler::            Using a progress handler function.
+* Allocation handler::          Using special memory allocation functions.
+* Error handler::               Using error handler functions.
+* Logging handler::             Using a special logging function.
+
+
+File: gcrypt.info,  Node: Progress handler,  Next: Allocation handler,  Up: Handler Functions
+
+4.1 Progress handler
+====================
+
+It is often useful to retrieve some feedback while long running
+operations are performed.
+
+ -- Data type: gcry_handler_progress_t
+     Progress handler functions have to be of the type
+     'gcry_handler_progress_t', which is defined as:
+
+     'void (*gcry_handler_progress_t) (void *, const char *, int, int,
+     int)'
+
+   The following function may be used to register a handler function for
+this purpose.
+
+ -- Function: void gcry_set_progress_handler (gcry_handler_progress_t
+          CB, void *CB_DATA)
+
+     This function installs CB as the 'Progress handler' function.  It
+     may be used only during initialization.  CB must be defined as
+     follows:
+
+          void
+          my_progress_handler (void *CB_DATA, const char *WHAT,
+                               int PRINTCHAR, int CURRENT, int TOTAL)
+          {
+            /* Do something.  */
+          }
+
+     A description of the arguments of the progress handler function
+     follows.
+
+     CB_DATA
+          The argument provided in the call to
+          'gcry_set_progress_handler'.
+     WHAT
+          A string identifying the type of the progress output.  The
+          following values for WHAT are defined:
+
+          'need_entropy'
+               Not enough entropy is available.  TOTAL holds the number
+               of required bytes.
+
+          'wait_dev_random'
+               Waiting to re-open a random device.  TOTAL gives the
+               number of seconds until the next try.
+
+          'primegen'
+               Values for PRINTCHAR:
+               '\n'
+                    Prime generated.
+               '!'
+                    Need to refresh the pool of prime numbers.
+               '<, >'
+                    Number of bits adjusted.
+               '^'
+                    Searching for a generator.
+               '.'
+                    Fermat test on 10 candidates failed.
+               ':'
+                    Restart with a new random value.
+               '+'
+                    Rabin Miller test passed.
+
+
+File: gcrypt.info,  Node: Allocation handler,  Next: Error handler,  Prev: Progress handler,  Up: Handler Functions
+
+4.2 Allocation handler
+======================
+
+It is possible to make Libgcrypt use special memory allocation functions
+instead of the built-in ones.
+
+   Memory allocation functions are of the following types:
+ -- Data type: gcry_handler_alloc_t
+     This type is defined as: 'void *(*gcry_handler_alloc_t) (size_t
+     n)'.
+ -- Data type: gcry_handler_secure_check_t
+     This type is defined as: 'int *(*gcry_handler_secure_check_t)
+     (const void *)'.
+ -- Data type: gcry_handler_realloc_t
+     This type is defined as: 'void *(*gcry_handler_realloc_t) (void *p,
+     size_t n)'.
+ -- Data type: gcry_handler_free_t
+     This type is defined as: 'void *(*gcry_handler_free_t) (void *)'.
+
+   Special memory allocation functions can be installed with the
+following function:
+
+ -- Function: void gcry_set_allocation_handler (gcry_handler_alloc_t
+          FUNC_ALLOC, gcry_handler_alloc_t FUNC_ALLOC_SECURE,
+          gcry_handler_secure_check_t FUNC_SECURE_CHECK,
+          gcry_handler_realloc_t FUNC_REALLOC, gcry_handler_free_t
+          FUNC_FREE)
+     Install the provided functions and use them instead of the built-in
+     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.
+
+
+File: gcrypt.info,  Node: Error handler,  Next: Logging handler,  Prev: Allocation handler,  Up: Handler Functions
+
+4.3 Error handler
+=================
+
+The following functions may be used to register handler functions that
+are called by Libgcrypt in case certain error conditions occur.  They
+may and should be registered prior to calling 'gcry_check_version'.
+
+ -- Data type: gcry_handler_no_mem_t
+     This type is defined as: 'int (*gcry_handler_no_mem_t) (void *,
+     size_t, unsigned int)'
+ -- Function: void gcry_set_outofcore_handler (gcry_handler_no_mem_t
+          FUNC_NO_MEM, void *CB_DATA)
+     This function registers FUNC_NO_MEM as 'out-of-core handler', which
+     means that it will be called in the case of not having enough
+     memory available.  The handler is called with 3 arguments: The
+     first one is the pointer 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.
+
+ -- Data type: gcry_handler_error_t
+     This type is defined as: 'void (*gcry_handler_error_t) (void *,
+     int, const char *)'
+
+ -- Function: void gcry_set_fatalerror_handler (gcry_handler_error_t
+          FUNC_ERROR, void *CB_DATA)
+     This function registers FUNC_ERROR as 'error handler', which means
+     that it will be called in error conditions.
+
+
+File: gcrypt.info,  Node: Logging handler,  Prev: Error handler,  Up: Handler Functions
+
+4.4 Logging handler
+===================
+
+ -- Data type: gcry_handler_log_t
+     This type is defined as: 'void (*gcry_handler_log_t) (void *, int,
+     const char *, va_list)'
+
+ -- Function: void gcry_set_log_handler (gcry_handler_log_t FUNC_LOG,
+          void *CB_DATA)
+     This function registers FUNC_LOG as 'logging handler', which means
+     that it will be called in case Libgcrypt wants to log a message.
+     This function may and should be used prior to calling
+     'gcry_check_version'.
+
+
+File: gcrypt.info,  Node: Symmetric cryptography,  Next: Public Key cryptography,  Prev: Handler Functions,  Up: Top
+
+5 Symmetric cryptography
+************************
+
+The cipher functions are used for symmetrical cryptography, i.e.
+cryptography using a shared key.  The programming model follows an
+open/process/close paradigm and is in that similar to other building
+blocks provided by Libgcrypt.
+
+* Menu:
+
+* Available ciphers::           List of ciphers supported by the library.
+* Available cipher modes::      List of cipher modes supported by the library.
+* Working with cipher handles::  How to perform operations related to cipher handles.
+* General cipher functions::    General cipher functions independent of cipher handles.
+
+
+File: gcrypt.info,  Node: Available ciphers,  Next: Available cipher modes,  Up: Symmetric cryptography
+
+5.1 Available ciphers
+=====================
+
+'GCRY_CIPHER_NONE'
+     This is not a real algorithm but used by some functions as error
+     return.  The value always evaluates to false.
+
+'GCRY_CIPHER_IDEA'
+     This is the IDEA algorithm.
+
+'GCRY_CIPHER_3DES'
+     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.
+
+'GCRY_CIPHER_CAST5'
+     CAST128-5 block cipher algorithm.  The key size is 128 bits.
+
+'GCRY_CIPHER_BLOWFISH'
+     The blowfish algorithm.  The current implementation allows only for
+     a key size of 128 bits.
+
+'GCRY_CIPHER_SAFER_SK128'
+     Reserved and not currently implemented.
+
+'GCRY_CIPHER_DES_SK'
+     Reserved and not currently implemented.
+
+'GCRY_CIPHER_AES'
+'GCRY_CIPHER_AES128'
+'GCRY_CIPHER_RIJNDAEL'
+'GCRY_CIPHER_RIJNDAEL128'
+     AES (Rijndael) with a 128 bit key.
+
+'GCRY_CIPHER_AES192'
+'GCRY_CIPHER_RIJNDAEL192'
+     AES (Rijndael) with a 192 bit key.
+
+'GCRY_CIPHER_AES256'
+'GCRY_CIPHER_RIJNDAEL256'
+     AES (Rijndael) with a 256 bit key.
+
+'GCRY_CIPHER_TWOFISH'
+     The Twofish algorithm with a 256 bit key.
+
+'GCRY_CIPHER_TWOFISH128'
+     The Twofish algorithm with a 128 bit key.
+
+'GCRY_CIPHER_ARCFOUR'
+     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.
+
+'GCRY_CIPHER_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.
+
+'GCRY_CIPHER_SERPENT128'
+'GCRY_CIPHER_SERPENT192'
+'GCRY_CIPHER_SERPENT256'
+     The Serpent cipher from the AES contest.
+
+'GCRY_CIPHER_RFC2268_40'
+'GCRY_CIPHER_RFC2268_128'
+     Ron's Cipher 2 in the 40 and 128 bit variants.
+
+'GCRY_CIPHER_SEED'
+     A 128 bit cipher as described by RFC4269.
+
+'GCRY_CIPHER_CAMELLIA128'
+'GCRY_CIPHER_CAMELLIA192'
+'GCRY_CIPHER_CAMELLIA256'
+     The Camellia cipher by NTT. See
+     <http://info.isl.ntt.co.jp/crypt/eng/camellia/specifications.html>.
+
+'GCRY_CIPHER_SALSA20'
+     This is the Salsa20 stream cipher.
+
+'GCRY_CIPHER_SALSA20R12'
+     This is the Salsa20/12 - reduced round version of Salsa20 stream
+     cipher.
+
+'GCRY_CIPHER_GOST28147'
+     The GOST 28147-89 cipher, defined in the respective GOST standard.
+     Translation of this GOST into English is provided in the RFC-5830.
+
+'GCRY_CIPHER_CHACHA20'
+     This is the ChaCha20 stream cipher.
+
+
+File: gcrypt.info,  Node: Available cipher modes,  Next: Working with cipher handles,  Prev: Available ciphers,  Up: Symmetric cryptography
+
+5.2 Available cipher modes
+==========================
+
+'GCRY_CIPHER_MODE_NONE'
+     No mode specified.  This should not be used.  The only exception is
+     that 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.
+
+'GCRY_CIPHER_MODE_ECB'
+     Electronic Codebook mode.
+
+'GCRY_CIPHER_MODE_CFB'
+'GCRY_CIPHER_MODE_CFB8'
+     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.
+
+'GCRY_CIPHER_MODE_CBC'
+     Cipher Block Chaining mode.
+
+'GCRY_CIPHER_MODE_STREAM'
+     Stream mode, only to be used with stream cipher algorithms.
+
+'GCRY_CIPHER_MODE_OFB'
+     Output Feedback mode.
+
+'GCRY_CIPHER_MODE_CTR'
+     Counter mode.
+
+'GCRY_CIPHER_MODE_AESWRAP'
+     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 '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.
+
+'GCRY_CIPHER_MODE_CCM'
+     Counter with CBC-MAC mode is an Authenticated Encryption with
+     Associated Data (AEAD) block cipher mode, which is specified in
+     'NIST Special Publication 800-38C' and RFC 3610.
+
+'GCRY_CIPHER_MODE_GCM'
+     Galois/Counter Mode (GCM) is an Authenticated Encryption with
+     Associated Data (AEAD) block cipher mode, which is specified in
+     'NIST Special Publication 800-38D'.
+
+'GCRY_CIPHER_MODE_POLY1305'
+     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.
+
+'GCRY_CIPHER_MODE_OCB'
+     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 'gcry_cipher_ctl' using the
+     command 'GCRYCTL_SET_TAGLEN' and the address of an 'int' variable
+     set to 12 (for 96 bit) or 8 (for 64 bit) provided for the 'buffer'
+     argument and 'sizeof(int)' for 'buflen'.
+
+     Note that the use of 'gcry_cipher_final' is required.
+
+'GCRY_CIPHER_MODE_XTS'
+     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 ('GCRY_CIPHER_AES256').  The 128-bit tweak
+     value is feed to XTS mode as little-endian byte array using
+     'gcry_cipher_setiv' function.  When encrypting or decrypting,
+     full-sized data unit buffers needs to be passed to
+     'gcry_cipher_encrypt' or 'gcry_cipher_decrypt'.  The tweak value is
+     automatically incremented after each call of 'gcry_cipher_encrypt'
+     and 'gcry_cipher_decrypt'.  Auto-increment allows avoiding need of
+     setting IV between processing of sequential data units.
+
+
+File: gcrypt.info,  Node: Working with cipher handles,  Next: General cipher functions,  Prev: Available cipher modes,  Up: Symmetric cryptography
+
+5.3 Working with cipher handles
+===============================
+
+To use a cipher algorithm, you must first allocate an according handle.
+This is to be done using the open function:
+
+ -- Function: gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *HD, int
+          ALGO, int MODE, unsigned int FLAGS)
+
+     This function creates the context handle required for most of the
+     other cipher functions and returns a handle to it in 'hd'.  In case
+     of an error, an according error code is returned.
+
+     The ID of algorithm to use must be specified via ALGO.  See *note
+     Available ciphers::, for a list of supported ciphers and the
+     according constants.
+
+     Besides using the constants directly, the function
+     'gcry_cipher_map_name' may be used to convert the textual name of
+     an algorithm into the according numeric ID.
+
+     The cipher mode to use must be specified via MODE.  See *note
+     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
+     ('GCRY_CIPHER_MODE_STREAM') only works with stream ciphers.
+     Poly1305 AEAD mode ('GCRY_CIPHER_MODE_POLY1305') only works with
+     ChaCha20 stream cipher.  The block cipher modes
+     ('GCRY_CIPHER_MODE_ECB', 'GCRY_CIPHER_MODE_CBC',
+     'GCRY_CIPHER_MODE_CFB', 'GCRY_CIPHER_MODE_OFB' and
+     'GCRY_CIPHER_MODE_CTR') will work with any block cipher algorithm.
+     GCM mode ('GCRY_CIPHER_MODE_CCM'), CCM mode
+     ('GCRY_CIPHER_MODE_GCM'), OCB mode ('GCRY_CIPHER_MODE_OCB'), and
+     XTS mode ('GCRY_CIPHER_MODE_XTS') will only work with block cipher
+     algorithms which have the block size of 16 bytes.
+
+     The third argument FLAGS can either be passed as '0' or as the
+     bit-wise OR of the following constants.
+
+     'GCRY_CIPHER_SECURE'
+          Make sure that all operations are allocated in secure memory.
+          This is useful when the key material is highly confidential.
+     'GCRY_CIPHER_ENABLE_SYNC'
+          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 'gcry_cipher_sync'.
+     'GCRY_CIPHER_CBC_CTS'
+          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).
+     'GCRY_CIPHER_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.
+
+   Use the following function to release an existing handle:
+
+ -- Function: void gcry_cipher_close (gcry_cipher_hd_t H)
+
+     This function releases the context created by 'gcry_cipher_open'.
+     It also zeroises all sensitive information associated with this
+     cipher handle.
+
+   In order to use a handle for performing cryptographic operations, a
+'key' has to be set first:
+
+ -- Function: gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t H, const
+          void *K, size_t L)
+
+     Set the key K used for encryption or decryption in the context
+     denoted by the handle H.  The length L (in bytes) of the key 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.
+
+   Most crypto modes requires an initialization vector (IV), which
+usually is a non-secret random string acting as a kind of salt value.
+The CTR mode requires a counter, which is also similar to a salt value.
+To set the IV or CTR, use these functions:
+
+ -- Function: gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t H, const
+          void *K, size_t L)
+
+     Set the initialization vector used for encryption or decryption.
+     The vector is passed as the buffer K of length 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 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.
+
+ -- Function: gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t H, const
+          void *C, size_t L)
+
+     Set the counter vector used for encryption or decryption.  The
+     counter is passed as the buffer C of length 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).
+
+ -- Function: gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t H)
+
+     Set the given handle's context back to the state it had after the
+     last call to gcry_cipher_setkey and clear the initialization
+     vector.
+
+     Note that gcry_cipher_reset is implemented as a macro.
+
+   Authenticated Encryption with Associated Data (AEAD) block cipher
+modes require the handling of the authentication tag and the additional
+authenticated data, which can be done by using the following functions:
+
+ -- Function: gcry_error_t gcry_cipher_authenticate (gcry_cipher_hd_t H,
+          const void *ABUF, size_t ABUFLEN)
+
+     Process the buffer ABUF of length ABUFLEN as the additional
+     authenticated data (AAD) for AEAD cipher modes.
+
+ -- Function: gcry_error_t gcry_cipher_gettag (gcry_cipher_hd_t H,
+          void *TAG, size_t TAGLEN)
+
+     This function is used to read the authentication tag after
+     encryption.  The function finalizes and outputs the authentication
+     tag to the buffer TAG of length TAGLEN bytes.
+
+     Depending on the used mode certain restrictions for TAGLEN are
+     enforced: For GCM TAGLEN must be at least 16 or one of the allowed
+     truncated lengths (4, 8, 12, 13, 14, or 15).
+
+ -- Function: gcry_error_t gcry_cipher_checktag (gcry_cipher_hd_t H,
+          const void *TAG, size_t TAGLEN)
+
+     Check the authentication tag after decryption.  The authentication
+     tag is passed as the buffer TAG of length TAGLEN bytes and compared
+     to internal authentication tag computed during decryption.  Error
+     code 'GPG_ERR_CHECKSUM' is returned if the authentication tag in
+     the buffer TAG does not match the authentication tag calculated
+     during decryption.
+
+     Depending on the used mode certain restrictions for TAGLEN are
+     enforced: For GCM TAGLEN must either be 16 or one of the allowed
+     truncated lengths (4, 8, 12, 13, 14, or 15).
+
+   The actual encryption and decryption is done by using one of the
+following functions.  They may be used as often as required to process
+all the data.
+
+ -- Function: gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t H,
+          unsigned char *out, size_t OUTSIZE, const unsigned char *IN,
+          size_t INLEN)
+
+     'gcry_cipher_encrypt' is used to encrypt the data.  This function
+     can either work in place or with two buffers.  It uses the cipher
+     context already setup and described by the handle H.  There are 2
+     ways to use the function: If IN is passed as 'NULL' and INLEN is
+     '0', in-place encryption of the data in OUT of length OUTSIZE takes
+     place.  With IN being not 'NULL', INLEN bytes are encrypted to the
+     buffer OUT which must have at least a size of INLEN.  OUTSIZE must
+     be set to the allocated size of OUT, so that the function can check
+     that there 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 'gcry_cipher_final' is used
+     before the final data chunk is passed to this function.
+
+     The function returns '0' on success or an error code.
+
+ -- Function: gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t H,
+          unsigned char *out, size_t OUTSIZE, const unsigned char *IN,
+          size_t INLEN)
+
+     'gcry_cipher_decrypt' is used to decrypt the data.  This function
+     can either work in place or with two buffers.  It uses the cipher
+     context already setup and described by the handle H.  There are 2
+     ways to use the function: If IN is passed as 'NULL' and INLEN is
+     '0', in-place decryption of the data in OUT or length OUTSIZE takes
+     place.  With IN being not 'NULL', INLEN bytes are decrypted to the
+     buffer OUT which must have at least a size of INLEN.  OUTSIZE must
+     be set to the allocated size of OUT, so that the function can check
+     that there 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 'gcry_cipher_final' is used
+     before the final data chunk is passed to this function.
+
+     The function returns '0' on success or an error code.
+
+   The OCB mode features integrated padding and must thus be told about
+the end of the input data.  This is done with:
+
+ -- Function: gcry_error_t gcry_cipher_final (gcry_cipher_hd_t 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.
+
+   OpenPGP (as defined in RFC-4880) requires a special sync operation in
+some places.  The following function is used for this:
+
+ -- Function: gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t H)
+
+     Perform the OpenPGP sync operation on context H.  Note that this is
+     a no-op unless the context was created with the flag
+     'GCRY_CIPHER_ENABLE_SYNC'
+
+   Some of the described functions are implemented as macros utilizing a
+catch-all control function.  This control function is rarely used
+directly but there is nothing which would inhibit it:
+
+ -- Function: gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t H, int CMD,
+          void *BUFFER, size_t BUFLEN)
+
+     'gcry_cipher_ctl' controls various aspects of the cipher module and
+     specific cipher contexts.  Usually some more specialized functions
+     or macros are used for this purpose.  The semantics of the function
+     and its parameters depends on the the command CMD and the passed
+     context handle H.  Please see the comments in the source code
+     ('src/global.c') for details.
+
+ -- Function: gcry_error_t gcry_cipher_info (gcry_cipher_hd_t H, int
+          WHAT, void *BUFFER, size_t *NBYTES)
+
+     'gcry_cipher_info' is used to retrieve various information about a
+     cipher context or the cipher module in general.
+
+     '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.
+          BUFFER must be given as NULL. On success the result is stored
+          NBYTES.  The taglen is returned in bytes.
+
+
+File: gcrypt.info,  Node: General cipher functions,  Prev: Working with cipher handles,  Up: Symmetric cryptography
+
+5.4 General cipher functions
+============================
+
+To work with the algorithms, several functions are available to map
+algorithm names to the internal identifiers, as well as ways to retrieve
+information about an algorithm or the current cipher context.
+
+ -- Function: gcry_error_t gcry_cipher_algo_info (int ALGO, int WHAT,
+          void *BUFFER, size_t *NBYTES)
+
+     This function is used to retrieve information on a specific
+     algorithm.  You pass the cipher algorithm ID as ALGO and the type
+     of information requested as WHAT.  The result is either returned as
+     the return code of the function or copied to the provided BUFFER
+     whose allocated length must be available in an integer variable
+     with the address passed in NBYTES.  This variable will also receive
+     the actual used length of the buffer.
+
+     Here is a list of supported codes for WHAT:
+
+     'GCRYCTL_GET_KEYLEN:'
+          Return the length of the key.  If the algorithm supports
+          multiple key lengths, the maximum supported value is returned.
+          The length is returned as number of octets (bytes) and not as
+          number of bits in NBYTES; BUFFER must be zero.  Note that it
+          is usually better to use the convenience function
+          'gcry_cipher_get_algo_keylen'.
+
+     'GCRYCTL_GET_BLKLEN:'
+          Return the block length of the algorithm.  The length is
+          returned as a number of octets in NBYTES; BUFFER must be zero.
+          Note that it is usually better to use the convenience function
+          'gcry_cipher_get_algo_blklen'.
+
+     'GCRYCTL_TEST_ALGO:'
+          Returns '0' when the specified algorithm is available for use.
+          BUFFER and NBYTES must be zero.
+
+ -- Function: size_t gcry_cipher_get_algo_keylen (ALGO)
+
+     This function returns length of the key for algorithm ALGO.  If the
+     algorithm supports multiple key lengths, the maximum supported key
+     length is returned.  On error '0' is returned.  The key length is
+     returned as number of octets.
+
+     This is a convenience functions which should be preferred over
+     'gcry_cipher_algo_info' because it allows for proper type checking.
+
+ -- Function: size_t gcry_cipher_get_algo_blklen (int ALGO)
+
+     This functions returns the block-length of the algorithm ALGO
+     counted in octets.  On error '0' is returned.
+
+     This is a convenience functions which should be preferred over
+     'gcry_cipher_algo_info' because it allows for proper type checking.
+
+ -- Function: const char * gcry_cipher_algo_name (int ALGO)
+
+     'gcry_cipher_algo_name' returns a string with the name of the
+     cipher algorithm ALGO.  If the algorithm is not known or another
+     error occurred, the string '"?"' is returned.  This function should
+     not be used to test for the availability of an algorithm.
+
+ -- Function: int gcry_cipher_map_name (const char *NAME)
+
+     'gcry_cipher_map_name' returns the algorithm identifier for the
+     cipher algorithm described by the string NAME.  If this algorithm
+     is not available '0' is returned.
+
+ -- Function: int gcry_cipher_mode_from_oid (const char *STRING)
+
+     Return the cipher mode associated with an ASN.1 object identifier.
+     The object identifier is expected to be in the IETF-style dotted
+     decimal notation.  The function returns '0' for an unknown object
+     identifier or when no mode is associated with it.
+
+
+File: gcrypt.info,  Node: Public Key cryptography,  Next: Hashing,  Prev: Symmetric cryptography,  Up: Top
+
+6 Public Key cryptography
+*************************
+
+Public key cryptography, also known as asymmetric cryptography, is an
+easy way for key management and to provide digital signatures.
+Libgcrypt provides two completely different interfaces to public key
+cryptography, this chapter explains the one based on S-expressions.
+
+* Menu:
+
+* Available algorithms::        Algorithms supported by the library.
+* Used S-expressions::          Introduction into the used S-expression.
+* Cryptographic Functions::     Functions for performing the cryptographic actions.
+* General public-key related Functions::  General functions, not implementing any cryptography.
+
+
+File: gcrypt.info,  Node: Available algorithms,  Next: Used S-expressions,  Up: Public Key cryptography
+
+6.1 Available algorithms
+========================
+
+Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well as
+DSA (Digital Signature Algorithm) and Elgamal.  The versatile interface
+allows to add more algorithms in the future.
+
+
+File: gcrypt.info,  Node: Used S-expressions,  Next: Cryptographic Functions,  Prev: Available algorithms,  Up: Public Key cryptography
+
+6.2 Used S-expressions
+======================
+
+Libgcrypt's API for asymmetric cryptography is based on data structures
+called S-expressions (see
+<http://people.csail.mit.edu/rivest/sexp.html>) and does not work with
+contexts as most of the other building blocks of Libgcrypt do.
+
+The following information are stored in S-expressions:
+
+   * keys
+
+   * plain text data
+
+   * encrypted data
+
+   * signatures
+
+To describe how Libgcrypt expect keys, we use examples.  Note that words
+in uppercase indicate parameters whereas lowercase words are literals.
+
+   Note that all MPI (multi-precision-integers) values are expected to
+be in 'GCRYMPI_FMT_USG' format.  An easy way to create S-expressions is
+by using 'gcry_sexp_build' which allows to pass a string with
+printf-like escapes to insert MPI values.
+
+* Menu:
+
+* RSA key parameters::  Parameters used with an RSA key.
+* DSA key parameters::  Parameters used with a DSA key.
+* ECC key parameters::  Parameters used with ECC keys.
+
+
+File: gcrypt.info,  Node: RSA key parameters,  Next: DSA key parameters,  Up: Used S-expressions
+
+6.2.1 RSA key parameters
+------------------------
+
+An RSA private key is described by this S-expression:
+
+     (private-key
+       (rsa
+         (n N-MPI)
+         (e E-MPI)
+         (d D-MPI)
+         (p P-MPI)
+         (q Q-MPI)
+         (u U-MPI)))
+
+An RSA public key is described by this S-expression:
+
+     (public-key
+       (rsa
+         (n N-MPI)
+         (e E-MPI)))
+
+N-MPI
+     RSA public modulus n.
+E-MPI
+     RSA public exponent e.
+D-MPI
+     RSA secret exponent d = e^{-1} \bmod (p-1)(q-1).
+P-MPI
+     RSA secret prime p.
+Q-MPI
+     RSA secret prime q with p < q.
+U-MPI
+     Multiplicative inverse u = p^{-1} \bmod q.
+
+   For signing and decryption the parameters (p, q, u) are optional but
+greatly improve the performance.  Either all of these optional
+parameters must be given or none of them.  They are mandatory for
+gcry_pk_testkey.
+
+   Note that OpenSSL uses slighly different parameters: q < p and u =
+q^{-1} \bmod p.  To use these parameters you will need to swap the
+values and recompute u.  Here is example code to do this:
+
+       if (gcry_mpi_cmp (p, q) > 0)
+         {
+           gcry_mpi_swap (p, q);
+           gcry_mpi_invm (u, p, q);
+         }
+
+
+File: gcrypt.info,  Node: DSA key parameters,  Next: ECC key parameters,  Prev: RSA key parameters,  Up: Used S-expressions
+
+6.2.2 DSA key parameters
+------------------------
+
+A DSA private key is described by this S-expression:
+
+     (private-key
+       (dsa
+         (p P-MPI)
+         (q Q-MPI)
+         (g G-MPI)
+         (y Y-MPI)
+         (x X-MPI)))
+
+P-MPI
+     DSA prime p.
+Q-MPI
+     DSA group order q (which is a prime divisor of p-1).
+G-MPI
+     DSA group generator g.
+Y-MPI
+     DSA public key value y = g^x \bmod p.
+X-MPI
+     DSA secret exponent x.
+
+   The public key is similar with "private-key" replaced by "public-key"
+and no X-MPI.
+
+
+File: gcrypt.info,  Node: ECC key parameters,  Prev: DSA key parameters,  Up: Used S-expressions
+
+6.2.3 ECC key parameters
+------------------------
+
+An ECC private key is described by this S-expression:
+
+     (private-key
+       (ecc
+         (p P-MPI)
+         (a A-MPI)
+         (b B-MPI)
+         (g G-POINT)
+         (n N-MPI)
+         (q Q-POINT)
+         (d D-MPI)))
+
+P-MPI
+     Prime specifying the field GF(p).
+A-MPI
+B-MPI
+     The two coefficients of the Weierstrass equation y^2 = x^3 + ax + b
+G-POINT
+     Base point g.
+N-MPI
+     Order of g
+Q-POINT
+     The point representing the public key Q = dG.
+D-MPI
+     The private key d
+
+   All point values are encoded in standard format; Libgcrypt does in
+general only support uncompressed points, thus the first byte needs to
+be '0x04'.  However "EdDSA" describes its own compression scheme which
+is used by default; the non-standard first byte '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 D-MPI.
+
+   If the domain parameters are well-known, the name of this curve may
+be used.  For example
+
+     (private-key
+       (ecc
+         (curve "NIST P-192")
+         (q Q-POINT)
+         (d D-MPI)))
+
+   Note that Q-POINT is optional for a private key.  The 'curve'
+parameter may be given in any case and is used to replace missing
+parameters.
+
+Currently implemented curves are:
+'NIST P-192'
+'1.2.840.10045.3.1.1'
+'prime192v1'
+'secp192r1'
+     The NIST 192 bit curve, its OID, X9.62 and SECP aliases.
+
+'NIST P-224'
+'secp224r1'
+     The NIST 224 bit curve and its SECP alias.
+
+'NIST P-256'
+'1.2.840.10045.3.1.7'
+'prime256v1'
+'secp256r1'
+     The NIST 256 bit curve, its OID, X9.62 and SECP aliases.
+
+'NIST P-384'
+'secp384r1'
+     The NIST 384 bit curve and its SECP alias.
+
+'NIST P-521'
+'secp521r1'
+     The NIST 521 bit curve and its SECP alias.
+
+   As usual the OIDs may optionally be prefixed with the string 'OID.'
+or 'oid.'.
+
+
+File: gcrypt.info,  Node: Cryptographic Functions,  Next: General public-key related Functions,  Prev: Used S-expressions,  Up: Public Key cryptography
+
+6.3 Cryptographic Functions
+===========================
+
+Some functions operating on S-expressions support 'flags' to influence
+the operation.  These flags have to be listed in a sub-S-expression
+named 'flags'.  Flag names are case-sensitive.  The following flags are
+known:
+
+'comp'
+'nocomp'
+     If supported by the algorithm and curve the 'comp' flag requests
+     that points are returned in compact (compressed) representation.
+     The '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.  If
+     'comp' is used with the "EdDSA" algorithm the key generation prefix
+     the public key with a '0x40' byte.
+
+'pkcs1'
+     Use PKCS#1 block type 2 padding for encryption, block type 1
+     padding for signing.
+
+'oaep'
+     Use RSA-OAEP padding for encryption.
+
+'pss'
+     Use RSA-PSS padding for signing.
+
+'eddsa'
+     Use the EdDSA scheme signing instead of the default ECDSA
+     algorithm.  Note that the EdDSA uses a special form of the public
+     key.
+
+'rfc6979'
+     For DSA and ECDSA use a deterministic scheme for the k parameter.
+
+'no-blinding'
+     Do not use a technique called 'blinding', which is used by default
+     in order to prevent leaking of secret information.  Blinding is
+     only implemented by RSA, but it might be implemented by other
+     algorithms in the future as well, when necessary.
+
+'param'
+     For ECC key generation also return the domain parameters.  For ECC
+     signing and verification override default parameters by provided
+     domain parameters of the public or private key.
+
+'transient-key'
+     This flag is only meaningful for RSA, DSA, and ECC key generation.
+     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.
+
+'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.
+
+'use-x931'
+     Force the use of the ANSI X9.31 key generation algorithm instead of
+     the default algorithm.  This flag is only meaningful for RSA key
+     generation and usually not required.  Note that this algorithm is
+     implicitly used if either 'derive-parms' is given or Libgcrypt is
+     in FIPS mode.
+
+'use-fips186'
+     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 '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.
+
+'use-fips186-2'
+     Force the use of the FIPS 186-2 key generation algorithm instead of
+     the default algorithm.  This algorithm is slightly 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.
+
+Now that we know the key basics, we can carry on and explain how to
+encrypt and decrypt data.  In almost all cases the data is a random
+session key which is in turn used for the actual encryption of the real
+data.  There are 2 functions to do this:
+
+ -- Function: gcry_error_t gcry_pk_encrypt (gcry_sexp_t *R_CIPH,
+          gcry_sexp_t DATA, gcry_sexp_t PKEY)
+
+     Obviously a public key must be provided for encryption.  It is
+     expected as an appropriate S-expression (see above) in PKEY.  The
+     data to be encrypted can either be in the simple old format, which
+     is a very simple S-expression consisting only of one MPI, or it may
+     be a more complex S-expression which also allows to specify flags
+     for operation, like e.g.  padding rules.
+
+     If you don't want to let Libgcrypt handle the padding, you must
+     pass an appropriate MPI using this expression for DATA:
+
+          (data
+            (flags raw)
+            (value MPI))
+
+     This has the same semantics as the old style MPI only way.  MPI is
+     the actual data, already padded appropriate for your protocol.
+     Most RSA based systems however use PKCS#1 padding and so you can
+     use this S-expression for DATA:
+
+          (data
+            (flags pkcs1)
+            (value BLOCK))
+
+     Here, the "flags" list has the "pkcs1" flag which let the function
+     know that it should provide PKCS#1 block type 2 padding.  The
+     actual data to be encrypted is passed as a string of octets in
+     BLOCK.  The function checks that this data actually can be used
+     with the given key, does the padding and encrypts it.
+
+     If the function could successfully perform the encryption, the
+     return value will be 0 and a new S-expression with the encrypted
+     result is allocated and assigned to the variable at the address of
+     R_CIPH.  The caller is responsible to release this value using
+     'gcry_sexp_release'.  In case of an error, an error code is
+     returned and R_CIPH will be set to 'NULL'.
+
+     The returned S-expression has this format when used with RSA:
+
+          (enc-val
+            (rsa
+              (a A-MPI)))
+
+     Where A-MPI is an MPI with the result of the RSA operation.  When
+     using the Elgamal algorithm, the return value will have this
+     format:
+
+          (enc-val
+            (elg
+              (a A-MPI)
+              (b B-MPI)))
+
+     Where A-MPI and B-MPI are MPIs with the result of the Elgamal
+     encryption operation.
+
+ -- Function: gcry_error_t gcry_pk_decrypt (gcry_sexp_t *R_PLAIN,
+          gcry_sexp_t DATA, gcry_sexp_t SKEY)
+
+     Obviously a private key must be provided for decryption.  It is
+     expected as an appropriate S-expression (see above) in SKEY.  The
+     data to be decrypted must match the format of the result as
+     returned by 'gcry_pk_encrypt', but should be enlarged with a
+     'flags' element:
+
+          (enc-val
+            (flags)
+            (elg
+              (a A-MPI)
+              (b B-MPI)))
+
+     This function does not remove padding from the data by default.  To
+     let Libgcrypt remove padding, give a hint in 'flags' telling which
+     padding method was used when encrypting:
+
+          (flags PADDING-METHOD)
+
+     Currently PADDING-METHOD is either 'pkcs1' for PKCS#1 block type 2
+     padding, or 'oaep' for RSA-OAEP padding.
+
+     The function returns 0 on success or an error code.  The variable
+     at the address of R_PLAIN will be set to NULL on error or receive
+     the decrypted value on success.  The format of R_PLAIN is a simple
+     S-expression part (i.e.  not a valid one) with just one MPI if
+     there was no 'flags' element in DATA; if at least an empty 'flags'
+     is passed in DATA, the format is:
+
+          (value PLAINTEXT)
+
+   Another operation commonly performed using public key cryptography is
+signing data.  In some sense this is even more important than encryption
+because digital signatures are an important instrument for key
+management.  Libgcrypt supports digital signatures using 2 functions,
+similar to the encryption functions:
+
+ -- Function: gcry_error_t gcry_pk_sign (gcry_sexp_t *R_SIG,
+          gcry_sexp_t DATA, gcry_sexp_t SKEY)
+
+     This function creates a digital signature for DATA using the
+     private key SKEY and place it into the variable at the address of
+     R_SIG.  DATA may either be the simple old style S-expression with
+     just one MPI or a modern and more versatile S-expression which
+     allows to let Libgcrypt handle padding:
+
+           (data
+            (flags pkcs1)
+            (hash HASH-ALGO BLOCK))
+
+     This example requests to sign the data in BLOCK after applying
+     PKCS#1 block type 1 style padding.  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 "sha256" or "sha1".  It is obvious that the length of BLOCK
+     must match the size of that message digests; the function checks
+     that this and other constraints are valid.
+
+     If PKCS#1 padding is not required (because the caller does already
+     provide a padded value), either the old format or better the
+     following format should be used:
+
+          (data
+            (flags raw)
+            (value MPI))
+
+     Here, the data to be signed is directly given as an MPI.
+
+     For DSA the input data is expected in this format:
+
+          (data
+            (flags raw)
+            (value MPI))
+
+     Here, the data to be signed is directly given as an MPI.  It is
+     expect that this MPI is the the hash value.  For the standard DSA
+     using a MPI is not a problem in regard to leading zeroes because
+     the hash value is directly used as an MPI. For better standard
+     conformance it would be better to explicit use a memory string
+     (like with pkcs1) but that is currently not supported.  However,
+     for deterministic DSA as specified in RFC6979 this can't be used.
+     Instead the following input is expected.
+
+          (data
+            (flags rfc6979)
+            (hash HASH-ALGO BLOCK))
+
+     Note that the provided hash-algo is used for the internal HMAC; it
+     should match the hash-algo used to create BLOCK.
+
+     The signature is returned as a newly allocated S-expression in
+     R_SIG using this format for RSA:
+
+          (sig-val
+            (rsa
+              (s S-MPI)))
+
+     Where S-MPI is the result of the RSA sign operation.  For DSA the
+     S-expression returned is:
+
+          (sig-val
+            (dsa
+              (r R-MPI)
+              (s S-MPI)))
+
+     Where R-MPI and S-MPI are the result of the DSA sign operation.
+
+     For Elgamal signing (which is slow, yields large numbers, hard to
+     use correctly and probably is not as secure as the other
+     algorithms), the same format is used with "elg" replacing "dsa";
+     for ECDSA signing, the same format is used with "ecdsa" replacing
+     "dsa".
+
+     For the EdDSA algorithm (cf.  Ed25515) the required input
+     parameters are:
+
+          (data
+            (flags eddsa)
+            (hash-algo sha512)
+            (value MESSAGE))
+
+     Note that the MESSAGE may be of any length; hashing is part of the
+     algorithm.  Using a large data block for MESSAGE is not suggested;
+     in that case the used protocol should better require that a hash of
+     the message is used as input to the EdDSA algorithm.
+
+The operation most commonly used is definitely the verification of a
+signature.  Libgcrypt provides this function:
+
+ -- Function: gcry_error_t gcry_pk_verify (gcry_sexp_t SIG,
+          gcry_sexp_t DATA, gcry_sexp_t PKEY)
+
+     This is used to check whether the signature SIG matches the DATA.
+     The public key PKEY must be provided to perform this verification.
+     This function is similar in its parameters to 'gcry_pk_sign' with
+     the exceptions that the public key is used instead of the private
+     key and that no signature is created but a signature, in a format
+     as created by 'gcry_pk_sign', is passed to the function in SIG.
+
+     The result is 0 for success (i.e.  the data matches the signature),
+     or an error code where the most relevant code is
+     'GCRY_ERR_BAD_SIGNATURE' to indicate that the signature does not
+     match the provided data.
+
+
+File: gcrypt.info,  Node: General public-key related Functions,  Prev: Cryptographic Functions,  Up: Public Key cryptography
+
+6.4 General public-key related Functions
+========================================
+
+A couple of utility functions are available to retrieve the length of
+the key, map algorithm identifiers and perform sanity checks:
+
+ -- Function: const char * gcry_pk_algo_name (int ALGO)
+
+     Map the public key algorithm id ALGO to a string representation of
+     the algorithm name.  For unknown algorithms this functions returns
+     the string '"?"'.  This function should not be used to test for the
+     availability of an algorithm.
+
+ -- Function: int gcry_pk_map_name (const char *NAME)
+
+     Map the algorithm NAME to a public key algorithm Id.  Returns 0 if
+     the algorithm name is not known.
+
+ -- Function: int gcry_pk_test_algo (int ALGO)
+
+     Return 0 if the public key algorithm ALGO is available for use.
+     Note that this is implemented as a macro.
+
+ -- Function: unsigned int gcry_pk_get_nbits (gcry_sexp_t KEY)
+
+     Return what is commonly referred as the key length for the given
+     public or private in KEY.
+
+ -- Function: unsigned char * gcry_pk_get_keygrip (gcry_sexp_t KEY,
+          unsigned char *ARRAY)
+
+     Return the so called "keygrip" which is the SHA-1 hash of the
+     public key parameters expressed in a way depended on the algorithm.
+     ARRAY must either provide space for 20 bytes or be 'NULL'.  In the
+     latter case a newly allocated array of that size is returned.  On
+     success a pointer to the newly allocated space or to ARRAY is
+     returned.  'NULL' is returned to indicate an error which is most
+     likely an unknown algorithm or one where a "keygrip" has not yet
+     been defined.  The function accepts public or secret keys in KEY.
+
+ -- Function: gcry_error_t gcry_pk_testkey (gcry_sexp_t KEY)
+
+     Return zero if the private key KEY is 'sane', an error code
+     otherwise.  Note that it is not possible to check the 'saneness' of
+     a public key.
+
+ -- Function: gcry_error_t gcry_pk_algo_info (int ALGO, int WHAT,
+          void *BUFFER, size_t *NBYTES)
+
+     Depending on the value of WHAT return various information about the
+     public key algorithm with the id ALGO.  Note that the function
+     returns '-1' on error and the actual error code must be retrieved
+     using the function 'gcry_errno'.  The currently defined values for
+     WHAT are:
+
+     'GCRYCTL_TEST_ALGO:'
+          Return 0 if the specified algorithm is available for use.
+          BUFFER must be 'NULL', NBYTES may be passed as 'NULL' or point
+          to a variable with the required usage of the algorithm.  This
+          may be 0 for "don't care" or the bit-wise OR of these flags:
+
+          'GCRY_PK_USAGE_SIGN'
+               Algorithm is usable for signing.
+          'GCRY_PK_USAGE_ENCR'
+               Algorithm is usable for encryption.
+
+          Unless you need to test for the allowed usage, it is in
+          general better to use the macro gcry_pk_test_algo instead.
+
+     'GCRYCTL_GET_ALGO_USAGE:'
+          Return the usage flags for the given algorithm.  An invalid
+          algorithm return 0.  Disabled algorithms are ignored here
+          because we want to know whether the algorithm is at all
+          capable of a certain usage.
+
+     'GCRYCTL_GET_ALGO_NPKEY'
+          Return the number of elements the public key for algorithm
+          ALGO consist of.  Return 0 for an unknown algorithm.
+
+     'GCRYCTL_GET_ALGO_NSKEY'
+          Return the number of elements the private key for algorithm
+          ALGO consist of.  Note that this value is always larger than
+          that of the public key.  Return 0 for an unknown algorithm.
+
+     'GCRYCTL_GET_ALGO_NSIGN'
+          Return the number of elements a signature created with the
+          algorithm ALGO consists of.  Return 0 for an unknown algorithm
+          or for an algorithm not capable of creating signatures.
+
+     'GCRYCTL_GET_ALGO_NENC'
+          Return the number of elements a encrypted message created with
+          the algorithm ALGO consists of.  Return 0 for an unknown
+          algorithm or for an algorithm not capable of encryption.
+
+     Please note that parameters not required should be passed as
+     'NULL'.
+
+ -- Function: gcry_error_t gcry_pk_ctl (int CMD, void *BUFFER,
+          size_t BUFLEN)
+
+     This is a general purpose function to perform certain control
+     operations.  CMD controls what is to be done.  The return value is
+     0 for success or an error code.  Currently supported values for CMD
+     are:
+
+     'GCRYCTL_DISABLE_ALGO'
+          Disable the algorithm given as an algorithm id in BUFFER.
+          BUFFER must point to an 'int' variable with the algorithm id
+          and BUFLEN must have the value 'sizeof (int)'.  This function
+          is not thread safe and should thus be used before any other
+          threads are started.
+
+Libgcrypt also provides a function to generate public key pairs:
+
+ -- Function: gcry_error_t gcry_pk_genkey (gcry_sexp_t *R_KEY,
+          gcry_sexp_t PARMS)
+
+     This function create a new public key pair using information given
+     in the S-expression PARMS and stores the private and the public key
+     in one new S-expression at the address given by R_KEY.  In case of
+     an error, R_KEY is set to 'NULL'.  The return code is 0 for success
+     or an error code otherwise.
+
+     Here is an example for PARMS to create an 2048 bit RSA key:
+
+          (genkey
+            (rsa
+              (nbits 4:2048)))
+
+     To create an Elgamal key, substitute "elg" for "rsa" and to create
+     a DSA key use "dsa".  Valid ranges for the key length depend on the
+     algorithms; all commonly used key lengths are supported.  Currently
+     supported parameters are:
+
+     '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.  Note that the S-expression syntax
+          requires that a number is prefixed with its string length;
+          thus the '4:' in the above example.
+
+     'curve NAME'
+          For ECC a named curve may be used instead of giving the number
+          of requested bits.  This allows to request a specific curve to
+          override a default selection Libgcrypt would have taken if
+          'nbits' has been given.  The available names are listed with
+          the description of the ECC public key parameters.
+
+     'rsa-use-e VALUE'
+          This is only used with RSA to give a hint for the public
+          exponent.  The VALUE will be used as a base to test for a
+          usable exponent.  Some values are special:
+
+          '0'
+               Use a secure and fast value.  This is currently the
+               number 41.
+          '1'
+               Use a value as required by some crypto policies.  This is
+               currently the number 65537.
+          '2'
+               Reserved
+          '> 2'
+               Use the given value.
+
+          If this parameter is not used, Libgcrypt uses for historic
+          reasons 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).
+
+     'qbits N'
+          This is only meanigful for DSA keys.  If it is given the DSA
+          key is generated with a Q parameyer of size N bits.  If it is
+          not given or zero Q is deduced from NBITS in this way:
+          '512 <= N <= 1024'
+               Q = 160
+          'N = 2048'
+               Q = 224
+          'N = 3072'
+               Q = 256
+          'N = 7680'
+               Q = 384
+          'N = 15360'
+               Q = 512
+          Note that in this case only the values for N, as given in the
+          table, 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.
+
+     'domain LIST'
+          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:
+
+               (genkey
+                 (dsa
+                   (domain
+                     (p P-MPI)
+                     (q Q-MPI)
+                     (g Q-MPI))))
+
+          'nbits' and 'qbits' may not be specified because they are
+          derived from the domain parameters.
+
+     'derive-parms LIST'
+          This is currently only implemented for RSA and DSA keys.  It
+          is not allowed to use this together with a '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.
+
+               (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#))))
+
+               (genkey
+                 (dsa
+                   (nbits 4:1024)
+                   (derive-parms
+                     (seed SEED-MPI))))
+
+     'flags FLAGLIST'
+          This is preferred way to define flags.  FLAGLIST may contain
+          any number of flags.  See above for a specification of these
+          flags.
+
+          Here is an example on how to create a key using curve Ed25519
+          with the ECDSA signature algorithm.  Note that the use of
+          ECDSA with that curve is in general not recommended.
+               (genkey
+                 (ecc
+                   (flags transient-key)))
+
+     'transient-key'
+     'use-x931'
+     'use-fips186'
+     'use-fips186-2'
+          These are deprecated ways to set a flag with that name; see
+          above for a description of each flag.
+
+     The key pair is returned in a format depending on the algorithm.
+     Both private and public keys are returned in one container and may
+     be accompanied by some miscellaneous information.
+
+     Here are two examples; the first for Elgamal and the second for
+     elliptic curve key generation:
+
+          (key-data
+            (public-key
+              (elg
+                (p P-MPI)
+                (g G-MPI)
+                (y Y-MPI)))
+            (private-key
+              (elg
+                (p P-MPI)
+                (g G-MPI)
+                (y Y-MPI)
+                (x X-MPI)))
+            (misc-key-info
+              (pm1-factors N1 N2 ... NN))
+
+          (key-data
+            (public-key
+              (ecc
+                (curve Ed25519)
+                (flags eddsa)
+                (q Q-VALUE)))
+            (private-key
+              (ecc
+                (curve Ed25519)
+                (flags eddsa)
+                (q Q-VALUE)
+                (d D-VALUE))))
+
+     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.  N1 N2 ... NN is a
+     list of prime numbers used to composite P-MPI; this is in general
+     not a very useful information and only available if the key
+     generation algorithm provides them.
+
+Future versions of Libgcrypt will have extended versions of the public
+key interfaced which will take an additional context to allow for
+pre-computations, special operations, and other optimization.  As a
+first step a new function is introduced to help using the ECC algorithms
+in new ways:
+
+ -- Function: gcry_error_t gcry_pubkey_get_sexp (gcry_sexp_t *R_SEXP,
+          int MODE, gcry_ctx_t CTX)
+
+     Return an S-expression representing the context CTX.  Depending on
+     the state of that context, the S-expression may either be a public
+     key, a private key or any other object used with public key
+     operations.  On success 0 is returned and a new S-expression is
+     stored at R_SEXP; on error an error code is returned and NULL is
+     stored at R_SEXP.  MODE must be one of:
+
+     '0'
+          Decide what to return depending on the context.  For example
+          if the private key parameter is available a private key is
+          returned, if not a public key is returned.
+
+     'GCRY_PK_GET_PUBKEY'
+          Return the public key even if the context has the private key
+          parameter.
+
+     'GCRY_PK_GET_SECKEY'
+          Return the private key or the error 'GPG_ERR_NO_SECKEY' if it
+          is not possible.
+
+     As of now this function supports only certain ECC operations
+     because a context object is right now only defined for ECC. Over
+     time this function will be extended to cover more algorithms.
+
+
+File: gcrypt.info,  Node: Hashing,  Next: Message Authentication Codes,  Prev: Public Key cryptography,  Up: Top
+
+7 Hashing
+*********
+
+Libgcrypt provides an easy and consistent to use interface for hashing.
+Hashing is buffered and several hash algorithms can be updated at once.
+It is possible to compute a HMAC using the same routines.  The
+programming model follows an open/process/close paradigm and is in that
+similar to other building blocks provided by Libgcrypt.
+
+   For convenience reasons, a few cyclic redundancy check value
+operations are also supported.
+
+* Menu:
+
+* Available hash algorithms::   List of hash algorithms supported by the library.
+* Working with hash algorithms::  List of functions related to hashing.
+
+
+File: gcrypt.info,  Node: Available hash algorithms,  Next: Working with hash algorithms,  Up: Hashing
+
+7.1 Available hash algorithms
+=============================
+
+'GCRY_MD_NONE'
+     This is not a real algorithm but used by some functions as an error
+     return value.  This constant is guaranteed to have the value '0'.
+
+'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.
+
+'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.
+     This algorithm share a lot of design properties with SHA-1 and thus
+     it is advisable not to use it for new protocols.
+
+'GCRY_MD_MD5'
+     This is the well known MD5 algorithm, which yields a message digest
+     of 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.
+
+'GCRY_MD_MD4'
+     This is the MD4 algorithm, which yields a message digest of 16
+     bytes.  This algorithm has severe weaknesses and should not be
+     used.
+
+'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.
+
+'GCRY_MD_TIGER'
+     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.
+
+'GCRY_MD_TIGER1'
+     This is the TIGER variant as used by the NESSIE project.  It uses
+     the most commonly used output print order.
+
+'GCRY_MD_TIGER2'
+     This is another variant of TIGER with a different padding scheme.
+
+'GCRY_MD_HAVAL'
+     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.
+
+'GCRY_MD_SHA224'
+     This is the SHA-224 algorithm which yields a message digest of 28
+     bytes.  See Change Notice 1 for FIPS 180-2 for the specification.
+
+'GCRY_MD_SHA256'
+     This is the SHA-256 algorithm which yields a message digest of 32
+     bytes.  See FIPS 180-2 for the specification.
+
+'GCRY_MD_SHA384'
+     This is the SHA-384 algorithm which yields a message digest of 48
+     bytes.  See FIPS 180-2 for the specification.
+
+'GCRY_MD_SHA512'
+     This is the SHA-384 algorithm which yields a message digest of 64
+     bytes.  See FIPS 180-2 for the specification.
+
+'GCRY_MD_SHA3_224'
+     This is the SHA3-224 algorithm which yields a message digest of 28
+     bytes.  See FIPS 202 for the specification.
+
+'GCRY_MD_SHA3_256'
+     This is the SHA3-256 algorithm which yields a message digest of 32
+     bytes.  See FIPS 202 for the specification.
+
+'GCRY_MD_SHA3_384'
+     This is the SHA3-384 algorithm which yields a message digest of 48
+     bytes.  See FIPS 202 for the specification.
+
+'GCRY_MD_SHA3_512'
+     This is the SHA3-512 algorithm which yields a message digest of 64
+     bytes.  See FIPS 202 for the specification.
+
+'GCRY_MD_SHAKE128'
+     This is the SHAKE128 extendable-output function (XOF) algorithm
+     with 128 bit security strength.  See FIPS 202 for the
+     specification.
+
+'GCRY_MD_SHAKE256'
+     This is the SHAKE256 extendable-output function (XOF) algorithm
+     with 256 bit security strength.  See FIPS 202 for the
+     specification.
+
+'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 cryptographic sense.
+
+'GCRY_MD_CRC32_RFC1510'
+     This is the above cyclic redundancy check function, as modified by
+     RFC 1510.  It yields an output of 4 bytes.  Note that this is not a
+     hash algorithm in the cryptographic sense.
+
+'GCRY_MD_CRC24_RFC2440'
+     This is the OpenPGP cyclic redundancy check function.  It yields an
+     output of 3 bytes.  Note that this is not a hash algorithm in the
+     cryptographic sense.
+
+'GCRY_MD_WHIRLPOOL'
+     This is the Whirlpool algorithm which yields a message digest of 64
+     bytes.
+
+'GCRY_MD_GOSTR3411_94'
+     This is the hash algorithm described in GOST R 34.11-94 which
+     yields a message digest of 32 bytes.
+
+'GCRY_MD_STRIBOG256'
+     This is the 256-bit version of hash algorithm described in GOST R
+     34.11-2012 which yields a message digest of 32 bytes.
+
+'GCRY_MD_STRIBOG512'
+     This is the 512-bit version of hash algorithm described in GOST R
+     34.11-2012 which yields a message digest of 64 bytes.
+
+'GCRY_MD_BLAKE2B_512'
+     This is the BLAKE2b-512 algorithm which yields a message digest of
+     64 bytes.  See RFC 7693 for the specification.
+
+'GCRY_MD_BLAKE2B_384'
+     This is the BLAKE2b-384 algorithm which yields a message digest of
+     48 bytes.  See RFC 7693 for the specification.
+
+'GCRY_MD_BLAKE2B_256'
+     This is the BLAKE2b-256 algorithm which yields a message digest of
+     32 bytes.  See RFC 7693 for the specification.
+
+'GCRY_MD_BLAKE2B_160'
+     This is the BLAKE2b-160 algorithm which yields a message digest of
+     20 bytes.  See RFC 7693 for the specification.
+
+'GCRY_MD_BLAKE2S_256'
+     This is the BLAKE2s-256 algorithm which yields a message digest of
+     32 bytes.  See RFC 7693 for the specification.
+
+'GCRY_MD_BLAKE2S_224'
+     This is the BLAKE2s-224 algorithm which yields a message digest of
+     28 bytes.  See RFC 7693 for the specification.
+
+'GCRY_MD_BLAKE2S_160'
+     This is the BLAKE2s-160 algorithm which yields a message digest of
+     20 bytes.  See RFC 7693 for the specification.
+
+'GCRY_MD_BLAKE2S_128'
+     This is the BLAKE2s-128 algorithm which yields a message digest of
+     16 bytes.  See RFC 7693 for the specification.
+
+
+File: gcrypt.info,  Node: Working with hash algorithms,  Prev: Available hash algorithms,  Up: Hashing
+
+7.2 Working with hash algorithms
+================================
+
+To use most of these function it is necessary to create a context; this
+is done using:
+
+ -- Function: gcry_error_t gcry_md_open (gcry_md_hd_t *HD, int ALGO,
+          unsigned int FLAGS)
+
+     Create a message digest object for algorithm ALGO.  FLAGS may be
+     given as an bitwise OR of constants described below.  ALGO may be
+     given as '0' if the algorithms to use are later set using
+     'gcry_md_enable'.  HD is guaranteed to either receive a valid
+     handle or NULL.
+
+     For a list of supported algorithms, see *note Available hash
+     algorithms::.
+
+     The flags allowed for MODE are:
+
+     'GCRY_MD_FLAG_SECURE'
+          Allocate all buffers and the resulting digest in "secure
+          memory".  Use this is the hashed data is highly confidential.
+
+     'GCRY_MD_FLAG_HMAC'
+          Turn the algorithm into a HMAC message authentication
+          algorithm.  This only works if just one algorithm is enabled
+          for the handle and that algorithm is not an extendable-output
+          function.  Note that the function '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 *note
+          Working with cipher handles::.
+
+     'GCRY_MD_FLAG_BUGEMU1'
+          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.
+
+     You may use the function 'gcry_md_is_enabled' to later check
+     whether an algorithm has been enabled.
+
+   If you want to calculate several hash algorithms at the same time,
+you have to use the following function right after the 'gcry_md_open':
+
+ -- Function: gcry_error_t gcry_md_enable (gcry_md_hd_t H, int ALGO)
+
+     Add the message digest algorithm ALGO to the digest object
+     described by handle H.  Duplicated enabling of algorithms is
+     detected and ignored.
+
+   If the flag 'GCRY_MD_FLAG_HMAC' was used, the key for the MAC must be
+set using the function:
+
+ -- Function: gcry_error_t gcry_md_setkey (gcry_md_hd_t H, const void
+          *KEY, size_t KEYLEN)
+
+     For use with the HMAC feature or BLAKE2 keyed hash, set the MAC key
+     to the value of KEY of length 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.
+
+   After you are done with the hash calculation, you should release the
+resources by using:
+
+ -- Function: void gcry_md_close (gcry_md_hd_t H)
+
+     Release all resources of hash context H.  H should not be used
+     after a call to this function.  A 'NULL' passed as H is ignored.
+     The function also zeroises all sensitive information associated
+     with this handle.
+
+   Often you have to do several hash operations using the same
+algorithm.  To avoid the overhead of creating and releasing context, a
+reset function is provided:
+
+ -- Function: void gcry_md_reset (gcry_md_hd_t H)
+
+     Reset the current context to its initial state.  This is
+     effectively identical to a close followed by an open and enabling
+     all currently active algorithms.
+
+   Often it is necessary to start hashing some data and then continue to
+hash different data.  To avoid hashing the same data several times
+(which might not even be possible if the data is received from a pipe),
+a snapshot of the current hash context can be taken and turned into a
+new context:
+
+ -- Function: gcry_error_t gcry_md_copy (gcry_md_hd_t *HANDLE_DST,
+          gcry_md_hd_t HANDLE_SRC)
+
+     Create a new digest object as an exact copy of the object described
+     by handle HANDLE_SRC and store it in HANDLE_DST.  The context is
+     not reset and you can continue to hash data using this context and
+     independently using the original context.
+
+   Now that we have prepared everything to calculate hashes, it is time
+to see how it is actually done.  There are two ways for this, one to
+update the hash with a block of memory and one macro to update the hash
+by just one character.  Both methods can be used on the same hash
+context.
+
+ -- Function: void gcry_md_write (gcry_md_hd_t H, const void *BUFFER,
+          size_t LENGTH)
+
+     Pass LENGTH bytes of the data in BUFFER to the digest object with
+     handle H to update the digest values.  This 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.
+
+ -- Function: void gcry_md_putc (gcry_md_hd_t H, int C)
+
+     Pass the byte in C to the digest object with handle H to update the
+     digest value.  This is an efficient function, implemented as a
+     macro to buffer the data before an actual update.
+
+   The semantics of the hash functions do not provide for reading out
+intermediate message digests because the calculation must be finalized
+first.  This finalization may for example include the number of bytes
+hashed in the message digest or some padding.
+
+ -- Function: void gcry_md_final (gcry_md_hd_t H)
+
+     Finalize the message digest calculation.  This is not really needed
+     because 'gcry_md_read' and 'gcry_md_extract' do this implicitly.
+     After this has been done no further updates (by means of
+     'gcry_md_write' or '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.
+
+   The way to read out the calculated message digest is by using the
+function:
+
+ -- Function: unsigned char * gcry_md_read (gcry_md_hd_t H, int ALGO)
+
+     'gcry_md_read' returns the message digest after finalizing the
+     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 reset-ed (using
+     'gcry_md_close' or 'gcry_md_reset' or it has been updated as a
+     mitigation measure against timing attacks.  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 'NULL' if the
+     requested algorithm has not been enabled.
+
+   The way to read output of extendable-output function is by using the
+function:
+
+ -- Function: gpg_err_code_t gcry_md_extract (gcry_md_hd_t H, int ALGO,
+          void *BUFFER, size_t LENGTH)
+
+     '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 BUFFER of the length LENGTH.  Buffer will be fully
+     populated with new output.  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.
+
+   Because it is often necessary to get the message digest of blocks of
+memory, two fast convenience function are available for this task:
+
+ -- Function: gpg_err_code_t gcry_md_hash_buffers ( int ALGO,
+          unsigned int FLAGS, void *DIGEST, const gcry_buffer_t *IOV,
+          int IOVCNT )
+
+     '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 the
+     data described by IOV and IOVCNT.  DIGEST must be allocated by the
+     caller, large enough to hold the message digest yielded by the the
+     specified algorithm ALGO.  This required size may be obtained by
+     using the function 'gcry_md_get_algo_dlen'.
+
+     IOV is an array of buffer descriptions with IOVCNT items.  The
+     caller should zero out the structures in this array and for each
+     array item set the fields '.data' to the address of the data to be
+     hashed, '.len' to number of bytes to be hashed.  If .OFF is also
+     set, the data is taken starting at .OFF bytes from the begin of the
+     buffer.  The field '.size' is not used.
+
+     The only supported flag value for FLAGS is GCRY_MD_FLAG_HMAC which
+     turns this function into a HMAC function; the first item in IOV is
+     then used as the key.
+
+     On success the function returns 0 and stores the resulting hash or
+     MAC at DIGEST.
+
+ -- Function: void gcry_md_hash_buffer (int ALGO, void *DIGEST, const
+          void *BUFFER, size_t LENGTH);
+
+     'gcry_md_hash_buffer' is a shortcut function to calculate a message
+     digest of a buffer.  This function does not require a context and
+     immediately returns the message digest of the LENGTH bytes at
+     BUFFER.  DIGEST must be allocated by the caller, large enough to
+     hold the message digest yielded by the the specified algorithm
+     ALGO.  This required size may be obtained by using the function
+     'gcry_md_get_algo_dlen'.
+
+     Note that in contrast to 'gcry_md_hash_buffers' this function will
+     abort the process if an unavailable algorithm is used.
+
+   Hash algorithms are identified by internal algorithm numbers (see
+'gcry_md_open' for a list).  However, in most applications they are used
+by names, so two functions are available to map between string
+representations and hash algorithm identifiers.
+
+ -- Function: const char * gcry_md_algo_name (int ALGO)
+
+     Map the digest algorithm id ALGO to a string representation of the
+     algorithm name.  For unknown algorithms this function returns the
+     string '"?"'.  This function should not be used to test for the
+     availability of an algorithm.
+
+ -- Function: int gcry_md_map_name (const char *NAME)
+
+     Map the algorithm with NAME to a digest algorithm identifier.
+     Returns 0 if the algorithm name is not known.  Names representing
+     ASN.1 object identifiers are recognized if the IETF dotted format
+     is used and the OID is prefixed with either "'oid.'" or "'OID.'".
+     For a list of supported OIDs, see the source code at 'cipher/md.c'.
+     This function should not be used to test for the availability of an
+     algorithm.
+
+ -- Function: gcry_error_t gcry_md_get_asnoid (int ALGO, void *BUFFER,
+          size_t *LENGTH)
+
+     Return an DER encoded ASN.1 OID for the algorithm ALGO in the user
+     allocated BUFFER.  LENGTH must point to variable with the available
+     size of BUFFER and receives after return the actual size of the
+     returned OID. The returned error code may be 'GPG_ERR_TOO_SHORT' if
+     the provided buffer is to short to receive the OID; it is possible
+     to call the function with 'NULL' for BUFFER to have it only return
+     the required size.  The function returns 0 on success.
+
+   To test whether an algorithm is actually available for use, the
+following macro should be used:
+
+ -- Function: gcry_error_t gcry_md_test_algo (int ALGO)
+
+     The macro returns 0 if the algorithm ALGO is available for use.
+
+   If the length of a message digest is not known, it can be retrieved
+using the following function:
+
+ -- Function: unsigned int gcry_md_get_algo_dlen (int ALGO)
+
+     Retrieve the length in bytes of the digest yielded by algorithm
+     ALGO.  This is often used prior to 'gcry_md_read' to allocate
+     sufficient memory for the digest.
+
+   In some situations it might be hard to remember the algorithm used
+for the ongoing hashing.  The following function might be used to get
+that information:
+
+ -- Function: int gcry_md_get_algo (gcry_md_hd_t H)
+
+     Retrieve the algorithm used with the handle H.  Note that this does
+     not work reliable if more than one algorithm is enabled in H.
+
+   The following macro might also be useful:
+
+ -- Function: int gcry_md_is_secure (gcry_md_hd_t H)
+
+     This function returns true when the digest object H is allocated in
+     "secure memory"; i.e.  H was created with the
+     'GCRY_MD_FLAG_SECURE'.
+
+ -- Function: int gcry_md_is_enabled (gcry_md_hd_t H, int ALGO)
+
+     This function returns true when the algorithm ALGO has been enabled
+     for the digest object H.
+
+   Tracking bugs related to hashing is often a cumbersome task which
+requires to add a lot of printf statements into the code.  Libgcrypt
+provides an easy way to avoid this.  The actual data hashed can be
+written to files on request.
+
+ -- Function: void gcry_md_debug (gcry_md_hd_t H, const char *SUFFIX)
+
+     Enable debugging for the digest object with handle H.  This creates
+     files named 'dbgmd-<n>.<string>' while doing the actual hashing.
+     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 'gcry_md_write' or 'gcry_md_putc'.  If 'NULL' is
+     used for SUFFIX, the debugging is stopped and the file closed.
+     This is only rarely required because 'gcry_md_close' implicitly
+     stops debugging.
+
+
+File: gcrypt.info,  Node: Message Authentication Codes,  Next: Key Derivation,  Prev: Hashing,  Up: Top
+
+8 Message Authentication Codes
+******************************
+
+Libgcrypt provides an easy and consistent to use interface for
+generating Message Authentication Codes (MAC). MAC generation is
+buffered and interface similar to the one used with hash algorithms.
+The programming model follows an open/process/close paradigm and is in
+that similar to other building blocks provided by Libgcrypt.
+
+* Menu:
+
+* Available MAC algorithms::   List of MAC algorithms supported by the library.
+* Working with MAC algorithms::  List of functions related to MAC algorithms.
+
+
+File: gcrypt.info,  Node: Available MAC algorithms,  Next: Working with MAC algorithms,  Up: Message Authentication Codes
+
+8.1 Available MAC algorithms
+============================
+
+'GCRY_MAC_NONE'
+     This is not a real algorithm but used by some functions as an error
+     return value.  This constant is guaranteed to have the value '0'.
+
+'GCRY_MAC_HMAC_SHA256'
+     This is keyed-hash message authentication code (HMAC) message
+     authentication algorithm based on the SHA-256 hash algorithm.
+
+'GCRY_MAC_HMAC_SHA224'
+     This is HMAC message authentication algorithm based on the SHA-224
+     hash algorithm.
+
+'GCRY_MAC_HMAC_SHA512'
+     This is HMAC message authentication algorithm based on the SHA-512
+     hash algorithm.
+
+'GCRY_MAC_HMAC_SHA384'
+     This is HMAC message authentication algorithm based on the SHA-384
+     hash algorithm.
+
+'GCRY_MAC_HMAC_SHA3_256'
+     This is HMAC message authentication algorithm based on the SHA3-256
+     hash algorithm.
+
+'GCRY_MAC_HMAC_SHA3_224'
+     This is HMAC message authentication algorithm based on the SHA3-224
+     hash algorithm.
+
+'GCRY_MAC_HMAC_SHA3_512'
+     This is HMAC message authentication algorithm based on the SHA3-512
+     hash algorithm.
+
+'GCRY_MAC_HMAC_SHA3_384'
+     This is HMAC message authentication algorithm based on the SHA3-384
+     hash algorithm.
+
+'GCRY_MAC_HMAC_SHA1'
+     This is HMAC message authentication algorithm based on the SHA-1
+     hash algorithm.
+
+'GCRY_MAC_HMAC_MD5'
+     This is HMAC message authentication algorithm based on the MD5 hash
+     algorithm.
+
+'GCRY_MAC_HMAC_MD4'
+     This is HMAC message authentication algorithm based on the MD4 hash
+     algorithm.
+
+'GCRY_MAC_HMAC_RMD160'
+     This is HMAC message authentication algorithm based on the
+     RIPE-MD-160 hash algorithm.
+
+'GCRY_MAC_HMAC_WHIRLPOOL'
+     This is HMAC message authentication algorithm based on the
+     WHIRLPOOL hash algorithm.
+
+'GCRY_MAC_HMAC_GOSTR3411_94'
+     This is HMAC message authentication algorithm based on the GOST R
+     34.11-94 hash algorithm.
+
+'GCRY_MAC_HMAC_STRIBOG256'
+     This is HMAC message authentication algorithm based on the 256-bit
+     hash algorithm described in GOST R 34.11-2012.
+
+'GCRY_MAC_HMAC_STRIBOG512'
+     This is HMAC message authentication algorithm based on the 512-bit
+     hash algorithm described in GOST R 34.11-2012.
+
+'GCRY_MAC_CMAC_AES'
+     This is CMAC (Cipher-based MAC) message authentication algorithm
+     based on the AES block cipher algorithm.
+
+'GCRY_MAC_CMAC_3DES'
+     This is CMAC message authentication algorithm based on the
+     three-key EDE Triple-DES block cipher algorithm.
+
+'GCRY_MAC_CMAC_CAMELLIA'
+     This is CMAC message authentication algorithm based on the Camellia
+     block cipher algorithm.
+
+'GCRY_MAC_CMAC_CAST5'
+     This is CMAC message authentication algorithm based on the
+     CAST128-5 block cipher algorithm.
+
+'GCRY_MAC_CMAC_BLOWFISH'
+     This is CMAC message authentication algorithm based on the Blowfish
+     block cipher algorithm.
+
+'GCRY_MAC_CMAC_TWOFISH'
+     This is CMAC message authentication algorithm based on the Twofish
+     block cipher algorithm.
+
+'GCRY_MAC_CMAC_SERPENT'
+     This is CMAC message authentication algorithm based on the Serpent
+     block cipher algorithm.
+
+'GCRY_MAC_CMAC_SEED'
+     This is CMAC message authentication algorithm based on the SEED
+     block cipher algorithm.
+
+'GCRY_MAC_CMAC_RFC2268'
+     This is CMAC message authentication algorithm based on the Ron's
+     Cipher 2 block cipher algorithm.
+
+'GCRY_MAC_CMAC_IDEA'
+     This is CMAC message authentication algorithm based on the IDEA
+     block cipher algorithm.
+
+'GCRY_MAC_CMAC_GOST28147'
+     This is CMAC message authentication algorithm based on the GOST
+     28147-89 block cipher algorithm.
+
+'GCRY_MAC_GMAC_AES'
+     This is GMAC (GCM mode based MAC) message authentication algorithm
+     based on the AES block cipher algorithm.
+
+'GCRY_MAC_GMAC_CAMELLIA'
+     This is GMAC message authentication algorithm based on the Camellia
+     block cipher algorithm.
+
+'GCRY_MAC_GMAC_TWOFISH'
+     This is GMAC message authentication algorithm based on the Twofish
+     block cipher algorithm.
+
+'GCRY_MAC_GMAC_SERPENT'
+     This is GMAC message authentication algorithm based on the Serpent
+     block cipher algorithm.
+
+'GCRY_MAC_GMAC_SEED'
+     This is GMAC message authentication algorithm based on the SEED
+     block cipher algorithm.
+
+'GCRY_MAC_POLY1305'
+     This is plain Poly1305 message authentication algorithm, used with
+     one-time key.
+
+'GCRY_MAC_POLY1305_AES'
+     This is Poly1305-AES message authentication algorithm, used with
+     key and one-time nonce.
+
+'GCRY_MAC_POLY1305_CAMELLIA'
+     This is Poly1305-Camellia message authentication algorithm, used
+     with key and one-time nonce.
+
+'GCRY_MAC_POLY1305_TWOFISH'
+     This is Poly1305-Twofish message authentication algorithm, used
+     with key and one-time nonce.
+
+'GCRY_MAC_POLY1305_SERPENT'
+     This is Poly1305-Serpent message authentication algorithm, used
+     with key and one-time nonce.
+
+'GCRY_MAC_POLY1305_SEED'
+     This is Poly1305-SEED message authentication algorithm, used with
+     key and one-time nonce.
+
+
+File: gcrypt.info,  Node: Working with MAC algorithms,  Prev: Available MAC algorithms,  Up: Message Authentication Codes
+
+8.2 Working with MAC algorithms
+===============================
+
+To use most of these function it is necessary to create a context; this
+is done using:
+
+ -- Function: gcry_error_t gcry_mac_open (gcry_mac_hd_t *HD, int ALGO,
+          unsigned int FLAGS, gcry_ctx_t CTX)
+
+     Create a MAC object for algorithm ALGO.  FLAGS may be given as an
+     bitwise OR of constants described below.  HD is guaranteed to
+     either receive a valid handle or NULL. CTX is context object to
+     associate MAC object with.  CTX maybe set to NULL.
+
+     For a list of supported algorithms, see *note Available MAC
+     algorithms::.
+
+     The flags allowed for MODE are:
+
+     'GCRY_MAC_FLAG_SECURE'
+          Allocate all buffers and the resulting MAC in "secure memory".
+          Use this if the MAC data is highly confidential.
+
+   In order to use a handle for performing MAC algorithm operations, a
+'key' has to be set first:
+
+ -- Function: gcry_error_t gcry_mac_setkey (gcry_mac_hd_t H, const void
+          *KEY, size_t KEYLEN)
+
+     Set the MAC key to the value of KEY of length KEYLEN bytes.  With
+     HMAC algorithms, there is no restriction on the length of the key.
+     With CMAC algorithms, the length of the key is restricted to those
+     supported by the underlying block cipher.
+
+   GMAC algorithms and Poly1305-with-cipher algorithms need
+initialization vector to be set, which can be performed with function:
+
+ -- Function: gcry_error_t gcry_mac_setiv (gcry_mac_hd_t H, const void
+          *IV, size_t IVLEN)
+
+     Set the IV to the value of IV of length IVLEN bytes.
+
+   After you are done with the MAC calculation, you should release the
+resources by using:
+
+ -- Function: void gcry_mac_close (gcry_mac_hd_t H)
+
+     Release all resources of MAC context H.  H should not be used after
+     a call to this function.  A 'NULL' passed as H is ignored.  The
+     function also clears all sensitive information associated with this
+     handle.
+
+   Often you have to do several MAC operations using the same algorithm.
+To avoid the overhead of creating and releasing context, a reset
+function is provided:
+
+ -- Function: gcry_error_t gcry_mac_reset (gcry_mac_hd_t H)
+
+     Reset the current context to its initial state.  This is
+     effectively identical to a close followed by an open and setting
+     same key.
+
+     Note that gcry_mac_reset is implemented as a macro.
+
+   Now that we have prepared everything to calculate MAC, it is time to
+see how it is actually done.
+
+ -- Function: gcry_error_t gcry_mac_write (gcry_mac_hd_t H, const void
+          *BUFFER, size_t LENGTH)
+
+     Pass LENGTH bytes of the data in BUFFER to the MAC object with
+     handle 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.
+
+   The way to read out the calculated MAC is by using the function:
+
+ -- Function: gcry_error_t gcry_mac_read (gcry_mac_hd_t H, void *BUFFER,
+          size_t *LENGTH)
+
+     'gcry_mac_read' returns the MAC after finalizing the calculation.
+     Function copies the resulting MAC value to BUFFER of the length
+     LENGTH.  If LENGTH is larger than length of resulting MAC value,
+     then length of MAC is returned through LENGTH.
+
+   To compare existing MAC value with recalculated MAC, one is to use
+the function:
+
+ -- Function: gcry_error_t gcry_mac_verify (gcry_mac_hd_t H, void
+          *BUFFER, size_t LENGTH)
+
+     'gcry_mac_verify' finalizes MAC calculation and compares result
+     with LENGTH bytes of data in BUFFER.  Error code 'GPG_ERR_CHECKSUM'
+     is returned if the MAC value in the buffer BUFFER does not match
+     the MAC calculated in object H.
+
+   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:
+
+ -- Function: int gcry_mac_get_algo (gcry_mac_hd_t H)
+
+     Retrieve the algorithm used with the handle H.
+
+   MAC algorithms are identified by internal algorithm numbers (see
+'gcry_mac_open' for a list).  However, in most applications they are
+used by names, so two functions are available to map between string
+representations and MAC algorithm identifiers.
+
+ -- Function: const char * gcry_mac_algo_name (int ALGO)
+
+     Map the MAC algorithm id ALGO to a string representation of the
+     algorithm name.  For unknown algorithms this function returns the
+     string '"?"'.  This function should not be used to test for the
+     availability of an algorithm.
+
+ -- Function: int gcry_mac_map_name (const char *NAME)
+
+     Map the algorithm with NAME to a MAC algorithm identifier.  Returns
+     0 if the algorithm name is not known.  This function should not be
+     used to test for the availability of an algorithm.
+
+   To test whether an algorithm is actually available for use, the
+following macro should be used:
+
+ -- Function: gcry_error_t gcry_mac_test_algo (int ALGO)
+
+     The macro returns 0 if the MAC algorithm ALGO is available for use.
+
+   If the length of a message digest is not known, it can be retrieved
+using the following function:
+
+ -- Function: unsigned int gcry_mac_get_algo_maclen (int ALGO)
+
+     Retrieve the length in bytes of the MAC yielded by algorithm ALGO.
+     This is often used prior to 'gcry_mac_read' to allocate sufficient
+     memory for the MAC value.  On error '0' is returned.
+
+ -- Function: unsigned int gcry_mac_get_algo_keylen (ALGO)
+
+     This function returns length of the key for MAC algorithm ALGO.  If
+     the algorithm supports multiple key lengths, the default supported
+     key length is returned.  On error '0' is returned.  The key length
+     is returned as number of octets.
+
+
+File: gcrypt.info,  Node: Key Derivation,  Next: Random Numbers,  Prev: Message Authentication Codes,  Up: Top
+
+9 Key Derivation
+****************
+
+Libgcypt provides a general purpose function to derive keys from
+strings.
+
+ -- Function: gpg_error_t gcry_kdf_derive ( const void *PASSPHRASE,
+          size_t PASSPHRASELEN, int ALGO, int SUBALGO, const void *SALT,
+          size_t SALTLEN, unsigned long ITERATIONS, size_t KEYSIZE,
+          void *KEYBUFFER )
+
+     Derive a key from a passphrase.  KEYSIZE gives the requested size
+     of the keys in octets.  KEYBUFFER is a caller provided buffer
+     filled on success with the derived key.  The input passphrase is
+     taken from PASSPHRASE which is an arbitrary memory buffer of
+     PASSPHRASELEN octets.  ALGO specifies the KDF algorithm to use; see
+     below.  SUBALGO specifies an algorithm used internally by the KDF
+     algorithms; this is usually a hash algorithm but certain KDF
+     algorithms may use it differently.  SALT is a salt of length
+     SALTLEN octets, as needed by most KDF algorithms.  ITERATIONS is a
+     positive integer parameter to most KDFs.
+
+     On success 0 is returned; on failure an error code.
+
+     Currently supported KDFs (parameter ALGO):
+
+     'GCRY_KDF_SIMPLE_S2K'
+          The OpenPGP simple S2K algorithm (cf.  RFC4880).  Its use is
+          strongly deprecated.  SALT and ITERATIONS are not needed and
+          may be passed as 'NULL'/'0'.
+
+     'GCRY_KDF_SALTED_S2K'
+          The OpenPGP salted S2K algorithm (cf.  RFC4880).  Usually not
+          used.  ITERATIONS is not needed and may be passed as '0'.
+          SALTLEN must be given as 8.
+
+     'GCRY_KDF_ITERSALTED_S2K'
+          The OpenPGP iterated+salted S2K algorithm (cf.  RFC4880).
+          This is the default for most OpenPGP applications.  SALTLEN
+          must be given as 8.  Note that OpenPGP defines a special
+          encoding of the ITERATIONS; however this function takes the
+          plain decoded iteration count.
+
+     'GCRY_KDF_PBKDF2'
+          The PKCS#5 Passphrase Based Key Derivation Function number 2.
+
+     'GCRY_KDF_SCRYPT'
+          The SCRYPT Key Derivation Function.  The subalgorithm is used
+          to specify the CPU/memory cost parameter N, and the number of
+          iterations is used for the parallelization parameter p.  The
+          block size is fixed at 8 in the current implementation.
+
+
+File: gcrypt.info,  Node: Random Numbers,  Next: S-expressions,  Prev: Key Derivation,  Up: Top
+
+10 Random Numbers
+*****************
+
+* Menu:
+
+* Quality of random numbers::   Libgcrypt uses different quality levels.
+* Retrieving random numbers::   How to retrieve random numbers.
+
+
+File: gcrypt.info,  Node: Quality of random numbers,  Next: Retrieving random numbers,  Up: Random Numbers
+
+10.1 Quality of random numbers
+==============================
+
+Libgcypt offers random numbers of different quality levels:
+
+ -- Data type: gcry_random_level_t
+     The constants for the random quality levels are of this enum type.
+
+'GCRY_WEAK_RANDOM'
+     For all functions, except for 'gcry_mpi_randomize', this level maps
+     to GCRY_STRONG_RANDOM. If you do not want this, consider using
+     'gcry_create_nonce'.
+'GCRY_STRONG_RANDOM'
+     Use this level for session keys and similar purposes.
+'GCRY_VERY_STRONG_RANDOM'
+     Use this level for long term key material.
+
+
+File: gcrypt.info,  Node: Retrieving random numbers,  Prev: Quality of random numbers,  Up: Random Numbers
+
+10.2 Retrieving random numbers
+==============================
+
+ -- Function: void gcry_randomize (unsigned char *BUFFER, size_t LENGTH,
+          enum gcry_random_level LEVEL)
+
+     Fill BUFFER with LENGTH random bytes using a random quality as
+     defined by LEVEL.
+
+ -- Function: void * gcry_random_bytes (size_t NBYTES, enum
+          gcry_random_level LEVEL)
+
+     Convenience function to allocate a memory block consisting of
+     NBYTES fresh random bytes using a random quality as defined by
+     LEVEL.
+
+ -- Function: void * gcry_random_bytes_secure (size_t NBYTES, enum
+          gcry_random_level LEVEL)
+
+     Convenience function to allocate a memory block consisting of
+     NBYTES fresh random bytes using a random quality as defined by
+     LEVEL.  This function differs from 'gcry_random_bytes' in that the
+     returned buffer is allocated in a "secure" area of the memory.
+
+ -- Function: void gcry_create_nonce (unsigned char *BUFFER, size_t
+          LENGTH)
+
+     Fill BUFFER with LENGTH unpredictable bytes.  This is commonly
+     called a nonce and may also be used for initialization vectors and
+     padding.  This is an extra function nearly independent of the other
+     random function for 3 reasons: It better protects the regular
+     random generator's internal state, provides better performance and
+     does not drain the precious entropy pool.
+
+
+File: gcrypt.info,  Node: S-expressions,  Next: MPI library,  Prev: Random Numbers,  Up: Top
+
+11 S-expressions
+****************
+
+S-expressions are used by the public key functions to pass complex data
+structures around.  These LISP like objects are used by some
+cryptographic protocols (cf.  RFC-2692) and Libgcrypt provides functions
+to parse and construct them.  For detailed information, see 'Ron Rivest,
+code and description of S-expressions,
+<http://theory.lcs.mit.edu/~rivest/sexp.html>'.
+
+* Menu:
+
+* Data types for S-expressions::  Data types related with S-expressions.
+* Working with S-expressions::  How to work with S-expressions.
+
+
+File: gcrypt.info,  Node: Data types for S-expressions,  Next: Working with S-expressions,  Up: S-expressions
+
+11.1 Data types for S-expressions
+=================================
+
+ -- Data type: gcry_sexp_t
+     The 'gcry_sexp_t' type describes an object with the Libgcrypt
+     internal representation of an S-expression.
+
+
+File: gcrypt.info,  Node: Working with S-expressions,  Prev: Data types for S-expressions,  Up: S-expressions
+
+11.2 Working with S-expressions
+===============================
+
+There are several functions to create an Libgcrypt S-expression object
+from its external representation or from a string template.  There is
+also a function to convert the internal representation back into one of
+the external formats:
+
+ -- Function: gcry_error_t gcry_sexp_new (gcry_sexp_t *R_SEXP,
+          const void *BUFFER, size_t LENGTH, int AUTODETECT)
+
+     This is the generic function to create an new S-expression object
+     from its external representation in BUFFER of LENGTH bytes.  On
+     success the result is stored at the address given by R_SEXP.  With
+     AUTODETECT set to 0, the data in BUFFER is expected to be in
+     canonized format, with AUTODETECT set to 1 the parses any of the
+     defined external formats.  If BUFFER does not hold a valid
+     S-expression an error code is returned and R_SEXP set to 'NULL'.
+     Note that the caller is responsible for releasing the newly
+     allocated S-expression using 'gcry_sexp_release'.
+
+ -- Function: gcry_error_t gcry_sexp_create (gcry_sexp_t *R_SEXP,
+          void *BUFFER, size_t LENGTH, int AUTODETECT,
+          void (*FREEFNC)(void*))
+
+     This function is identical to 'gcry_sexp_new' but has an extra
+     argument FREEFNC, which, when not set to 'NULL', is expected to be
+     a function to release the BUFFER; most likely the standard 'free'
+     function is used for this argument.  This has the effect of
+     transferring the ownership of BUFFER to the created object in
+     R_SEXP.  The advantage of using this function is that Libgcrypt
+     might decide to directly use the provided buffer and thus avoid
+     extra copying.
+
+ -- Function: gcry_error_t gcry_sexp_sscan (gcry_sexp_t *R_SEXP,
+          size_t *ERROFF, const char *BUFFER, size_t LENGTH)
+
+     This is another variant of the above functions.  It behaves nearly
+     identical but provides an ERROFF argument which will receive the
+     offset into the buffer where the parsing stopped on error.
+
+ -- Function: gcry_error_t gcry_sexp_build (gcry_sexp_t *R_SEXP,
+          size_t *ERROFF, const char *FORMAT, ...)
+
+     This function creates an internal S-expression from the string
+     template FORMAT and stores it at the address of R_SEXP.  If there
+     is a parsing error, the function returns an appropriate error code
+     and stores the offset into FORMAT where the parsing stopped in
+     ERROFF.  The function supports a couple of printf-like formatting
+     characters and expects arguments for some of these escape sequences
+     right after FORMAT.  The following format characters are defined:
+
+     '%m'
+          The next argument is expected to be of type 'gcry_mpi_t' and a
+          copy of its value is inserted into the resulting S-expression.
+          The MPI is stored as a signed integer.
+     '%M'
+          The next argument is expected to be of type 'gcry_mpi_t' and a
+          copy of its value is inserted into the resulting S-expression.
+          The MPI is stored as an unsigned integer.
+     '%s'
+          The next argument is expected to be of type 'char *' and that
+          string is inserted into the resulting S-expression.
+     '%d'
+          The next argument is expected to be of type 'int' and its
+          value is inserted into the resulting S-expression.
+     '%u'
+          The next argument is expected to be of type 'unsigned int' and
+          its value is inserted into the resulting S-expression.
+     '%b'
+          The next argument is expected to be of type 'int' directly
+          followed by an argument of type 'char *'.  This represents a
+          buffer of given length to be inserted into the resulting
+          S-expression.
+     '%S'
+          The next argument is expected to be of type '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.
+
+     No other format characters are defined and would return an error.
+     Note that the format character '%%' does not exists, because a
+     percent sign is not a valid character in an S-expression.
+
+ -- Function: void gcry_sexp_release (gcry_sexp_t SEXP)
+
+     Release the S-expression object 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.
+
+The next 2 functions are used to convert the internal representation
+back into a regular external S-expression format and to show the
+structure for debugging.
+
+ -- Function: size_t gcry_sexp_sprint (gcry_sexp_t SEXP, int MODE,
+          char *BUFFER, size_t MAXLENGTH)
+
+     Copies the S-expression object SEXP into BUFFER using the format
+     specified in MODE.  MAXLENGTH must be set to the allocated length
+     of BUFFER.  The function returns the actual length of valid bytes
+     put into BUFFER or 0 if the provided buffer is too short.  Passing
+     'NULL' for BUFFER returns the required length for BUFFER.  For
+     convenience reasons an extra byte with value 0 is appended to the
+     buffer.
+
+     The following formats are supported:
+
+     'GCRYSEXP_FMT_DEFAULT'
+          Returns a convenient external S-expression representation.
+
+     'GCRYSEXP_FMT_CANON'
+          Return the S-expression in canonical format.
+
+     'GCRYSEXP_FMT_BASE64'
+          Not currently supported.
+
+     'GCRYSEXP_FMT_ADVANCED'
+          Returns the S-expression in advanced format.
+
+ -- Function: void gcry_sexp_dump (gcry_sexp_t SEXP)
+
+     Dumps SEXP in a format suitable for debugging to Libgcrypt's
+     logging stream.
+
+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.
+
+ -- Function: size_t gcry_sexp_canon_len (const unsigned char *BUFFER,
+          size_t LENGTH, size_t *ERROFF, int *ERRCODE)
+
+     Scan the canonical encoded BUFFER with implicit length values and
+     return the actual length this S-expression uses.  For a valid
+     S-expression it should never return 0.  If LENGTH is not 0, the
+     maximum length to scan is given; this can be used for syntax checks
+     of data passed from outside.  ERRCODE and ERROFF may both be passed
+     as 'NULL'.
+
+There are functions to parse S-expressions and retrieve elements:
+
+ -- Function: gcry_sexp_t gcry_sexp_find_token (const gcry_sexp_t LIST,
+          const char *TOKEN, size_t TOKLEN)
+
+     Scan the S-expression for a sublist with a type (the car of the
+     list) matching the string TOKEN.  If TOKLEN is not 0, the token is
+     assumed to be raw memory of this length.  The function returns a
+     newly allocated S-expression consisting of the found sublist or
+     'NULL' when not found.
+
+ -- Function: int gcry_sexp_length (const gcry_sexp_t LIST)
+
+     Return the length of the LIST.  For a valid S-expression this
+     should be at least 1.
+
+ -- Function: gcry_sexp_t gcry_sexp_nth (const gcry_sexp_t LIST,
+          int NUMBER)
+
+     Create and return a new S-expression from the element with index
+     NUMBER in LIST.  Note that the first element has the index 0.  If
+     there is no such element, 'NULL' is returned.
+
+ -- Function: gcry_sexp_t gcry_sexp_car (const gcry_sexp_t LIST)
+
+     Create and return a new S-expression from the first element in
+     LIST; this is called the "type" and should always exist per
+     S-expression specification and in general be a string.  'NULL' is
+     returned in case of a problem.
+
+ -- Function: gcry_sexp_t gcry_sexp_cdr (const gcry_sexp_t LIST)
+
+     Create and return a new list form all elements except for the first
+     one.  Note that this function may return an invalid S-expression
+     because it is not guaranteed, that the type exists and is a string.
+     However, for parsing a complex S-expression it might be useful for
+     intermediate lists.  Returns 'NULL' on error.
+
+ -- Function: const char * gcry_sexp_nth_data (const gcry_sexp_t LIST,
+          int NUMBER, size_t *DATALEN)
+
+     This function is used to get data from a LIST.  A pointer to the
+     actual data with index NUMBER is returned and the length of this
+     data will be stored to DATALEN.  If there is no data at the given
+     index or the index represents another list, 'NULL' is returned.
+     *Caution:* The returned pointer is valid as long as LIST is not
+     modified or released.
+
+     Here is an example on how to extract and print the surname (Meier)
+     from the S-expression '(Name Otto Meier (address Burgplatz 3))':
+
+          size_t len;
+          const char *name;
+
+          name = gcry_sexp_nth_data (list, 2, &len);
+          printf ("my name is %.*s\n", (int)len, name);
+
+ -- Function: void * gcry_sexp_nth_buffer (const gcry_sexp_t LIST,
+          int NUMBER, size_t *RLENGTH)
+
+     This function is used to get data from a LIST.  A malloced buffer
+     with the actual data at list index NUMBER is returned and the
+     length of this buffer will be stored to RLENGTH.  If there is no
+     data at the given index or the index represents another list,
+     'NULL' is returned.  The caller must release the result using
+     'gcry_free'.
+
+     Here is an example on how to extract and print the CRC value from
+     the S-expression '(hash crc32 #23ed00d7)':
+
+          size_t len;
+          char *value;
+
+          value = gcry_sexp_nth_buffer (list, 2, &len);
+          if (value)
+            fwrite (value, len, 1, stdout);
+          gcry_free (value);
+
+ -- Function: char * gcry_sexp_nth_string (gcry_sexp_t LIST, int NUMBER)
+
+     This function is used to get and convert data from a LIST.  The
+     data is assumed to be a Nul terminated string.  The caller must
+     release this returned value using 'gcry_free'.  If there is no data
+     at the given index, the index represents a list or the value can't
+     be converted to a string, 'NULL' is returned.
+
+ -- Function: gcry_mpi_t gcry_sexp_nth_mpi (gcry_sexp_t LIST,
+          int NUMBER, int MPIFMT)
+
+     This function is used to get and convert data from a LIST.  This
+     data is assumed to be an MPI stored in the format described by
+     MPIFMT and returned as a standard Libgcrypt MPI. The caller must
+     release this returned value using 'gcry_mpi_release'.  If there is
+     no data at the given index, the index represents a list or the
+     value can't be converted to an MPI, 'NULL' is returned.  If you use
+     this function to parse results of a public key function, you most
+     likely want to use 'GCRYMPI_FMT_USG'.
+
+ -- Function: gpg_error_t gcry_sexp_extract_param ( gcry_sexp_t SEXP,
+          const char *PATH, const char *LIST, ...)
+
+     Extract parameters from an S-expression using a list of parameter
+     names.  The names of these parameters are specified in LIST. White
+     space between the parameter names are ignored.  Some special
+     characters may be given to control the conversion:
+
+     '+'
+          Switch to unsigned integer format (GCRYMPI_FMT_USG). This is
+          the default mode.
+     '-'
+          Switch to standard signed format (GCRYMPI_FMT_STD).
+     '/'
+          Switch to opaque MPI format.  The resulting MPIs may not be
+          used for computations; see 'gcry_mpi_get_opaque' for details.
+     '&'
+          Switch to buffer descriptor mode.  See below for details.
+     '?'
+          If immediately following a parameter letter (no white space
+          allowed), that parameter is considered optional.
+
+     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 'gcry_mpi_t' variable is expected that must be set to 'NULL'
+     prior to invoking this function, and finally a 'NULL' is expected.
+     For example
+
+            gcry_sexp_extract_param (key, NULL, "n/x+e d-'foo'",
+                                     &mpi_n, &mpi_x, &mpi_e, &mpi_d, &mpi_foo, NULL)
+
+     stores the parameter 'n' from KEY as an unsigned MPI into MPI_N,
+     the parameter 'x' as an opaque MPI into MPI_X, the parameters 'e'
+     and 'd' again as an unsigned MPI into MPI_E and MPI_D and finally
+     the parameter 'foo' as a signed MPI into MPI_FOO.
+
+     PATH is an optional string used to locate a token.  The exclamation
+     mark separated tokens are used via 'gcry_sexp_find_token' to find a
+     start point inside the S-expression.
+
+     In buffer descriptor mode a pointer to a 'gcry_buffer_t' descriptor
+     is expected instead of a pointer to an MPI. The caller may use two
+     different operation modes here: If the DATA field of the provided
+     descriptor is 'NULL', the function allocates a new buffer and
+     stores it at DATA; the other fields are set accordingly with OFF
+     set to 0.  If DATA is not 'NULL', the function assumes that the
+     DATA, SIZE, and OFF fields specify a buffer where to but the value
+     of the respective parameter; on return the LEN field receives the
+     number of bytes copied to that buffer; in case the buffer is too
+     small, the function immediately returns with an error code (and LEN
+     is set to 0).
+
+     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 'NULL', and all passed buffers are
+     either truncated if the caller supplied the buffer, or deallocated
+     if the function allocated the buffer.
+
+
+File: gcrypt.info,  Node: MPI library,  Next: Prime numbers,  Prev: S-expressions,  Up: Top
+
+12 MPI library
+**************
+
+* Menu:
+
+* Data types::                  MPI related data types.
+* Basic functions::             First steps with MPI numbers.
+* MPI formats::                 External representation of MPIs.
+* Calculations::                Performing MPI calculations.
+* Comparisons::                 How to compare MPI values.
+* Bit manipulations::           How to access single bits of MPI values.
+* EC functions::                Elliptic curve related functions.
+* Miscellaneous::               Miscellaneous MPI functions.
+
+Public key cryptography is based on mathematics with large numbers.  To
+implement the public key functions, a library for handling these large
+numbers is required.  Because of the general usefulness of such a
+library, its interface is exposed by Libgcrypt.  In the context of
+Libgcrypt and in most other applications, these large numbers are called
+MPIs (multi-precision-integers).
+
+
+File: gcrypt.info,  Node: Data types,  Next: Basic functions,  Up: MPI library
+
+12.1 Data types
+===============
+
+ -- Data type: gcry_mpi_t
+     This type represents an object to hold an MPI.
+
+ -- Data type: gcry_mpi_point_t
+     This type represents an object to hold a point for elliptic curve
+     math.
+
+
+File: gcrypt.info,  Node: Basic functions,  Next: MPI formats,  Prev: Data types,  Up: MPI library
+
+12.2 Basic functions
+====================
+
+To work with MPIs, storage must be allocated and released for the
+numbers.  This can be done with one of these functions:
+
+ -- Function: gcry_mpi_t gcry_mpi_new (unsigned int NBITS)
+
+     Allocate a new MPI object, initialize it to 0 and initially
+     allocate enough memory for a number of at least NBITS.  This
+     pre-allocation is only a small performance issue and not actually
+     necessary because Libgcrypt automatically re-allocates the required
+     memory.
+
+ -- Function: gcry_mpi_t gcry_mpi_snew (unsigned int NBITS)
+
+     This is identical to 'gcry_mpi_new' but allocates the MPI in the so
+     called "secure memory" which in turn will take care that all
+     derived values will also be stored in this "secure memory".  Use
+     this for highly confidential data like private key parameters.
+
+ -- Function: gcry_mpi_t gcry_mpi_copy (const gcry_mpi_t A)
+
+     Create a new MPI as the exact copy of A but with the constant and
+     immutable flags cleared.
+
+ -- Function: void gcry_mpi_release (gcry_mpi_t A)
+
+     Release the MPI A and free all associated resources.  Passing
+     'NULL' is allowed and ignored.  When a MPI stored in the "secure
+     memory" is released, that memory gets wiped out immediately.
+
+The simplest operations are used to assign a new value to an MPI:
+
+ -- Function: gcry_mpi_t gcry_mpi_set (gcry_mpi_t W, const gcry_mpi_t U)
+
+     Assign the value of U to W and return W.  If 'NULL' is passed for
+     W, a new MPI is allocated, set to the value of U and returned.
+
+ -- Function: gcry_mpi_t gcry_mpi_set_ui (gcry_mpi_t W, unsigned long U)
+
+     Assign the value of U to W and return W.  If 'NULL' is passed for
+     W, a new MPI is allocated, set to the value of U and returned.
+     This function takes an 'unsigned int' as type for U and thus it is
+     only possible to set W to small values (usually up to the word size
+     of the CPU).
+
+ -- Function: void gcry_mpi_swap (gcry_mpi_t A, gcry_mpi_t B)
+
+     Swap the values of A and B.
+
+ -- Function: void gcry_mpi_snatch (gcry_mpi_t W, const gcry_mpi_t U)
+
+     Set U into W and release U.  If W is 'NULL' only U will be
+     released.
+
+ -- Function: void gcry_mpi_neg (gcry_mpi_t W, gcry_mpi_t U)
+
+     Set the sign of W to the negative of U.
+
+ -- Function: void gcry_mpi_abs (gcry_mpi_t W)
+
+     Clear the sign of W.
+
+
+File: gcrypt.info,  Node: MPI formats,  Next: Calculations,  Prev: Basic functions,  Up: MPI library
+
+12.3 MPI formats
+================
+
+The following functions are used to convert between an external
+representation of an MPI and the internal one of Libgcrypt.
+
+ -- Function: gcry_error_t gcry_mpi_scan (gcry_mpi_t *R_MPI,
+          enum gcry_mpi_format FORMAT, const unsigned char *BUFFER,
+          size_t BUFLEN, size_t *NSCANNED)
+
+     Convert the external representation of an integer stored in BUFFER
+     with a length of BUFLEN into a newly created MPI returned which
+     will be stored at the address of R_MPI.  For certain formats the
+     length argument is not required and should be passed as '0'.  A
+     BUFLEN larger than 16 MiByte will be rejected.  After a successful
+     operation the variable NSCANNED receives the number of bytes
+     actually scanned unless NSCANNED was given as 'NULL'.  FORMAT
+     describes the format of the MPI as stored in BUFFER:
+
+     'GCRYMPI_FMT_STD'
+          2-complement stored without a length header.  Note that
+          'gcry_mpi_print' stores a '0' as a string of zero length.
+
+     'GCRYMPI_FMT_PGP'
+          As used by OpenPGP (only defined as unsigned).  This is
+          basically 'GCRYMPI_FMT_STD' with a 2 byte big endian length
+          header.  A length header indicating a length of more than
+          16384 is not allowed.
+
+     'GCRYMPI_FMT_SSH'
+          As used in the Secure Shell protocol.  This is
+          'GCRYMPI_FMT_STD' with a 4 byte big endian header.
+
+     'GCRYMPI_FMT_HEX'
+          Stored as a string with each byte of the MPI encoded as 2 hex
+          digits.  Negative numbers are prefix with a minus sign and in
+          addition the high bit is always zero to make clear that an
+          explicit sign ist used.  When using this format, BUFLEN must
+          be zero.
+
+     'GCRYMPI_FMT_USG'
+          Simple unsigned integer.
+
+     Note that all of the above formats store the integer in big-endian
+     format (MSB first).
+
+ -- Function: gcry_error_t gcry_mpi_print (enum gcry_mpi_format FORMAT,
+          unsigned char *BUFFER, size_t BUFLEN, size_t *NWRITTEN,
+          const gcry_mpi_t A)
+
+     Convert the MPI A into an external representation described by
+     FORMAT (see above) and store it in the provided BUFFER which has a
+     usable length of at least the BUFLEN bytes.  If NWRITTEN is not
+     NULL, it will receive the number of bytes actually stored in BUFFER
+     after a successful operation.
+
+ -- Function: gcry_error_t gcry_mpi_aprint (enum gcry_mpi_format FORMAT,
+          unsigned char **BUFFER, size_t *NBYTES, const gcry_mpi_t A)
+
+     Convert the MPI A into an external representation described by
+     FORMAT (see above) and store it in a newly allocated buffer which
+     address will be stored in the variable BUFFER points to.  The
+     number of bytes stored in this buffer will be stored in the
+     variable NBYTES points to, unless NBYTES is 'NULL'.
+
+     Even if NBYTES is zero, the function allocates at least one byte
+     and store a zero there.  Thus with formats 'GCRYMPI_FMT_STD' and
+     'GCRYMPI_FMT_USG' the caller may safely set a returned length of 0
+     to 1 to represent a zero as a 1 byte string.
+
+ -- Function: void gcry_mpi_dump (const gcry_mpi_t A)
+
+     Dump the value of A in a format suitable for debugging to
+     Libgcrypt's logging stream.  Note that one leading space but no
+     trailing space or linefeed will be printed.  It is okay to pass
+     'NULL' for A.
+
+
+File: gcrypt.info,  Node: Calculations,  Next: Comparisons,  Prev: MPI formats,  Up: MPI library
+
+12.4 Calculations
+=================
+
+Basic arithmetic operations:
+
+ -- Function: void gcry_mpi_add (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V)
+
+     W = U + V.
+
+ -- Function: void gcry_mpi_add_ui (gcry_mpi_t W, gcry_mpi_t U,
+          unsigned long V)
+
+     W = U + V.  Note that V is an unsigned integer.
+
+ -- Function: void gcry_mpi_addm (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V, gcry_mpi_t M)
+
+     W = U + V \bmod M.
+
+ -- Function: void gcry_mpi_sub (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V)
+
+     W = U - V.
+
+ -- Function: void gcry_mpi_sub_ui (gcry_mpi_t W, gcry_mpi_t U,
+          unsigned long V)
+
+     W = U - V.  V is an unsigned integer.
+
+ -- Function: void gcry_mpi_subm (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V, gcry_mpi_t M)
+
+     W = U - V \bmod M.
+
+ -- Function: void gcry_mpi_mul (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V)
+
+     W = U * V.
+
+ -- Function: void gcry_mpi_mul_ui (gcry_mpi_t W, gcry_mpi_t U,
+          unsigned long V)
+
+     W = U * V.  V is an unsigned integer.
+
+ -- Function: void gcry_mpi_mulm (gcry_mpi_t W, gcry_mpi_t U,
+          gcry_mpi_t V, gcry_mpi_t M)
+
+     W = U * V \bmod M.
+
+ -- Function: void gcry_mpi_mul_2exp (gcry_mpi_t W, gcry_mpi_t U,
+          unsigned long E)
+
+     W = U * 2^e.
+
+ -- Function: void gcry_mpi_div (gcry_mpi_t Q, gcry_mpi_t R,
+          gcry_mpi_t DIVIDEND, gcry_mpi_t DIVISOR, int ROUND)
+
+     Q = DIVIDEND / DIVISOR, R = DIVIDEND \bmod DIVISOR.  Q and R may be
+     passed as 'NULL'.  ROUND should be negative or 0.
+
+ -- Function: void gcry_mpi_mod (gcry_mpi_t R, gcry_mpi_t DIVIDEND,
+          gcry_mpi_t DIVISOR)
+
+     R = DIVIDEND \bmod DIVISOR.
+
+ -- Function: void gcry_mpi_powm (gcry_mpi_t W, const gcry_mpi_t B,
+          const gcry_mpi_t E, const gcry_mpi_t M)
+
+     W = B^e \bmod M.
+
+ -- Function: int gcry_mpi_gcd (gcry_mpi_t G, gcry_mpi_t A,
+          gcry_mpi_t B)
+
+     Set G to the greatest common divisor of A and B.  Return true if
+     the G is 1.
+
+ -- Function: int gcry_mpi_invm (gcry_mpi_t X, gcry_mpi_t A,
+          gcry_mpi_t M)
+
+     Set X to the multiplicative inverse of A \bmod M.  Return true if
+     the inverse exists.
+
+
+File: gcrypt.info,  Node: Comparisons,  Next: Bit manipulations,  Prev: Calculations,  Up: MPI library
+
+12.5 Comparisons
+================
+
+The next 2 functions are used to compare MPIs:
+
+ -- Function: int gcry_mpi_cmp (const gcry_mpi_t U, const gcry_mpi_t V)
+
+     Compare the multi-precision-integers number U and V returning 0 for
+     equality, a positive value for U > V and a negative for U < 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.
+
+ -- Function: int gcry_mpi_cmp_ui (const gcry_mpi_t U, unsigned long V)
+
+     Compare the multi-precision-integers number U with the unsigned
+     integer V returning 0 for equality, a positive value for U > V and
+     a negative for U < V.
+
+ -- Function: int gcry_mpi_is_neg (const gcry_mpi_t A)
+
+     Return 1 if A is less than zero; return 0 if zero or positive.
+
+
+File: gcrypt.info,  Node: Bit manipulations,  Next: EC functions,  Prev: Comparisons,  Up: MPI library
+
+12.6 Bit manipulations
+======================
+
+There are a couple of functions to get information on arbitrary bits in
+an MPI and to set or clear them:
+
+ -- Function: unsigned int gcry_mpi_get_nbits (gcry_mpi_t A)
+
+     Return the number of bits required to represent A.
+
+ -- Function: int gcry_mpi_test_bit (gcry_mpi_t A, unsigned int N)
+
+     Return true if bit number N (counting from 0) is set in A.
+
+ -- Function: void gcry_mpi_set_bit (gcry_mpi_t A, unsigned int N)
+
+     Set bit number N in A.
+
+ -- Function: void gcry_mpi_clear_bit (gcry_mpi_t A, unsigned int N)
+
+     Clear bit number N in A.
+
+ -- Function: void gcry_mpi_set_highbit (gcry_mpi_t A, unsigned int N)
+
+     Set bit number N in A and clear all bits greater than N.
+
+ -- Function: void gcry_mpi_clear_highbit (gcry_mpi_t A, unsigned int N)
+
+     Clear bit number N in A and all bits greater than N.
+
+ -- Function: void gcry_mpi_rshift (gcry_mpi_t X, gcry_mpi_t A,
+          unsigned int N)
+
+     Shift the value of A by N bits to the right and store the result in
+     X.
+
+ -- Function: void gcry_mpi_lshift (gcry_mpi_t X, gcry_mpi_t A,
+          unsigned int N)
+
+     Shift the value of A by N bits to the left and store the result in
+     X.
+
+
+File: gcrypt.info,  Node: EC functions,  Next: Miscellaneous,  Prev: Bit manipulations,  Up: MPI library
+
+12.7 EC functions
+=================
+
+Libgcrypt provides an API to access low level functions used by its
+elliptic curve implementation.  These functions allow to implement
+elliptic curve methods for which no explicit support is available.
+
+ -- Function: gcry_mpi_point_t gcry_mpi_point_new (unsigned int NBITS)
+
+     Allocate a new point object, initialize it to 0, and allocate
+     enough memory for a points of at least NBITS.  This pre-allocation
+     yields only a small performance win and is not really necessary
+     because Libgcrypt automatically re-allocates the required memory.
+     Using 0 for NBITS is usually the right thing to do.
+
+ -- Function: void gcry_mpi_point_release (gcry_mpi_point_t POINT)
+
+     Release POINT and free all associated resources.  Passing 'NULL' is
+     allowed and ignored.
+
+ -- Function: gcry_mpi_point_t gcry_mpi_point_copy
+          (gcry_mpi_point_t POINT)
+
+     Allocate and return a new point object and initialize it with
+     POINT.  If POINT is NULL the function is identical to
+     'gcry_mpi_point_new(0)'.
+
+ -- Function: void gcry_mpi_point_get (gcry_mpi_t X, gcry_mpi_t Y,
+          gcry_mpi_t Z, gcry_mpi_point_t POINT)
+
+     Store the projective coordinates from POINT into the MPIs X, Y, and
+     Z.  If a coordinate is not required, 'NULL' may be used for X, Y,
+     or Z.
+
+ -- Function: void gcry_mpi_point_snatch_get (gcry_mpi_t X,
+          gcry_mpi_t Y, gcry_mpi_t Z, gcry_mpi_point_t POINT)
+
+     Store the projective coordinates from POINT into the MPIs X, Y, and
+     Z.  If a coordinate is not required, 'NULL' may be used for X, Y,
+     or Z.  The object POINT is then released.  Using this function
+     instead of 'gcry_mpi_point_get' and 'gcry_mpi_point_release' has
+     the advantage of avoiding some extra memory allocations and copies.
+
+ -- Function: gcry_mpi_point_t gcry_mpi_point_set (
+          gcry_mpi_point_t POINT, gcry_mpi_t X, gcry_mpi_t Y,
+          gcry_mpi_t Z)
+
+     Store the projective coordinates from X, Y, and Z into POINT.  If a
+     coordinate is given as 'NULL', the value 0 is used.  If 'NULL' is
+     used for POINT a new point object is allocated and returned.
+     Returns POINT or the newly allocated point object.
+
+ -- Function: gcry_mpi_point_t gcry_mpi_point_snatch_set (
+          gcry_mpi_point_t POINT, gcry_mpi_t X, gcry_mpi_t Y,
+          gcry_mpi_t Z)
+
+     Store the projective coordinates from X, Y, and Z into POINT.  If a
+     coordinate is given as 'NULL', the value 0 is used.  If 'NULL' is
+     used for POINT a new point object is allocated and returned.  The
+     MPIs X, Y, and Z are released.  Using this function instead of
+     'gcry_mpi_point_set' and 3 calls to 'gcry_mpi_release' has the
+     advantage of avoiding some extra memory allocations and copies.
+     Returns POINT or the newly allocated point object.
+
+ -- Function: gpg_error_t gcry_mpi_ec_new (gcry_ctx_t *R_CTX,
+          gcry_sexp_t KEYPARAM, const char *CURVENAME)
+
+     Allocate a new context for elliptic curve operations.  If KEYPARAM
+     is given it specifies the parameters of the curve (*note
+     ecc_keyparam::).  If CURVENAME is given in addition to KEYPARAM and
+     the key parameters do not include a named curve reference, the
+     string CURVENAME is used to fill in missing parameters.  If only
+     CURVENAME is given, the context is initialized for this named
+     curve.
+
+     If a parameter specifying a point (e.g.  'g' or 'q') is not found,
+     the parser looks for a non-encoded point by appending '.x', '.y',
+     and '.z' to the parameter name and looking them all up to create a
+     point.  A parameter with the suffix '.z' is optional and defaults
+     to 1.
+
+     On success the function returns 0 and stores the new context object
+     at R_CTX; this object eventually needs to be released (*note
+     gcry_ctx_release::).  On error the function stores 'NULL' at R_CTX
+     and returns an error code.
+
+ -- Function: gcry_mpi_t gcry_mpi_ec_get_mpi ( const char *NAME,
+          gcry_ctx_t CTX, int COPY)
+
+     Return the MPI with NAME from the context CTX.  If not found 'NULL'
+     is returned.  If the returned MPI may later be modified, it is
+     suggested to pass '1' to COPY, so that the function guarantees that
+     a modifiable copy of the MPI is returned.  If '0' is used for COPY,
+     this function may return a constant flagged MPI. In any case
+     'gcry_mpi_release' needs to be called to release the result.  For
+     valid names *note ecc_keyparam::.  If the public key 'q' is
+     requested but only the private key 'd' is available, 'q' will be
+     recomputed on the fly.  If a point parameter is requested it is
+     returned as an uncompressed encoded point unless these special
+     names are used:
+     Q@EDDSA
+          Return an EdDSA style compressed point.  This is only
+          supported for Twisted Edwards curves.
+
+ -- Function: gcry_mpi_point_t gcry_mpi_ec_get_point ( const char *NAME,
+          gcry_ctx_t CTX, int COPY)
+
+     Return the point with NAME from the context CTX.  If not found
+     'NULL' is returned.  If the returned MPI may later be modified, it
+     is suggested to pass '1' to COPY, so that the function guarantees
+     that a modifiable copy of the MPI is returned.  If '0' is used for
+     COPY, this function may return a constant flagged point.  In any
+     case 'gcry_mpi_point_release' needs to be called to release the
+     result.  If the public key 'q' is requested but only the private
+     key 'd' is available, 'q' will be recomputed on the fly.
+
+ -- Function: gpg_error_t gcry_mpi_ec_set_mpi ( const char *NAME,
+          gcry_mpi_t NEWVALUE, gcry_ctx_t CTX)
+
+     Store the MPI NEWVALUE at NAME into the context CTX.  On success
+     '0' is returned; on error an error code.  Valid names are the MPI
+     parameters of an elliptic curve (*note ecc_keyparam::).
+
+ -- Function: gpg_error_t gcry_mpi_ec_set_point ( const char *NAME,
+          gcry_mpi_point_t NEWVALUE, gcry_ctx_t CTX)
+
+     Store the point NEWVALUE at NAME into the context CTX.  On success
+     '0' is returned; on error an error code.  Valid names are the point
+     parameters of an elliptic curve (*note ecc_keyparam::).
+
+ -- Function: gpg_err_code_t gcry_mpi_ec_decode_point (
+          mpi_point_t RESULT, gcry_mpi_t VALUE, gcry_ctx_t CTX)
+
+     Decode the point given as an MPI in VALUE and store at RESULT.  To
+     decide which encoding is used the function takes a context CTX
+     which can be created with 'gcry_mpi_ec_new'.  If 'NULL' is given
+     for the context the function assumes a 0x04 prefixed uncompressed
+     encoding.  On error an error code is returned and RESULT might be
+     changed.
+
+ -- Function: int gcry_mpi_ec_get_affine ( gcry_mpi_t X, gcry_mpi_t Y,
+          gcry_mpi_point_t POINT, gcry_ctx_t CTX)
+
+     Compute the affine coordinates from the projective coordinates in
+     POINT and store them into X and Y.  If one coordinate is not
+     required, 'NULL' may be passed to X or Y.  CTX is the context
+     object which has been created using 'gcry_mpi_ec_new'.  Returns 0
+     on success or not 0 if POINT is at infinity.
+
+     Note that you can use 'gcry_mpi_ec_set_point' with the value
+     'GCRYMPI_CONST_ONE' for Z to convert affine coordinates back into
+     projective coordinates.
+
+ -- Function: void gcry_mpi_ec_dup ( gcry_mpi_point_t W,
+          gcry_mpi_point_t U, gcry_ctx_t CTX)
+
+     Double the point U of the elliptic curve described by CTX and store
+     the result into W.
+
+ -- Function: void gcry_mpi_ec_add ( gcry_mpi_point_t W,
+          gcry_mpi_point_t U, gcry_mpi_point_t V, gcry_ctx_t CTX)
+
+     Add the points U and V of the elliptic curve described by CTX and
+     store the result into W.
+
+ -- Function: void gcry_mpi_ec_sub ( gcry_mpi_point_t W,
+          gcry_mpi_point_t U, gcry_mpi_point_t V, gcry_ctx_t CTX)
+
+     Subtracts the point V from the point U of the elliptic curve
+     described by CTX and store the result into W.  Only Twisted Edwards
+     curves are supported for now.
+
+ -- Function: void gcry_mpi_ec_mul ( gcry_mpi_point_t W, gcry_mpi_t N,
+          gcry_mpi_point_t U, gcry_ctx_t CTX)
+
+     Multiply the point U of the elliptic curve described by CTX by N
+     and store the result into W.
+
+ -- Function: int gcry_mpi_ec_curve_point ( gcry_mpi_point_t POINT,
+          gcry_ctx_t CTX)
+
+     Return true if POINT is on the elliptic curve described by CTX.
+
+
+File: gcrypt.info,  Node: Miscellaneous,  Prev: EC functions,  Up: MPI library
+
+12.8 Miscellaneous
+==================
+
+An MPI data type is allowed to be "misused" to store an arbitrary value.
+Two functions implement this kludge:
+
+ -- Function: gcry_mpi_t gcry_mpi_set_opaque (gcry_mpi_t A, void *P,
+          unsigned int NBITS)
+
+     Store NBITS of the value P points to in A and mark A as an opaque
+     value (i.e.  an value that can't be used for any math calculation
+     and is only used to store an arbitrary bit pattern in A).
+     Ownership of P is taken by this function and thus the user may not
+     use dereference the passed value anymore.  It is required that them
+     memory referenced by P has been allocated in a way that 'gcry_free'
+     is able to release it.
+
+     WARNING: Never use an opaque MPI for actual math operations.  The
+     only valid functions are gcry_mpi_get_opaque and gcry_mpi_release.
+     Use gcry_mpi_scan to convert a string of arbitrary bytes into an
+     MPI.
+
+ -- Function: gcry_mpi_t gcry_mpi_set_opaque_copy (gcry_mpi_t A,
+          const void *P, unsigned int NBITS)
+
+     Same as 'gcry_mpi_set_opaque' but ownership of P is not taken
+     instead a copy of P is used.
+
+ -- Function: void * gcry_mpi_get_opaque (gcry_mpi_t A,
+          unsigned int *NBITS)
+
+     Return a pointer to an opaque value stored in A and return its size
+     in NBITS.  Note that the returned pointer is still owned by A and
+     that the function should never be used for an non-opaque MPI.
+
+   Each MPI has an associated set of flags for special purposes.  The
+currently defined flags are:
+
+'GCRYMPI_FLAG_SECURE'
+     Setting this flag converts A into an MPI stored in "secure memory".
+     Clearing this flag is not allowed.
+'GCRYMPI_FLAG_OPAQUE'
+     This is an interanl 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.
+'GCRYMPI_FLAG_IMMUTABLE'
+     If this flag is set, the MPI is marked as immutable.  Setting or
+     changing the value of that MPI is ignored and an error message is
+     logged.  The flag is sometimes useful for debugging.
+'GCRYMPI_FLAG_CONST'
+     If this flag is set, the MPI is marked as a constant and as
+     immutable Setting or changing the value of that MPI is ignored and
+     an error message is logged.  Such an MPI will never be deallocated
+     and may thus be used without copying.  Note that using
+     gcry_mpi_copy will return a copy of that constant with this and the
+     immutable flag cleared.  A few commonly used constants are
+     pre-defined and accessible using the macros 'GCRYMPI_CONST_ONE',
+     'GCRYMPI_CONST_TWO', 'GCRYMPI_CONST_THREE', 'GCRYMPI_CONST_FOUR',
+     and 'GCRYMPI_CONST_EIGHT'.
+'GCRYMPI_FLAG_USER1'
+'GCRYMPI_FLAG_USER2'
+'GCRYMPI_FLAG_USER3'
+'GCRYMPI_FLAG_USER4'
+     These flags are reserved for use by the application.
+
+ -- Function: void gcry_mpi_set_flag (gcry_mpi_t A,
+          enum gcry_mpi_flag FLAG)
+
+     Set the FLAG for the MPI A.  The only allowed flags are
+     'GCRYMPI_FLAG_SECURE', 'GCRYMPI_FLAG_IMMUTABLE', and
+     'GCRYMPI_FLAG_CONST'.
+
+ -- Function: void gcry_mpi_clear_flag (gcry_mpi_t A,
+          enum gcry_mpi_flag FLAG)
+
+     Clear FLAG for the multi-precision-integers A.  The only allowed
+     flag is 'GCRYMPI_FLAG_IMMUTABLE' but only if 'GCRYMPI_FLAG_CONST'
+     is not set.  If 'GCRYMPI_FLAG_CONST' is set, clearing
+     'GCRYMPI_FLAG_IMMUTABLE' will simply be ignored.
+   o
+ -- Function: int gcry_mpi_get_flag (gcry_mpi_t A,
+          enum gcry_mpi_flag FLAG)
+
+     Return true if FLAG is set for A.
+
+   To put a random value into an MPI, the following convenience function
+may be used:
+
+ -- Function: void gcry_mpi_randomize (gcry_mpi_t W, unsigned int NBITS,
+          enum gcry_random_level LEVEL)
+
+     Set the multi-precision-integers W to a random non-negative number
+     of NBITS, using random data quality of level LEVEL.  In case NBITS
+     is not a multiple of a byte, NBITS is rounded up to the next byte
+     boundary.  When using a LEVEL of 'GCRY_WEAK_RANDOM' this function
+     makes use of 'gcry_create_nonce'.
+
+
+File: gcrypt.info,  Node: Prime numbers,  Next: Utilities,  Prev: MPI library,  Up: Top
+
+13 Prime numbers
+****************
+
+* Menu:
+
+* Generation::                  Generation of new prime numbers.
+* Checking::                    Checking if a given number is prime.
+
+
+File: gcrypt.info,  Node: Generation,  Next: Checking,  Up: Prime numbers
+
+13.1 Generation
+===============
+
+ -- Function: gcry_error_t gcry_prime_generate (gcry_mpi_t
+          *PRIME,unsigned int PRIME_BITS, unsigned int FACTOR_BITS,
+          gcry_mpi_t **FACTORS, gcry_prime_check_func_t CB_FUNC, void
+          *CB_ARG, gcry_random_level_t RANDOM_LEVEL, unsigned int FLAGS)
+
+     Generate a new prime number of PRIME_BITS bits and store it in
+     PRIME.  If FACTOR_BITS is non-zero, one of the prime factors of
+     (PRIME - 1) / 2 must be FACTOR_BITS bits long.  If FACTORS is
+     non-zero, allocate a new, 'NULL'-terminated array holding the prime
+     factors and store it in FACTORS.  FLAGS might be used to influence
+     the prime number generation process.
+
+ -- Function: gcry_error_t gcry_prime_group_generator (gcry_mpi_t *R_G,
+          gcry_mpi_t PRIME, gcry_mpi_t *FACTORS, gcry_mpi_t START_G)
+
+     Find a generator for PRIME where the factorization of (PRIME-1) is
+     in the 'NULL' terminated array FACTORS.  Return the generator as a
+     newly allocated MPI in R_G.  If START_G is not NULL, use this as
+     the start for the search.
+
+ -- Function: void gcry_prime_release_factors (gcry_mpi_t *FACTORS)
+
+     Convenience function to release the FACTORS array.
+
+
+File: gcrypt.info,  Node: Checking,  Prev: Generation,  Up: Prime numbers
+
+13.2 Checking
+=============
+
+ -- Function: gcry_error_t gcry_prime_check (gcry_mpi_t P, unsigned int
+          FLAGS)
+
+     Check whether the number P is prime.  Returns zero in case P is
+     indeed a prime, returns 'GPG_ERR_NO_PRIME' in case P is not a prime
+     and a different error code in case something went horribly wrong.
+
+
+File: gcrypt.info,  Node: Utilities,  Next: Tools,  Prev: Prime numbers,  Up: Top
+
+14 Utilities
+************
+
+* Menu:
+
+* 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.
+
+
+File: gcrypt.info,  Node: Memory allocation,  Next: Context management,  Up: Utilities
+
+14.1 Memory allocation
+======================
+
+ -- Function: void * gcry_malloc (size_t N)
+
+     This function tries to allocate N bytes of memory.  On success it
+     returns a pointer to the memory area, in an out-of-core condition,
+     it returns NULL.
+
+ -- Function: void * gcry_malloc_secure (size_t N)
+     Like 'gcry_malloc', but uses secure memory.
+
+ -- Function: void * gcry_calloc (size_t N, size_t M)
+
+     This function allocates a cleared block of memory (i.e.
+     initialized with zero bytes) long enough to contain a vector of N
+     elements, each of size M bytes.  On success it returns a pointer to
+     the memory block; in an out-of-core condition, it returns NULL.
+
+ -- Function: void * gcry_calloc_secure (size_t N, size_t M)
+     Like 'gcry_calloc', but uses secure memory.
+
+ -- Function: void * gcry_realloc (void *P, size_t N)
+
+     This function tries to resize the memory area pointed to by P to N
+     bytes.  On success it returns a pointer to the new memory area, in
+     an out-of-core condition, it returns NULL. Depending on whether the
+     memory pointed to by P is secure memory or not, gcry_realloc tries
+     to use secure memory as well.
+
+ -- Function: void gcry_free (void *P)
+     Release the memory area pointed to by P.
+
+
+File: gcrypt.info,  Node: Context management,  Next: Buffer description,  Prev: Memory allocation,  Up: Utilities
+
+14.2 Context management
+=======================
+
+Some function make use of a context object.  As of now there are only a
+few math functions.  However, future versions of Libgcrypt may make more
+use of this context object.
+
+ -- Data type: gcry_ctx_t
+     This type is used to refer to the general purpose context object.
+
+ -- Function: void gcry_ctx_release (gcry_ctx_t CTX)
+     Release the context object CTX and all associated resources.  A
+     'NULL' passed as CTX is ignored.
+
+
+File: gcrypt.info,  Node: Buffer description,  Next: Config reporting,  Prev: Context management,  Up: Utilities
+
+14.3 Buffer description
+=======================
+
+To help hashing non-contiguous areas of memory a general purpose data
+type is defined:
+
+ -- Data type: gcry_buffer_t
+     This type is a structure to describe a buffer.  The user should
+     make sure that this structure is initialized to zero.  The
+     available fields of this structure are:
+
+     '.size'
+          This is either 0 for no information available or indicates the
+          allocated length of the buffer.
+     '.off'
+          This is the offset into the buffer.
+     '.len'
+          This is the valid length of the buffer starting at '.off'.
+     '.data'
+          This is the address of the buffer.
+
+
+File: gcrypt.info,  Node: Config reporting,  Prev: Buffer description,  Up: Utilities
+
+14.4 How to return Libgcrypt's configuration.
+=============================================
+
+Although '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:
+
+ -- Function: char * gcry_get_config (int MODE, const char *WHAT)
+
+     This function returns a malloced string with colon delimited
+     configure options.  With a value of 0 for MODE this string
+     resembles the output of 'GCRYCTL_PRINT_CONFIG'.  However, if WHAT
+     is not NULL, only the line where the first field (e.g.  "cpu-arch")
+     matches WHAT is returned.
+
+     Other values than 0 for MODE are not defined.  The caller shall
+     free the string using 'gcry_free'.  On error NULL is returned and
+     ERRNO is set; if a value for WHAT is unknow ERRNO will be set to 0.
+
+
+File: gcrypt.info,  Node: Tools,  Next: Configuration,  Prev: Utilities,  Up: Top
+
+15 Tools
+********
+
+* Menu:
+
+* hmac256:: A standalone HMAC-SHA-256 implementation
+
+
+File: gcrypt.info,  Node: hmac256,  Up: Tools
+
+15.1 A HMAC-SHA-256 tool
+========================
+
+This is a standalone HMAC-SHA-256 implementation used to compute an
+HMAC-SHA-256 message authentication code.  The tool has originally been
+developed as a second implementation for Libgcrypt to allow comparing
+against the primary implementation and to be used for internal
+consistency checks.  It should not be used for sensitive data because no
+mechanisms to clear the stack etc are used.
+
+   The code has been written in a highly portable manner and requires
+only a few standard definitions to be provided in a config.h file.
+
+'hmac256' is commonly invoked as
+
+     hmac256 "This is my key" foo.txt
+
+This compute the MAC on the file 'foo.txt' using the key given on the
+command line.
+
+'hmac256' understands these options:
+
+'--binary'
+     Print the MAC as a binary string.  The default is to print the MAC
+     encoded has lower case hex digits.
+
+'--version'
+     Print version of the program and exit.
+
+
+File: gcrypt.info,  Node: Configuration,  Next: Architecture,  Prev: Tools,  Up: Top
+
+16 Configuration files and environment variables
+************************************************
+
+This chapter describes which files and environment variables can be used
+to change the behaviour of Libgcrypt.
+
+The environment variables considered by Libgcrypt are:
+
+'GCRYPT_BARRETT'
+     By setting this variable to any value a different algorithm for
+     modular reduction is used for ECC.
+
+'GCRYPT_RNDUNIX_DBG'
+'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 'GCRYPT_RNDUNIX_DBG' is a file
+     name or '-' for stdout.  Debug output is the written to this file.
+     By setting 'GCRYPT_RNDUNIX_DBGALL' to any value the debug output
+     will be more verbose.
+
+'GCRYPT_RNDW32_NOPERF'
+     Setting this environment variable on Windows to any value disables
+     the use of performance data ('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.
+
+'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.
+
+'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.
+
+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:
+
+'/etc/gcrypt/hwf.deny'
+     This file can be used to disable the use of hardware based
+     optimizations, *note hardware features::.
+
+'/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
+
+     'disable-jent'
+          Disable the use of the jitter based entropy generator.
+
+     '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.
+
+'/etc/gcrypt/fips_enabled'
+'/proc/sys/crypto/fips_enabled'
+     On Linux these files are used to enable FIPS mode, *note enabling
+     fips mode::.
+
+'/proc/cpuinfo'
+'/proc/self/auxv'
+     On Linux running on the ARM architecture, these files are used to
+     read hardware capabilities of the CPU.
+
+
+File: gcrypt.info,  Node: Architecture,  Next: Self-Tests,  Prev: Configuration,  Up: Top
+
+17 Architecture
+***************
+
+This chapter describes the internal architecture of Libgcrypt.
+
+   Libgcrypt is a function library written in ISO C-90.  Any compliant
+compiler should be able to build Libgcrypt as long as the target is
+either a POSIX platform or compatible to the API used by Windows NT.
+Provisions have been take so that the library can be directly used from
+C++ applications; however building with a C++ compiler is not supported.
+
+   Building Libgcrypt is done by using the common './configure && make'
+approach.  The configure command is included in the source distribution
+and as a portable shell script it works on any Unix-alike system.  The
+result of running the configure script are a C header file ('config.h'),
+customized Makefiles, the setup of symbolic links and a few other
+things.  After that the make tool builds and optionally installs the
+library and the documentation.  See the files 'INSTALL' and 'README' in
+the source distribution on how to do this.
+
+   Libgcrypt is developed using a Subversion(1) repository.  Although
+all released versions are tagged in this repository, they should not be
+used to build production versions of Libgcrypt.  Instead released
+tarballs should be used.  These tarballs are available from several
+places with the master copy at 'ftp://ftp.gnupg.org/gcrypt/libgcrypt/'.
+Announcements of new releases are posted to the
+'gnupg-announce@gnupg.org' mailing list(2).
+
+    
+
+Figure 17.1: Libgcrypt subsystems
+
+   Libgcrypt consists of several subsystems (*note Figure 17.1:
+fig:subsystems.) and all these subsystems provide a public API; this
+includes the helper subsystems like the one for S-expressions.  The API
+style depends on the subsystem; in general an open-use-close approach is
+implemented.  The open returns a handle to a context used for all
+further operations on this handle, several functions may then be used on
+this handle and a final close function releases all resources associated
+with the handle.
+
+* Menu:
+
+* Public-Key Subsystem Architecture::              About public keys.
+* Symmetric Encryption Subsystem Architecture::    About standard ciphers.
+* Hashing and MACing Subsystem Architecture::      About hashing.
+* Multi-Precision-Integer Subsystem Architecture:: About big integers.
+* Prime-Number-Generator Subsystem Architecture::  About prime numbers.
+* Random-Number Subsystem Architecture::           About random stuff.
+
+   ---------- Footnotes ----------
+
+   (1) A version control system available for many platforms
+
+   (2) See <http://www.gnupg.org/documentation/mailing-lists.en.html>
+for details.
+
+
+File: gcrypt.info,  Node: Public-Key Subsystem Architecture,  Next: Symmetric Encryption Subsystem Architecture,  Up: Architecture
+
+17.1 Public-Key Architecture
+============================
+
+Because public key cryptography is almost always used to process small
+amounts of data (hash values or session keys), the interface is not
+implemented using the open-use-close paradigm, but with single
+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.
+
+   Aside of functions to register new algorithms, map algorithms names
+to algorithms identifiers and to lookup properties of a key, the
+following main functions are available:
+
+'gcry_pk_encrypt'
+     Encrypt data using a public key.
+
+'gcry_pk_decrypt'
+     Decrypt data using a private key.
+
+'gcry_pk_sign'
+     Sign data using a private key.
+
+'gcry_pk_verify'
+     Verify that a signature matches the data.
+
+'gcry_pk_testkey'
+     Perform a consistency over a public or private key.
+
+'gcry_pk_genkey'
+     Create a new public/private key pair.
+
+   All these functions lookup the module implementing the algorithm and
+pass the actual work to that module.  The parsing of the S-expression
+input and the construction of S-expression for the return values is done
+by the high level code ('cipher/pubkey.c').  Thus the internal interface
+between the algorithm modules and the high level functions passes data
+in a custom format.
+
+   By default Libgcrypt uses a blinding technique for RSA decryption to
+mitigate real world timing attacks over a network: Instead of using the
+RSA decryption directly, a blinded value y = x r^{e} \bmod n is
+decrypted and the unblinded value x' = y' r^{-1} \bmod n returned.  The
+blinding value r is a random value with the size of the modulus n and
+generated with 'GCRY_WEAK_RANDOM' random level.
+
+   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.
+
+
+File: gcrypt.info,  Node: Symmetric Encryption Subsystem Architecture,  Next: Hashing and MACing Subsystem Architecture,  Prev: Public-Key Subsystem Architecture,  Up: Architecture
+
+17.2 Symmetric Encryption Subsystem Architecture
+================================================
+
+The interface to work with symmetric encryption algorithms is made up of
+functions from the 'gcry_cipher_' name space.  The implementation
+follows the open-use-close paradigm and uses registered algorithm
+modules for the actual work.  Unless a module implements optimized
+cipher mode implementations, the high level code ('cipher/cipher.c')
+implements the modes and calls the core algorithm functions to process
+each block.
+
+   The most important functions are:
+
+'gcry_cipher_open'
+     Create a new instance to encrypt or decrypt using a specified
+     algorithm and mode.
+
+'gcry_cipher_close'
+     Release an instance.
+
+'gcry_cipher_setkey'
+     Set a key to be used for encryption or decryption.
+
+'gcry_cipher_setiv'
+     Set an initialization vector to be used for encryption or
+     decryption.
+
+'gcry_cipher_encrypt'
+'gcry_cipher_decrypt'
+     Encrypt or decrypt data.  These functions may be called with
+     arbitrary amounts of data and as often as needed to encrypt or
+     decrypt all data.
+
+   There are also functions to query properties of algorithms or
+context, like block length, key length, map names or to enable features
+like padding methods.
+
+
+File: gcrypt.info,  Node: Hashing and MACing Subsystem Architecture,  Next: Multi-Precision-Integer Subsystem Architecture,  Prev: Symmetric Encryption Subsystem Architecture,  Up: Architecture
+
+17.3 Hashing and MACing Subsystem Architecture
+==============================================
+
+The interface to work with message digests and CRC algorithms is made up
+of functions from the 'gcry_md_' name space.  The implementation follows
+the open-use-close paradigm and uses registered algorithm modules for
+the actual work.  Although CRC algorithms are not considered
+cryptographic hash algorithms, they share enough properties so that it
+makes sense to handle them in the same way.  It is possible to use
+several algorithms at once with one context and thus compute them all on
+the same data.
+
+   The most important functions are:
+
+'gcry_md_open'
+     Create a new message digest instance and optionally enable one
+     algorithm.  A flag may be used to turn the message digest algorithm
+     into a HMAC algorithm.
+
+'gcry_md_enable'
+     Enable an additional algorithm for the instance.
+
+'gcry_md_setkey'
+     Set the key for the MAC.
+
+'gcry_md_write'
+     Pass more data for computing the message digest to an instance.
+
+'gcry_md_putc'
+     Buffered version of 'gcry_md_write' implemented as a macro.
+
+'gcry_md_read'
+     Finalize the computation of the message digest or HMAC and return
+     the result.
+
+'gcry_md_close'
+     Release an instance
+
+'gcry_md_hash_buffer'
+     Convenience function to directly compute a message digest over a
+     memory buffer without the need to create an instance first.
+
+   There are also functions to query properties of algorithms or the
+instance, like enabled algorithms, digest length, map algorithm names.
+it is also possible to reset an instance or to copy the current state of
+an instance at any time.  Debug functions to write the hashed data to
+files are available as well.
+
+
+File: gcrypt.info,  Node: Multi-Precision-Integer Subsystem Architecture,  Next: Prime-Number-Generator Subsystem Architecture,  Prev: Hashing and MACing Subsystem Architecture,  Up: Architecture
+
+17.4 Multi-Precision-Integer Subsystem Architecture
+===================================================
+
+The implementation of Libgcrypt's big integer computation code is based
+on an old release of GNU Multi-Precision Library (GMP). The decision not
+to use the GMP library directly was due to stalled development at that
+time and due to security requirements which could not be provided by the
+code in GMP. As GMP does, Libgcrypt provides high performance assembler
+implementations of low level code for several CPUS to gain much better
+performance than with a generic C implementation.
+
+Major features of Libgcrypt's multi-precision-integer code compared to
+GMP are:
+
+   * Avoidance of stack based allocations to allow protection against
+     swapping out of sensitive data and for easy zeroing of sensitive
+     intermediate results.
+
+   * Optional use of secure memory and tracking of its use so that
+     results are also put into secure memory.
+
+   * MPIs are identified by a handle (implemented as a pointer) to give
+     better control over allocations and to augment them with extra
+     properties like opaque data.
+
+   * Removal of unnecessary code to reduce complexity.
+
+   * Functions specialized for public key cryptography.
+
+
+File: gcrypt.info,  Node: Prime-Number-Generator Subsystem Architecture,  Next: Random-Number Subsystem Architecture,  Prev: Multi-Precision-Integer Subsystem Architecture,  Up: Architecture
+
+17.5 Prime-Number-Generator Subsystem Architecture
+==================================================
+
+Libgcrypt provides an interface to its prime number generator.  These
+functions make use of the internal prime number generator which is
+required for the generation for public key key pairs.  The plain prime
+checking function is exported as well.
+
+   The generation of random prime numbers is based on the Lim and Lee
+algorithm to create practically save primes.(1)  This algorithm creates
+a pool of smaller primes, select a few of them to create candidate
+primes of the form 2 * p_0 * p_1 * ... * p_n + 1, tests the candidate
+for primality and permutates the pool until a prime has been found.  It
+is possible to clamp one of the small primes to a certain size to help
+DSA style algorithms.  Because most of the small primes in the pool are
+not used for the resulting prime number, they are saved for later use
+(see 'save_pool_prime' and 'get_pool_prime' in 'cipher/primegen.c').
+The prime generator optionally supports the finding of an appropriate
+generator.
+
+The primality test works in three steps:
+
+  1. The standard sieve algorithm using the primes up to 4999 is used as
+     a quick first check.
+
+  2. A Fermat test filters out almost all non-primes.
+
+  3. A 5 round Rabin-Miller test is finally used.  The first round uses
+     a witness of 2, whereas the next rounds use a random witness.
+
+   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: '_gcry_derive_x931_prime' and
+'_gcry_generate_fips186_2_prime'.  These functions are internal and not
+available through the public API.
+
+   ---------- Footnotes ----------
+
+   (1) Chae Hoon Lim and Pil Joong Lee.  A key recovery attack on
+discrete log-based schemes using a prime order subgroup.  In Burton S.
+Kaliski Jr., editor, Advances in Cryptology: Crypto '97, pages
+249-263, Berlin / Heidelberg / New York, 1997.  Springer-Verlag.
+Described on page 260.
+
+
+File: gcrypt.info,  Node: Random-Number Subsystem Architecture,  Prev: Prime-Number-Generator Subsystem Architecture,  Up: Architecture
+
+17.6 Random-Number Subsystem Architecture
+=========================================
+
+Libgcrypt provides 3 levels or random quality: The level
+'GCRY_VERY_STRONG_RANDOM' usually used for key generation, the level
+'GCRY_STRONG_RANDOM' for all other strong random requirements and the
+function 'gcry_create_nonce' which is used for weaker usages like
+nonces.  There is also a level 'GCRY_WEAK_RANDOM' which in general maps
+to 'GCRY_STRONG_RANDOM' except when used with the function
+'gcry_mpi_randomize', where it randomizes an multi-precision-integer
+using the 'gcry_create_nonce' function.
+
+There are two distinct random generators available:
+
+   * The Continuously Seeded Pseudo Random Number Generator (CSPRNG),
+     which is based on the classic GnuPG derived big pool
+     implementation.  Implemented in 'random/random-csprng.c' and used
+     by default.
+   * A FIPS approved ANSI X9.31 PRNG using AES with a 128 bit key.
+     Implemented in 'random/random-fips.c' and used if Libgcrypt is in
+     FIPS mode.
+
+Both generators make use of so-called entropy gathering modules:
+
+rndlinux
+     Uses the operating system provided '/dev/random' and '/dev/urandom'
+     devices.  The '/dev/gcrypt/random.conf' config option
+     'only-urandom' can be used to inhibit the use of the blocking
+     '/dev/random' device.
+
+rndunix
+     Runs several operating system commands to collect entropy from
+     sources like virtual machine and process statistics.  It is a kind
+     of poor-man's '/dev/random' implementation.  It is not available in
+     FIPS mode.
+
+rndegd
+     Uses the operating system provided Entropy Gathering Daemon (EGD).
+     The EGD basically uses the same algorithms as rndunix does.
+     However as a system daemon it keeps on running and thus can serve
+     several processes requiring entropy input and does not waste
+     collected entropy if the application does not need all the
+     collected entropy.  It is not available in FIPS mode.
+
+rndw32
+     Targeted for the Microsoft Windows OS. It uses certain properties
+     of that system and is the only gathering module available for that
+     OS.
+
+rndhw
+     Extra module to collect additional entropy by utilizing a hardware
+     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.
+
+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 '/dev/gcrypt/random.conf' config option
+     'disable-jent' can be used to inhibit the use of this module.
+
+* Menu:
+
+* CSPRNG Description::      Description of the CSPRNG.
+* FIPS PRNG Description::   Description of the FIPS X9.31 PRNG.
+
+
+File: gcrypt.info,  Node: CSPRNG Description,  Next: FIPS PRNG Description,  Up: Random-Number Subsystem Architecture
+
+17.6.1 Description of the CSPRNG
+--------------------------------
+
+This random number generator is loosely modelled after the one described
+in Peter Gutmann's paper: "Software Generation of Practically Strong
+Random Numbers".(1)
+
+   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 file and
+initially seed form a file.
+
+   Depending on how Libgcrypt was build the generator is able to select
+the best working entropy gathering module.  It makes use of the slow and
+fast collection methods and requires the pool to initially seeded form
+the slow gatherer or a seed file.  An entropy estimation is used to mix
+in enough data from the gather modules before returning the actual
+random output.  Process fork detection and protection is implemented.
+
+   The implementation of the nonce generator (for 'gcry_create_nonce')
+is a straightforward repeated hash design: A 28 byte buffer is initially
+seeded with the PID and the time in seconds in the first 20 bytes and
+with 8 bytes of random taken from the 'GCRY_STRONG_RANDOM' generator.
+Random numbers are then created by hashing all the 28 bytes with SHA-1
+and saving that again in the first 20 bytes.  The hash is also returned
+as result.
+
+   ---------- Footnotes ----------
+
+   (1) Also described in chapter 6 of his book "Cryptographic Security
+Architecture", New York, 2004, ISBN 0-387-95387-6.
+
+
+File: gcrypt.info,  Node: FIPS PRNG Description,  Prev: CSPRNG Description,  Up: Random-Number Subsystem Architecture
+
+17.6.2 Description of the FIPS X9.31 PRNG
+-----------------------------------------
+
+The core of this deterministic random number generator is implemented
+according to the document "NIST-Recommended Random Number Generator
+Based on ANSI X9.31 Appendix A.2.4 Using the 3-Key Triple DES and AES
+Algorithms", dated 2005-01-31.  This implementation uses the AES
+variant.
+
+   The generator is based on contexts to utilize the same core functions
+for all random levels as required by the high-level interface.  All
+random generators return their data in 128 bit blocks.  If the caller
+requests less bits, the extra bits are not used.  The key for each
+generator is only set once at the first time a generator context is
+used.  The seed value is set along with the key and again after 1000
+output blocks.
+
+   On Unix like systems the 'GCRY_VERY_STRONG_RANDOM' and
+'GCRY_STRONG_RANDOM' generators are keyed and seeded using the rndlinux
+module with the '/dev/random' device.  Thus these generators may block
+until the OS kernel has collected enough entropy.  When used with
+Microsoft Windows the rndw32 module is used instead.
+
+   The generator used for 'gcry_create_nonce' is keyed and seeded from
+the 'GCRY_STRONG_RANDOM' generator.  Thus is may also block if the
+'GCRY_STRONG_RANDOM' generator has not yet been used before and thus
+gets initialized on the first use by 'gcry_create_nonce'.  This special
+treatment is justified by the 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
+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 stuck generator.
+
+   The DT value for the generator is made up of the current time down to
+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.
+
+
+File: gcrypt.info,  Node: Self-Tests,  Next: FIPS Mode,  Prev: Architecture,  Up: Top
+
+Appendix A 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 '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.
+
+A.1 Power-Up Tests
+==================
+
+Power-up tests are only performed if Libgcrypt is in FIPS mode.
+
+A.1.1 Symmetric Cipher Algorithm Power-Up Tests
+-----------------------------------------------
+
+The following symmetric encryption algorithm tests are run during
+power-up:
+
+3DES
+     To test the 3DES 3-key EDE encryption in ECB mode these tests are
+     run:
+       1. 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.
+       2. 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.
+       3. 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.
+     ('cipher/des.c:selftest')
+
+AES-128
+     A known answer tests is run using one test vector and one test key
+     with AES in ECB mode.  ('cipher/rijndael.c:selftest_basic_128')
+
+AES-192
+     A known answer tests is run using one test vector and one test key
+     with AES in ECB mode.  ('cipher/rijndael.c:selftest_basic_192')
+
+AES-256
+     A known answer tests is run using one test vector and one test key
+     with AES in ECB mode.  ('cipher/rijndael.c:selftest_basic_256')
+
+A.1.2 Hash Algorithm Power-Up Tests
+-----------------------------------
+
+The following hash algorithm tests are run during power-up:
+
+SHA-1
+     A known answer test using the string '"abc"' is run.
+     ('cipher/sha1.c:selftests_sha1')
+SHA-224
+     A known answer test using the string '"abc"' is run.
+     ('cipher/sha256.c:selftests_sha224')
+SHA-256
+     A known answer test using the string '"abc"' is run.
+     ('cipher/sha256.c:selftests_sha256')
+SHA-384
+     A known answer test using the string '"abc"' is run.
+     ('cipher/sha512.c:selftests_sha384')
+SHA-512
+     A known answer test using the string '"abc"' is run.
+     ('cipher/sha512.c:selftests_sha512')
+
+A.1.3 MAC Algorithm Power-Up Tests
+----------------------------------
+
+The following MAC algorithm tests are run during power-up:
+
+HMAC SHA-1
+     A known answer test using 9 byte of data and a 64 byte key is run.
+     ('cipher/hmac-tests.c:selftests_sha1')
+HMAC SHA-224
+     A known answer test using 28 byte of data and a 4 byte key is run.
+     ('cipher/hmac-tests.c:selftests_sha224')
+HMAC SHA-256
+     A known answer test using 28 byte of data and a 4 byte key is run.
+     ('cipher/hmac-tests.c:selftests_sha256')
+HMAC SHA-384
+     A known answer test using 28 byte of data and a 4 byte key is run.
+     ('cipher/hmac-tests.c:selftests_sha384')
+HMAC SHA-512
+     A known answer test using 28 byte of data and a 4 byte key is run.
+     ('cipher/hmac-tests.c:selftests_sha512')
+
+A.1.4 Random Number Power-Up Test
+---------------------------------
+
+The DRNG is tested during power-up this way:
+
+  1. Requesting one block of random using the public interface to check
+     general working and the duplicated block detection.
+  2. 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.
+
+A.1.5 Public Key Algorithm Power-Up Tests
+-----------------------------------------
+
+The public key algorithms are tested during power-up:
+
+RSA
+     A pre-defined 1024 bit RSA key is used and these tests are run in
+     turn:
+       1. Conversion of S-expression to internal format.
+          ('cipher/rsa.c:selftests_rsa')
+       2. Private key consistency check.  ('cipher/rsa.c:selftests_rsa')
+       3. 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.
+          ('cipher/rsa.c:selftest_sign_1024')
+       4. A 1000 bit random value is encrypted and checked that it does
+          not match the original random value.  The encrypted result is
+          then decrypted and checked that it matches the original random
+          value.  ('cipher/rsa.c:selftest_encr_1024')
+
+DSA
+     A pre-defined 1024 bit DSA key is used and these tests are run in
+     turn:
+       1. Conversion of S-expression to internal format.
+          ('cipher/dsa.c:selftests_dsa')
+       2. Private key consistency check.  ('cipher/dsa.c:selftests_dsa')
+       3. 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.
+          ('cipher/dsa.c:selftest_sign_1024')
+
+A.1.6 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 '.hmac'.
+
+A.1.7 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.
+('cipher/des.c:selftest')
+
+A.2 Conditional Tests
+=====================
+
+The conditional tests are performed if a certain condition 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.
+
+A.2.1 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.
+
+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.  ('cipher/rsa.c:test_keys')
+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.  ('cipher/dsa.c:test_keys')
+
+A.2.2 Software Load Tests
+-------------------------
+
+No code is loaded at runtime.
+
+A.2.3 Manual Key Entry Tests
+----------------------------
+
+A manual key entry feature is not implemented in Libgcrypt.
+
+A.2.4 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.
+('random/random-fips.c:x931_aes_driver')
+
+A.3 Application Requested Tests
+===============================
+
+The application may requests tests at any time by means of the
+'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.
+
+A.3.1 Symmetric Cipher Algorithm Tests
+--------------------------------------
+
+The following symmetric encryption algorithm tests are run in addition
+to the power-up tests:
+
+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.
+
+A.3.2 Hash Algorithm Tests
+--------------------------
+
+The following hash algorithm tests are run in addition to the power-up
+tests:
+
+SHA-1
+SHA-224
+SHA-256
+       1. A known answer test using a 56 byte string is run.
+       2. A known answer test using a string of one million letters "a"
+          is run.
+     ('cipher/sha1.c:selftests_sha1',
+     'cipher/sha256.c:selftests_sha224',
+     'cipher/sha256.c:selftests_sha256')
+SHA-384
+SHA-512
+       1. A known answer test using a 112 byte string is run.
+       2. A known answer test using a string of one million letters "a"
+          is run.
+     ('cipher/sha512.c:selftests_sha384',
+     'cipher/sha512.c:selftests_sha512')
+
+A.3.3 MAC Algorithm Tests
+-------------------------
+
+The following MAC algorithm tests are run in addition to the power-up
+tests:
+
+HMAC SHA-1
+       1. A known answer test using 9 byte of data and a 20 byte key is
+          run.
+       2. A known answer test using 9 byte of data and a 100 byte key is
+          run.
+       3. A known answer test using 9 byte of data and a 49 byte key is
+          run.
+     ('cipher/hmac-tests.c:selftests_sha1')
+HMAC SHA-224
+HMAC SHA-256
+HMAC SHA-384
+HMAC SHA-512
+       1. A known answer test using 9 byte of data and a 20 byte key is
+          run.
+       2. A known answer test using 50 byte of data and a 20 byte key is
+          run.
+       3. A known answer test using 50 byte of data and a 26 byte key is
+          run.
+       4. A known answer test using 54 byte of data and a 131 byte key
+          is run.
+       5. A known answer test using 152 byte of data and a 131 byte key
+          is run.
+     ('cipher/hmac-tests.c:selftests_sha224',
+     'cipher/hmac-tests.c:selftests_sha256',
+     'cipher/hmac-tests.c:selftests_sha384',
+     'cipher/hmac-tests.c:selftests_sha512')
+
+
+File: gcrypt.info,  Node: FIPS Mode,  Next: Library Copying,  Prev: Self-Tests,  Up: Top
+
+Appendix B 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.
+
+B.1 Restrictions in FIPS Mode
+=============================
+
+If Libgcrypt is used in FIPS mode these restrictions are effective:
+
+   * The cryptographic algorithms are restricted to this list:
+
+     GCRY_CIPHER_3DES
+          3 key EDE Triple-DES symmetric encryption.
+     GCRY_CIPHER_AES128
+          AES 128 bit symmetric encryption.
+     GCRY_CIPHER_AES192
+          AES 192 bit symmetric encryption.
+     GCRY_CIPHER_AES256
+          AES 256 bit symmetric encryption.
+     GCRY_MD_SHA1
+          SHA-1 message digest.
+     GCRY_MD_SHA224
+          SHA-224 message digest.
+     GCRY_MD_SHA256
+          SHA-256 message digest.
+     GCRY_MD_SHA384
+          SHA-384 message digest.
+     GCRY_MD_SHA512
+          SHA-512 message digest.
+     GCRY_MD_SHA1,GCRY_MD_FLAG_HMAC
+          HMAC using a SHA-1 message digest.
+     GCRY_MD_SHA224,GCRY_MD_FLAG_HMAC
+          HMAC using a SHA-224 message digest.
+     GCRY_MD_SHA256,GCRY_MD_FLAG_HMAC
+          HMAC using a SHA-256 message digest.
+     GCRY_MD_SHA384,GCRY_MD_FLAG_HMAC
+          HMAC using a SHA-384 message digest.
+     GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC
+          HMAC using a SHA-512 message digest.
+     GCRY_PK_RSA
+          RSA encryption and signing.
+     GCRY_PK_DSA
+          DSA signing.
+
+     Note that the CRC algorithms are not considered cryptographic
+     algorithms and thus are in addition available.
+
+   * RSA key generation refuses to create a key with a keysize of less
+     than 1024 bits.
+
+   * DSA key generation refuses to create a key with a keysize other
+     than 1024 bits.
+
+   * The 'transient-key' flag for RSA and DSA key generation is ignored.
+
+   * Support for the VIA Padlock engine is disabled.
+
+   * FIPS mode may only be used on systems with a /dev/random device.
+     Switching into FIPS mode on other systems will fail at runtime.
+
+   * Saving and loading a random seed file is ignored.
+
+   * An X9.31 style random number generator is used in place of the
+     large-pool-CSPRNG generator.
+
+   * The command 'GCRYCTL_ENABLE_QUICK_RANDOM' is ignored.
+
+   * Message digest debugging is disabled.
+
+   * All debug output related to cryptographic data is suppressed.
+
+   * On-the-fly self-tests are not performed, instead self-tests are run
+     before entering operational state.
+
+   * The function '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.
+
+   * 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.
+
+   * In Enforced FIPS mode the command 'GCRYCTL_DISABLE_SECMEM' is
+     ignored.  In standard FIPS mode it disables FIPS mode.
+
+   * A handler set by 'gcry_set_outofcore_handler' is ignored.
+   * A handler set by 'gcry_set_fatalerror_handler' is ignored.
+
+   Note that when we speak about disabling FIPS mode, it merely means
+that the function 'gcry_fips_mode_active' returns false; it does not
+mean that any non FIPS algorithms are allowed.
+
+B.2 FIPS Finite State Machine
+=============================
+
+The FIPS mode of libgcrypt implements a finite state machine (FSM) using
+8 states (*note Table B.1: tbl:fips-states.) and checks at runtime that
+only valid transitions (*note Table B.2: tbl:fips-state-transitions.)
+may happen.
+
+           
+
+Figure B.1: FIPS mode state diagram
+
+States used by the FIPS FSM:
+
+Power-Off
+     Libgcrypt is not runtime linked to another application.  This
+     usually means that the library is not loaded into main memory.
+     This state is documentation only.
+
+Power-On
+     Libgcrypt is loaded into memory and API calls may be made.
+     Compiler introduced constructor functions may be run.  Note that
+     Libgcrypt does not implement any arbitrary constructor functions to
+     be called by the operating system
+
+Init
+     The Libgcrypt initialization functions are performed and the
+     library has not yet run any self-test.
+
+Self-Test
+     Libgcrypt is performing self-tests.
+
+Operational
+     Libgcrypt is in the operational state and all interfaces may be
+     used.
+
+Error
+     Libgrypt is in the error state.  When calling any FIPS relevant
+     interfaces they either return an error ('GPG_ERR_NOT_OPERATIONAL')
+     or put Libgcrypt into the Fatal-Error state and won't return.
+
+Fatal-Error
+     Libgcrypt is in a non-recoverable error state and will
+     automatically transit into the Shutdown state.
+
+Shutdown
+     Libgcrypt is about to be terminated and removed from the memory.
+     The application may at this point still running cleanup handlers.
+
+Table B.1: FIPS mode states
+
+The valid state transitions (*note Figure B.1: fig:fips-fsm.) are:
+'1'
+     Power-Off to Power-On is implicitly done by the OS loading
+     Libgcrypt as a shared library and having it linked to an
+     application.
+
+'2'
+     Power-On to Init is triggered by the application calling the
+     Libgcrypt initialization function 'gcry_check_version'.
+
+'3'
+     Init to Self-Test is either triggered by a dedicated API call or
+     implicit by invoking a libgrypt service controlled by the FSM.
+
+'4'
+     Self-Test to Operational is triggered after all self-tests passed
+     successfully.
+
+'5'
+     Operational to Shutdown is an artificial state without any direct
+     action in Libgcrypt.  When reaching the Shutdown state the library
+     is deinitialized and can't return to any other state again.
+
+'6'
+     Shutdown to Power-off is the process of removing Libgcrypt from the
+     computer's memory.  For obvious reasons the Power-Off state can't
+     be represented within Libgcrypt and thus this transition is for
+     documentation only.
+
+'7'
+     Operational to Error is triggered if Libgcrypt detected an
+     application error which can't be returned to the caller but still
+     allows Libgcrypt to properly run.  In the Error state all FIPS
+     relevant interfaces return an error code.
+
+'8'
+     Error to Shutdown is similar to the Operational to Shutdown
+     transition (5).
+
+'9'
+     Error to Fatal-Error is triggered if Libgrypt detects an fatal
+     error while already being in Error state.
+
+'10'
+     Fatal-Error to Shutdown is automatically entered by Libgcrypt after
+     having reported the error.
+
+'11'
+     Power-On to Shutdown is an artificial state to document that
+     Libgcrypt has not ye been initialized but the process is about to
+     terminate.
+
+'12'
+     Power-On to Fatal-Error will be triggered if certain Libgcrypt
+     functions are used without having reached the Init state.
+
+'13'
+     Self-Test to Fatal-Error is triggered by severe errors in Libgcrypt
+     while running self-tests.
+
+'14'
+     Self-Test to Error is triggered by a failed self-test.
+
+'15'
+     Operational to Fatal-Error is triggered if Libcrypt encountered a
+     non-recoverable error.
+
+'16'
+     Operational to Self-Test is triggered if the application requested
+     to run the self-tests again.
+
+'17'
+     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.
+
+'18'
+     Init to Error is triggered by errors in the initialization code.
+
+'19'
+     Init to Fatal-Error is triggered by non-recoverable errors in the
+     initialization code.
+
+'20'
+     Error to Error is triggered by errors while already in the Error
+     state.
+
+Table B.2: FIPS mode state transitions
+
+B.3 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
+'gcry_malloc_secure' and 'gcry_calloc_secure'.  By calling '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 'GCRYCTL_TERM_SECMEM' before
+process termination.  This will zero out the entire secure memory and
+thus also the encryption contexts with these keys.
+
+
+File: gcrypt.info,  Node: Library Copying,  Next: Copying,  Prev: FIPS Mode,  Up: Top
+
+GNU Lesser General Public License
+*********************************
+
+                      Version 2.1, February 1999
+
+     Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+     [This is the first released version of the Lesser GPL.  It also counts
+     as the successor of the GNU Library Public License, version 2, hence the
+     version number 2.1.]
+
+Preamble
+========
+
+The licenses for most software are designed to take away your freedom to
+share and change it.  By contrast, the GNU General Public Licenses are
+intended to guarantee your freedom to share and change free software--to
+make sure the software is free for all its users.
+
+   This license, the Lesser General Public License, applies to some
+specially designated software--typically libraries--of the Free Software
+Foundation and other authors who decide to use it.  You can use it too,
+but we suggest you first think carefully about whether this license or
+the ordinary General Public License is the better strategy to use in any
+particular case, based on the explanations below.
+
+   When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of it
+in new free programs; and that you are informed that you can do these
+things.
+
+   To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+   For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling it.
+And you must show them these terms so they know their rights.
+
+   We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+   To protect each distributor, we want to make it very clear that there
+is no warranty for the free library.  Also, if the library is modified
+by someone else and passed on, the recipients should know that what they
+have is not the original version, so that the original author's
+reputation will not be affected by problems that might be introduced by
+others.
+
+   Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that any
+patent license obtained for a version of the library must be consistent
+with the full freedom of use specified in this license.
+
+   Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and is
+quite different from the ordinary General Public License.  We use this
+license for certain libraries in order to permit linking those libraries
+into non-free programs.
+
+   When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the entire
+combination fits its criteria of freedom.  The Lesser General Public
+License permits more lax criteria for linking other code with the
+library.
+
+   We call this license the "Lesser" General Public License because it
+does _Less_ to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less of
+an advantage over competing non-free programs.  These disadvantages are
+the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+   For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it
+becomes a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free library
+does the same job as widely used non-free libraries.  In this case,
+there is little to gain by limiting the free library to free software
+only, so we use the Lesser General Public License.
+
+   In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of free
+software.  For example, permission to use the GNU C Library in non-free
+programs enables many more people to use the whole GNU operating system,
+as well as its variant, the GNU/Linux operating system.
+
+   Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is linked
+with the Library has the freedom and the wherewithal to run that program
+using a modified version of the Library.
+
+   The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+                   GNU LESSER GENERAL PUBLIC LICENSE
+    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library or other
+     program which contains a notice placed by the copyright holder or
+     other authorized party saying it may be distributed under the terms
+     of this Lesser General Public License (also called "this License").
+     Each licensee is addressed as "you".
+
+     A "library" means a collection of software functions and/or data
+     prepared so as to be conveniently linked with application programs
+     (which use some of those functions and data) to form executables.
+
+     The "Library", below, refers to any such software library or work
+     which has been distributed under these terms.  A "work based on the
+     Library" means either the Library or any derivative work under
+     copyright law: that is to say, a work containing the Library or a
+     portion of it, either verbatim or with modifications and/or
+     translated straightforwardly into another language.  (Hereinafter,
+     translation is included without limitation in the term
+     "modification".)
+
+     "Source code" for a work means the preferred form of the work for
+     making modifications to it.  For a library, complete source code
+     means all the source code for all modules it contains, plus any
+     associated interface definition files, plus the scripts used to
+     control compilation and installation of the library.
+
+     Activities other than copying, distribution and modification are
+     not covered by this License; they are outside its scope.  The act
+     of running a program using the Library is not restricted, and
+     output from such a program is covered only if its contents
+     constitute a work based on the Library (independent of the use of
+     the Library in a tool for writing it).  Whether that is true
+     depends on what the Library does and what the program that uses the
+     Library does.
+
+  1. You may copy and distribute verbatim copies of the Library's
+     complete source code as you receive it, in any medium, provided
+     that you conspicuously and appropriately publish on each copy an
+     appropriate copyright notice and disclaimer of warranty; keep
+     intact all the notices that refer to this License and to the
+     absence of any warranty; and distribute a copy of this License
+     along with the Library.
+
+     You may charge a fee for the physical act of transferring a copy,
+     and you may at your option offer warranty protection in exchange
+     for a fee.
+
+  2. You may modify your copy or copies of the Library or any portion of
+     it, thus forming a work based on the Library, and copy and
+     distribute such modifications or work under the terms of Section 1
+     above, provided that you also meet all of these conditions:
+
+       a. The modified work must itself be a software library.
+
+       b. You must cause the files modified to carry prominent notices
+          stating that you changed the files and the date of any change.
+
+       c. You must cause the whole of the work to be licensed at no
+          charge to all third parties under the terms of this License.
+
+       d. If a facility in the modified Library refers to a function or
+          a table of data to be supplied by an application program that
+          uses the facility, other than as an argument passed when the
+          facility is invoked, then you must make a good faith effort to
+          ensure that, in the event an application does not supply such
+          function or table, the facility still operates, and performs
+          whatever part of its purpose remains meaningful.
+
+          (For example, a function in a library to compute square roots
+          has a purpose that is entirely well-defined independent of the
+          application.  Therefore, Subsection 2d requires that any
+          application-supplied function or table used by this function
+          must be optional: if the application does not supply it, the
+          square root function must still compute square roots.)
+
+     These requirements apply to the modified work as a whole.  If
+     identifiable sections of that work are not derived from the
+     Library, and can be reasonably considered independent and separate
+     works in themselves, then this License, and its terms, do not apply
+     to those sections when you distribute them as separate works.  But
+     when you distribute the same sections as part of a whole which is a
+     work based on the Library, the distribution of the whole must be on
+     the terms of this License, whose permissions for other licensees
+     extend to the entire whole, and thus to each and every part
+     regardless of who wrote it.
+
+     Thus, it is not the intent of this section to claim rights or
+     contest your rights to work written entirely by you; rather, the
+     intent is to exercise the right to control the distribution of
+     derivative or collective works based on the Library.
+
+     In addition, mere aggregation of another work not based on the
+     Library with the Library (or with a work based on the Library) on a
+     volume of a storage or distribution medium does not bring the other
+     work under the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+     License instead of this License to a given copy of the Library.  To
+     do this, you must alter all the notices that refer to this License,
+     so that they refer to the ordinary GNU General Public License,
+     version 2, instead of to this License.  (If a newer version than
+     version 2 of the ordinary GNU General Public License has appeared,
+     then you can specify that version instead if you wish.)  Do not
+     make any other change in these notices.
+
+     Once this change is made in a given copy, it is irreversible for
+     that copy, so the ordinary GNU General Public License applies to
+     all subsequent copies and derivative works made from that copy.
+
+     This option is useful when you wish to copy part of the code of the
+     Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or derivative
+     of it, under Section 2) in object code or executable form under the
+     terms of Sections 1 and 2 above provided that you accompany it with
+     the complete corresponding machine-readable source code, which must
+     be distributed under the terms of Sections 1 and 2 above on a
+     medium customarily used for software interchange.
+
+     If distribution of object code is made by offering access to copy
+     from a designated place, then offering equivalent access to copy
+     the source code from the same place satisfies the requirement to
+     distribute the source code, even though third parties are not
+     compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+     Library, but is designed to work with the Library by being compiled
+     or linked with it, is called a "work that uses the Library".  Such
+     a work, in isolation, is not a derivative work of the Library, and
+     therefore falls outside the scope of this License.
+
+     However, linking a "work that uses the Library" with the Library
+     creates an executable that is a derivative of the Library (because
+     it contains portions of the Library), rather than a "work that uses
+     the library".  The executable is therefore covered by this License.
+     Section 6 states terms for distribution of such executables.
+
+     When a "work that uses the Library" uses material from a header
+     file that is part of the Library, the object code for the work may
+     be a derivative work of the Library even though the source code is
+     not.  Whether this is true is especially significant if the work
+     can be linked without the Library, or if the work is itself a
+     library.  The threshold for this to be true is not precisely
+     defined by law.
+
+     If such an object file uses only numerical parameters, data
+     structure layouts and accessors, and small macros and small inline
+     functions (ten lines or less in length), then the use of the object
+     file is unrestricted, regardless of whether it is legally a
+     derivative work.  (Executables containing this object code plus
+     portions of the Library will still fall under Section 6.)
+
+     Otherwise, if the work is a derivative of the Library, you may
+     distribute the object code for the work under the terms of Section
+     6.  Any executables containing that work also fall under Section 6,
+     whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also combine or link
+     a "work that uses the Library" with the Library to produce a work
+     containing portions of the Library, and distribute that work under
+     terms of your choice, provided that the terms permit modification
+     of the work for the customer's own use and reverse engineering for
+     debugging such modifications.
+
+     You must give prominent notice with each copy of the work that the
+     Library is used in it and that the Library and its use are covered
+     by this License.  You must supply a copy of this License.  If the
+     work during execution displays copyright notices, you must include
+     the copyright notice for the Library among them, as well as a
+     reference directing the user to the copy of this License.  Also,
+     you must do one of these things:
+
+       a. Accompany the work with the complete corresponding
+          machine-readable source code for the Library including
+          whatever changes were used in the work (which must be
+          distributed under Sections 1 and 2 above); and, if the work is
+          an executable linked with the Library, with the complete
+          machine-readable "work that uses the Library", as object code
+          and/or source code, so that the user can modify the Library
+          and then relink to produce a modified executable containing
+          the modified Library.  (It is understood that the user who
+          changes the contents of definitions files in the Library will
+          not necessarily be able to recompile the application to use
+          the modified definitions.)
+
+       b. Use a suitable shared library mechanism for linking with the
+          Library.  A suitable mechanism is one that (1) uses at run
+          time a copy of the library already present on the user's
+          computer system, rather than copying library functions into
+          the executable, and (2) will operate properly with a modified
+          version of the library, if the user installs one, as long as
+          the modified version is interface-compatible with the version
+          that the work was made with.
+
+       c. Accompany the work with a written offer, valid for at least
+          three years, to give the same user the materials specified in
+          Subsection 6a, above, for a charge no more than the cost of
+          performing this distribution.
+
+       d. If distribution of the work is made by offering access to copy
+          from a designated place, offer equivalent access to copy the
+          above specified materials from the same place.
+
+       e. Verify that the user has already received a copy of these
+          materials or that you have already sent this user a copy.
+
+     For an executable, the required form of the "work that uses the
+     Library" must include any data and utility programs needed for
+     reproducing the executable from it.  However, as a special
+     exception, the materials to be distributed need not include
+     anything that is normally distributed (in either source or binary
+     form) with the major components (compiler, kernel, and so on) of
+     the operating system on which the executable runs, unless that
+     component itself accompanies the executable.
+
+     It may happen that this requirement contradicts the license
+     restrictions of other proprietary libraries that do not normally
+     accompany the operating system.  Such a contradiction means you
+     cannot use both them and the Library together in an executable that
+     you distribute.
+
+  7. You may place library facilities that are a work based on the
+     Library side-by-side in a single library together with other
+     library facilities not covered by this License, and distribute such
+     a combined library, provided that the separate distribution of the
+     work based on the Library and of the other library facilities is
+     otherwise permitted, and provided that you do these two things:
+
+       a. Accompany the combined library with a copy of the same work
+          based on the Library, uncombined with any other library
+          facilities.  This must be distributed under the terms of the
+          Sections above.
+
+       b. Give prominent notice with the combined library of the fact
+          that part of it is a work based on the Library, and explaining
+          where to find the accompanying uncombined form of the same
+          work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute the
+     Library except as expressly provided under this License.  Any
+     attempt otherwise to copy, modify, sublicense, link with, or
+     distribute the Library is void, and will automatically terminate
+     your rights under this License.  However, parties who have received
+     copies, or rights, from you under this License will not have their
+     licenses terminated so long as such parties remain in full
+     compliance.
+
+  9. You are not required to accept this License, since you have not
+     signed it.  However, nothing else grants you permission to modify
+     or distribute the Library or its derivative works.  These actions
+     are prohibited by law if you do not accept this License.
+     Therefore, by modifying or distributing the Library (or any work
+     based on the Library), you indicate your acceptance of this License
+     to do so, and all its terms and conditions for copying,
+     distributing or modifying the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+     Library), the recipient automatically receives a license from the
+     original licensor to copy, distribute, link with or modify the
+     Library subject to these terms and conditions.  You may not impose
+     any further restrictions on the recipients' exercise of the rights
+     granted herein.  You are not responsible for enforcing compliance
+     by third parties with this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+     infringement or for any other reason (not limited to patent
+     issues), conditions are imposed on you (whether by court order,
+     agreement or otherwise) that contradict the conditions of this
+     License, they do not excuse you from the conditions of this
+     License.  If you cannot distribute so as to satisfy simultaneously
+     your obligations under this License and any other pertinent
+     obligations, then as a consequence you may not distribute the
+     Library at all.  For example, if a patent license would not permit
+     royalty-free redistribution of the Library by all those who receive
+     copies directly or indirectly through you, then the only way you
+     could satisfy both it and this License would be to refrain entirely
+     from distribution of the Library.
+
+     If any portion of this section is held invalid or unenforceable
+     under any particular circumstance, the balance of the section is
+     intended to apply, and the section as a whole is intended to apply
+     in other circumstances.
+
+     It is not the purpose of this section to induce you to infringe any
+     patents or other property right claims or to contest validity of
+     any such claims; this section has the sole purpose of protecting
+     the integrity of the free software distribution system which is
+     implemented by public license practices.  Many people have made
+     generous contributions to the wide range of software distributed
+     through that system in reliance on consistent application of that
+     system; it is up to the author/donor to decide if he or she is
+     willing to distribute software through any other system and a
+     licensee cannot impose that choice.
+
+     This section is intended to make thoroughly clear what is believed
+     to be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+     certain countries either by patents or by copyrighted interfaces,
+     the original copyright holder who places the Library under this
+     License may add an explicit geographical distribution limitation
+     excluding those countries, so that distribution is permitted only
+     in or among countries not thus excluded.  In such case, this
+     License incorporates the limitation as if written in the body of
+     this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+     versions of the Lesser General Public License from time to time.
+     Such new versions will be similar in spirit to the present version,
+     but may differ in detail to address new problems or concerns.
+
+     Each version is given a distinguishing version number.  If the
+     Library specifies a version number of this License which applies to
+     it and "any later version", you have the option of following the
+     terms and conditions either of that version or of any later version
+     published by the Free Software Foundation.  If the Library does not
+     specify a license version number, you may choose any version ever
+     published by the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+     programs whose distribution conditions are incompatible with these,
+     write to the author to ask for permission.  For software which is
+     copyrighted by the Free Software Foundation, write to the Free
+     Software Foundation; we sometimes make exceptions for this.  Our
+     decision will be guided by the two goals of preserving the free
+     status of all derivatives of our free software and of promoting the
+     sharing and reuse of software generally.
+
+                              NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+     WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE
+     LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
+     AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY
+     OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+     FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
+     PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE
+     DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
+     OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+     MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
+     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+     INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
+     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+     OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY
+     OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+                      END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Libraries
+==============================================
+
+If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of
+the ordinary General Public License).
+
+   To apply these terms, attach the following notices to the library.
+It is safest to attach them to the start of each source file to most
+effectively convey the exclusion of warranty; and each file should have
+at least the "copyright" line and a pointer to where the full notice is
+found.
+
+     ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES.
+     Copyright (C) YEAR  NAME OF AUTHOR
+
+     This library is free software; you can redistribute it and/or modify it
+     under the terms of the GNU Lesser General Public License as published by
+     the Free Software Foundation; either version 2.1 of the License, or (at
+     your option) any later version.
+
+     This library is distributed in the hope that it will be useful, but
+     WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
+     USA.
+
+   Also add information on how to contact you by electronic and paper
+mail.
+
+   You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the library,
+if necessary.  Here is a sample; alter the names:
+
+     Yoyodyne, Inc., hereby disclaims all copyright interest in the library
+     `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+     SIGNATURE OF TY COON, 1 April 1990
+     Ty Coon, President of Vice
+
+   That's all there is to it!
+
+
+File: gcrypt.info,  Node: Copying,  Next: Figures and Tables,  Prev: Library Copying,  Up: Top
+
+GNU General Public License
+**************************
+
+                         Version 2, June 1991
+
+     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+Preamble
+========
+
+The licenses for most software are designed to take away your freedom to
+share and change it.  By contrast, the GNU General Public License is
+intended to guarantee your freedom to share and change free software--to
+make sure the software is free for all its users.  This General Public
+License applies to most of the Free Software Foundation's software and
+to any other program whose authors commit to using it.  (Some other Free
+Software Foundation software is covered by the GNU Library General
+Public License instead.)  You can apply it to your programs, too.
+
+   When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it if
+you want it, that you can change the software or use pieces of it in new
+free programs; and that you know you can do these things.
+
+   To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+   For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+   We protect your rights with two steps: (1) copyright the software,
+and (2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+   Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+   Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+   The precise terms and conditions for copying, distribution and
+modification follow.
+
+    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  1. This License applies to any program or other work which contains a
+     notice placed by the copyright holder saying it may be distributed
+     under the terms of this General Public License.  The "Program",
+     below, refers to any such program or work, and a "work based on the
+     Program" means either the Program or any derivative work under
+     copyright law: that is to say, a work containing the Program or a
+     portion of it, either verbatim or with modifications and/or
+     translated into another language.  (Hereinafter, translation is
+     included without limitation in the term "modification".)  Each
+     licensee is addressed as "you".
+
+     Activities other than copying, distribution and modification are
+     not covered by this License; they are outside its scope.  The act
+     of running the Program is not restricted, and the output from the
+     Program is covered only if its contents constitute a work based on
+     the Program (independent of having been made by running the
+     Program).  Whether that is true depends on what the Program does.
+
+  2. You may copy and distribute verbatim copies of the Program's source
+     code as you receive it, in any medium, provided that you
+     conspicuously and appropriately publish on each copy an appropriate
+     copyright notice and disclaimer of warranty; keep intact all the
+     notices that refer to this License and to the absence of any
+     warranty; and give any other recipients of the Program a copy of
+     this License along with the Program.
+
+     You may charge a fee for the physical act of transferring a copy,
+     and you may at your option offer warranty protection in exchange
+     for a fee.
+
+  3. You may modify your copy or copies of the Program or any portion of
+     it, thus forming a work based on the Program, and copy and
+     distribute such modifications or work under the terms of Section 1
+     above, provided that you also meet all of these conditions:
+
+       a. You must cause the modified files to carry prominent notices
+          stating that you changed the files and the date of any change.
+
+       b. You must cause any work that you distribute or publish, that
+          in whole or in part contains or is derived from the Program or
+          any part thereof, to be licensed as a whole at no charge to
+          all third parties under the terms of this License.
+
+       c. If the modified program normally reads commands interactively
+          when run, you must cause it, when started running for such
+          interactive use in the most ordinary way, to print or display
+          an announcement including an appropriate copyright notice and
+          a notice that there is no warranty (or else, saying that you
+          provide a warranty) and that users may redistribute the
+          program under these conditions, and telling the user how to
+          view a copy of this License.  (Exception: if the Program
+          itself is interactive but does not normally print such an
+          announcement, your work based on the Program is not required
+          to print an announcement.)
+
+     These requirements apply to the modified work as a whole.  If
+     identifiable sections of that work are not derived from the
+     Program, and can be reasonably considered independent and separate
+     works in themselves, then this License, and its terms, do not apply
+     to those sections when you distribute them as separate works.  But
+     when you distribute the same sections as part of a whole which is a
+     work based on the Program, the distribution of the whole must be on
+     the terms of this License, whose permissions for other licensees
+     extend to the entire whole, and thus to each and every part
+     regardless of who wrote it.
+
+     Thus, it is not the intent of this section to claim rights or
+     contest your rights to work written entirely by you; rather, the
+     intent is to exercise the right to control the distribution of
+     derivative or collective works based on the Program.
+
+     In addition, mere aggregation of another work not based on the
+     Program with the Program (or with a work based on the Program) on a
+     volume of a storage or distribution medium does not bring the other
+     work under the scope of this License.
+
+  4. You may copy and distribute the Program (or a work based on it,
+     under Section 2) in object code or executable form under the terms
+     of Sections 1 and 2 above provided that you also do one of the
+     following:
+
+       a. Accompany it with the complete corresponding machine-readable
+          source code, which must be distributed under the terms of
+          Sections 1 and 2 above on a medium customarily used for
+          software interchange; or,
+
+       b. Accompany it with a written offer, valid for at least three
+          years, to give any third party, for a charge no more than your
+          cost of physically performing source distribution, a complete
+          machine-readable copy of the corresponding source code, to be
+          distributed under the terms of Sections 1 and 2 above on a
+          medium customarily used for software interchange; or,
+
+       c. Accompany it with the information you received as to the offer
+          to distribute corresponding source code.  (This alternative is
+          allowed only for noncommercial distribution and only if you
+          received the program in object code or executable form with
+          such an offer, in accord with Subsection b above.)
+
+     The source code for a work means the preferred form of the work for
+     making modifications to it.  For an executable work, complete
+     source code means all the source code for all modules it contains,
+     plus any associated interface definition files, plus the scripts
+     used to control compilation and installation of the executable.
+     However, as a special exception, the source code distributed need
+     not include anything that is normally distributed (in either source
+     or binary form) with the major components (compiler, kernel, and so
+     on) of the operating system on which the executable runs, unless
+     that component itself accompanies the executable.
+
+     If distribution of executable or object code is made by offering
+     access to copy from a designated place, then offering equivalent
+     access to copy the source code from the same place counts as
+     distribution of the source code, even though third parties are not
+     compelled to copy the source along with the object code.
+
+  5. You may not copy, modify, sublicense, or distribute the Program
+     except as expressly provided under this License.  Any attempt
+     otherwise to copy, modify, sublicense or distribute the Program is
+     void, and will automatically terminate your rights under this
+     License.  However, parties who have received copies, or rights,
+     from you under this License will not have their licenses terminated
+     so long as such parties remain in full compliance.
+
+  6. You are not required to accept this License, since you have not
+     signed it.  However, nothing else grants you permission to modify
+     or distribute the Program or its derivative works.  These actions
+     are prohibited by law if you do not accept this License.
+     Therefore, by modifying or distributing the Program (or any work
+     based on the Program), you indicate your acceptance of this License
+     to do so, and all its terms and conditions for copying,
+     distributing or modifying the Program or works based on it.
+
+  7. Each time you redistribute the Program (or any work based on the
+     Program), the recipient automatically receives a license from the
+     original licensor to copy, distribute or modify the Program subject
+     to these terms and conditions.  You may not impose any further
+     restrictions on the recipients' exercise of the rights granted
+     herein.  You are not responsible for enforcing compliance by third
+     parties to this License.
+
+  8. If, as a consequence of a court judgment or allegation of patent
+     infringement or for any other reason (not limited to patent
+     issues), conditions are imposed on you (whether by court order,
+     agreement or otherwise) that contradict the conditions of this
+     License, they do not excuse you from the conditions of this
+     License.  If you cannot distribute so as to satisfy simultaneously
+     your obligations under this License and any other pertinent
+     obligations, then as a consequence you may not distribute the
+     Program at all.  For example, if a patent license would not permit
+     royalty-free redistribution of the Program by all those who receive
+     copies directly or indirectly through you, then the only way you
+     could satisfy both it and this License would be to refrain entirely
+     from distribution of the Program.
+
+     If any portion of this section is held invalid or unenforceable
+     under any particular circumstance, the balance of the section is
+     intended to apply and the section as a whole is intended to apply
+     in other circumstances.
+
+     It is not the purpose of this section to induce you to infringe any
+     patents or other property right claims or to contest validity of
+     any such claims; this section has the sole purpose of protecting
+     the integrity of the free software distribution system, which is
+     implemented by public license practices.  Many people have made
+     generous contributions to the wide range of software distributed
+     through that system in reliance on consistent application of that
+     system; it is up to the author/donor to decide if he or she is
+     willing to distribute software through any other system and a
+     licensee cannot impose that choice.
+
+     This section is intended to make thoroughly clear what is believed
+     to be a consequence of the rest of this License.
+
+  9. If the distribution and/or use of the Program is restricted in
+     certain countries either by patents or by copyrighted interfaces,
+     the original copyright holder who places the Program under this
+     License may add an explicit geographical distribution limitation
+     excluding those countries, so that distribution is permitted only
+     in or among countries not thus excluded.  In such case, this
+     License incorporates the limitation as if written in the body of
+     this License.
+
+  10. The Free Software Foundation may publish revised and/or new
+     versions of the General Public License from time to time.  Such new
+     versions will be similar in spirit to the present version, but may
+     differ in detail to address new problems or concerns.
+
+     Each version is given a distinguishing version number.  If the
+     Program specifies a version number of this License which applies to
+     it and "any later version", you have the option of following the
+     terms and conditions either of that version or of any later version
+     published by the Free Software Foundation.  If the Program does not
+     specify a version number of this License, you may choose any
+     version ever published by the Free Software Foundation.
+
+  11. If you wish to incorporate parts of the Program into other free
+     programs whose distribution conditions are different, write to the
+     author to ask for permission.  For software which is copyrighted by
+     the Free Software Foundation, write to the Free Software
+     Foundation; we sometimes make exceptions for this.  Our decision
+     will be guided by the two goals of preserving the free status of
+     all derivatives of our free software and of promoting the sharing
+     and reuse of software generally.
+
+                              NO WARRANTY
+
+  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
+     LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
+     AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+     OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+     FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
+     PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
+     DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
+     OR CORRECTION.
+
+  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
+     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
+     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+                      END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+=============================================
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+   To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
+     Copyright (C) 19YY  NAME OF AUTHOR
+
+     This program is free software; you can redistribute it and/or
+     modify it under the terms of the GNU General Public License
+     as published by the Free Software Foundation; either version 2
+     of the License, or (at your option) any later version.
+
+     This program is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+     GNU General Public License for more details.
+
+     You should have received a copy of the GNU General Public License along
+     with this program; if not, write to the Free Software Foundation, Inc.,
+     59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+
+   Also add information on how to contact you by electronic and paper
+mail.
+
+   If the program is interactive, make it output a short notice like
+this when it starts in an interactive mode:
+
+     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
+     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+     type `show w'.  This is free software, and you are welcome
+     to redistribute it under certain conditions; type `show c'
+     for details.
+
+   The hypothetical commands 'show w' and 'show c' should show the
+appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than 'show w' and 'show
+c'; they could even be mouse-clicks or menu items--whatever suits your
+program.
+
+   You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the program,
+if necessary.  Here is a sample; alter the names:
+
+     Yoyodyne, Inc., hereby disclaims all copyright
+     interest in the program `Gnomovision'
+     (which makes passes at compilers) written
+     by James Hacker.
+
+     SIGNATURE OF TY COON, 1 April 1989
+     Ty Coon, President of Vice
+
+   This General Public License does not permit incorporating your
+program into proprietary programs.  If your program is a subroutine
+library, you may consider it more useful to permit linking proprietary
+applications with the library.  If this is what you want to do, use the
+GNU Library General Public License instead of this License.
+
+
+File: gcrypt.info,  Node: Figures and Tables,  Next: Concept Index,  Prev: Copying,  Up: Top
+
+List of Figures and Tables
+**************************
+
+* Menu:
+
+* Figure 17.1: fig:subsystems.           Libgcrypt subsystems
+* Figure B.1: fig:fips-fsm.              FIPS mode state diagram
+
+* Menu:
+
+* Table B.1: tbl:fips-states.            FIPS mode states
+* Table B.2: tbl:fips-state-transitions. FIPS mode state transitions
+
+
+File: gcrypt.info,  Node: Concept Index,  Next: Function and Data Index,  Prev: Figures and Tables,  Up: Top
+
+Concept Index
+*************
+
+
+* Menu:
+
+* /etc/gcrypt/fips_enabled:              Configuration.        (line 69)
+* /etc/gcrypt/hwf.deny:                  Configuration.        (line 48)
+* /etc/gcrypt/random.conf:               Configuration.        (line 52)
+* /proc/cpuinfo:                         Configuration.        (line 74)
+* /proc/self/auxv:                       Configuration.        (line 74)
+* 3DES:                                  Available ciphers.    (line 14)
+* Advanced Encryption Standard:          Available ciphers.    (line 35)
+* AES:                                   Available ciphers.    (line 35)
+* AES-Wrap mode:                         Available cipher modes.
+                                                               (line 35)
+* Arcfour:                               Available ciphers.    (line 52)
+* BLAKE2b-512, BLAKE2b-384, BLAKE2b-256, BLAKE2b-160: Available hash algorithms.
+                                                               (line  6)
+* BLAKE2s-256, BLAKE2s-224, BLAKE2s-160, BLAKE2s-128: Available hash algorithms.
+                                                               (line  6)
+* Blowfish:                              Available ciphers.    (line 22)
+* bug emulation:                         Working with hash algorithms.
+                                                               (line 38)
+* Camellia:                              Available ciphers.    (line 77)
+* CAST5:                                 Available ciphers.    (line 19)
+* CBC, Cipher Block Chaining mode:       Available cipher modes.
+                                                               (line 23)
+* CBC-MAC:                               Working with cipher handles.
+                                                               (line 56)
+* CCM, Counter with CBC-MAC mode:        Available cipher modes.
+                                                               (line 48)
+* CFB, Cipher Feedback mode:             Available cipher modes.
+                                                               (line 17)
+* ChaCha20:                              Available ciphers.    (line 92)
+* cipher text stealing:                  Working with cipher handles.
+                                                               (line 50)
+* comp:                                  Cryptographic Functions.
+                                                               (line 13)
+* CRC32:                                 Available hash algorithms.
+                                                               (line  6)
+* CTR, Counter mode:                     Available cipher modes.
+                                                               (line 32)
+* DES:                                   Available ciphers.    (line 57)
+* DES-EDE:                               Available ciphers.    (line 14)
+* Digital Encryption Standard:           Available ciphers.    (line 14)
+* disable-jent:                          Configuration.        (line 58)
+* ECB, Electronic Codebook mode:         Available cipher modes.
+                                                               (line 13)
+* EdDSA:                                 Cryptographic Functions.
+                                                               (line 33)
+* Enforced FIPS mode:                    Enabling FIPS mode.   (line 29)
+* error codes:                           Error Values.         (line  6)
+* error codes, list of:                  Error Sources.        (line  6)
+* error codes, list of <1>:              Error Codes.          (line  6)
+* error codes, printing of:              Error Strings.        (line  6)
+* error sources:                         Error Values.         (line  6)
+* error sources, printing of:            Error Strings.        (line  6)
+* error strings:                         Error Strings.        (line  6)
+* error values:                          Error Values.         (line  6)
+* error values, printing of:             Error Strings.        (line  6)
+* FIPS 140:                              Enabling FIPS mode.   (line  6)
+* FIPS 186:                              Cryptographic Functions.
+                                                               (line 72)
+* FIPS 186 <1>:                          Public-Key Subsystem Architecture.
+                                                               (line 50)
+* FIPS 186-2:                            Cryptographic Functions.
+                                                               (line 80)
+* FIPS mode:                             Enabling FIPS mode.   (line  6)
+* fips_enabled:                          Configuration.        (line 69)
+* GCM, Galois/Counter Mode:              Available cipher modes.
+                                                               (line 53)
+* GCRYPT_BARRETT:                        Configuration.        (line 12)
+* GCRYPT_RNDUNIX_DBG:                    Configuration.        (line 17)
+* GCRYPT_RNDUNIX_DBGALL:                 Configuration.        (line 17)
+* GCRYPT_RNDW32_DBG:                     Configuration.        (line 32)
+* GCRYPT_RNDW32_NOPERF:                  Configuration.        (line 25)
+* GOST 28147-89:                         Available ciphers.    (line 88)
+* GPL, GNU General Public License:       Copying.              (line  6)
+* hardware features:                     Hardware features.    (line  6)
+* HAVAL:                                 Available hash algorithms.
+                                                               (line  6)
+* HMAC:                                  Working with hash algorithms.
+                                                               (line 28)
+* HMAC-GOSTR-3411-94:                    Available MAC algorithms.
+                                                               (line  6)
+* HMAC-MD2, HMAC-MD4, HMAC-MD5:          Available MAC algorithms.
+                                                               (line  6)
+* HMAC-RIPE-MD-160:                      Available MAC algorithms.
+                                                               (line  6)
+* HMAC-SHA-1:                            Available MAC algorithms.
+                                                               (line  6)
+* HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, HMAC-SHA-512: Available MAC algorithms.
+                                                               (line  6)
+* HMAC-SHA3-224, HMAC-SHA3-256, HMAC-SHA3-384, HMAC-SHA3-512: Available MAC algorithms.
+                                                               (line  6)
+* HMAC-Stribog-256, HMAC-Stribog-512:    Available MAC algorithms.
+                                                               (line  6)
+* HMAC-TIGER1:                           Available MAC algorithms.
+                                                               (line  6)
+* HMAC-Whirlpool:                        Available MAC algorithms.
+                                                               (line  6)
+* HOME:                                  Configuration.        (line 37)
+* IDEA:                                  Available ciphers.    (line 11)
+* LGPL, GNU Lesser General Public License: Library Copying.    (line  6)
+* MD2, MD4, MD5:                         Available hash algorithms.
+                                                               (line  6)
+* no-blinding:                           Cryptographic Functions.
+                                                               (line 41)
+* no-keytest:                            Cryptographic Functions.
+                                                               (line 59)
+* nocomp:                                Cryptographic Functions.
+                                                               (line 13)
+* OAEP:                                  Cryptographic Functions.
+                                                               (line 27)
+* OCB, OCB3:                             Available cipher modes.
+                                                               (line 63)
+* OFB, Output Feedback mode:             Available cipher modes.
+                                                               (line 29)
+* only-urandom:                          Configuration.        (line 61)
+* param:                                 Cryptographic Functions.
+                                                               (line 47)
+* PKCS1:                                 Cryptographic Functions.
+                                                               (line 23)
+* Poly1305 based AEAD mode with ChaCha20: Available cipher modes.
+                                                               (line 58)
+* PSS:                                   Cryptographic Functions.
+                                                               (line 30)
+* RC2:                                   Available ciphers.    (line 69)
+* RC4:                                   Available ciphers.    (line 52)
+* rfc-2268:                              Available ciphers.    (line 69)
+* RFC6979:                               Cryptographic Functions.
+                                                               (line 38)
+* Rijndael:                              Available ciphers.    (line 35)
+* RIPE-MD-160:                           Available hash algorithms.
+                                                               (line  6)
+* Salsa20:                               Available ciphers.    (line 81)
+* Salsa20/12:                            Available ciphers.    (line 84)
+* Seed (cipher):                         Available ciphers.    (line 72)
+* Serpent:                               Available ciphers.    (line 65)
+* SHA-1:                                 Available hash algorithms.
+                                                               (line  6)
+* SHA-224, SHA-256, SHA-384, SHA-512:    Available hash algorithms.
+                                                               (line  6)
+* SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256: Available hash algorithms.
+                                                               (line  6)
+* sync mode (OpenPGP):                   Working with cipher handles.
+                                                               (line 46)
+* TIGER, TIGER1, TIGER2:                 Available hash algorithms.
+                                                               (line  6)
+* transient-key:                         Cryptographic Functions.
+                                                               (line 52)
+* Triple-DES:                            Available ciphers.    (line 14)
+* Twofish:                               Available ciphers.    (line 46)
+* Whirlpool:                             Available hash algorithms.
+                                                               (line  6)
+* X9.31:                                 Cryptographic Functions.
+                                                               (line 65)
+* X9.31 <1>:                             Public-Key Subsystem Architecture.
+                                                               (line 50)
+* XTS, XTS mode:                         Available cipher modes.
+                                                               (line 74)
+
diff --git a/libotr/libgcrypt-1.8.7/doc/gcrypt.info-2 b/libotr/libgcrypt-1.8.7/doc/gcrypt.info-2
new file mode 100644
index 0000000..e1bf652
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/gcrypt.info-2
Binary files differdiff --git a/libotr/libgcrypt-1.8.7/doc/gcrypt.texi b/libotr/libgcrypt-1.8.7/doc/gcrypt.texi
new file mode 100644
index 0000000..7cd1b0f
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/gcrypt.texi
@@ -0,0 +1,6698 @@
+\input texinfo                  @c -*- Texinfo -*-
+@c %**start of header
+@setfilename gcrypt.info
+@include version.texi
+@settitle The Libgcrypt Reference Manual
+@c Unify some of the indices.
+@syncodeindex tp fn
+@syncodeindex pg fn
+@c %**end of header
+@copying
+This manual is for Libgcrypt
+(version @value{VERSION}, @value{UPDATED}),
+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, 2016, 2017 g10 Code GmbH
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2 of the License, or (at your
+option) any later version. The text of the license can be found in the
+section entitled ``GNU General Public License''.
+@end quotation
+@end copying
+
+@dircategory GNU Libraries
+@direntry
+* libgcrypt: (gcrypt).  Cryptographic function library.
+@end direntry
+
+@c A couple of macros with no effect on texinfo
+@c but used by the yat2m processor.
+@macro manpage {a}
+@end macro
+@macro mansect {a}
+@end macro
+@macro manpause
+@end macro
+@macro mancont
+@end macro
+
+@c
+@c Printing stuff taken from gcc.
+@c
+@macro gnupgtabopt{body}
+@code{\body\}
+@end macro
+
+
+@c
+@c Titlepage
+@c
+@setchapternewpage odd
+@titlepage
+@title The Libgcrypt Reference Manual
+@subtitle Version @value{VERSION}
+@subtitle @value{UPDATED}
+@author Werner Koch (@email{wk@@gnupg.org})
+@author Moritz Schulte (@email{mo@@g10code.com})
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnothtml
+@summarycontents
+@contents
+@page
+@end ifnothtml
+
+
+@ifnottex
+@node Top
+@top The Libgcrypt Library
+@insertcopying
+@end ifnottex
+
+
+@menu
+* Introduction::                 What is Libgcrypt.
+* Preparation::                  What you should do before using the library.
+* Generalities::                 General library functions and data types.
+* Handler Functions::            Working with handler functions.
+* Symmetric cryptography::       How to use symmetric cryptography.
+* Public Key cryptography::      How to use public key cryptography.
+* Hashing::                      How to use hash algorithms.
+* Message Authentication Codes:: How to use MAC algorithms.
+* Key Derivation::               How to derive keys from strings
+* Random Numbers::               How to work with random numbers.
+* S-expressions::                How to manage S-expressions.
+* MPI library::                  How to work with multi-precision-integers.
+* Prime numbers::                How to use the Prime number related functions.
+* Utilities::                    Utility functions.
+* Tools::                        Utility tools.
+* Configuration::                Configuration files and environment variables.
+* Architecture::                 How Libgcrypt works internally.
+
+Appendices
+
+* 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
+                                can copy and share some parts of Libgcrypt.
+
+Indices
+
+* Figures and Tables::          Index of figures and tables.
+* Concept Index::               Index of concepts and programs.
+* Function and Data Index::     Index of functions, variables and data types.
+
+@end menu
+
+@ifhtml
+@page
+@summarycontents
+@contents
+@end ifhtml
+
+
+@c **********************************************************
+@c *******************  Introduction  ***********************
+@c **********************************************************
+@node Introduction
+@chapter Introduction
+
+Libgcrypt is a library providing cryptographic building blocks.
+
+@menu
+* Getting Started::             How to use this manual.
+* Features::                    A glance at Libgcrypt's features.
+* Overview::                    Overview about the library.
+@end menu
+
+@node Getting Started
+@section Getting Started
+
+This manual documents the Libgcrypt library application programming
+interface (API).  All functions and data types provided by the library
+are explained.
+
+@noindent
+The reader is assumed to possess basic knowledge about applied
+cryptography.
+
+This manual can be used in several ways.  If read from the beginning
+to the end, it gives a good introduction into the library and how it
+can be used in an application.  Forward references are included where
+necessary.  Later on, the manual can be used as a reference manual to
+get just the information needed about any particular interface of the
+library.  Experienced programmers might want to start looking at the
+examples at the end of the manual, and then only read up those parts
+of the interface which are unclear.
+
+
+@node Features
+@section Features
+
+Libgcrypt might have a couple of advantages over other libraries doing
+a similar job.
+
+@table @asis
+@item It's Free Software
+Anybody can use, modify, and redistribute it under the terms of the GNU
+Lesser General Public License (@pxref{Library Copying}).  Note, that
+some parts (which are in general not needed by applications) are subject
+to the terms of the GNU General Public License (@pxref{Copying}); please
+see the README file of the distribution for of list of these parts.
+
+@item It encapsulates the low level cryptography
+Libgcrypt provides a high level interface to cryptographic
+building blocks using an extensible and flexible API.
+
+@end table
+
+@node Overview
+@section Overview
+
+@noindent
+The Libgcrypt library is fully thread-safe, where it makes
+sense to be thread-safe.  Not thread-safe are some cryptographic
+functions that modify a certain context stored in handles.  If the
+user really intents to use such functions from different threads on
+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 some
+common code used by other GnuPG components.
+
+@c **********************************************************
+@c *******************  Preparation  ************************
+@c **********************************************************
+@node Preparation
+@chapter Preparation
+
+To use Libgcrypt, you have to perform some changes to your
+sources and the build system.  The necessary changes are small and
+explained in the following sections.  At the end of this chapter, it
+is described how the library is initialized, and how the requirements
+of the library are verified.
+
+@menu
+* Header::                      What header file you need to include.
+* Building sources::            How to build sources using the library.
+* Building sources using Automake::  How to build sources with the help of Automake.
+* Initializing the library::    How to initialize the library.
+* Multi-Threading::             How Libgcrypt can be used in a MT environment.
+* Enabling FIPS mode::          How to enable the FIPS mode.
+* Hardware features::           How to disable hardware features.
+@end menu
+
+
+@node Header
+@section Header
+
+All interfaces (data types and functions) of the library are defined
+in the header file @file{gcrypt.h}.  You must include this in all source
+files using the library, either directly or through some other header
+file, like this:
+
+@example
+#include <gcrypt.h>
+@end example
+
+The name space of Libgcrypt is @code{gcry_*} for function
+and type names and @code{GCRY*} for other symbols.  In addition the
+same name prefixes with one prepended underscore are reserved for
+internal use and should never be used by an application.  Note that
+Libgcrypt uses libgpg-error, which uses @code{gpg_*} as
+name space for function and type names and @code{GPG_*} for other
+symbols, including all the error codes.
+
+@noindent
+Certain parts of gcrypt.h may be excluded by defining these macros:
+
+@table @code
+@item GCRYPT_NO_MPI_MACROS
+Do not define the shorthand macros @code{mpi_*} for @code{gcry_mpi_*}.
+
+@item GCRYPT_NO_DEPRECATED
+Do not include definitions for deprecated features.  This is useful to
+make sure that no deprecated features are used.
+@end table
+
+@node Building sources
+@section Building sources
+
+If you want to compile a source file including the `gcrypt.h' header
+file, you must make sure that the compiler can find it in the
+directory hierarchy.  This is accomplished by adding the path to the
+directory in which the header file is located to the compilers include
+file search path (via the @option{-I} option).
+
+However, the path to the include file is determined at the time the
+source is configured.  To solve this problem, Libgcrypt ships with a small
+helper program @command{libgcrypt-config} that knows the path to the
+include file and other configuration options.  The options that need
+to be added to the compiler invocation at compile time are output by
+the @option{--cflags} option to @command{libgcrypt-config}.  The following
+example shows how it can be used at the command line:
+
+@example
+gcc -c foo.c `libgcrypt-config --cflags`
+@end example
+
+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,
+the path to the library files has to be added to the library search path
+(via the @option{-L} option).  For this, the option @option{--libs} to
+@command{libgcrypt-config} can be used.  For convenience, this option
+also outputs all other options that are required to link the program
+with the Libgcrypt libraries (in particular, the @samp{-lgcrypt}
+option).  The example shows how to link @file{foo.o} with the Libgcrypt
+library to a program @command{foo}.
+
+@example
+gcc -o foo foo.o `libgcrypt-config --libs`
+@end example
+
+Of course you can also combine both examples to a single command by
+specifying both options to @command{libgcrypt-config}:
+
+@example
+gcc -o foo foo.c `libgcrypt-config --cflags --libs`
+@end example
+
+@node Building sources using Automake
+@section Building sources using Automake
+
+It is much easier if you use GNU Automake instead of writing your own
+Makefiles.  If you do that, you do not have to worry about finding and
+invoking the @command{libgcrypt-config} script at all.
+Libgcrypt provides an extension to Automake that does all
+the work for you.
+
+@c A simple macro for optional variables.
+@macro ovar{varname}
+@r{[}@var{\varname\}@r{]}
+@end macro
+@defmac AM_PATH_LIBGCRYPT (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
+Check whether Libgcrypt (at least version
+@var{minimum-version}, if given) exists on the host system.  If it is
+found, execute @var{action-if-found}, otherwise do
+@var{action-if-not-found}, if given.
+
+Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the
+flags needed for compilation of the program to find the
+@file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker
+flags needed to link the program to the 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
+@file{Makefile.am}:
+
+@example
+AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
+LDADD = $(LIBGCRYPT_LIBS)
+@end example
+
+@node Initializing the library
+@section Initializing the library
+
+Before the library can be used, it must initialize itself.  This is
+achieved by invoking the function @code{gcry_check_version} described
+below.
+
+Also, it is often desirable to check that the version of
+Libgcrypt used is indeed one which fits all requirements.
+Even with binary compatibility, new features may have been introduced,
+but due to problem with the dynamic linker an old version may actually
+be used.  So you may want to check that the version is okay right
+after program startup.
+
+@deftypefun {const char *} gcry_check_version (const char *@var{req_version})
+
+The function @code{gcry_check_version} initializes some subsystems used
+by Libgcrypt and must be invoked before any other function in the
+library.
+@xref{Multi-Threading}.
+
+Furthermore, this function returns the version number of the library.
+It can also verify that the version number is higher than a certain
+required version number @var{req_version}, if this value is not a null
+pointer.
+@end deftypefun
+
+Libgcrypt uses a concept known as secure memory, which is a region of
+memory set aside for storing sensitive data.  Because such memory is a
+scarce resource, it needs to be setup in advanced to a fixed size.
+Further, most operating systems have special requirements on how that
+secure memory can be used.  For example, it might be required to install
+an application as ``setuid(root)'' to allow allocating such memory.
+Libgcrypt requires a sequence of initialization steps to make sure that
+this works correctly.  The following examples show the necessary steps.
+
+If you don't have a need for secure memory, for example if your
+application does not use secret keys or other confidential data or it
+runs in a controlled environment where key material floating around in
+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 initialized.
+     #define NEED_LIBGCRYPT_VERSION to the minimum required version. */
+  if (!gcry_check_version (NEED_LIBGCRYPT_VERSION))
+    @{
+      fprintf (stderr, "libgcrypt is too old (need %s, have %s)\n",
+         NEED_LIBGCRYPT_VERSION, gcry_check_version (NULL));
+      exit (2);
+    @}
+
+  /* Disable secure memory.  */
+  gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
+
+  /* ... If required, other initialization goes here.  */
+
+  /* Tell Libgcrypt that initialization has completed. */
+  gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
+@end example
+
+
+If you have to protect your keys or other information in memory against
+being swapped out to disk and to enable an automatic overwrite of used
+and freed memory, you need to initialize Libgcrypt this way:
+
+@example
+  /* Version check should be the very first call because it
+     makes sure that important subsystems are initialized.
+     #define NEED_LIBGCRYPT_VERSION to the minimum required version. */
+  if (!gcry_check_version (NEED_LIBGCRYPT_VERSION))
+    @{
+      fprintf (stderr, "libgcrypt is too old (need %s, have %s)\n",
+         NEED_LIBGCRYPT_VERSION, gcry_check_version (NULL));
+      exit (2);
+    @}
+
+@anchor{sample-use-suspend-secmem}
+  /* We don't want to see any warnings, e.g. because we have not yet
+     parsed program options which might be used to suppress such
+     warnings. */
+  gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
+
+  /* ... If required, other initialization goes here.  Note that the
+     process might still be running with increased privileges and that
+     the secure memory has not been initialized.  */
+
+  /* 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}
+  /* 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.  */
+
+  /* Tell Libgcrypt that initialization has completed. */
+  gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
+@end example
+
+It is important that these initialization steps are not done by a
+library but by the actual application.  A library using Libgcrypt might
+want to check for finished initialization using:
+
+@example
+  if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))
+    @{
+      fputs ("libgcrypt has not been initialized\n", stderr);
+      abort ();
+    @}
+@end example
+
+Instead of terminating the process, the library may instead print a
+warning and try to initialize Libgcrypt itself.  See also the section on
+multi-threading below for more pitfalls.
+
+
+
+@node Multi-Threading
+@section Multi-Threading
+
+As mentioned earlier, the Libgcrypt library is
+thread-safe if you adhere to the following requirements:
+
+@itemize @bullet
+@item
+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.
+
+
+@item
+The function @code{gcry_check_version} must be called before any other
+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
+@code{gcry_check_version} before creating the other threads using
+Libgcrypt@footnote{At least this is true for POSIX threads,
+as @code{pthread_create} is a function that synchronizes memory with
+respects to other threads.  There are many functions which have this
+property, a complete list can be found in POSIX, IEEE Std 1003.1-2003,
+Base Definitions, Issue 6, in the definition of the term ``Memory
+Synchronization''.  For other thread packages, more relaxed or more
+strict rules may apply.}.
+
+@item
+Just like the function @code{gpg_strerror}, the function
+@code{gcry_strerror} is not thread safe.  You have to use
+@code{gpg_strerror_r} instead.
+
+@end itemize
+
+
+@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
+versions of Libgcrypt are approved.
+
+Because FIPS 140 has certain restrictions on the use of cryptography
+which are not always wanted, Libgcrypt needs to be put into FIPS mode
+explicitly.  Three alternative mechanisms are provided to switch
+Libgcrypt into this mode:
+
+@itemize
+@item
+If the file @file{/proc/sys/crypto/fips_enabled} exists and contains a
+numeric value other than @code{0}, Libgcrypt is put into FIPS mode at
+initialization time.  Obviously this works only on systems with a
+@code{proc} file system (i.e. GNU/Linux).
+
+@item
+If the file @file{/etc/gcrypt/fips_enabled} exists, Libgcrypt is put
+into FIPS mode at initialization time.  Note that this filename is
+hardwired and does not depend on any configuration options.
+
+@item
+If the application requests FIPS mode using the control command
+@code{GCRYCTL_FORCE_FIPS_MODE}.  This must be done prior to any
+initialization (i.e. before @code{gcry_check_version}).
+
+@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} or by using the control command
+@code{GCRYCTL_SET_ENFORCED_FIPS_FLAG} before any other calls to
+libgcrypt.  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 self-tests are logged.
+
+@node Hardware features
+@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
+are
+
+@table @code
+@item padlock-rng
+@item padlock-aes
+@item padlock-sha
+@item padlock-mmul
+@item intel-cpu
+@item intel-fast-shld
+@item intel-bmi2
+@item intel-ssse3
+@item intel-pclmul
+@item intel-aesni
+@item intel-rdrand
+@item intel-avx
+@item intel-avx2
+@item intel-rdtsc
+@item arm-neon
+@end table
+
+To disable a feature for all processes using Libgcrypt 1.6 or newer,
+create the file @file{/etc/gcrypt/hwf.deny} and put each feature not
+to be used on a single line.  Empty lines, white space, and lines
+prefixed with a hash mark are ignored.  The file should be world
+readable.
+
+To disable a feature specifically for a program that program must tell
+it Libgcrypt before before calling @code{gcry_check_version}.
+Example:@footnote{NB. Libgcrypt uses the RDRAND feature only as one
+source of entropy.  A CPU with a broken RDRAND will thus not
+compromise of the random number generator}
+
+@example
+  gcry_control (GCRYCTL_DISABLE_HWF, "intel-rdrand", NULL);
+@end example
+
+@noindent
+To print the list of active features you may use this command:
+
+@example
+  mpicalc --print-config | grep ^hwflist: | tr : '\n' | tail -n +2
+@end example
+
+
+@c **********************************************************
+@c *******************  General  ****************************
+@c **********************************************************
+@node Generalities
+@chapter Generalities
+
+@menu
+* Controlling the library::     Controlling Libgcrypt's behavior.
+* Error Handling::              Error codes and such.
+@end menu
+
+@node Controlling the library
+@section Controlling the library
+
+@deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
+
+This function can be used to influence the general behavior of
+Libgcrypt in several ways.  Depending on @var{cmd}, more
+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 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
+(@code{GCRY_VERY_STRONG_RANDOM}) and degrades all request down to
+@code{GCRY_STRONG_RANDOM}.  In general this is not recommended.  However,
+for some applications the extra quality random Libgcrypt tries to create
+is not justified and this option may help to get better performance.
+Please check with a crypto expert whether this option can be used for
+your application.
+
+This option can only be used at initialization time.
+
+
+@item GCRYCTL_DUMP_RANDOM_STATS; Arguments: none
+This command dumps random number generator related statistics to the
+library's logging stream.
+
+@item GCRYCTL_DUMP_MEMORY_STATS; Arguments: none
+This command dumps memory management related statistics to the library's
+logging stream.
+
+@item GCRYCTL_DUMP_SECMEM_STATS; Arguments: none
+This command dumps secure memory management related statistics to the
+library's logging stream.
+
+@item GCRYCTL_DROP_PRIVS; Arguments: none
+This command disables the use of secure memory and drops the privileges
+of the current process.  This command has not much use; the suggested way
+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.  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.  This command should be executed right after
+@code{gcry_check_version}.
+
+@item GCRYCTL_DISABLE_LOCKED_SECMEM; Arguments: none
+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}.  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
+that it shall not drop privileges after secure memory has been
+allocated.  This command is commonly used right after
+@code{gcry_check_version} but may also be used right away at program
+startup.  It won't have an effect after the secure memory pool has
+been initialized.  WARNING: A process running setuid(root) is a severe
+security risk.  Processes making use of Libgcrypt or other complex
+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: 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
+@var{nbytes} is 0, secure memory will be disabled.  The minimum amount
+of secure memory allocated is currently 16384 bytes; you may thus use a
+value of 1 to request that default size.
+
+@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.
+If the secure memory pool as already been destroyed, this command has
+no effect.  Applications might want to run this command from their
+exit handler to make sure that the secure memory gets properly
+destroyed.  This command is not necessarily thread-safe but that
+should not be needed in cleanup code.  It may be called from a signal
+handler.
+
+@item GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none
+Disable warning messages about problems with the secure memory
+subsystem. This command should be run right after
+@code{gcry_check_version}.
+
+@item GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none
+Postpone warning messages from the secure memory subsystem.
+@xref{sample-use-suspend-secmem,,the initialization example}, on how to
+use it.
+
+@item GCRYCTL_RESUME_SECMEM_WARN; Arguments: none
+Resume warning messages from the secure memory subsystem.
+@xref{sample-use-resume-secmem,,the initialization example}, on how to
+use it.
+
+@item GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none
+This command tells the PRNG to store random numbers in secure memory.
+This command should be run right after @code{gcry_check_version} and not
+later than the command GCRYCTL_INIT_SECMEM.  Note that in FIPS mode the
+secure memory is always used.
+
+@item GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename
+This command specifies the file, which is to be used as seed file for
+the PRNG.  If the seed file is registered prior to initialization of the
+PRNG, the seed file's content (if it exists and seems to be valid) is
+fed into the PRNG pool.  After the seed file has been registered, the
+PRNG can be signalled to write out the PRNG pool's content into the seed
+file with the following command.
+
+
+@item GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none
+Write out the PRNG pool's content into the registered seed file.
+
+Multiple instances of the applications sharing the same random seed file
+can be started in parallel, in which case they will read out the same
+pool and then race for updating it (the last update overwrites earlier
+updates).  They will differentiate only by the weak entropy that is
+added in read_seed_file based on the PID and clock, and up to 16 bytes
+of weak random non-blockingly.  The consequence is that the output of
+these different instances is correlated to some extent.  In a perfect
+attack scenario, the attacker can control (or at least guess) the PID
+and clock of the application, and drain the system's entropy pool to
+reduce the "up to 16 bytes" above to 0.  Then the dependencies of the
+initial states of the pools are completely known.  Note that this is not
+an issue if random of @code{GCRY_VERY_STRONG_RANDOM} quality is
+requested as in this case enough extra entropy gets mixed.  It is also
+not an issue when using Linux (rndlinux driver), because this one
+guarantees to read full 16 bytes from /dev/urandom and thus there is no
+way for an attacker without kernel access to control these 16 bytes.
+
+@item GCRYCTL_CLOSE_RANDOM_DEVICE; Arguments: none
+Try to close the random device.  If on Unix system you call fork(),
+the child process does no call exec(), and you do not intend to use
+Libgcrypt in the child, it might be useful to use this control code to
+close the inherited file descriptors of the random device.  If
+Libgcrypt is later used again by the child, the device will be
+re-opened.  On non-Unix systems this control code is ignored.
+
+@item GCRYCTL_SET_VERBOSITY; Arguments: int level
+This command sets the verbosity of the logging.  A level of 0 disables
+all extra logging whereas positive numbers enable more verbose logging.
+The level may be changed at any time but be aware that no memory
+synchronization is done so the effect of this command might not
+immediately show up in other threads.  This command may even be used
+prior to @code{gcry_check_version}.
+
+@item GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags
+Set the debug flag bits as given by the argument.  Be aware that that no
+memory synchronization is done so the effect of this command might not
+immediately show up in other threads.  The debug flags are not
+considered part of the API and thus may change without notice.  As of
+now bit 0 enables debugging of cipher functions and bit 1 debugging of
+multi-precision-integers.  This command may even be used prior to
+@code{gcry_check_version}.
+
+@item GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags
+Set the debug flag bits as given by the argument.  Be aware that that no
+memory synchronization is done so the effect of this command might not
+immediately show up in other threads.  This command may even be used
+prior to @code{gcry_check_version}.
+
+@item GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none
+This command does nothing.  It exists only for backward compatibility.
+
+@item GCRYCTL_ANY_INITIALIZATION_P; Arguments: none
+This command returns true if the library has been basically initialized.
+Such a basic initialization happens implicitly with many commands to get
+certain internal subsystems running.  The common and suggested way to
+do this basic initialization is by calling gcry_check_version.
+
+@item GCRYCTL_INITIALIZATION_FINISHED; Arguments: none
+This command tells the library that the application has finished the
+initialization.
+
+@item GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none
+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 is obsolete since version 1.6.
+
+@item GCRYCTL_FAST_POLL; Arguments: none
+Run a fast random poll.
+
+@item GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename
+This command may be used to override the default name of the EGD socket
+to connect to.  It may be used only during initialization as it is not
+thread safe.  Changing the socket name again is not supported.  The
+function may return an error if the given filename is too long for a
+local socket name.
+
+EGD is an alternative random gatherer, used only on systems lacking a
+proper random device.
+
+@item GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream
+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}.  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.
+This information makes only sense in FIPS mode.  In contrast to other
+functions, this is a pure test function and won't put the library into
+FIPS mode or change the internal state.  This command may be used before
+the initialization has been finished but not before a @code{gcry_check_version}.
+
+@item GCRYCTL_FIPS_MODE_P; Arguments: none
+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 initialization has been finished but not
+before a @code{gcry_check_version}.  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 self-test is triggered and thus the library will
+be put into operational state.  This command may be used before a call
+to @code{gcry_check_version} and that is actually the recommended way to let an
+application switch the library into FIPS mode.  Note that Libgcrypt will
+reject an attempt to switch to fips mode during or after the initialization.
+
+@item GCRYCTL_SET_ENFORCED_FIPS_FLAG; Arguments: none
+Running this command sets the internal flag that puts the library into
+the enforced FIPS mode during the FIPS mode initialization.  This command
+does not affect the library if the library is not put into the FIPS mode and
+it must be used before any other libgcrypt library calls that initialize
+the library such as @code{gcry_check_version}. Note that Libgcrypt will
+reject an attempt to switch to the enforced fips mode during or after
+the initialization.
+
+@item GCRYCTL_SET_PREFERRED_RNG_TYPE; Arguments: int
+These are advisory commands to select a certain random number
+generator.  They are only advisory because libraries may not know what
+an application actually wants or vice versa.  Thus Libgcrypt employs a
+priority check to select the actually used RNG.  If an applications
+selects a lower priority RNG but a library requests a higher priority
+RNG Libgcrypt will switch to the higher priority RNG.  Applications
+and libraries should use these control codes before
+@code{gcry_check_version}.  The available generators are:
+@table @code
+@item GCRY_RNG_TYPE_STANDARD
+A conservative standard generator based on the ``Continuously Seeded
+Pseudo Random Number Generator'' designed by Peter Gutmann.
+@item GCRY_RNG_TYPE_FIPS
+A deterministic random number generator conforming to he document
+``NIST-Recommended Random Number Generator Based on ANSI X9.31
+Appendix A.2.4 Using the 3-Key Triple DES and AES Algorithms''
+(2005-01-31).  This implementation uses the AES variant.
+@item GCRY_RNG_TYPE_SYSTEM
+A wrapper around the system's native RNG.  On Unix system these are
+usually the /dev/random and /dev/urandom devices.
+@end table
+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_GET_CURRENT_RNG_TYPE; Arguments: int *
+This command stores the type of the currently used RNG as an integer
+value at the provided address.
+
+
+@item GCRYCTL_SELFTEST; Arguments: none
+This may be used at anytime to have the library run all implemented
+self-tests.  It works in standard and in FIPS mode.  Returns 0 on
+success or an error code on failure.
+
+@item GCRYCTL_DISABLE_HWF; Arguments: const char *name
+
+Libgcrypt detects certain features of the CPU at startup time.  For
+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.  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
+
+@end deftypefun
+
+@c **********************************************************
+@c *******************  Errors  ****************************
+@c **********************************************************
+@node Error Handling
+@section Error Handling
+
+Many functions in Libgcrypt can return an error if they
+fail.  For this reason, the application should always catch the error
+condition and take appropriate measures, for example by releasing the
+resources and passing the error up to the caller, or by displaying a
+descriptive message to the user and cancelling the operation.
+
+Some error values do not indicate a system error or an error in the
+operation, but the result of an operation that failed properly.  For
+example, if you try to decrypt a tempered message, the decryption will
+fail.  Another error value actually means that the end of a data
+buffer or list has been reached.  The following descriptions explain
+for many error codes what they mean usually.  Some error values have
+specific meanings if returned by a certain functions.  Such cases are
+described in the documentation of those functions.
+
+Libgcrypt uses the @code{libgpg-error} library.  This allows to share
+the error codes with other components of the GnuPG system, and to pass
+error values transparently from the crypto engine, or some helper
+application of the crypto engine, to the user.  This way no
+information is lost.  As a consequence, Libgcrypt does not use its own
+identifiers for error codes, but uses those provided by
+@code{libgpg-error}.  They usually start with @code{GPG_ERR_}.
+
+However, Libgcrypt does provide aliases for the functions
+defined in libgpg-error, which might be preferred for name space
+consistency.
+
+
+Most functions in Libgcrypt return an error code in the case
+of failure.  For this reason, the application should always catch the
+error condition and take appropriate measures, for example by
+releasing the resources and passing the error up to the caller, or by
+displaying a descriptive message to the user and canceling the
+operation.
+
+Some error values do not indicate a system error or an error in the
+operation, but the result of an operation that failed properly.
+
+GnuPG components, including Libgcrypt, use an extra library named
+libgpg-error to provide a common error handling scheme.  For more
+information on libgpg-error, see the according manual.
+
+@menu
+* Error Values::                The error value and what it means.
+* Error Sources::               A list of important error sources.
+* Error Codes::                 A list of important error codes.
+* Error Strings::               How to get a descriptive string from a value.
+@end menu
+
+
+@node Error Values
+@subsection Error Values
+@cindex error values
+@cindex error codes
+@cindex error sources
+
+@deftp {Data type} {gcry_err_code_t}
+The @code{gcry_err_code_t} type is an alias for the
+@code{libgpg-error} type @code{gpg_err_code_t}.  The error code
+indicates the type of an error, or the reason why an operation failed.
+
+A list of important error codes can be found in the next section.
+@end deftp
+
+@deftp {Data type} {gcry_err_source_t}
+The @code{gcry_err_source_t} type is an alias for the
+@code{libgpg-error} type @code{gpg_err_source_t}.  The error source
+has not a precisely defined meaning.  Sometimes it is the place where
+the error happened, sometimes it is the place where an error was
+encoded into an error value.  Usually the error source will give an
+indication to where to look for the problem.  This is not always true,
+but it is attempted to achieve this goal.
+
+A list of important error sources can be found in the next section.
+@end deftp
+
+@deftp {Data type} {gcry_error_t}
+The @code{gcry_error_t} type is an alias for the @code{libgpg-error}
+type @code{gpg_error_t}.  An error value like this has always two
+components, an error code and an error source.  Both together form the
+error value.
+
+Thus, the error value can not be directly compared against an error
+code, but the accessor functions described below must be used.
+However, it is guaranteed that only 0 is used to indicate success
+(@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
+the error value are set to 0, too.
+
+Note that in Libgcrypt, the error source is used purely for
+diagnostic purposes.  Only the error code should be checked to test
+for a certain outcome of a function.  The manual only documents the
+error code part of an error value.  The error source is left
+unspecified and might be anything.
+@end deftp
+
+@deftypefun {gcry_err_code_t} gcry_err_code (@w{gcry_error_t @var{err}})
+The static inline function @code{gcry_err_code} returns the
+@code{gcry_err_code_t} component of the error value @var{err}.  This
+function must be used to extract the error code from an error value in
+order to compare it with the @code{GPG_ERR_*} error code macros.
+@end deftypefun
+
+@deftypefun {gcry_err_source_t} gcry_err_source (@w{gcry_error_t @var{err}})
+The static inline function @code{gcry_err_source} returns the
+@code{gcry_err_source_t} component of the error value @var{err}.  This
+function must be used to extract the error source from an error value in
+order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
+@end deftypefun
+
+@deftypefun {gcry_error_t} gcry_err_make (@w{gcry_err_source_t @var{source}}, @w{gcry_err_code_t @var{code}})
+The static inline function @code{gcry_err_make} returns the error
+value consisting of the error source @var{source} and the error code
+@var{code}.
+
+This function can be used in callback functions to construct an error
+value to return it to the library.
+@end deftypefun
+
+@deftypefun {gcry_error_t} gcry_error (@w{gcry_err_code_t @var{code}})
+The static inline function @code{gcry_error} returns the error value
+consisting of the default error source and the error code @var{code}.
+
+For @acronym{GCRY} applications, the default error source is
+@code{GPG_ERR_SOURCE_USER_1}.  You can define
+@code{GCRY_ERR_SOURCE_DEFAULT} before including @file{gcrypt.h} to
+change this default.
+
+This function can be used in callback functions to construct an error
+value to return it to the library.
+@end deftypefun
+
+The @code{libgpg-error} library provides error codes for all system
+error numbers it knows about.  If @var{err} is an unknown error
+number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used.  The
+following functions can be used to construct error values from system
+errno numbers.
+
+@deftypefun {gcry_error_t} gcry_err_make_from_errno (@w{gcry_err_source_t @var{source}}, @w{int @var{err}})
+The function @code{gcry_err_make_from_errno} is like
+@code{gcry_err_make}, but it takes a system error like @code{errno}
+instead of a @code{gcry_err_code_t} error code.
+@end deftypefun
+
+@deftypefun {gcry_error_t} gcry_error_from_errno (@w{int @var{err}})
+The function @code{gcry_error_from_errno} is like @code{gcry_error},
+but it takes a system error like @code{errno} instead of a
+@code{gcry_err_code_t} error code.
+@end deftypefun
+
+Sometimes you might want to map system error numbers to error codes
+directly, or map an error code representing a system error back to the
+system error number.  The following functions can be used to do that.
+
+@deftypefun {gcry_err_code_t} gcry_err_code_from_errno (@w{int @var{err}})
+The function @code{gcry_err_code_from_errno} returns the error code
+for the system error @var{err}.  If @var{err} is not a known system
+error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
+@end deftypefun
+
+@deftypefun {int} gcry_err_code_to_errno (@w{gcry_err_code_t @var{err}})
+The function @code{gcry_err_code_to_errno} returns the system error
+for the error code @var{err}.  If @var{err} is not an error code
+representing a system error, or if this system error is not defined on
+this system, the function returns @code{0}.
+@end deftypefun
+
+
+@node Error Sources
+@subsection Error Sources
+@cindex error codes, list of
+
+The library @code{libgpg-error} defines an error source for every
+component of the GnuPG system.  The error source part of an error
+value is not well defined.  As such it is mainly useful to improve the
+diagnostic error message for the user.
+
+If the error code part of an error value is @code{0}, the whole error
+value will be @code{0}.  In this case the error source part is of
+course @code{GPG_ERR_SOURCE_UNKNOWN}.
+
+The list of error sources that might occur in applications using
+@acronym{Libgcrypt} is:
+
+@table @code
+@item GPG_ERR_SOURCE_UNKNOWN
+The error source is not known.  The value of this error source is
+@code{0}.
+
+@item GPG_ERR_SOURCE_GPGME
+The error source is @acronym{GPGME} itself.
+
+@item GPG_ERR_SOURCE_GPG
+The error source is GnuPG, which is the crypto engine used for the
+OpenPGP protocol.
+
+@item GPG_ERR_SOURCE_GPGSM
+The error source is GPGSM, which is the crypto engine used for the
+OpenPGP protocol.
+
+@item GPG_ERR_SOURCE_GCRYPT
+The error source is @code{libgcrypt}, which is used by crypto engines
+to perform cryptographic operations.
+
+@item GPG_ERR_SOURCE_GPGAGENT
+The error source is @command{gpg-agent}, which is used by crypto
+engines to perform operations with the secret key.
+
+@item GPG_ERR_SOURCE_PINENTRY
+The error source is @command{pinentry}, which is used by
+@command{gpg-agent} to query the passphrase to unlock a secret key.
+
+@item GPG_ERR_SOURCE_SCD
+The error source is the SmartCard Daemon, which is used by
+@command{gpg-agent} to delegate operations with the secret key to a
+SmartCard.
+
+@item GPG_ERR_SOURCE_KEYBOX
+The error source is @code{libkbx}, a library used by the crypto
+engines to manage local keyrings.
+
+@item GPG_ERR_SOURCE_USER_1
+@item GPG_ERR_SOURCE_USER_2
+@item GPG_ERR_SOURCE_USER_3
+@item GPG_ERR_SOURCE_USER_4
+These error sources are not used by any GnuPG component and can be
+used by other software.  For example, applications using
+Libgcrypt can use them to mark error values coming from callback
+handlers.  Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
+created with @code{gcry_error} and @code{gcry_error_from_errno},
+unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including
+@file{gcrypt.h}.
+@end table
+
+
+@node Error Codes
+@subsection Error Codes
+@cindex error codes, list of
+
+The library @code{libgpg-error} defines many error values.  The
+following list includes the most important error codes.
+
+@table @code
+@item GPG_ERR_EOF
+This value indicates the end of a list, buffer or file.
+
+@item GPG_ERR_NO_ERROR
+This value indicates success.  The value of this error code is
+@code{0}.  Also, it is guaranteed that an error value made from the
+error code @code{0} will be @code{0} itself (as a whole).  This means
+that the error source information is lost for this error code,
+however, as this error code indicates that no error occurred, this is
+generally not a problem.
+
+@item GPG_ERR_GENERAL
+This value means that something went wrong, but either there is not
+enough information about the problem to return a more useful error
+value, or there is no separate error value for this type of problem.
+
+@item GPG_ERR_ENOMEM
+This value means that an out-of-memory condition occurred.
+
+@item GPG_ERR_E...
+System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for
+the system error.
+
+@item GPG_ERR_INV_VALUE
+This value means that some user provided data was out of range.
+
+@item GPG_ERR_UNUSABLE_PUBKEY
+This value means that some recipients for a message were invalid.
+
+@item GPG_ERR_UNUSABLE_SECKEY
+This value means that some signers were invalid.
+
+@item GPG_ERR_NO_DATA
+This value means that data was expected where no data was found.
+
+@item GPG_ERR_CONFLICT
+This value means that a conflict of some sort occurred.
+
+@item GPG_ERR_NOT_IMPLEMENTED
+This value indicates that the specific function (or operation) is not
+implemented.  This error should never happen.  It can only occur if
+you use certain values or configuration options which do not work,
+but for which we think that they should work at some later time.
+
+@item GPG_ERR_DECRYPT_FAILED
+This value indicates that a decryption operation was unsuccessful.
+
+@item GPG_ERR_WRONG_KEY_USAGE
+This value indicates that a key is not used appropriately.
+
+@item GPG_ERR_NO_SECKEY
+This value indicates that no secret key for the user ID is available.
+
+@item GPG_ERR_UNSUPPORTED_ALGORITHM
+This value means a verification failed because the cryptographic
+algorithm is not supported by the crypto backend.
+
+@item GPG_ERR_BAD_SIGNATURE
+This value means a verification failed because the signature is bad.
+
+@item GPG_ERR_NO_PUBKEY
+This value means a verification failed because the public key is not
+available.
+
+@item GPG_ERR_NOT_OPERATIONAL
+This value means that the library is not yet in state which allows to
+use this function.  This error code is in particular returned if
+Libgcrypt is operated in FIPS mode and the internal state of the
+library does not yet or not anymore allow the use of a service.
+
+This error code is only available with newer libgpg-error versions, thus
+you might see ``invalid error code'' when passing this to
+@code{gpg_strerror}.  The numeric value of this error code is 176.
+
+@item GPG_ERR_USER_1
+@item GPG_ERR_USER_2
+@item ...
+@item GPG_ERR_USER_16
+These error codes are not used by any GnuPG component and can be
+freely used by other software.  Applications using Libgcrypt
+might use them to mark specific errors returned by callback handlers
+if no suitable error codes (including the system errors) for these
+errors exist already.
+@end table
+
+
+@node Error Strings
+@subsection Error Strings
+@cindex error values, printing of
+@cindex error codes, printing of
+@cindex error sources, printing of
+@cindex error strings
+
+@deftypefun {const char *} gcry_strerror (@w{gcry_error_t @var{err}})
+The function @code{gcry_strerror} returns a pointer to a statically
+allocated string containing a description of the error code contained
+in the error value @var{err}.  This string can be used to output a
+diagnostic message to the user.
+@end deftypefun
+
+
+@deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}})
+The function @code{gcry_strsource} returns a pointer to a statically
+allocated string containing a description of the error source
+contained in the error value @var{err}.  This string can be used to
+output a diagnostic message to the user.
+@end deftypefun
+
+The following example illustrates the use of the functions described
+above:
+
+@example
+@{
+  gcry_cipher_hd_t handle;
+  gcry_error_t err = 0;
+
+  err = gcry_cipher_open (&handle, GCRY_CIPHER_AES,
+                          GCRY_CIPHER_MODE_CBC, 0);
+  if (err)
+    @{
+      fprintf (stderr, "Failure: %s/%s\n",
+               gcry_strsource (err),
+               gcry_strerror (err));
+    @}
+@}
+@end example
+
+@c **********************************************************
+@c *******************  General  ****************************
+@c **********************************************************
+@node Handler Functions
+@chapter Handler Functions
+
+Libgcrypt makes it possible to install so called `handler functions',
+which get called by Libgcrypt in case of certain events.
+
+@menu
+* Progress handler::            Using a progress handler function.
+* Allocation handler::          Using special memory allocation functions.
+* Error handler::               Using error handler functions.
+* Logging handler::             Using a special logging function.
+@end menu
+
+@node Progress handler
+@section Progress handler
+
+It is often useful to retrieve some feedback while long running
+operations are performed.
+
+@deftp {Data type} gcry_handler_progress_t
+Progress handler functions have to be of the type
+@code{gcry_handler_progress_t}, which is defined as:
+
+@code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)}
+@end deftp
+
+The following function may be used to register a handler function for
+this purpose.
+
+@deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data})
+
+This function installs @var{cb} as the `Progress handler' function.
+It may be used only during initialization.  @var{cb} must be defined
+as follows:
+
+@example
+void
+my_progress_handler (void *@var{cb_data}, const char *@var{what},
+                     int @var{printchar}, int @var{current}, int @var{total})
+@{
+  /* Do something.  */
+@}
+@end example
+
+A description of the arguments of the progress handler function follows.
+
+@table @var
+@item cb_data
+The argument provided in the call to @code{gcry_set_progress_handler}.
+@item what
+A string identifying the type of the progress output.  The following
+values for @var{what} are defined:
+
+@table @code
+@item need_entropy
+Not enough entropy is available.  @var{total} holds the number of
+required bytes.
+
+@item wait_dev_random
+Waiting to re-open a random device.  @var{total} gives the number of
+seconds until the next try.
+
+@item primegen
+Values for @var{printchar}:
+@table @code
+@item \n
+Prime generated.
+@item !
+Need to refresh the pool of prime numbers.
+@item <, >
+Number of bits adjusted.
+@item ^
+Searching for a generator.
+@item .
+Fermat test on 10 candidates failed.
+@item :
+Restart with a new random value.
+@item +
+Rabin Miller test passed.
+@end table
+
+@end table
+
+@end table
+@end deftypefun
+
+@node Allocation handler
+@section Allocation handler
+
+It is possible to make Libgcrypt use special memory
+allocation functions instead of the built-in ones.
+
+Memory allocation functions are of the following types:
+@deftp {Data type} gcry_handler_alloc_t
+This type is defined as: @code{void *(*gcry_handler_alloc_t) (size_t n)}.
+@end deftp
+@deftp {Data type} gcry_handler_secure_check_t
+This type is defined as: @code{int *(*gcry_handler_secure_check_t) (const void *)}.
+@end deftp
+@deftp {Data type} gcry_handler_realloc_t
+This type is defined as: @code{void *(*gcry_handler_realloc_t) (void *p, size_t n)}.
+@end deftp
+@deftp {Data type} gcry_handler_free_t
+This type is defined as: @code{void *(*gcry_handler_free_t) (void *)}.
+@end deftp
+
+Special memory allocation functions can be installed with the
+following function:
+
+@deftypefun void gcry_set_allocation_handler (gcry_handler_alloc_t @var{func_alloc}, gcry_handler_alloc_t @var{func_alloc_secure}, gcry_handler_secure_check_t @var{func_secure_check}, gcry_handler_realloc_t @var{func_realloc}, gcry_handler_free_t @var{func_free})
+Install the provided functions and use them instead of the built-in
+functions for doing memory allocation.  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
+@section Error handler
+
+The following functions may be used to register handler functions that
+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{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.  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
+This type is defined as: @code{void (*gcry_handler_error_t) (void *, int, const char *)}
+@end deftp
+
+@deftypefun void gcry_set_fatalerror_handler (gcry_handler_error_t @var{func_error}, void *@var{cb_data})
+This function registers @var{func_error} as `error handler',
+which means that it will be called in error conditions.
+@end deftypefun
+
+@node Logging handler
+@section Logging handler
+
+@deftp {Data type} gcry_handler_log_t
+This type is defined as: @code{void (*gcry_handler_log_t) (void *, int, const char *, va_list)}
+@end deftp
+
+@deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})
+This function registers @var{func_log} as `logging handler', which means
+that it will be called in case Libgcrypt wants to log a message.  This
+function may and should be used prior to calling
+@code{gcry_check_version}.
+@end deftypefun
+
+@c **********************************************************
+@c *******************  Ciphers  ****************************
+@c **********************************************************
+@c @include cipher-ref.texi
+@node Symmetric cryptography
+@chapter Symmetric cryptography
+
+The cipher functions are used for symmetrical cryptography,
+i.e. cryptography using a shared key.  The programming model follows
+an open/process/close paradigm and is in that similar to other
+building blocks provided by Libgcrypt.
+
+@menu
+* Available ciphers::           List of ciphers supported by the library.
+* Available cipher modes::      List of cipher modes supported by the library.
+* Working with cipher handles::  How to perform operations related to cipher handles.
+* General cipher functions::    General cipher functions independent of cipher handles.
+@end menu
+
+@node Available ciphers
+@section Available ciphers
+
+@table @code
+@item GCRY_CIPHER_NONE
+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.
+
+@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.
+
+@item GCRY_CIPHER_SAFER_SK128
+Reserved and not currently implemented.
+
+@item GCRY_CIPHER_DES_SK
+Reserved and not currently implemented.
+
+@item  GCRY_CIPHER_AES
+@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
+@itemx GCRY_CIPHER_RIJNDAEL192
+AES (Rijndael) with a 192 bit key.
+
+@item  GCRY_CIPHER_AES256
+@itemx GCRY_CIPHER_RIJNDAEL256
+AES (Rijndael) with a 256 bit key.
+
+@item  GCRY_CIPHER_TWOFISH
+@cindex Twofish
+The Twofish algorithm with a 256 bit key.
+
+@item  GCRY_CIPHER_TWOFISH128
+The Twofish algorithm with a 128 bit key.
+
+@item  GCRY_CIPHER_ARCFOUR
+@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
+@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.
+
+@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.
+
+@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}.
+
+@item GCRY_CIPHER_SALSA20
+@cindex Salsa20
+This is the Salsa20 stream cipher.
+
+@item GCRY_CIPHER_SALSA20R12
+@cindex Salsa20/12
+This is the Salsa20/12 - reduced round version of Salsa20 stream cipher.
+
+@item GCRY_CIPHER_GOST28147
+@cindex GOST 28147-89
+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
+@section Available cipher modes
+
+@table @code
+@item GCRY_CIPHER_MODE_NONE
+No mode specified.  This should not be used.  The only exception is that
+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
+@item GCRY_CIPHER_MODE_CFB8
+@cindex CFB, Cipher Feedback mode
+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
+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.
+
+@item  GCRY_CIPHER_MODE_CCM
+@cindex CCM, Counter with CBC-MAC mode
+Counter with CBC-MAC mode is an Authenticated Encryption with
+Associated Data (AEAD) block cipher mode, which is specified in
+'NIST Special Publication 800-38C' and RFC 3610.
+
+@item  GCRY_CIPHER_MODE_GCM
+@cindex GCM, Galois/Counter Mode
+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.
+
+@end table
+
+@node Working with cipher handles
+@section Working with cipher handles
+
+To use a cipher algorithm, you must first allocate an according
+handle.  This is to be done using the open function:
+
+@deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd}, int @var{algo}, int @var{mode}, unsigned int @var{flags})
+
+This function creates the context handle required for most of the
+other cipher functions and returns a handle to it in `hd'.  In case of
+an error, an according error code is returned.
+
+The ID of algorithm to use must be specified via @var{algo}.  See
+@ref{Available ciphers}, for a list of supported ciphers and the
+according constants.
+
+Besides using the constants directly, the function
+@code{gcry_cipher_map_name} may be used to convert the textual name of
+an algorithm into the according numeric ID.
+
+The cipher mode to use must be specified via @var{mode}.  See
+@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.
+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} and
+@code{GCRY_CIPHER_MODE_CTR}) 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.
+
+@table @code
+@item GCRY_CIPHER_SECURE
+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.
+@end table
+@end deftypefun
+
+Use the following function to release an existing handle:
+
+@deftypefun void gcry_cipher_close (gcry_cipher_hd_t @var{h})
+
+This function releases the context created by @code{gcry_cipher_open}.
+It also zeroises all sensitive information associated with this cipher
+handle.
+@end deftypefun
+
+In order to use a handle for performing cryptographic operations, a
+`key' has to be set first:
+
+@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} (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
+
+Most crypto modes requires an initialization vector (IV), which
+usually is a non-secret random string acting as a kind of salt value.
+The CTR mode requires a counter, which is also similar to a salt
+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} 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 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
+
+@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} 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).
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
+
+Set the given handle's context back to the state it had after the last
+call to gcry_cipher_setkey and clear the initialization vector.
+
+Note that gcry_cipher_reset is implemented as a macro.
+@end deftypefun
+
+Authenticated Encryption with Associated Data (AEAD) block cipher
+modes require the handling of the authentication tag and the additional
+authenticated data, which can be done by using the following
+functions:
+
+@deftypefun gcry_error_t gcry_cipher_authenticate (gcry_cipher_hd_t @var{h}, const void *@var{abuf}, size_t @var{abuflen})
+
+Process the buffer @var{abuf} of length @var{abuflen} as the additional
+authenticated data (AAD) for AEAD cipher modes.
+
+@end deftypefun
+
+@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 @
+            (@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
+and compared to internal authentication tag computed during
+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
+following functions.  They may be used as often as required to process
+all the data.
+
+@deftypefun gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
+
+@code{gcry_cipher_encrypt} is used to encrypt the data.  This function
+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} 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
+allocated size of @var{out}, so that the function can check that there
+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
+
+
+@deftypefun gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
+
+@code{gcry_cipher_decrypt} is used to decrypt the data.  This function
+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 decryption of the data in @var{out} or
+length @var{outsize} takes place.  With @var{in} being not @code{NULL},
+@var{inlen} bytes are decrypted to the buffer @var{out} which must have
+at least a size of @var{inlen}.  @var{outsize} must be set to the
+allocated size of @var{out}, so that the function can check that there
+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
+
+
+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})
+
+Perform the OpenPGP sync operation on context @var{h}.  Note that this
+is a no-op unless the context was created with the flag
+@code{GCRY_CIPHER_ENABLE_SYNC}
+@end deftypefun
+
+Some of the described functions are implemented as macros utilizing a
+catch-all control function.  This control function is rarely used
+directly but there is nothing which would inhibit it:
+
+@deftypefun gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
+
+@code{gcry_cipher_ctl} controls various aspects of the cipher module and
+specific cipher contexts.  Usually some more specialized functions or
+macros are used for this purpose.  The semantics of the function and its
+parameters depends on the the command @var{cmd} and the passed context
+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})
+
+@code{gcry_cipher_info} is used to retrieve various
+information about a cipher context or the cipher module in general.
+
+@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
+@section General cipher functions
+
+To work with the algorithms, several functions are available to map
+algorithm names to the internal identifiers, as well as ways to
+retrieve information about an algorithm or the current cipher context.
+
+@deftypefun gcry_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
+
+This function is used to retrieve information on a specific algorithm.
+You pass the cipher algorithm ID as @var{algo} and the type of
+information requested as @var{what}. The result is either returned as
+the return code of the function or copied to the provided @var{buffer}
+whose allocated length must be available in an integer variable with the
+address passed in @var{nbytes}.  This variable will also receive the
+actual used length of the buffer.
+
+Here is a list of supported codes for @var{what}:
+
+@c begin constants for gcry_cipher_algo_info
+@table @code
+@item GCRYCTL_GET_KEYLEN:
+Return the length of the key. If the algorithm supports multiple key
+lengths, the maximum supported value is returned.  The length is
+returned as number of octets (bytes) and not as number of bits in
+@var{nbytes}; @var{buffer} must be zero.  Note that it is usually
+better to use the convenience function
+@code{gcry_cipher_get_algo_keylen}.
+
+@item GCRYCTL_GET_BLKLEN:
+Return the block length of the algorithm.  The length is returned as a
+number of octets in @var{nbytes}; @var{buffer} must be zero.  Note
+that it is usually better to use the convenience function
+@code{gcry_cipher_get_algo_blklen}.
+
+@item GCRYCTL_TEST_ALGO:
+Returns @code{0} when the specified algorithm is available for use.
+@var{buffer} and @var{nbytes} must be zero.
+
+@end table
+@c end constants for gcry_cipher_algo_info
+
+@end deftypefun
+@c end gcry_cipher_algo_info
+
+@deftypefun size_t gcry_cipher_get_algo_keylen (@var{algo})
+
+This function returns length of the key for algorithm @var{algo}.  If
+the algorithm supports multiple key lengths, the maximum supported key
+length is returned.  On error @code{0} is returned.  The key length is
+returned as number of octets.
+
+This is a convenience functions which should be preferred over
+@code{gcry_cipher_algo_info} because it allows for proper type
+checking.
+@end deftypefun
+@c end gcry_cipher_get_algo_keylen
+
+@deftypefun size_t gcry_cipher_get_algo_blklen (int @var{algo})
+
+This functions returns the block-length of the algorithm @var{algo}
+counted in octets.  On error @code{0} is returned.
+
+This is a convenience functions which should be preferred over
+@code{gcry_cipher_algo_info} because it allows for proper type
+checking.
+@end deftypefun
+@c end gcry_cipher_get_algo_blklen
+
+
+@deftypefun {const char *} gcry_cipher_algo_name (int @var{algo})
+
+@code{gcry_cipher_algo_name} returns a string with the name of the
+cipher algorithm @var{algo}.  If the algorithm is not known or another
+error occurred, the string @code{"?"} is returned.  This function should
+not be used to test for the availability of an algorithm.
+@end deftypefun
+
+@deftypefun int gcry_cipher_map_name (const char *@var{name})
+
+@code{gcry_cipher_map_name} returns the algorithm identifier for the
+cipher algorithm described by the string @var{name}.  If this algorithm
+is not available @code{0} is returned.
+@end deftypefun
+
+@deftypefun int gcry_cipher_mode_from_oid (const char *@var{string})
+
+Return the cipher mode associated with an @acronym{ASN.1} object
+identifier.  The object identifier is expected to be in the
+@acronym{IETF}-style dotted decimal notation.  The function returns
+@code{0} for an unknown object identifier or when no mode is associated
+with it.
+@end deftypefun
+
+
+@c **********************************************************
+@c *******************  Public Key  *************************
+@c **********************************************************
+@node Public Key cryptography
+@chapter Public Key cryptography
+
+Public key cryptography, also known as asymmetric cryptography, is an
+easy way for key management and to provide digital signatures.
+Libgcrypt provides two completely different interfaces to
+public key cryptography, this chapter explains the one based on
+S-expressions.
+
+@menu
+* Available algorithms::        Algorithms supported by the library.
+* Used S-expressions::          Introduction into the used S-expression.
+* Cryptographic Functions::     Functions for performing the cryptographic actions.
+* General public-key related Functions::  General functions, not implementing any cryptography.
+@end menu
+
+@node Available algorithms
+@section Available algorithms
+
+Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well
+as DSA (Digital Signature Algorithm) and Elgamal.  The versatile
+interface allows to add more algorithms in the future.
+
+@node Used S-expressions
+@section Used S-expressions
+
+Libgcrypt's API for asymmetric cryptography is based on data structures
+called S-expressions (see
+@uref{http://people.csail.mit.edu/@/rivest/@/sexp.html}) and does not work
+with contexts as most of the other building blocks of Libgcrypt do.
+
+@noindent
+The following information are stored in S-expressions:
+
+@itemize
+@item keys
+
+@item plain text data
+
+@item encrypted data
+
+@item signatures
+
+@end itemize
+
+@noindent
+To describe how Libgcrypt expect keys, we use examples. Note that
+words in
+@ifnottex
+uppercase
+@end ifnottex
+@iftex
+italics
+@end iftex
+indicate parameters whereas lowercase words are literals.
+
+Note that all MPI (multi-precision-integers) values are expected to be in
+@code{GCRYMPI_FMT_USG} format.  An easy way to create S-expressions is
+by using @code{gcry_sexp_build} which allows to pass a string with
+printf-like escapes to insert MPI values.
+
+@menu
+* RSA key parameters::  Parameters used with an RSA key.
+* DSA key parameters::  Parameters used with a DSA key.
+* ECC key parameters::  Parameters used with ECC keys.
+@end menu
+
+@node RSA key parameters
+@subsection RSA key parameters
+
+@noindent
+An RSA private key is described by this S-expression:
+
+@example
+(private-key
+  (rsa
+    (n @var{n-mpi})
+    (e @var{e-mpi})
+    (d @var{d-mpi})
+    (p @var{p-mpi})
+    (q @var{q-mpi})
+    (u @var{u-mpi})))
+@end example
+
+@noindent
+An RSA public key is described by this S-expression:
+
+@example
+(public-key
+  (rsa
+    (n @var{n-mpi})
+    (e @var{e-mpi})))
+@end example
+
+
+@table @var
+@item n-mpi
+RSA public modulus @math{n}.
+@item e-mpi
+RSA public exponent @math{e}.
+@item d-mpi
+RSA secret exponent @math{d = e^{-1} \bmod (p-1)(q-1)}.
+@item p-mpi
+RSA secret prime @math{p}.
+@item q-mpi
+RSA secret prime @math{q} with @math{p < q}.
+@item u-mpi
+Multiplicative inverse @math{u = p^{-1} \bmod q}.
+@end table
+
+For signing and decryption the parameters @math{(p, q, u)} are optional
+but greatly improve the performance.  Either all of these optional
+parameters must be given or none of them.  They are mandatory for
+gcry_pk_testkey.
+
+Note that OpenSSL uses slighly different parameters: @math{q < p} and
+ @math{u = q^{-1} \bmod p}.  To use these parameters you will need to
+swap the values and recompute @math{u}.  Here is example code to do this:
+
+@example
+  if (gcry_mpi_cmp (p, q) > 0)
+    @{
+      gcry_mpi_swap (p, q);
+      gcry_mpi_invm (u, p, q);
+    @}
+@end example
+
+
+
+
+@node DSA key parameters
+@subsection DSA key parameters
+
+@noindent
+A DSA private key is described by this S-expression:
+
+@example
+(private-key
+  (dsa
+    (p @var{p-mpi})
+    (q @var{q-mpi})
+    (g @var{g-mpi})
+    (y @var{y-mpi})
+    (x @var{x-mpi})))
+@end example
+
+@table @var
+@item p-mpi
+DSA prime @math{p}.
+@item q-mpi
+DSA group order @math{q} (which is a prime divisor of @math{p-1}).
+@item g-mpi
+DSA group generator @math{g}.
+@item y-mpi
+DSA public key value @math{y = g^x \bmod p}.
+@item x-mpi
+DSA secret exponent x.
+@end table
+
+The public key is similar with "private-key" replaced by "public-key"
+and no @var{x-mpi}.
+
+
+@node ECC key parameters
+@subsection ECC key parameters
+
+@anchor{ecc_keyparam}
+@noindent
+An ECC private key is described by this S-expression:
+
+@example
+(private-key
+  (ecc
+    (p @var{p-mpi})
+    (a @var{a-mpi})
+    (b @var{b-mpi})
+    (g @var{g-point})
+    (n @var{n-mpi})
+    (q @var{q-point})
+    (d @var{d-mpi})))
+@end example
+
+@table @var
+@item p-mpi
+Prime specifying the field @math{GF(p)}.
+@item a-mpi
+@itemx b-mpi
+The two coefficients of the Weierstrass equation @math{y^2 = x^3 + ax + b}
+@item g-point
+Base point @math{g}.
+@item n-mpi
+Order of @math{g}
+@item q-point
+The point representing the public key @math{Q = dG}.
+@item d-mpi
+The private key @math{d}
+@end table
+
+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; 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}.
+
+If the domain parameters are well-known, the name of this curve may be
+used.  For example
+
+@example
+(private-key
+  (ecc
+    (curve "NIST P-192")
+    (q @var{q-point})
+    (d @var{d-mpi})))
+@end example
+
+Note that @var{q-point} is optional for a private key.  The
+@code{curve} parameter may be given in any case and is used to replace
+missing parameters.
+
+@noindent
+Currently implemented curves are:
+@table @code
+@item NIST P-192
+@itemx 1.2.840.10045.3.1.1
+@itemx prime192v1
+@itemx secp192r1
+The NIST 192 bit curve, its OID, X9.62 and SECP aliases.
+
+@item NIST P-224
+@itemx secp224r1
+The NIST 224 bit curve and its SECP alias.
+
+@item NIST P-256
+@itemx 1.2.840.10045.3.1.7
+@itemx prime256v1
+@itemx secp256r1
+The NIST 256 bit curve, its OID, X9.62 and SECP aliases.
+
+@item NIST P-384
+@itemx secp384r1
+The NIST 384 bit curve and its SECP alias.
+
+@item NIST P-521
+@itemx secp521r1
+The NIST 521 bit curve and its SECP alias.
+
+@end table
+As usual the OIDs may optionally be prefixed with the string @code{OID.}
+or @code{oid.}.
+
+
+@node Cryptographic Functions
+@section Cryptographic Functions
+
+@noindent
+Some functions operating on S-expressions support `flags' to influence
+the operation.  These flags have to be listed in a sub-S-expression
+named `flags'.  Flag names are case-sensitive.  The following flags
+are known:
+
+@table @code
+
+@item comp
+@itemx nocomp
+@cindex comp
+@cindex nocomp
+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.  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
+Use PKCS#1 block type 2 padding for encryption, block type 1 padding
+for signing.
+
+@item oaep
+@cindex OAEP
+Use RSA-OAEP padding for encryption.
+
+@item pss
+@cindex PSS
+Use RSA-PSS padding for signing.
+
+@item eddsa
+@cindex EdDSA
+Use the EdDSA scheme signing instead of the default ECDSA algorithm.
+Note that the EdDSA uses a special form of the public key.
+
+@item rfc6979
+@cindex RFC6979
+For DSA and ECDSA use a deterministic scheme for the k parameter.
+
+@item no-blinding
+@cindex no-blinding
+Do not use a technique called `blinding', which is used by default in
+order to prevent leaking of secret information.  Blinding is only
+implemented by RSA, but it might be implemented by other algorithms in
+the future as well, when necessary.
+
+@item param
+@cindex param
+For ECC key generation also return the domain parameters.  For ECC
+signing and verification override default parameters by provided
+domain parameters of the public or private key.
+
+@item transient-key
+@cindex transient-key
+This flag is only meaningful for RSA, DSA, and ECC key generation.  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 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
+the default algorithm. This flag is only meaningful for RSA key
+generation 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
+@cindex FIPS 186-2
+Force the use of the FIPS 186-2 key generation algorithm instead of
+the default algorithm.  This algorithm is slightly 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
+
+@noindent
+Now that we know the key basics, we can carry on and explain how to
+encrypt and decrypt data.  In almost all cases the data is a random
+session key which is in turn used for the actual encryption of the real
+data.  There are 2 functions to do this:
+
+@deftypefun gcry_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}})
+
+Obviously a public key must be provided for encryption.  It is
+expected as an appropriate S-expression (see above) in @var{pkey}.
+The data to be encrypted can either be in the simple old format, which
+is a very simple S-expression consisting only of one MPI, or it may be
+a more complex S-expression which also allows to specify flags for
+operation, like e.g. padding rules.
+
+@noindent
+If you don't want to let Libgcrypt handle the padding, you must pass an
+appropriate MPI using this expression for @var{data}:
+
+@example
+(data
+  (flags raw)
+  (value @var{mpi}))
+@end example
+
+@noindent
+This has the same semantics as the old style MPI only way.  @var{MPI}
+is the actual data, already padded appropriate for your protocol.
+Most RSA based systems however use PKCS#1 padding and so you can use
+this S-expression for @var{data}:
+
+@example
+(data
+  (flags pkcs1)
+  (value @var{block}))
+@end example
+
+@noindent
+Here, the "flags" list has the "pkcs1" flag which let the function know
+that it should provide PKCS#1 block type 2 padding.  The actual data to
+be encrypted is passed as a string of octets in @var{block}.  The
+function checks that this data actually can be used with the given key,
+does the padding and encrypts it.
+
+If the function could successfully perform the encryption, the return
+value will be 0 and a new S-expression with the encrypted result is
+allocated and assigned to the variable at the address of @var{r_ciph}.
+The caller is responsible to release this value using
+@code{gcry_sexp_release}.  In case of an error, an error code is
+returned and @var{r_ciph} will be set to @code{NULL}.
+
+@noindent
+The returned S-expression has this format when used with RSA:
+
+@example
+(enc-val
+  (rsa
+    (a @var{a-mpi})))
+@end example
+
+@noindent
+Where @var{a-mpi} is an MPI with the result of the RSA operation.  When
+using the Elgamal algorithm, the return value will have this format:
+
+@example
+(enc-val
+  (elg
+    (a @var{a-mpi})
+    (b @var{b-mpi})))
+@end example
+
+@noindent
+Where @var{a-mpi} and @var{b-mpi} are MPIs with the result of the
+Elgamal encryption operation.
+@end deftypefun
+@c end gcry_pk_encrypt
+
+@deftypefun gcry_error_t gcry_pk_decrypt (@w{gcry_sexp_t *@var{r_plain},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
+
+Obviously a private key must be provided for decryption.  It is expected
+as an appropriate S-expression (see above) in @var{skey}.  The data to
+be decrypted must match the format of the result as returned by
+@code{gcry_pk_encrypt}, but should be enlarged with a @code{flags}
+element:
+
+@example
+(enc-val
+  (flags)
+  (elg
+    (a @var{a-mpi})
+    (b @var{b-mpi})))
+@end example
+
+@noindent
+This function does not remove padding from the data by default.  To
+let Libgcrypt remove padding, give a hint in `flags' telling which
+padding method was used when encrypting:
+
+@example
+(flags @var{padding-method})
+@end example
+
+@noindent
+Currently @var{padding-method} is either @code{pkcs1} for PKCS#1 block
+type 2 padding, or @code{oaep} for RSA-OAEP padding.
+
+@noindent
+The function returns 0 on success or an error code.  The variable at the
+address of @var{r_plain} will be set to NULL on error or receive the
+decrypted value on success.  The format of @var{r_plain} is a
+simple S-expression part (i.e. not a valid one) with just one MPI if
+there was no @code{flags} element in @var{data}; if at least an empty
+@code{flags} is passed in @var{data}, the format is:
+
+@example
+(value @var{plaintext})
+@end example
+@end deftypefun
+@c end gcry_pk_decrypt
+
+
+Another operation commonly performed using public key cryptography is
+signing data.  In some sense this is even more important than
+encryption because digital signatures are an important instrument for
+key management.  Libgcrypt supports digital signatures using
+2 functions, similar to the encryption functions:
+
+@deftypefun gcry_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
+
+This function creates a digital signature for @var{data} using the
+private key @var{skey} and place it into the variable at the address of
+@var{r_sig}.  @var{data} may either be the simple old style S-expression
+with just one MPI or a modern and more versatile S-expression which
+allows to let Libgcrypt handle padding:
+
+@example
+ (data
+  (flags pkcs1)
+  (hash @var{hash-algo} @var{block}))
+@end example
+
+@noindent
+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
+"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
+provide a padded value), either the old format or better the following
+format should be used:
+
+@example
+(data
+  (flags raw)
+  (value @var{mpi}))
+@end example
+
+@noindent
+Here, the data to be signed is directly given as an @var{MPI}.
+
+@noindent
+For DSA the input data is expected in this format:
+
+@example
+(data
+  (flags raw)
+  (value @var{mpi}))
+@end example
+
+@noindent
+Here, the data to be signed is directly given as an @var{MPI}.  It is
+expect that this MPI is the the hash value.  For the standard DSA
+using a MPI is not a problem in regard to leading zeroes because the
+hash value is directly used as an MPI.  For better standard
+conformance it would be better to explicit use a memory string (like
+with pkcs1) but that is currently not supported.  However, for
+deterministic DSA as specified in RFC6979 this can't be used.  Instead
+the following input is expected.
+
+@example
+(data
+  (flags rfc6979)
+  (hash @var{hash-algo} @var{block}))
+@end example
+
+Note that the provided hash-algo is used for the internal HMAC; it
+should match the hash-algo used to create @var{block}.
+
+
+@noindent
+The signature is returned as a newly allocated S-expression in
+@var{r_sig} using this format for RSA:
+
+@example
+(sig-val
+  (rsa
+    (s @var{s-mpi})))
+@end example
+
+Where @var{s-mpi} is the result of the RSA sign operation.  For DSA the
+S-expression returned is:
+
+@example
+(sig-val
+  (dsa
+    (r @var{r-mpi})
+    (s @var{s-mpi})))
+@end example
+
+Where @var{r-mpi} and @var{s-mpi} are the result of the DSA sign
+operation.
+
+For Elgamal signing (which is slow, yields large numbers, hard to use
+correctly and probably is not as secure as the other algorithms), the
+same format is used with "elg" replacing "dsa"; for ECDSA signing, the
+same format is used with "ecdsa" replacing "dsa".
+
+For the EdDSA algorithm (cf. Ed25515) the required input parameters are:
+
+@example
+(data
+  (flags eddsa)
+  (hash-algo sha512)
+  (value @var{message}))
+@end example
+
+Note that the @var{message} may be of any length; hashing is part of
+the algorithm.  Using a large data block for @var{message} is not
+suggested; in that case the used protocol should better require that a
+hash of the message is used as input to the EdDSA algorithm.
+
+
+@end deftypefun
+@c end gcry_pk_sign
+
+@noindent
+The operation most commonly used is definitely the verification of a
+signature.  Libgcrypt provides this function:
+
+@deftypefun gcry_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})
+
+This is used to check whether the signature @var{sig} matches the
+@var{data}.  The public key @var{pkey} must be provided to perform this
+verification.  This function is similar in its parameters to
+@code{gcry_pk_sign} with the exceptions that the public key is used
+instead of the private key and that no signature is created but a
+signature, in a format as created by @code{gcry_pk_sign}, is passed to
+the function in @var{sig}.
+
+@noindent
+The result is 0 for success (i.e. the data matches the signature), or an
+error code where the most relevant code is @code{GCRY_ERR_BAD_SIGNATURE}
+to indicate that the signature does not match the provided data.
+
+@end deftypefun
+@c end gcry_pk_verify
+
+@node General public-key related Functions
+@section General public-key related Functions
+
+@noindent
+A couple of utility functions are available to retrieve the length of
+the key, map algorithm identifiers and perform sanity checks:
+
+@deftypefun {const char *} gcry_pk_algo_name (int @var{algo})
+
+Map the public key algorithm id @var{algo} to a string representation of
+the algorithm name.  For unknown algorithms this functions returns the
+string @code{"?"}.  This function should not be used to test for the
+availability of an algorithm.
+@end deftypefun
+
+@deftypefun int gcry_pk_map_name (const char *@var{name})
+
+Map the algorithm @var{name} to a public key algorithm Id.  Returns 0 if
+the algorithm name is not known.
+@end deftypefun
+
+@deftypefun int gcry_pk_test_algo (int @var{algo})
+
+Return 0 if the public key algorithm @var{algo} is available for use.
+Note that this is implemented as a macro.
+@end deftypefun
+
+
+@deftypefun {unsigned int} gcry_pk_get_nbits (gcry_sexp_t @var{key})
+
+Return what is commonly referred as the key length for the given
+public or private in @var{key}.
+@end deftypefun
+
+@deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{gcry_sexp_t @var{key}}, @w{unsigned char *@var{array}})
+
+Return the so called "keygrip" which is the SHA-1 hash of the public key
+parameters expressed in a way depended on the algorithm.  @var{array}
+must either provide space for 20 bytes or be @code{NULL}. In the latter
+case a newly allocated array of that size is returned.  On success a
+pointer to the newly allocated space or to @var{array} is returned.
+@code{NULL} is returned to indicate an error which is most likely an
+unknown algorithm or one where a "keygrip" has not yet been defined.
+The function accepts public or secret keys in @var{key}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key})
+
+Return zero if the private key @var{key} is `sane', an error code otherwise.
+Note that it is not possible to check the `saneness' of a public key.
+
+@end deftypefun
+
+
+@deftypefun gcry_error_t gcry_pk_algo_info (@w{int @var{algo}}, @w{int @var{what}}, @w{void *@var{buffer}}, @w{size_t *@var{nbytes}})
+
+Depending on the value of @var{what} return various information about
+the public key algorithm with the id @var{algo}.  Note that the
+function returns @code{-1} on error and the actual error code must be
+retrieved using the function @code{gcry_errno}.  The currently defined
+values for @var{what} are:
+
+@table @code
+@item GCRYCTL_TEST_ALGO:
+Return 0 if the specified algorithm is available for use.
+@var{buffer} must be @code{NULL}, @var{nbytes} may be passed as
+@code{NULL} or point to a variable with the required usage of the
+algorithm. This may be 0 for "don't care" or the bit-wise OR of these
+flags:
+
+@table @code
+@item GCRY_PK_USAGE_SIGN
+Algorithm is usable for signing.
+@item GCRY_PK_USAGE_ENCR
+Algorithm is usable for encryption.
+@end table
+
+Unless you need to test for the allowed usage, it is in general better
+to use the macro gcry_pk_test_algo instead.
+
+@item GCRYCTL_GET_ALGO_USAGE:
+Return the usage flags for the given algorithm.  An invalid algorithm
+return 0.  Disabled algorithms are ignored here because we
+want to know whether the algorithm is at all capable of a certain usage.
+
+@item GCRYCTL_GET_ALGO_NPKEY
+Return the number of elements the public key for algorithm @var{algo}
+consist of.  Return 0 for an unknown algorithm.
+
+@item GCRYCTL_GET_ALGO_NSKEY
+Return the number of elements the private key for algorithm @var{algo}
+consist of.  Note that this value is always larger than that of the
+public key.  Return 0 for an unknown algorithm.
+
+@item GCRYCTL_GET_ALGO_NSIGN
+Return the number of elements a signature created with the algorithm
+@var{algo} consists of.  Return 0 for an unknown algorithm or for an
+algorithm not capable of creating signatures.
+
+@item GCRYCTL_GET_ALGO_NENC
+Return the number of elements a encrypted message created with the algorithm
+@var{algo} consists of.  Return 0 for an unknown algorithm or for an
+algorithm not capable of encryption.
+@end table
+
+@noindent
+Please note that parameters not required should be passed as @code{NULL}.
+@end deftypefun
+@c end gcry_pk_algo_info
+
+
+@deftypefun gcry_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})
+
+This is a general purpose function to perform certain control
+operations.  @var{cmd} controls what is to be done. The return value is
+0 for success or an error code.  Currently supported values for
+@var{cmd} are:
+
+@table @code
+@item GCRYCTL_DISABLE_ALGO
+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
+function is not thread safe and should thus be used before any other
+threads are started.
+
+@end table
+@end deftypefun
+@c end gcry_pk_ctl
+
+@noindent
+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}})
+
+This function create a new public key pair using information given in
+the S-expression @var{parms} and stores the private and the public key
+in one new S-expression at the address given by @var{r_key}.  In case of
+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} to create an 2048 bit RSA key:
+
+@example
+(genkey
+  (rsa
+    (nbits 4:2048)))
+@end example
+
+@noindent
+To create an Elgamal key, substitute "elg" for "rsa" and to create a DSA
+key use "dsa".  Valid ranges for the key length depend on the
+algorithms; all commonly used key lengths are supported.  Currently
+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.  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
+requested bits.  This allows to request a specific curve to override a
+default selection Libgcrypt would have taken if @code{nbits} has been
+given.  The available names are listed with the description of the ECC
+public key parameters.
+
+@item rsa-use-e @var{value}
+This is only used with RSA to give a hint for the public exponent. The
+@var{value} will be used as a base to test for a usable exponent. Some
+values are special:
+
+@table @samp
+@item 0
+Use a secure and fast value.  This is currently the number 41.
+@item 1
+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
+If this parameter is not used, Libgcrypt uses for historic reasons
+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
+generated with a Q parameyer of size @var{n} bits.  If it is not given
+or zero Q is deduced from NBITS in this way:
+@table @samp
+@item 512 <= N <= 1024
+Q = 160
+@item N = 2048
+Q = 224
+@item N = 3072
+Q = 256
+@item N = 7680
+Q = 384
+@item N = 15360
+Q = 512
+@end table
+Note that in this case only the values for N, as given in the table,
+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 domain @var{list}
+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 @var{list}
+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 flags @var{flaglist}
+This is preferred way to define flags.  @var{flaglist} may contain any
+number of flags.  See above for a specification of these flags.
+
+Here is an example on how to create a key using curve Ed25519 with the
+ECDSA signature algorithm.  Note that the use of ECDSA with that curve
+is in general not recommended.
+@example
+(genkey
+  (ecc
+    (flags transient-key)))
+@end example
+
+@item transient-key
+@itemx use-x931
+@itemx use-fips186
+@itemx use-fips186-2
+These are deprecated ways to set a flag with that name; see above for
+a description of each flag.
+
+
+@end table
+@c end table of parameters
+
+@noindent
+The key pair is returned in a format depending on the algorithm.  Both
+private and public keys are returned in one container and may be
+accompanied by some miscellaneous information.
+
+@noindent
+Here are two examples; the first for Elgamal and the second for
+elliptic curve key generation:
+
+@example
+(key-data
+  (public-key
+    (elg
+      (p @var{p-mpi})
+      (g @var{g-mpi})
+      (y @var{y-mpi})))
+  (private-key
+    (elg
+      (p @var{p-mpi})
+      (g @var{g-mpi})
+      (y @var{y-mpi})
+      (x @var{x-mpi})))
+  (misc-key-info
+    (pm1-factors @var{n1 n2 ... nn}))
+@end example
+
+@example
+(key-data
+  (public-key
+    (ecc
+      (curve Ed25519)
+      (flags eddsa)
+      (q @var{q-value})))
+  (private-key
+    (ecc
+      (curve Ed25519)
+      (flags eddsa)
+      (q @var{q-value})
+      (d @var{d-value}))))
+@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 and only available if the key generation
+algorithm provides them.
+@end deftypefun
+@c end gcry_pk_genkey
+
+
+@noindent
+Future versions of Libgcrypt will have extended versions of the public
+key interfaced which will take an additional context to allow for
+pre-computations, special operations, and other optimization.  As a
+first step a new function is introduced to help using the ECC
+algorithms in new ways:
+
+@deftypefun gcry_error_t gcry_pubkey_get_sexp (@w{gcry_sexp_t *@var{r_sexp}}, @
+ @w{int @var{mode}}, @w{gcry_ctx_t @var{ctx}})
+
+Return an S-expression representing the context @var{ctx}.  Depending
+on the state of that context, the S-expression may either be a public
+key, a private key or any other object used with public key
+operations.  On success 0 is returned and a new S-expression is stored
+at @var{r_sexp}; on error an error code is returned and NULL is stored
+at @var{r_sexp}.  @var{mode} must be one of:
+
+@table @code
+@item 0
+Decide what to return depending on the context.  For example if the
+private key parameter is available a private key is returned, if not a
+public key is returned.
+
+@item GCRY_PK_GET_PUBKEY
+Return the public key even if the context has the private key
+parameter.
+
+@item GCRY_PK_GET_SECKEY
+Return the private key or the error @code{GPG_ERR_NO_SECKEY} if it is
+not possible.
+@end table
+
+As of now this function supports only certain ECC operations because a
+context object is right now only defined for ECC.  Over time this
+function will be extended to cover more algorithms.
+
+@end deftypefun
+@c end gcry_pubkey_get_sexp
+
+
+
+
+
+@c **********************************************************
+@c *******************  Hash Functions  *********************
+@c **********************************************************
+@node Hashing
+@chapter Hashing
+
+Libgcrypt provides an easy and consistent to use interface for hashing.
+Hashing is buffered and several hash algorithms can be updated at once.
+It is possible to compute a HMAC using the same routines.  The
+programming model follows an open/process/close paradigm and is in that
+similar to other building blocks provided by Libgcrypt.
+
+For convenience reasons, a few cyclic redundancy check value operations
+are also supported.
+
+@menu
+* Available hash algorithms::   List of hash algorithms supported by the library.
+* Working with hash algorithms::  List of functions related to hashing.
+@end menu
+
+@node Available hash algorithms
+@section Available hash algorithms
+
+@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
+This is not a real algorithm but used by some functions as an error
+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.  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.  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 algorithm has 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.  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 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.
+
+@item GCRY_MD_SHA224
+This is the SHA-224 algorithm which yields a message digest of 28 bytes.
+See Change Notice 1 for FIPS 180-2 for the specification.
+
+@item GCRY_MD_SHA256
+This is the SHA-256 algorithm which yields a message digest of 32 bytes.
+See FIPS 180-2 for the specification.
+
+@item GCRY_MD_SHA384
+This is the SHA-384 algorithm which yields a message digest of 48 bytes.
+See FIPS 180-2 for the specification.
+
+@item GCRY_MD_SHA512
+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-512 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
+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.  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.  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
+bytes.
+
+@item GCRY_MD_GOSTR3411_94
+This is the hash algorithm described in GOST R 34.11-94 which yields a
+message digest of 32 bytes.
+
+@item GCRY_MD_STRIBOG256
+This is the 256-bit version of hash algorithm described in GOST R 34.11-2012
+which yields a message digest of 32 bytes.
+
+@item GCRY_MD_STRIBOG512
+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
+
+@node Working with hash algorithms
+@section Working with hash algorithms
+
+To use most of these function it is necessary to create a context;
+this is done using:
+
+@deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})
+
+Create a message digest object for algorithm @var{algo}.  @var{flags}
+may be given as an bitwise OR of constants described below.  @var{algo}
+may be given as @code{0} if the algorithms to use are later set using
+@code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid
+handle or NULL.
+
+For a list of supported algorithms, see @ref{Available hash
+algorithms}.
+
+The flags allowed for @var{mode} are:
+
+@c begin table of hash flags
+@table @code
+@item GCRY_MD_FLAG_SECURE
+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 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
+
+You may use the function @code{gcry_md_is_enabled} to later check
+whether an algorithm has been enabled.
+
+@end deftypefun
+@c end function gcry_md_open
+
+If you want to calculate several hash algorithms at the same time, you
+have to use the following function right after the @code{gcry_md_open}:
+
+@deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
+
+Add the message digest algorithm @var{algo} to the digest object
+described by handle @var{h}.  Duplicated enabling of algorithms is
+detected and ignored.
+@end deftypefun
+
+If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must
+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 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
+
+
+After you are done with the hash calculation, you should release the
+resources by using:
+
+@deftypefun void gcry_md_close (gcry_md_hd_t @var{h})
+
+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.  The function also zeroises all sensitive information
+associated with this handle.
+
+
+@end deftypefun
+
+Often you have to do several hash operations using the same algorithm.
+To avoid the overhead of creating and releasing context, a reset function
+is provided:
+
+@deftypefun void gcry_md_reset (gcry_md_hd_t @var{h})
+
+Reset the current context to its initial state.  This is effectively
+identical to a close followed by an open and enabling all currently
+active algorithms.
+@end deftypefun
+
+
+Often it is necessary to start hashing some data and then continue to
+hash different data.  To avoid hashing the same data several times (which
+might not even be possible if the data is received from a pipe), a
+snapshot of the current hash context can be taken and turned into a new
+context:
+
+@deftypefun gcry_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src})
+
+Create a new digest object as an exact copy of the object described by
+handle @var{handle_src} and store it in @var{handle_dst}.  The context
+is not reset and you can continue to hash data using this context and
+independently using the original context.
+@end deftypefun
+
+
+Now that we have prepared everything to calculate hashes, it is time to
+see how it is actually done.  There are two ways for this, one to
+update the hash with a block of memory and one macro to update the hash
+by just one character.  Both methods can be used on the same hash context.
+
+@deftypefun void gcry_md_write (gcry_md_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
+
+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.  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})
+
+Pass the byte in @var{c} to the digest object with handle @var{h} to
+update the digest value.  This is an efficient function, implemented as
+a macro to buffer the data before an actual update.
+@end deftypefun
+
+The semantics of the hash functions do not provide for reading out intermediate
+message digests because the calculation must be finalized first.  This
+finalization may for example include the number of bytes hashed in the
+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} 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
+
+The way to read out the calculated message digest is by using the
+function:
+
+@deftypefun {unsigned char *} gcry_md_read (gcry_md_hd_t @var{h}, int @var{algo})
+
+@code{gcry_md_read} returns the message digest after finalizing the
+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 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:
+
+@deftypefun gpg_err_code_t gcry_md_hash_buffers ( @
+  @w{int @var{algo}}, @w{unsigned int @var{flags}}, @
+  @w{void *@var{digest}}, @
+  @w{const gcry_buffer_t *@var{iov}}, @w{int @var{iovcnt}} )
+
+@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 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
+may be obtained by using the function @code{gcry_md_get_algo_dlen}.
+
+@var{iov} is an array of buffer descriptions with @var{iovcnt} items.
+The caller should zero out the structures in this array and for each
+array item set the fields @code{.data} to the address of the data to
+be hashed, @code{.len} to number of bytes to be hashed.  If @var{.off}
+is also set, the data is taken starting at @var{.off} bytes from the
+begin of the buffer.  The field @code{.size} is not used.
+
+The only supported flag value for @var{flags} is
+@var{GCRY_MD_FLAG_HMAC} which turns this function into a HMAC
+function; the first item in @var{iov} is then used as the key.
+
+On success the function returns 0 and stores the resulting hash or MAC
+at @var{digest}.
+@end deftypefun
+
+@deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const void *@var{buffer}, size_t @var{length});
+
+@code{gcry_md_hash_buffer} is a shortcut function to calculate a message
+digest of a buffer.  This function does not require a context and
+immediately returns the message digest of the @var{length} bytes at
+@var{buffer}.  @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 may be obtained by using the function
+@code{gcry_md_get_algo_dlen}.
+
+Note that in contrast to @code{gcry_md_hash_buffers} this function
+will abort the process if an unavailable algorithm is used.
+@end deftypefun
+
+@c ***********************************
+@c ***** MD info functions ***********
+@c ***********************************
+
+Hash algorithms are identified by internal algorithm numbers (see
+@code{gcry_md_open} for a list).  However, in most applications they are
+used by names, so two functions are available to map between string
+representations and hash algorithm identifiers.
+
+@deftypefun {const char *} gcry_md_algo_name (int @var{algo})
+
+Map the digest algorithm id @var{algo} to a string representation of the
+algorithm name.  For unknown algorithms this function returns the
+string @code{"?"}.  This function should not be used to test for the
+availability of an algorithm.
+@end deftypefun
+
+@deftypefun int gcry_md_map_name (const char *@var{name})
+
+Map the algorithm with @var{name} to a digest algorithm identifier.
+Returns 0 if the algorithm name is not known.  Names representing
+@acronym{ASN.1} object identifiers are recognized if the @acronym{IETF}
+dotted format is used and the OID is prefixed with either "@code{oid.}"
+or "@code{OID.}".  For a list of supported OIDs, see the source code at
+@file{cipher/md.c}. This function should not be used to test for the
+availability of an algorithm.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
+
+Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the
+user allocated @var{buffer}. @var{length} must point to variable with
+the available size of @var{buffer} and receives after return the
+actual size of the returned OID.  The returned error code may be
+@code{GPG_ERR_TOO_SHORT} if the provided buffer is to short to receive
+the OID; it is possible to call the function with @code{NULL} for
+@var{buffer} to have it only return the required size.  The function
+returns 0 on success.
+
+@end deftypefun
+
+
+To test whether an algorithm is actually available for use, the
+following macro should be used:
+
+@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo})
+
+The macro returns 0 if the algorithm @var{algo} is available for use.
+@end deftypefun
+
+If the length of a message digest is not known, it can be retrieved
+using the following function:
+
+@deftypefun {unsigned int} gcry_md_get_algo_dlen (int @var{algo})
+
+Retrieve the length in bytes of the digest yielded by algorithm
+@var{algo}.  This is often used prior to @code{gcry_md_read} to allocate
+sufficient memory for the digest.
+@end deftypefun
+
+
+In some situations it might be hard to remember the algorithm used for
+the ongoing hashing. The following function might be used to get that
+information:
+
+@deftypefun int gcry_md_get_algo (gcry_md_hd_t @var{h})
+
+Retrieve the algorithm used with the handle @var{h}.  Note that this
+does not work reliable if more than one algorithm is enabled in @var{h}.
+@end deftypefun
+
+The following macro might also be useful:
+
+@deftypefun int gcry_md_is_secure (gcry_md_hd_t @var{h})
+
+This function returns true when the digest object @var{h} is allocated
+in "secure memory"; i.e. @var{h} was created with the
+@code{GCRY_MD_FLAG_SECURE}.
+@end deftypefun
+
+@deftypefun int gcry_md_is_enabled (gcry_md_hd_t @var{h}, int @var{algo})
+
+This function returns true when the algorithm @var{algo} has been
+enabled for the digest object @var{h}.
+@end deftypefun
+
+
+
+Tracking bugs related to hashing is often a cumbersome task which
+requires to add a lot of printf statements into the code.
+Libgcrypt provides an easy way to avoid this.  The actual data
+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 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
+@code{gcry_md_putc}.  If @code{NULL} is used for @var{suffix}, the
+debugging is stopped and the file closed.  This is only rarely required
+because @code{gcry_md_close} implicitly stops debugging.
+@end deftypefun
+
+
+
+@c **********************************************************
+@c *******************  MAC Functions  **********************
+@c **********************************************************
+@node Message Authentication Codes
+@chapter Message Authentication Codes
+
+Libgcrypt provides an easy and consistent to use interface for generating
+Message Authentication Codes (MAC). MAC generation is buffered and interface
+similar to the one used with hash algorithms. The programming model follows
+an open/process/close paradigm and is in that similar to other building blocks
+provided by Libgcrypt.
+
+@menu
+* Available MAC algorithms::   List of MAC algorithms supported by the library.
+* Working with MAC algorithms::  List of functions related to MAC algorithms.
+@end menu
+
+@node Available MAC algorithms
+@section Available MAC algorithms
+
+@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
+@cindex HMAC-Whirlpool
+@cindex HMAC-Stribog-256, HMAC-Stribog-512
+@cindex HMAC-GOSTR-3411-94
+@table @code
+@item GCRY_MAC_NONE
+This is not a real algorithm but used by some functions as an error
+return value.  This constant is guaranteed to have the value @code{0}.
+
+@item GCRY_MAC_HMAC_SHA256
+This is keyed-hash message authentication code (HMAC) message authentication
+algorithm based on the SHA-256 hash algorithm.
+
+@item GCRY_MAC_HMAC_SHA224
+This is HMAC message authentication algorithm based on the SHA-224 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_SHA512
+This is HMAC message authentication algorithm based on the SHA-512 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_SHA384
+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-256 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.
+
+@item GCRY_MAC_HMAC_MD5
+This is HMAC message authentication algorithm based on the MD5 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_MD4
+This is HMAC message authentication algorithm based on the MD4 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_RMD160
+This is HMAC message authentication algorithm based on the RIPE-MD-160 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_WHIRLPOOL
+This is HMAC message authentication algorithm based on the WHIRLPOOL hash
+algorithm.
+
+@item GCRY_MAC_HMAC_GOSTR3411_94
+This is HMAC message authentication algorithm based on the GOST R 34.11-94 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_STRIBOG256
+This is HMAC message authentication algorithm based on the 256-bit hash
+algorithm described in GOST R 34.11-2012.
+
+@item GCRY_MAC_HMAC_STRIBOG512
+This is HMAC message authentication algorithm based on the 512-bit hash
+algorithm described in GOST R 34.11-2012.
+
+@item GCRY_MAC_CMAC_AES
+This is CMAC (Cipher-based MAC) message authentication algorithm based on
+the AES block cipher algorithm.
+
+@item GCRY_MAC_CMAC_3DES
+This is CMAC message authentication algorithm based on the three-key EDE
+Triple-DES block cipher algorithm.
+
+@item GCRY_MAC_CMAC_CAMELLIA
+This is CMAC message authentication algorithm based on the Camellia block cipher
+algorithm.
+
+@item GCRY_MAC_CMAC_CAST5
+This is CMAC message authentication algorithm based on the CAST128-5
+block cipher algorithm.
+
+@item GCRY_MAC_CMAC_BLOWFISH
+This is CMAC message authentication algorithm based on the Blowfish
+block cipher algorithm.
+
+@item GCRY_MAC_CMAC_TWOFISH
+This is CMAC message authentication algorithm based on the Twofish
+block cipher algorithm.
+
+@item GCRY_MAC_CMAC_SERPENT
+This is CMAC message authentication algorithm based on the Serpent
+block cipher algorithm.
+
+@item GCRY_MAC_CMAC_SEED
+This is CMAC message authentication algorithm based on the SEED
+block cipher algorithm.
+
+@item GCRY_MAC_CMAC_RFC2268
+This is CMAC message authentication algorithm based on the Ron's Cipher 2
+block cipher algorithm.
+
+@item GCRY_MAC_CMAC_IDEA
+This is CMAC message authentication algorithm based on the IDEA
+block cipher algorithm.
+
+@item GCRY_MAC_CMAC_GOST28147
+This is CMAC message authentication algorithm based on the GOST 28147-89
+block cipher algorithm.
+
+@item GCRY_MAC_GMAC_AES
+This is GMAC (GCM mode based MAC) message authentication algorithm based on
+the AES block cipher algorithm.
+
+@item GCRY_MAC_GMAC_CAMELLIA
+This is GMAC message authentication algorithm based on the Camellia
+block cipher algorithm.
+
+@item GCRY_MAC_GMAC_TWOFISH
+This is GMAC message authentication algorithm based on the Twofish
+block cipher algorithm.
+
+@item GCRY_MAC_GMAC_SERPENT
+This is GMAC message authentication algorithm based on the Serpent
+block cipher algorithm.
+
+@item GCRY_MAC_GMAC_SEED
+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
+
+@node Working with MAC algorithms
+@section Working with MAC algorithms
+
+To use most of these function it is necessary to create a context;
+this is done using:
+
+@deftypefun gcry_error_t gcry_mac_open (gcry_mac_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags}, gcry_ctx_t @var{ctx})
+
+Create a MAC object for algorithm @var{algo}. @var{flags} may be given as an
+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 @ref{Available MAC algorithms}.
+
+The flags allowed for @var{mode} are:
+
+@c begin table of MAC flags
+@table @code
+@item GCRY_MAC_FLAG_SECURE
+Allocate all buffers and the resulting MAC in "secure memory".  Use this if the
+MAC data is highly confidential.
+
+@end table
+@c begin table of MAC flags
+
+@end deftypefun
+@c end function gcry_mac_open
+
+
+In order to use a handle for performing MAC algorithm operations, a
+`key' has to be set first:
+
+@deftypefun gcry_error_t gcry_mac_setkey (gcry_mac_hd_t @var{h}, const void *@var{key}, size_t @var{keylen})
+
+Set the MAC key to the value of @var{key} of length @var{keylen} bytes. With
+HMAC algorithms, there is no restriction on the length of the key. With CMAC
+algorithms, the length of the key is restricted to those supported by the
+underlying block cipher.
+@end deftypefun
+
+
+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})
+
+Set the IV to the value of @var{iv} of length @var{ivlen} bytes.
+@end deftypefun
+
+
+After you are done with the MAC calculation, you should release the resources
+by using:
+
+@deftypefun void gcry_mac_close (gcry_mac_hd_t @var{h})
+
+Release all resources of MAC context @var{h}.  @var{h} should not be
+used after a call to this function.  A @code{NULL} passed as @var{h} is
+ignored.  The function also clears all sensitive information associated
+with this handle.
+@end deftypefun
+
+
+Often you have to do several MAC operations using the same algorithm.
+To avoid the overhead of creating and releasing context, a reset function
+is provided:
+
+@deftypefun gcry_error_t gcry_mac_reset (gcry_mac_hd_t @var{h})
+
+Reset the current context to its initial state. This is effectively identical
+to a close followed by an open and setting same key.
+
+Note that gcry_mac_reset is implemented as a macro.
+@end deftypefun
+
+
+Now that we have prepared everything to calculate MAC, it is time to
+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.  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})
+
+@code{gcry_mac_read} returns the MAC after finalizing the calculation.
+Function copies the resulting MAC value to @var{buffer} of the length
+@var{length}. If @var{length} is larger than length of resulting MAC value,
+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})
+
+@code{gcry_mac_verify} finalizes MAC calculation and compares result with
+@var{length} bytes of data in @var{buffer}. Error code @code{GPG_ERR_CHECKSUM}
+is returned if the MAC value in the buffer @var{buffer} does not match
+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 ***********************************
+
+MAC algorithms are identified by internal algorithm numbers (see
+@code{gcry_mac_open} for a list).  However, in most applications they are
+used by names, so two functions are available to map between string
+representations and MAC algorithm identifiers.
+
+@deftypefun {const char *} gcry_mac_algo_name (int @var{algo})
+
+Map the MAC algorithm id @var{algo} to a string representation of the
+algorithm name.  For unknown algorithms this function returns the
+string @code{"?"}.  This function should not be used to test for the
+availability of an algorithm.
+@end deftypefun
+
+@deftypefun int gcry_mac_map_name (const char *@var{name})
+
+Map the algorithm with @var{name} to a MAC algorithm identifier.
+Returns 0 if the algorithm name is not known. This function should not
+be used to test for the availability of an algorithm.
+@end deftypefun
+
+
+To test whether an algorithm is actually available for use, the
+following macro should be used:
+
+@deftypefun gcry_error_t gcry_mac_test_algo (int @var{algo})
+
+The macro returns 0 if the MAC algorithm @var{algo} is available for use.
+@end deftypefun
+
+
+If the length of a message digest is not known, it can be retrieved
+using the following function:
+
+@deftypefun {unsigned int} gcry_mac_get_algo_maclen (int @var{algo})
+
+Retrieve the length in bytes of the MAC yielded by algorithm @var{algo}.
+This is often used prior to @code{gcry_mac_read} to allocate sufficient memory
+for the MAC value. On error @code{0} is returned.
+@end deftypefun
+
+
+@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
+length is returned.  On error @code{0} is returned.  The key length is
+returned as number of octets.
+@end deftypefun
+
+
+
+@c *******************************************************
+@c *******************  KDF  *****************************
+@c *******************************************************
+@node Key Derivation
+@chapter Key Derivation
+
+@acronym{Libgcypt} provides a general purpose function to derive keys
+from strings.
+
+@deftypefun gpg_error_t gcry_kdf_derive ( @
+            @w{const void *@var{passphrase}}, @w{size_t @var{passphraselen}}, @
+            @w{int @var{algo}}, @w{int @var{subalgo}}, @
+            @w{const void *@var{salt}}, @w{size_t @var{saltlen}}, @
+            @w{unsigned long @var{iterations}}, @
+            @w{size_t @var{keysize}}, @w{void *@var{keybuffer}} )
+
+
+Derive a key from a passphrase.  @var{keysize} gives the requested
+size of the keys in octets.  @var{keybuffer} is a caller provided
+buffer filled on success with the derived key.  The input passphrase
+is taken from @var{passphrase} which is an arbitrary memory buffer of
+@var{passphraselen} octets.  @var{algo} specifies the KDF algorithm to
+use; see below.  @var{subalgo} specifies an algorithm used internally
+by the KDF algorithms; this is usually a hash algorithm but certain
+KDF algorithms may use it differently.  @var{salt} is a salt of length
+@var{saltlen} octets, as needed by most KDF algorithms.
+@var{iterations} is a positive integer parameter to most KDFs.
+
+@noindent
+On success 0 is returned; on failure an error code.
+
+@noindent
+Currently supported KDFs (parameter @var{algo}):
+
+@table @code
+@item GCRY_KDF_SIMPLE_S2K
+The OpenPGP simple S2K algorithm (cf. RFC4880).  Its use is strongly
+deprecated.  @var{salt} and @var{iterations} are not needed and may be
+passed as @code{NULL}/@code{0}.
+
+@item GCRY_KDF_SALTED_S2K
+The OpenPGP salted S2K algorithm (cf. RFC4880).  Usually not used.
+@var{iterations} is not needed and may be passed as @code{0}.  @var{saltlen}
+must be given as 8.
+
+@item GCRY_KDF_ITERSALTED_S2K
+The OpenPGP iterated+salted S2K algorithm (cf. RFC4880).  This is the
+default for most OpenPGP applications.  @var{saltlen} must be given as
+8.  Note that OpenPGP defines a special encoding of the
+@var{iterations}; however this function takes the plain decoded
+iteration count.
+
+@item GCRY_KDF_PBKDF2
+The PKCS#5 Passphrase Based Key Derivation Function number 2.
+
+@item GCRY_KDF_SCRYPT
+The SCRYPT Key Derivation Function.  The subalgorithm is used to specify
+the CPU/memory cost parameter N, and the number of iterations
+is used for the parallelization parameter p.  The block size is fixed
+at 8 in the current implementation.
+
+@end table
+@end deftypefun
+
+
+@c **********************************************************
+@c *******************  Random  *****************************
+@c **********************************************************
+@node Random Numbers
+@chapter Random Numbers
+
+@menu
+* Quality of random numbers::   Libgcrypt uses different quality levels.
+* Retrieving random numbers::   How to retrieve random numbers.
+@end menu
+
+@node Quality of random numbers
+@section Quality of random numbers
+
+@acronym{Libgcypt} offers random numbers of different quality levels:
+
+@deftp {Data type} gcry_random_level_t
+The constants for the random quality levels are of this enum type.
+@end deftp
+
+@table @code
+@item GCRY_WEAK_RANDOM
+For all functions, except for @code{gcry_mpi_randomize}, this level maps
+to GCRY_STRONG_RANDOM.  If you do not want this, consider using
+@code{gcry_create_nonce}.
+@item GCRY_STRONG_RANDOM
+Use this level for session keys and similar purposes.
+@item GCRY_VERY_STRONG_RANDOM
+Use this level for long term key material.
+@end table
+
+@node Retrieving random numbers
+@section Retrieving random numbers
+
+@deftypefun void gcry_randomize (unsigned char *@var{buffer}, size_t @var{length}, enum gcry_random_level @var{level})
+
+Fill @var{buffer} with @var{length} random bytes using a random quality
+as defined by @var{level}.
+@end deftypefun
+
+@deftypefun {void *} gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level})
+
+Convenience function to allocate a memory block consisting of
+@var{nbytes} fresh random bytes using a random quality as defined by
+@var{level}.
+@end deftypefun
+
+@deftypefun {void *} gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level})
+
+Convenience function to allocate a memory block consisting of
+@var{nbytes} fresh random bytes using a random quality as defined by
+@var{level}.  This function differs from @code{gcry_random_bytes} in
+that the returned buffer is allocated in a ``secure'' area of the
+memory.
+@end deftypefun
+
+@deftypefun void gcry_create_nonce (unsigned char *@var{buffer}, size_t @var{length})
+
+Fill @var{buffer} with @var{length} unpredictable bytes.  This is
+commonly called a nonce and may also be used for initialization
+vectors and padding.  This is an extra function nearly independent of
+the other random function for 3 reasons: It better protects the
+regular random generator's internal state, provides better performance
+and does not drain the precious entropy pool.
+
+@end deftypefun
+
+
+
+@c **********************************************************
+@c *******************  S-Expressions ***********************
+@c **********************************************************
+@node S-expressions
+@chapter S-expressions
+
+S-expressions are used by the public key functions to pass complex data
+structures around.  These LISP like objects are used by some
+cryptographic protocols (cf. RFC-2692) and Libgcrypt provides functions
+to parse and construct them.  For detailed information, see
+@cite{Ron Rivest, code and description of S-expressions,
+@uref{http://theory.lcs.mit.edu/~rivest/sexp.html}}.
+
+@menu
+* Data types for S-expressions::  Data types related with S-expressions.
+* Working with S-expressions::  How to work with S-expressions.
+@end menu
+
+@node Data types for S-expressions
+@section Data types for S-expressions
+
+@deftp {Data type} gcry_sexp_t
+The @code{gcry_sexp_t} type describes an object with the Libgcrypt internal
+representation of an S-expression.
+@end deftp
+
+@node Working with S-expressions
+@section Working with S-expressions
+
+@noindent
+There are several functions to create an Libgcrypt S-expression object
+from its external representation or from a string template.  There is
+also a function to convert the internal representation back into one of
+the external formats:
+
+
+@deftypefun gcry_error_t gcry_sexp_new (@w{gcry_sexp_t *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}})
+
+This is the generic function to create an new S-expression object from
+its external representation in @var{buffer} of @var{length} bytes.  On
+success the result is stored at the address given by @var{r_sexp}.
+With @var{autodetect} set to 0, the data in @var{buffer} is expected to
+be in canonized format, with @var{autodetect} set to 1 the parses any of
+the defined external formats.  If @var{buffer} does not hold a valid
+S-expression an error code is returned and @var{r_sexp} set to
+@code{NULL}.
+Note that the caller is responsible for releasing the newly allocated
+S-expression using @code{gcry_sexp_release}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_sexp_create (@w{gcry_sexp_t *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)})
+
+This function is identical to @code{gcry_sexp_new} but has an extra
+argument @var{freefnc}, which, when not set to @code{NULL}, is expected
+to be a function to release the @var{buffer}; most likely the standard
+@code{free} function is used for this argument.  This has the effect of
+transferring the ownership of @var{buffer} to the created object in
+@var{r_sexp}.  The advantage of using this function is that Libgcrypt
+might decide to directly use the provided buffer and thus avoid extra
+copying.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_sexp_sscan (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
+
+This is another variant of the above functions.  It behaves nearly
+identical but provides an @var{erroff} argument which will receive the
+offset into the buffer where the parsing stopped on error.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_sexp_build (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...})
+
+This function creates an internal S-expression from the string template
+@var{format} and stores it at the address of @var{r_sexp}. If there is a
+parsing error, the function returns an appropriate error code and stores
+the offset into @var{format} where the parsing stopped in @var{erroff}.
+The function supports a couple of printf-like formatting characters and
+expects arguments for some of these escape sequences right after
+@var{format}.  The following format characters are defined:
+
+@table @samp
+@item %m
+The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
+its value is inserted into the resulting S-expression.  The MPI is
+stored as a signed integer.
+@item %M
+The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
+its value is inserted into the resulting S-expression.  The MPI is
+stored as an unsigned integer.
+@item %s
+The next argument is expected to be of type @code{char *} and that
+string is inserted into the resulting S-expression.
+@item %d
+The next argument is expected to be of type @code{int} and its value is
+inserted into the resulting S-expression.
+@item %u
+The next argument is expected to be of type @code{unsigned int} and
+its value is inserted into the resulting S-expression.
+@item %b
+The next argument is expected to be of type @code{int} directly
+followed by an argument of type @code{char *}.  This represents a
+buffer of given length to be inserted into the resulting 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
+No other format characters are defined and would return an error.  Note
+that the format character @samp{%%} does not exists, because a percent
+sign is not a valid character in an S-expression.
+@end deftypefun
+
+@deftypefun void gcry_sexp_release (@w{gcry_sexp_t @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
+
+
+@noindent
+The next 2 functions are used to convert the internal representation
+back into a regular external S-expression format and to show the
+structure for debugging.
+
+@deftypefun size_t gcry_sexp_sprint (@w{gcry_sexp_t @var{sexp}}, @w{int @var{mode}}, @w{char *@var{buffer}}, @w{size_t @var{maxlength}})
+
+Copies the S-expression object @var{sexp} into @var{buffer} using the
+format specified in @var{mode}.  @var{maxlength} must be set to the
+allocated length of @var{buffer}.  The function returns the actual
+length of valid bytes put into @var{buffer} or 0 if the provided buffer
+is too short.  Passing @code{NULL} for @var{buffer} returns the required
+length for @var{buffer}.  For convenience reasons an extra byte with
+value 0 is appended to the buffer.
+
+@noindent
+The following formats are supported:
+
+@table @code
+@item GCRYSEXP_FMT_DEFAULT
+Returns a convenient external S-expression representation.
+
+@item GCRYSEXP_FMT_CANON
+Return the S-expression in canonical format.
+
+@item GCRYSEXP_FMT_BASE64
+Not currently supported.
+
+@item GCRYSEXP_FMT_ADVANCED
+Returns the S-expression in advanced format.
+@end table
+@end deftypefun
+
+@deftypefun void gcry_sexp_dump (@w{gcry_sexp_t @var{sexp}})
+
+Dumps @var{sexp} in a format suitable for debugging to Libgcrypt's
+logging stream.
+@end deftypefun
+
+@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.
+
+@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}})
+
+Scan the canonical encoded @var{buffer} with implicit length values and
+return the actual length this S-expression uses.  For a valid S-expression
+it should never return 0.  If @var{length} is not 0, the maximum
+length to scan is given; this can be used for syntax checks of
+data passed from outside.  @var{errcode} and @var{erroff} may both be
+passed as @code{NULL}.
+
+@end deftypefun
+
+
+@noindent
+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}})
+
+Scan the S-expression for a sublist with a type (the car of the list)
+matching the string @var{token}.  If @var{toklen} is not 0, the token is
+assumed to be raw memory of this length.  The function returns a newly
+allocated S-expression consisting of the found sublist or @code{NULL}
+when not found.
+@end deftypefun
+
+
+@deftypefun int gcry_sexp_length (@w{const gcry_sexp_t @var{list}})
+
+Return the length of the @var{list}.  For a valid S-expression this
+should be at least 1.
+@end deftypefun
+
+
+@deftypefun gcry_sexp_t gcry_sexp_nth (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}})
+
+Create and return a new S-expression from the element with index @var{number} in
+@var{list}.  Note that the first element has the index 0.  If there is
+no such element, @code{NULL} is returned.
+@end deftypefun
+
+@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 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}})
+
+Create and return a new list form all elements except for the first one.
+Note that this function may return an invalid S-expression because it
+is not guaranteed, that the type exists and is a string.  However, for
+parsing a complex S-expression it might be useful for intermediate
+lists.  Returns @code{NULL} on error.
+@end deftypefun
+
+
+@deftypefun {const char *} gcry_sexp_nth_data (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{size_t *@var{datalen}})
+
+This function is used to get data from a @var{list}.  A pointer to the
+actual data with index @var{number} is returned and the length of this
+data will be stored to @var{datalen}.  If there is no data at the given
+index or the index represents another list, @code{NULL} is returned.
+@strong{Caution:} The returned pointer is valid as long as @var{list} is
+not modified or released.
+
+@noindent
+Here is an example on how to extract and print the surname (Meier) from
+the S-expression @samp{(Name Otto Meier (address Burgplatz 3))}:
+
+@example
+size_t len;
+const char *name;
+
+name = gcry_sexp_nth_data (list, 2, &len);
+printf ("my name is %.*s\n", (int)len, name);
+@end example
+@end deftypefun
+
+@deftypefun {void *} gcry_sexp_nth_buffer (@w{const gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{size_t *@var{rlength}})
+
+This function is used to get data from a @var{list}.  A malloced
+buffer with the actual data at list index @var{number} is returned and
+the length of this buffer will be stored to @var{rlength}.  If there
+is no data at the given index or the index represents another list,
+@code{NULL} is returned.  The caller must release the result using
+@code{gcry_free}.
+
+@noindent
+Here is an example on how to extract and print the CRC value from the
+S-expression @samp{(hash crc32 #23ed00d7)}:
+
+@example
+size_t len;
+char *value;
+
+value = gcry_sexp_nth_buffer (list, 2, &len);
+if (value)
+  fwrite (value, len, 1, stdout);
+gcry_free (value);
+@end example
+@end deftypefun
+
+@deftypefun {char *} gcry_sexp_nth_string (@w{gcry_sexp_t @var{list}}, @w{int @var{number}})
+
+This function is used to get and convert data from a @var{list}. The
+data is assumed to be a Nul terminated string.  The caller must
+release this returned value using @code{gcry_free}.  If there is
+no data at the given index, the index represents a list or the value
+can't be converted to a string, @code{NULL} is returned.
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_sexp_nth_mpi (@w{gcry_sexp_t @var{list}}, @w{int @var{number}}, @w{int @var{mpifmt}})
+
+This function is used to get and convert data from a @var{list}. This
+data is assumed to be an MPI stored in the format described by
+@var{mpifmt} and returned as a standard Libgcrypt MPI.  The caller must
+release this returned value using @code{gcry_mpi_release}.  If there is
+no data at the given index, the index represents a list or the value
+can't be converted to an MPI, @code{NULL} is returned.  If you use
+this function to parse results of a public key function, you most
+likely want to use @code{GCRYMPI_FMT_USG}.
+@end deftypefun
+
+@deftypefun gpg_error_t gcry_sexp_extract_param ( @
+  @w{gcry_sexp_t @var{sexp}}, @
+  @w{const char *@var{path}}, @
+  @w{const char *@var{list}}, ...)
+
+Extract parameters from an S-expression using a list of parameter
+names.  The names of these parameters are specified in LIST.  White
+space between the parameter names are ignored. Some special characters
+may be given to control the conversion:
+
+@table @samp
+@item +
+Switch to unsigned integer format (GCRYMPI_FMT_USG).  This is the
+default mode.
+@item -
+Switch to standard signed format (GCRYMPI_FMT_STD).
+@item /
+Switch to opaque MPI format.  The resulting MPIs may not be used for
+computations; see @code{gcry_mpi_get_opaque} for details.
+@item &
+Switch to buffer descriptor mode.  See below for details.
+@item ?
+If immediately following a parameter letter (no white space allowed),
+that parameter is considered optional.
+@end table
+
+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 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_d, &mpi_foo, NULL)
+@end example
+
+stores the parameter 'n' from @var{key} as an unsigned MPI into
+@var{mpi_n}, the parameter 'x' as an opaque MPI into @var{mpi_x}, the
+parameters 'e' and 'd' again as an unsigned MPI into @var{mpi_e} and
+@var{mpi_d} and finally the parameter 'foo' as a signed MPI into
+@var{mpi_foo}.
+
+@var{path} is an optional string used to locate a token.  The
+exclamation mark separated tokens are used via
+@code{gcry_sexp_find_token} to find a start point inside the
+S-expression.
+
+In buffer descriptor mode a pointer to a @code{gcry_buffer_t}
+descriptor is expected instead of a pointer to an MPI.  The caller may
+use two different operation modes here: If the @var{data} field of the
+provided descriptor is @code{NULL}, the function allocates a new
+buffer and stores it at @var{data}; the other fields are set
+accordingly with @var{off} set to 0.  If @var{data} is not
+@code{NULL}, the function assumes that the @var{data}, @var{size}, and
+@var{off} fields specify a buffer where to but the value of the
+respective parameter; on return the @var{len} field receives the
+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 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
+
+
+@c **********************************************************
+@c *******************  MPIs ******** ***********************
+@c **********************************************************
+@node MPI library
+@chapter MPI library
+
+@menu
+* Data types::                  MPI related data types.
+* Basic functions::             First steps with MPI numbers.
+* MPI formats::                 External representation of MPIs.
+* Calculations::                Performing MPI calculations.
+* Comparisons::                 How to compare MPI values.
+* Bit manipulations::           How to access single bits of MPI values.
+* EC functions::                Elliptic curve related functions.
+* Miscellaneous::               Miscellaneous MPI functions.
+@end menu
+
+Public key cryptography is based on mathematics with large numbers.  To
+implement the public key functions, a library for handling these large
+numbers is required.  Because of the general usefulness of such a
+library, its interface is exposed by Libgcrypt.
+In the context of Libgcrypt and in most other applications, these large
+numbers are called MPIs (multi-precision-integers).
+
+@node Data types
+@section Data types
+
+@deftp {Data type} {gcry_mpi_t}
+This type represents an object to hold an MPI.
+@end deftp
+
+@deftp {Data type} {gcry_mpi_point_t}
+This type represents an object to hold a point for elliptic curve math.
+@end deftp
+
+@node Basic functions
+@section Basic functions
+
+@noindent
+To work with MPIs, storage must be allocated and released for the
+numbers.  This can be done with one of these functions:
+
+@deftypefun gcry_mpi_t gcry_mpi_new (@w{unsigned int @var{nbits}})
+
+Allocate a new MPI object, initialize it to 0 and initially allocate
+enough memory for a number of at least @var{nbits}.  This pre-allocation is
+only a small performance issue and not actually necessary because
+Libgcrypt automatically re-allocates the required memory.
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_mpi_snew (@w{unsigned int @var{nbits}})
+
+This is identical to @code{gcry_mpi_new} but allocates the MPI in the so
+called "secure memory" which in turn will take care that all derived
+values will also be stored in this "secure memory".  Use this for highly
+confidential data like private key parameters.
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_mpi_copy (@w{const gcry_mpi_t @var{a}})
+
+Create a new MPI as the exact copy of @var{a} but with the constant
+and immutable flags cleared.
+@end deftypefun
+
+
+@deftypefun void gcry_mpi_release (@w{gcry_mpi_t @var{a}})
+
+Release the MPI @var{a} and free all associated resources.  Passing
+@code{NULL} is allowed and ignored.  When a MPI stored in the "secure
+memory" is released, that memory gets wiped out immediately.
+@end deftypefun
+
+@noindent
+The simplest operations are used to assign a new value to an MPI:
+
+@deftypefun gcry_mpi_t gcry_mpi_set (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{u}})
+
+Assign the value of @var{u} to @var{w} and return @var{w}.  If
+@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the
+value of @var{u} and returned.
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_mpi_set_ui (@w{gcry_mpi_t @var{w}}, @w{unsigned long @var{u}})
+
+Assign the value of @var{u} to @var{w} and return @var{w}.  If
+@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the
+value of @var{u} and returned.  This function takes an @code{unsigned
+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 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}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_snatch (@w{gcry_mpi_t @var{w}}, @
+                                  @w{const gcry_mpi_t @var{u}})
+
+Set @var{u} into @var{w} and release @var{u}.  If @var{w} is
+@code{NULL} only @var{u} will be released.
+@end deftypefun
+
+@deftypefun void gcry_mpi_neg (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}})
+
+Set the sign of @var{w} to the negative of @var{u}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_abs (@w{gcry_mpi_t @var{w}})
+
+Clear the sign of @var{w}.
+@end deftypefun
+
+
+@node MPI formats
+@section MPI formats
+
+@noindent
+The following functions are used to convert between an external
+representation of an MPI and the internal one of Libgcrypt.
+
+@deftypefun gcry_error_t gcry_mpi_scan (@w{gcry_mpi_t *@var{r_mpi}}, @w{enum gcry_mpi_format @var{format}}, @w{const unsigned char *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nscanned}})
+
+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}. 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
+@var{buffer}:
+
+@table @code
+@item GCRYMPI_FMT_STD
+2-complement stored without a length header.  Note that
+@code{gcry_mpi_print} stores a @code{0} as a string of zero length.
+
+@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}
+with a 4 byte big endian header.
+
+@item GCRYMPI_FMT_HEX
+Stored as a string with each byte of the MPI encoded as 2 hex digits.
+Negative numbers are prefix with a minus sign and in addition the
+high bit is always zero to make clear that an explicit sign ist used.
+When using this format, @var{buflen} must be zero.
+
+@item GCRYMPI_FMT_USG
+Simple unsigned integer.
+@end table
+
+@noindent
+Note that all of the above formats store the integer in big-endian
+format (MSB first).
+@end deftypefun
+
+
+@deftypefun gcry_error_t gcry_mpi_print (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char *@var{buffer}}, @w{size_t @var{buflen}}, @w{size_t *@var{nwritten}}, @w{const gcry_mpi_t @var{a}})
+
+Convert the MPI @var{a} into an external representation described by
+@var{format} (see above) and store it in the provided @var{buffer}
+which has a usable length of at least the @var{buflen} bytes. If
+@var{nwritten} is not NULL, it will receive the number of bytes
+actually stored in @var{buffer} after a successful operation.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_mpi_aprint (@w{enum gcry_mpi_format @var{format}}, @w{unsigned char **@var{buffer}}, @w{size_t *@var{nbytes}}, @w{const gcry_mpi_t @var{a}})
+
+Convert the MPI @var{a} into an external representation described by
+@var{format} (see above) and store it in a newly allocated buffer which
+address will be stored in the variable @var{buffer} points to.  The
+number of bytes stored in this buffer will be stored in the variable
+@var{nbytes} points to, unless @var{nbytes} is @code{NULL}.
+
+Even if @var{nbytes} is zero, the function allocates at least one byte
+and store a zero there.  Thus with formats @code{GCRYMPI_FMT_STD} and
+@code{GCRYMPI_FMT_USG} the caller may safely set a returned length of
+0 to 1 to represent a zero as a 1 byte string.
+
+@end deftypefun
+
+@deftypefun void gcry_mpi_dump (@w{const gcry_mpi_t @var{a}})
+
+Dump the value of @var{a} in a format suitable for debugging to
+Libgcrypt's logging stream.  Note that one leading space but no trailing
+space or linefeed will be printed.  It is okay to pass @code{NULL} for
+@var{a}.
+@end deftypefun
+
+
+@node Calculations
+@section Calculations
+
+@noindent
+Basic arithmetic operations:
+
+@deftypefun void gcry_mpi_add (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
+
+@math{@var{w} = @var{u} + @var{v}}.
+@end deftypefun
+
+
+@deftypefun void gcry_mpi_add_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
+
+@math{@var{w} = @var{u} + @var{v}}.  Note that @var{v} is an unsigned integer.
+@end deftypefun
+
+
+@deftypefun void gcry_mpi_addm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
+
+@math{@var{w} = @var{u} + @var{v} \bmod @var{m}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_sub (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
+
+@math{@var{w} = @var{u} - @var{v}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_sub_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
+
+@math{@var{w} = @var{u} - @var{v}}.  @var{v} is an unsigned integer.
+@end deftypefun
+
+@deftypefun void gcry_mpi_subm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
+
+@math{@var{w} = @var{u} - @var{v} \bmod @var{m}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_mul (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}})
+
+@math{@var{w} = @var{u} * @var{v}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_mul_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
+
+@math{@var{w} = @var{u} * @var{v}}.  @var{v} is an unsigned integer.
+@end deftypefun
+
+@deftypefun void gcry_mpi_mulm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}})
+
+@math{@var{w} = @var{u} * @var{v} \bmod @var{m}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_mul_2exp (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{e}})
+
+@c FIXME: I am in need for a real TeX{info} guru:
+@c I don't know why TeX can grok @var{e} here.
+@math{@var{w} = @var{u} * 2^e}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_div (@w{gcry_mpi_t @var{q}}, @w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}}, @w{int @var{round}})
+
+@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.
+@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}})
+
+@math{@var{r} = @var{dividend} \bmod @var{divisor}}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_powm (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{b}}, @w{const gcry_mpi_t @var{e}}, @w{const gcry_mpi_t @var{m}})
+
+@c I don't know why TeX can grok @var{e} here.
+@math{@var{w} = @var{b}^e \bmod @var{m}}.
+@end deftypefun
+
+@deftypefun int gcry_mpi_gcd (@w{gcry_mpi_t @var{g}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
+
+Set @var{g} to the greatest common divisor of @var{a} and @var{b}.
+Return true if the @var{g} is 1.
+@end deftypefun
+
+@deftypefun int gcry_mpi_invm (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{m}})
+
+Set @var{x} to the multiplicative inverse of @math{@var{a} \bmod @var{m}}.
+Return true if the inverse exists.
+@end deftypefun
+
+
+@node Comparisons
+@section Comparisons
+
+@noindent
+The next 2 functions are used to compare MPIs:
+
+
+@deftypefun int gcry_mpi_cmp (@w{const gcry_mpi_t @var{u}}, @w{const gcry_mpi_t @var{v}})
+
+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}.  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}})
+
+Compare the multi-precision-integers number @var{u} with the unsigned
+integer @var{v} returning 0 for equality, a positive value for @var{u} >
+@var{v} and a negative for @var{u} < @var{v}.
+@end deftypefun
+
+@deftypefun int gcry_mpi_is_neg (@w{const gcry_mpi_t @var{a}})
+
+Return 1 if @var{a} is less than zero; return 0 if zero or positive.
+@end deftypefun
+
+
+@node Bit manipulations
+@section Bit manipulations
+
+@noindent
+There are a couple of functions to get information on arbitrary bits
+in an MPI and to set or clear them:
+
+@deftypefun {unsigned int} gcry_mpi_get_nbits (@w{gcry_mpi_t @var{a}})
+
+Return the number of bits required to represent @var{a}.
+@end deftypefun
+
+@deftypefun int gcry_mpi_test_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Return true if bit number @var{n} (counting from 0) is set in @var{a}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_set_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Set bit number @var{n} in @var{a}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_clear_bit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Clear bit number @var{n} in @var{a}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_set_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Set bit number @var{n} in @var{a} and clear all bits greater than @var{n}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_clear_highbit (@w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Clear bit number @var{n} in @var{a} and all bits greater than @var{n}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_rshift (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Shift the value of @var{a} by @var{n} bits to the right and store the
+result in @var{x}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_lshift (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
+
+Shift the value of @var{a} by @var{n} bits to the left and store the
+result in @var{x}.
+@end deftypefun
+
+@node EC functions
+@section EC functions
+
+@noindent
+Libgcrypt provides an API to access low level functions used by its
+elliptic curve implementation.  These functions allow to implement
+elliptic curve methods for which no explicit support is available.
+
+@deftypefun gcry_mpi_point_t gcry_mpi_point_new (@w{unsigned int @var{nbits}})
+
+Allocate a new point object, initialize it to 0, and allocate enough
+memory for a points of at least @var{nbits}.  This pre-allocation
+yields only a small performance win and is not really necessary
+because Libgcrypt automatically re-allocates the required memory.
+Using 0 for @var{nbits} is usually the right thing to do.
+@end deftypefun
+
+@deftypefun void gcry_mpi_point_release (@w{gcry_mpi_point_t @var{point}})
+
+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}})
+
+Store the projective coordinates from @var{point} into the MPIs
+@var{x}, @var{y}, and @var{z}.  If a coordinate is not required,
+@code{NULL} may be used for @var{x}, @var{y}, or @var{z}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_point_snatch_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}})
+
+Store the projective coordinates from @var{point} into the MPIs
+@var{x}, @var{y}, and @var{z}.  If a coordinate is not required,
+@code{NULL} may be used for @var{x}, @var{y}, or @var{z}.  The object
+@var{point} is then released.  Using this function instead of
+@code{gcry_mpi_point_get} and @code{gcry_mpi_point_release} has the
+advantage of avoiding some extra memory allocations and copies.
+@end deftypefun
+
+@deftypefun gcry_mpi_point_t gcry_mpi_point_set ( @
+ @w{gcry_mpi_point_t @var{point}}, @
+ @w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{y}}, @w{gcry_mpi_t @var{z}})
+
+Store the projective coordinates from @var{x}, @var{y}, and @var{z}
+into @var{point}.  If a coordinate is given as @code{NULL}, the value
+0 is used.  If @code{NULL} is used for @var{point} a new point object
+is allocated and returned.  Returns @var{point} or the newly allocated
+point object.
+@end deftypefun
+
+@deftypefun gcry_mpi_point_t gcry_mpi_point_snatch_set ( @
+ @w{gcry_mpi_point_t @var{point}}, @
+ @w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{y}}, @w{gcry_mpi_t @var{z}})
+
+Store the projective coordinates from @var{x}, @var{y}, and @var{z}
+into @var{point}.  If a coordinate is given as @code{NULL}, the value
+0 is used.  If @code{NULL} is used for @var{point} a new point object
+is allocated and returned.  The MPIs @var{x}, @var{y}, and @var{z} are
+released.  Using this function instead of @code{gcry_mpi_point_set}
+and 3 calls to @code{gcry_mpi_release} has the advantage of avoiding
+some extra memory allocations and copies.  Returns @var{point} or the
+newly allocated point object.
+@end deftypefun
+
+@anchor{gcry_mpi_ec_new}
+@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
+@var{keyparam} is given it specifies the parameters of the curve
+(@pxref{ecc_keyparam}).  If @var{curvename} is given in addition to
+@var{keyparam} and the key parameters do not include a named curve
+reference, the string @var{curvename} is used to fill in missing
+parameters.  If only @var{curvename} is given, the context is
+initialized for this named curve.
+
+If a parameter specifying a point (e.g. @code{g} or @code{q}) is not
+found, the parser looks for a non-encoded point by appending
+@code{.x}, @code{.y}, and @code{.z} to the parameter name and looking
+them all up to create a point.  A parameter with the suffix @code{.z}
+is optional and defaults to 1.
+
+On success the function returns 0 and stores the new context object at
+@var{r_ctx}; this object eventually needs to be released
+(@pxref{gcry_ctx_release}).  On error the function stores @code{NULL} at
+@var{r_ctx} and returns an error code.
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_mpi_ec_get_mpi ( @
+ @w{const char *@var{name}}, @w{gcry_ctx_t @var{ctx}}, @w{int @var{copy}})
+
+Return the MPI with @var{name} from the context @var{ctx}.  If not
+found @code{NULL} is returned.  If the returned MPI may later be
+modified, it is suggested to pass @code{1} to @var{copy}, so that the
+function guarantees that a modifiable copy of the MPI is returned.  If
+@code{0} is used for @var{copy}, this function may return a constant
+flagged MPI.  In any case @code{gcry_mpi_release} needs to be called
+to release the result.  For valid names @ref{ecc_keyparam}.  If the
+public key @code{q} is requested but only the private key @code{d} is
+available, @code{q} will be recomputed on the fly.  If a point
+parameter is requested it is returned as an uncompressed
+encoded point unless these special names are used:
+@table @var
+@item q@@eddsa
+Return an EdDSA style compressed point.  This is only supported for
+Twisted Edwards curves.
+@end table
+@end deftypefun
+
+@deftypefun gcry_mpi_point_t gcry_mpi_ec_get_point ( @
+ @w{const char *@var{name}}, @w{gcry_ctx_t @var{ctx}}, @w{int @var{copy}})
+
+Return the point with @var{name} from the context @var{ctx}.  If not
+found @code{NULL} is returned.  If the returned MPI may later be
+modified, it is suggested to pass @code{1} to @var{copy}, so that the
+function guarantees that a modifiable copy of the MPI is returned.  If
+@code{0} is used for @var{copy}, this function may return a constant
+flagged point.  In any case @code{gcry_mpi_point_release} needs to be
+called to release the result.  If the public key @code{q} is requested
+but only the private key @code{d} is available, @code{q} will be
+recomputed on the fly.
+@end deftypefun
+
+@deftypefun gpg_error_t gcry_mpi_ec_set_mpi ( @
+ @w{const char *@var{name}}, @w{gcry_mpi_t @var{newvalue}}, @
+ @w{gcry_ctx_t @var{ctx}})
+
+Store the MPI @var{newvalue} at @var{name} into the context @var{ctx}.
+On success @code{0} is returned; on error an error code.  Valid names
+are the MPI parameters of an elliptic curve (@pxref{ecc_keyparam}).
+@end deftypefun
+
+@deftypefun gpg_error_t gcry_mpi_ec_set_point ( @
+ @w{const char *@var{name}}, @w{gcry_mpi_point_t @var{newvalue}}, @
+ @w{gcry_ctx_t @var{ctx}})
+
+Store the point @var{newvalue} at @var{name} into the context
+@var{ctx}.  On success @code{0} is returned; on error an error code.
+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}})
+
+Compute the affine coordinates from the projective coordinates in
+@var{point} and store them into @var{x} and @var{y}.  If one
+coordinate is not required, @code{NULL} may be passed to @var{x} or
+@var{y}.  @var{ctx} is the context object which has been created using
+@code{gcry_mpi_ec_new}. Returns 0 on success or not 0 if @var{point}
+is at infinity.
+
+Note that you can use @code{gcry_mpi_ec_set_point} with the value
+@code{GCRYMPI_CONST_ONE} for @var{z} to convert affine coordinates
+back into projective coordinates.
+
+@end deftypefun
+
+@deftypefun void gcry_mpi_ec_dup ( @
+ @w{gcry_mpi_point_t @var{w}}, @w{gcry_mpi_point_t @var{u}}, @
+ @w{gcry_ctx_t @var{ctx}})
+
+Double the point @var{u} of the elliptic curve described by @var{ctx}
+and store the result into @var{w}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_ec_add ( @
+ @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}})
+
+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}})
+
+Multiply the point @var{u} of the elliptic curve described by
+@var{ctx} by @var{n} and store the result into @var{w}.
+@end deftypefun
+
+@deftypefun int gcry_mpi_ec_curve_point ( @
+ @w{gcry_mpi_point_t @var{point}}, @w{gcry_ctx_t @var{ctx}})
+
+Return true if @var{point} is on the elliptic curve described by
+@var{ctx}.
+@end deftypefun
+
+
+@node Miscellaneous
+@section Miscellaneous
+
+An MPI data type is allowed to be ``misused'' to store an arbitrary
+value.  Two functions implement this kludge:
+
+@deftypefun gcry_mpi_t gcry_mpi_set_opaque (@w{gcry_mpi_t @var{a}}, @w{void *@var{p}}, @w{unsigned int @var{nbits}})
+
+Store @var{nbits} of the value @var{p} points to in @var{a} and mark
+@var{a} as an opaque value (i.e. an value that can't be used for any
+math calculation and is only used to store an arbitrary bit pattern in
+@var{a}).  Ownership of @var{p} is taken by this function and thus the
+user may not use dereference the passed value anymore.  It is required
+that them memory referenced by @var{p} has been allocated in a way
+that @code{gcry_free} is able to release it.
+
+WARNING: Never use an opaque MPI for actual math operations.  The only
+valid functions are gcry_mpi_get_opaque and gcry_mpi_release.  Use
+gcry_mpi_scan to convert a string of arbitrary bytes into an MPI.
+@end deftypefun
+
+@deftypefun gcry_mpi_t gcry_mpi_set_opaque_copy (@w{gcry_mpi_t @var{a}}, @w{const void *@var{p}}, @w{unsigned int @var{nbits}})
+
+Same as @code{gcry_mpi_set_opaque} but ownership of @var{p} is not
+taken instead a copy of @var{p} is used.
+@end deftypefun
+
+
+@deftypefun {void *} gcry_mpi_get_opaque (@w{gcry_mpi_t @var{a}}, @w{unsigned int *@var{nbits}})
+
+Return a pointer to an opaque value stored in @var{a} and return its
+size in @var{nbits}.  Note that the returned pointer is still owned by
+@var{a} and that the function should never be used for an non-opaque
+MPI.
+@end deftypefun
+
+Each MPI has an associated set of flags for special purposes.  The
+currently defined flags are:
+
+@table @code
+@item GCRYMPI_FLAG_SECURE
+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
+integer is stored.  This is an read-only flag; it may not be set or
+cleared.
+@item GCRYMPI_FLAG_IMMUTABLE
+If this flag is set, the MPI is marked as immutable.  Setting or
+changing the value of that MPI is ignored and an error message is
+logged.  The flag is sometimes useful for debugging.
+@item GCRYMPI_FLAG_CONST
+If this flag is set, the MPI is marked as a constant and as immutable
+Setting or changing the value of that MPI is ignored and an error
+message is logged.  Such an MPI will never be deallocated and may thus
+be used without copying.  Note that using gcry_mpi_copy will return a
+copy of that constant with this and the immutable flag cleared.  A few
+commonly used constants are pre-defined and accessible using the
+macros @code{GCRYMPI_CONST_ONE}, @code{GCRYMPI_CONST_TWO},
+@code{GCRYMPI_CONST_THREE}, @code{GCRYMPI_CONST_FOUR}, and
+@code{GCRYMPI_CONST_EIGHT}.
+@item GCRYMPI_FLAG_USER1
+@itemx GCRYMPI_FLAG_USER2
+@itemx GCRYMPI_FLAG_USER3
+@itemx GCRYMPI_FLAG_USER4
+These flags are reserved for use by the application.
+@end table
+
+@deftypefun void gcry_mpi_set_flag (@w{gcry_mpi_t @var{a}}, @
+ @w{enum gcry_mpi_flag @var{flag}})
+
+Set the @var{flag} for the MPI @var{a}.  The only allowed flags are
+@code{GCRYMPI_FLAG_SECURE}, @code{GCRYMPI_FLAG_IMMUTABLE}, and
+@code{GCRYMPI_FLAG_CONST}.
+@end deftypefun
+
+@deftypefun void gcry_mpi_clear_flag (@w{gcry_mpi_t @var{a}}, @
+ @w{enum gcry_mpi_flag @var{flag}})
+
+Clear @var{flag} for the multi-precision-integers @var{a}.  The only
+allowed flag is @code{GCRYMPI_FLAG_IMMUTABLE} but only if
+@code{GCRYMPI_FLAG_CONST} is not set.  If @code{GCRYMPI_FLAG_CONST} is
+set, clearing @code{GCRYMPI_FLAG_IMMUTABLE} will simply be ignored.
+@end deftypefun
+o
+@deftypefun int gcry_mpi_get_flag (@w{gcry_mpi_t @var{a}}, @
+ @w{enum gcry_mpi_flag @var{flag}})
+
+Return true if @var{flag} is set for @var{a}.
+@end deftypefun
+
+
+To put a random value into an MPI, the following convenience function
+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 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
+@code{GCRY_WEAK_RANDOM} this function makes use of
+@code{gcry_create_nonce}.
+@end deftypefun
+
+@c **********************************************************
+@c ******************** Prime numbers ***********************
+@c **********************************************************
+@node Prime numbers
+@chapter Prime numbers
+
+@menu
+* Generation::                  Generation of new prime numbers.
+* Checking::                    Checking if a given number is prime.
+@end menu
+
+@node Generation
+@section Generation
+
+@deftypefun gcry_error_t gcry_prime_generate (gcry_mpi_t *@var{prime},unsigned int @var{prime_bits}, unsigned int @var{factor_bits}, gcry_mpi_t **@var{factors}, gcry_prime_check_func_t @var{cb_func}, void *@var{cb_arg}, gcry_random_level_t @var{random_level}, unsigned int @var{flags})
+
+Generate a new prime number of @var{prime_bits} bits and store it in
+@var{prime}.  If @var{factor_bits} is non-zero, one of the prime factors
+of (@var{prime} - 1) / 2 must be @var{factor_bits} bits long.  If
+@var{factors} is non-zero, allocate a new, @code{NULL}-terminated array
+holding the prime factors and store it in @var{factors}.  @var{flags}
+might be used to influence the prime number generation process.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_prime_group_generator (gcry_mpi_t *@var{r_g}, gcry_mpi_t @var{prime}, gcry_mpi_t *@var{factors}, gcry_mpi_t @var{start_g})
+
+Find a generator for @var{prime} where the factorization of
+(@var{prime}-1) is in the @code{NULL} terminated array @var{factors}.
+Return the generator as a newly allocated MPI in @var{r_g}.  If
+@var{start_g} is not NULL, use this as the start for the search.
+@end deftypefun
+
+@deftypefun void gcry_prime_release_factors (gcry_mpi_t *@var{factors})
+
+Convenience function to release the @var{factors} array.
+@end deftypefun
+
+@node Checking
+@section Checking
+
+@deftypefun gcry_error_t gcry_prime_check (gcry_mpi_t @var{p}, unsigned int @var{flags})
+
+Check whether the number @var{p} is prime.  Returns zero in case @var{p}
+is indeed a prime, returns @code{GPG_ERR_NO_PRIME} in case @var{p} is
+not a prime and a different error code in case something went horribly
+wrong.
+@end deftypefun
+
+@c **********************************************************
+@c ******************** Utilities ***************************
+@c **********************************************************
+@node Utilities
+@chapter Utilities
+
+@menu
+* 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
+
+
+@node Memory allocation
+@section Memory allocation
+
+@deftypefun {void *} gcry_malloc (size_t @var{n})
+
+This function tries to allocate @var{n} bytes of memory.  On success
+it returns a pointer to the memory area, in an out-of-core condition,
+it returns NULL.
+@end deftypefun
+
+@deftypefun {void *} gcry_malloc_secure (size_t @var{n})
+Like @code{gcry_malloc}, but uses secure memory.
+@end deftypefun
+
+@deftypefun {void *} gcry_calloc (size_t @var{n}, size_t @var{m})
+
+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}, size_t @var{m})
+Like @code{gcry_calloc}, but uses secure memory.
+@end deftypefun
+
+@deftypefun {void *} gcry_realloc (void *@var{p}, size_t @var{n})
+
+This function tries to resize the memory area pointed to by @var{p} to
+@var{n} bytes.  On success it returns a pointer to the new memory
+area, in an out-of-core condition, it returns NULL.  Depending on
+whether the memory pointed to by @var{p} is secure memory or not,
+gcry_realloc tries to use secure memory as well.
+@end deftypefun
+
+@deftypefun void gcry_free (void *@var{p})
+Release the memory area pointed to by @var{p}.
+@end deftypefun
+
+
+@node Context management
+@section Context management
+
+Some function make use of a context object.  As of now there are only
+a few math functions. However, future versions of Libgcrypt may make
+more use of this context object.
+
+@deftp {Data type} {gcry_ctx_t}
+This type is used to refer to the general purpose context object.
+@end deftp
+
+@anchor{gcry_ctx_release}
+@deftypefun void gcry_ctx_release (gcry_ctx_t @var{ctx})
+Release the context object @var{ctx} and all associated resources.  A
+@code{NULL} passed as @var{ctx} is ignored.
+@end deftypefun
+
+@node Buffer description
+@section Buffer description
+
+To help hashing non-contiguous areas of memory a general purpose data
+type is defined:
+
+@deftp {Data type} {gcry_buffer_t}
+This type is a structure to describe a buffer.  The user should make
+sure that this structure is initialized to zero.  The available fields
+of this structure are:
+
+@table @code
+  @item .size
+  This is either 0 for no information available or indicates the
+  allocated length of the buffer.
+  @item .off
+  This is the offset into the buffer.
+  @item .len
+  This is the valid length of the buffer starting at @code{.off}.
+  @item .data
+  This is the address of the buffer.
+  @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 **********************************************************
+@c *********************  Tools  ****************************
+@c **********************************************************
+@node Tools
+@chapter Tools
+
+@menu
+* hmac256:: A standalone HMAC-SHA-256 implementation
+@end menu
+
+@manpage hmac256.1
+@node hmac256
+@section A HMAC-SHA-256 tool
+@ifset manverb
+.B hmac256
+\- Compute an HMAC-SHA-256 MAC
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B  hmac256
+.RB [ \-\-binary ]
+.I key
+.I [FILENAME]
+@end ifset
+
+@mansect description
+This is a standalone HMAC-SHA-256 implementation used to compute an
+HMAC-SHA-256 message authentication code.  The tool has originally
+been developed as a second implementation for Libgcrypt to allow
+comparing against the primary implementation and to be used for
+internal consistency checks.  It should not be used for sensitive data
+because no mechanisms to clear the stack etc are used.
+
+The code has been written in a highly portable manner and requires
+only a few standard definitions to be provided in a config.h file.
+
+@noindent
+@command{hmac256} is commonly invoked as
+
+@example
+hmac256 "This is my key" foo.txt
+@end example
+
+@noindent
+This compute the MAC on the file @file{foo.txt} using the key given on
+the command line.
+
+@mansect options
+@noindent
+@command{hmac256} understands these options:
+
+@table @gnupgtabopt
+
+@item --binary
+Print the MAC as a binary string.  The default is to print the MAC
+encoded has lower case hex digits.
+
+@item --version
+Print version of the program and exit.
+
+@end table
+
+@mansect see also
+@ifset isman
+@command{sha256sum}(1)
+@end ifset
+@manpause
+
+@c **********************************************************
+@c ****************  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
+@chapter Architecture
+
+This chapter describes the internal architecture of Libgcrypt.
+
+Libgcrypt is a function library written in ISO C-90.  Any compliant
+compiler should be able to build Libgcrypt as long as the target is
+either a POSIX platform or compatible to the API used by Windows NT.
+Provisions have been take so that the library can be directly used from
+C++ applications; however building with a C++ compiler is not supported.
+
+Building Libgcrypt is done by using the common @code{./configure && make}
+approach.  The configure command is included in the source distribution
+and as a portable shell script it works on any Unix-alike system.  The
+result of running the configure script are a C header file
+(@file{config.h}), customized Makefiles, the setup of symbolic links and
+a few other things.  After that the make tool builds and optionally
+installs the library and the documentation.  See the files
+@file{INSTALL} and @file{README} in the source distribution on how to do
+this.
+
+Libgcrypt is developed using a Subversion@footnote{A version control
+system available for many platforms} repository.  Although all released
+versions are tagged in this repository, they should not be used to build
+production versions of Libgcrypt.  Instead released tarballs should be
+used.  These tarballs are available from several places with the master
+copy at @indicateurl{ftp://ftp.gnupg.org/gcrypt/libgcrypt/}.
+Announcements of new releases are posted to the
+@indicateurl{gnupg-announce@@gnupg.org} mailing list@footnote{See
+@url{http://www.gnupg.org/documentation/mailing-lists.en.html} for
+details.}.
+
+
+@float Figure,fig:subsystems
+@caption{Libgcrypt subsystems}
+@center @image{libgcrypt-modules, 150mm,,Libgcrypt subsystems}
+@end float
+
+Libgcrypt consists of several subsystems (@pxref{fig:subsystems}) and
+all these subsystems provide a public API; this includes the helper
+subsystems like the one for S-expressions.  The API style depends on the
+subsystem; in general an open-use-close approach is implemented.  The
+open returns a handle to a context used for all further operations on
+this handle, several functions may then be used on this handle and a
+final close function releases all resources associated with the handle.
+
+@menu
+* Public-Key Subsystem Architecture::              About public keys.
+* Symmetric Encryption Subsystem Architecture::    About standard ciphers.
+* Hashing and MACing Subsystem Architecture::      About hashing.
+* Multi-Precision-Integer Subsystem Architecture:: About big integers.
+* Prime-Number-Generator Subsystem Architecture::  About prime numbers.
+* Random-Number Subsystem Architecture::           About random stuff.
+@c * Helper Subsystems Architecture::                 About other stuff.
+@end menu
+
+
+
+@node Public-Key Subsystem Architecture
+@section Public-Key Architecture
+
+Because public key cryptography is almost always used to process small
+amounts of data (hash values or session keys), the interface is not
+implemented using the open-use-close paradigm, but with single
+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 @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
+following main functions are available:
+
+@table @code
+
+@item gcry_pk_encrypt
+Encrypt data using a public key.
+
+@item gcry_pk_decrypt
+Decrypt data using a private key.
+
+@item gcry_pk_sign
+Sign data using a private key.
+
+@item gcry_pk_verify
+Verify that a signature matches the data.
+
+@item gcry_pk_testkey
+Perform a consistency over a public or private key.
+
+@item gcry_pk_genkey
+Create a new public/private key pair.
+
+@end table
+
+All these functions
+lookup the module implementing the algorithm and pass the actual work
+to that module.  The parsing of the S-expression input and the
+construction of S-expression for the return values is done by the high
+level code (@file{cipher/pubkey.c}).  Thus the internal interface
+between the algorithm modules and the high level functions passes data
+in a custom format.
+
+By default Libgcrypt uses a blinding technique for RSA decryption to
+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_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.
+
+
+
+@node Symmetric Encryption Subsystem Architecture
+@section Symmetric Encryption Subsystem Architecture
+
+The interface to work with symmetric encryption algorithms is made up
+of functions from the @code{gcry_cipher_} name space.  The
+implementation follows the open-use-close paradigm and uses registered
+algorithm modules for the actual work.  Unless a module implements
+optimized cipher mode implementations, the high level code
+(@file{cipher/cipher.c}) implements the modes and calls the core
+algorithm functions to process each block.
+
+The most important functions are:
+
+@table @code
+
+@item gcry_cipher_open
+Create a new instance to encrypt or decrypt using a specified
+algorithm and mode.
+
+@item gcry_cipher_close
+Release an instance.
+
+@item gcry_cipher_setkey
+Set a key to be used for encryption or decryption.
+
+@item gcry_cipher_setiv
+Set an initialization vector to be used for encryption or decryption.
+
+@item gcry_cipher_encrypt
+@itemx gcry_cipher_decrypt
+Encrypt or decrypt data.  These functions may be called with arbitrary
+amounts of data and as often as needed to encrypt or decrypt all data.
+
+@end table
+
+There are also functions to query properties of algorithms or context,
+like block length, key length, map names or to enable features like
+padding methods.
+
+
+
+@node Hashing and MACing Subsystem Architecture
+@section Hashing and MACing Subsystem Architecture
+
+The interface to work with message digests and CRC algorithms is made
+up of functions from the @code{gcry_md_} name space.  The
+implementation follows the open-use-close paradigm and uses registered
+algorithm modules for the actual work.  Although CRC algorithms are
+not considered cryptographic hash algorithms, they share enough
+properties so that it makes sense to handle them in the same way.
+It is possible to use several algorithms at once with one context and
+thus compute them all on the same data.
+
+The most important functions are:
+
+@table @code
+@item gcry_md_open
+Create a new message digest instance and optionally enable one
+algorithm.  A flag may be used to turn the message digest algorithm
+into a HMAC algorithm.
+
+@item gcry_md_enable
+Enable an additional algorithm for the instance.
+
+@item gcry_md_setkey
+Set the key for the MAC.
+
+@item gcry_md_write
+Pass more data for computing the message digest to an instance.
+
+@item gcry_md_putc
+Buffered version of @code{gcry_md_write} implemented as a macro.
+
+@item gcry_md_read
+Finalize the computation of the message digest or HMAC and return the
+result.
+
+@item gcry_md_close
+Release an instance
+
+@item gcry_md_hash_buffer
+Convenience function to directly compute a message digest over a
+memory buffer without the need to create an instance first.
+
+@end table
+
+There are also functions to query properties of algorithms or the
+instance, like enabled algorithms, digest length, map algorithm names.
+it is also possible to reset an instance or to copy the current state
+of an instance at any time.  Debug functions to write the hashed data
+to files are available as well.
+
+
+
+@node Multi-Precision-Integer Subsystem Architecture
+@section Multi-Precision-Integer Subsystem Architecture
+
+The implementation of Libgcrypt's big integer computation code is
+based on an old release of GNU Multi-Precision Library (GMP).  The
+decision not to use the GMP library directly was due to stalled
+development at that time and due to security requirements which could
+not be provided by the code in GMP.  As GMP does, Libgcrypt provides
+high performance assembler implementations of low level code for
+several CPUS to gain much better performance than with a generic C
+implementation.
+
+@noindent
+Major features of Libgcrypt's multi-precision-integer code compared to
+GMP are:
+
+@itemize
+@item
+Avoidance of stack based allocations to allow protection against
+swapping out of sensitive data and for easy zeroing of sensitive
+intermediate results.
+
+@item
+Optional use of secure memory and tracking of its use so that results
+are also put into secure memory.
+
+@item
+MPIs are identified by a handle (implemented as a pointer) to give
+better control over allocations and to augment them with extra
+properties like opaque data.
+
+@item
+Removal of unnecessary code to reduce complexity.
+
+@item
+Functions specialized for public key cryptography.
+
+@end itemize
+
+
+
+@node Prime-Number-Generator Subsystem Architecture
+@section Prime-Number-Generator Subsystem Architecture
+
+Libgcrypt provides an interface to its prime number generator.  These
+functions make use of the internal prime number generator which is
+required for the generation for public key key pairs.  The plain prime
+checking function is exported as well.
+
+The generation of random prime numbers is based on the Lim and Lee
+algorithm to create practically save primes.@footnote{Chae Hoon Lim
+and Pil Joong Lee. A key recovery attack on discrete log-based schemes
+using a prime order subgroup. In Burton S. Kaliski Jr., editor,
+Advances in Cryptology: Crypto '97, pages 249-263, Berlin /
+Heidelberg / New York, 1997. Springer-Verlag.  Described on page 260.}
+This algorithm creates a pool of smaller primes, select a few of them
+to create candidate primes of the form @math{2 * p_0 * p_1 * ... * p_n
++ 1}, tests the candidate for primality and permutates the pool until
+a prime has been found.  It is possible to clamp one of the small
+primes to a certain size to help DSA style algorithms.  Because most
+of the small primes in the pool are not used for the resulting prime
+number, they are saved for later use (see @code{save_pool_prime} and
+@code{get_pool_prime} in @file{cipher/primegen.c}).  The prime
+generator optionally supports the finding of an appropriate generator.
+
+@noindent
+The primality test works in three steps:
+
+@enumerate
+@item
+The standard sieve algorithm using the primes up to 4999 is used as a
+quick first check.
+
+@item
+A Fermat test filters out almost all non-primes.
+
+@item
+A 5 round Rabin-Miller test is finally used.  The first round uses a
+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
+
+Libgcrypt provides 3 levels or random quality: The level
+@code{GCRY_VERY_STRONG_RANDOM} usually used for key generation, the
+level @code{GCRY_STRONG_RANDOM} for all other strong random
+requirements and the function @code{gcry_create_nonce} which is used
+for weaker usages like nonces.  There is also a level
+@code{GCRY_WEAK_RANDOM} which in general maps to
+@code{GCRY_STRONG_RANDOM} except when used with the function
+@code{gcry_mpi_randomize}, where it randomizes an
+multi-precision-integer using the @code{gcry_create_nonce} function.
+
+@noindent
+There are two distinct random generators available:
+
+@itemize
+@item
+The Continuously Seeded Pseudo Random Number Generator (CSPRNG), which
+is based on the classic GnuPG derived big pool implementation.
+Implemented in @code{random/random-csprng.c} and used by default.
+@item
+A FIPS approved ANSI X9.31 PRNG using AES with a 128 bit key. Implemented in
+@code{random/random-fips.c} and used if Libgcrypt is in FIPS mode.
+@end itemize
+
+@noindent
+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.  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
+like virtual machine and process statistics.  It is a kind of
+poor-man's @code{/dev/random} implementation. It is not available in
+FIPS mode.
+
+@item rndegd
+Uses the operating system provided Entropy Gathering Daemon (EGD).
+The EGD basically uses the same algorithms as rndunix does.  However
+as a system daemon it keeps on running and thus can serve several
+processes requiring entropy input and does not waste collected entropy
+if the application does not need all the collected entropy. It is not
+available in FIPS mode.
+
+@item rndw32
+Targeted for the Microsoft Windows OS.  It uses certain properties of
+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 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
+
+
+@menu
+* CSPRNG Description::      Description of the CSPRNG.
+* FIPS PRNG Description::   Description of the FIPS X9.31 PRNG.
+@end menu
+
+
+@node CSPRNG Description
+@subsection Description of the CSPRNG
+
+This random number generator is loosely modelled after the one
+described in Peter Gutmann's paper: "Software Generation of
+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 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
+file and initially seed form a file.
+
+Depending on how Libgcrypt was build the generator is able to select
+the best working entropy gathering module.  It makes use of the slow
+and fast collection methods and requires the pool to initially seeded
+form the slow gatherer or a seed file.  An entropy estimation is used
+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 implementation needs a more verbose description.
+
+The implementation of the nonce generator (for
+@code{gcry_create_nonce}) is a straightforward repeated hash design: A
+28 byte buffer is initially seeded with the PID and the time in
+seconds in the first 20 bytes and with 8 bytes of random taken from
+the @code{GCRY_STRONG_RANDOM} generator.  Random numbers are then
+created by hashing all the 28 bytes with SHA-1 and saving that again
+in the first 20 bytes.  The hash is also returned as result.
+
+
+@node FIPS PRNG Description
+@subsection Description of the FIPS X9.31 PRNG
+
+The core of this deterministic random number generator is implemented
+according to the document ``NIST-Recommended Random Number Generator
+Based on ANSI X9.31 Appendix A.2.4 Using the 3-Key Triple DES and AES
+Algorithms'', dated 2005-01-31.  This implementation uses the AES
+variant.
+
+The generator is based on contexts to utilize the same core functions
+for all random levels as required by the high-level interface.  All
+random generators return their data in 128 bit blocks.  If the caller
+requests less bits, the extra bits are not used.  The key for each
+generator is only set once at the first time a generator context is
+used.  The seed value is set along with the key and again after 1000
+output blocks.
+
+On Unix like systems the @code{GCRY_VERY_STRONG_RANDOM} and
+@code{GCRY_STRONG_RANDOM} generators are keyed and seeded using the
+rndlinux module with the @file{/dev/random} device. Thus these
+generators may block until the OS kernel has collected enough entropy.
+When used with Microsoft Windows the rndw32 module is used instead.
+
+The generator used for @code{gcry_create_nonce} is keyed and seeded
+from the @code{GCRY_STRONG_RANDOM} generator.  Thus is may also block
+if the @code{GCRY_STRONG_RANDOM} generator has not yet been used
+before and thus gets initialized on the first use by
+@code{gcry_create_nonce}.  This special treatment is justified by the
+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
+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 stuck generator.
+
+The DT value for the generator is made up of the current time down to
+microseconds (if available) and a free running 64 bit counter.  When
+used with the test context the DT value is taken from the context and
+incremented on each use.
+
+@c @node Helper Subsystems Architecture
+@c @section Helper Subsystems Architecture
+@c
+@c There are a few smaller subsystems which are mainly used internally by
+@c Libgcrypt but also available to applications.
+@c
+@c @menu
+@c * S-expression Subsystem Architecture::   Details about the S-expression architecture.
+@c * Memory Subsystem Architecture::         Details about the memory allocation architecture.
+@c * Miscellaneous Subsystems Architecture:: Details about other subsystems.
+@c @end menu
+@c
+@c @node S-expression Subsystem Architecture
+@c @subsection S-expression Subsystem Architecture
+@c
+@c Libgcrypt provides an interface to S-expression to create and parse
+@c them.  To use an S-expression with Libgcrypt it needs first be
+@c converted into the internal representation used by Libgcrypt (the type
+@c @code{gcry_sexp_t}).  The conversion functions support a large subset
+@c of the S-expression specification and further feature a printf like
+@c function to convert a list of big integers or other binary data into
+@c an S-expression.
+@c
+@c Libgcrypt currently implements S-expressions using a tagged linked
+@c list.  However this is not exposed to an application and may be
+@c changed in future releases to reduce overhead when already working
+@c with canonically encoded S-expressions.  Secure memory is supported by
+@c this S-expressions implementation.
+@c
+@c @node Memory Subsystem Architecture
+@c @subsection Memory Subsystem Architecture
+@c
+@c TBD.
+@c
+@c
+@c @node Miscellaneous Subsystems Architecture
+@c @subsection Miscellaneous Subsystems Architecture
+@c
+@c TBD.
+@c
+@c
+
+
+
+@c **********************************************************
+@c *******************  Appendices  *************************
+@c **********************************************************
+
+@c ********************************************
+@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 original random value.  The encrypted result is then
+decrypted and checked that it matches 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 condition 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
+
+No code is loaded at runtime.
+
+@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
+@item
+The cryptographic algorithms are restricted to this list:
+
+@table @asis
+@item GCRY_CIPHER_3DES
+3 key EDE Triple-DES symmetric encryption.
+@item GCRY_CIPHER_AES128
+AES 128 bit symmetric encryption.
+@item GCRY_CIPHER_AES192
+AES 192 bit symmetric encryption.
+@item GCRY_CIPHER_AES256
+AES 256 bit symmetric encryption.
+@item GCRY_MD_SHA1
+SHA-1 message digest.
+@item GCRY_MD_SHA224
+SHA-224 message digest.
+@item GCRY_MD_SHA256
+SHA-256 message digest.
+@item GCRY_MD_SHA384
+SHA-384 message digest.
+@item GCRY_MD_SHA512
+SHA-512 message digest.
+@item GCRY_MD_SHA1,GCRY_MD_FLAG_HMAC
+HMAC using a SHA-1 message digest.
+@item GCRY_MD_SHA224,GCRY_MD_FLAG_HMAC
+HMAC using a SHA-224 message digest.
+@item GCRY_MD_SHA256,GCRY_MD_FLAG_HMAC
+HMAC using a SHA-256 message digest.
+@item GCRY_MD_SHA384,GCRY_MD_FLAG_HMAC
+HMAC using a SHA-384 message digest.
+@item GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC
+HMAC using a SHA-512 message digest.
+@item GCRY_PK_RSA
+RSA encryption and signing.
+@item GCRY_PK_DSA
+DSA signing.
+@end table
+
+Note that the CRC algorithms are not considered cryptographic algorithms
+and thus are in addition available.
+
+@item
+RSA key generation refuses to create a key with a keysize of
+less than 1024 bits.
+
+@item
+DSA key generation refuses to create a key with a keysize other
+than 1024 bits.
+
+@item
+The @code{transient-key} flag for RSA and DSA key generation is ignored.
+
+@item
+Support for the VIA Padlock engine is disabled.
+
+@item
+FIPS mode may only be used on systems with a /dev/random device.
+Switching into FIPS mode on other systems will fail at runtime.
+
+@item
+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
+Message digest debugging is disabled.
+
+@item
+All debug output related to cryptographic data is suppressed.
+
+@item
+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 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 ********************************************
+@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
+transitions (@pxref{tbl:fips-state-transitions}) may happen.
+
+@float Figure,fig:fips-fsm
+@caption{FIPS mode state diagram}
+@center @image{fips-fsm,150mm,,FIPS FSM Diagram}
+@end float
+
+@float Table,tbl:fips-states
+@caption{FIPS mode states}
+@noindent
+States used by the FIPS FSM:
+@table @asis
+
+@item Power-Off
+Libgcrypt is not runtime linked to another application.  This usually
+means that the library is not loaded into main memory.  This state is
+documentation only.
+
+@item Power-On
+Libgcrypt is loaded into memory and API calls may be made.  Compiler
+introduced constructor functions may be run.  Note that Libgcrypt does
+not implement any arbitrary constructor functions to be called by the
+operating system
+
+@item Init
+The Libgcrypt initialization functions are performed and the library has
+not yet run any self-test.
+
+@item Self-Test
+Libgcrypt is performing self-tests.
+
+@item Operational
+Libgcrypt is in the operational state and all interfaces may be used.
+
+@item Error
+Libgrypt is in the error state.  When calling any FIPS relevant
+interfaces they either return an error (@code{GPG_ERR_NOT_OPERATIONAL})
+or put Libgcrypt into the Fatal-Error state and won't return.
+
+@item Fatal-Error
+Libgcrypt is in a non-recoverable error state and
+will automatically transit into the  Shutdown state.
+
+@item Shutdown
+Libgcrypt is about to be terminated and removed from the memory. The
+application may at this point still running cleanup handlers.
+
+@end table
+@end float
+
+
+@float Table,tbl:fips-state-transitions
+@caption{FIPS mode state transitions}
+@noindent
+The valid state transitions (@pxref{fig:fips-fsm}) are:
+@table @code
+@item 1
+Power-Off to Power-On is implicitly done by the OS loading Libgcrypt as
+a shared library and having it linked to an application.
+
+@item 2
+Power-On to Init is triggered by the application calling the
+Libgcrypt initialization function @code{gcry_check_version}.
+
+@item 3
+Init to Self-Test is either triggered by a dedicated API call or implicit
+by invoking a libgrypt service controlled by the FSM.
+
+@item 4
+Self-Test to Operational is triggered after all self-tests passed
+successfully.
+
+@item 5
+Operational to Shutdown is an artificial state without any direct action
+in Libgcrypt.  When reaching the Shutdown state the library is
+deinitialized and can't return to any other state again.
+
+@item 6
+Shutdown to Power-off is the process of removing Libgcrypt from the
+computer's memory.  For obvious reasons the Power-Off state can't be
+represented within Libgcrypt and thus this transition is for
+documentation only.
+
+@item 7
+Operational to Error is triggered if Libgcrypt detected an application
+error which can't be returned to the caller but still allows Libgcrypt
+to properly run.  In the Error state all FIPS relevant interfaces return
+an error code.
+
+@item 8
+Error to Shutdown is similar to the Operational to Shutdown transition
+(5).
+
+@item 9
+Error to Fatal-Error is triggered if Libgrypt detects an fatal error
+while already being in Error state.
+
+@item 10
+Fatal-Error to Shutdown is automatically entered by Libgcrypt
+after having reported the error.
+
+@item 11
+Power-On to Shutdown is an artificial state to document that Libgcrypt
+has not ye been initialized but the process is about to terminate.
+
+@item 12
+Power-On to Fatal-Error will be triggered if certain Libgcrypt functions
+are used without having reached the Init state.
+
+@item 13
+Self-Test to Fatal-Error is triggered by severe errors in Libgcrypt while
+running self-tests.
+
+@item 14
+Self-Test to Error is triggered by a failed self-test.
+
+@item 15
+Operational to Fatal-Error is triggered if Libcrypt encountered a
+non-recoverable error.
+
+@item 16
+Operational to Self-Test is triggered if the application requested to run
+the self-tests again.
+
+@item 17
+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 **********************************************************
+@include lgpl.texi
+
+@include gpl.texi
+
+@node Figures and Tables
+@unnumbered List of Figures and Tables
+
+@listoffloats Figure
+
+@listoffloats Table
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Function and Data Index
+@unnumbered Function and Data Index
+
+@printindex fn
+
+
+
+@bye
+
+GCRYCTL_SET_RANDOM_DAEMON_SOCKET
+GCRYCTL_USE_RANDOM_DAEMON
+The random daemon is still a bit experimental, thus we do not document
+them.  Note that they should be used during initialization and that
+these functions are not really thread safe.
+
+
+
+
+@c  LocalWords:  int HD
diff --git a/libotr/libgcrypt-1.8.7/doc/gpl.texi b/libotr/libgcrypt-1.8.7/doc/gpl.texi
new file mode 100644
index 0000000..6eb301e
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/gpl.texi
@@ -0,0 +1,392 @@
+@node Copying
+@unnumbered GNU General Public License
+
+@cindex GPL, GNU General Public License
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
+59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@heading Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software---to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+@iftex
+@heading TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate
+@item
+This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The ``Program'', below,
+refers to any such program or work, and a ``work based on the Program''
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term ``modification''.)  Each licensee is addressed as ``you''.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+@item
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+@item
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+@enumerate a
+@item
+You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+@item
+If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License.  (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+@end enumerate
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+@item
+You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+@enumerate a
+@item
+Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+@item
+Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+@item
+Accompany it with the information you received as to the offer
+to distribute corresponding source code.  (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+@end enumerate
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+@item
+You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+@item
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and ``any
+later version'', you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+@item
+If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+@center NO WARRANTY
+
+@item
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+@end enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+@page
+@heading How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the ``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the program's name and an idea of what it does.}
+Copyright (C) 19@var{yy}  @var{name of author}
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+type `show w'.  This is free software, and you are welcome
+to redistribute it under certain conditions; type `show c'
+for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than @samp{show w} and
+@samp{show c}; they could even be mouse-clicks or menu items---whatever
+suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the program, if
+necessary.  Here is a sample; alter the names:
+
+@smallexample
+@group
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written
+by James Hacker.
+
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end group
+@end smallexample
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.
diff --git a/libotr/libgcrypt-1.8.7/doc/lgpl.texi b/libotr/libgcrypt-1.8.7/doc/lgpl.texi
new file mode 100644
index 0000000..bbd18a0
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/lgpl.texi
@@ -0,0 +1,560 @@
+@node Library Copying
+@unnumbered GNU Lesser General Public License
+
+@cindex LGPL, GNU Lesser General Public License
+@center Version 2.1, February 1999
+
+@display
+Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc.
+59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+as the successor of the GNU Library Public License, version 2, hence the
+version number 2.1.]
+@end display
+
+@heading Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software---to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software---typically libraries---of the Free
+Software Foundation and other authors who decide to use it.  You can use
+it too, but we suggest you first think carefully about whether this
+license or the ordinary General Public License is the better strategy to
+use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of it
+in new free programs; and that you are informed that you can do these
+things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the @dfn{Lesser} General Public License because it
+does @emph{Less} to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+``work based on the library'' and a ``work that uses the library''.  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+@iftex
+@heading TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center GNU LESSER GENERAL PUBLIC LICENSE
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate 0
+@item
+This License Agreement applies to any software library or other program
+which contains a notice placed by the copyright holder or other
+authorized party saying it may be distributed under the terms of this
+Lesser General Public License (also called ``this License'').  Each
+licensee is addressed as ``you''.
+
+  A ``library'' means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The ``Library'', below, refers to any such software library or work
+which has been distributed under these terms.  A ``work based on the
+Library'' means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term ``modification''.)
+
+  ``Source code'' for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+
+@item
+You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+@item
+You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+@enumerate a
+@item
+The modified work must itself be a software library.
+
+@item
+You must cause the files modified to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+You must cause the whole of the work to be licensed at no
+charge to all third parties under the terms of this License.
+
+@item
+If a facility in the modified Library refers to a function or a
+table of data to be supplied by an application program that uses
+the facility, other than as an argument passed when the facility
+is invoked, then you must make a good faith effort to ensure that,
+in the event an application does not supply such function or
+table, the facility still operates, and performs whatever part of
+its purpose remains meaningful.
+
+(For example, a function in a library to compute square roots has
+a purpose that is entirely well-defined independent of the
+application.  Therefore, Subsection 2d requires that any
+application-supplied function or table used by this function must
+be optional: if the application does not supply it, the square
+root function must still compute square roots.)
+@end enumerate
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+@item
+You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+@item
+You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+@item
+A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a ``work that uses the Library''.  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a ``work that uses the Library'' with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a ``work that uses the
+library''.  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a ``work that uses the Library'' uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+@item
+As an exception to the Sections above, you may also combine or
+link a ``work that uses the Library'' with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+@enumerate a
+@item
+Accompany the work with the complete corresponding
+machine-readable source code for the Library including whatever
+changes were used in the work (which must be distributed under
+Sections 1 and 2 above); and, if the work is an executable linked
+with the Library, with the complete machine-readable ``work that
+uses the Library'', as object code and/or source code, so that the
+user can modify the Library and then relink to produce a modified
+executable containing the modified Library.  (It is understood
+that the user who changes the contents of definitions files in the
+Library will not necessarily be able to recompile the application
+to use the modified definitions.)
+
+@item
+Use a suitable shared library mechanism for linking with the Library.  A
+suitable mechanism is one that (1) uses at run time a copy of the
+library already present on the user's computer system, rather than
+copying library functions into the executable, and (2) will operate
+properly with a modified version of the library, if the user installs
+one, as long as the modified version is interface-compatible with the
+version that the work was made with.
+
+@item
+Accompany the work with a written offer, valid for at
+least three years, to give the same user the materials
+specified in Subsection 6a, above, for a charge no more
+than the cost of performing this distribution.
+
+@item
+If distribution of the work is made by offering access to copy
+from a designated place, offer equivalent access to copy the above
+specified materials from the same place.
+
+@item
+Verify that the user has already received a copy of these
+materials or that you have already sent this user a copy.
+@end enumerate
+
+  For an executable, the required form of the ``work that uses the
+Library'' must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies the
+executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+@item
+You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+@enumerate a
+@item
+Accompany the combined library with a copy of the same work
+based on the Library, uncombined with any other library
+facilities.  This must be distributed under the terms of the
+Sections above.
+
+@item
+Give prominent notice with the combined library of the fact
+that part of it is a work based on the Library, and explaining
+where to find the accompanying uncombined form of the same work.
+@end enumerate
+
+@item
+You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+@item
+You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+@item
+Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+``any later version'', you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+@item
+If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+@center NO WARRANTY
+
+@item
+BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+@end enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+@page
+@heading How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the library's name and an idea of what it does.}
+Copyright (C) @var{year}  @var{name of author}
+
+This library is free software; you can redistribute it and/or modify it
+under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation; either version 2.1 of the License, or (at
+your option) any later version.
+
+This library is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
+USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the library, if
+necessary.  Here is a sample; alter the names:
+
+@smallexample
+Yoyodyne, Inc., hereby disclaims all copyright interest in the library
+`Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+@var{signature of Ty Coon}, 1 April 1990
+Ty Coon, President of Vice
+@end smallexample
+
+That's all there is to it!
diff --git a/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.eps b/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.eps
new file mode 100644
index 0000000..a9d9058
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.eps
@@ -0,0 +1,322 @@
+%!PS-Adobe-3.0 EPSF-3.0
+%%Title: /home/wk/s/libgcrypt-1.8/doc/libgcrypt-modules.fig
+%%Creator: fig2dev Version 3.2.7a
+%%CreationDate: 2020-10-23 19:27:38
+%%BoundingBox: 0 0 488 300
+%%Magnification: 1.0000
+%%EndComments
+%%BeginProlog
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col32 {0.557 0.557 0.557 srgb} bind def
+/col33 {0.255 0.271 0.255 srgb} bind def
+/col34 {0.753 0.753 0.753 srgb} bind def
+/col35 {0.502 0.502 0.502 srgb} bind def
+/col36 {0.388 0.388 0.388 srgb} bind def
+/col37 {0.804 0.804 0.804 srgb} bind def
+/col38 {0.424 0.424 0.424 srgb} bind def
+/col39 {0.776 0.718 0.592 srgb} bind def
+/col40 {0.937 0.973 1.000 srgb} bind def
+/col41 {0.863 0.796 0.651 srgb} bind def
+/col42 {0.251 0.251 0.251 srgb} bind def
+/col43 {0.878 0.878 0.878 srgb} bind def
+/col44 {0.557 0.561 0.557 srgb} bind def
+/col45 {0.667 0.667 0.667 srgb} bind def
+/col46 {0.333 0.333 0.333 srgb} bind def
+/col47 {0.843 0.843 0.843 srgb} bind def
+/col48 {0.682 0.682 0.682 srgb} bind def
+/col49 {0.745 0.745 0.745 srgb} bind def
+/col50 {0.318 0.318 0.318 srgb} bind def
+/col51 {0.906 0.890 0.906 srgb} bind def
+/col52 {0.000 0.000 0.286 srgb} bind def
+/col53 {0.475 0.475 0.475 srgb} bind def
+/col54 {0.188 0.204 0.188 srgb} bind def
+/col55 {0.255 0.255 0.255 srgb} bind def
+/col56 {0.780 0.714 0.588 srgb} bind def
+/col57 {0.867 0.616 0.576 srgb} bind def
+/col58 {0.945 0.925 0.878 srgb} bind def
+/col59 {0.765 0.765 0.765 srgb} bind def
+/col60 {0.886 0.784 0.659 srgb} bind def
+/col61 {0.882 0.882 0.882 srgb} bind def
+/col62 {0.824 0.824 0.824 srgb} bind def
+/col63 {0.929 0.929 0.929 srgb} bind def
+/col64 {0.855 0.478 0.102 srgb} bind def
+/col65 {0.945 0.894 0.102 srgb} bind def
+/col66 {0.533 0.490 0.761 srgb} bind def
+/col67 {0.839 0.839 0.839 srgb} bind def
+/col68 {0.549 0.549 0.647 srgb} bind def
+/col69 {0.290 0.290 0.290 srgb} bind def
+/col70 {0.549 0.420 0.420 srgb} bind def
+/col71 {0.353 0.353 0.353 srgb} bind def
+/col72 {0.718 0.608 0.451 srgb} bind def
+/col73 {0.255 0.576 1.000 srgb} bind def
+/col74 {0.749 0.439 0.231 srgb} bind def
+/col75 {0.859 0.467 0.000 srgb} bind def
+/col76 {0.855 0.722 0.000 srgb} bind def
+/col77 {0.000 0.392 0.000 srgb} bind def
+/col78 {0.353 0.420 0.231 srgb} bind def
+/col79 {0.827 0.827 0.827 srgb} bind def
+/col80 {0.557 0.557 0.643 srgb} bind def
+/col81 {0.953 0.725 0.365 srgb} bind def
+/col82 {0.537 0.600 0.420 srgb} bind def
+/col83 {0.392 0.392 0.392 srgb} bind def
+/col84 {0.718 0.902 1.000 srgb} bind def
+/col85 {0.525 0.753 0.925 srgb} bind def
+/col86 {0.741 0.741 0.741 srgb} bind def
+/col87 {0.827 0.584 0.322 srgb} bind def
+/col88 {0.596 0.824 0.996 srgb} bind def
+/col89 {0.549 0.612 0.420 srgb} bind def
+/col90 {0.969 0.420 0.000 srgb} bind def
+/col91 {0.353 0.420 0.224 srgb} bind def
+/col92 {0.549 0.612 0.420 srgb} bind def
+/col93 {0.549 0.612 0.482 srgb} bind def
+/col94 {0.094 0.290 0.094 srgb} bind def
+/col95 {0.678 0.678 0.678 srgb} bind def
+/col96 {0.969 0.741 0.353 srgb} bind def
+/col97 {0.388 0.420 0.612 srgb} bind def
+/col98 {0.969 0.969 0.969 srgb} bind def
+/col99 {0.871 0.000 0.000 srgb} bind def
+/col100 {0.678 0.678 0.678 srgb} bind def
+/col101 {0.969 0.741 0.353 srgb} bind def
+/col102 {0.678 0.678 0.678 srgb} bind def
+/col103 {0.969 0.741 0.353 srgb} bind def
+/col104 {0.388 0.420 0.612 srgb} bind def
+/col105 {0.322 0.420 0.161 srgb} bind def
+/col106 {0.580 0.580 0.580 srgb} bind def
+/col107 {0.000 0.388 0.000 srgb} bind def
+/col108 {0.000 0.388 0.290 srgb} bind def
+/col109 {0.482 0.518 0.290 srgb} bind def
+/col110 {0.906 0.741 0.482 srgb} bind def
+/col111 {0.647 0.710 0.776 srgb} bind def
+/col112 {0.420 0.420 0.580 srgb} bind def
+/col113 {0.518 0.420 0.420 srgb} bind def
+/col114 {0.322 0.612 0.290 srgb} bind def
+/col115 {0.839 0.906 0.906 srgb} bind def
+/col116 {0.322 0.388 0.388 srgb} bind def
+/col117 {0.094 0.420 0.290 srgb} bind def
+/col118 {0.612 0.647 0.710 srgb} bind def
+/col119 {1.000 0.580 0.000 srgb} bind def
+/col120 {1.000 0.580 0.000 srgb} bind def
+/col121 {0.000 0.388 0.290 srgb} bind def
+/col122 {0.482 0.518 0.290 srgb} bind def
+/col123 {0.388 0.451 0.482 srgb} bind def
+/col124 {0.906 0.741 0.482 srgb} bind def
+/col125 {0.871 0.871 0.871 srgb} bind def
+/col126 {0.953 0.933 0.827 srgb} bind def
+/col127 {0.961 0.682 0.365 srgb} bind def
+/col128 {0.584 0.808 0.600 srgb} bind def
+/col129 {0.710 0.082 0.490 srgb} bind def
+/col130 {0.933 0.933 0.933 srgb} bind def
+/col131 {0.518 0.518 0.518 srgb} bind def
+/col132 {0.482 0.482 0.482 srgb} bind def
+/col133 {0.000 0.353 0.000 srgb} bind def
+/col134 {0.906 0.451 0.451 srgb} bind def
+/col135 {1.000 0.796 0.192 srgb} bind def
+/col136 {0.161 0.475 0.290 srgb} bind def
+/col137 {0.871 0.157 0.129 srgb} bind def
+/col138 {0.129 0.349 0.776 srgb} bind def
+/col139 {0.973 0.973 0.973 srgb} bind def
+/col140 {0.902 0.902 0.902 srgb} bind def
+/col141 {0.129 0.518 0.353 srgb} bind def
+/col142 {0.788 0.788 0.788 srgb} bind def
+/col143 {0.875 0.847 0.875 srgb} bind def
+/col144 {0.969 0.953 0.969 srgb} bind def
+
+end
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/rl {rlineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+/reencdict 12 dict def /ReEncode { reencdict begin
+/newcodesandnames exch def /newfontname exch def /basefontname exch def
+/basefontdict basefontname findfont def /newfont basefontdict maxlength dict def
+basefontdict { exch dup /FID ne { dup /Encoding eq
+{ exch dup length array copy newfont 3 1 roll put }
+{ exch newfont 3 1 roll put } ifelse } { pop pop } ifelse } forall
+newfont /FontName newfontname put newcodesandnames aload pop
+128 1 255 { newfont /Encoding get exch /.notdef put } for
+newcodesandnames length 2 idiv { newfont /Encoding get 3 1 roll put } repeat
+newfontname newfont definefont pop end } def
+/isovec [
+8#055 /minus 8#200 /grave 8#201 /acute 8#202 /circumflex 8#203 /tilde
+8#204 /macron 8#205 /breve 8#206 /dotaccent 8#207 /dieresis
+8#210 /ring 8#211 /cedilla 8#212 /hungarumlaut 8#213 /ogonek 8#214 /caron
+8#220 /dotlessi 8#230 /oe 8#231 /OE
+8#240 /space 8#241 /exclamdown 8#242 /cent 8#243 /sterling
+8#244 /currency 8#245 /yen 8#246 /brokenbar 8#247 /section 8#250 /dieresis
+8#251 /copyright 8#252 /ordfeminine 8#253 /guillemotleft 8#254 /logicalnot
+8#255 /hyphen 8#256 /registered 8#257 /macron 8#260 /degree 8#261 /plusminus
+8#262 /twosuperior 8#263 /threesuperior 8#264 /acute 8#265 /mu 8#266 /paragraph
+8#267 /periodcentered 8#270 /cedilla 8#271 /onesuperior 8#272 /ordmasculine
+8#273 /guillemotright 8#274 /onequarter 8#275 /onehalf
+8#276 /threequarters 8#277 /questiondown 8#300 /Agrave 8#301 /Aacute
+8#302 /Acircumflex 8#303 /Atilde 8#304 /Adieresis 8#305 /Aring
+8#306 /AE 8#307 /Ccedilla 8#310 /Egrave 8#311 /Eacute
+8#312 /Ecircumflex 8#313 /Edieresis 8#314 /Igrave 8#315 /Iacute
+8#316 /Icircumflex 8#317 /Idieresis 8#320 /Eth 8#321 /Ntilde 8#322 /Ograve
+8#323 /Oacute 8#324 /Ocircumflex 8#325 /Otilde 8#326 /Odieresis 8#327 /multiply
+8#330 /Oslash 8#331 /Ugrave 8#332 /Uacute 8#333 /Ucircumflex
+8#334 /Udieresis 8#335 /Yacute 8#336 /Thorn 8#337 /germandbls 8#340 /agrave
+8#341 /aacute 8#342 /acircumflex 8#343 /atilde 8#344 /adieresis 8#345 /aring
+8#346 /ae 8#347 /ccedilla 8#350 /egrave 8#351 /eacute
+8#352 /ecircumflex 8#353 /edieresis 8#354 /igrave 8#355 /iacute
+8#356 /icircumflex 8#357 /idieresis 8#360 /eth 8#361 /ntilde 8#362 /ograve
+8#363 /oacute 8#364 /ocircumflex 8#365 /otilde 8#366 /odieresis 8#367 /divide
+8#370 /oslash 8#371 /ugrave 8#372 /uacute 8#373 /ucircumflex
+8#374 /udieresis 8#375 /yacute 8#376 /thorn 8#377 /ydieresis] def
+/Helvetica /Helvetica-iso isovec ReEncode
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+/pageheader {
+sa
+n 0 300 m 0 0 l 488 0 l 488 300 l cp clip
+-32.6 348.9 tr
+1 -1 sc
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+} bind def
+/pagefooter {
+$F2psEnd
+restore
+} bind def
+%%EndProlog
+pageheader
+%
+% Fig objects follow
+%
+% 
+% here starts figure with depth 50
+% Polyline
+0 slj
+0 slc
+15.000 slw
+n 645 810 m 540 810 540 2055 105 arcto 4 {pop} repeat
+  540 2160 2685 2160 105 arcto 4 {pop} repeat
+  2790 2160 2790 915 105 arcto 4 {pop} repeat
+  2790 810 645 810 105 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 645 2790 m 540 2790 540 4035 105 arcto 4 {pop} repeat
+  540 4140 2685 4140 105 arcto 4 {pop} repeat
+  2790 4140 2790 2895 105 arcto 4 {pop} repeat
+  2790 2790 645 2790 105 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 3345 2790 m 3240 2790 3240 4035 105 arcto 4 {pop} repeat
+  3240 4140 5385 4140 105 arcto 4 {pop} repeat
+  5490 4140 5490 2895 105 arcto 4 {pop} repeat
+  5490 2790 3345 2790 105 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 6075 2805 m 5970 2805 5970 4050 105 arcto 4 {pop} repeat
+  5970 4155 8115 4155 105 arcto 4 {pop} repeat
+  8220 4155 8220 2910 105 arcto 4 {pop} repeat
+  8220 2805 6075 2805 105 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 3345 810 m 3240 810 3240 2055 105 arcto 4 {pop} repeat
+  3240 2160 5385 2160 105 arcto 4 {pop} repeat
+  5490 2160 5490 915 105 arcto 4 {pop} repeat
+  5490 810 3345 810 105 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 6090 810 m 5985 810 5985 2055 105 arcto 4 {pop} repeat
+  5985 2160 8130 2160 105 arcto 4 {pop} repeat
+  8235 2160 8235 915 105 arcto 4 {pop} repeat
+  8235 810 6090 810 105 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 3513 4563 m 3438 4563 3438 5438 75 arcto 4 {pop} repeat
+  3438 5513 4947 5513 75 arcto 4 {pop} repeat
+  5022 5513 5022 4638 75 arcto 4 {pop} repeat
+  5022 4563 3513 4563 75 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 5583 4563 m 5508 4563 5508 5438 75 arcto 4 {pop} repeat
+  5508 5513 7017 5513 75 arcto 4 {pop} repeat
+  7092 5513 7092 4638 75 arcto 4 {pop} repeat
+  7092 4563 5583 4563 75 arcto 4 {pop} repeat
+ cp gs col0 s gr % Polyline
+n 1443 4567 m 1368 4567 1368 5442 75 arcto 4 {pop} repeat
+  1368 5517 2877 5517 75 arcto 4 {pop} repeat
+  2952 5517 2952 4642 75 arcto 4 {pop} repeat
+  2952 4567 1443 4567 75 arcto 4 {pop} repeat
+ cp gs col0 s gr /Helvetica-iso ff 300.00 scf sf
+900 1440 m
+gs 1 -1 sc (Public-Key) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+900 1815 m
+gs 1 -1 sc (Encryption) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+630 3420 m
+gs 1 -1 sc (Multi-Precision-) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+900 3795 m
+gs 1 -1 sc (Integers) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+3420 3420 m
+gs 1 -1 sc (Prime-Number) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+3420 3795 m
+gs 1 -1 sc (Generator) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+6420 3435 m
+gs 1 -1 sc (Random) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+6420 3810 m
+gs 1 -1 sc (Numbers) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+3600 1440 m
+gs 1 -1 sc (Symmetric) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+3600 1815 m
+gs 1 -1 sc (Encryption) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+6435 1440 m
+gs 1 -1 sc (Hashing) col0 sh gr
+/Helvetica-iso ff 300.00 scf sf
+6435 1815 m
+gs 1 -1 sc (MACing) col0 sh gr
+/Helvetica-iso ff 210.00 scf sf
+3825 5130 m
+gs 1 -1 sc (Memory) col0 sh gr
+/Helvetica-iso ff 210.00 scf sf
+5635 5133 m
+gs 1 -1 sc (Miscelleanous) col0 sh gr
+/Helvetica-iso ff 210.00 scf sf
+1495 5137 m
+gs 1 -1 sc (S-expressions) col0 sh gr
+% here ends figure;
+pagefooter
+showpage
+%%Trailer
+%EOF
diff --git a/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.fig b/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.fig
new file mode 100644
index 0000000..ea3d053
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.fig
@@ -0,0 +1,193 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+0 32 #8e8e8e
+0 33 #414541
+0 34 #c0c0c0
+0 35 #808080
+0 36 #636363
+0 37 #cdcdcd
+0 38 #6c6c6c
+0 39 #c6b797
+0 40 #eff8ff
+0 41 #dccba6
+0 42 #404040
+0 43 #e0e0e0
+0 44 #8e8f8e
+0 45 #aaaaaa
+0 46 #555555
+0 47 #d7d7d7
+0 48 #aeaeae
+0 49 #bebebe
+0 50 #515151
+0 51 #e7e3e7
+0 52 #000049
+0 53 #797979
+0 54 #303430
+0 55 #414141
+0 56 #c7b696
+0 57 #dd9d93
+0 58 #f1ece0
+0 59 #c3c3c3
+0 60 #e2c8a8
+0 61 #e1e1e1
+0 62 #d2d2d2
+0 63 #ededed
+0 64 #da7a1a
+0 65 #f1e41a
+0 66 #887dc2
+0 67 #d6d6d6
+0 68 #8c8ca5
+0 69 #4a4a4a
+0 70 #8c6b6b
+0 71 #5a5a5a
+0 72 #b79b73
+0 73 #4193ff
+0 74 #bf703b
+0 75 #db7700
+0 76 #dab800
+0 77 #006400
+0 78 #5a6b3b
+0 79 #d3d3d3
+0 80 #8e8ea4
+0 81 #f3b95d
+0 82 #89996b
+0 83 #646464
+0 84 #b7e6ff
+0 85 #86c0ec
+0 86 #bdbdbd
+0 87 #d39552
+0 88 #98d2fe
+0 89 #8c9c6b
+0 90 #f76b00
+0 91 #5a6b39
+0 92 #8c9c6b
+0 93 #8c9c7b
+0 94 #184a18
+0 95 #adadad
+0 96 #f7bd5a
+0 97 #636b9c
+0 98 #f7f7f7
+0 99 #de0000
+0 100 #adadad
+0 101 #f7bd5a
+0 102 #adadad
+0 103 #f7bd5a
+0 104 #636b9c
+0 105 #526b29
+0 106 #949494
+0 107 #006300
+0 108 #00634a
+0 109 #7b844a
+0 110 #e7bd7b
+0 111 #a5b5c6
+0 112 #6b6b94
+0 113 #846b6b
+0 114 #529c4a
+0 115 #d6e7e7
+0 116 #526363
+0 117 #186b4a
+0 118 #9ca5b5
+0 119 #ff9400
+0 120 #ff9400
+0 121 #00634a
+0 122 #7b844a
+0 123 #63737b
+0 124 #e7bd7b
+0 125 #dedede
+0 126 #f3eed3
+0 127 #f5ae5d
+0 128 #95ce99
+0 129 #b5157d
+0 130 #eeeeee
+0 131 #848484
+0 132 #7b7b7b
+0 133 #005a00
+0 134 #e77373
+0 135 #ffcb31
+0 136 #29794a
+0 137 #de2821
+0 138 #2159c6
+0 139 #f8f8f8
+0 140 #e6e6e6
+0 141 #21845a
+0 142 #c9c9c9
+0 143 #dfd8df
+0 144 #f7f3f7
+6 450 720 8325 5580
+6 450 720 8325 4275
+6 450 720 2880 2250
+6 900 1170 2340 1890
+4 0 0 50 -1 16 20 0.0000 4 300 1410 900 1440 Public-Key\001
+4 0 0 50 -1 16 20 0.0000 4 300 1410 900 1815 Encryption\001
+-6
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 2790 2160 2790 810 540 810 540 2160 2790 2160
+-6
+6 525 2775 2805 4155
+6 630 3150 2700 3870
+6 630 3150 2700 3870
+4 0 0 50 -1 16 20 0.0000 4 225 2055 630 3420 Multi-Precision-\001
+4 0 0 50 -1 16 20 0.0000 4 300 1095 900 3795 Integers\001
+-6
+-6
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 2790 4140 2790 2790 540 2790 540 4140 2790 4140
+-6
+6 3150 2700 5580 4230
+6 3420 3150 5400 3870
+4 0 0 50 -1 16 20 0.0000 4 225 1965 3420 3420 Prime-Number\001
+4 0 0 50 -1 16 20 0.0000 4 225 1365 3420 3795 Generator\001
+-6
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 5490 4140 5490 2790 3240 2790 3240 4140 5490 4140
+-6
+6 5880 2715 8310 4245
+6 6420 3165 7680 3885
+4 0 0 50 -1 16 20 0.0000 4 225 1140 6420 3435 Random\001
+4 0 0 50 -1 16 20 0.0000 4 225 1230 6420 3810 Numbers\001
+-6
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 8220 4155 8220 2805 5970 2805 5970 4155 8220 4155
+-6
+6 3150 720 5580 2250
+6 3600 1170 5040 1890
+4 0 0 50 -1 16 20 0.0000 4 300 1425 3600 1440 Symmetric\001
+4 0 0 50 -1 16 20 0.0000 4 300 1410 3600 1815 Encryption\001
+-6
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 5490 2160 5490 810 3240 810 3240 2160 5490 2160
+-6
+6 5940 765 8280 2205
+6 6435 1215 7530 1890
+4 0 0 50 -1 16 20 0.0000 4 300 1095 6435 1440 Hashing\001
+4 0 0 50 -1 16 20 0.0000 4 300 1065 6435 1815 MACing\001
+-6
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 8235 2160 8235 810 5985 810 5985 2160 8235 2160
+-6
+-6
+6 1305 4500 7155 5580
+6 3375 4500 5085 5580
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 5 0 0 5
+	 5022 5513 5022 4563 3438 4563 3438 5513 5022 5513
+4 0 0 50 -1 16 14 0.0000 4 195 780 3825 5130 Memory\001
+-6
+6 5445 4500 7155 5576
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 5 0 0 5
+	 7092 5513 7092 4563 5508 4563 5508 5513 7092 5513
+4 0 0 50 -1 16 14 0.0000 4 150 1350 5635 5133 Miscelleanous\001
+-6
+6 1305 4504 3015 5580
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 5 0 0 5
+	 2952 5517 2952 4567 1368 4567 1368 5517 2952 5517
+4 0 0 50 -1 16 14 0.0000 4 195 1350 1495 5137 S-expressions\001
+-6
+-6
+-6
diff --git a/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.pdf b/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.pdf
new file mode 100644
index 0000000..d96484d
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.pdf
Binary files differdiff --git a/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.png b/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.png
new file mode 100644
index 0000000..c84ef1f
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/libgcrypt-modules.png
Binary files differdiff --git a/libotr/libgcrypt-1.8.7/doc/stamp-vti b/libotr/libgcrypt-1.8.7/doc/stamp-vti
new file mode 100644
index 0000000..29ebd35
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/stamp-vti
@@ -0,0 +1,4 @@
+@set UPDATED 30 July 2020
+@set UPDATED-MONTH July 2020
+@set EDITION 1.8.7
+@set VERSION 1.8.7
diff --git a/libotr/libgcrypt-1.8.7/doc/version.texi b/libotr/libgcrypt-1.8.7/doc/version.texi
new file mode 100644
index 0000000..29ebd35
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/version.texi
@@ -0,0 +1,4 @@
+@set UPDATED 30 July 2020
+@set UPDATED-MONTH July 2020
+@set EDITION 1.8.7
+@set VERSION 1.8.7
diff --git a/libotr/libgcrypt-1.8.7/doc/yat2m.c b/libotr/libgcrypt-1.8.7/doc/yat2m.c
new file mode 100644
index 0000000..3c7b363
--- /dev/null
+++ b/libotr/libgcrypt-1.8.7/doc/yat2m.c
@@ -0,0 +1,1649 @@
+/* yat2m.c - Yet Another Texi 2 Man converter
+ *	Copyright (C) 2005, 2013, 2015, 2016, 2017 g10 Code GmbH
+ *      Copyright (C) 2006, 2008, 2011 Free Software Foundation, Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses/>.
+ */
+
+/*
+    This is a simple texinfo to man page converter.  It needs some
+    special markup in th e texinfo and tries best to get a create man
+    page.  It has been designed for the GnuPG man pages and thus only
+    a few texinfo commands are supported.
+
+    To use this you need to add the following macros into your texinfo
+    source:
+
+      @macro manpage {a}
+      @end macro
+      @macro mansect {a}
+      @end macro
+      @macro manpause
+      @end macro
+      @macro mancont
+      @end macro
+
+    They are used by yat2m to select parts of the Texinfo which should
+    go into the man page. These macros need to be used without leading
+    left space. Processing starts after a "manpage" macro has been
+    seen.  "mansect" identifies the section and yat2m make sure to
+    emit the sections in the proper order.  Note that @mansect skips
+    the next input line if that line begins with @section, @subsection or
+    @chapheading.
+
+    To insert verbatim troff markup, the following texinfo code may be
+    used:
+
+      @ifset manverb
+      .B whateever you want
+      @end ifset
+
+    alternativly a special comment may be used:
+
+      @c man:.B whatever you want
+
+    This is useful in case you need just one line. If you want to
+    include parts only in the man page but keep the texinfo
+    translation you may use:
+
+      @ifset isman
+      stuff to be rendered only on man pages
+      @end ifset
+
+    or to exclude stuff from man pages:
+
+      @ifclear isman
+      stuff not to be rendered on man pages
+      @end ifclear
+
+    the keyword @section is ignored, however @subsection gets rendered
+    as ".SS".  @menu is completely skipped. Several man pages may be
+    extracted from one file, either using the --store or the --select
+    option.
+
+    If you want to indent tables in the source use this style:
+
+      @table foo
+        @item
+        @item
+        @table
+          @item
+        @end
+      @end
+
+    Don't change the indentation within a table and keep the same
+    number of white space at the start of the line.  yat2m simply
+    detects the number of white spaces in front of an @item and remove
+    this number of spaces from all following lines until a new @item
+    is found or there are less spaces than for the last @item.
+
+    Note that @* does only work correctly if used at the end of an
+    input line.
+
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <stddef.h>
+#include <string.h>
+#include <errno.h>
+#include <stdarg.h>
+#include <assert.h>
+#include <ctype.h>
+#include <time.h>
+
+
+#if __GNUC__
+# define MY_GCC_VERSION (__GNUC__ * 10000 \
+                         + __GNUC_MINOR__ * 100         \
+                         + __GNUC_PATCHLEVEL__)
+#else
+# define MY_GCC_VERSION 0
+#endif
+
+#if MY_GCC_VERSION >= 20500
+# define ATTR_PRINTF(f, a) __attribute__ ((format(printf,f,a)))
+# define ATTR_NR_PRINTF(f, a) __attribute__ ((noreturn, format(printf,f,a)))
+#else
+# define ATTR_PRINTF(f, a)
+# define ATTR_NR_PRINTF(f, a)
+#endif
+#if MY_GCC_VERSION >= 30200
+# define ATTR_MALLOC  __attribute__ ((__malloc__))
+#else
+# define ATTR_MALLOC
+#endif
+
+
+
+#define PGM "yat2m"
+#ifdef PACKAGE_VERSION
+# define VERSION PACKAGE_VERSION
+#else
+# define VERSION "1.0"
+#endif
+
+/* The maximum length of a line including the linefeed and one extra
+   character. */
+#define LINESIZE 1024
+
+/* Number of allowed condition nestings.  */
+#define MAX_CONDITION_NESTING  10
+
+/* Option flags. */
+static int verbose;
+static int quiet;
+static int debug;
+static const char *opt_source;
+static const char *opt_release;
+static const char *opt_date;
+static const char *opt_select;
+static const char *opt_include;
+static int opt_store;
+
+/* Flag to keep track whether any error occurred.  */
+static int any_error;
+
+
+/* Object to keep macro definitions.  */
+struct macro_s
+{
+  struct macro_s *next;
+  char *value;    /* Malloced value. */
+  char name[1];
+};
+typedef struct macro_s *macro_t;
+
+/* List of all defined macros. */
+static macro_t macrolist;
+
+/* List of variables set by @set. */
+static macro_t variablelist;
+
+/* List of global macro names.  The value part is not used.  */
+static macro_t predefinedmacrolist;
+
+/* Object to keep track of @isset and @ifclear.  */
+struct condition_s
+{
+  int manverb;   /* "manverb" needs special treatment.  */
+  int isset;     /* This is an @isset condition.  */
+  char name[1];  /* Name of the condition macro.  */
+};
+typedef struct condition_s *condition_t;
+
+/* The stack used to evaluate conditions.  And the current states. */
+static condition_t condition_stack[MAX_CONDITION_NESTING];
+static int condition_stack_idx;
+static int cond_is_active;     /* State of ifset/ifclear */
+static int cond_in_verbatim;   /* State of "manverb".  */
+
+
+/* Object to store one line of content.  */
+struct line_buffer_s
+{
+  struct line_buffer_s *next;
+  int verbatim;  /* True if LINE contains verbatim data.  The default
+                    is Texinfo source.  */
+  char *line;
+};
+typedef struct line_buffer_s *line_buffer_t;
+
+
+/* Object to collect the data of a section.  */
+struct section_buffer_s
+{
+  char *name;           /* Malloced name of the section. This may be
+                           NULL to indicate this slot is not used.  */
+  line_buffer_t lines;  /* Linked list with the lines of the section.  */
+  line_buffer_t *lines_tail; /* Helper for faster appending to the
+                                linked list.  */
+  line_buffer_t last_line;   /* Points to the last line appended.  */
+};
+typedef struct section_buffer_s *section_buffer_t;
+
+/* Variable to keep info about the current page together.  */
+static struct
+{
+  /* Filename of the current page or NULL if no page is active.  Malloced. */
+  char *name;
+
+  /* Number of allocated elements in SECTIONS below.  */
+  size_t n_sections;
+  /* Array with the data of the sections.  */
+  section_buffer_t sections;
+
+} thepage;
+
+
+/* The list of standard section names.  COMMANDS and ASSUAN are GnuPG
+   specific. */
+static const char * const standard_sections[] =
+  { "NAME",  "SYNOPSIS",  "DESCRIPTION",
+    "RETURN VALUE", "EXIT STATUS", "ERROR HANDLING", "ERRORS",
+    "COMMANDS", "OPTIONS", "USAGE", "EXAMPLES", "FILES",
+    "ENVIRONMENT", "DIAGNOSTICS", "SECURITY", "CONFORMING TO",
+    "ASSUAN", "NOTES", "BUGS", "AUTHOR", "SEE ALSO", NULL };
+
+
+/*-- Local prototypes.  --*/
+static void proc_texi_buffer (FILE *fp, const char *line, size_t len,
+                              int *table_level, int *eol_action);
+
+static void die (const char *format, ...) ATTR_NR_PRINTF(1,2);
+static void err (const char *format, ...) ATTR_PRINTF(1,2);
+static void inf (const char *format, ...) ATTR_PRINTF(1,2);
+static void *xmalloc (size_t n) ATTR_MALLOC;
+static void *xcalloc (size_t n, size_t m) ATTR_MALLOC;
+
+
+
+/*-- Functions --*/
+
+/* Print diagnostic message and exit with failure. */
+static void
+die (const char *format, ...)
+{
+  va_list arg_ptr;
+
+  fflush (stdout);
+  fprintf (stderr, "%s: ", PGM);
+
+  va_start (arg_ptr, format);
+  vfprintf (stderr, format, arg_ptr);
+  va_end (arg_ptr);
+  putc ('\n', stderr);
+
+  exit (1);
+}
+
+
+/* Print diagnostic message. */
+static void
+err (const char *format, ...)
+{
+  va_list arg_ptr;
+
+  fflush (stdout);
+  if (strncmp (format, "%s:%d:", 6))
+    fprintf (stderr, "%s: ", PGM);
+
+  va_start (arg_ptr, format);
+  vfprintf (stderr, format, arg_ptr);
+  va_end (arg_ptr);
+  putc ('\n', stderr);
+  any_error = 1;
+}
+
+/* Print diagnostic message. */
+static void
+inf (const char *format, ...)
+{
+  va_list arg_ptr;
+
+  fflush (stdout);
+  fprintf (stderr, "%s: ", PGM);
+
+  va_start (arg_ptr, format);
+  vfprintf (stderr, format, arg_ptr);
+  va_end (arg_ptr);
+  putc ('\n', stderr);
+}
+
+
+static void *
+xmalloc (size_t n)
+{
+  void *p = malloc (n);
+  if (!p)
+    die ("out of core: %s", strerror (errno));
+  return p;
+}
+
+static void *
+xcalloc (size_t n, size_t m)
+{
+  void *p = calloc (n, m);
+  if (!p)
+    die ("out of core: %s", strerror (errno));
+  return p;
+}
+
+static void *
+xrealloc (void *old, size_t n)
+{
+  void *p = realloc (old, n);
+  if (!p)
+    die ("out of core: %s", strerror (errno));
+  return p;
+}
+
+static char *
+xstrdup (const char *string)
+{
+  void *p = malloc (strlen (string)+1);
+  if (!p)
+    die ("out of core: %s", strerror (errno));
+  strcpy (p, string);
+  return p;
+}
+
+
+/* Uppercase the ascii characters in STRING.  */
+static char *
+ascii_strupr (char *string)
+{
+  char *p;
+
+  for (p = string; *p; p++)
+    if (!(*p & 0x80))
+      *p = toupper (*p);
+  return string;
+}
+
+
+/* Return the current date as an ISO string.  */
+const char *
+isodatestring (void)
+{
+  static char buffer[36];
+  struct tm *tp;
+  time_t atime;
+
+  if (opt_date && *opt_date)
+    atime = strtoul (opt_date, NULL, 10);
+  else
+    atime = time (NULL);
+  if (atime < 0)
+    strcpy (buffer, "????" "-??" "-??");
+  else
+    {
+      tp = gmtime (&atime);
+      sprintf (buffer,"%04d-%02d-%02d",
+               1900+tp->tm_year, tp->tm_mon+1, tp->tm_mday );
+    }
+  return buffer;
+}
+
+
+/* Add NAME to the list of predefined macros which are global for all
+   files.  */
+static void
+add_predefined_macro (const char *name)
+{
+  macro_t m;
+
+  for (m=predefinedmacrolist; m; m = m->next)
+    if (!strcmp (m->name, name))
+      break;
+  if (!m)
+    {
+      m = xcalloc (1, sizeof *m + strlen (name));
+      strcpy (m->name, name);
+      m->next = predefinedmacrolist;
+      predefinedmacrolist = m;
+    }
+}
+
+
+/* Create or update a macro with name MACRONAME and set its values TO
+   MACROVALUE.  Note that ownership of the macro value is transferred
+   to this function.  */
+static void
+set_macro (const char *macroname, char *macrovalue)
+{
+  macro_t m;
+
+  for (m=macrolist; m; m = m->next)
+    if (!strcmp (m->name, macroname))
+      break;
+  if (m)
+    free (m->value);
+  else
+    {
+      m = xcalloc (1, sizeof *m + strlen (macroname));
+      strcpy (m->name, macroname);
+      m->next = macrolist;
+      macrolist = m;
+    }
+  m->value = macrovalue;
+  macrovalue = NULL;
+}
+
+
+/* Create or update a variable with name and value given in NAMEANDVALUE.  */
+static void
+set_variable (char *nameandvalue)
+{
+  macro_t m;
+  const char *value;
+  char *p;
+
+  for (p = nameandvalue; *p && *p != ' ' && *p != '\t'; p++)
+    ;
+  if (!*p)
+    value = "";
+  else
+    {
+      *p++ = 0;
+      while (*p == ' ' || *p == '\t')
+        p++;
+      value = p;
+    }
+
+  for (m=variablelist; m; m = m->next)
+    if (!strcmp (m->name, nameandvalue))
+      break;
+  if (m)
+    free (m->value);
+  else
+    {
+      m = xcalloc (1, sizeof *m + strlen (nameandvalue));
+      strcpy (m->name, nameandvalue);
+      m->next = variablelist;
+      variablelist = m;
+    }
+  m->value = xstrdup (value);
+}
+
+
+/* Return true if the macro or variable NAME is set, i.e. not the
+   empty string and not evaluating to 0.  */
+static int
+macro_set_p (const char *name)
+{
+  macro_t m;
+
+  for (m = macrolist; m ; m = m->next)
+    if (!strcmp (m->name, name))
+      break;
+  if (!m)
+    for (m = variablelist; m ; m = m->next)
+      if (!strcmp (m->name, name))
+        break;
+  if (!m || !m->value || !*m->value)
+    return 0;
+  if ((*m->value & 0x80) || !isdigit (*m->value))
+    return 1; /* Not a digit but some other string.  */
+  return !!atoi (m->value);
+}
+
+
+/* Evaluate the current conditions.  */
+static void
+evaluate_conditions (const char *fname, int lnr)
+{
+  int i;
+
+  (void)fname;
+  (void)lnr;
+
+  /* for (i=0; i < condition_stack_idx; i++) */
+  /*   inf ("%s:%d:   stack[%d] %s %s %c", */
+  /*        fname, lnr, i, condition_stack[i]->isset? "set":"clr", */
+  /*        condition_stack[i]->name, */
+  /*        (macro_set_p (condition_stack[i]->name) */
+  /*         ^ !condition_stack[i]->isset)? 't':'f'); */
+
+  cond_is_active = 1;
+  cond_in_verbatim = 0;
+  if (condition_stack_idx)
+    {
+      for (i=0; i < condition_stack_idx; i++)
+        {
+          if (condition_stack[i]->manverb)
+            cond_in_verbatim = (macro_set_p (condition_stack[i]->name)
+                                ^ !condition_stack[i]->isset);
+          else if (!(macro_set_p (condition_stack[i]->name)
+                     ^ !condition_stack[i]->isset))
+            {
+              cond_is_active = 0;
+              break;
+            }
+        }
+    }
+
+  /* inf ("%s:%d:   active=%d verbatim=%d", */
+  /*      fname, lnr, cond_is_active, cond_in_verbatim); */
+}
+
+
+/* Push a condition with condition macro NAME onto the stack.  If
+   ISSET is true, a @isset condition is pushed.  */
+static void
+push_condition (const char *name, int isset, const char *fname, int lnr)
+{
+  condition_t cond;
+  int manverb = 0;
+
+  if (condition_stack_idx >= MAX_CONDITION_NESTING)
+    {
+      err ("%s:%d: condition nested too deep", fname, lnr);
+      return;
+    }
+
+  if (!strcmp (name, "manverb"))
+    {
+      if (!isset)
+        {
+          err ("%s:%d: using \"@ifclear manverb\" is not allowed", fname, lnr);
+          return;
+        }
+      manverb = 1;
+    }
+
+  cond = xcalloc (1, sizeof *cond + strlen (name));
+  cond->manverb = manverb;
+  cond->isset = isset;
+  strcpy (cond->name, name);
+
+  condition_stack[condition_stack_idx++] = cond;
+  evaluate_conditions (fname, lnr);
+}
+
+
+/* Remove the last condition from the stack.  ISSET is used for error
+   reporting.  */
+static void
+pop_condition (int isset, const char *fname, int lnr)
+{
+  if (!condition_stack_idx)
+    {
+      err ("%s:%d: unbalanced \"@end %s\"",
+           fname, lnr, isset?"isset":"isclear");
+      return;
+    }
+  condition_stack_idx--;
+  free (condition_stack[condition_stack_idx]);
+  condition_stack[condition_stack_idx] = NULL;
+  evaluate_conditions (fname, lnr);
+}
+
+
+
+/* Return a section buffer for the section NAME.  Allocate a new buffer
+   if this is a new section.  Keep track of the sections in THEPAGE.
+   This function may reallocate the section array in THEPAGE.  */
+static section_buffer_t
+get_section_buffer (const char *name)
+{
+  int i;
+  section_buffer_t sect;
+
+  /* If there is no section we put everything into the required NAME
+     section.  Given that this is the first one listed it is likely
+     that error are easily visible.  */
+  if (!name)
+    name = "NAME";
+
+  for (i=0; i < thepage.n_sections; i++)
+    {
+      sect = thepage.sections + i;
+      if (sect->name && !strcmp (name, sect->name))
+        return sect;
+    }
+  for (i=0; i < thepage.n_sections; i++)
+    if (!thepage.sections[i].name)
+      break;
+  if (thepage.n_sections && i < thepage.n_sections)
+    sect = thepage.sections + i;
+  else
+    {
+      /* We need to allocate or reallocate the section array.  */
+      size_t old_n = thepage.n_sections;
+      size_t new_n = 20;
+
+      if (!old_n)
+        thepage.sections = xcalloc (new_n, sizeof *thepage.sections);
+      else
+        {
+          thepage.sections = xrealloc (thepage.sections,
+                                       ((old_n + new_n)
+                                        * sizeof *thepage.sections));
+          memset (thepage.sections + old_n, 0,
+                  new_n * sizeof *thepage.sections);
+        }
+      thepage.n_sections += new_n;
+
+      /* Setup the tail pointers.  */
+      for (i=old_n; i < thepage.n_sections; i++)
+        {
+          sect = thepage.sections + i;
+          sect->lines_tail = &sect->lines;
+        }
+      sect = thepage.sections + old_n;
+    }
+
+  /* Store the name.  */
+  assert (!sect->name);
+  sect->name = xstrdup (name);
+  return sect;
+}
+
+
+
+/* Add the content of LINE to the section named SECTNAME.  */
+static void
+add_content (const char *sectname, char *line, int verbatim)
+{
+  section_buffer_t sect;
+  line_buffer_t lb;
+
+  sect = get_section_buffer (sectname);
+  if (sect->last_line && !sect->last_line->verbatim == !verbatim)
+    {
+      /* Lets append that line to the last one.  We do this to keep
+         all lines of the same kind (i.e.verbatim or not) together in
+         one large buffer.  */
+      size_t n1, n;
+
+      lb = sect->last_line;
+      n1 = strlen (lb->line);
+      n = n1 + 1 + strlen (line) + 1;
+      lb->line = xrealloc (lb->line, n);
+      strcpy (lb->line+n1, "\n");
+      strcpy (lb->line+n1+1, line);
+    }
+  else
+    {
+      lb = xcalloc (1, sizeof *lb);
+      lb->verbatim = verbatim;
+      lb->line = xstrdup (line);
+      sect->last_line = lb;
+      *sect->lines_tail = lb;
+      sect->lines_tail = &lb->next;
+    }
+}
+
+
+/* Prepare for a new man page using the filename NAME. */
+static void
+start_page (char *name)
+{
+  if (verbose)
+    inf ("starting page '%s'", name);
+  assert (!thepage.name);
+  thepage.name = xstrdup (name);
+  thepage.n_sections = 0;
+}
+
+
+/* Write the .TH entry of the current page.  Return -1 if there is a
+   problem with the page. */
+static int
+write_th (FILE *fp)
+{
+  char *name, *p;
+
+  fputs (".\\\" Created from Texinfo source by yat2m " VERSION "\n", fp);
+
+  name = ascii_strupr (xstrdup (thepage.name));
+  p = strrchr (name, '.');
+  if (!p || !p[1])
+    {
+      err ("no section name in man page '%s'", thepage.name);
+      free (name);
+      return -1;
+    }
+  *p++ = 0;
+  fprintf (fp, ".TH %s %s %s \"%s\" \"%s\"\n",
+           name, p, isodatestring (), opt_release, opt_source);
+  free (name);
+  return 0;
+}
+
+
+/* Process the texinfo command COMMAND (without the leading @) and
+   write output if needed to FP. REST is the remainer of the line
+   which should either point to an opening brace or to a white space.
+   The function returns the number of characters already processed
+   from REST.  LEN is the usable length of REST.  TABLE_LEVEL is used to
+   control the indentation of tables.  */
+static size_t
+proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
+               int *table_level, int *eol_action)
+{
+  static struct {
+    const char *name;    /* Name of the command.  */
+    int what;            /* What to do with this command. */
+    const char *lead_in; /* String to print with a opening brace.  */
+    const char *lead_out;/* String to print with the closing brace. */
+  } cmdtbl[] = {
+    { "command", 0, "\\fB", "\\fR" },
+    { "code",    0, "\\fB", "\\fR" },
+    { "url",     0, "\\fB", "\\fR" },
+    { "sc",      0, "\\fB", "\\fR" },
+    { "var",     0, "\\fI", "\\fR" },
+    { "samp",    0, "\\(aq", "\\(aq"  },
+    { "file",    0, "\\(oq\\fI","\\fR\\(cq" },
+    { "env",     0, "\\(oq\\fI","\\fR\\(cq" },
+    { "acronym", 0 },
+    { "dfn",     0 },
+    { "option",  0, "\\fB", "\\fR"   },
+    { "example", 1, ".RS 2\n.nf\n" },
+    { "smallexample", 1, ".RS 2\n.nf\n" },
+    { "asis",    7 },
+    { "anchor",  7 },
+    { "cartouche", 1 },
+    { "ref",     0, "[", "]" },
+    { "xref",    0, "See: [", "]" },
+    { "pxref",   0, "see: [", "]" },
+    { "uref",    0, "(\\fB", "\\fR)" },
+    { "footnote",0, " ([", "])" },
+    { "emph",    0, "\\fI", "\\fR" },
+    { "w",       1 },
+    { "c",       5 },
+    { "efindex", 1 },
+    { "opindex", 1 },
+    { "cpindex", 1 },
+    { "cindex",  1 },
+    { "noindent", 0 },
+    { "section", 1 },
+    { "chapter", 1 },
+    { "subsection", 6, "\n.SS " },
+    { "chapheading", 0},
+    { "item",    2, ".TP\n.B " },
+    { "itemx",   2, ".TQ\n.B " },
+    { "table",   3 },
+    { "itemize",   3 },
+    { "bullet",  0, "* " },
+    { "*",       0, "\n.br"},
+    { "/",       0 },
+    { "end",     4 },
+    { "quotation",1, ".RS\n\\fB" },
+    { "value", 8 },
+    { NULL }
+  };
+  size_t n;
+  int i;
+  const char *s;
+  const char *lead_out = NULL;
+  int ignore_args = 0;
+
+  for (i=0; cmdtbl[i].name && strcmp (cmdtbl[i].name, command); i++)
+    ;
+  if (cmdtbl[i].name)
+    {
+      s = cmdtbl[i].lead_in;
+      if (s)
+        fputs (s, fp);
+      lead_out = cmdtbl[i].lead_out;
+      switch (cmdtbl[i].what)
+        {
+        case 1: /* Throw away the entire line.  */
+          s = memchr (rest, '\n', len);
+          return s? (s-rest)+1 : len;
+        case 2: /* Handle @item.  */
+          break;
+        case 3: /* Handle table.  */
+          if (++(*table_level) > 1)
+            fputs (".RS\n", fp);
+          /* Now throw away the entire line. */
+          s = memchr (rest, '\n', len);
+          return s? (s-rest)+1 : len;
+          break;
+        case 4: /* Handle end.  */
+          for (s=rest, n=len; n && (*s == ' ' || *s == '\t'); s++, n--)
+            ;
+          if (n >= 5 && !memcmp (s, "table", 5)
+              && (!n || s[5] == ' ' || s[5] == '\t' || s[5] == '\n'))
+            {
+              if ((*table_level)-- > 1)
+                fputs (".RE\n", fp);
+              else
+                fputs (".P\n", fp);
+            }
+          else if (n >= 7 && !memcmp (s, "example", 7)
+              && (!n || s[7] == ' ' || s[7] == '\t' || s[7] == '\n'))
+            {
+              fputs (".fi\n.RE\n", fp);
+            }
+          else if (n >= 12 && !memcmp (s, "smallexample", 12)
+              && (!n || s[12] == ' ' || s[12] == '\t' || s[12] == '\n'))
+            {
+              fputs (".fi\n.RE\n", fp);
+            }
+          else if (n >= 9 && !memcmp (s, "quotation", 9)
+              && (!n || s[9] == ' ' || s[9] == '\t' || s[9] == '\n'))
+            {
+              fputs ("\\fR\n.RE\n", fp);
+            }
+          /* Now throw away the entire line. */
+          s = memchr (rest, '\n', len);
+          return s? (s-rest)+1 : len;
+        case 5: /* Handle special comments. */
+          for (s=rest, n=len; n && (*s == ' ' || *s == '\t'); s++, n--)
+            ;
+          if (n >= 4 && !memcmp (s, "man:", 4))
+            {
+              for (s+=4, n-=4; n && *s != '\n'; n--, s++)
+                putc (*s, fp);
+              putc ('\n', fp);
+            }
+          /* Now throw away the entire line. */
+          s = memchr (rest, '\n', len);
+          return s? (s-rest)+1 : len;
+        case 6:
+          *eol_action = 1;
+          break;
+        case 7:
+          ignore_args = 1;
+          break;
+        case 8:
+          ignore_args = 1;
+          if (*rest != '{')
+            {
+              err ("opening brace for command '%s' missing", command);
+              return len;
+            }
+          else
+            {
+              /* Find closing brace.  */
+              for (s=rest+1, n=1; *s && n < len; s++, n++)
+                if (*s == '}')
+                  break;
+              if (*s != '}')
+                {
+                  err ("closing brace for command '%s' not found", command);
+                  return len;
+                }
+              else
+                {
+                  size_t rlen = s - (rest + 1);
+                  macro_t m;
+
+                  for (m = variablelist; m; m = m->next)
+                    {
+                      if (strlen (m->name) == rlen
+                          && !strncmp (m->name, rest+1, rlen))
+                        break;
+                    }
+                  if (m)
+                    fputs (m->value, fp);
+                  else
+                    inf ("texinfo variable '%.*s' is not set",
+                         (int)rlen, rest+1);
+                }
+            }
+          break;
+        default:
+          break;
+        }
+    }
+  else /* macro */
+    {
+      macro_t m;
+
+      for (m = macrolist; m ; m = m->next)
+        if (!strcmp (m->name, command))
+            break;
+      if (m)
+        {
+          proc_texi_buffer (fp, m->value, strlen (m->value),
+                            table_level, eol_action);
+          ignore_args = 1; /* Parameterized macros are not yet supported. */
+        }
+      else
+        inf ("texinfo command '%s' not supported (%.*s)", command,
+             (int)((s = memchr (rest, '\n', len)), (s? (s-rest) : len)), rest);
+    }
+
+  if (*rest == '{')
+    {
+      /* Find matching closing brace.  */
+      for (s=rest+1, n=1, i=1; i && *s && n < len; s++, n++)
+        if (*s == '{')
+          i++;
+        else if (*s == '}')
+          i--;
+      if (i)
+        {
+          err ("closing brace for command '%s' not found", command);
+          return len;
+        }
+      if (n > 2 && !ignore_args)
+        proc_texi_buffer (fp, rest+1, n-2, table_level, eol_action);
+    }
+  else
+    n = 0;
+
+  if (lead_out)
+    fputs (lead_out, fp);
+
+  return n;
+}
+
+
+
+/* Process the string LINE with LEN bytes of Texinfo content. */
+static void
+proc_texi_buffer (FILE *fp, const char *line, size_t len,
+                  int *table_level, int *eol_action)
+{
+  const char *s;
+  char cmdbuf[256];
+  int cmdidx = 0;
+  int in_cmd = 0;
+  size_t n;
+
+  for (s=line; *s && len; s++, len--)
+    {
+      if (in_cmd)
+        {
+          if (in_cmd == 1)
+            {
+              switch (*s)
+                {
+                case '@': case '{': case '}':
+                  putc (*s, fp); in_cmd = 0;
+                  break;
+                case ':': /* Not ending a sentence flag.  */
+                  in_cmd = 0;
+                  break;
+                case '.': case '!': case '?': /* Ending a sentence. */
+                  putc (*s, fp); in_cmd = 0;
+                  break;
+                case ' ': case '\t': case '\n': /* Non collapsing spaces.  */
+                  putc (*s, fp); in_cmd = 0;
+                  break;
+                default:
+                  cmdidx = 0;
+                  cmdbuf[cmdidx++] = *s;
+                  in_cmd++;
+                  break;
+                }
+            }
+          else if (*s == '{' || *s == ' ' || *s == '\t' || *s == '\n')
+            {
+              cmdbuf[cmdidx] = 0;
+              n = proc_texi_cmd (fp, cmdbuf, s, len, table_level, eol_action);
+              assert (n <= len);
+              s += n; len -= n;
+              s--; len++;
+              in_cmd = 0;
+            }
+          else if (cmdidx < sizeof cmdbuf -1)
+            cmdbuf[cmdidx++] = *s;
+          else
+            {
+              err ("texinfo command too long - ignored");
+              in_cmd = 0;
+            }
+        }
+      else if (*s == '@')
+        in_cmd = 1;
+      else if (*s == '\n')
+        {
+          switch (*eol_action)
+            {
+            case 1: /* Create a dummy paragraph. */
+              fputs ("\n\\ \n", fp);
+              break;
+            default:
+              putc (*s, fp);
+            }
+          *eol_action = 0;
+        }
+      else if (*s == '\\')
+        fputs ("\\\\", fp);
+      else
+        putc (*s, fp);
+    }
+
+  if (in_cmd > 1)
+    {
+      cmdbuf[cmdidx] = 0;
+      n = proc_texi_cmd (fp, cmdbuf, s, len, table_level, eol_action);
+      assert (n <= len);
+      s += n; len -= n;
+      s--; len++;
+      /* in_cmd = 0; -- doc only */
+    }
+}
+
+
+/* Do something with the Texinfo line LINE.  */
+static void
+parse_texi_line (FILE *fp, const char *line, int *table_level)
+{
+  int eol_action = 0;
+
+  /* A quick test whether there are any texinfo commands.  */
+  if (!strchr (line, '@'))
+    {
+      fputs (line, fp);
+      putc ('\n', fp);
+      return;
+    }
+  proc_texi_buffer (fp, line, strlen (line), table_level, &eol_action);
+  putc ('\n', fp);
+}
+
+
+/* Write all the lines LINES to FP.  */
+static void
+write_content (FILE *fp, line_buffer_t lines)
+{
+  line_buffer_t line;
+  int table_level = 0;
+
+  for (line = lines; line; line = line->next)
+    {
+      if (line->verbatim)
+        {
+          fputs (line->line, fp);
+          putc ('\n', fp);
+        }
+      else
+        {
+/*           fputs ("TEXI---", fp); */
+/*           fputs (line->line, fp); */
+/*           fputs ("---\n", fp); */
+          parse_texi_line (fp, line->line, &table_level);
+        }
+    }
+}
+
+
+
+static int
+is_standard_section (const char *name)
+{
+  int i;
+  const char *s;
+
+  for (i=0; (s=standard_sections[i]); i++)
+    if (!strcmp (s, name))
+      return 1;
+  return 0;
+}
+
+
+/* Finish a page; that is sort the data and write it out to the file.  */
+static void
+finish_page (void)
+{
+  FILE *fp;
+  section_buffer_t sect = NULL;
+  int idx;
+  const char *s;
+  int i;
+
+  if (!thepage.name)
+    return; /* No page active.  */
+
+  if (verbose)
+    inf ("finishing page '%s'", thepage.name);
+
+  if (opt_select)
+    {
+      if (!strcmp (opt_select, thepage.name))
+        {
+          inf ("selected '%s'", thepage.name );
+          fp = stdout;
+        }
+      else
+        {
+          fp = fopen ( "/dev/null", "w" );
+          if (!fp)
+            die ("failed to open /dev/null: %s\n", strerror (errno));
+        }
+    }
+  else if (opt_store)
+    {
+      inf ("writing '%s'", thepage.name );
+      fp = fopen ( thepage.name, "w" );
+      if (!fp)
+        die ("failed to create '%s': %s\n", thepage.name, strerror (errno));
+    }
+  else
+    fp = stdout;
+
+  if (write_th (fp))
+    goto leave;
+
+  for (idx=0; (s=standard_sections[idx]); idx++)
+    {
+      for (i=0; i < thepage.n_sections; i++)
+        {
+          sect = thepage.sections + i;
+          if (sect->name && !strcmp (s, sect->name))
+            break;
+        }
+      if (i == thepage.n_sections)
+        sect = NULL;
+
+      if (sect)
+        {
+          fprintf (fp, ".SH %s\n", sect->name);
+          write_content (fp, sect->lines);
+          /* Now continue with all non standard sections directly
+             following this one. */
+          for (i++; i < thepage.n_sections; i++)
+            {
+              sect = thepage.sections + i;
+              if (sect->name && is_standard_section (sect->name))
+                break;
+              if (sect->name)
+                {
+                  fprintf (fp, ".SH %s\n", sect->name);
+                  write_content (fp, sect->lines);
+                }
+            }
+
+        }
+    }
+
+
+ leave:
+  if (fp != stdout)
+    fclose (fp);
+  free (thepage.name);
+  thepage.name = NULL;
+  /* FIXME: Cleanup the content.  */
+}
+
+
+
+
+/* Parse one Texinfo file and create manpages according to the
+   embedded instructions.  */
+static void
+parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
+{
+  char *line;
+  int lnr = 0;
+  /* Fixme: The following state variables don't carry over to include
+     files. */
+  int skip_to_end = 0;        /* Used to skip over menu entries. */
+  int skip_sect_line = 0;     /* Skip after @mansect.  */
+  int item_indent = 0;        /* How far is the current @item indented.  */
+
+  /* Helper to define a macro. */
+  char *macroname = NULL;
+  char *macrovalue = NULL;
+  size_t macrovaluesize = 0;
+  size_t macrovalueused = 0;
+
+  line = xmalloc (LINESIZE);
+  while (fgets (line, LINESIZE, fp))
+    {
+      size_t n = strlen (line);
+      int got_line = 0;
+      char *p, *pend;
+
+      lnr++;
+      if (!n || line[n-1] != '\n')
+        {
+          err ("%s:%d: trailing linefeed missing, line too long or "
+               "embedded Nul character", fname, lnr);
+          break;
+        }
+      line[--n] = 0;
+
+      /* Kludge to allow indentation of tables.  */
+      for (p=line; *p == ' ' || *p == '\t'; p++)
+        ;
+      if (*p)
+        {
+          if (*p == '@' && !strncmp (p+1, "item", 4))
+            item_indent = p - line;  /* Set a new indent level.  */
+          else if (p - line < item_indent)
+            item_indent = 0;         /* Switch off indention.  */
+
+          if (item_indent)
+            {
+              memmove (line, line+item_indent, n - item_indent + 1);
+              n -= item_indent;
+            }
+        }
+
+
+      if (*line == '@')
+        {
+          for (p=line+1, n=1; *p && *p != ' ' && *p != '\t'; p++)
+            n++;
+          while (*p == ' ' || *p == '\t')
+            p++;
+        }
+      else
+        p = line;
+
+      /* Take action on macro.  */
+      if (macroname)
+        {
+          if (n == 4 && !memcmp (line, "@end", 4)
+              && (line[4]==' '||line[4]=='\t'||!line[4])
+              && !strncmp (p, "macro", 5)
+              && (p[5]==' '||p[5]=='\t'||!p[5]))
+            {
+              if (macrovalueused)
+                macrovalue[--macrovalueused] = 0; /* Kill the last LF. */
+              macrovalue[macrovalueused] = 0;     /* Terminate macro. */
+              macrovalue = xrealloc (macrovalue, macrovalueused+1);
+
+              set_macro (macroname, macrovalue);
+              macrovalue = NULL;
+              free (macroname);
+              macroname = NULL;
+            }
+          else
+            {
+              if (macrovalueused + strlen (line) + 2 >= macrovaluesize)
+                {
+                  macrovaluesize += strlen (line) + 256;
+                  macrovalue = xrealloc (macrovalue,  macrovaluesize);
+                }
+              strcpy (macrovalue+macrovalueused, line);
+              macrovalueused += strlen (line);
+              macrovalue[macrovalueused++] = '\n';
+            }
+          continue;
+        }
+
+
+      if (n >= 5 && !memcmp (line, "@node", 5)
+          && (line[5]==' '||line[5]=='\t'||!line[5]))
+        {
+          /* Completey ignore @node lines.  */
+          continue;
+        }
+
+
+      if (skip_sect_line)
+        {
+          skip_sect_line = 0;
+          if (!strncmp (line, "@section", 8)
+              || !strncmp (line, "@subsection", 11)
+              || !strncmp (line, "@chapheading", 12))
+            continue;
+        }
+
+      /* We only parse lines we need and ignore the rest.  There are a
+         few macros used to control this as well as one @ifset
+         command.  Parts we know about are saved away into containers
+         separate for each section. */
+
+      /* First process ifset/ifclear commands. */
+      if (*line == '@')
+        {
+          if (n == 6 && !memcmp (line, "@ifset", 6)
+                   && (line[6]==' '||line[6]=='\t'))
+            {
+              for (p=line+7; *p == ' ' || *p == '\t'; p++)
+                ;
+              if (!*p)
+                {
+                  err ("%s:%d: name missing after \"@ifset\"", fname, lnr);
+                  continue;
+                }
+              for (pend=p; *pend && *pend != ' ' && *pend != '\t'; pend++)
+                ;
+              *pend = 0;  /* Ignore rest of the line.  */
+              push_condition (p, 1, fname, lnr);
+              continue;
+            }
+          else if (n == 8 && !memcmp (line, "@ifclear", 8)
+                   && (line[8]==' '||line[8]=='\t'))
+            {
+              for (p=line+9; *p == ' ' || *p == '\t'; p++)
+                ;
+              if (!*p)
+                {
+                  err ("%s:%d: name missing after \"@ifsclear\"", fname, lnr);
+                  continue;
+                }
+              for (pend=p; *pend && *pend != ' ' && *pend != '\t'; pend++)
+                ;
+              *pend = 0;  /* Ignore rest of the line.  */
+              push_condition (p, 0, fname, lnr);
+              continue;
+            }
+          else if (n == 4 && !memcmp (line, "@end", 4)
+                   && (line[4]==' '||line[4]=='\t')
+                   && !strncmp (p, "ifset", 5)
+                   && (p[5]==' '||p[5]=='\t'||!p[5]))
+            {
+              pop_condition (1, fname, lnr);
+              continue;
+            }
+          else if (n == 4 && !memcmp (line, "@end", 4)
+                   && (line[4]==' '||line[4]=='\t')
+                   && !strncmp (p, "ifclear", 7)
+                   && (p[7]==' '||p[7]=='\t'||!p[7]))
+            {
+              pop_condition (0, fname, lnr);
+              continue;
+            }
+        }
+
+      /* Take action on ifset/ifclear.  */
+      if (!cond_is_active)
+        continue;
+
+      /* Process commands. */
+      if (*line == '@')
+        {
+          if (skip_to_end
+              && n == 4 && !memcmp (line, "@end", 4)
+              && (line[4]==' '||line[4]=='\t'||!line[4]))
+            {
+              skip_to_end = 0;
+            }
+          else if (cond_in_verbatim)
+            {
+                got_line = 1;
+            }
+          else if (n == 6 && !memcmp (line, "@macro", 6))
+            {
+              macroname = xstrdup (p);
+              macrovalue = xmalloc ((macrovaluesize = 1024));
+              macrovalueused = 0;
+            }
+          else if (n == 4 && !memcmp (line, "@set", 4))
+            {
+              set_variable (p);
+            }
+          else if (n == 8 && !memcmp (line, "@manpage", 8))
+            {
+              free (*section_name);
+              *section_name = NULL;
+              finish_page ();
+              start_page (p);
+              in_pause = 0;
+            }
+          else if (n == 8 && !memcmp (line, "@mansect", 8))
+            {
+              if (!thepage.name)
+                err ("%s:%d: section outside of a man page", fname, lnr);
+              else
+                {
+                  free (*section_name);
+                  *section_name = ascii_strupr (xstrdup (p));
+                  in_pause = 0;
+                  skip_sect_line = 1;
+                }
+            }
+          else if (n == 9 && !memcmp (line, "@manpause", 9))
+            {
+              if (!*section_name)
+                err ("%s:%d: pausing outside of a man section", fname, lnr);
+              else if (in_pause)
+                err ("%s:%d: already pausing", fname, lnr);
+              else
+                in_pause = 1;
+            }
+          else if (n == 8 && !memcmp (line, "@mancont", 8))
+            {
+              if (!*section_name)
+                err ("%s:%d: continue outside of a man section", fname, lnr);
+              else if (!in_pause)
+                err ("%s:%d: continue while not pausing", fname, lnr);
+              else
+                in_pause = 0;
+            }
+          else if (n == 5 && !memcmp (line, "@menu", 5)
+                   && (line[5]==' '||line[5]=='\t'||!line[5]))
+            {
+              skip_to_end = 1;
+            }
+          else if (n == 8 && !memcmp (line, "@include", 8)
+                   && (line[8]==' '||line[8]=='\t'||!line[8]))
+            {
+              char *incname = xstrdup (p);
+              FILE *incfp = fopen (incname, "r");
+
+              if (!incfp && opt_include && *opt_include && *p != '/')
+                {
+                  free (incname);
+                  incname = xmalloc (strlen (opt_include) + 1
+                                     + strlen (p) + 1);
+                  strcpy (incname, opt_include);
+                  if ( incname[strlen (incname)-1] != '/' )
+                    strcat (incname, "/");
+                  strcat (incname, p);
+                  incfp = fopen (incname, "r");
+                }
+
+              if (!incfp)
+                err ("can't open include file '%s': %s",
+                     incname, strerror (errno));
+              else
+                {
+                  parse_file (incname, incfp, section_name, in_pause);
+                  fclose (incfp);
+                }
+              free (incname);
+            }
+          else if (n == 4 && !memcmp (line, "@bye", 4)
+                   && (line[4]==' '||line[4]=='\t'||!line[4]))
+            {
+              break;
+            }
+          else if (!skip_to_end)
+            got_line = 1;
+        }
+      else if (!skip_to_end)
+        got_line = 1;
+
+      if (got_line && cond_in_verbatim)
+        add_content (*section_name, line, 1);
+      else if (got_line && thepage.name && *section_name && !in_pause)
+        add_content (*section_name, line, 0);
+
+    }
+  if (ferror (fp))
+    err ("%s:%d: read error: %s", fname, lnr, strerror (errno));
+  free (macroname);
+  free (macrovalue);
+  free (line);
+}
+
+
+static void
+top_parse_file (const char *fname, FILE *fp)
+{
+  char *section_name = NULL;  /* Name of the current section or NULL
+                                 if not in a section.  */
+  macro_t m;
+
+  while (macrolist)
+    {
+      macro_t next = macrolist->next;
+      free (macrolist->value);
+      free (macrolist);
+      macrolist = next;
+    }
+  while (variablelist)
+    {
+      macro_t next = variablelist->next;
+      free (variablelist->value);
+      free (variablelist);
+      variablelist = next;
+    }
+  for (m=predefinedmacrolist; m; m = m->next)
+    set_macro (m->name, xstrdup ("1"));
+  cond_is_active = 1;
+  cond_in_verbatim = 0;
+
+  parse_file (fname, fp, &section_name, 0);
+  free (section_name);
+  finish_page ();
+}
+
+
+int
+main (int argc, char **argv)
+{
+  int last_argc = -1;
+  const char *s;
+
+  opt_source = "GNU";
+  opt_release = "";
+
+  /* Define default macros.  The trick is that these macros are not
+     defined when using the actual texinfo renderer. */
+  add_predefined_macro ("isman");
+  add_predefined_macro ("manverb");
+
+  /* Option parsing.  */
+  if (argc)
+    {
+      argc--; argv++;
+    }
+  while (argc && last_argc != argc )
+    {
+      last_argc = argc;
+      if (!strcmp (*argv, "--"))
+        {
+          argc--; argv++;
+          break;
+        }
+      else if (!strcmp (*argv, "--help"))
+        {
+          puts (
+                "Usage: " PGM " [OPTION] [FILE]\n"
+                "Extract man pages from a Texinfo source.\n\n"
+                "  --source NAME    use NAME as source field\n"
+                "  --release STRING use STRING as the release field\n"
+                "  --date EPOCH     use EPOCH as publication date\n"
+                "  --store          write output using @manpage name\n"
+                "  --select NAME    only output pages with @manpage NAME\n"
+                "  --verbose        enable extra informational output\n"
+                "  --debug          enable additional debug output\n"
+                "  --help           display this help and exit\n"
+                "  -I DIR           also search in include DIR\n"
+                "  -D gpgone        the only usable define\n\n"
+                "With no FILE, or when FILE is -, read standard input.\n\n"
+                "Report bugs to <https://bugs.gnupg.org>.");
+          exit (0);
+        }
+      else if (!strcmp (*argv, "--version"))
+        {
+          puts (PGM " " VERSION "\n"
+               "Copyright (C) 2005, 2017 g10 Code GmbH\n"
+               "This program comes with ABSOLUTELY NO WARRANTY.\n"
+               "This is free software, and you are welcome to redistribute it\n"
+                "under certain conditions. See the file COPYING for details.");
+          exit (0);
+        }
+      else if (!strcmp (*argv, "--verbose"))
+        {
+          verbose = 1;
+          argc--; argv++;
+        }
+      else if (!strcmp (*argv, "--quiet"))
+        {
+          quiet = 1;
+          argc--; argv++;
+        }
+      else if (!strcmp (*argv, "--debug"))
+        {
+          verbose = debug = 1;
+          argc--; argv++;
+        }
+      else if (!strcmp (*argv, "--source"))
+        {
+          argc--; argv++;
+          if (argc)
+            {
+              opt_source = *argv;
+              argc--; argv++;
+            }
+        }
+      else if (!strcmp (*argv, "--release"))
+        {
+          argc--; argv++;
+          if (argc)
+            {
+              opt_release = *argv;
+              argc--; argv++;
+            }
+        }
+      else if (!strcmp (*argv, "--date"))
+        {
+          argc--; argv++;
+          if (argc)
+            {
+              opt_date = *argv;
+              argc--; argv++;
+            }
+        }
+      else if (!strcmp (*argv, "--store"))
+        {
+          opt_store = 1;
+          argc--; argv++;
+        }
+      else if (!strcmp (*argv, "--select"))
+        {
+          argc--; argv++;
+          if (argc)
+            {
+              opt_select = strrchr (*argv, '/');
+              if (opt_select)
+                opt_select++;
+              else
+                opt_select = *argv;
+              argc--; argv++;
+            }
+        }
+      else if (!strcmp (*argv, "-I"))
+        {
+          argc--; argv++;
+          if (argc)
+            {
+              opt_include = *argv;
+              argc--; argv++;
+            }
+        }
+      else if (!strcmp (*argv, "-D"))
+        {
+          argc--; argv++;
+          if (argc)
+            {
+              add_predefined_macro (*argv);
+              argc--; argv++;
+            }
+        }
+    }
+
+  if (argc > 1)
+    die ("usage: " PGM " [OPTION] [FILE] (try --help for more information)\n");
+
+  /* Take care of supplied timestamp for reproducible builds.  See
+   * https://reproducible-builds.org/specs/source-date-epoch/  */
+  if (!opt_date && (s = getenv ("SOURCE_DATE_EPOCH")) && *s)
+    opt_date = s;
+
+  /* Start processing. */
+  if (argc && strcmp (*argv, "-"))
+    {
+      FILE *fp = fopen (*argv, "rb");
+      if (!fp)
+        die ("%s:0: can't open file: %s", *argv, strerror (errno));
+      top_parse_file (*argv, fp);
+      fclose (fp);
+    }
+  else
+    top_parse_file ("-", stdin);
+
+  return !!any_error;
+}
+
+
+/*
+Local Variables:
+compile-command: "gcc -Wall -g -Wall -o yat2m yat2m.c"
+End:
+*/
author	SoniEx2 <endermoneymod@gmail.com>	2021-04-09 07:19:03 -0300
committer	SoniEx2 <endermoneymod@gmail.com>	2021-04-09 07:19:03 -0300
commit	0e752a6e215aee21dc73da097c3225495d54a5b6 (patch)
tree	b81be02cbf2f06aebf322ac4a5d014b44176bba5 /libotr/libgcrypt-1.8.7/doc
parent	7754076c715285173311a1b6811ce377950e18a6 (diff)