summaryrefslogtreecommitdiffstats
path: root/comm/third_party/libgcrypt/doc
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 17:32:43 +0000
commit6bf0a5cb5034a7e684dcc3500e841785237ce2dd (patch)
treea68f146d7fa01f0134297619fbe7e33db084e0aa /comm/third_party/libgcrypt/doc
parentInitial commit. (diff)
downloadthunderbird-upstream.tar.xz
thunderbird-upstream.zip
Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--comm/third_party/libgcrypt/doc/ChangeLog-2011488
-rw-r--r--comm/third_party/libgcrypt/doc/DCO29
-rw-r--r--comm/third_party/libgcrypt/doc/HACKING143
-rw-r--r--comm/third_party/libgcrypt/doc/Makefile.am106
-rw-r--r--comm/third_party/libgcrypt/doc/Makefile.in982
-rw-r--r--comm/third_party/libgcrypt/doc/README.apichanges115
-rw-r--r--comm/third_party/libgcrypt/doc/fips-fsm.eps514
-rw-r--r--comm/third_party/libgcrypt/doc/fips-fsm.fig199
-rw-r--r--comm/third_party/libgcrypt/doc/fips-fsm.pdfbin0 -> 12084 bytes
-rw-r--r--comm/third_party/libgcrypt/doc/fips-fsm.pngbin0 -> 6884 bytes
-rw-r--r--comm/third_party/libgcrypt/doc/gcrypt.info135
-rw-r--r--comm/third_party/libgcrypt/doc/gcrypt.info-17269
-rw-r--r--comm/third_party/libgcrypt/doc/gcrypt.info-2bin0 -> 23526 bytes
-rw-r--r--comm/third_party/libgcrypt/doc/gcrypt.texi6944
-rw-r--r--comm/third_party/libgcrypt/doc/gpl.texi392
-rw-r--r--comm/third_party/libgcrypt/doc/lgpl.texi560
-rw-r--r--comm/third_party/libgcrypt/doc/libgcrypt-modules.eps322
-rw-r--r--comm/third_party/libgcrypt/doc/libgcrypt-modules.fig193
-rw-r--r--comm/third_party/libgcrypt/doc/libgcrypt-modules.pdfbin0 -> 6933 bytes
-rw-r--r--comm/third_party/libgcrypt/doc/libgcrypt-modules.pngbin0 -> 2535 bytes
-rw-r--r--comm/third_party/libgcrypt/doc/stamp-vti4
-rw-r--r--comm/third_party/libgcrypt/doc/version.texi4
-rw-r--r--comm/third_party/libgcrypt/doc/yat2m.c1649
23 files changed, 20048 insertions, 0 deletions
diff --git a/comm/third_party/libgcrypt/doc/ChangeLog-2011 b/comm/third_party/libgcrypt/doc/ChangeLog-2011
new file mode 100644
index 0000000000..de837a057a
--- /dev/null
+++ b/comm/third_party/libgcrypt/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/comm/third_party/libgcrypt/doc/DCO b/comm/third_party/libgcrypt/doc/DCO
new file mode 100644
index 0000000000..ee460f6b68
--- /dev/null
+++ b/comm/third_party/libgcrypt/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/comm/third_party/libgcrypt/doc/HACKING b/comm/third_party/libgcrypt/doc/HACKING
new file mode 100644
index 0000000000..0cb8d56098
--- /dev/null
+++ b/comm/third_party/libgcrypt/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/comm/third_party/libgcrypt/doc/Makefile.am b/comm/third_party/libgcrypt/doc/Makefile.am
new file mode 100644
index 0000000000..fd7aac2f45
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/Makefile.am
@@ -0,0 +1,106 @@
+## 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) $(CFLAGS_FOR_BUILD) $(LDFLAGS_FOR_BUILD) \
+ $(CPPFLAGS_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/comm/third_party/libgcrypt/doc/Makefile.in b/comm/third_party/libgcrypt/doc/Makefile.in
new file mode 100644
index 0000000000..90d007d909
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/Makefile.in
@@ -0,0 +1,982 @@
+# 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/ax_cc_for_build.m4 \
+ $(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/socklen.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@
+BUILD_VERSION = @BUILD_VERSION@
+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@
+EXEEXT_FOR_BUILD = @EXEEXT_FOR_BUILD@
+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@
+GPGRT_CONFIG = @GPGRT_CONFIG@
+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@
+LDADD_FOR_TESTS_KLUDGE = @LDADD_FOR_TESTS_KLUDGE@
+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@
+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) $(CFLAGS_FOR_BUILD) $(LDFLAGS_FOR_BUILD) \
+ $(CPPFLAGS_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/comm/third_party/libgcrypt/doc/README.apichanges b/comm/third_party/libgcrypt/doc/README.apichanges
new file mode 100644
index 0000000000..63b64da241
--- /dev/null
+++ b/comm/third_party/libgcrypt/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/comm/third_party/libgcrypt/doc/fips-fsm.eps b/comm/third_party/libgcrypt/doc/fips-fsm.eps
new file mode 100644
index 0000000000..fbb3a90c3f
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/fips-fsm.eps
@@ -0,0 +1,514 @@
+%!PS-Adobe-3.0 EPSF-3.0
+%%Title: /home/wk/s/libgcrypt/doc/fips-fsm.fig
+%%Creator: fig2dev Version 3.2.7a
+%%CreationDate: 2021-02-17 09:16:49
+%%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/comm/third_party/libgcrypt/doc/fips-fsm.fig b/comm/third_party/libgcrypt/doc/fips-fsm.fig
new file mode 100644
index 0000000000..a4f0aeceef
--- /dev/null
+++ b/comm/third_party/libgcrypt/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/comm/third_party/libgcrypt/doc/fips-fsm.pdf b/comm/third_party/libgcrypt/doc/fips-fsm.pdf
new file mode 100644
index 0000000000..05e5e93f9a
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/fips-fsm.pdf
Binary files differ
diff --git a/comm/third_party/libgcrypt/doc/fips-fsm.png b/comm/third_party/libgcrypt/doc/fips-fsm.png
new file mode 100644
index 0000000000..e56aa750c1
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/fips-fsm.png
Binary files differ
diff --git a/comm/third_party/libgcrypt/doc/gcrypt.info b/comm/third_party/libgcrypt/doc/gcrypt.info
new file mode 100644
index 0000000000..8895c16684
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/gcrypt.info
@@ -0,0 +1,135 @@
+This is gcrypt.info, produced by makeinfo version 6.5 from gcrypt.texi.
+
+This manual is for Libgcrypt version 1.9.2 and was last updated 28
+January 2021. Libgcrypt 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: 861
+gcrypt.info-2: 310476
+
+Tag Table:
+(Indirect)
+Node: Top861
+Node: Introduction3413
+Node: Getting Started3785
+Node: Features4665
+Node: Overview5449
+Node: Preparation6072
+Node: Header6995
+Node: Building sources8066
+Node: Building sources using Automake9983
+Node: Initializing the library11911
+Ref: sample-use-suspend-secmem15303
+Ref: sample-use-resume-secmem16146
+Node: Multi-Threading17049
+Ref: Multi-Threading-Footnote-118228
+Node: Enabling FIPS mode18637
+Ref: enabling fips mode18818
+Node: Hardware features20630
+Ref: hardware features20797
+Ref: Hardware features-Footnote-121974
+Node: Generalities22135
+Node: Controlling the library22394
+Node: Error Handling41291
+Node: Error Values43830
+Node: Error Sources48770
+Node: Error Codes51038
+Node: Error Strings54514
+Node: Handler Functions55698
+Node: Progress handler56257
+Node: Allocation handler58406
+Node: Error handler59952
+Node: Logging handler61518
+Node: Symmetric cryptography62110
+Node: Available ciphers62850
+Node: Available cipher modes65997
+Node: Working with cipher handles70062
+Node: General cipher functions81591
+Node: Public Key cryptography85117
+Node: Available algorithms85956
+Node: Used S-expressions86256
+Node: RSA key parameters87381
+Node: DSA key parameters88656
+Node: ECC key parameters89310
+Ref: ecc_keyparam89461
+Node: Cryptographic Functions92467
+Node: Dedicated ECC Functions104442
+Node: General public-key related Functions105586
+Node: Hashing119256
+Node: Available hash algorithms119989
+Node: Working with hash algorithms126342
+Node: Message Authentication Codes140474
+Node: Available MAC algorithms141142
+Node: Working with MAC algorithms147903
+Node: Key Derivation153891
+Node: Random Numbers156293
+Node: Quality of random numbers156576
+Node: Retrieving random numbers157259
+Node: S-expressions158748
+Node: Data types for S-expressions159393
+Node: Working with S-expressions159719
+Node: MPI library174818
+Node: Data types175840
+Node: Basic functions176149
+Node: MPI formats179166
+Node: Calculations182690
+Node: Comparisons185078
+Node: Bit manipulations186081
+Node: EC functions187403
+Ref: gcry_mpi_ec_new190352
+Node: Miscellaneous195911
+Node: Prime numbers200055
+Node: Generation200325
+Node: Checking201612
+Node: Utilities202022
+Node: Memory allocation202399
+Node: Context management203755
+Ref: gcry_ctx_release204193
+Node: Buffer description204354
+Node: Config reporting205141
+Node: Tools206091
+Node: hmac256206258
+Node: Configuration207264
+Node: Architecture210317
+Ref: fig:subsystems211841
+Ref: Architecture-Footnote-1212927
+Ref: Architecture-Footnote-2212989
+Node: Public-Key Subsystem Architecture213073
+Node: Symmetric Encryption Subsystem Architecture215351
+Node: Hashing and MACing Subsystem Architecture216948
+Node: Multi-Precision-Integer Subsystem Architecture219022
+Node: Prime-Number-Generator Subsystem Architecture220460
+Ref: Prime-Number-Generator Subsystem Architecture-Footnote-1222391
+Node: Random-Number Subsystem Architecture222682
+Node: CSPRNG Description225631
+Ref: CSPRNG Description-Footnote-1227187
+Node: FIPS PRNG Description227310
+Node: Self-Tests229444
+Node: FIPS Mode240903
+Ref: fig:fips-fsm244729
+Ref: tbl:fips-states244832
+Ref: tbl:fips-state-transitions246084
+Node: Library Copying249705
+Node: Copying277811
+Node: Figures and Tables296987
+Node: Concept Index297412
+Node: Function and Data Index310476
+
+End Tag Table
diff --git a/comm/third_party/libgcrypt/doc/gcrypt.info-1 b/comm/third_party/libgcrypt/doc/gcrypt.info-1
new file mode 100644
index 0000000000..3bd16f486e
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/gcrypt.info-1
@@ -0,0 +1,7269 @@
+This is gcrypt.info, produced by makeinfo version 6.5 from gcrypt.texi.
+
+This manual is for Libgcrypt version 1.9.2 and was last updated 28
+January 2021. Libgcrypt 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.9.2 and was last updated 28
+January 2021. Libgcrypt 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-sse4.1'
+'intel-pclmul'
+'intel-aesni'
+'intel-rdrand'
+'intel-avx'
+'intel-avx2'
+'intel-fast-vpgather'
+'intel-rdtsc'
+'intel-shaext'
+'arm-neon'
+'arm-aes'
+'arm-sha1'
+'arm-sha2'
+'arm-pmull'
+
+ 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_AUTO_EXPAND_SECMEM; Arguments: unsigned int chunksize'
+ This command enables on-the-fly expanding of the secure memory
+ area. Note that by using functions like 'gcry_xmalloc_secure'
+ and 'gcry_mpi_snew' will do this auto expanding anyway. The
+ argument to this option is the suggested size for new secure
+ memory areas. A larger size improves performance of all
+ memory allocation and releasing functions. The given
+ chunksize is rounded up to the next 32KiB. The drawback of
+ auto expanding is that memory might be swapped out to disk;
+ this can be fixed by configuring the system to use an
+ encrypted swap space.
+
+ '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 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 advise Libgcrypt 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 bits 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 supported key sizes are 8 to 576 bits
+ in 8 bit increments.
+
+'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_GOST28147_MESH'
+ The GOST 28147-89 cipher, defined in the respective GOST standard.
+ Translation of this GOST into English is provided in the RFC-5830.
+ This cipher will use CryptoPro keymeshing as defined in RFC 4357 if
+ it has to be used for the selected parameter set.
+
+'GCRY_CIPHER_CHACHA20'
+ This is the ChaCha20 stream cipher.
+
+'GCRY_CIPHER_SM4'
+ A 128 bit cipher by the State Cryptography Administration of China
+ (SCA). See <https://tools.ietf.org/html/draft-ribose-cfrg-sm4-10>.
+
+
+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-8439. 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.
+
+'GCRY_CIPHER_MODE_EAX'
+ EAX is an Authenticated Encryption with Associated Data (AEAD)
+ block cipher mode by Bellare, Rogaway, and Wagner (see
+ <http://web.cs.ucdavis.edu/~rogaway/papers/eax.html>).
+
+
+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',
+ 'GCRY_CIPHER_MODE_CTR' and 'GCRY_CIPHER_MODE_EAX') 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.
+* Dedicated ECC Functions:: Dedicated functions for elliptic curves.
+* 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), Elgamal, ECDSA, ECDH, and EdDSA.
+
+
+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/handles 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:
+
+'Curve25519'
+'X25519'
+'1.3.6.1.4.1.3029.1.5.1'
+'1.3.101.110'
+ The RFC-8410 255 bit curve, its RFC name, OpenPGP and RFC OIDs.
+
+'X448'
+'1.3.101.111'
+ The RFC-8410 448 bit curve and its RFC OID.
+
+'Ed25519'
+'1.3.6.1.4.1.11591.15.1'
+'1.3.101.112'
+ The signing variant of the RFC-8410 255 bit curve, its OpenPGP and
+ RFC OIDs.
+
+'Ed448'
+'1.3.101.113'
+ The signing variant of the RFC-8410 448 bit curve and its RFC OID.
+
+'NIST P-192'
+'1.2.840.10045.3.1.1'
+'nistp192'
+'prime192v1'
+'secp192r1'
+ The NIST 192 bit curve, its OID and aliases.
+
+'NIST P-224'
+'1.3.132.0.33'
+'nistp224'
+'secp224r1'
+ The NIST 224 bit curve, its OID and aliases.
+
+'NIST P-256'
+'1.2.840.10045.3.1.7'
+'nistp256'
+'prime256v1'
+'secp256r1'
+ The NIST 256 bit curve, its OID and aliases.
+
+'NIST P-384'
+'1.3.132.0.34'
+'nistp384'
+'secp384r1'
+ The NIST 384 bit curve, its OID and aliases.
+
+'NIST P-521'
+'1.3.132.0.35'
+'nistp521'
+'secp521r1'
+ The NIST 521 bit curve, its OID and aliases.
+
+'brainpoolP160r1'
+'1.3.36.3.3.2.8.1.1.1'
+ The Brainpool 160 bit curve and its OID.
+
+'brainpoolP192r1'
+'1.3.36.3.3.2.8.1.1.3'
+ The Brainpool 192 bit curve and its OID.
+
+'brainpoolP224r1'
+'1.3.36.3.3.2.8.1.1.5'
+ The Brainpool 224 bit curve and its OID.
+
+'brainpoolP256r1'
+'1.3.36.3.3.2.8.1.1.7'
+ The Brainpool 256 bit curve and its OID.
+
+'brainpoolP320r1'
+'1.3.36.3.3.2.8.1.1.9'
+ The Brainpool 320 bit curve and its OID.
+
+'brainpoolP384r1'
+'1.3.36.3.3.2.8.1.1.11'
+ The Brainpool 384 bit curve and its OID.
+
+'brainpoolP512r1'
+'1.3.36.3.3.2.8.1.1.13'
+ The Brainpool 512 bit curve and its OID.
+
+ As usual the OIDs may optionally be prefixed with the string 'OID.'
+or 'oid.'.
+
+
+File: gcrypt.info, Node: Cryptographic Functions, Next: Dedicated ECC 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 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 in general 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.
+ Note that for X.509 certificates MESSAGE is the 'tbsCertificate'
+ part and in CMS MESSAGE is the 'signedAttrs' part; see RFC-8410 and
+ RFC-8419.
+
+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: Dedicated ECC Functions, Next: General public-key related Functions, Prev: Cryptographic Functions, Up: Public Key cryptography
+
+6.4 Dedicated functions for elliptic curves.
+============================================
+
+The S-expression based interface is for certain operations on elliptic
+curves not optimal. Thus a few special functions are implemented to
+support common operations on curves with one of these assigned curve
+ids:
+
+'GCRY_ECC_CURVE25519'
+'GCRY_ECC_CURVE448'
+
+ -- Function: unsigned int gcry_ecc_get_algo_keylen (int CURVEID);
+
+ Returns the length in bytes of a point on the curve with the id
+ CURVEID. 0 is returned for curves which have no assigned id.
+
+ -- Function: gpg_error_t gcry_ecc_mul_point (int CURVEID,
+ unsigned char *RESULT, const unsigned char *SCALAR,
+ const unsigned char *POINT)
+
+ This function computes the scalar multiplication on the Montgomery
+ form of the curve with id CURVEID. If POINT is NULL the base point
+ of the curve is used. The caller needs to provide a large enough
+ buffer for RESULT and a valid SCALAR and POINT.
+
+
+File: gcrypt.info, Node: General public-key related Functions, Prev: Dedicated ECC Functions, Up: Public Key cryptography
+
+6.5 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_NENCR'
+ 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-512 algorithm which yields a message digest of 64
+ bytes. See FIPS 180-2 for the specification.
+
+'GCRY_MD_SHA512_224'
+ This is the SHA-512/224 algorithm which yields a message digest of
+ 28 bytes. See FIPS 180-4 for the specification.
+
+'GCRY_MD_SHA512_256'
+ This is the SHA-512/256 algorithm which yields a message digest of
+ 32 bytes. See FIPS 180-4 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.
+
+'GCRY_MD_SM3'
+ This is the SM3 algorithm which yields a message digest of 32
+ bytes.
+
+
+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_SHA512_224'
+ This is HMAC message authentication algorithm based on the
+ SHA-512/224 hash algorithm.
+
+'GCRY_MAC_HMAC_SHA512_256'
+ This is HMAC message authentication algorithm based on the
+ SHA-512/256 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_HMAC_BLAKE2B_512'
+ This is HMAC message authentication algorithm based on the
+ BLAKE2b-512 hash algorithm.
+
+'GCRY_MAC_HMAC_BLAKE2B_384'
+ This is HMAC message authentication algorithm based on the
+ BLAKE2b-384 hash algorithm.
+
+'GCRY_MAC_HMAC_BLAKE2B_256'
+ This is HMAC message authentication algorithm based on the
+ BLAKE2b-256 hash algorithm.
+
+'GCRY_MAC_HMAC_BLAKE2B_160'
+ This is HMAC message authentication algorithm based on the
+ BLAKE2b-160 hash algorithm.
+
+'GCRY_MAC_HMAC_BLAKE2S_256'
+ This is HMAC message authentication algorithm based on the
+ BLAKE2s-256 hash algorithm.
+
+'GCRY_MAC_HMAC_BLAKE2S_224'
+ This is HMAC message authentication algorithm based on the
+ BLAKE2s-224 hash algorithm.
+
+'GCRY_MAC_HMAC_BLAKE2S_160'
+ This is HMAC message authentication algorithm based on the
+ BLAKE2s-160 hash algorithm.
+
+'GCRY_MAC_HMAC_BLAKE2S_128'
+ This is HMAC message authentication algorithm based on the
+ BLAKE2s-128 hash algorithm.
+
+'GCRY_MAC_HMAC_SM3'
+ This is HMAC message authentication algorithm based on the SM3 hash
+ algorithm.
+
+'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_CMAC_SM4'
+ This is CMAC message authentication algorithm based on the SM4
+ 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.
+
+'GCRY_MAC_GOST28147_IMIT'
+ This is MAC construction defined in GOST 28147-89 (see RFC 5830
+ Section 8).
+
+
+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 and character sequences 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.
+ '%s'
+ Switch to string mode. The expected argument is the address
+ of a 'char *' variable; the caller must release that value.
+ If the parameter was marked optional and is not found, NULL is
+ stored.
+ '%#s'
+ Switch to multi string mode. The expected argument is the
+ address of a 'char *' variable; the caller must release that
+ value. If the parameter was marked optional and is not found,
+ NULL is stored. A multi string takes all values, assumes they
+ are strings and concatenates them using a space as delimiter.
+ In case a value is actually another list this is not further
+ parsed but a '()' is inserted in place of that sublist.
+ '%u'
+ Switch to unsigned integer mode. The expected argument is
+ address of a 'unsigned int' variable.
+ '%lu'
+ Switch to unsigned long integer mode. The expected argument
+ is address of a 'unsigned long' variable.
+ '%d'
+ Switch to signed integer mode. The expected argument is
+ address of a 'int' variable.
+ '%ld'
+ Switch to signed long integer mode. The expected argument is
+ address of a 'long' variable.
+ '%zu'
+ Switch to size_t mode. The expected argument is address of a
+ 'size_t' variable.
+ '?'
+ 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: gcry_error_t gcry_mpi_get_ui (unsigned int *W,
+ gcry_mpi_t U)
+
+ If U is not negative and small enough to be stored in an 'unsigned
+ int' variable, store its value at W. If the value does not fit or
+ is negative return GPG_ERR_ERANGE and do not change the value
+ stored at W. Note that this function returns an 'unsigned int' so
+ that this value can immediately be used with the bit test
+ functions. This is in contrast to the other "_ui" functions which
+ allow for values up to an 'unsigned long'.
+
+ -- 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 is either negative for floored division
+ (rounds towards the next lower integer) or zero for truncated
+ division (rounds towards zero).
+
+ -- 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 internal flag, indicating the an opaque valuue and not
+ an integer is stored. This is an read-only flag; it may not be set
+ or cleared.
+'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 is no strict alignment requirements for data, but the best
+ performance can be archived if data is aligned to cacheline
+ boundary.
+
+ 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.
+
+ There is no strict alignment requirements for data, but the best
+ performance can be archived if data is aligned to cacheline
+ boundary.
+
+'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 98)
+* 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)
+* EAX, EAX mode: Available cipher modes.
+ (line 89)
+* 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)
+* GOST 28147-89 CryptoPro keymeshing: Available ciphers. (line 92)
+* 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-BLAKE2s, HMAC-BLAKE2b: Available MAC algorithms.
+ (line 6)
+* 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-SHA-512/224, HMAC-SHA-512/256: Available MAC algorithms.
+ (line 6)
+* HMAC-SHA3-224, HMAC-SHA3-256, HMAC-SHA3-384, HMAC-SHA3-512: Available MAC algorithms.
+ (line 6)
+* HMAC-SM3: 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, SHA-512/224, SHA-512/256: Available hash algorithms.
+ (line 6)
+* SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256: Available hash algorithms.
+ (line 6)
+* SM3: Available hash algorithms.
+ (line 6)
+* SM4 (cipher): Available ciphers. (line 101)
+* 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/comm/third_party/libgcrypt/doc/gcrypt.info-2 b/comm/third_party/libgcrypt/doc/gcrypt.info-2
new file mode 100644
index 0000000000..67b75c96c9
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/gcrypt.info-2
Binary files differ
diff --git a/comm/third_party/libgcrypt/doc/gcrypt.texi b/comm/third_party/libgcrypt/doc/gcrypt.texi
new file mode 100644
index 0000000000..11c1549f4e
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/gcrypt.texi
@@ -0,0 +1,6944 @@
+\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} and was last
+updated @value{UPDATED}. Libgcrypt 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-sse4.1
+@item intel-pclmul
+@item intel-aesni
+@item intel-rdrand
+@item intel-avx
+@item intel-avx2
+@item intel-fast-vpgather
+@item intel-rdtsc
+@item intel-shaext
+@item arm-neon
+@item arm-aes
+@item arm-sha1
+@item arm-sha2
+@item arm-pmull
+@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_AUTO_EXPAND_SECMEM; Arguments: unsigned int chunksize
+This command enables on-the-fly expanding of the secure memory area.
+Note that by using functions like @code{gcry_xmalloc_secure} and
+@code{gcry_mpi_snew} will do this auto expanding anyway. The argument
+to this option is the suggested size for new secure memory areas. A
+larger size improves performance of all memory allocation and
+releasing functions. The given chunksize is rounded up to the next
+32KiB. The drawback of auto expanding is that memory might be swapped
+out to disk; this can be fixed by configuring the system to use an
+encrypted swap space.
+
+@item GCRYCTL_TERM_SECMEM; Arguments: none
+This command zeroises the secure memory and destroys the handler. The
+secure memory pool may not be used anymore after running this command.
+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 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 advise Libgcrypt 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 bits 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 supported key sizes are 8 to 576 bits in
+8 bit increments.
+
+@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_GOST28147_MESH
+@cindex GOST 28147-89 CryptoPro keymeshing
+The GOST 28147-89 cipher, defined in the respective GOST standard.
+Translation of this GOST into English is provided in the RFC-5830.
+This cipher will use CryptoPro keymeshing as defined in RFC 4357
+if it has to be used for the selected parameter set.
+
+@item GCRY_CIPHER_CHACHA20
+@cindex ChaCha20
+This is the ChaCha20 stream cipher.
+
+@item GCRY_CIPHER_SM4
+@cindex SM4 (cipher)
+A 128 bit cipher by the State Cryptography Administration
+of China (SCA). See
+@uref{https://tools.ietf.org/html/draft-ribose-cfrg-sm4-10}.
+
+@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-8439. This mode can be used with ChaCha20
+stream cipher.
+
+@item GCRY_CIPHER_MODE_OCB
+@cindex OCB, OCB3
+OCB is an Authenticated Encryption with Associated Data (AEAD) block
+cipher mode, which is specified in RFC-7253. Supported tag lengths
+are 128, 96, and 64 bit with the default being 128 bit. To switch to
+a different tag length @code{gcry_cipher_ctl} using the command
+@code{GCRYCTL_SET_TAGLEN} and the address of an @code{int} variable
+set to 12 (for 96 bit) or 8 (for 64 bit) provided for the
+@code{buffer} argument and @code{sizeof(int)} for @code{buflen}.
+
+Note that the use of @code{gcry_cipher_final} is required.
+
+@item GCRY_CIPHER_MODE_XTS
+@cindex XTS, XTS mode
+XEX-based tweaked-codebook mode with ciphertext stealing (XTS) mode
+is used to implement the AES-XTS as specified in IEEE 1619 Standard
+Architecture for Encrypted Shared Storage Media and NIST SP800-38E.
+
+The XTS mode requires doubling key-length, for example, using 512-bit
+key with AES-256 (@code{GCRY_CIPHER_AES256}). The 128-bit tweak value
+is feed to XTS mode as little-endian byte array using
+@code{gcry_cipher_setiv} function. When encrypting or decrypting,
+full-sized data unit buffers needs to be passed to
+@code{gcry_cipher_encrypt} or @code{gcry_cipher_decrypt}. The tweak
+value is automatically incremented after each call of
+@code{gcry_cipher_encrypt} and @code{gcry_cipher_decrypt}.
+Auto-increment allows avoiding need of setting IV between processing
+of sequential data units.
+
+@item GCRY_CIPHER_MODE_EAX
+@cindex EAX, EAX mode
+EAX is an Authenticated Encryption with Associated Data (AEAD) block cipher
+mode by Bellare, Rogaway, and Wagner (see
+@uref{http://web.cs.ucdavis.edu/~rogaway/papers/eax.html}).
+
+@end table
+
+@node Working with cipher handles
+@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},
+@code{GCRY_CIPHER_MODE_CTR} and @code{GCRY_CIPHER_MODE_EAX}) will work
+with any block cipher algorithm. GCM mode
+(@code{GCRY_CIPHER_MODE_CCM}), CCM mode (@code{GCRY_CIPHER_MODE_GCM}),
+OCB mode (@code{GCRY_CIPHER_MODE_OCB}), and XTS mode
+(@code{GCRY_CIPHER_MODE_XTS}) will only work with block cipher
+algorithms which have the block size of 16 bytes.
+
+The third argument @var{flags} can either be passed as @code{0} or as
+the bit-wise OR of the following constants.
+
+@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.
+* Dedicated ECC Functions:: Dedicated functions for elliptic curves.
+* 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), Elgamal, ECDSA, ECDH, and EdDSA.
+
+@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/handles 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 Curve25519
+@itemx X25519
+@itemx 1.3.6.1.4.1.3029.1.5.1
+@itemx 1.3.101.110
+The RFC-8410 255 bit curve, its RFC name, OpenPGP and RFC OIDs.
+
+@item X448
+@itemx 1.3.101.111
+The RFC-8410 448 bit curve and its RFC OID.
+
+@item Ed25519
+@itemx 1.3.6.1.4.1.11591.15.1
+@itemx 1.3.101.112
+The signing variant of the RFC-8410 255 bit curve, its OpenPGP and RFC OIDs.
+
+@item Ed448
+@itemx 1.3.101.113
+The signing variant of the RFC-8410 448 bit curve and its RFC OID.
+
+@item NIST P-192
+@itemx 1.2.840.10045.3.1.1
+@itemx nistp192
+@itemx prime192v1
+@itemx secp192r1
+The NIST 192 bit curve, its OID and aliases.
+
+@item NIST P-224
+@itemx 1.3.132.0.33
+@itemx nistp224
+@itemx secp224r1
+The NIST 224 bit curve, its OID and aliases.
+
+@item NIST P-256
+@itemx 1.2.840.10045.3.1.7
+@itemx nistp256
+@itemx prime256v1
+@itemx secp256r1
+The NIST 256 bit curve, its OID and aliases.
+
+@item NIST P-384
+@itemx 1.3.132.0.34
+@itemx nistp384
+@itemx secp384r1
+The NIST 384 bit curve, its OID and aliases.
+
+@item NIST P-521
+@itemx 1.3.132.0.35
+@itemx nistp521
+@itemx secp521r1
+The NIST 521 bit curve, its OID and aliases.
+
+@item brainpoolP160r1
+@itemx 1.3.36.3.3.2.8.1.1.1
+The Brainpool 160 bit curve and its OID.
+
+@item brainpoolP192r1
+@itemx 1.3.36.3.3.2.8.1.1.3
+The Brainpool 192 bit curve and its OID.
+
+@item brainpoolP224r1
+@itemx 1.3.36.3.3.2.8.1.1.5
+The Brainpool 224 bit curve and its OID.
+
+@item brainpoolP256r1
+@itemx 1.3.36.3.3.2.8.1.1.7
+The Brainpool 256 bit curve and its OID.
+
+@item brainpoolP320r1
+@itemx 1.3.36.3.3.2.8.1.1.9
+The Brainpool 320 bit curve and its OID.
+
+@item brainpoolP384r1
+@itemx 1.3.36.3.3.2.8.1.1.11
+The Brainpool 384 bit curve and its OID.
+
+@item brainpoolP512r1
+@itemx 1.3.36.3.3.2.8.1.1.13
+The Brainpool 512 bit curve and its OID.
+
+@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 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 in
+general 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. Note that for X.509 certificates @var{message} is the
+@code{tbsCertificate} part and in CMS @var{message} is the
+@code{signedAttrs} part; see RFC-8410 and RFC-8419.
+
+
+@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 Dedicated ECC Functions
+@section Dedicated functions for elliptic curves.
+
+@noindent
+The S-expression based interface is for certain operations on elliptic
+curves not optimal. Thus a few special functions are implemented to
+support common operations on curves with one of these assigned curve
+ids:
+
+@table @code
+@item GCRY_ECC_CURVE25519
+@item GCRY_ECC_CURVE448
+@end table
+
+@deftypefun @w{unsigned int} gcry_ecc_get_algo_keylen (@w{int @var{curveid}});
+
+Returns the length in bytes of a point on the curve with the id
+@var{curveid}. 0 is returned for curves which have no assigned id.
+@end deftypefun
+
+
+@deftypefun gpg_error_t gcry_ecc_mul_point @
+ (@w{int @var{curveid}}, @
+ @w{unsigned char *@var{result}}, @
+ @w{const unsigned char *@var{scalar}}, @
+ @w{const unsigned char *@var{point}})
+
+This function computes the scalar multiplication on the Montgomery
+form of the curve with id @var{curveid}. If @var{point} is NULL the
+base point of the curve is used. The caller needs to provide a large
+enough buffer for @var{result} and a valid @var{scalar} and
+@var{point}.
+@end deftypefun
+
+
+@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_NENCR
+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, SHA-512/224, SHA-512/256
+@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 SM3
+@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-512 algorithm which yields a message digest of 64 bytes.
+See FIPS 180-2 for the specification.
+
+@item GCRY_MD_SHA512_224
+This is the SHA-512/224 algorithm which yields a message digest of 28 bytes.
+See FIPS 180-4 for the specification.
+
+@item GCRY_MD_SHA512_256
+This is the SHA-512/256 algorithm which yields a message digest of 32 bytes.
+See FIPS 180-4 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.
+
+@item GCRY_MD_SM3
+This is the SM3 algorithm which yields a message digest of 32 bytes.
+
+@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-SHA-512/224, HMAC-SHA-512/256
+@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-SM3
+@cindex HMAC-Whirlpool
+@cindex HMAC-Stribog-256, HMAC-Stribog-512
+@cindex HMAC-GOSTR-3411-94
+@cindex HMAC-BLAKE2s, HMAC-BLAKE2b
+@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_SHA512_224
+This is HMAC message authentication algorithm based on the SHA-512/224 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_SHA512_256
+This is HMAC message authentication algorithm based on the SHA-512/256 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_HMAC_BLAKE2B_512
+This is HMAC message authentication algorithm based on the BLAKE2b-512 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_BLAKE2B_384
+This is HMAC message authentication algorithm based on the BLAKE2b-384 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_BLAKE2B_256
+This is HMAC message authentication algorithm based on the BLAKE2b-256 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_BLAKE2B_160
+This is HMAC message authentication algorithm based on the BLAKE2b-160 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_BLAKE2S_256
+This is HMAC message authentication algorithm based on the BLAKE2s-256 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_BLAKE2S_224
+This is HMAC message authentication algorithm based on the BLAKE2s-224 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_BLAKE2S_160
+This is HMAC message authentication algorithm based on the BLAKE2s-160 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_BLAKE2S_128
+This is HMAC message authentication algorithm based on the BLAKE2s-128 hash
+algorithm.
+
+@item GCRY_MAC_HMAC_SM3
+This is HMAC message authentication algorithm based on the SM3 hash
+algorithm.
+
+@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_CMAC_SM4
+This is CMAC message authentication algorithm based on the SM4
+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.
+
+@item GCRY_MAC_GOST28147_IMIT
+This is MAC construction defined in GOST 28147-89 (see RFC 5830 Section 8).
+
+@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
+and character sequences 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 %s
+Switch to string mode. The expected argument is the address of a
+@code{char *} variable; the caller must release that value. If the
+parameter was marked optional and is not found, NULL is stored.
+@item %#s
+Switch to multi string mode. The expected argument is the address of a
+@code{char *} variable; the caller must release that value. If the
+parameter was marked optional and is not found, NULL is stored. A
+multi string takes all values, assumes they are strings and
+concatenates them using a space as delimiter. In case a value is
+actually another list this is not further parsed but a @code{()} is
+inserted in place of that sublist.
+@item %u
+Switch to unsigned integer mode. The expected argument is address of
+a @code{unsigned int} variable.
+@item %lu
+Switch to unsigned long integer mode. The expected argument is address of
+a @code{unsigned long} variable.
+@item %d
+Switch to signed integer mode. The expected argument is address of
+a @code{int} variable.
+@item %ld
+Switch to signed long integer mode. The expected argument is address of
+a @code{long} variable.
+@item %zu
+Switch to size_t mode. The expected argument is address of
+a @code{size_t} variable.
+@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 gcry_error_t gcry_mpi_get_ui (@w{unsigned int *@var{w}}, @w{gcry_mpi_t @var{u}})
+
+If @var{u} is not negative and small enough to be stored in an
+@code{unsigned int} variable, store its value at @var{w}. If the
+value does not fit or is negative return GPG_ERR_ERANGE and do not
+change the value stored at @var{w}. Note that this function returns
+an @code{unsigned int} so that this value can immediately be used with
+the bit test functions. This is in contrast to the other "_ui"
+functions which allow for values up to an @code{unsigned long}.
+@end deftypefun
+
+
+@deftypefun void gcry_mpi_swap (@w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
+
+Swap the values of @var{a} and @var{b}.
+@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} is either negative for floored division
+(rounds towards the next lower integer) or zero for truncated division
+(rounds towards zero).
+@end deftypefun
+
+@deftypefun void gcry_mpi_mod (@w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}})
+
+@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 internal flag, indicating the an opaque valuue and not an
+integer is stored. This is an read-only flag; it may not be set or
+cleared.
+@item GCRYMPI_FLAG_IMMUTABLE
+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.
+
+There is no strict alignment requirements for data, but the best
+performance can be archived if data is aligned to cacheline boundary.
+
+@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.
+
+There is no strict alignment requirements for data, but the best
+performance can be archived if data is aligned to cacheline boundary.
+
+@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/comm/third_party/libgcrypt/doc/gpl.texi b/comm/third_party/libgcrypt/doc/gpl.texi
new file mode 100644
index 0000000000..6eb301e2b2
--- /dev/null
+++ b/comm/third_party/libgcrypt/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/comm/third_party/libgcrypt/doc/lgpl.texi b/comm/third_party/libgcrypt/doc/lgpl.texi
new file mode 100644
index 0000000000..bbd18a006f
--- /dev/null
+++ b/comm/third_party/libgcrypt/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/comm/third_party/libgcrypt/doc/libgcrypt-modules.eps b/comm/third_party/libgcrypt/doc/libgcrypt-modules.eps
new file mode 100644
index 0000000000..d015cb6b5f
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/libgcrypt-modules.eps
@@ -0,0 +1,322 @@
+%!PS-Adobe-3.0 EPSF-3.0
+%%Title: /home/wk/s/libgcrypt/doc/libgcrypt-modules.fig
+%%Creator: fig2dev Version 3.2.7a
+%%CreationDate: 2021-02-17 09:16:49
+%%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/comm/third_party/libgcrypt/doc/libgcrypt-modules.fig b/comm/third_party/libgcrypt/doc/libgcrypt-modules.fig
new file mode 100644
index 0000000000..ea3d05372a
--- /dev/null
+++ b/comm/third_party/libgcrypt/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/comm/third_party/libgcrypt/doc/libgcrypt-modules.pdf b/comm/third_party/libgcrypt/doc/libgcrypt-modules.pdf
new file mode 100644
index 0000000000..9722b22366
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/libgcrypt-modules.pdf
Binary files differ
diff --git a/comm/third_party/libgcrypt/doc/libgcrypt-modules.png b/comm/third_party/libgcrypt/doc/libgcrypt-modules.png
new file mode 100644
index 0000000000..c84ef1f6a7
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/libgcrypt-modules.png
Binary files differ
diff --git a/comm/third_party/libgcrypt/doc/stamp-vti b/comm/third_party/libgcrypt/doc/stamp-vti
new file mode 100644
index 0000000000..37de05924c
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/stamp-vti
@@ -0,0 +1,4 @@
+@set UPDATED 28 January 2021
+@set UPDATED-MONTH January 2021
+@set EDITION 1.9.2
+@set VERSION 1.9.2
diff --git a/comm/third_party/libgcrypt/doc/version.texi b/comm/third_party/libgcrypt/doc/version.texi
new file mode 100644
index 0000000000..37de05924c
--- /dev/null
+++ b/comm/third_party/libgcrypt/doc/version.texi
@@ -0,0 +1,4 @@
+@set UPDATED 28 January 2021
+@set UPDATED-MONTH January 2021
+@set EDITION 1.9.2
+@set VERSION 1.9.2
diff --git a/comm/third_party/libgcrypt/doc/yat2m.c b/comm/third_party/libgcrypt/doc/yat2m.c
new file mode 100644
index 0000000000..3c7b363558
--- /dev/null
+++ b/comm/third_party/libgcrypt/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:
+*/