diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 17:32:43 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 17:32:43 +0000 |
| commit | 6bf0a5cb5034a7e684dcc3500e841785237ce2dd (patch) | |
| tree | a68f146d7fa01f0134297619fbe7e33db084e0aa /comm/third_party/libgcrypt/doc | |
| parent | Initial commit. (diff) | |
| download | thunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.tar.xz thunderbird-6bf0a5cb5034a7e684dcc3500e841785237ce2dd.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 'comm/third_party/libgcrypt/doc')
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 Binary files differnew file mode 100644 index 0000000000..05e5e93f9a --- /dev/null +++ b/comm/third_party/libgcrypt/doc/fips-fsm.pdf diff --git a/comm/third_party/libgcrypt/doc/fips-fsm.png b/comm/third_party/libgcrypt/doc/fips-fsm.png Binary files differnew file mode 100644 index 0000000000..e56aa750c1 --- /dev/null +++ b/comm/third_party/libgcrypt/doc/fips-fsm.png 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 Binary files differnew file mode 100644 index 0000000000..67b75c96c9 --- /dev/null +++ b/comm/third_party/libgcrypt/doc/gcrypt.info-2 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 Binary files differnew file mode 100644 index 0000000000..9722b22366 --- /dev/null +++ b/comm/third_party/libgcrypt/doc/libgcrypt-modules.pdf diff --git a/comm/third_party/libgcrypt/doc/libgcrypt-modules.png b/comm/third_party/libgcrypt/doc/libgcrypt-modules.png Binary files differnew file mode 100644 index 0000000000..c84ef1f6a7 --- /dev/null +++ b/comm/third_party/libgcrypt/doc/libgcrypt-modules.png 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 = §->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, §ion_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: +*/ |
