diff options
Diffstat (limited to 'plugins/MirOTR/libgcrypt-1.4.6/doc')
25 files changed, 0 insertions, 24229 deletions
diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/ChangeLog b/plugins/MirOTR/libgcrypt-1.4.6/doc/ChangeLog deleted file mode 100644 index e0843c5cb5..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/ChangeLog +++ /dev/null @@ -1,455 +0,0 @@ -2009-07-09 Werner Koch <wk@g10code.com> - - * gcrypt.texi (Working with S-expressions): Describe format - character '%S'. Typo fixes. - (gcry_cipher_close, gcry_md_close) - (gcry_sexp_release): Explicitly mention zeroisation. - -2009-04-02 Werner Koch <wk@g10code.com> - - * gcrypt.texi (Self-Tests): Fix name of register functions. - -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. diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/HACKING b/plugins/MirOTR/libgcrypt-1.4.6/doc/HACKING deleted file mode 100644 index 51380b172c..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/HACKING +++ /dev/null @@ -1,66 +0,0 @@ - Various hacking notes -*- text -*- - ======================= - - -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. - - -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/plugins/MirOTR/libgcrypt-1.4.6/doc/Makefile.am b/plugins/MirOTR/libgcrypt-1.4.6/doc/Makefile.am deleted file mode 100644 index f25106438e..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/Makefile.am +++ /dev/null @@ -1,71 +0,0 @@ -## 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 \ - libgcrypt-modules.eps fips-fsm.eps \ - libgcrypt-modules.png fips-fsm.png \ - libgcrypt-modules.pdf fips-fsm.pdf - -DISTCLEANFILES = gcrypt.cps - -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 - - -.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)/'`$< $@ - - -# 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. -gnupg.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/plugins/MirOTR/libgcrypt-1.4.6/doc/Makefile.in b/plugins/MirOTR/libgcrypt-1.4.6/doc/Makefile.in deleted file mode 100644 index 56acfbe4e2..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/Makefile.in +++ /dev/null @@ -1,699 +0,0 @@ -# Makefile.in generated by automake 1.10.2 from Makefile.am. -# @configure_input@ - -# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -# 2003, 2004, 2005, 2006, 2007, 2008 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@ -pkgdatadir = $(datadir)/@PACKAGE@ -pkglibdir = $(libdir)/@PACKAGE@ -pkgincludedir = $(includedir)/@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 -DIST_COMMON = $(gcrypt_TEXINFOS) $(srcdir)/Makefile.am \ - $(srcdir)/Makefile.in $(srcdir)/stamp-vti \ - $(srcdir)/version.texi ChangeLog mdate-sh texinfo.tex -ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 -am__aclocal_m4_deps = $(top_srcdir)/m4/libtool.m4 \ - $(top_srcdir)/m4/noexecstack.m4 $(top_srcdir)/m4/onceonly.m4 \ - $(top_srcdir)/m4/socklen.m4 $(top_srcdir)/m4/sys_socket_h.m4 \ - $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac -am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ - $(ACLOCAL_M4) -mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs -CONFIG_HEADER = $(top_builddir)/config.h -CONFIG_CLEAN_FILES = -SOURCES = -DIST_SOURCES = -INFO_DEPS = $(srcdir)/gcrypt.info -am__TEXINFO_TEX_DIR = $(srcdir) -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__installdirs = "$(DESTDIR)$(infodir)" -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 = `echo $$p | sed -e 's|^.*/||'`; -DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) -ACLOCAL = @ACLOCAL@ -AMTAR = @AMTAR@ -AR = @AR@ -AS = @AS@ -AUTOCONF = @AUTOCONF@ -AUTOHEADER = @AUTOHEADER@ -AUTOMAKE = @AUTOMAKE@ -AWK = @AWK@ -BUILD_FILEVERSION = @BUILD_FILEVERSION@ -BUILD_REVISION = @BUILD_REVISION@ -BUILD_TIMESTAMP = @BUILD_TIMESTAMP@ -CC = @CC@ -CCAS = @CCAS@ -CCASDEPMODE = @CCASDEPMODE@ -CCASFLAGS = @CCASFLAGS@ -CCDEPMODE = @CCDEPMODE@ -CFLAGS = @CFLAGS@ -CPP = @CPP@ -CPPFLAGS = @CPPFLAGS@ -CXX = @CXX@ -CXXCPP = @CXXCPP@ -CXXDEPMODE = @CXXDEPMODE@ -CXXFLAGS = @CXXFLAGS@ -CYGPATH_W = @CYGPATH_W@ -DEFS = @DEFS@ -DEPDIR = @DEPDIR@ -DLLTOOL = @DLLTOOL@ -DL_LIBS = @DL_LIBS@ -ECHO = @ECHO@ -ECHO_C = @ECHO_C@ -ECHO_N = @ECHO_N@ -ECHO_T = @ECHO_T@ -EGREP = @EGREP@ -EXEEXT = @EXEEXT@ -F77 = @F77@ -FALLBACK_SOCKLEN_T = @FALLBACK_SOCKLEN_T@ -FFLAGS = @FFLAGS@ -GCRYPT_CIPHERS = @GCRYPT_CIPHERS@ -GCRYPT_DIGESTS = @GCRYPT_DIGESTS@ -GCRYPT_PUBKEY_CIPHERS = @GCRYPT_PUBKEY_CIPHERS@ -GCRYPT_RANDOM = @GCRYPT_RANDOM@ -GPG_ERROR_CFLAGS = @GPG_ERROR_CFLAGS@ -GPG_ERROR_CONFIG = @GPG_ERROR_CONFIG@ -GPG_ERROR_LIBS = @GPG_ERROR_LIBS@ -GREP = @GREP@ -INSTALL = @INSTALL@ -INSTALL_DATA = @INSTALL_DATA@ -INSTALL_PROGRAM = @INSTALL_PROGRAM@ -INSTALL_SCRIPT = @INSTALL_SCRIPT@ -INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ -LDFLAGS = @LDFLAGS@ -LIBGCRYPT_CIPHERS = @LIBGCRYPT_CIPHERS@ -LIBGCRYPT_CONFIG_API_VERSION = @LIBGCRYPT_CONFIG_API_VERSION@ -LIBGCRYPT_CONFIG_CFLAGS = @LIBGCRYPT_CONFIG_CFLAGS@ -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@ -LN_S = @LN_S@ -LTLIBOBJS = @LTLIBOBJS@ -MAINT = @MAINT@ -MAKEINFO = @MAKEINFO@ -MKDIR_P = @MKDIR_P@ -MPI_SFLAGS = @MPI_SFLAGS@ -NOEXECSTACK_FLAGS = @NOEXECSTACK_FLAGS@ -OBJDUMP = @OBJDUMP@ -OBJEXT = @OBJEXT@ -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@ -SET_MAKE = @SET_MAKE@ -SHELL = @SHELL@ -STRIP = @STRIP@ -SYS_SOCKET_H = @SYS_SOCKET_H@ -VERSION = @VERSION@ -abs_builddir = @abs_builddir@ -abs_srcdir = @abs_srcdir@ -abs_top_builddir = @abs_top_builddir@ -abs_top_srcdir = @abs_top_srcdir@ -ac_ct_CC = @ac_ct_CC@ -ac_ct_CXX = @ac_ct_CXX@ -ac_ct_F77 = @ac_ct_F77@ -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@ -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@ -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 \ - libgcrypt-modules.eps fips-fsm.eps \ - libgcrypt-modules.png fips-fsm.png \ - libgcrypt-modules.pdf fips-fsm.pdf - -DISTCLEANFILES = gcrypt.cps -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 -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'; \ - cd $(top_srcdir) && \ - $(AUTOMAKE) --gnu doc/Makefile -.PRECIOUS: 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__depfiles_maybe)'; \ - cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ - 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 - -mostlyclean-libtool: - -rm -f *.lo - -clean-libtool: - -rm -rf .libs _libs - -.texi.info: - restore=: && backupdir="$(am__leading_dot)am$$$$" && \ - am__cwd=`pwd` && 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; \ - cd $(srcdir); \ - else \ - rc=$$?; \ - cd $(srcdir) && \ - $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ - fi; \ - rm -rf $$backupdir; exit $$rc - -.texi.dvi: - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2DVI) $< - -.texi.pdf: - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2PDF) $< - -.texi.html: - rm -rf $(@:.html=.htp) - if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $(@:.html=.htp) $<; \ - then \ - rm -rf $@; \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ - else \ - if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ - rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ - 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) $(srcdir)/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) - -@rm -f vti.tmp - @cp $(srcdir)/version.texi $@ - -mostlyclean-vti: - -rm -f vti.tmp - -maintainer-clean-vti: -@MAINTAINER_MODE_TRUE@ -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi -.dvi.ps: - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - $(DVIPS) -o $@ $< - -uninstall-dvi-am: - @$(NORMAL_UNINSTALL) - @list='$(DVIS)'; for p in $$list; do \ - f=$(am__strip_dir) \ - echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ - rm -f "$(DESTDIR)$(dvidir)/$$f"; \ - done - -uninstall-html-am: - @$(NORMAL_UNINSTALL) - @list='$(HTMLS)'; for p in $$list; do \ - f=$(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)' && \ - (install-info --version && \ - install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; 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'"; \ - install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ - 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)'; for p in $$list; do \ - f=$(am__strip_dir) \ - echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ - rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ - done - -uninstall-ps-am: - @$(NORMAL_UNINSTALL) - @list='$(PSS)'; for p in $$list; do \ - f=$(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.aux gcrypt.cp gcrypt.cps gcrypt.fn gcrypt.fns gcrypt.ky \ - gcrypt.kys gcrypt.log gcrypt.pg gcrypt.tmp gcrypt.toc \ - gcrypt.tp gcrypt.vr gcrypt.vrs 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 -tags: TAGS -TAGS: - -ctags: CTAGS -CTAGS: - - -distdir: $(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 $(srcdir)/$$file && test $$d != $(srcdir); then \ - cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ - fi; \ - cp -pR $$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) -installdirs: - for dir in "$(DESTDIR)$(infodir)"; 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: - $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ - install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ - `test -z '$(STRIP)' || \ - echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install -mostlyclean-generic: - -clean-generic: - -distclean-generic: - -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_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-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-dvi: install-dvi-am - -install-dvi-am: $(DVIS) - @$(NORMAL_INSTALL) - test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" - @list='$(DVIS)'; for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/$$f"; \ - done -install-exec-am: - -install-html: install-html-am - -install-html-am: $(HTMLS) - @$(NORMAL_INSTALL) - test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" - @list='$(HTMLS)'; for p in $$list; do \ - if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - if test -d "$$d$$p"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ - $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ - echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \ - else \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \ - fi; \ - done -install-info: install-info-am - -install-info-am: $(INFO_DEPS) - @$(NORMAL_INSTALL) - test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - list='$(INFO_DEPS)'; \ - 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 \ - relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ - echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ - $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ - else : ; fi; \ - done; \ - done - @$(POST_INSTALL) - @if (install-info --version && \ - install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ - list='$(INFO_DEPS)'; \ - 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-pdf: install-pdf-am - -install-pdf-am: $(PDFS) - @$(NORMAL_INSTALL) - test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" - @list='$(PDFS)'; for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \ - done -install-ps: install-ps-am - -install-ps-am: $(PSS) - @$(NORMAL_INSTALL) - test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" - @list='$(PSS)'; for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(psdir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(psdir)/$$f"; \ - 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-pdf-am uninstall-ps-am - -.MAKE: install-am install-strip - -.PHONY: all all-am check check-am clean clean-generic clean-libtool \ - 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-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 uninstall uninstall-am \ - uninstall-dvi-am uninstall-html-am uninstall-info-am \ - uninstall-pdf-am uninstall-ps-am - - -.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)/'`$< $@ - -# 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. -gnupg.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/plugins/MirOTR/libgcrypt-1.4.6/doc/README.apichanges b/plugins/MirOTR/libgcrypt-1.4.6/doc/README.apichanges deleted file mode 100644 index 63b64da241..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/README.apichanges +++ /dev/null @@ -1,115 +0,0 @@ -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/plugins/MirOTR/libgcrypt-1.4.6/doc/authors.txt b/plugins/MirOTR/libgcrypt-1.4.6/doc/authors.txt deleted file mode 100644 index 5eef49c084..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/authors.txt +++ /dev/null @@ -1,7 +0,0 @@ -gpgvs
-building gnupg related projects with Visual Studio
-
-Authors:
- Francesco Picasso
- mr.s0rr0w@gmail.com
- www.s0rr0w.net
\ No newline at end of file diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.eps b/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.eps deleted file mode 100644 index ec3f683875..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.eps +++ /dev/null @@ -1,580 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: fips-fsm.fig -%%Creator: fig2dev Version 3.2 Patchlevel 4 -%%CreationDate: Thu Jul 9 13:24:33 2009 -%%For: wk@vigenere (Werner Koch,,,) -%%BoundingBox: 0 0 497 579 -%%Magnification: 1.0000 -%%EndComments -/$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 -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def -/col32 {0.609 0.000 0.000 srgb} bind def -/col33 {0.547 0.547 0.547 srgb} bind def -/col34 {0.547 0.547 0.547 srgb} bind def -/col35 {0.258 0.258 0.258 srgb} bind def -/col36 {0.547 0.547 0.547 srgb} bind def -/col37 {0.258 0.258 0.258 srgb} bind def -/col38 {0.547 0.547 0.547 srgb} bind def -/col39 {0.258 0.258 0.258 srgb} bind def -/col40 {0.547 0.547 0.547 srgb} bind def -/col41 {0.258 0.258 0.258 srgb} bind def -/col42 {0.547 0.547 0.547 srgb} bind def -/col43 {0.258 0.258 0.258 srgb} bind def - -end -save -newpath 0 579 moveto 0 0 lineto 497 0 lineto 497 579 lineto closepath clip newpath --56.9 596.0 translate -1 -1 scale - -/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 -/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 - -$F2psBegin -10 setmiterlimit -0 slj 0 slc - 0.06299 0.06299 sc -% -% 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 - -/Courier-Oblique-iso ff 180.00 scf sf -3157 1805 m -gs 1 -1 sc (1) col0 sh gr -% Ellipse -n 2408 3749 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -2327 3819 m -gs 1 -1 sc (2) col0 sh gr -% Ellipse -n 1708 5809 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -1627 5879 m -gs 1 -1 sc (3) col0 sh gr -% Ellipse -n 5848 1685 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -5767 1755 m -gs 1 -1 sc (6) col0 sh gr -% Ellipse -n 6128 7899 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -6047 7969 m -gs 1 -1 sc (7) col0 sh gr -% Ellipse -n 7568 4889 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -7487 4959 m -gs 1 -1 sc (8) col0 sh gr -% Ellipse -n 6008 3879 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -5882 3940 m -gs 1 -1 sc (10) col0 sh gr -% Ellipse -n 5418 2659 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -5292 2720 m -gs 1 -1 sc (11) col0 sh gr -% Ellipse -n 4268 3715 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -4142 3776 m -gs 1 -1 sc (12) col0 sh gr -% Ellipse -n 3208 5865 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -3082 5926 m -gs 1 -1 sc (13) col0 sh gr -% Ellipse -n 4178 6765 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -4052 6826 m -gs 1 -1 sc (14) col0 sh gr -% Ellipse -n 4558 7355 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -4432 7416 m -gs 1 -1 sc (15) col0 sh gr -% Ellipse -n 5208 7365 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -5127 7435 m -gs 1 -1 sc (5) col0 sh gr -% Ellipse -n 3708 7715 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -3582 7776 m -gs 1 -1 sc (16) col0 sh gr -% Ellipse -n 3038 7925 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -2957 7995 m -gs 1 -1 sc (4) col0 sh gr -% Ellipse -n 6568 5895 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -6487 5965 m -gs 1 -1 sc (9) col0 sh gr -% Polyline -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 -/Times-Roman-iso ff 360.00 scf sf -3870 9000 m -gs 1 -1 sc (Operational) col0 sh 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 -/Times-Roman-iso ff 360.00 scf sf -1620 4995 m -gs 1 -1 sc (Init) col0 sh 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 -/Times-Roman-iso ff 360.00 scf sf -1215 7020 m -gs 1 -1 sc (Self-Test) col0 sh 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 -/Times-Roman-iso ff 360.00 scf sf -7335 7020 m -gs 1 -1 sc (Error) col0 sh 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 -/Times-Roman-iso ff 360.00 scf sf -3915 4995 m -gs 1 -1 sc (Fatal-Error) col0 sh 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 -/Times-Roman-iso ff 360.00 scf sf -6930 2970 m -gs 1 -1 sc (Shutdown) col0 sh 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 -/Times-Roman-iso ff 360.00 scf sf -2655 2970 m -gs 1 -1 sc (Power-On) col0 sh 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 -/Times-Roman-iso ff 360.00 scf sf -2565 945 m -gs 1 -1 sc (Power-Off) col0 sh gr -% Ellipse -n 4192 6338 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -4066 6399 m -gs 1 -1 sc (17) col0 sh gr -% Ellipse -n 3202 4507 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -3076 4568 m -gs 1 -1 sc (19) col0 sh gr -% Ellipse -n 3181 5161 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -3055 5222 m -gs 1 -1 sc (18) col0 sh gr -% Ellipse -n 7709 7996 142 142 0 360 DrawEllipse gs col0 s gr - -/Courier-Oblique-iso ff 180.00 scf sf -7612 8047 m -gs 1 -1 sc (20) col0 sh gr -% Arc -15.000 slw -1 slc -gs clippath -2899 6648 m 2920 6766 l 3203 6716 l 2957 6699 l 3182 6598 l cp -eoclip -n 4837.5 16740.0 10215.6 -79.2 -100.8 arcn -gs col0 s gr - gr - -% arrowhead -0 slc -n 3182 6598 m 2957 6699 l 3203 6716 l 3182 6598 l cp gs 0.00 setgray ef gr col0 s -% Arc -1 slc -gs clippath -2911 7184 m 2908 7304 l 3195 7313 l 2957 7246 l 3198 7193 l cp -eoclip -n 3026.1 8399.8 1159.2 -1.5 -95.0 arcn -gs col0 s gr - gr - -% arrowhead -0 slc -n 3198 7193 m 2957 7246 l 3195 7313 l 3198 7193 l cp gs 0.00 setgray ef gr col0 s -% Arc -1 slc -gs clippath -6757 6631 m 6772 6512 l 6487 6477 l 6718 6566 l 6472 6596 l cp -eoclip -n 7663.1 -2028.8 8647.1 123.6 96.1 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 -8336 7494 m 8241 7421 l 8066 7650 l 8260 7496 l 8162 7723 l cp -eoclip -n 7717.5 7211.2 619.2 155.3 24.7 arcn -gs col0 s gr - gr - -% arrowhead -0 slc -n 8162 7723 m 8260 7496 l 8066 7650 l 8162 7723 l cp gs 0.00 setgray ef gr col0 s -% Polyline -1 slc -gs clippath -3360 2310 m 3480 2310 l 3480 2023 l 3420 2263 l 3360 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 -4794 4378 m 4860 4278 l 4621 4118 l 4788 4302 l 4555 4218 l cp -eoclip -n 3465 3420 m - 4815 4320 l gs col0 s gr gr - -% arrowhead -0 slc -n 4555 4218 m 4788 4302 l 4621 4118 l 4555 4218 l cp gs 0.00 setgray ef gr col0 s -% Polyline -1 slc -gs clippath -1830 6360 m 1950 6360 l 1950 6073 l 1890 6313 l 1830 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 -3699 8465 m 3790 8386 l 3601 8170 l 3714 8391 l 3511 8249 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 3601 8170 l 3511 8249 l cp gs 0.00 setgray ef gr col0 s -% Polyline -1 slc -gs clippath -4785 5475 m 4665 5475 l 4665 5762 l 4725 5522 l 4785 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 -7395 3432 m 7287 3380 l 7162 3639 l 7321 3449 l 7270 3691 l cp -eoclip -n 4950 8370 m - 7335 3420 l gs col0 s gr gr - -% arrowhead -0 slc -n 7270 3691 m 7321 3449 l 7162 3639 l 7270 3691 l cp gs 0.00 setgray ef gr col0 s -% Polyline -1 slc -gs clippath -6765 6990 m 6765 6870 l 6478 6870 l 6718 6930 l 6478 6990 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 -3969 5384 m 3880 5303 l 3686 5515 l 3893 5379 l 3774 5596 l cp -eoclip -n 2880 6480 m - 3915 5355 l gs col0 s gr gr - -% arrowhead -0 slc -n 3774 5596 m 3893 5379 l 3686 5515 l 3774 5596 l cp gs 0.00 setgray ef gr col0 s -% Polyline -1 slc -gs clippath -6765 2895 m 6765 2775 l 6478 2775 l 6718 2835 l 6478 2895 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 -7800 3405 m 7680 3405 l 7680 3692 l 7740 3452 l 7800 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 -1846 4276 m 1908 4379 l 2154 4229 l 1918 4303 l 2092 4127 l cp -eoclip -n 3375 3420 m - 1890 4320 l gs col0 s gr gr - -% arrowhead -0 slc -n 2092 4127 m 1918 4303 l 2154 4229 l 2092 4127 l cp gs 0.00 setgray ef gr col0 s -% Polyline -1 slc -gs clippath -6893 3361 m 6808 3276 l 6604 3480 l 6817 3353 l 6689 3565 l cp -eoclip -n 5760 4410 m - 6840 3330 l gs col0 s gr gr - -% arrowhead -0 slc -n 6689 3565 m 6817 3353 l 6604 3480 l 6689 3565 l cp gs 0.00 setgray ef gr col0 s -% Polyline -1 slc -gs clippath -4510 794 m 4461 903 l 4724 1020 l 4530 868 l 4773 910 l cp -eoclip -n 7740 2295 m - 4500 855 l gs col0 s gr gr - -% arrowhead -0 slc -n 4773 910 m 4530 868 l 4724 1020 l 4773 910 l cp gs 0.00 setgray ef gr col0 s -% Polyline -1 slc -gs clippath -5791 5301 m 5706 5386 l 5910 5590 l 5783 5378 l 5995 5505 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 -6895 7408 m 6804 7329 l 6615 7545 l 6819 7404 l 6706 7624 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 -3840 4740 m 3840 4620 l 3553 4620 l 3793 4680 l 3553 4740 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 -% here ends figure; -$F2psEnd -rs -showpage diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.fig b/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.fig deleted file mode 100644 index a4f0aeceef..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.fig +++ /dev/null @@ -1,199 +0,0 @@ -#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/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.pdf b/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.pdf Binary files differdeleted file mode 100644 index 0ea00af1f8..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.pdf +++ /dev/null diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.png b/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.png Binary files differdeleted file mode 100644 index 5da2442a6c..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/fips-fsm.png +++ /dev/null diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.info b/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.info deleted file mode 100644 index 0c6c6ee847..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.info +++ /dev/null @@ -1,6839 +0,0 @@ -This is gcrypt.info, produced by makeinfo version 4.13 from gcrypt.texi. - -This manual is for Libgcrypt (version 1.4.6, 9 July 2009), which is -GNU's library of cryptographic building blocks. - - Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free -Software Foundation, Inc. - - 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.4.6, 9 July 2009), which is -GNU's library of cryptographic building blocks. - - Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free -Software Foundation, Inc. - - 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 and MAC algorithms. -* 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. -* 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 -common error handling related code for 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. - - -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 defintions 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 compilers -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. - - 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, with the exception of the `GCRYCTL_SET_THREAD_CBS' command - (called via the `gcry_control' function). *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 intialized. */ - if (!gcry_check_version (GCRYPT_VERSION)) - { - fputs ("libgcrypt version mismatch\n", stderr); - 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 intialized. */ - if (!gcry_check_version (GCRYPT_VERSION)) - { - fputs ("libgcrypt version mismatch\n", stderr); - 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 intialized. */ - - /* Allocate a pool of 16k secure memory. This make the secure memory - available and also drops privileges where needed. */ - 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 your application is multi-threaded, you must set the thread - support callbacks with the `GCRYCTL_SET_THREAD_CBS' command - *before* any other function in the library. - - This is easy enough if you are indeed writing an application using - Libgcrypt. It is rather problematic if you are writing a library - instead. Here are some tips what to do if you are writing a - library: - - If your library requires a certain thread package, just initialize - Libgcrypt to use this thread package. If your library supports - multiple thread packages, but needs to be configured, you will - have to implement a way to determine which thread package the - application wants to use with your library anyway. Then configure - Libgcrypt to use this thread package. - - If your library is fully reentrant without any special support by a - thread package, then you are lucky indeed. Unfortunately, this - does not relieve you from doing either of the two above, or use a - third option. The third option is to let the application - initialize Libgcrypt for you. Then you are not using Libgcrypt - transparently, though. - - As if this was not difficult enough, a conflict may arise if two - libraries try to initialize Libgcrypt independently of each - others, and both such libraries are then linked into the same - application. To make it a bit simpler for you, this will probably - work, but only if both libraries have the same requirement for the - thread package. This is currently only supported for the - non-threaded case, GNU Pth and pthread. Support for more thread - packages is easy to add, so contact us if you require it. - - * The function `gcry_check_version' must be called before any other - function in the library, except the `GCRYCTL_SET_THREAD_CBS' - command (called via the `gcry_control' function), because it - initializes the thread support subsystem in Libgcrypt. 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. - - - Libgcrypt contains convenient macros, which define the necessary -thread callbacks for PThread and for GNU Pth: - -`GCRY_THREAD_OPTION_PTH_IMPL' - This macro defines the following (static) symbols: - `gcry_pth_init', `gcry_pth_mutex_init', `gcry_pth_mutex_destroy', - `gcry_pth_mutex_lock', `gcry_pth_mutex_unlock', `gcry_pth_read', - `gcry_pth_write', `gcry_pth_select', `gcry_pth_waitpid', - `gcry_pth_accept', `gcry_pth_connect', `gcry_threads_pth'. - - After including this macro, `gcry_control()' shall be used with a - command of `GCRYCTL_SET_THREAD_CBS' in order to register the - thread callback structure named "gcry_threads_pth". - -`GCRY_THREAD_OPTION_PTHREAD_IMPL' - This macro defines the following (static) symbols: - `gcry_pthread_mutex_init', `gcry_pthread_mutex_destroy', - `gcry_pthread_mutex_lock', `gcry_pthread_mutex_unlock', - `gcry_threads_pthread'. - - After including this macro, `gcry_control()' shall be used with a - command of `GCRYCTL_SET_THREAD_CBS' in order to register the - thread callback structure named "gcry_threads_pthread". - - Note that these macros need to be terminated with a semicolon. Keep -in mind that these are convenient macros for C programmers; C++ -programmers might have to wrap these macros in an "extern C" body. - - ---------- 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, 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'. 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: Generalities, Next: Handler Functions, Prev: Preparation, Up: Top - -3 Generalities -************** - -* Menu: - -* Controlling the library:: Controlling Libgcrypt's behavior. -* Modules:: Description of extension modules. -* Error Handling:: Error codes and such. - - -File: gcrypt.info, Node: Controlling the library, Next: Modules, 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 at initialization time. 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 - recommened. However, for some applications the extra quality - random Libgcrypt tries to create is not justified and this - option may help to get better performace. 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 randum number generator related statistics - to the library's logging stream. - - `GCRYCTL_DUMP_MEMORY_STATS; Arguments: none' - This command dumps memory managment related statistics to the - library's logging stream. - - `GCRYCTL_DUMP_SECMEM_STATS; Arguments: none' - This command dumps secure memory manamgent related statistics - to the library's logging stream. - - `GCRYCTL_DROP_PRIVS; Arguments: none' - This command disables the use of secure memory and drops the - priviliges 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_INIT_SECMEM; Arguments: int nbytes' - This command is used to allocate a pool of secure memory and - thus enabling the use of secure memory. It also drops all - extra privileges the process has (i.e. if it is run as setuid - (root)). If the argument NBYTES is 0, secure memory will be - disabled. The minimum amount of secure memory allocated is - currently 16384 bytes; you may thus use a value of 1 to - request that default size. - - `GCRYCTL_TERM_SECMEM; Arguments: none' - This command zeroises the secure memory and destroys the - handler. The secure memory pool may not be used anymore - after running this command. If the secure memory pool as - already been destroyed, this command has no effect. - Applications might want to run this command from their exit - handler to make sure that the secure memory gets properly - destroyed. This command is not necessarily thread-safe but - that should not be needed in cleanup code. It may be called - from a signal handler. - - `GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none' - Disable warning messages about problems with the secure memory - subsystem. This command should be run right after - `gcry_check_version'. - - `GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none' - Postpone warning messages from the secure memory subsystem. - *Note the initialization example: sample-use-suspend-secmem, - on how to use it. - - `GCRYCTL_RESUME_SECMEM_WARN; Arguments: none' - Resume warning messages from the secure memory subsystem. - *Note the initialization example: sample-use-resume-secmem, - on how to use it. - - `GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none' - This command tells the PRNG to store random numbers in secure - memory. This command should be run right after - `gcry_check_version' and not later than the command - GCRYCTL_INIT_SECMEM. Note that in FIPS mode the secure - memory is always used. - - `GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename' - This command specifies the file, which is to be used as seed - file for the PRNG. If the seed file is registered prior to - initialization of the PRNG, the seed file's content (if it - exists and seems to be valid) is fed into the PRNG pool. - After the seed file has been registered, the PRNG can be - signalled to write out the PRNG pool's content into the seed - file with the following command. - - `GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none' - Write out the PRNG pool's content into the registered seed - file. - - Multiple instances of the applications sharing the same - random seed file can be started in parallel, in which case - they will read out the same pool and then race for updating - it (the last update overwrites earlier updates). They will - differentiate only by the weak entropy that is added in - read_seed_file based on the PID and clock, and up to 16 bytes - of weak random non-blockingly. The consequence is that the - output of these different instances is correlated to some - extent. In a perfect attack scenario, the attacker can - control (or at least guess) the PID and clock of the - application, and drain the system's entropy pool to reduce - the "up to 16 bytes" above to 0. Then the dependencies of the - inital 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_SET_VERBOSITY; Arguments: int level' - This command sets the verbosity of the logging. A level of 0 - disables all extra logging whereas positive numbers enable - more verbose logging. The level may be changed at any time - but be aware that no memory synchronization is done so the - effect of this command might not immediately show up in other - threads. This command may even be used prior to - `gcry_check_version'. - - `GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags' - Set the debug flag bits as given by the argument. Be aware - that that no memory synchronization is done so the effect of - this command might not immediately show up in other threads. - The debug flags are not considered part of the API and thus - may change without notice. As of now bit 0 enables debugging - of cipher functions and bit 1 debugging of - multi-precision-integers. This command may even be used - prior to `gcry_check_version'. - - `GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags' - Set the debug flag bits as given by the argument. Be aware - that that no memory synchronization is done so the effect of - this command might not immediately show up in other threads. - This command may even be used prior to `gcry_check_version'. - - `GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none' - This command does nothing. It exists only for backward - compatibility. - - `GCRYCTL_ANY_INITIALIZATION_P; Arguments: none' - This command returns true if the library has been basically - initialized. Such a basic initialization happens implicitly - with many commands to get certain internal subsystems - running. The common and suggested way to do this basic - intialization is by calling gcry_check_version. - - `GCRYCTL_INITIALIZATION_FINISHED; Arguments: none' - This command tells the libray that the application has - finished the intialization. - - `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 registers a thread-callback structure. *Note - Multi-Threading::. - - `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 intialization has been finished but not - before a gcry_version_check. - - `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 intialization has - been finished but not before a gcry_version_check. - - `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 - intialization has been finished but not before a - gcry_version_check. 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 - intialization. - - `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. - - - - -File: gcrypt.info, Node: Modules, Next: Error Handling, Prev: Controlling the library, Up: Generalities - -3.2 Modules -=========== - -Libgcrypt supports the use of `extension modules', which implement -algorithms in addition to those already built into the library directly. - - -- Data type: gcry_module_t - This data type represents a `module'. - - Functions registering modules provided by the user take a `module -specification structure' as input and return a value of `gcry_module_t' -and an ID that is unique in the modules' category. This ID can be used -to reference the newly registered module. After registering a module -successfully, the new functionality should be able to be used through -the normal functions provided by Libgcrypt until it is unregistered -again. - - -File: gcrypt.info, Node: Error Handling, Prev: Modules, Up: Generalities - -3.3 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.3.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.3.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.3.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.3.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_strerror' 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. - - `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. -* Cipher modules:: How to work with cipher modules. -* 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: Cipher modules, 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. The constant is provided but there is - currently no implementation for it because the algorithm is - patented. - -`GCRY_CIPHER_3DES' - Triple-DES with 3 Keys as EDE. The key size of this algorithm is - 168 but you have to pass 192 bits because the most significant - bits of each byte are ignored. - -`GCRY_CIPHER_CAST5' - CAST128-5 block cipher algorithm. The key size is 128 bits. - -`GCRY_CIPHER_BLOWFISH' - The blowfish algorithm. The current implementation allows only for - a key size of 128 bits. - -`GCRY_CIPHER_SAFER_SK128' - Reserved and not currently implemented. - -`GCRY_CIPHER_DES_SK' - Reserved and not currently implemented. - -`GCRY_CIPHER_AES' -`GCRY_CIPHER_AES128' -`GCRY_CIPHER_RIJNDAEL' -`GCRY_CIPHER_RIJNDAEL128' - AES (Rijndael) with a 128 bit key. - -`GCRY_CIPHER_AES192' -`GCRY_CIPHER_RIJNDAEL192' - AES (Rijndael) with a 192 bit key. - -`GCRY_CIPHER_AES256' -`GCRY_CIPHER_RIJNDAEL256' - AES (Rijndael) with a 256 bit key. - -`GCRY_CIPHER_TWOFISH' - The Twofish algorithm with a 256 bit key. - -`GCRY_CIPHER_TWOFISH128' - The Twofish algorithm with a 128 bit key. - -`GCRY_CIPHER_ARCFOUR' - An algorithm which is 100% compatible with RSA Inc.'s RC4 - algorithm. Note that this is a stream cipher and must be used - very carefully to avoid a couple of weaknesses. - -`GCRY_CIPHER_DES' - Standard DES with a 56 bit key. You need to pass 64 bit but the - high bits of each byte are ignored. Note, that this is a weak - algorithm which can be broken in reasonable time using a brute - force approach. - -`GCRY_CIPHER_SERPENT128' -`GCRY_CIPHER_SERPENT192' -`GCRY_CIPHER_SERPENT256' - The Serpent cipher from the AES contest. - -`GCRY_CIPHER_RFC2268_40' -`GCRY_CIPHER_RFC2268_128' - Ron's Cipher 2 in the 40 and 128 bit variants. Note, that we - currently only support the 40 bit variant. The identifier for 128 - is reserved for future use. - -`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'. - - - -File: gcrypt.info, Node: Cipher modules, Next: Available cipher modes, Prev: Available ciphers, Up: Symmetric cryptography - -5.2 Cipher modules -================== - -Libgcrypt makes it possible to load additional `cipher modules'; these -ciphers can be used just like the cipher algorithms that are built into -the library directly. For an introduction into extension modules, see -*Note Modules::. - - -- Data type: gcry_cipher_spec_t - This is the `module specification structure' needed for registering - cipher modules, which has to be filled in by the user before it - can be used to register a module. It contains the following - members: - - `const char *name' - The primary name of the algorithm. - - `const char **aliases' - A list of strings that are `aliases' for the algorithm. The - list must be terminated with a NULL element. - - `gcry_cipher_oid_spec_t *oids' - A list of OIDs that are to be associated with the algorithm. - The list's last element must have it's `oid' member set to - NULL. See below for an explanation of this type. - - `size_t blocksize' - The block size of the algorithm, in bytes. - - `size_t keylen' - The length of the key, in bits. - - `size_t contextsize' - The size of the algorithm-specific `context', that should be - allocated for each handle. - - `gcry_cipher_setkey_t setkey' - The function responsible for initializing a handle with a - provided key. See below for a description of this type. - - `gcry_cipher_encrypt_t encrypt' - The function responsible for encrypting a single block. See - below for a description of this type. - - `gcry_cipher_decrypt_t decrypt' - The function responsible for decrypting a single block. See - below for a description of this type. - - `gcry_cipher_stencrypt_t stencrypt' - Like `encrypt', for stream ciphers. See below for a - description of this type. - - `gcry_cipher_stdecrypt_t stdecrypt' - Like `decrypt', for stream ciphers. See below for a - description of this type. - - -- Data type: gcry_cipher_oid_spec_t - This type is used for associating a user-provided algorithm - implementation with certain OIDs. It contains the following - members: - `const char *oid' - Textual representation of the OID. - - `int mode' - Cipher mode for which this OID is valid. - - -- Data type: gcry_cipher_setkey_t - Type for the `setkey' function, defined as: gcry_err_code_t - (*gcry_cipher_setkey_t) (void *c, const unsigned char *key, - unsigned keylen) - - -- Data type: gcry_cipher_encrypt_t - Type for the `encrypt' function, defined as: gcry_err_code_t - (*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, - const unsigned char *inbuf) - - -- Data type: gcry_cipher_decrypt_t - Type for the `decrypt' function, defined as: gcry_err_code_t - (*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, - const unsigned char *inbuf) - - -- Data type: gcry_cipher_stencrypt_t - Type for the `stencrypt' function, defined as: gcry_err_code_t - (*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, - const unsigned char *, unsigned int n) - - -- Data type: gcry_cipher_stdecrypt_t - Type for the `stdecrypt' function, defined as: gcry_err_code_t - (*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, - const unsigned char *, unsigned int n) - - -- Function: gcry_error_t gcry_cipher_register (gcry_cipher_spec_t - *CIPHER, unsigned int *algorithm_id, gcry_module_t *MODULE) - Register a new cipher module whose specification can be found in - CIPHER. On success, a new algorithm ID is stored in ALGORITHM_ID - and a pointer representing this module is stored in MODULE. - - -- Function: void gcry_cipher_unregister (gcry_module_t MODULE) - Unregister the cipher identified by MODULE, which must have been - registered with gcry_cipher_register. - - -- Function: gcry_error_t gcry_cipher_list (int *LIST, int - *LIST_LENGTH) - Get a list consisting of the IDs of the loaded cipher modules. If - LIST is zero, write the number of loaded cipher modules to - LIST_LENGTH and return. If LIST is non-zero, the first - *LIST_LENGTH algorithm IDs are stored in LIST, which must be of - according size. In case there are less cipher modules than - *LIST_LENGTH, *LIST_LENGTH is updated to the correct number. - - -File: gcrypt.info, Node: Available cipher modes, Next: Working with cipher handles, Prev: Cipher modules, Up: Symmetric cryptography - -5.3 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' - Cipher Feedback mode. The shift size equals the block size of the - cipher (e.g. for AES it is CFB-128). - -`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. - - - -File: gcrypt.info, Node: Working with cipher handles, Next: General cipher functions, Prev: Available cipher modes, Up: Symmetric cryptography - -5.4 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. Any - block cipher mode (`GCRY_CIPHER_MODE_ECB', `GCRY_CIPHER_MODE_CBC', - `GCRY_CIPHER_MODE_CFB', `GCRY_CIPHER_MODE_OFB' or - `GCRY_CIPHER_MODE_CTR') will work with any block cipher algorithm. - - 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. - - -- 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. - - 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 or 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. - - 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. - - The function returns `0' on success or an error code. - - OpenPGP (as defined in RFC-2440) 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. - - Currently no information is available. - - -File: gcrypt.info, Node: General cipher functions, Prev: Working with cipher handles, Up: Symmetric cryptography - -5.5 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. - - `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. - - `GCRYCTL_TEST_ALGO:' - Returns `0' when the specified algorithm is available for use. - BUFFER and NBYTES must be zero. - - - - -- 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. -* Public key modules:: How to work with public key modules. -* Cryptographic Functions:: Functions for performing the cryptographic actions. -* General public-key related Functions:: General functions, not implementing any cryptography. - -* AC Interface:: Alternative interface to public key functions. - - -File: gcrypt.info, Node: Available algorithms, Next: Used S-expressions, Up: Public Key cryptography - -6.1 Available algorithms -======================== - -Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well -as DSA (Digital Signature Algorithm) and Elgamal. The versatile -interface allows to add more algorithms in the future. - - -File: gcrypt.info, Node: Used S-expressions, Next: Public key modules, Prev: Available algorithms, Up: Public Key cryptography - -6.2 Used S-expressions -====================== - -Libgcrypt's API for asymmetric cryptography is based on data structures -called S-expressions (see -`http://people.csail.mit.edu/rivest/sexp.html') and does not work with -contexts as most of the other building blocks of Libgcrypt do. - -The following information are stored in S-expressions: - - keys - - plain text data - - encrypted data - - signatures - - -To describe how Libgcrypt expect keys, we use examples. Note that words -in uppercase indicate parameters whereas lowercase words are literals. - - Note that all MPI (multi-precision-integers) values are expected to -be in `GCRYMPI_FMT_USG' format. An easy way to create S-expressions is -by using `gcry_sexp_build' which allows to pass a string with -printf-like escapes to insert MPI values. - -* Menu: - -* RSA key parameters:: Parameters used with an RSA key. -* DSA key parameters:: Parameters used with a DSA key. -* ECC key parameters:: Parameters used with ECC keys. - - -File: gcrypt.info, Node: RSA key parameters, Next: DSA key parameters, Up: Used S-expressions - -6.2.1 RSA key parameters ------------------------- - -An RSA private key is described by this S-expression: - - (private-key - (rsa - (n N-MPI) - (e E-MPI) - (d D-MPI) - (p P-MPI) - (q Q-MPI) - (u U-MPI))) - -An RSA public key is described by this S-expression: - - (public-key - (rsa - (n N-MPI) - (e E-MPI))) - -N-MPI - RSA public modulus n. - -E-MPI - RSA public exponent e. - -D-MPI - RSA secret exponent d = e^-1 \bmod (p-1)(q-1). - -P-MPI - RSA secret prime p. - -Q-MPI - RSA secret prime q with p < q. - -U-MPI - Multiplicative inverse u = p^-1 \bmod q. - - For signing and decryption the parameters (p, q, u) are optional but -greatly improve the performance. Either all of these optional -parameters must be given or none of them. They are mandatory for -gcry_pk_testkey. - - Note that OpenSSL uses slighly different parameters: q < p and u = -q^-1 \bmod p. To use these parameters you will need to swap the values -and recompute u. Here is example code to do this: - - if (gcry_mpi_cmp (p, q) > 0) - { - gcry_mpi_swap (p, q); - gcry_mpi_invm (u, p, q); - } - - -File: gcrypt.info, Node: DSA key parameters, Next: ECC key parameters, Prev: RSA key parameters, Up: Used S-expressions - -6.2.2 DSA key parameters ------------------------- - -A DSA private key is described by this S-expression: - - (private-key - (dsa - (p P-MPI) - (q Q-MPI) - (g G-MPI) - (y Y-MPI) - (x X-MPI))) - -P-MPI - DSA prime p. - -Q-MPI - DSA group order q (which is a prime divisor of p-1). - -G-MPI - DSA group generator g. - -Y-MPI - DSA public key value y = g^x \bmod p. - -X-MPI - DSA secret exponent x. - - The public key is similar with "private-key" replaced by "public-key" -and no X-MPI. - - -File: gcrypt.info, Node: ECC key parameters, Prev: DSA key parameters, Up: Used S-expressions - -6.2.3 ECC key parameters ------------------------- - -An ECC private key is described by this S-expression: - - (private-key - (ecc - (p P-MPI) - (a A-MPI) - (b B-MPI) - (g G-POINT) - (n N-MPI) - (q Q-POINT) - (d D-MPI))) - -P-MPI - Prime specifying the field GF(p). - -A-MPI -B-MPI - The two coefficients of the Weierstrass equation y^2 = x^3 + ax + b - -G-POINT - Base point g. - -N-MPI - Order of g - -Q-POINT - The point representing the public key Q = dP. - -D-MPI - The private key d - - All point values are encoded in standard format; Libgcrypt does -currently only support uncompressed points, thus the first byte needs to -be `0x04'. - - 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))) - - The `curve' parameter may be given in any case and is used to replace -missing parameters. - -Currently implemented curves are: -`NIST P-192' -`1.2.840.10045.3.1.1' -`prime192v1' -`secp192r1' - The NIST 192 bit curve, its OID, X9.62 and SECP aliases. - -`NIST P-224' -`secp224r1' - The NIST 224 bit curve and its SECP alias. - -`NIST P-256' -`1.2.840.10045.3.1.7' -`prime256v1' -`secp256r1' - The NIST 256 bit curve, its OID, X9.62 and SECP aliases. - -`NIST P-384' -`secp384r1' - The NIST 384 bit curve and its SECP alias. - -`NIST P-521' -`secp521r1' - The NIST 521 bit curve and its SECP alias. - - As usual the OIDs may optionally be prefixed with the string `OID.' -or `oid.'. - - -File: gcrypt.info, Node: Public key modules, Next: Cryptographic Functions, Prev: Used S-expressions, Up: Public Key cryptography - -6.3 Public key modules -====================== - -Libgcrypt makes it possible to load additional `public key modules'; -these public key algorithms can be used just like the algorithms that -are built into the library directly. For an introduction into -extension modules, see *Note Modules::. - - -- Data type: gcry_pk_spec_t - This is the `module specification structure' needed for registering - public key modules, which has to be filled in by the user before it - can be used to register a module. It contains the following - members: - - `const char *name' - The primary name of this algorithm. - - `char **aliases' - A list of strings that are `aliases' for the algorithm. The - list must be terminated with a NULL element. - - `const char *elements_pkey' - String containing the one-letter names of the MPI values - contained in a public key. - - `const char *element_skey' - String containing the one-letter names of the MPI values - contained in a secret key. - - `const char *elements_enc' - String containing the one-letter names of the MPI values that - are the result of an encryption operation using this - algorithm. - - `const char *elements_sig' - String containing the one-letter names of the MPI values that - are the result of a sign operation using this algorithm. - - `const char *elements_grip' - String containing the one-letter names of the MPI values that - are to be included in the `key grip'. - - `int use' - The bitwise-OR of the following flags, depending on the - abilities of the algorithm: - `GCRY_PK_USAGE_SIGN' - The algorithm supports signing and verifying of data. - - `GCRY_PK_USAGE_ENCR' - The algorithm supports the encryption and decryption of - data. - - `gcry_pk_generate_t generate' - The function responsible for generating a new key pair. See - below for a description of this type. - - `gcry_pk_check_secret_key_t check_secret_key' - The function responsible for checking the sanity of a - provided secret key. See below for a description of this - type. - - `gcry_pk_encrypt_t encrypt' - The function responsible for encrypting data. See below for a - description of this type. - - `gcry_pk_decrypt_t decrypt' - The function responsible for decrypting data. See below for a - description of this type. - - `gcry_pk_sign_t sign' - The function responsible for signing data. See below for a - description of this type. - - `gcry_pk_verify_t verify' - The function responsible for verifying that the provided - signature matches the provided data. See below for a - description of this type. - - `gcry_pk_get_nbits_t get_nbits' - The function responsible for returning the number of bits of - a provided key. See below for a description of this type. - - -- Data type: gcry_pk_generate_t - Type for the `generate' function, defined as: gcry_err_code_t - (*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long - use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors) - - -- Data type: gcry_pk_check_secret_key_t - Type for the `check_secret_key' function, defined as: - gcry_err_code_t (*gcry_pk_check_secret_key_t) (int algo, - gcry_mpi_t *skey) - - -- Data type: gcry_pk_encrypt_t - Type for the `encrypt' function, defined as: gcry_err_code_t - (*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t - data, gcry_mpi_t *pkey, int flags) - - -- Data type: gcry_pk_decrypt_t - Type for the `decrypt' function, defined as: gcry_err_code_t - (*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t - *data, gcry_mpi_t *skey, int flags) - - -- Data type: gcry_pk_sign_t - Type for the `sign' function, defined as: gcry_err_code_t - (*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data, - gcry_mpi_t *skey) - - -- Data type: gcry_pk_verify_t - Type for the `verify' function, defined as: gcry_err_code_t - (*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data, - gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev) - - -- Data type: gcry_pk_get_nbits_t - Type for the `get_nbits' function, defined as: unsigned - (*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey) - - -- Function: gcry_error_t gcry_pk_register (gcry_pk_spec_t *PUBKEY, - unsigned int *algorithm_id, gcry_module_t *MODULE) - Register a new public key module whose specification can be found - in PUBKEY. On success, a new algorithm ID is stored in - ALGORITHM_ID and a pointer representing this module is stored in - MODULE. - - -- Function: void gcry_pk_unregister (gcry_module_t MODULE) - Unregister the public key module identified by MODULE, which must - have been registered with gcry_pk_register. - - -- Function: gcry_error_t gcry_pk_list (int *LIST, int *LIST_LENGTH) - Get a list consisting of the IDs of the loaded pubkey modules. If - LIST is zero, write the number of loaded pubkey modules to - LIST_LENGTH and return. If LIST is non-zero, the first - *LIST_LENGTH algorithm IDs are stored in LIST, which must be of - according size. In case there are less pubkey modules than - *LIST_LENGTH, *LIST_LENGTH is updated to the correct number. - - -File: gcrypt.info, Node: Cryptographic Functions, Next: General public-key related Functions, Prev: Public key modules, Up: Public Key cryptography - -6.4 Cryptographic Functions -=========================== - -Note that we will in future allow to use keys without p,q and u -specified and may also support other parameters for performance reasons. - -Some functions operating on S-expressions support `flags', that -influence the operation. These flags have to be listed in a -sub-S-expression named `flags'; the following flags are known: - -`pkcs1' - Use PKCS#1 block type 2 padding. - -`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. - -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 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))) - - Note that this function currently does not know of any padding - methods and the caller must do any un-padding on his own. - - 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. - - 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". - -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 - `GCRYERR_BAD_SIGNATURE' to indicate that the signature does not - match the provided data. - - - -File: gcrypt.info, Node: General public-key related Functions, Next: AC Interface, Prev: Cryptographic 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_NENC' - Return the number of elements a encrypted message created - with the algorithm ALGO consists of. Return 0 for an unknown - algorithm or for an algorithm not capable of encryption. - - Please note that parameters not required should be passed as - `NULL'. - - -- Function: gcry_error_t gcry_pk_ctl (int CMD, void *BUFFER, - size_t BUFLEN) - This is a general purpose function to perform certain control - operations. CMD controls what is to be done. The return value is - 0 for success or an error code. Currently supported values for - CMD are: - - `GCRYCTL_DISABLE_ALGO' - Disable the algorithm given as an algorithm id in BUFFER. - BUFFER must point to an `int' variable with the algorithm id - and BUFLEN must have the value `sizeof (int)'. - - -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. - - `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' - 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. - - `qbits' - This is only meanigful for DSA keys. If it is given the DSA - key is generated with a Q parameyer of this size. 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. - - `transient-key' - This is only meaningful for RSA and DSA keys. This is a flag - with no value. If given the RSA or DSA key is created using - a faster and a somewhat less secure random number generator. - This flag may be used for keys which are only used for a - short time and do not require full cryptographic strength. - - `domain' - This is only meaningful for DLP algorithms. If specified - keys are generated with domain parameters taken from this - list. The exact format of this parameter depends on the - actual algorithm. It is currently only implemented for DSA - using this format: - - (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' - 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)))) - - `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 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 slighlty - different from FIPS 186-3 and allows only 1024 bit keys. - This flag is only meaningful for DSA and only required for - FIPS testing backward compatibility. - - - 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. - - As an example, here is what the Elgamal key generation returns: - - (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)) - - 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. - - -File: gcrypt.info, Node: AC Interface, Prev: General public-key related Functions, Up: Public Key cryptography - -6.6 Alternative Public Key Interface -==================================== - -This section documents the alternative interface to asymmetric -cryptography (ac) that is not based on S-expressions, but on native C -data structures. As opposed to the pk interface described in the -former chapter, this one follows an open/use/close paradigm like other -building blocks of the library. - - *This interface has a few known problems; most noteworthy an -inherent tendency to leak memory. It might not be available in -forthcoming versions of Libgcrypt.* - -* Menu: - -* Available asymmetric algorithms:: List of algorithms supported by the library. -* Working with sets of data:: How to work with sets of data. -* Working with IO objects:: How to work with IO objects. -* Working with handles:: How to use handles. -* Working with keys:: How to work with keys. -* Using cryptographic functions:: How to perform cryptographic operations. -* Handle-independent functions:: General functions independent of handles. - - -File: gcrypt.info, Node: Available asymmetric algorithms, Next: Working with sets of data, Up: AC Interface - -6.6.1 Available asymmetric algorithms -------------------------------------- - -Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well -as DSA (Digital Signature Algorithm) and Elgamal. The versatile -interface allows to add more algorithms in the future. - - -- Data type: gcry_ac_id_t - The following constants are defined for this type: - - `GCRY_AC_RSA' - Rivest-Shamir-Adleman - - `GCRY_AC_DSA' - Digital Signature Algorithm - - `GCRY_AC_ELG' - Elgamal - - `GCRY_AC_ELG_E' - Elgamal, encryption only. - - -File: gcrypt.info, Node: Working with sets of data, Next: Working with IO objects, Prev: Available asymmetric algorithms, Up: AC Interface - -6.6.2 Working with sets of data -------------------------------- - -In the context of this interface the term `data set' refers to a list -of `named MPI values' that is used by functions performing -cryptographic operations; a named MPI value is a an MPI value, -associated with a label. - - Such data sets are used for representing keys, since keys simply -consist of a variable amount of numbers. Furthermore some functions -return data sets to the caller that are to be provided to other -functions. - - This section documents the data types, symbols and functions that are -relevant for working with data sets. - - -- Data type: gcry_ac_data_t - A single data set. - - The following flags are supported: - -`GCRY_AC_FLAG_DEALLOC' - Used for storing data in a data set. If given, the data will be - released by the library. Note that whenever one of the ac - functions is about to release objects because of this flag, the - objects are expected to be stored in memory allocated through the - Libgcrypt memory management. In other words: gcry_free() is used - instead of free(). - -`GCRY_AC_FLAG_COPY' - Used for storing/retrieving data in/from a data set. If given, the - library will create copies of the provided/contained data, which - will then be given to the user/associated with the data set. - - -- Function: gcry_error_t gcry_ac_data_new (gcry_ac_data_t *DATA) - Creates a new, empty data set and stores it in DATA. - - -- Function: void gcry_ac_data_destroy (gcry_ac_data_t DATA) - Destroys the data set DATA. - - -- Function: gcry_error_t gcry_ac_data_set (gcry_ac_data_t DATA, - unsigned int FLAGS, char *NAME, gcry_mpi_t MPI) - Add the value MPI to DATA with the label NAME. If FLAGS contains - GCRY_AC_FLAG_COPY, the data set will contain copies of NAME and - MPI. If FLAGS contains GCRY_AC_FLAG_DEALLOC or GCRY_AC_FLAG_COPY, - the values contained in the data set will be deallocated when they - are to be removed from the data set. - - -- Function: gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *DATA_CP, - gcry_ac_data_t DATA) - Create a copy of the data set DATA and store it in DATA_CP. - FIXME: exact semantics undefined. - - -- Function: unsigned int gcry_ac_data_length (gcry_ac_data_t DATA) - Returns the number of named MPI values inside of the data set DATA. - - -- Function: gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t DATA, - unsigned int FLAGS, char *NAME, gcry_mpi_t *MPI) - Store the value labelled with NAME found in DATA in MPI. If FLAGS - contains GCRY_AC_FLAG_COPY, store a copy of the MPI value - contained in the data set. MPI may be NULL (this might be useful - for checking the existence of an MPI with extracting it). - - -- Function: gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t DATA, - unsigned int flags, unsigned int INDEX, const char **NAME, - gcry_mpi_t *MPI) - Stores in NAME and MPI the named MPI value contained in the data - set DATA with the index IDX. If FLAGS contains GCRY_AC_FLAG_COPY, - store copies of the values contained in the data set. NAME or MPI - may be NULL. - - -- Function: void gcry_ac_data_clear (gcry_ac_data_t DATA) - Destroys any values contained in the data set DATA. - - -- Function: gcry_error_t gcry_ac_data_to_sexp (gcry_ac_data_t DATA, - gcry_sexp_t *SEXP, const char **IDENTIFIERS) - This function converts the data set DATA into a newly created - S-Expression, which is to be stored in SEXP; IDENTIFIERS is a NULL - terminated list of C strings, which specifies the structure of the - S-Expression. - - Example: - - If IDENTIFIERS is a list of pointers to the strings "foo" and - "bar" and if DATA is a data set containing the values "val1 = - 0x01" and "val2 = 0x02", then the resulting S-Expression will look - like this: (foo (bar ((val1 0x01) (val2 0x02))). - - -- Function: gcry_error gcry_ac_data_from_sexp (gcry_ac_data_t *DATA, - gcry_sexp_t SEXP, const char **IDENTIFIERS) - This function converts the S-Expression SEXP into a newly created - data set, which is to be stored in DATA; IDENTIFIERS is a NULL - terminated list of C strings, which specifies the structure of the - S-Expression. If the list of identifiers does not match the - structure of the S-Expression, the function fails. - - -File: gcrypt.info, Node: Working with IO objects, Next: Working with handles, Prev: Working with sets of data, Up: AC Interface - -6.6.3 Working with IO objects ------------------------------ - -Note: IO objects are currently only used in the context of message -encoding/decoding and encryption/signature schemes. - - -- Data type: gcry_ac_io_t - `gcry_ac_io_t' is the type to be used for IO objects. - - IO objects provide an uniform IO layer on top of different underlying -IO mechanisms; either they can be used for providing data to the -library (mode is GCRY_AC_IO_READABLE) or they can be used for -retrieving data from the library (mode is GCRY_AC_IO_WRITABLE). - - IO object need to be initialized by calling on of the following -functions: - - -- Function: void gcry_ac_io_init (gcry_ac_io_t *AC_IO, - gcry_ac_io_mode_t MODE, gcry_ac_io_type_t TYPE, ...); - Initialize AC_IO according to MODE, TYPE and the variable list of - arguments. The list of variable arguments to specify depends on - the given TYPE. - - -- Function: void gcry_ac_io_init_va (gcry_ac_io_t *AC_IO, - gcry_ac_io_mode_t MODE, gcry_ac_io_type_t TYPE, va_list AP); - Initialize AC_IO according to MODE, TYPE and the variable list of - arguments AP. The list of variable arguments to specify depends - on the given TYPE. - - The following types of IO objects exist: - -`GCRY_AC_IO_STRING' - In case of GCRY_AC_IO_READABLE the IO object will provide data - from a memory string. Arguments to specify at initialization time: - `unsigned char *' - Pointer to the beginning of the memory string - - `size_t' - Size of the memory string - In case of GCRY_AC_IO_WRITABLE the object will store retrieved - data in a newly allocated memory string. Arguments to specify at - initialization time: - `unsigned char **' - Pointer to address, at which the pointer to the newly created - memory string is to be stored - - `size_t *' - Pointer to address, at which the size of the newly created - memory string is to be stored - -`GCRY_AC_IO_CALLBACK' - In case of GCRY_AC_IO_READABLE the object will forward read - requests to a provided callback function. Arguments to specify at - initialization time: - `gcry_ac_data_read_cb_t' - Callback function to use - - `void *' - Opaque argument to provide to the callback function - In case of GCRY_AC_IO_WRITABLE the object will forward write - requests to a provided callback function. Arguments to specify at - initialization time: - `gcry_ac_data_write_cb_t' - Callback function to use - - `void *' - Opaque argument to provide to the callback function - - -File: gcrypt.info, Node: Working with handles, Next: Working with keys, Prev: Working with IO objects, Up: AC Interface - -6.6.4 Working with handles --------------------------- - -In order to use an algorithm, an according handle must be created. -This is done using the following function: - - -- Function: gcry_error_t gcry_ac_open (gcry_ac_handle_t *HANDLE, int - ALGORITHM, int FLAGS) - Creates a new handle for the algorithm ALGORITHM and stores it in - HANDLE. FLAGS is not used currently. - - ALGORITHM must be a valid algorithm ID, see *Note Available - asymmetric algorithms::, for a list of supported algorithms and the - according constants. Besides using the listed constants directly, - the functions `gcry_pk_name_to_id' may be used to convert the - textual name of an algorithm into the according numeric ID. - - -- Function: void gcry_ac_close (gcry_ac_handle_t HANDLE) - Destroys the handle HANDLE. - - -File: gcrypt.info, Node: Working with keys, Next: Using cryptographic functions, Prev: Working with handles, Up: AC Interface - -6.6.5 Working with keys ------------------------ - - -- Data type: gcry_ac_key_type_t - Defined constants: - - `GCRY_AC_KEY_SECRET' - Specifies a secret key. - - `GCRY_AC_KEY_PUBLIC' - Specifies a public key. - - -- Data type: gcry_ac_key_t - This type represents a single `key', either a secret one or a - public one. - - -- Data type: gcry_ac_key_pair_t - This type represents a `key pair' containing a secret and a public - key. - - Key data structures can be created in two different ways; a new key -pair can be generated, resulting in ready-to-use key. Alternatively a -key can be initialized from a given data set. - - -- Function: gcry_error_t gcry_ac_key_init (gcry_ac_key_t *KEY, - gcry_ac_handle_t HANDLE, gcry_ac_key_type_t TYPE, - gcry_ac_data_t DATA) - Creates a new key of type TYPE, consisting of the MPI values - contained in the data set DATA and stores it in KEY. - - -- Function: gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t - HANDLE, unsigned int NBITS, void *KEY_SPEC, - gcry_ac_key_pair_t *KEY_PAIR, gcry_mpi_t **MISC_DATA) - Generates a new key pair via the handle HANDLE of NBITS bits and - stores it in KEY_PAIR. - - In case non-standard settings are wanted, a pointer to a structure - of type `gcry_ac_key_spec_<algorithm>_t', matching the selected - algorithm, can be given as KEY_SPEC. MISC_DATA is not used yet. - Such a structure does only exist for RSA. A description of the - members of the supported structures follows. - - `gcry_ac_key_spec_rsa_t' - - `gcry_mpi_t e' - Generate the key pair using a special `e'. The value of - `e' has the following meanings: - `= 0' - Let Libgcrypt decide what exponent should be used. - - `= 1' - Request the use of a "secure" exponent; this is - required by some specification to be 65537. - - `> 2' - Try starting at this value until a working exponent - is found. Note that the current implementation - leaks some information about the private key - because the incrementation used is not randomized. - Thus, this function will be changed in the future - to return a random exponent of the given size. - - Example code: - { - gcry_ac_key_pair_t key_pair; - gcry_ac_key_spec_rsa_t rsa_spec; - - rsa_spec.e = gcry_mpi_new (0); - gcry_mpi_set_ui (rsa_spec.e, 1); - - err = gcry_ac_open (&handle, GCRY_AC_RSA, 0); - assert (! err); - - err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec, - &key_pair, NULL); - assert (! err); - } - - -- Function: gcry_ac_key_t gcry_ac_key_pair_extract - (gcry_ac_key_pair_t KEY_PAIR, gcry_ac_key_type_t WHICH) - Returns the key of type WHICH out of the key pair KEY_PAIR. - - -- Function: void gcry_ac_key_destroy (gcry_ac_key_t KEY) - Destroys the key KEY. - - -- Function: void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t - KEY_PAIR) - Destroys the key pair KEY_PAIR. - - -- Function: gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t KEY) - Returns the data set contained in the key KEY. - - -- Function: gcry_error_t gcry_ac_key_test (gcry_ac_handle_t HANDLE, - gcry_ac_key_t KEY) - Verifies that the private key KEY is sane via HANDLE. - - -- Function: gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t - HANDLE, gcry_ac_key_t KEY, unsigned int *NBITS) - Stores the number of bits of the key KEY in NBITS via HANDLE. - - -- Function: gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t - HANDLE, gcry_ac_key_t KEY, unsigned char *KEY_GRIP) - Writes the 20 byte long key grip of the key KEY to KEY_GRIP via - HANDLE. - - -File: gcrypt.info, Node: Using cryptographic functions, Next: Handle-independent functions, Prev: Working with keys, Up: AC Interface - -6.6.6 Using cryptographic functions ------------------------------------ - -The following flags might be relevant: - -`GCRY_AC_FLAG_NO_BLINDING' - Disable any blinding, which might be supported by the chosen - algorithm; blinding is the default. - - There exist two kinds of cryptographic functions available through -the ac interface: primitives, and high-level functions. - - Primitives deal with MPIs (data sets) directly; what they provide is -direct access to the cryptographic operations provided by an algorithm -implementation. - - High-level functions deal with octet strings, according to a -specified "scheme". Schemes make use of "encoding methods", which are -responsible for converting the provided octet strings into MPIs, which -are then forwared to the cryptographic primitives. Since schemes are -to be used for a special purpose in order to achieve a particular -security goal, there exist "encryption schemes" and "signature -schemes". Encoding methods can be used seperately or implicitly -through schemes. - - What follows is a description of the cryptographic primitives. - - -- Function: gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t - HANDLE, unsigned int FLAGS, gcry_ac_key_t KEY, gcry_mpi_t - DATA_PLAIN, gcry_ac_data_t *DATA_ENCRYPTED) - Encrypts the plain text MPI value DATA_PLAIN with the key public - KEY under the control of the flags FLAGS and stores the resulting - data set into DATA_ENCRYPTED. - - -- Function: gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t - HANDLE, unsigned int FLAGS, gcry_ac_key_t KEY, gcry_mpi_t - *DATA_PLAIN, gcry_ac_data_t DATA_ENCRYPTED) - Decrypts the encrypted data contained in the data set - DATA_ENCRYPTED with the secret key KEY under the control of the - flags FLAGS and stores the resulting plain text MPI value in - DATA_PLAIN. - - -- Function: gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t HANDLE, - gcry_ac_key_t KEY, gcry_mpi_t DATA, gcry_ac_data_t - *DATA_SIGNATURE) - Signs the data contained in DATA with the secret key KEY and - stores the resulting signature in the data set DATA_SIGNATURE. - - -- Function: gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t - HANDLE, gcry_ac_key_t KEY, gcry_mpi_t DATA, gcry_ac_data_t - DATA_SIGNATURE) - Verifies that the signature contained in the data set - DATA_SIGNATURE is indeed the result of signing the data contained - in DATA with the secret key belonging to the public key KEY. - - What follows is a description of the high-level functions. - - The type "gcry_ac_em_t" is used for specifying encoding methods; the -following methods are supported: - -`GCRY_AC_EME_PKCS_V1_5' - PKCS-V1_5 Encoding Method for Encryption. Options must be provided - through a pointer to a correctly initialized object of type - gcry_ac_eme_pkcs_v1_5_t. - -`GCRY_AC_EMSA_PKCS_V1_5' - PKCS-V1_5 Encoding Method for Signatures with Appendix. Options - must be provided through a pointer to a correctly initialized - object of type gcry_ac_emsa_pkcs_v1_5_t. - - Option structure types: - -`gcry_ac_eme_pkcs_v1_5_t' - - `gcry_ac_key_t key' - - `gcry_ac_handle_t handle' - -`gcry_ac_emsa_pkcs_v1_5_t' - - `gcry_md_algo_t md' - - `size_t em_n' - - Encoding methods can be used directly through the following -functions: - - -- Function: gcry_error_t gcry_ac_data_encode (gcry_ac_em_t METHOD, - unsigned int FLAGS, void *OPTIONS, unsigned char *M, size_t - M_N, unsigned char **EM, size_t *EM_N) - Encodes the message contained in M of size M_N according to - METHOD, FLAGS and OPTIONS. The newly created encoded message is - stored in EM and EM_N. - - -- Function: gcry_error_t gcry_ac_data_decode (gcry_ac_em_t METHOD, - unsigned int FLAGS, void *OPTIONS, unsigned char *EM, size_t - EM_N, unsigned char **M, size_t *M_N) - Decodes the message contained in EM of size EM_N according to - METHOD, FLAGS and OPTIONS. The newly created decoded message is - stored in M and M_N. - - The type "gcry_ac_scheme_t" is used for specifying schemes; the -following schemes are supported: - -`GCRY_AC_ES_PKCS_V1_5' - PKCS-V1_5 Encryption Scheme. No options can be provided. - -`GCRY_AC_SSA_PKCS_V1_5' - PKCS-V1_5 Signature Scheme (with Appendix). Options can be - provided through a pointer to a correctly initialized object of - type gcry_ac_ssa_pkcs_v1_5_t. - - Option structure types: - -`gcry_ac_ssa_pkcs_v1_5_t' - - `gcry_md_algo_t md' - - The functions implementing schemes: - - -- Function: gcry_error_t gcry_ac_data_encrypt_scheme - (gcry_ac_handle_t HANDLE, gcry_ac_scheme_t SCHEME, unsigned - int FLAGS, void *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t - *IO_MESSAGE, gcry_ac_io_t *IO_CIPHER) - Encrypts the plain text readable from IO_MESSAGE through HANDLE - with the public key KEY according to SCHEME, FLAGS and OPTS. If - OPTS is not NULL, it has to be a pointer to a structure specific - to the chosen scheme (gcry_ac_es_*_t). The encrypted message is - written to IO_CIPHER. - - -- Function: gcry_error_t gcry_ac_data_decrypt_scheme - (gcry_ac_handle_t HANDLE, gcry_ac_scheme_t SCHEME, unsigned - int FLAGS, void *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t - *IO_CIPHER, gcry_ac_io_t *IO_MESSAGE) - Decrypts the cipher text readable from IO_CIPHER through HANDLE - with the secret key KEY according to SCHEME, FLAGS and OPTS. If - OPTS is not NULL, it has to be a pointer to a structure specific - to the chosen scheme (gcry_ac_es_*_t). The decrypted message is - written to IO_MESSAGE. - - -- Function: gcry_error_t gcry_ac_data_sign_scheme (gcry_ac_handle_t - HANDLE, gcry_ac_scheme_t SCHEME, unsigned int FLAGS, void - *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t *IO_MESSAGE, - gcry_ac_io_t *IO_SIGNATURE) - Signs the message readable from IO_MESSAGE through HANDLE with the - secret key KEY according to SCHEME, FLAGS and OPTS. If OPTS is - not NULL, it has to be a pointer to a structure specific to the - chosen scheme (gcry_ac_ssa_*_t). The signature is written to - IO_SIGNATURE. - - -- Function: gcry_error_t gcry_ac_data_verify_scheme (gcry_ac_handle_t - HANDLE, gcry_ac_scheme_t SCHEME, unsigned int FLAGS, void - *OPTS, gcry_ac_key_t KEY, gcry_ac_io_t *IO_MESSAGE, - gcry_ac_io_t *IO_SIGNATURE) - Verifies through HANDLE that the signature readable from - IO_SIGNATURE is indeed the result of signing the message readable - from IO_MESSAGE with the secret key belonging to the public key - KEY according to SCHEME and OPTS. If OPTS is not NULL, it has to - be an anonymous structure (gcry_ac_ssa_*_t) specific to the chosen - scheme. - - -File: gcrypt.info, Node: Handle-independent functions, Prev: Using cryptographic functions, Up: AC Interface - -6.6.7 Handle-independent functions ----------------------------------- - -These two functions are deprecated; do not use them for new code. - - -- Function: gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t ALGORITHM, - const char **NAME) - Stores the textual representation of the algorithm whose id is - given in ALGORITHM in NAME. Deprecated; use `gcry_pk_algo_name'. - - -- Function: gcry_error_t gcry_ac_name_to_id (const char *NAME, - gcry_ac_id_t *ALGORITHM) - Stores the numeric ID of the algorithm whose textual - representation is contained in NAME in ALGORITHM. Deprecated; use - `gcry_pk_map_name'. - - -File: gcrypt.info, Node: Hashing, Next: Random Numbers, 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 MAC 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. -* Hash algorithm modules:: How to work with hash algorithm modules. -* Working with hash algorithms:: List of functions related to hashing. - - -File: gcrypt.info, Node: Available hash algorithms, Next: Hash algorithm modules, 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 algorithms ha 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. - -`GCRY_MD_HAVAL' - This is an reserved value for the HAVAL algorithm with 5 passes - and 160 bit. It yields a message digest of 20 bytes. Note that - there is no implementation yet available. - -`GCRY_MD_SHA224' - This is the SHA-224 algorithm which yields a message digest of 28 - bytes. See Change Notice 1 for FIPS 180-2 for the specification. - -`GCRY_MD_SHA256' - This is the SHA-256 algorithm which yields a message digest of 32 - bytes. See FIPS 180-2 for the specification. - -`GCRY_MD_SHA384' - This is the SHA-384 algorithm which yields a message digest of 48 - bytes. See FIPS 180-2 for the specification. - -`GCRY_MD_SHA512' - This is the SHA-384 algorithm which yields a message digest of 64 - bytes. See FIPS 180-2 for the specification. - -`GCRY_MD_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. - - - -File: gcrypt.info, Node: Hash algorithm modules, Next: Working with hash algorithms, Prev: Available hash algorithms, Up: Hashing - -7.2 Hash algorithm modules -========================== - -Libgcrypt makes it possible to load additional `message digest -modules'; these digests can be used just like the message digest -algorithms that are built into the library directly. For an -introduction into extension modules, see *Note Modules::. - - -- Data type: gcry_md_spec_t - This is the `module specification structure' needed for registering - message digest modules, which has to be filled in by the user - before it can be used to register a module. It contains the - following members: - - `const char *name' - The primary name of this algorithm. - - `unsigned char *asnoid' - Array of bytes that form the ASN OID. - - `int asnlen' - Length of bytes in `asnoid'. - - `gcry_md_oid_spec_t *oids' - A list of OIDs that are to be associated with the algorithm. - The list's last element must have it's `oid' member set to - NULL. See below for an explanation of this type. See below - for an explanation of this type. - - `int mdlen' - Length of the message digest algorithm. See below for an - explanation of this type. - - `gcry_md_init_t init' - The function responsible for initializing a handle. See - below for an explanation of this type. - - `gcry_md_write_t write' - The function responsible for writing data into a message - digest context. See below for an explanation of this type. - - `gcry_md_final_t final' - The function responsible for `finalizing' a message digest - context. See below for an explanation of this type. - - `gcry_md_read_t read' - The function responsible for reading out a message digest - result. See below for an explanation of this type. - - `size_t contextsize' - The size of the algorithm-specific `context', that should be - allocated for each handle. - - -- Data type: gcry_md_oid_spec_t - This type is used for associating a user-provided algorithm - implementation with certain OIDs. It contains the following - members: - - `const char *oidstring' - Textual representation of the OID. - - -- Data type: gcry_md_init_t - Type for the `init' function, defined as: void (*gcry_md_init_t) - (void *c) - - -- Data type: gcry_md_write_t - Type for the `write' function, defined as: void (*gcry_md_write_t) - (void *c, unsigned char *buf, size_t nbytes) - - -- Data type: gcry_md_final_t - Type for the `final' function, defined as: void (*gcry_md_final_t) - (void *c) - - -- Data type: gcry_md_read_t - Type for the `read' function, defined as: unsigned char - *(*gcry_md_read_t) (void *c) - - -- Function: gcry_error_t gcry_md_register (gcry_md_spec_t *DIGEST, - unsigned int *algorithm_id, gcry_module_t *MODULE) - Register a new digest module whose specification can be found in - DIGEST. On success, a new algorithm ID is stored in ALGORITHM_ID - and a pointer representing this module is stored in MODULE. - - -- Function: void gcry_md_unregister (gcry_module_t MODULE) - Unregister the digest identified by MODULE, which must have been - registered with gcry_md_register. - - -- Function: gcry_error_t gcry_md_list (int *LIST, int *LIST_LENGTH) - Get a list consisting of the IDs of the loaded message digest - modules. If LIST is zero, write the number of loaded message - digest modules to LIST_LENGTH and return. If LIST is non-zero, - the first *LIST_LENGTH algorithm IDs are stored in LIST, which - must be of according size. In case there are less message digests - modules than *LIST_LENGTH, *LIST_LENGTH is updated to the correct - number. - - -File: gcrypt.info, Node: Working with hash algorithms, Prev: Hash algorithm modules, Up: Hashing - -7.3 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. 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::. - - - 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, set the MAC key to the value of KEY - of length KEYLEN bytes. There is no restriction on the length of - the key. - - 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. - - -- 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' does this implicitly. After this has been - done no further updates (by means of `gcry_md_write' or - `gcry_md_putc' are allowed. 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 reseted (using - `gcry_md_close' or `gcry_md_reset'. 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. - - Because it is often necessary to get the message digest of one block -of memory, a fast convenience function is available for this task: - - -- 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 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 create 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. - - The following two deprecated macros are used for debugging by old -code. They shopuld be replaced by `gcry_md_debug'. - - -- Function: void gcry_md_start_debug (gcry_md_hd_t H, const char - *SUFFIX) - Enable debugging for the digest object with handle H. This - creates create 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'. - - -- Function: void gcry_md_stop_debug (gcry_md_hd_t H, int RESERVED) - Stop debugging on handle H. RESERVED should be specified as 0. - This function is usually not required because `gcry_md_close' does - implicitly stop debugging. - - -File: gcrypt.info, Node: Random Numbers, Next: S-expressions, Prev: Hashing, Up: Top - -8 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 - -8.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 - -8.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 - -9 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 - -9.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 - -9.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. - - `%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. - - `%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 called the "type" and should always exist and 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: 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. - - -File: gcrypt.info, Node: MPI library, Next: Prime numbers, Prev: S-expressions, Up: Top - -10 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. -* 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 - -10.1 Data types -=============== - - -- Data type: gcry_mpi_t - This type represents an object to hold an MPI. - - -File: gcrypt.info, Node: Basic functions, Next: MPI formats, Prev: Data types, Up: MPI library - -10.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. - - -- Function: void gcry_mpi_release (gcry_mpi_t A) - Release the MPI A and free all associated resources. Passing - `NULL' is allowed and ignored. When a MPI stored in the "secure - memory" is released, that memory gets wiped out immediately. - -The simplest operations are used to assign a new value to an MPI: - - -- Function: gcry_mpi_t gcry_mpi_set (gcry_mpi_t W, const gcry_mpi_t U) - Assign the value of U to W and return W. If `NULL' is passed for - W, a new MPI is allocated, set to the value of U and returned. - - -- Function: gcry_mpi_t gcry_mpi_set_ui (gcry_mpi_t W, unsigned long U) - Assign the value of U to W and return W. If `NULL' is passed for - W, a new MPI is allocated, set to the value of U and returned. - This function takes an `unsigned int' as type for U and thus it is - only possible to set W to small values (usually up to the word - size of the CPU). - - -- Function: void gcry_mpi_swap (gcry_mpi_t A, gcry_mpi_t B) - Swap the values of A and B. - - -File: gcrypt.info, Node: MPI formats, Next: Calculations, Prev: Basic functions, Up: MPI library - -10.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'. - 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. - - `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. - - `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 C style string with each byte of the MPI encoded - as 2 hex digits. 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'. - - -- 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 - -10.4 Calculations -================= - -Basic arithmetic operations: - - -- Function: void gcry_mpi_add (gcry_mpi_t W, gcry_mpi_t U, - gcry_mpi_t V) - W = U + V. - - -- Function: void gcry_mpi_add_ui (gcry_mpi_t W, gcry_mpi_t U, - unsigned long V) - W = U + V. Note that V is an unsigned integer. - - -- Function: void gcry_mpi_addm (gcry_mpi_t W, gcry_mpi_t U, - gcry_mpi_t V, gcry_mpi_t M) - W = U + V \bmod M. - - -- Function: void gcry_mpi_sub (gcry_mpi_t W, gcry_mpi_t U, - gcry_mpi_t V) - W = U - V. - - -- Function: void gcry_mpi_sub_ui (gcry_mpi_t W, gcry_mpi_t U, - unsigned long V) - W = U - V. V is an unsigned integer. - - -- Function: void gcry_mpi_subm (gcry_mpi_t W, gcry_mpi_t U, - gcry_mpi_t V, gcry_mpi_t M) - W = U - V \bmod M. - - -- Function: void gcry_mpi_mul (gcry_mpi_t W, gcry_mpi_t U, - gcry_mpi_t V) - W = U * V. - - -- Function: void gcry_mpi_mul_ui (gcry_mpi_t W, gcry_mpi_t U, - unsigned long V) - W = U * V. V is an unsigned integer. - - -- Function: void gcry_mpi_mulm (gcry_mpi_t W, gcry_mpi_t U, - gcry_mpi_t V, gcry_mpi_t M) - W = U * V \bmod M. - - -- Function: void gcry_mpi_mul_2exp (gcry_mpi_t W, gcry_mpi_t U, - unsigned long E) - W = U * 2^e. - - -- Function: void gcry_mpi_div (gcry_mpi_t Q, gcry_mpi_t R, - gcry_mpi_t DIVIDEND, gcry_mpi_t DIVISOR, int ROUND) - Q = DIVIDEND / DIVISOR, R = DIVIDEND \bmod DIVISOR. Q and R may - be passed as `NULL'. ROUND should be negative or 0. - - -- Function: void gcry_mpi_mod (gcry_mpi_t R, gcry_mpi_t DIVIDEND, - gcry_mpi_t DIVISOR) - R = DIVIDEND \bmod DIVISOR. - - -- Function: void gcry_mpi_powm (gcry_mpi_t W, const gcry_mpi_t B, - const gcry_mpi_t E, const gcry_mpi_t M) - W = B^e \bmod M. - - -- Function: int gcry_mpi_gcd (gcry_mpi_t G, gcry_mpi_t A, - gcry_mpi_t B) - Set G to the greatest common divisor of A and B. Return true if - the G is 1. - - -- Function: int gcry_mpi_invm (gcry_mpi_t X, gcry_mpi_t A, - gcry_mpi_t M) - Set X to the multiplicative inverse of A \bmod M. Return true if - the inverse exists. - - -File: gcrypt.info, Node: Comparisons, Next: Bit manipulations, Prev: Calculations, Up: MPI library - -10.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. - - -- 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. - - -File: gcrypt.info, Node: Bit manipulations, Next: Miscellaneous, Prev: Comparisons, Up: MPI library - -10.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: Miscellaneous, Prev: Bit manipulations, Up: MPI library - -10.7 Miscellaneous -================== - - -- 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). - - 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: 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. - - -- Function: void gcry_mpi_set_flag (gcry_mpi_t A, - enum gcry_mpi_flag FLAG) - Set the FLAG for the MPI A. Currently only the flag - `GCRYMPI_FLAG_SECURE' is allowed to convert A into an MPI stored - in "secure memory". - - -- Function: void gcry_mpi_clear_flag (gcry_mpi_t A, - enum gcry_mpi_flag FLAG) - Clear FLAG for the multi-precision-integers A. Note that this - function is currently useless as no flags are allowed. - - -- Function: int gcry_mpi_get_flag (gcry_mpi_t A, - enum gcry_mpi_flag FLAG) - Return true when the FLAG is set for A. - - -- 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 value 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 - -11 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 - -11.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 - -11.2 Checking -============= - - -- Function: gcry_error_t gcry_prime_check (gcry_mpi_t P, unsigned int - FLAGS) - Check wether 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: Architecture, Prev: Prime numbers, Up: Top - -12 Utilities -************ - -* Menu: - -* Memory allocation:: Functions related with memory allocation. - - -File: gcrypt.info, Node: Memory allocation, Up: Utilities - -12.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: Architecture, Next: Self-Tests, Prev: Utilities, Up: Top - -13 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 13.1: Libgcrypt subsystems - - Libgcrypt consists of several subsystems (*note Figure 13.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 - -13.1 Public-Key Architecture -============================ - -Libgcrypt implements two interfaces for public key cryptography: The -standard interface is PK interface using functions in the `gcry_pk_' -name space. The AC interface in an alternative one which is now -deprecated and will not be further described. The AC interface is also -disabled in FIPS mode. - - 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. - - - With the help of the module registration system 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. The interface to the modules is published -(`gcrypt-modules.h') so that it can used to register external -implementations of algorithms with Libgcrypt. However, for some -algorithms this module interface is to limited and thus for the -internal modules an extra interface is sometimes used to convey more -information. - - 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 - -13.2 Symmetric Encryption Subsystem Architecture -================================================ - -The interface to work with symmetric encryption algorithms is made up -of functions from the `gcry_cipher_' name space. The implementation -follows the open-use-close paradigm and uses registered algorithm -modules for the actual work. Unless a module implements optimized -cipher mode implementations, the high level code (`cipher/cipher.c') -implements the modes and calls the core algorithm functions to process -each block. - - The most important functions are: - -`gcry_cipher_open' - Create a new instance to encrypt or decrypt using a specified - algorithm and mode. - -`gcry_cipher_close' - Release an instance. - -`gcry_cipher_setkey' - Set a key to be used for encryption or decryption. - -`gcry_cipher_setiv' - Set an initialization vector to be used for encryption or - decryption. - -`gcry_cipher_encrypt' -`gcry_cipher_decrypt' - Encrypt or decrypt data. These functions may be called with - arbitrary amounts of data and as often as needed to encrypt or - decrypt all data. - - - There are also functions to query properties of algorithms or -context, like block length, key length, map names or to enable features -like padding methods. - - -File: gcrypt.info, Node: Hashing and MACing Subsystem Architecture, Next: Multi-Precision-Integer Subsystem Architecture, Prev: Symmetric Encryption Subsystem Architecture, Up: Architecture - -13.3 Hashing and MACing Subsystem Architecture -============================================== - -The interface to work with message digests and CRC algorithms is made -up of functions from the `gcry_md_' name space. The implementation -follows the open-use-close paradigm and uses registered algorithm -modules for the actual work. Although CRC algorithms are not -considered cryptographic hash algorithms, they share enough properties -so that it makes sense to handle them in the same way. It is possible -to use several algorithms at once with one context and thus compute -them all on the same data. - - The most important functions are: - -`gcry_md_open' - Create a new message digest instance and optionally enable one - algorithm. A flag may be used to turn the message digest algorithm - into a HMAC algorithm. - -`gcry_md_enable' - Enable an additional algorithm for the instance. - -`gcry_md_setkey' - Set the key for the MAC. - -`gcry_md_write' - Pass more data for computing the message digest to an instance. - -`gcry_md_putc' - Buffered version of `gcry_md_write' implemented as a macro. - -`gcry_md_read' - Finalize the computation of the message digest or HMAC and return - the result. - -`gcry_md_close' - Release an instance - -`gcry_md_hash_buffer' - Convenience function to directly compute a message digest over a - memory buffer without the need to create an instance first. - - - There are also functions to query properties of algorithms or the -instance, like enabled algorithms, digest length, map algorithm names. -it is also possible to reset an instance or to copy the current state -of an instance at any time. Debug functions to write the hashed data -to files are available as well. - - -File: gcrypt.info, Node: Multi-Precision-Integer Subsystem Architecture, Next: Prime-Number-Generator Subsystem Architecture, Prev: Hashing and MACing Subsystem Architecture, Up: Architecture - -13.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 - -13.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 shemes 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 - -13.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. - -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 only supported hardware - RNG is the Padlock engine of VIA (Centaur) CPUs. It is not - available in FIPS mode. - - -* 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 - -13.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 RIPE-MD160 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 - -13.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/radnom' 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 stucked 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 orginal random value. The encrtypted result is - then decrypted and checked that it macthes 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 contidion is met. -This may occur at any time; the library does not necessary enter the -"Self-Test" state to run these tests but will transit to the "Error" -state if a test failed. - -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 -------------------------- - -Loading of extra modules into libgcrypt is disabled in FIPS mode and -thus no tests are implemented. (`cipher/cipher.c:_gcry_cipher_register', -`cipher/md.c:_gcry_md_register', `cipher/pubkey.c:_gcry_pk_register') - -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 libray 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. - - * The Alternative Public Key Interface (`gcry_ac_xxx') is not - supported and all API calls return an error. - - * Registration of external modules is not supported. - - * 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 tbl:fips-states::) and checks at runtime that only valid -transitions (*note 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 introducted 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 runing 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 intialization function `gcry_check_version'. - -`3' - Init to Self-Test is either triggred by a dedicated API call or - implicit by invoking a libgrypt service conrolled by the FSM. - -`4' - Self-Test to Operational is triggered after all self-tests passed - successfully. - -`5' - Operational to Shutdown is an artifical 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 triggred 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 artifical state to document that - Libgcrypt has not ye been initializaed but the process is about to - terminate. - -`12' - Power-On to Fatal-Error will be triggerd if certain Libgcrypt - functions are used without having reached the Init state. - -`13' - Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt - while running self-tests. - -`14' - Self-Test to Error is triggred 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 triggred 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 13.1: Libgcrypt subsystems: fig:subsystems. -* Figure B.1: FIPS mode state ...: fig:fips-fsm. - -* Menu: - -* Table B.1: FIPS mode states: tbl:fips-states. -* Table B.2: FIPS mode state ...: tbl:fips-state-transitions. - - -File: gcrypt.info, Node: Concept Index, Next: Function and Data Index, Prev: Figures and Tables, Up: Top - -Concept Index -************* - - -* Menu: - -* 3DES: Available ciphers. (line 16) -* Advanced Encryption Standard: Available ciphers. (line 37) -* AES: Available ciphers. (line 37) -* Arcfour: Available ciphers. (line 54) -* Blowfish: Available ciphers. (line 24) -* Camellia: Available ciphers. (line 81) -* CAST5: Available ciphers. (line 21) -* CBC, Cipher Block Chaining mode: Available cipher modes. - (line 20) -* CBC-MAC: Working with cipher handles. - (line 52) -* CFB, Cipher Feedback mode: Available cipher modes. - (line 16) -* cipher text stealing: Working with cipher handles. - (line 45) -* CRC32: Available hash algorithms. - (line 6) -* CTR, Counter mode: Available cipher modes. - (line 29) -* DES: Available ciphers. (line 59) -* DES-EDE: Available ciphers. (line 16) -* Digital Encryption Standard: Available ciphers. (line 16) -* ECB, Electronic Codebook mode: Available cipher modes. - (line 13) -* Enforced FIPS mode: Enabling FIPS mode. (line 30) -* error codes: Error Values. (line 6) -* error codes, list of <1>: Error Codes. (line 6) -* error codes, list of: Error Sources. (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 <1>: Public-Key Subsystem Architecture. - (line 63) -* FIPS 186: General public-key related Functions. - (line 256) -* FIPS mode: Enabling FIPS mode. (line 6) -* GPL, GNU General Public License: Copying. (line 6) -* HAVAL: Available hash algorithms. - (line 6) -* HMAC: Working with hash algorithms. - (line 27) -* IDEA: Available ciphers. (line 11) -* LGPL, GNU Lesser General Public License: Library Copying. (line 6) -* MD2, MD4, MD5: Available hash algorithms. - (line 6) -* OFB, Output Feedback mode: Available cipher modes. - (line 26) -* RC2: Available ciphers. (line 71) -* RC4: Available ciphers. (line 54) -* rfc-2268: Available ciphers. (line 71) -* Rijndael: Available ciphers. (line 37) -* RIPE-MD-160: Available hash algorithms. - (line 6) -* Seed (cipher): Available ciphers. (line 76) -* Serpent: Available ciphers. (line 67) -* SHA-1: Available hash algorithms. - (line 6) -* SHA-224, SHA-256, SHA-384, SHA-512: Available hash algorithms. - (line 6) -* sync mode (OpenPGP): Working with cipher handles. - (line 40) -* TIGER: Available hash algorithms. - (line 6) -* Triple-DES: Available ciphers. (line 16) -* Twofish: Available ciphers. (line 48) -* Whirlpool: Available hash algorithms. - (line 6) -* X9.31 <1>: Public-Key Subsystem Architecture. - (line 63) -* X9.31: General public-key related Functions. - (line 249) - - -File: gcrypt.info, Node: Function and Data Index, Prev: Concept Index, Up: Top - -Function and Data Index -*********************** - - -* Menu: - -* AM_PATH_LIBGCRYPT: Building sources using Automake. - (line 13) -* gcry_ac_close: Working with handles. - (line 21) -* gcry_ac_data_clear: Working with sets of data. - (line 75) -* gcry_ac_data_copy: Working with sets of data. - (line 53) -* gcry_ac_data_decode: Using cryptographic functions. - (line 100) -* gcry_ac_data_decrypt: Using cryptographic functions. - (line 40) -* gcry_ac_data_decrypt_scheme: Using cryptographic functions. - (line 137) -* gcry_ac_data_destroy: Working with sets of data. - (line 41) -* gcry_ac_data_encode: Using cryptographic functions. - (line 93) -* gcry_ac_data_encrypt: Using cryptographic functions. - (line 33) -* gcry_ac_data_encrypt_scheme: Using cryptographic functions. - (line 127) -* gcry_ac_data_from_sexp: Working with sets of data. - (line 93) -* gcry_ac_data_get_index: Working with sets of data. - (line 69) -* gcry_ac_data_get_name: Working with sets of data. - (line 61) -* gcry_ac_data_length: Working with sets of data. - (line 57) -* gcry_ac_data_new: Working with sets of data. - (line 38) -* gcry_ac_data_set: Working with sets of data. - (line 45) -* gcry_ac_data_sign: Using cryptographic functions. - (line 48) -* gcry_ac_data_sign_scheme: Using cryptographic functions. - (line 147) -* gcry_ac_data_t: Working with sets of data. - (line 20) -* gcry_ac_data_to_sexp: Working with sets of data. - (line 79) -* gcry_ac_data_verify: Using cryptographic functions. - (line 54) -* gcry_ac_data_verify_scheme: Using cryptographic functions. - (line 157) -* gcry_ac_id_t: Available asymmetric algorithms. - (line 11) -* gcry_ac_id_to_name: Handle-independent functions. - (line 10) -* gcry_ac_io_init: Working with IO objects. - (line 22) -* gcry_ac_io_init_va: Working with IO objects. - (line 28) -* gcry_ac_io_t: Working with IO objects. - (line 10) -* gcry_ac_key_data_get: Working with keys. (line 93) -* gcry_ac_key_destroy: Working with keys. (line 86) -* gcry_ac_key_get_grip: Working with keys. (line 105) -* gcry_ac_key_get_nbits: Working with keys. (line 101) -* gcry_ac_key_init: Working with keys. (line 30) -* gcry_ac_key_pair_destroy: Working with keys. (line 90) -* gcry_ac_key_pair_extract: Working with keys. (line 83) -* gcry_ac_key_pair_generate: Working with keys. (line 36) -* gcry_ac_key_pair_t: Working with keys. (line 20) -* gcry_ac_key_t: Working with keys. (line 16) -* gcry_ac_key_test: Working with keys. (line 97) -* gcry_ac_key_type_t: Working with keys. (line 7) -* gcry_ac_name_to_id: Handle-independent functions. - (line 15) -* gcry_ac_open: Working with handles. - (line 11) -* gcry_calloc: Memory allocation. (line 15) -* gcry_calloc_secure: Memory allocation. (line 21) -* gcry_check_version: Initializing the library. - (line 17) -* gcry_cipher_algo_info: General cipher functions. - (line 12) -* gcry_cipher_algo_name: General cipher functions. - (line 39) -* gcry_cipher_close: Working with cipher handles. - (line 59) -* gcry_cipher_ctl: Working with cipher handles. - (line 159) -* gcry_cipher_decrypt: Working with cipher handles. - (line 129) -* gcry_cipher_decrypt_t: Cipher modules. (line 80) -* gcry_cipher_encrypt: Working with cipher handles. - (line 110) -* gcry_cipher_encrypt_t: Cipher modules. (line 75) -* gcry_cipher_info: Working with cipher handles. - (line 168) -* gcry_cipher_list: Cipher modules. (line 106) -* gcry_cipher_map_name: General cipher functions. - (line 45) -* gcry_cipher_mode_from_oid: General cipher functions. - (line 50) -* gcry_cipher_oid_spec_t: Cipher modules. (line 60) -* gcry_cipher_open: Working with cipher handles. - (line 11) -* gcry_cipher_register: Cipher modules. (line 96) -* gcry_cipher_reset: Working with cipher handles. - (line 97) -* gcry_cipher_setctr: Working with cipher handles. - (line 90) -* gcry_cipher_setiv: Working with cipher handles. - (line 83) -* gcry_cipher_setkey: Working with cipher handles. - (line 68) -* gcry_cipher_setkey_t: Cipher modules. (line 70) -* gcry_cipher_spec_t: Cipher modules. (line 12) -* gcry_cipher_stdecrypt_t: Cipher modules. (line 90) -* gcry_cipher_stencrypt_t: Cipher modules. (line 85) -* gcry_cipher_sync: Working with cipher handles. - (line 149) -* gcry_cipher_unregister: Cipher modules. (line 101) -* gcry_control: Controlling the library. - (line 7) -* gcry_create_nonce: Retrieving random numbers. - (line 26) -* gcry_err_code: Error Values. (line 43) -* gcry_err_code_from_errno: Error Values. (line 95) -* gcry_err_code_t: Error Values. (line 7) -* gcry_err_code_to_errno: Error Values. (line 100) -* gcry_err_make: Error Values. (line 57) -* gcry_err_make_from_errno: Error Values. (line 81) -* gcry_err_source: Error Values. (line 49) -* gcry_err_source_t: Error Values. (line 14) -* gcry_error: Error Values. (line 64) -* gcry_error_from_errno: Error Values. (line 86) -* gcry_error_t: Error Values. (line 25) -* gcry_fips_mode_active: Controlling the library. - (line 221) -* gcry_free: Memory allocation. (line 31) -* gcry_handler_alloc_t: Allocation handler. (line 12) -* gcry_handler_error_t: Error handler. (line 27) -* gcry_handler_free_t: Allocation handler. (line 24) -* gcry_handler_log_t: Logging handler. (line 7) -* gcry_handler_no_mem_t: Error handler. (line 11) -* gcry_handler_progress_t: Progress handler. (line 10) -* gcry_handler_realloc_t: Allocation handler. (line 20) -* gcry_handler_secure_check_t: Allocation handler. (line 16) -* gcry_malloc: Memory allocation. (line 7) -* gcry_malloc_secure: Memory allocation. (line 12) -* gcry_md_algo_name: Working with hash algorithms. - (line 154) -* gcry_md_close: Working with hash algorithms. - (line 61) -* gcry_md_copy: Working with hash algorithms. - (line 84) -* gcry_md_debug: Working with hash algorithms. - (line 218) -* gcry_md_enable: Working with hash algorithms. - (line 44) -* gcry_md_final: Working with hash algorithms. - (line 112) -* gcry_md_final_t: Hash algorithm modules. - (line 73) -* gcry_md_get_algo: Working with hash algorithms. - (line 198) -* gcry_md_get_algo_dlen: Working with hash algorithms. - (line 189) -* gcry_md_get_asnoid: Working with hash algorithms. - (line 170) -* gcry_md_hash_buffer: Working with hash algorithms. - (line 137) -* gcry_md_init_t: Hash algorithm modules. - (line 65) -* gcry_md_is_enabled: Working with hash algorithms. - (line 209) -* gcry_md_is_secure: Working with hash algorithms. - (line 204) -* gcry_md_list: Hash algorithm modules. - (line 91) -* gcry_md_map_name: Working with hash algorithms. - (line 160) -* gcry_md_oid_spec_t: Hash algorithm modules. - (line 57) -* gcry_md_open: Working with hash algorithms. - (line 11) -* gcry_md_putc: Working with hash algorithms. - (line 102) -* gcry_md_read: Working with hash algorithms. - (line 122) -* gcry_md_read_t: Hash algorithm modules. - (line 77) -* gcry_md_register: Hash algorithm modules. - (line 82) -* gcry_md_reset: Working with hash algorithms. - (line 72) -* gcry_md_setkey: Working with hash algorithms. - (line 53) -* gcry_md_spec_t: Hash algorithm modules. - (line 12) -* gcry_md_start_debug: Working with hash algorithms. - (line 232) -* gcry_md_stop_debug: Working with hash algorithms. - (line 240) -* gcry_md_test_algo: Working with hash algorithms. - (line 183) -* gcry_md_unregister: Hash algorithm modules. - (line 87) -* gcry_md_write: Working with hash algorithms. - (line 97) -* gcry_md_write_t: Hash algorithm modules. - (line 69) -* gcry_module_t: Modules. (line 10) -* gcry_mpi_add: Calculations. (line 10) -* gcry_mpi_add_ui: Calculations. (line 14) -* gcry_mpi_addm: Calculations. (line 18) -* gcry_mpi_aprint: MPI formats. (line 54) -* gcry_mpi_clear_bit: Bit manipulations. (line 19) -* gcry_mpi_clear_flag: Miscellaneous. (line 32) -* gcry_mpi_clear_highbit: Bit manipulations. (line 25) -* gcry_mpi_cmp: Comparisons. (line 9) -* gcry_mpi_cmp_ui: Comparisons. (line 13) -* gcry_mpi_copy: Basic functions. (line 23) -* gcry_mpi_div: Calculations. (line 50) -* gcry_mpi_dump: MPI formats. (line 61) -* gcry_mpi_gcd: Calculations. (line 63) -* gcry_mpi_get_flag: Miscellaneous. (line 37) -* gcry_mpi_get_nbits: Bit manipulations. (line 10) -* gcry_mpi_get_opaque: Miscellaneous. (line 20) -* gcry_mpi_invm: Calculations. (line 68) -* gcry_mpi_lshift: Bit manipulations. (line 34) -* gcry_mpi_mod: Calculations. (line 55) -* gcry_mpi_mul: Calculations. (line 34) -* gcry_mpi_mul_2exp: Calculations. (line 46) -* gcry_mpi_mul_ui: Calculations. (line 38) -* gcry_mpi_mulm: Calculations. (line 42) -* gcry_mpi_new: Basic functions. (line 10) -* gcry_mpi_powm: Calculations. (line 59) -* gcry_mpi_print: MPI formats. (line 45) -* gcry_mpi_randomize: Miscellaneous. (line 41) -* gcry_mpi_release: Basic functions. (line 26) -* gcry_mpi_rshift: Bit manipulations. (line 29) -* gcry_mpi_scan: MPI formats. (line 12) -* gcry_mpi_set: Basic functions. (line 33) -* gcry_mpi_set_bit: Bit manipulations. (line 16) -* gcry_mpi_set_flag: Miscellaneous. (line 26) -* gcry_mpi_set_highbit: Bit manipulations. (line 22) -* gcry_mpi_set_opaque: Miscellaneous. (line 8) -* gcry_mpi_set_ui: Basic functions. (line 37) -* gcry_mpi_snew: Basic functions. (line 17) -* gcry_mpi_sub: Calculations. (line 22) -* gcry_mpi_sub_ui: Calculations. (line 26) -* gcry_mpi_subm: Calculations. (line 30) -* gcry_mpi_swap: Basic functions. (line 44) -* gcry_mpi_t: Data types. (line 7) -* gcry_mpi_test_bit: Bit manipulations. (line 13) -* gcry_pk_algo_info: General public-key related Functions. - (line 47) -* gcry_pk_algo_name: General public-key related Functions. - (line 10) -* gcry_pk_check_secret_key_t: Public key modules. (line 91) -* gcry_pk_ctl: General public-key related Functions. - (line 100) -* gcry_pk_decrypt: Cryptographic Functions. - (line 85) -* gcry_pk_decrypt_t: Public key modules. (line 101) -* gcry_pk_encrypt: Cryptographic Functions. - (line 29) -* gcry_pk_encrypt_t: Public key modules. (line 96) -* gcry_pk_generate_t: Public key modules. (line 86) -* gcry_pk_genkey: General public-key related Functions. - (line 115) -* gcry_pk_get_keygrip: General public-key related Functions. - (line 29) -* gcry_pk_get_nbits: General public-key related Functions. - (line 24) -* gcry_pk_get_nbits_t: Public key modules. (line 116) -* gcry_pk_list: Public key modules. (line 131) -* gcry_pk_map_name: General public-key related Functions. - (line 16) -* gcry_pk_register: Public key modules. (line 121) -* gcry_pk_sign: Cryptographic Functions. - (line 117) -* gcry_pk_sign_t: Public key modules. (line 106) -* gcry_pk_spec_t: Public key modules. (line 12) -* gcry_pk_test_algo: General public-key related Functions. - (line 20) -* gcry_pk_testkey: General public-key related Functions. - (line 40) -* gcry_pk_unregister: Public key modules. (line 127) -* gcry_pk_verify: Cryptographic Functions. - (line 170) -* gcry_pk_verify_t: Public key modules. (line 111) -* gcry_prime_check: Checking. (line 8) -* gcry_prime_generate: Generation. (line 10) -* gcry_prime_group_generator: Generation. (line 19) -* gcry_prime_release_factors: Generation. (line 25) -* gcry_random_bytes: Retrieving random numbers. - (line 13) -* gcry_random_bytes_secure: Retrieving random numbers. - (line 19) -* gcry_random_level_t: Quality of random numbers. - (line 9) -* gcry_randomize: Retrieving random numbers. - (line 8) -* gcry_realloc: Memory allocation. (line 24) -* gcry_set_allocation_handler: Allocation handler. (line 34) -* gcry_set_fatalerror_handler: Error handler. (line 32) -* gcry_set_log_handler: Logging handler. (line 12) -* gcry_set_outofcore_handler: Error handler. (line 16) -* gcry_set_progress_handler: Progress handler. (line 21) -* gcry_sexp_build: Working with S-expressions. - (line 43) -* gcry_sexp_canon_len: Working with S-expressions. - (line 126) -* gcry_sexp_car: Working with S-expressions. - (line 155) -* gcry_sexp_cdr: Working with S-expressions. - (line 160) -* gcry_sexp_create: Working with S-expressions. - (line 26) -* gcry_sexp_dump: Working with S-expressions. - (line 117) -* gcry_sexp_find_token: Working with S-expressions. - (line 138) -* gcry_sexp_length: Working with S-expressions. - (line 145) -* gcry_sexp_new: Working with S-expressions. - (line 13) -* gcry_sexp_nth: Working with S-expressions. - (line 150) -* gcry_sexp_nth_data: Working with S-expressions. - (line 168) -* gcry_sexp_nth_mpi: Working with S-expressions. - (line 193) -* gcry_sexp_nth_string: Working with S-expressions. - (line 185) -* gcry_sexp_release: Working with S-expressions. - (line 83) -* gcry_sexp_sprint: Working with S-expressions. - (line 94) -* gcry_sexp_sscan: Working with S-expressions. - (line 37) -* gcry_sexp_t: Data types for S-expressions. - (line 7) -* gcry_strerror: Error Strings. (line 7) -* gcry_strsource: Error Strings. (line 13) - - - -Tag Table: -Node: Top775 -Node: Introduction2994 -Node: Getting Started3366 -Node: Features4247 -Node: Overview5031 -Node: Preparation5662 -Node: Header6519 -Node: Building sources7589 -Node: Building sources using Automake9503 -Node: Initializing the library10685 -Ref: sample-use-suspend-secmem13860 -Ref: sample-use-resume-secmem14480 -Node: Multi-Threading15376 -Ref: Multi-Threading-Footnote-119389 -Node: Enabling FIPS mode19797 -Node: Generalities21663 -Node: Controlling the library21988 -Node: Modules34155 -Node: Error Handling34934 -Node: Error Values37457 -Node: Error Sources42397 -Node: Error Codes44668 -Node: Error Strings48153 -Node: Handler Functions49336 -Node: Progress handler49895 -Node: Allocation handler51891 -Node: Error handler53442 -Node: Logging handler55009 -Node: Symmetric cryptography55601 -Node: Available ciphers56406 -Node: Cipher modules58913 -Node: Available cipher modes63437 -Node: Working with cipher handles64316 -Node: General cipher functions72631 -Node: Public Key cryptography75149 -Node: Available algorithms76064 -Node: Used S-expressions76413 -Node: RSA key parameters77525 -Node: DSA key parameters78800 -Node: ECC key parameters79458 -Node: Public key modules81223 -Node: Cryptographic Functions86807 -Node: General public-key related Functions94287 -Node: AC Interface106576 -Node: Available asymmetric algorithms107711 -Node: Working with sets of data108380 -Node: Working with IO objects112882 -Node: Working with handles115602 -Node: Working with keys116549 -Node: Using cryptographic functions120631 -Node: Handle-independent functions127538 -Node: Hashing128286 -Node: Available hash algorithms129077 -Node: Hash algorithm modules132184 -Node: Working with hash algorithms136032 -Node: Random Numbers147334 -Node: Quality of random numbers147608 -Node: Retrieving random numbers148292 -Node: S-expressions149776 -Node: Data types for S-expressions150418 -Node: Working with S-expressions150742 -Node: MPI library160113 -Node: Data types161071 -Node: Basic functions161265 -Node: MPI formats163333 -Node: Calculations166216 -Node: Comparisons168470 -Node: Bit manipulations169114 -Node: Miscellaneous170429 -Node: Prime numbers172398 -Node: Generation172668 -Node: Checking173952 -Node: Utilities174365 -Node: Memory allocation174558 -Node: Architecture175885 -Ref: fig:subsystems177405 -Ref: Architecture-Footnote-1178490 -Ref: Architecture-Footnote-2178552 -Node: Public-Key Subsystem Architecture178636 -Node: Symmetric Encryption Subsystem Architecture181577 -Node: Hashing and MACing Subsystem Architecture183024 -Node: Multi-Precision-Integer Subsystem Architecture184948 -Node: Prime-Number-Generator Subsystem Architecture186389 -Ref: Prime-Number-Generator Subsystem Architecture-Footnote-1188320 -Node: Random-Number Subsystem Architecture188607 -Node: CSPRNG Description191096 -Ref: CSPRNG Description-Footnote-1192658 -Node: FIPS PRNG Description192781 -Node: Self-Tests194916 -Node: FIPS Mode206607 -Ref: fig:fips-fsm210587 -Ref: tbl:fips-states210689 -Ref: tbl:fips-state-transitions211942 -Node: Library Copying215556 -Node: Copying243674 -Node: Figures and Tables262848 -Node: Concept Index263258 -Node: Function and Data Index268823 - -End Tag Table diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi b/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi deleted file mode 100644 index a2993df97e..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/gcrypt.texi +++ /dev/null @@ -1,5867 +0,0 @@ -\input texinfo @c -*- Texinfo -*- -@c %**start of header -@setfilename gcrypt.info -@include version.texi -@settitle The Libgcrypt Reference Manual -@c Unify some of the indices. -@syncodeindex tp fn -@syncodeindex pg fn -@c %**end of header -@copying -This manual is for Libgcrypt -(version @value{VERSION}, @value{UPDATED}), -which is GNU's library of cryptographic building blocks. - -Copyright @copyright{} 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -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 -@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 and MAC algorithms. -* 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. -* 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 common error handling related code for 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. -@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 defintions 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 compilers -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. -@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, with the exception of the @code{GCRYCTL_SET_THREAD_CBS} command -(called via the @code{gcry_control} function). -@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 intialized. */ - if (!gcry_check_version (GCRYPT_VERSION)) - @{ - fputs ("libgcrypt version mismatch\n", stderr); - 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 intialized. */ - if (!gcry_check_version (GCRYPT_VERSION)) - @{ - fputs ("libgcrypt version mismatch\n", stderr); - 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 intialized. */ - - /* Allocate a pool of 16k secure memory. This make the secure memory - available and also drops privileges where needed. */ - 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 your application is multi-threaded, you must set the thread support -callbacks with the @code{GCRYCTL_SET_THREAD_CBS} command -@strong{before} any other function in the library. - -This is easy enough if you are indeed writing an application using -Libgcrypt. It is rather problematic if you are writing a library -instead. Here are some tips what to do if you are writing a library: - -If your library requires a certain thread package, just initialize -Libgcrypt to use this thread package. If your library supports multiple -thread packages, but needs to be configured, you will have to -implement a way to determine which thread package the application -wants to use with your library anyway. Then configure Libgcrypt to use -this thread package. - -If your library is fully reentrant without any special support by a -thread package, then you are lucky indeed. Unfortunately, this does -not relieve you from doing either of the two above, or use a third -option. The third option is to let the application initialize Libgcrypt -for you. Then you are not using Libgcrypt transparently, though. - -As if this was not difficult enough, a conflict may arise if two -libraries try to initialize Libgcrypt independently of each others, and -both such libraries are then linked into the same application. To -make it a bit simpler for you, this will probably work, but only if -both libraries have the same requirement for the thread package. This -is currently only supported for the non-threaded case, GNU Pth and -pthread. Support for more thread packages is easy to add, so contact -us if you require it. - -@item -The function @code{gcry_check_version} must be called before any other -function in the library, except the @code{GCRYCTL_SET_THREAD_CBS} -command (called via the @code{gcry_control} function), because it -initializes the thread support subsystem in Libgcrypt. To -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 - - -Libgcrypt contains convenient macros, which define the -necessary thread callbacks for PThread and for GNU Pth: - -@table @code -@item GCRY_THREAD_OPTION_PTH_IMPL - -This macro defines the following (static) symbols: -@code{gcry_pth_init}, @code{gcry_pth_mutex_init}, -@code{gcry_pth_mutex_destroy}, @code{gcry_pth_mutex_lock}, -@code{gcry_pth_mutex_unlock}, @code{gcry_pth_read}, -@code{gcry_pth_write}, @code{gcry_pth_select}, -@code{gcry_pth_waitpid}, @code{gcry_pth_accept}, -@code{gcry_pth_connect}, @code{gcry_threads_pth}. - -After including this macro, @code{gcry_control()} shall be used with a -command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the -thread callback structure named ``gcry_threads_pth''. - -@item GCRY_THREAD_OPTION_PTHREAD_IMPL - -This macro defines the following (static) symbols: -@code{gcry_pthread_mutex_init}, @code{gcry_pthread_mutex_destroy}, -@code{gcry_pthread_mutex_lock}, @code{gcry_pthread_mutex_unlock}, -@code{gcry_threads_pthread}. - -After including this macro, @code{gcry_control()} shall be used with a -command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the -thread callback structure named ``gcry_threads_pthread''. -@end table - -Note that these macros need to be terminated with a semicolon. Keep -in mind that these are convenient macros for C programmers; C++ -programmers might have to wrap these macros in an ``extern C'' body. - - -@node Enabling FIPS mode -@section How to enable the FIPS mode -@cindex FIPS mode -@cindex FIPS 140 - -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}. 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. - - - -@c ********************************************************** -@c ******************* General **************************** -@c ********************************************************** -@node Generalities -@chapter Generalities - -@menu -* Controlling the library:: Controlling Libgcrypt's behavior. -* Modules:: Description of extension modules. -* 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 at initialization time. 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 recommened. However, -for some applications the extra quality random Libgcrypt tries to create -is not justified and this option may help to get better performace. -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 randum number generator related statistics to the -library's logging stream. - -@item GCRYCTL_DUMP_MEMORY_STATS; Arguments: none -This command dumps memory managment related statistics to the library's -logging stream. - -@item GCRYCTL_DUMP_SECMEM_STATS; Arguments: none -This command dumps secure memory manamgent 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 priviliges -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_INIT_SECMEM; Arguments: int nbytes -This command is used to allocate a pool of secure memory and thus -enabling the use of secure memory. It also drops all extra privileges -the process has (i.e. if it is run as setuid (root)). If the argument -@var{nbytes} is 0, secure memory will be disabled. The minimum amount -of secure memory allocated is currently 16384 bytes; you may thus use a -value of 1 to request that default size. - -@item GCRYCTL_TERM_SECMEM; Arguments: none -This command zeroises the secure memory and destroys the handler. The -secure memory pool may not be used anymore after running this command. -If the secure memory pool as already been destroyed, this command has -no effect. Applications might want to run this command from their -exit handler to make sure that the secure memory gets properly -destroyed. This command is not necessarily thread-safe but that -should not be needed in cleanup code. It may be called from a signal -handler. - -@item GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none -Disable warning messages about problems with the secure memory -subsystem. This command should be run right after -@code{gcry_check_version}. - -@item GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none -Postpone warning messages from the secure memory subsystem. -@xref{sample-use-suspend-secmem,,the initialization example}, on how to -use it. - -@item GCRYCTL_RESUME_SECMEM_WARN; Arguments: none -Resume warning messages from the secure memory subsystem. -@xref{sample-use-resume-secmem,,the initialization example}, on how to -use it. - -@item GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none -This command tells the PRNG to store random numbers in secure memory. -This command should be run right after @code{gcry_check_version} and not -later than the command GCRYCTL_INIT_SECMEM. Note that in FIPS mode the -secure memory is always used. - -@item GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename -This command specifies the file, which is to be used as seed file for -the PRNG. If the seed file is registered prior to initialization of the -PRNG, the seed file's content (if it exists and seems to be valid) is -fed into the PRNG pool. After the seed file has been registered, the -PRNG can be signalled to write out the PRNG pool's content into the seed -file with the following command. - - -@item GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none -Write out the PRNG pool's content into the registered seed file. - -Multiple instances of the applications sharing the same random seed file -can be started in parallel, in which case they will read out the same -pool and then race for updating it (the last update overwrites earlier -updates). They will differentiate only by the weak entropy that is -added in read_seed_file based on the PID and clock, and up to 16 bytes -of weak random non-blockingly. The consequence is that the output of -these different instances is correlated to some extent. In a perfect -attack scenario, the attacker can control (or at least guess) the PID -and clock of the application, and drain the system's entropy pool to -reduce the "up to 16 bytes" above to 0. Then the dependencies of the -inital 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_SET_VERBOSITY; Arguments: int level -This command sets the verbosity of the logging. A level of 0 disables -all extra logging whereas positive numbers enable more verbose logging. -The level may be changed at any time but be aware that no memory -synchronization is done so the effect of this command might not -immediately show up in other threads. This command may even be used -prior to @code{gcry_check_version}. - -@item GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags -Set the debug flag bits as given by the argument. Be aware that that no -memory synchronization is done so the effect of this command might not -immediately show up in other threads. The debug flags are not -considered part of the API and thus may change without notice. As of -now bit 0 enables debugging of cipher functions and bit 1 debugging of -multi-precision-integers. This command may even be used prior to -@code{gcry_check_version}. - -@item GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags -Set the debug flag bits as given by the argument. Be aware that that no -memory synchronization is done so the effect of this command might not -immediately show up in other threads. This command may even be used -prior to @code{gcry_check_version}. - -@item GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none -This command does nothing. It exists only for backward compatibility. - -@item GCRYCTL_ANY_INITIALIZATION_P; Arguments: none -This command returns true if the library has been basically initialized. -Such a basic initialization happens implicitly with many commands to get -certain internal subsystems running. The common and suggested way to -do this basic intialization is by calling gcry_check_version. - -@item GCRYCTL_INITIALIZATION_FINISHED; Arguments: none -This command tells the libray that the application has finished the -intialization. - -@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 registers a thread-callback structure. -@xref{Multi-Threading}. - -@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 intialization has -been finished but not before a gcry_version_check. - -@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 intialization has been finished but not before a gcry_version_check. - -@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 intialization has been finished but not -before a gcry_version_check. An application may use this command or -the convenience macro below to check whether FIPS mode is actually -active. - -@deftypefun int gcry_fips_mode_active (void) - -Returns true if the FIPS mode is active. Note that this is -implemented as a macro. -@end deftypefun - - - -@item GCRYCTL_FORCE_FIPS_MODE; Arguments: none -Running this command puts the library into FIPS mode. If the library is -already in FIPS mode, a 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 intialization. - -@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. - - -@end table - -@end deftypefun - -@node Modules -@section Modules - -Libgcrypt supports the use of `extension modules', which -implement algorithms in addition to those already built into the library -directly. - -@deftp {Data type} gcry_module_t -This data type represents a `module'. -@end deftp - -Functions registering modules provided by the user take a `module -specification structure' as input and return a value of -@code{gcry_module_t} and an ID that is unique in the modules' -category. This ID can be used to reference the newly registered -module. After registering a module successfully, the new functionality -should be able to be used through the normal functions provided by -Libgcrypt until it is unregistered again. - -@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_strerror} 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 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. -* Cipher modules:: How to work with cipher modules. -* 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. The constant is provided but there is -currently no implementation for it because the algorithm is patented. - -@item GCRY_CIPHER_3DES -@cindex 3DES -@cindex Triple-DES -@cindex DES-EDE -@cindex Digital Encryption Standard -Triple-DES with 3 Keys as EDE. The key size of this algorithm is 168 but -you have to pass 192 bits because the most significant bits of each byte -are ignored. - -@item GCRY_CIPHER_CAST5 -@cindex CAST5 -CAST128-5 block cipher algorithm. The key size is 128 bits. - -@item GCRY_CIPHER_BLOWFISH -@cindex Blowfish -The blowfish algorithm. The current implementation allows only for a key -size of 128 bits. - -@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. Note, that we currently -only support the 40 bit variant. The identifier for 128 is reserved for -future use. - -@item GCRY_CIPHER_SEED -@cindex Seed (cipher) -A 128 bit cipher as described by RFC4269. - -@item GCRY_CIPHER_CAMELLIA128 -@itemx GCRY_CIPHER_CAMELLIA192 -@itemx GCRY_CIPHER_CAMELLIA256 -@cindex Camellia -The Camellia cipher by NTT. See -@uref{http://info.isl.ntt.co.jp/@/crypt/@/eng/@/camellia/@/specifications.html}. - -@end table - -@node Cipher modules -@section Cipher modules - -Libgcrypt makes it possible to load additional `cipher modules'; these -ciphers can be used just like the cipher algorithms that are built -into the library directly. For an introduction into extension -modules, see @xref{Modules}. - -@deftp {Data type} gcry_cipher_spec_t -This is the `module specification structure' needed for registering -cipher modules, which has to be filled in by the user before it can be -used to register a module. It contains the following members: - -@table @code -@item const char *name -The primary name of the algorithm. -@item const char **aliases -A list of strings that are `aliases' for the algorithm. The list must -be terminated with a NULL element. -@item gcry_cipher_oid_spec_t *oids -A list of OIDs that are to be associated with the algorithm. The -list's last element must have it's `oid' member set to NULL. See -below for an explanation of this type. -@item size_t blocksize -The block size of the algorithm, in bytes. -@item size_t keylen -The length of the key, in bits. -@item size_t contextsize -The size of the algorithm-specific `context', that should be allocated -for each handle. -@item gcry_cipher_setkey_t setkey -The function responsible for initializing a handle with a provided -key. See below for a description of this type. -@item gcry_cipher_encrypt_t encrypt -The function responsible for encrypting a single block. See below for -a description of this type. -@item gcry_cipher_decrypt_t decrypt -The function responsible for decrypting a single block. See below for -a description of this type. -@item gcry_cipher_stencrypt_t stencrypt -Like `encrypt', for stream ciphers. See below for a description of -this type. -@item gcry_cipher_stdecrypt_t stdecrypt -Like `decrypt', for stream ciphers. See below for a description of -this type. -@end table -@end deftp - -@deftp {Data type} gcry_cipher_oid_spec_t -This type is used for associating a user-provided algorithm -implementation with certain OIDs. It contains the following members: -@table @code -@item const char *oid -Textual representation of the OID. -@item int mode -Cipher mode for which this OID is valid. -@end table -@end deftp - -@deftp {Data type} gcry_cipher_setkey_t -Type for the `setkey' function, defined as: gcry_err_code_t -(*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned -keylen) -@end deftp - -@deftp {Data type} gcry_cipher_encrypt_t -Type for the `encrypt' function, defined as: gcry_err_code_t -(*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const -unsigned char *inbuf) -@end deftp - -@deftp {Data type} gcry_cipher_decrypt_t -Type for the `decrypt' function, defined as: gcry_err_code_t -(*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const -unsigned char *inbuf) -@end deftp - -@deftp {Data type} gcry_cipher_stencrypt_t -Type for the `stencrypt' function, defined as: gcry_err_code_t -(*gcry_@/cipher_@/stencrypt_@/t) (void *c, const unsigned char *outbuf, const -unsigned char *, unsigned int n) -@end deftp - -@deftp {Data type} gcry_cipher_stdecrypt_t -Type for the `stdecrypt' function, defined as: gcry_err_code_t -(*gcry_@/cipher_@/stdecrypt_@/t) (void *c, const unsigned char *outbuf, const -unsigned char *, unsigned int n) -@end deftp - -@deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module}) - -Register a new cipher module whose specification can be found in -@var{cipher}. On success, a new algorithm ID is stored in -@var{algorithm_id} and a pointer representing this module is stored -in @var{module}. -@end deftypefun - -@deftypefun void gcry_cipher_unregister (gcry_module_t @var{module}) -Unregister the cipher identified by @var{module}, which must have been -registered with gcry_cipher_register. -@end deftypefun - -@deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length}) -Get a list consisting of the IDs of the loaded cipher modules. If -@var{list} is zero, write the number of loaded cipher modules to -@var{list_length} and return. If @var{list} is non-zero, the first -*@var{list_length} algorithm IDs are stored in @var{list}, which must -be of according size. In case there are less cipher modules than -*@var{list_length}, *@var{list_length} is updated to the correct -number. -@end deftypefun - -@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 -@cindex CFB, Cipher Feedback mode -Cipher Feedback mode. The shift size equals the block size of the -cipher (e.g. for AES it is CFB-128). - -@item GCRY_CIPHER_MODE_CBC -@cindex CBC, Cipher Block Chaining mode -Cipher Block Chaining mode. - -@item GCRY_CIPHER_MODE_STREAM -Stream mode, only to be used with stream cipher algorithms. - -@item GCRY_CIPHER_MODE_OFB -@cindex OFB, Output Feedback mode -Output Feedback mode. - -@item GCRY_CIPHER_MODE_CTR -@cindex CTR, Counter mode -Counter mode. - -@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 -@xref{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 -@xref{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. Any -block cipher mode (@code{GCRY_CIPHER_MODE_ECB}, -@code{GCRY_CIPHER_MODE_CBC}, @code{GCRY_CIPHER_MODE_CFB}, -@code{GCRY_CIPHER_MODE_OFB} or @code{GCRY_CIPHER_MODE_CTR}) will work -with any block cipher algorithm. - -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. -@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 - -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} or -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. - -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. - -The function returns @code{0} on success or an error code. -@end deftypefun - - -OpenPGP (as defined in RFC-2440) requires a special sync operation in -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. - -Currently no information is available. -@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. - -@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. - -@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 {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. -* Public key modules:: How to work with public key modules. -* Cryptographic Functions:: Functions for performing the cryptographic actions. -* General public-key related Functions:: General functions, not implementing any cryptography. - -* AC Interface:: Alternative interface to public key functions. -@end menu - -@node Available algorithms -@section Available algorithms - -Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well -as DSA (Digital Signature Algorithm) and Elgamal. The versatile -interface allows to add more algorithms in the future. - -@node Used S-expressions -@section Used S-expressions - -Libgcrypt's API for asymmetric cryptography is based on data structures -called S-expressions (see -@uref{http://people.csail.mit.edu/@/rivest/@/sexp.html}) and does not work -with contexts as most of the other building blocks of Libgcrypt do. - -@noindent -The following information are stored in S-expressions: - -@itemize @asis -@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 - -@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 = dP}. -@item d-mpi -The private key @math{d} -@end table - -All point values are encoded in standard format; Libgcrypt does -currently only support uncompressed points, thus the first byte needs to -be @code{0x04}. - -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 - -The @code{curve} parameter may be given in any case and is used to replace -missing parameters. - -@noindent -Currently implemented curves are: -@table @code -@item NIST P-192 -@itemx 1.2.840.10045.3.1.1 -@itemx prime192v1 -@itemx secp192r1 -The NIST 192 bit curve, its OID, X9.62 and SECP aliases. - -@item NIST P-224 -@itemx secp224r1 -The NIST 224 bit curve and its SECP alias. - -@item NIST P-256 -@itemx 1.2.840.10045.3.1.7 -@itemx prime256v1 -@itemx secp256r1 -The NIST 256 bit curve, its OID, X9.62 and SECP aliases. - -@item NIST P-384 -@itemx secp384r1 -The NIST 384 bit curve and its SECP alias. - -@item NIST P-521 -@itemx secp521r1 -The NIST 521 bit curve and its SECP alias. - -@end table -As usual the OIDs may optionally be prefixed with the string @code{OID.} -or @code{oid.}. - - - -@node Public key modules -@section Public key modules - -Libgcrypt makes it possible to load additional `public key -modules'; these public key algorithms can be used just like the -algorithms that are built into the library directly. For an -introduction into extension modules, see @xref{Modules}. - -@deftp {Data type} gcry_pk_spec_t -This is the `module specification structure' needed for registering -public key modules, which has to be filled in by the user before it -can be used to register a module. It contains the following members: - -@table @code -@item const char *name -The primary name of this algorithm. -@item char **aliases -A list of strings that are `aliases' for the algorithm. The list -must be terminated with a NULL element. -@item const char *elements_pkey -String containing the one-letter names of the MPI values contained in -a public key. -@item const char *element_skey -String containing the one-letter names of the MPI values contained in -a secret key. -@item const char *elements_enc -String containing the one-letter names of the MPI values that are the -result of an encryption operation using this algorithm. -@item const char *elements_sig -String containing the one-letter names of the MPI values that are the -result of a sign operation using this algorithm. -@item const char *elements_grip -String containing the one-letter names of the MPI values that are to -be included in the `key grip'. -@item int use -The bitwise-OR of the following flags, depending on the abilities of -the algorithm: -@table @code -@item GCRY_PK_USAGE_SIGN -The algorithm supports signing and verifying of data. -@item GCRY_PK_USAGE_ENCR -The algorithm supports the encryption and decryption of data. -@end table -@item gcry_pk_generate_t generate -The function responsible for generating a new key pair. See below for -a description of this type. -@item gcry_pk_check_secret_key_t check_secret_key -The function responsible for checking the sanity of a provided secret -key. See below for a description of this type. -@item gcry_pk_encrypt_t encrypt -The function responsible for encrypting data. See below for a -description of this type. -@item gcry_pk_decrypt_t decrypt -The function responsible for decrypting data. See below for a -description of this type. -@item gcry_pk_sign_t sign -The function responsible for signing data. See below for a description -of this type. -@item gcry_pk_verify_t verify -The function responsible for verifying that the provided signature -matches the provided data. See below for a description of this type. -@item gcry_pk_get_nbits_t get_nbits -The function responsible for returning the number of bits of a provided -key. See below for a description of this type. -@end table -@end deftp - -@deftp {Data type} gcry_pk_generate_t -Type for the `generate' function, defined as: gcry_err_code_t -(*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long -use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors) -@end deftp - -@deftp {Data type} gcry_pk_check_secret_key_t -Type for the `check_secret_key' function, defined as: gcry_err_code_t -(*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey) -@end deftp - -@deftp {Data type} gcry_pk_encrypt_t -Type for the `encrypt' function, defined as: gcry_err_code_t -(*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data, -gcry_mpi_t *pkey, int flags) -@end deftp - -@deftp {Data type} gcry_pk_decrypt_t -Type for the `decrypt' function, defined as: gcry_err_code_t -(*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data, -gcry_mpi_t *skey, int flags) -@end deftp - -@deftp {Data type} gcry_pk_sign_t -Type for the `sign' function, defined as: gcry_err_code_t -(*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data, -gcry_mpi_t *skey) -@end deftp - -@deftp {Data type} gcry_pk_verify_t -Type for the `verify' function, defined as: gcry_err_code_t -(*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data, -gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev) -@end deftp - -@deftp {Data type} gcry_pk_get_nbits_t -Type for the `get_nbits' function, defined as: unsigned -(*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey) -@end deftp - -@deftypefun gcry_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module}) - -Register a new public key module whose specification can be found in -@var{pubkey}. On success, a new algorithm ID is stored in -@var{algorithm_id} and a pointer representing this module is stored -in @var{module}. -@end deftypefun - -@deftypefun void gcry_pk_unregister (gcry_module_t @var{module}) -Unregister the public key module identified by @var{module}, which -must have been registered with gcry_pk_register. -@end deftypefun - -@deftypefun gcry_error_t gcry_pk_list (int *@var{list}, int *@var{list_length}) -Get a list consisting of the IDs of the loaded pubkey modules. If -@var{list} is zero, write the number of loaded pubkey modules to -@var{list_length} and return. If @var{list} is non-zero, the first -*@var{list_length} algorithm IDs are stored in @var{list}, which must -be of according size. In case there are less pubkey modules than -*@var{list_length}, *@var{list_length} is updated to the correct -number. -@end deftypefun - -@node Cryptographic Functions -@section Cryptographic Functions - -@noindent -Note that we will in future allow to use keys without p,q and u -specified and may also support other parameters for performance -reasons. - -@noindent - -Some functions operating on S-expressions support `flags', that -influence the operation. These flags have to be listed in a -sub-S-expression named `flags'; the following flags are known: - -@table @code -@item pkcs1 -Use PKCS#1 block type 2 padding. -@item 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. -@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 -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 -Note that this function currently does not know of any padding -methods and the caller must do any un-padding on his own. - -@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 -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". -@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{GCRYERR_BAD_SIGNATURE} -to indicate that the signature does not match the provided data. - -@end deftypefun -@c end gcry_pk_verify - -@node General public-key related Functions -@section General public-key related Functions - -@noindent -A couple of utility functions are available to retrieve the length of -the key, map algorithm identifiers and perform sanity checks: - -@deftypefun {const char *} gcry_pk_algo_name (int @var{algo}) - -Map the public key algorithm id @var{algo} to a string representation of -the algorithm name. For unknown algorithms this functions returns the -string @code{"?"}. This function should not be used to test for the -availability of an algorithm. -@end deftypefun - -@deftypefun int gcry_pk_map_name (const char *@var{name}) - -Map the algorithm @var{name} to a public key algorithm Id. Returns 0 if -the algorithm name is not known. -@end deftypefun - -@deftypefun int gcry_pk_test_algo (int @var{algo}) - -Return 0 if the public key algorithm @var{algo} is available for use. -Note that this is implemented as a macro. -@end deftypefun - - -@deftypefun {unsigned int} gcry_pk_get_nbits (gcry_sexp_t @var{key}) - -Return what is commonly referred as the key length for the given -public or private in @var{key}. -@end deftypefun - -@deftypefun {unsigned char *} gcry_pk_get_keygrip (@w{gcry_sexp_t @var{key}}, @w{unsigned char *@var{array}}) - -Return the so called "keygrip" which is the SHA-1 hash of the public key -parameters expressed in a way depended on the algorithm. @var{array} -must either provide space for 20 bytes or be @code{NULL}. In the latter -case a newly allocated array of that size is returned. On success a -pointer to the newly allocated space or to @var{array} is returned. -@code{NULL} is returned to indicate an error which is most likely an -unknown algorithm or one where a "keygrip" has not yet been defined. -The function accepts public or secret keys in @var{key}. -@end deftypefun - -@deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key}) - -Return zero if the private key @var{key} is `sane', an error code otherwise. -Note that it is not possible to check the `saneness' of a public key. - -@end deftypefun - - -@deftypefun gcry_error_t gcry_pk_algo_info (@w{int @var{algo}}, @w{int @var{what}}, @w{void *@var{buffer}}, @w{size_t *@var{nbytes}}) - -Depending on the value of @var{what} return various information about -the public key algorithm with the id @var{algo}. Note that the -function returns @code{-1} on error and the actual error code must be -retrieved using the function @code{gcry_errno}. The currently defined -values for @var{what} are: - -@table @code -@item GCRYCTL_TEST_ALGO: -Return 0 if the specified algorithm is available for use. -@var{buffer} must be @code{NULL}, @var{nbytes} may be passed as -@code{NULL} or point to a variable with the required usage of the -algorithm. This may be 0 for "don't care" or the bit-wise OR of these -flags: - -@table @code -@item GCRY_PK_USAGE_SIGN -Algorithm is usable for signing. -@item GCRY_PK_USAGE_ENCR -Algorithm is usable for encryption. -@end table - -Unless you need to test for the allowed usage, it is in general better -to use the macro gcry_pk_test_algo instead. - -@item GCRYCTL_GET_ALGO_USAGE: -Return the usage flags for the given algorithm. An invalid algorithm -return 0. Disabled algorithms are ignored here because we -want to know whether the algorithm is at all capable of a certain usage. - -@item GCRYCTL_GET_ALGO_NPKEY -Return the number of elements the public key for algorithm @var{algo} -consist of. Return 0 for an unknown algorithm. - -@item GCRYCTL_GET_ALGO_NSKEY -Return the number of elements the private key for algorithm @var{algo} -consist of. Note that this value is always larger than that of the -public key. Return 0 for an unknown algorithm. - -@item GCRYCTL_GET_ALGO_NSIGN -Return the number of elements a signature created with the algorithm -@var{algo} consists of. Return 0 for an unknown algorithm or for an -algorithm not capable of creating signatures. - -@item GCRYCTL_GET_ALGO_NENC -Return the number of elements a encrypted message created with the algorithm -@var{algo} consists of. Return 0 for an unknown algorithm or for an -algorithm not capable of encryption. -@end table - -@noindent -Please note that parameters not required should be passed as @code{NULL}. -@end deftypefun -@c end gcry_pk_algo_info - - -@deftypefun gcry_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}}) - -This is a general purpose function to perform certain control -operations. @var{cmd} controls what is to be done. The return value is -0 for success or an error code. Currently supported values for -@var{cmd} are: - -@table @code -@item GCRYCTL_DISABLE_ALGO -Disable the algorithm given as an algorithm id in @var{buffer}. -@var{buffer} must point to an @code{int} variable with the algorithm id -and @var{buflen} must have the value @code{sizeof (int)}. - -@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. - -@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 -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: - -@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. - -@item qbits -This is only meanigful for DSA keys. If it is given the DSA key is -generated with a Q parameyer of this size. 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 transient-key -This is only meaningful for RSA and DSA keys. This is a flag with no -value. If given the RSA or DSA key is created using a faster and a -somewhat less secure random number generator. This flag may be used -for keys which are only used for a short time and do not require full -cryptographic strength. - -@item domain -This is only meaningful for DLP algorithms. If specified keys are -generated with domain parameters taken from this list. The exact -format of this parameter depends on the actual algorithm. It is -currently only implemented for DSA using this format: - -@example -(genkey - (dsa - (domain - (p @var{p-mpi}) - (q @var{q-mpi}) - (g @var{q-mpi})))) -@end example - -@code{nbits} and @code{qbits} may not be specified because they are -derived from the domain parameters. - -@item derive-parms -This is currently only implemented for RSA and DSA keys. It is not -allowed to use this together with a @code{domain} specification. If -given, it is used to derive the keys using the given parameters. - -If given for an RSA key the X9.31 key generation algorithm is used -even if libgcrypt is not in FIPS mode. If given for a DSA key, the -FIPS 186 algorithm is used even if libgcrypt is not in FIPS mode. - -@example -(genkey - (rsa - (nbits 4:1024) - (rsa-use-e 1:3) - (derive-parms - (Xp1 #1A1916DDB29B4EB7EB6732E128#) - (Xp2 #192E8AAC41C576C822D93EA433#) - (Xp #D8CD81F035EC57EFE822955149D3BFF70C53520D - 769D6D76646C7A792E16EBD89FE6FC5B605A6493 - 39DFC925A86A4C6D150B71B9EEA02D68885F5009 - B98BD984#) - (Xq1 #1A5CF72EE770DE50CB09ACCEA9#) - (Xq2 #134E4CAA16D2350A21D775C404#) - (Xq #CC1092495D867E64065DEE3E7955F2EBC7D47A2D - 7C9953388F97DDDC3E1CA19C35CA659EDC2FC325 - 6D29C2627479C086A699A49C4C9CEE7EF7BD1B34 - 321DE34A#)))) -@end example - -@example -(genkey - (dsa - (nbits 4:1024) - (derive-parms - (seed @var{seed-mpi})))) -@end example - - -@item use-x931 -@cindex X9.31 -Force the use of the ANSI X9.31 key generation algorithm instead of -the default algorithm. This flag is only meaningful for RSA and -usually not required. Note that this algorithm is implicitly used if -either @code{derive-parms} is given or Libgcrypt is in FIPS mode. - -@item use-fips186 -@cindex FIPS 186 -Force the use of the FIPS 186 key generation algorithm instead of the -default algorithm. This flag is only meaningful for DSA and usually -not required. Note that this algorithm is implicitly used if either -@code{derive-parms} is given or Libgcrypt is in FIPS mode. As of now -FIPS 186-2 is implemented; after the approval of FIPS 186-3 the code -will be changed to implement 186-3. - - -@item use-fips186-2 -Force the use of the FIPS 186-2 key generation algorithm instead of -the default algorithm. This algorithm is slighlty different from -FIPS 186-3 and allows only 1024 bit keys. This flag is only meaningful -for DSA and only required for FIPS testing backward compatibility. - - -@end table -@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 -As an example, here is what the Elgamal key generation returns: - -@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 - -@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 - -@node AC Interface -@section Alternative Public Key Interface - -This section documents the alternative interface to asymmetric -cryptography (ac) that is not based on S-expressions, but on native C -data structures. As opposed to the pk interface described in the -former chapter, this one follows an open/use/close paradigm like other -building blocks of the library. - -@strong{This interface has a few known problems; most noteworthy an -inherent tendency to leak memory. It might not be available in -forthcoming versions of Libgcrypt.} - - -@menu -* Available asymmetric algorithms:: List of algorithms supported by the library. -* Working with sets of data:: How to work with sets of data. -* Working with IO objects:: How to work with IO objects. -* Working with handles:: How to use handles. -* Working with keys:: How to work with keys. -* Using cryptographic functions:: How to perform cryptographic operations. -* Handle-independent functions:: General functions independent of handles. -@end menu - -@node Available asymmetric algorithms -@subsection Available asymmetric algorithms - -Libgcrypt supports the RSA (Rivest-Shamir-Adleman) -algorithms as well as DSA (Digital Signature Algorithm) and Elgamal. -The versatile interface allows to add more algorithms in the future. - -@deftp {Data type} gcry_ac_id_t - -The following constants are defined for this type: - -@table @code -@item GCRY_AC_RSA -Rivest-Shamir-Adleman -@item GCRY_AC_DSA -Digital Signature Algorithm -@item GCRY_AC_ELG -Elgamal -@item GCRY_AC_ELG_E -Elgamal, encryption only. -@end table -@end deftp - -@node Working with sets of data -@subsection Working with sets of data - -In the context of this interface the term `data set' refers to a list -of `named MPI values' that is used by functions performing -cryptographic operations; a named MPI value is a an MPI value, -associated with a label. - -Such data sets are used for representing keys, since keys simply -consist of a variable amount of numbers. Furthermore some functions -return data sets to the caller that are to be provided to other -functions. - -This section documents the data types, symbols and functions that are -relevant for working with data sets. - -@deftp {Data type} gcry_ac_data_t -A single data set. -@end deftp - -The following flags are supported: - -@table @code -@item GCRY_AC_FLAG_DEALLOC -Used for storing data in a data set. If given, the data will be -released by the library. Note that whenever one of the ac functions -is about to release objects because of this flag, the objects are -expected to be stored in memory allocated through the Libgcrypt memory -management. In other words: gcry_free() is used instead of free(). - -@item GCRY_AC_FLAG_COPY -Used for storing/retrieving data in/from a data set. If given, the -library will create copies of the provided/contained data, which will -then be given to the user/associated with the data set. -@end table - -@deftypefun gcry_error_t gcry_ac_data_new (gcry_ac_data_t *@var{data}) -Creates a new, empty data set and stores it in @var{data}. -@end deftypefun - -@deftypefun void gcry_ac_data_destroy (gcry_ac_data_t @var{data}) -Destroys the data set @var{data}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_set (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t @var{mpi}) -Add the value @var{mpi} to @var{data} with the label @var{name}. If -@var{flags} contains GCRY_AC_FLAG_COPY, the data set will contain -copies of @var{name} and @var{mpi}. If @var{flags} contains -GCRY_AC_FLAG_DEALLOC or GCRY_AC_FLAG_COPY, the values -contained in the data set will be deallocated when they are to be -removed from the data set. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data}) -Create a copy of the data set @var{data} and store it in -@var{data_cp}. FIXME: exact semantics undefined. -@end deftypefun - -@deftypefun {unsigned int} gcry_ac_data_length (gcry_ac_data_t @var{data}) -Returns the number of named MPI values inside of the data set -@var{data}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t @var{data}, unsigned int @var{flags}, char *@var{name}, gcry_mpi_t *@var{mpi}) -Store the value labelled with @var{name} found in @var{data} in -@var{mpi}. If @var{flags} contains GCRY_AC_FLAG_COPY, store a copy of -the @var{mpi} value contained in the data set. @var{mpi} may be NULL -(this might be useful for checking the existence of an MPI with -extracting it). -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t @var{data}, unsigned int flags, unsigned int @var{index}, const char **@var{name}, gcry_mpi_t *@var{mpi}) -Stores in @var{name} and @var{mpi} the named @var{mpi} value contained -in the data set @var{data} with the index @var{idx}. If @var{flags} -contains GCRY_AC_FLAG_COPY, store copies of the values contained in -the data set. @var{name} or @var{mpi} may be NULL. -@end deftypefun - -@deftypefun void gcry_ac_data_clear (gcry_ac_data_t @var{data}) -Destroys any values contained in the data set @var{data}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_to_sexp (gcry_ac_data_t @var{data}, gcry_sexp_t *@var{sexp}, const char **@var{identifiers}) -This function converts the data set @var{data} into a newly created -S-Expression, which is to be stored in @var{sexp}; @var{identifiers} -is a NULL terminated list of C strings, which specifies the structure -of the S-Expression. - -Example: - -If @var{identifiers} is a list of pointers to the strings ``foo'' and -``bar'' and if @var{data} is a data set containing the values ``val1 = -0x01'' and ``val2 = 0x02'', then the resulting S-Expression will look -like this: (foo (bar ((val1 0x01) (val2 0x02))). -@end deftypefun - -@deftypefun gcry_error gcry_ac_data_from_sexp (gcry_ac_data_t *@var{data}, gcry_sexp_t @var{sexp}, const char **@var{identifiers}) -This function converts the S-Expression @var{sexp} into a newly -created data set, which is to be stored in @var{data}; -@var{identifiers} is a NULL terminated list of C strings, which -specifies the structure of the S-Expression. If the list of -identifiers does not match the structure of the S-Expression, the -function fails. -@end deftypefun - -@node Working with IO objects -@subsection Working with IO objects - -Note: IO objects are currently only used in the context of message -encoding/decoding and encryption/signature schemes. - -@deftp {Data type} {gcry_ac_io_t} -@code{gcry_ac_io_t} is the type to be used for IO objects. -@end deftp - -IO objects provide an uniform IO layer on top of different underlying -IO mechanisms; either they can be used for providing data to the -library (mode is GCRY_AC_IO_READABLE) or they can be used for -retrieving data from the library (mode is GCRY_AC_IO_WRITABLE). - -IO object need to be initialized by calling on of the following -functions: - -@deftypefun void gcry_ac_io_init (gcry_ac_io_t *@var{ac_io}, gcry_ac_io_mode_t @var{mode}, gcry_ac_io_type_t @var{type}, ...); -Initialize @var{ac_io} according to @var{mode}, @var{type} and the -variable list of arguments. The list of variable arguments to specify -depends on the given @var{type}. -@end deftypefun - -@deftypefun void gcry_ac_io_init_va (gcry_ac_io_t *@var{ac_io}, gcry_ac_io_mode_t @var{mode}, gcry_ac_io_type_t @var{type}, va_list @var{ap}); -Initialize @var{ac_io} according to @var{mode}, @var{type} and the -variable list of arguments @var{ap}. The list of variable arguments -to specify depends on the given @var{type}. -@end deftypefun - -The following types of IO objects exist: - -@table @code -@item GCRY_AC_IO_STRING -In case of GCRY_AC_IO_READABLE the IO object will provide data from a -memory string. Arguments to specify at initialization time: -@table @code -@item unsigned char * -Pointer to the beginning of the memory string -@item size_t -Size of the memory string -@end table -In case of GCRY_AC_IO_WRITABLE the object will store retrieved data in -a newly allocated memory string. Arguments to specify at -initialization time: -@table @code -@item unsigned char ** -Pointer to address, at which the pointer to the newly created memory -string is to be stored -@item size_t * -Pointer to address, at which the size of the newly created memory -string is to be stored -@end table - -@item GCRY_AC_IO_CALLBACK -In case of GCRY_AC_IO_READABLE the object will forward read requests -to a provided callback function. Arguments to specify at -initialization time: -@table @code -@item gcry_ac_data_read_cb_t -Callback function to use -@item void * -Opaque argument to provide to the callback function -@end table -In case of GCRY_AC_IO_WRITABLE the object will forward write requests -to a provided callback function. Arguments to specify at -initialization time: -@table @code -@item gcry_ac_data_write_cb_t -Callback function to use -@item void * -Opaque argument to provide to the callback function -@end table -@end table - -@node Working with handles -@subsection Working with handles - -In order to use an algorithm, an according handle must be created. -This is done using the following function: - -@deftypefun gcry_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle}, int @var{algorithm}, int @var{flags}) - -Creates a new handle for the algorithm @var{algorithm} and stores it -in @var{handle}. @var{flags} is not used currently. - -@var{algorithm} must be a valid algorithm ID, see @xref{Available -asymmetric algorithms}, for a list of supported algorithms and the -according constants. Besides using the listed constants directly, the -functions @code{gcry_pk_name_to_id} may be used to convert the textual -name of an algorithm into the according numeric ID. -@end deftypefun - -@deftypefun void gcry_ac_close (gcry_ac_handle_t @var{handle}) -Destroys the handle @var{handle}. -@end deftypefun - -@node Working with keys -@subsection Working with keys - -@deftp {Data type} gcry_ac_key_type_t -Defined constants: - -@table @code -@item GCRY_AC_KEY_SECRET -Specifies a secret key. -@item GCRY_AC_KEY_PUBLIC -Specifies a public key. -@end table -@end deftp - -@deftp {Data type} gcry_ac_key_t -This type represents a single `key', either a secret one or a public -one. -@end deftp - -@deftp {Data type} gcry_ac_key_pair_t -This type represents a `key pair' containing a secret and a public key. -@end deftp - -Key data structures can be created in two different ways; a new key -pair can be generated, resulting in ready-to-use key. Alternatively a -key can be initialized from a given data set. - -@deftypefun gcry_error_t gcry_ac_key_init (gcry_ac_key_t *@var{key}, gcry_ac_handle_t @var{handle}, gcry_ac_key_type_t @var{type}, gcry_ac_data_t @var{data}) -Creates a new key of type @var{type}, consisting of the MPI values -contained in the data set @var{data} and stores it in @var{key}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t @var{handle}, unsigned int @var{nbits}, void *@var{key_spec}, gcry_ac_key_pair_t *@var{key_pair}, gcry_mpi_t **@var{misc_data}) - -Generates a new key pair via the handle @var{handle} of @var{NBITS} -bits and stores it in @var{key_pair}. - -In case non-standard settings are wanted, a pointer to a structure of -type @code{gcry_ac_key_spec_<algorithm>_t}, matching the selected -algorithm, can be given as @var{key_spec}. @var{misc_data} is not -used yet. Such a structure does only exist for RSA. A description -of the members of the supported structures follows. - -@table @code -@item gcry_ac_key_spec_rsa_t -@table @code -@item gcry_mpi_t e -Generate the key pair using a special @code{e}. The value of @code{e} -has the following meanings: -@table @code -@item = 0 -Let Libgcrypt decide what exponent should be used. -@item = 1 -Request the use of a ``secure'' exponent; this is required by some -specification to be 65537. -@item > 2 -Try starting at this value until a working exponent is found. Note -that the current implementation leaks some information about the -private key because the incrementation used is not randomized. Thus, -this function will be changed in the future to return a random -exponent of the given size. -@end table -@end table -@end table - -Example code: -@example -@{ - gcry_ac_key_pair_t key_pair; - gcry_ac_key_spec_rsa_t rsa_spec; - - rsa_spec.e = gcry_mpi_new (0); - gcry_mpi_set_ui (rsa_spec.e, 1); - - err = gcry_ac_open (&handle, GCRY_AC_RSA, 0); - assert (! err); - - err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec, - &key_pair, NULL); - assert (! err); -@} -@end example -@end deftypefun - - -@deftypefun gcry_ac_key_t gcry_ac_key_pair_extract (gcry_ac_key_pair_t @var{key_pair}, gcry_ac_key_type_t @var{which}) -Returns the key of type @var{which} out of the key pair -@var{key_pair}. -@end deftypefun - -@deftypefun void gcry_ac_key_destroy (gcry_ac_key_t @var{key}) -Destroys the key @var{key}. -@end deftypefun - -@deftypefun void gcry_ac_key_pair_destroy (gcry_ac_key_pair_t @var{key_pair}) -Destroys the key pair @var{key_pair}. -@end deftypefun - -@deftypefun gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t @var{key}) -Returns the data set contained in the key @var{key}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_key_test (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}) -Verifies that the private key @var{key} is sane via @var{handle}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_key_get_nbits (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned int *@var{nbits}) -Stores the number of bits of the key @var{key} in @var{nbits} via @var{handle}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_key_get_grip (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, unsigned char *@var{key_grip}) -Writes the 20 byte long key grip of the key @var{key} to -@var{key_grip} via @var{handle}. -@end deftypefun - -@node Using cryptographic functions -@subsection Using cryptographic functions - -The following flags might be relevant: - -@table @code -@item GCRY_AC_FLAG_NO_BLINDING -Disable any blinding, which might be supported by the chosen -algorithm; blinding is the default. -@end table - -There exist two kinds of cryptographic functions available through the -ac interface: primitives, and high-level functions. - -Primitives deal with MPIs (data sets) directly; what they provide is -direct access to the cryptographic operations provided by an algorithm -implementation. - -High-level functions deal with octet strings, according to a specified -``scheme''. Schemes make use of ``encoding methods'', which are -responsible for converting the provided octet strings into MPIs, which -are then forwared to the cryptographic primitives. Since schemes are -to be used for a special purpose in order to achieve a particular -security goal, there exist ``encryption schemes'' and ``signature -schemes''. Encoding methods can be used seperately or implicitly -through schemes. - -What follows is a description of the cryptographic primitives. - -@deftypefun gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data_plain}, gcry_ac_data_t *@var{data_encrypted}) -Encrypts the plain text MPI value @var{data_plain} with the key public -@var{key} under the control of the flags @var{flags} and stores the -resulting data set into @var{data_encrypted}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t *@var{data_plain}, gcry_ac_data_t @var{data_encrypted}) -Decrypts the encrypted data contained in the data set -@var{data_encrypted} with the secret key KEY under the control of the -flags @var{flags} and stores the resulting plain text MPI value in -@var{DATA_PLAIN}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t *@var{data_signature}) -Signs the data contained in @var{data} with the secret key @var{key} -and stores the resulting signature in the data set -@var{data_signature}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t @var{data_signature}) -Verifies that the signature contained in the data set -@var{data_signature} is indeed the result of signing the data -contained in @var{data} with the secret key belonging to the public -key @var{key}. -@end deftypefun - -What follows is a description of the high-level functions. - -The type ``gcry_ac_em_t'' is used for specifying encoding methods; the -following methods are supported: - -@table @code -@item GCRY_AC_EME_PKCS_V1_5 -PKCS-V1_5 Encoding Method for Encryption. Options must be provided -through a pointer to a correctly initialized object of type -gcry_ac_eme_pkcs_v1_5_t. - -@item GCRY_AC_EMSA_PKCS_V1_5 -PKCS-V1_5 Encoding Method for Signatures with Appendix. Options must -be provided through a pointer to a correctly initialized object of -type gcry_ac_emsa_pkcs_v1_5_t. -@end table - -Option structure types: - -@table @code -@item gcry_ac_eme_pkcs_v1_5_t -@table @code -@item gcry_ac_key_t key -@item gcry_ac_handle_t handle -@end table -@item gcry_ac_emsa_pkcs_v1_5_t -@table @code -@item gcry_md_algo_t md -@item size_t em_n -@end table -@end table - -Encoding methods can be used directly through the following functions: - -@deftypefun gcry_error_t gcry_ac_data_encode (gcry_ac_em_t @var{method}, unsigned int @var{flags}, void *@var{options}, unsigned char *@var{m}, size_t @var{m_n}, unsigned char **@var{em}, size_t *@var{em_n}) -Encodes the message contained in @var{m} of size @var{m_n} according -to @var{method}, @var{flags} and @var{options}. The newly created -encoded message is stored in @var{em} and @var{em_n}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_decode (gcry_ac_em_t @var{method}, unsigned int @var{flags}, void *@var{options}, unsigned char *@var{em}, size_t @var{em_n}, unsigned char **@var{m}, size_t *@var{m_n}) -Decodes the message contained in @var{em} of size @var{em_n} according -to @var{method}, @var{flags} and @var{options}. The newly created -decoded message is stored in @var{m} and @var{m_n}. -@end deftypefun - -The type ``gcry_ac_scheme_t'' is used for specifying schemes; the -following schemes are supported: - -@table @code -@item GCRY_AC_ES_PKCS_V1_5 -PKCS-V1_5 Encryption Scheme. No options can be provided. -@item GCRY_AC_SSA_PKCS_V1_5 -PKCS-V1_5 Signature Scheme (with Appendix). Options can be provided -through a pointer to a correctly initialized object of type -gcry_ac_ssa_pkcs_v1_5_t. -@end table - -Option structure types: - -@table @code -@item gcry_ac_ssa_pkcs_v1_5_t -@table @code -@item gcry_md_algo_t md -@end table -@end table - -The functions implementing schemes: - -@deftypefun gcry_error_t gcry_ac_data_encrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_cipher}) -Encrypts the plain text readable from @var{io_message} through -@var{handle} with the public key @var{key} according to @var{scheme}, -@var{flags} and @var{opts}. If @var{opts} is not NULL, it has to be a -pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t). -The encrypted message is written to @var{io_cipher}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_decrypt_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_cipher}, gcry_ac_io_t *@var{io_message}) -Decrypts the cipher text readable from @var{io_cipher} through -@var{handle} with the secret key @var{key} according to @var{scheme}, -@var{flags} and @var{opts}. If @var{opts} is not NULL, it has to be a -pointer to a structure specific to the chosen scheme (gcry_ac_es_*_t). -The decrypted message is written to @var{io_message}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_sign_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_signature}) -Signs the message readable from @var{io_message} through @var{handle} -with the secret key @var{key} according to @var{scheme}, @var{flags} -and @var{opts}. If @var{opts} is not NULL, it has to be a pointer to -a structure specific to the chosen scheme (gcry_ac_ssa_*_t). The -signature is written to @var{io_signature}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_data_verify_scheme (gcry_ac_handle_t @var{handle}, gcry_ac_scheme_t @var{scheme}, unsigned int @var{flags}, void *@var{opts}, gcry_ac_key_t @var{key}, gcry_ac_io_t *@var{io_message}, gcry_ac_io_t *@var{io_signature}) -Verifies through @var{handle} that the signature readable from -@var{io_signature} is indeed the result of signing the message -readable from @var{io_message} with the secret key belonging to the -public key @var{key} according to @var{scheme} and @var{opts}. If -@var{opts} is not NULL, it has to be an anonymous structure -(gcry_ac_ssa_*_t) specific to the chosen scheme. -@end deftypefun - -@node Handle-independent functions -@subsection Handle-independent functions - -These two functions are deprecated; do not use them for new code. - -@deftypefun gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t @var{algorithm}, const char **@var{name}) -Stores the textual representation of the algorithm whose id is given -in @var{algorithm} in @var{name}. Deprecated; use @code{gcry_pk_algo_name}. -@end deftypefun - -@deftypefun gcry_error_t gcry_ac_name_to_id (const char *@var{name}, gcry_ac_id_t *@var{algorithm}) -Stores the numeric ID of the algorithm whose textual representation is -contained in @var{name} in @var{algorithm}. Deprecated; use -@code{gcry_pk_map_name}. -@end deftypefun - -@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 MAC 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. -* Hash algorithm modules:: How to work with hash algorithm modules. -* Working with hash algorithms:: List of functions related to hashing. -@end menu - -@node Available hash algorithms -@section Available hash algorithms - -@c begin table of hash algorithms -@cindex SHA-1 -@cindex SHA-224, SHA-256, SHA-384, SHA-512 -@cindex RIPE-MD-160 -@cindex MD2, MD4, MD5 -@cindex TIGER -@cindex HAVAL -@cindex Whirlpool -@cindex CRC32 -@table @code -@item GCRY_MD_NONE -This is not a real algorithm but used by some functions as an error -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 algorithms ha severe weaknesses and should not be used. - -@item GCRY_MD_MD2 -This is an reserved identifier for MD-2; there is no implementation yet. -This algorithm has severe weaknesses and should not be used. - -@item GCRY_MD_TIGER -This is the TIGER/192 algorithm which yields a message digest of 24 bytes. - -@item GCRY_MD_HAVAL -This is an reserved value for the HAVAL algorithm with 5 passes and 160 -bit. It yields a message digest of 20 bytes. Note that there is no -implementation yet available. - -@item GCRY_MD_SHA224 -This is the SHA-224 algorithm which yields a message digest of 28 bytes. -See Change Notice 1 for FIPS 180-2 for the specification. - -@item GCRY_MD_SHA256 -This is the SHA-256 algorithm which yields a message digest of 32 bytes. -See FIPS 180-2 for the specification. - -@item GCRY_MD_SHA384 -This is the SHA-384 algorithm which yields a message digest of 48 bytes. -See FIPS 180-2 for the specification. - -@item GCRY_MD_SHA512 -This is the SHA-384 algorithm which yields a message digest of 64 bytes. -See FIPS 180-2 for the specification. - -@item GCRY_MD_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. - -@end table -@c end table of hash algorithms - -@node Hash algorithm modules -@section Hash algorithm modules - -Libgcrypt makes it possible to load additional `message -digest modules'; these digests can be used just like the message digest -algorithms that are built into the library directly. For an -introduction into extension modules, see @xref{Modules}. - -@deftp {Data type} gcry_md_spec_t -This is the `module specification structure' needed for registering -message digest modules, which has to be filled in by the user before -it can be used to register a module. It contains the following -members: - -@table @code -@item const char *name -The primary name of this algorithm. -@item unsigned char *asnoid -Array of bytes that form the ASN OID. -@item int asnlen -Length of bytes in `asnoid'. -@item gcry_md_oid_spec_t *oids -A list of OIDs that are to be associated with the algorithm. The -list's last element must have it's `oid' member set to NULL. See -below for an explanation of this type. See below for an explanation -of this type. -@item int mdlen -Length of the message digest algorithm. See below for an explanation -of this type. -@item gcry_md_init_t init -The function responsible for initializing a handle. See below for an -explanation of this type. -@item gcry_md_write_t write -The function responsible for writing data into a message digest -context. See below for an explanation of this type. -@item gcry_md_final_t final -The function responsible for `finalizing' a message digest context. -See below for an explanation of this type. -@item gcry_md_read_t read -The function responsible for reading out a message digest result. See -below for an explanation of this type. -@item size_t contextsize -The size of the algorithm-specific `context', that should be -allocated for each handle. -@end table -@end deftp - -@deftp {Data type} gcry_md_oid_spec_t -This type is used for associating a user-provided algorithm -implementation with certain OIDs. It contains the following members: - -@table @code -@item const char *oidstring -Textual representation of the OID. -@end table -@end deftp - -@deftp {Data type} gcry_md_init_t -Type for the `init' function, defined as: void (*gcry_md_init_t) (void -*c) -@end deftp - -@deftp {Data type} gcry_md_write_t -Type for the `write' function, defined as: void (*gcry_md_write_t) -(void *c, unsigned char *buf, size_t nbytes) -@end deftp - -@deftp {Data type} gcry_md_final_t -Type for the `final' function, defined as: void (*gcry_md_final_t) -(void *c) -@end deftp - -@deftp {Data type} gcry_md_read_t -Type for the `read' function, defined as: unsigned char -*(*gcry_md_read_t) (void *c) -@end deftp - -@deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module}) - -Register a new digest module whose specification can be found in -@var{digest}. On success, a new algorithm ID is stored in -@var{algorithm_id} and a pointer representing this module is stored -in @var{module}. -@end deftypefun - -@deftypefun void gcry_md_unregister (gcry_module_t @var{module}) -Unregister the digest identified by @var{module}, which must have been -registered with gcry_md_register. -@end deftypefun - -@deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length}) -Get a list consisting of the IDs of the loaded message digest modules. -If @var{list} is zero, write the number of loaded message digest -modules to @var{list_length} and return. If @var{list} is non-zero, -the first *@var{list_length} algorithm IDs are stored in @var{list}, -which must be of according size. In case there are less message -digests modules than *@var{list_length}, *@var{list_length} is updated -to the correct number. -@end deftypefun - -@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 @xref{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. Note that -the function @code{gcry_md_setkey} must be used to set the MAC key. -The size of the MAC is equal to the message digest of the underlying -hash algorithm. If you want CBC message authentication codes based on -a cipher, see @xref{Working with cipher handles}. - -@end table -@c begin table of hash flags - -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, set the MAC key to the value of -@var{key} of length @var{keylen} bytes. There is no restriction on -the length of the key. -@end deftypefun - - -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. -@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} does this implicitly. After this has been -done no further updates (by means of @code{gcry_md_write} or -@code{gcry_md_putc} are allowed. Only the first call to this function -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 reseted (using @code{gcry_md_close} or -@code{gcry_md_reset}. @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 - -Because it is often necessary to get the message digest of one block of -memory, a fast convenience function is available for this task: - -@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 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 create 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 - - -The following two deprecated macros are used for debugging by old code. -They shopuld be replaced by @code{gcry_md_debug}. - -@deftypefun void gcry_md_start_debug (gcry_md_hd_t @var{h}, const char *@var{suffix}) - -Enable debugging for the digest object with handle @var{h}. This -creates create files named @file{dbgmd-<n>.<string>} while doing the -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}. -@end deftypefun - - -@deftypefun void gcry_md_stop_debug (gcry_md_hd_t @var{h}, int @var{reserved}) - -Stop debugging on handle @var{h}. @var{reserved} should be specified as -0. This function is usually not required because @code{gcry_md_close} -does implicitly stop debugging. -@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. -@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 %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 called the "type" and should always exist and 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 {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. -@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. -* 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 - -@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}. -@end deftypefun - - -@deftypefun void gcry_mpi_release (@w{gcry_mpi_t @var{a}}) - -Release the MPI @var{a} and free all associated resources. Passing -@code{NULL} is allowed and ignored. When a MPI stored in the "secure -memory" is released, that memory gets wiped out immediately. -@end deftypefun - -@noindent -The simplest operations are used to assign a new value to an MPI: - -@deftypefun gcry_mpi_t gcry_mpi_set (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{u}}) - -Assign the value of @var{u} to @var{w} and return @var{w}. If -@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the -value of @var{u} and returned. -@end deftypefun - -@deftypefun gcry_mpi_t gcry_mpi_set_ui (@w{gcry_mpi_t @var{w}}, @w{unsigned long @var{u}}) - -Assign the value of @var{u} to @var{w} and return @var{w}. If -@code{NULL} is passed for @var{w}, a new MPI is allocated, set to the -value of @var{u} and returned. This function takes an @code{unsigned -int} as type for @var{u} and thus it is only possible to set @var{w} to -small values (usually up to the word size of the CPU). -@end deftypefun - -@deftypefun void gcry_mpi_swap (@w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}}) - -Swap the values of @var{a} and @var{b}. -@end deftypefun - -@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}. 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. - -@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. - -@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 C style string with each byte of the MPI encoded as 2 hex -digits. 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}. -@end deftypefun - -@deftypefun void gcry_mpi_dump (@w{const gcry_mpi_t @var{a}}) - -Dump the value of @var{a} in a format suitable for debugging to -Libgcrypt's logging stream. Note that one leading space but no trailing -space or linefeed will be printed. It is okay to pass @code{NULL} for -@var{a}. -@end deftypefun - - -@node Calculations -@section Calculations - -@noindent -Basic arithmetic operations: - -@deftypefun void gcry_mpi_add (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}) - -@math{@var{w} = @var{u} + @var{v}}. -@end deftypefun - - -@deftypefun void gcry_mpi_add_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}}) - -@math{@var{w} = @var{u} + @var{v}}. Note that @var{v} is an unsigned integer. -@end deftypefun - - -@deftypefun void gcry_mpi_addm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}}) - -@math{@var{w} = @var{u} + @var{v} \bmod @var{m}}. -@end deftypefun - -@deftypefun void gcry_mpi_sub (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}) - -@math{@var{w} = @var{u} - @var{v}}. -@end deftypefun - -@deftypefun void gcry_mpi_sub_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}}) - -@math{@var{w} = @var{u} - @var{v}}. @var{v} is an unsigned integer. -@end deftypefun - -@deftypefun void gcry_mpi_subm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}}) - -@math{@var{w} = @var{u} - @var{v} \bmod @var{m}}. -@end deftypefun - -@deftypefun void gcry_mpi_mul (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}) - -@math{@var{w} = @var{u} * @var{v}}. -@end deftypefun - -@deftypefun void gcry_mpi_mul_ui (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{v}}) - -@math{@var{w} = @var{u} * @var{v}}. @var{v} is an unsigned integer. -@end deftypefun - -@deftypefun void gcry_mpi_mulm (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{gcry_mpi_t @var{v}}, @w{gcry_mpi_t @var{m}}) - -@math{@var{w} = @var{u} * @var{v} \bmod @var{m}}. -@end deftypefun - -@deftypefun void gcry_mpi_mul_2exp (@w{gcry_mpi_t @var{w}}, @w{gcry_mpi_t @var{u}}, @w{unsigned long @var{e}}) - -@c FIXME: I am in need for a real TeX{info} guru: -@c I don't know why TeX can grok @var{e} here. -@math{@var{w} = @var{u} * 2^e}. -@end deftypefun - -@deftypefun void gcry_mpi_div (@w{gcry_mpi_t @var{q}}, @w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}}, @w{int @var{round}}) - -@math{@var{q} = @var{dividend} / @var{divisor}}, @math{@var{r} = -@var{dividend} \bmod @var{divisor}}. @var{q} and @var{r} may be passed -as @code{NULL}. @var{round} should be negative or 0. -@end deftypefun - -@deftypefun void gcry_mpi_mod (@w{gcry_mpi_t @var{r}}, @w{gcry_mpi_t @var{dividend}}, @w{gcry_mpi_t @var{divisor}}) - -@math{@var{r} = @var{dividend} \bmod @var{divisor}}. -@end deftypefun - -@deftypefun void gcry_mpi_powm (@w{gcry_mpi_t @var{w}}, @w{const gcry_mpi_t @var{b}}, @w{const gcry_mpi_t @var{e}}, @w{const gcry_mpi_t @var{m}}) - -@c I don't know why TeX can grok @var{e} here. -@math{@var{w} = @var{b}^e \bmod @var{m}}. -@end deftypefun - -@deftypefun int gcry_mpi_gcd (@w{gcry_mpi_t @var{g}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}}) - -Set @var{g} to the greatest common divisor of @var{a} and @var{b}. -Return true if the @var{g} is 1. -@end deftypefun - -@deftypefun int gcry_mpi_invm (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{m}}) - -Set @var{x} to the multiplicative inverse of @math{@var{a} \bmod @var{m}}. -Return true if the inverse exists. -@end deftypefun - - -@node Comparisons -@section Comparisons - -@noindent -The next 2 functions are used to compare MPIs: - - -@deftypefun int gcry_mpi_cmp (@w{const gcry_mpi_t @var{u}}, @w{const gcry_mpi_t @var{v}}) - -Compare the multi-precision-integers number @var{u} and @var{v} -returning 0 for equality, a positive value for @var{u} > @var{v} and a -negative for @var{u} < @var{v}. -@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 - - -@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 Miscellaneous -@section Miscellaneous - -@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}). - -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 {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 - -@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}. Currently only the flag -@code{GCRYMPI_FLAG_SECURE} is allowed to convert @var{a} into an MPI -stored in "secure memory". -@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}. Note that -this function is currently useless as no flags are allowed. -@end deftypefun - -@deftypefun int gcry_mpi_get_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}}) - -Return true when the @var{flag} is set for @var{a}. -@end deftypefun - -@deftypefun void gcry_mpi_randomize (@w{gcry_mpi_t @var{w}}, @w{unsigned int @var{nbits}}, @w{enum gcry_random_level @var{level}}) - -Set the multi-precision-integers @var{w} to a random value of -@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 wether 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. -@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 - -@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 - -Libgcrypt implements two interfaces for public key cryptography: The -standard interface is PK interface using functions in the -@code{gcry_pk_} name space. The AC interface in an alternative one -which is now deprecated and will not be further described. The AC -interface is also disabled in FIPS mode. - -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 @xref{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 - -With the help of the module registration system 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. The interface to the modules is published -(@file{gcrypt-modules.h}) so that it can used to register external -implementations of algorithms with Libgcrypt. However, for some -algorithms this module interface is to limited and thus for the -internal modules an extra interface is sometimes used to convey more -information. - -By default Libgcrypt uses a blinding technique for RSA decryption to -mitigate real world timing attacks over a network: Instead of using -the RSA decryption directly, a blinded value @math{y = x r^{e} \bmod n} -is decrypted and the unblinded value @math{x' = y' r^{-1} \bmod n} -returned. The blinding value @math{r} is a random value with the size -of the modulus @math{n} and generated with @code{GCRY_WEAK_RANDOM} -random level. - -@cindex X9.31 -@cindex FIPS 186 -The algorithm used for RSA and DSA key generation depends on whether -Libgcrypt is operated in standard or in FIPS mode. In standard mode -an algorithm based on the Lim-Lee prime number generator is used. In -FIPS mode RSA keys are generated as specified in ANSI X9.31 (1998) and -DSA keys as specified in FIPS 186-2. - - - -@node Symmetric Encryption Subsystem Architecture -@section Symmetric Encryption Subsystem Architecture - -The interface to work with symmetric encryption algorithms is made up -of functions from the @code{gcry_cipher_} name space. The -implementation follows the open-use-close paradigm and uses registered -algorithm modules for the actual work. Unless a module implements -optimized cipher mode implementations, the high level code -(@file{cipher/cipher.c}) implements the modes and calls the core -algorithm functions to process each block. - -The most important functions are: - -@table @code - -@item gcry_cipher_open -Create a new instance to encrypt or decrypt using a specified -algorithm and mode. - -@item gcry_cipher_close -Release an instance. - -@item gcry_cipher_setkey -Set a key to be used for encryption or decryption. - -@item gcry_cipher_setiv -Set an initialization vector to be used for encryption or decryption. - -@item gcry_cipher_encrypt -@itemx gcry_cipher_decrypt -Encrypt or decrypt data. These functions may be called with arbitrary -amounts of data and as often as needed to encrypt or decrypt all data. - -@end table - -There are also functions to query properties of algorithms or context, -like block length, key length, map names or to enable features like -padding methods. - - - -@node Hashing and MACing Subsystem Architecture -@section Hashing and MACing Subsystem Architecture - -The interface to work with message digests and CRC algorithms is made -up of functions from the @code{gcry_md_} name space. The -implementation follows the open-use-close paradigm and uses registered -algorithm modules for the actual work. Although CRC algorithms are -not considered cryptographic hash algorithms, they share enough -properties so that it makes sense to handle them in the same way. -It is possible to use several algorithms at once with one context and -thus compute them all on the same data. - -The most important functions are: - -@table @code -@item gcry_md_open -Create a new message digest instance and optionally enable one -algorithm. A flag may be used to turn the message digest algorithm -into a HMAC algorithm. - -@item gcry_md_enable -Enable an additional algorithm for the instance. - -@item gcry_md_setkey -Set the key for the MAC. - -@item gcry_md_write -Pass more data for computing the message digest to an instance. - -@item gcry_md_putc -Buffered version of @code{gcry_md_write} implemented as a macro. - -@item gcry_md_read -Finalize the computation of the message digest or HMAC and return the -result. - -@item gcry_md_close -Release an instance - -@item gcry_md_hash_buffer -Convenience function to directly compute a message digest over a -memory buffer without the need to create an instance first. - -@end table - -There are also functions to query properties of algorithms or the -instance, like enabled algorithms, digest length, map algorithm names. -it is also possible to reset an instance or to copy the current state -of an instance at any time. Debug functions to write the hashed data -to files are available as well. - - - -@node Multi-Precision-Integer Subsystem Architecture -@section Multi-Precision-Integer Subsystem Architecture - -The implementation of Libgcrypt's big integer computation code is -based on an old release of GNU Multi-Precision Library (GMP). The -decision not to use the GMP library directly was due to stalled -development at that time and due to security requirements which could -not be provided by the code in GMP. As GMP does, Libgcrypt provides -high performance assembler implementations of low level code for -several CPUS to gain much better performance than with a generic C -implementation. - -@noindent -Major features of Libgcrypt's multi-precision-integer code compared to -GMP are: - -@itemize -@item -Avoidance of stack based allocations to allow protection against -swapping out of sensitive data and for easy zeroing of sensitive -intermediate results. - -@item -Optional use of secure memory and tracking of its use so that results -are also put into secure memory. - -@item -MPIs are identified by a handle (implemented as a pointer) to give -better control over allocations and to augment them with extra -properties like opaque data. - -@item -Removal of unnecessary code to reduce complexity. - -@item -Functions specialized for public key cryptography. - -@end itemize - - - -@node Prime-Number-Generator Subsystem Architecture -@section Prime-Number-Generator Subsystem Architecture - -Libgcrypt provides an interface to its prime number generator. These -functions make use of the internal prime number generator which is -required for the generation for public key key pairs. The plain prime -checking function is exported as well. - -The generation of random prime numbers is based on the Lim and Lee -algorithm to create practically save primes.@footnote{Chae Hoon Lim -and Pil Joong Lee. A key recovery attack on discrete log-based shemes -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. - -@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 only supported hardware RNG is -the Padlock engine of VIA (Centaur) CPUs. It is not available in FIPS -mode. - -@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 RIPE-MD160 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 implementaion 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/radnom} 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 stucked 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 fature 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 orginal random value. The encrtypted result is then -decrypted and checked that it macthes the original random value. -(@code{cipher/@/rsa.c:@/selftest_encr_1024}) -@end enumerate - -@item DSA -A pre-defined 1024 bit DSA key is used and these tests are run in turn: -@enumerate -@item -Conversion of S-expression to internal format. -(@code{cipher/@/dsa.c:@/selftests_dsa}) -@item -Private key consistency check. -(@code{cipher/@/dsa.c:@/selftests_dsa}) -@item -A pre-defined 20 byte value is signed with PKCS#1 padding for -SHA-1. The result is verified using the public key against the -original data and against modified data. -(@code{cipher/@/dsa.c:@/selftest_sign_1024}) -@end enumerate -@end table - -@subsection Integrity Power-Up Tests - -The integrity of the Libgcrypt is tested during power-up but only if -checking has been enabled at build time. The check works by computing -a HMAC SHA-256 checksum over the file used to load Libgcrypt into -memory. That checksum is compared against a checksum stored in a file -of the same name but with a single dot as a prefix and a suffix of -@file{.hmac}. - - -@subsection Critical Functions Power-Up Tests - -The 3DES weak key detection is tested during power-up by calling the -detection function with keys taken from a table listening all weak -keys. The table itself is protected using a SHA-1 hash. -(@code{cipher/@/des.c:@/selftest}) - - - -@c -------------------------------- -@section Conditional Tests - -The conditional tests are performed if a certain contidion is met. -This may occur at any time; the library does not necessary enter the -``Self-Test'' state to run these tests but will transit to the -``Error'' state if a test failed. - -@subsection Key-Pair Generation Tests - -After an asymmetric key-pair has been generated, Libgcrypt runs a -pair-wise consistency tests on the generated key. On failure the -generated key is not used, an error code is returned and, if in FIPS -mode, the library is put into the ``Error'' state. - -@table @asis -@item RSA -The test uses a random number 64 bits less the size of the modulus as -plaintext and runs an encryption and decryption operation in turn. The -encrypted value is checked to not match the plaintext and the result -of the decryption is checked to match the plaintext. - -A new random number of the same size is generated, signed and verified -to test the correctness of the signing operation. As a second signing -test, the signature is modified by incrementing its value and then -verified with the expected result that the verification fails. -(@code{cipher/@/rsa.c:@/test_keys}) -@item DSA -The test uses a random number of the size of the Q parameter to create -a signature and then checks that the signature verifies. As a second -signing test, the data is modified by incrementing its value and then -verified against the signature with the expected result that the -verification fails. (@code{cipher/@/dsa.c:@/test_keys}) -@end table - - -@subsection Software Load Tests - -Loading of extra modules into libgcrypt is disabled in FIPS mode and -thus no tests are -implemented. (@code{cipher/@/cipher.c:@/_gcry_cipher_register}, -@code{cipher/@/md.c:@/_gcry_md_register}, -@code{cipher/@/pubkey.c:@/_gcry_pk_register}) - - -@subsection Manual Key Entry Tests - -A manual key entry feature is not implemented in Libgcrypt. - - -@subsection Continuous RNG Tests - -The continuous random number test is only used in FIPS mode. The RNG -generates blocks of 128 bit size; the first block generated per -context is saved in the context and another block is generated to be -returned to the caller. Each block is compared against the saved -block and then stored in the context. If a duplicated block is -detected an error is signaled and the libray 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 -The Alternative Public Key Interface (@code{gcry_ac_xxx}) is not -supported and all API calls return an error. - -@item -Registration of external modules is not supported. - -@item -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 -introducted 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 runing 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 intialization function @code{gcry_check_version}. - -@item 3 -Init to Self-Test is either triggred by a dedicated API call or implicit -by invoking a libgrypt service conrolled by the FSM. - -@item 4 -Self-Test to Operational is triggered after all self-tests passed -successfully. - -@item 5 -Operational to Shutdown is an artifical 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 triggred 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 artifical state to document that Libgcrypt -has not ye been initializaed but the process is about to terminate. - -@item 12 -Power-On to Fatal-Error will be triggerd if certain Libgcrypt functions -are used without having reached the Init state. - -@item 13 -Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt while -running self-tests. - -@item 14 -Self-Test to Error is triggred 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 triggred 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 damon 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/plugins/MirOTR/libgcrypt-1.4.6/doc/gpgvs.aim.txt b/plugins/MirOTR/libgcrypt-1.4.6/doc/gpgvs.aim.txt deleted file mode 100644 index c7cbd9272d..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/gpgvs.aim.txt +++ /dev/null @@ -1,22 +0,0 @@ -~~~
-AIM
-~~~
-the aim of *.vs projects is to provide a well organized
-and not invasive way to build target open source projects
-using visual studio (vs.6 and vs.net)
-
-~~~~~~
-REASON
-~~~~~~
-In many situations I was obliged to use visual studio in
-writing projects, and writing windows software is best suited
-using this ide.
-When I had need to use these great open source projects in
-my applications, I had to use the binaries provided (if) for
-the win32 environment: but, I think, if it can run in win32,
-it could also be built using win32 compiler/linker.
-I know you have to pay for visual studio, but why don't give
-the opportunity to build using this tool too?
-Moreover I think that providing these projects could increment
-the number of coworker programmers.
-So I decided to provide these visual studio projects.
\ No newline at end of file diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/gpgvs.architecture.txt b/plugins/MirOTR/libgcrypt-1.4.6/doc/gpgvs.architecture.txt deleted file mode 100644 index 4a2c2511f9..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/gpgvs.architecture.txt +++ /dev/null @@ -1,108 +0,0 @@ -~~~~~~~~~~~~
-ARCHITECTURE
-~~~~~~~~~~~~
-I admit that architecture meaning is too much for this project,
-but with this document I explain how is built and
-how to use these projects.
-First of all you should respect the directory structure otherwise
-projects will not compile, but obviously you can change it:
-rembember to change vs workspace relativ paths too.
-Regarding workspaces compile flags: I decided to not provide particular
-building flags, so if you have to optimize (or anything else) you
-have to change settings.
-
-
-~~~~~~~~~~~
-DIRECTORIES
-~~~~~~~~~~~
-As said in “aim” document, I do not want to get inside original
-source code, less than it is not forced:
-so the first step is to look at directories structure (not whole)
-
-
-[anywhwere]\
- \libgcrypt-1.2.1\
- \libgcrypt-1.2.1\
- \[...]
- \gpg.vs\bin.vs\
- \inc.vs\
- \libgcrypt-1.2.1.vs\
- \libgpg-error-1.1.vs\custom\
- \libgpg_error_1_1.dsp
- \libgpg_error_1_1.dsw
-
-There is a "root" directory, use whatever you want:
-inside this directory extract the original package, like
-libgcrypt-1.2.1, libgcrypt-1.2.1 and so on.
-Inside the "root" download/extract gpg.vs (otr.vs) project:
-you should have at least the same directories structure just shown.
-Inside you have "[original.package.name].vs" and all tools to be
-able to build original packages with visual studio.
-
-
-~~~~~~
-bin.vs
-~~~~~~
-here we'll go binaries created by visual studio, as
-\bin.vs\libgpg-error-1.1\debug\static\...
-\bin.vs\libgpg-error-1.1\release\static\...
-\bin.vs\libgpg-error-1.1\release\dll\...
-
-
-~~~~~~
-inc.vs
-~~~~~~
-this folder contains include files needed to build original packages
-without changing their code, like empty "socket.h" headers;
-and you will find "hooked" includes (like stddef.h) useful to declare
-definition that visual studio misses (like pid_t)
-
-
-~~~~~~~~~~~~~~~~~
-package.vs.custom
-~~~~~~~~~~~~~~~~~
-here you'll always find package->"config.h" header, made "by hand".
-You will find some others files that under *nix are automatically
-created, and I provide them in a "custom" way
-
-
-~~~~~~~
-EXAMPLE
-~~~~~~~
-You want to compile with vs libgpg-error-1.1.: choose your parent directory,
-in my case “gnu”
-
-\gnu\
-
-download and extract here the libgpg-error-1.1, so now I have
-
-\gnu\libgpg-error-1.1\libgpg-error\[source code]
-
-basically extract always in libgpg-error directory and the
-closest parent is libgpg-error-version, to have
-
-\gnu\libgpg-error-1.0\libgpg-error\[source code]
-\gnu\libgpg-error-1.1\libgpg-error\[source code]
-
-Now download gpg.vs project (or take it from cvs), which includes
-vs project for libgpg-error, and extract it in the directory
-you have choosen (gnu in my case),
-
-\gnu\gpg.vs\
-
-In gpg.vs directory find the libgpg-error-1.1.vs
-(appending .vs at the end of package name is the “standard” for this project)
-
-\gnu\gpg.vs\ libgpg-error-1.1.vs\
-
-And inside find the dsw/dsp of the project
-
-libgpg_error_1_1.dsw
-libgpg_error_1_1.dsp
-
-Note: the little change to names is due to vs limitations.
-You have only to build it.
-The binaries files will be created in
-
-\gnu\gpg.vs\bin.vs\libgpg-error.1.1\debug
-\gnu\gpg.vs\bin.vs\libgpg-error.1.1\release
\ No newline at end of file diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/gpl.texi b/plugins/MirOTR/libgcrypt-1.4.6/doc/gpl.texi deleted file mode 100644 index d965561869..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/gpl.texi +++ /dev/null @@ -1,397 +0,0 @@ -@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. - -@iftex -@heading NO WARRANTY -@end iftex -@ifinfo -@center NO WARRANTY -@end ifinfo - -@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/plugins/MirOTR/libgcrypt-1.4.6/doc/lgpl.texi b/plugins/MirOTR/libgcrypt-1.4.6/doc/lgpl.texi deleted file mode 100644 index a3f83cb353..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/lgpl.texi +++ /dev/null @@ -1,565 +0,0 @@ -@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. - -@iftex -@heading NO WARRANTY -@end iftex -@ifinfo -@center NO WARRANTY -@end ifinfo - -@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/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.eps b/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.eps deleted file mode 100644 index a53fdeb673..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.eps +++ /dev/null @@ -1,349 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: libgcrypt-modules.fig -%%Creator: fig2dev Version 3.2 Patchlevel 4 -%%CreationDate: Thu Jul 9 13:24:33 2009 -%%For: wk@vigenere (Werner Koch,,,) -%%BoundingBox: 0 0 488 300 -%%Magnification: 1.0000 -%%EndComments -/$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 -/col1 {0.000 0.000 1.000 srgb} bind def -/col2 {0.000 1.000 0.000 srgb} bind def -/col3 {0.000 1.000 1.000 srgb} bind def -/col4 {1.000 0.000 0.000 srgb} bind def -/col5 {1.000 0.000 1.000 srgb} bind def -/col6 {1.000 1.000 0.000 srgb} bind def -/col7 {1.000 1.000 1.000 srgb} bind def -/col8 {0.000 0.000 0.560 srgb} bind def -/col9 {0.000 0.000 0.690 srgb} bind def -/col10 {0.000 0.000 0.820 srgb} bind def -/col11 {0.530 0.810 1.000 srgb} bind def -/col12 {0.000 0.560 0.000 srgb} bind def -/col13 {0.000 0.690 0.000 srgb} bind def -/col14 {0.000 0.820 0.000 srgb} bind def -/col15 {0.000 0.560 0.560 srgb} bind def -/col16 {0.000 0.690 0.690 srgb} bind def -/col17 {0.000 0.820 0.820 srgb} bind def -/col18 {0.560 0.000 0.000 srgb} bind def -/col19 {0.690 0.000 0.000 srgb} bind def -/col20 {0.820 0.000 0.000 srgb} bind def -/col21 {0.560 0.000 0.560 srgb} bind def -/col22 {0.690 0.000 0.690 srgb} bind def -/col23 {0.820 0.000 0.820 srgb} bind def -/col24 {0.500 0.190 0.000 srgb} bind def -/col25 {0.630 0.250 0.000 srgb} bind def -/col26 {0.750 0.380 0.000 srgb} bind def -/col27 {1.000 0.500 0.500 srgb} bind def -/col28 {1.000 0.630 0.630 srgb} bind def -/col29 {1.000 0.750 0.750 srgb} bind def -/col30 {1.000 0.880 0.880 srgb} bind def -/col31 {1.000 0.840 0.000 srgb} bind def -/col32 {0.555 0.555 0.555 srgb} bind def -/col33 {0.254 0.270 0.254 srgb} bind def -/col34 {0.750 0.750 0.750 srgb} bind def -/col35 {0.500 0.500 0.500 srgb} bind def -/col36 {0.387 0.387 0.387 srgb} bind def -/col37 {0.801 0.801 0.801 srgb} bind def -/col38 {0.422 0.422 0.422 srgb} bind def -/col39 {0.773 0.715 0.590 srgb} bind def -/col40 {0.934 0.969 0.996 srgb} bind def -/col41 {0.859 0.793 0.648 srgb} bind def -/col42 {0.250 0.250 0.250 srgb} bind def -/col43 {0.875 0.875 0.875 srgb} bind def -/col44 {0.555 0.559 0.555 srgb} bind def -/col45 {0.664 0.664 0.664 srgb} bind def -/col46 {0.332 0.332 0.332 srgb} bind def -/col47 {0.840 0.840 0.840 srgb} bind def -/col48 {0.680 0.680 0.680 srgb} bind def -/col49 {0.742 0.742 0.742 srgb} bind def -/col50 {0.316 0.316 0.316 srgb} bind def -/col51 {0.902 0.887 0.902 srgb} bind def -/col52 {0.000 0.000 0.285 srgb} bind def -/col53 {0.473 0.473 0.473 srgb} bind def -/col54 {0.188 0.203 0.188 srgb} bind def -/col55 {0.254 0.254 0.254 srgb} bind def -/col56 {0.777 0.711 0.586 srgb} bind def -/col57 {0.863 0.613 0.574 srgb} bind def -/col58 {0.941 0.922 0.875 srgb} bind def -/col59 {0.762 0.762 0.762 srgb} bind def -/col60 {0.883 0.781 0.656 srgb} bind def -/col61 {0.879 0.879 0.879 srgb} bind def -/col62 {0.820 0.820 0.820 srgb} bind def -/col63 {0.926 0.926 0.926 srgb} bind def -/col64 {0.852 0.477 0.102 srgb} bind def -/col65 {0.941 0.891 0.102 srgb} bind def -/col66 {0.531 0.488 0.758 srgb} bind def -/col67 {0.836 0.836 0.836 srgb} bind def -/col68 {0.547 0.547 0.645 srgb} bind def -/col69 {0.289 0.289 0.289 srgb} bind def -/col70 {0.547 0.418 0.418 srgb} bind def -/col71 {0.352 0.352 0.352 srgb} bind def -/col72 {0.715 0.605 0.449 srgb} bind def -/col73 {0.254 0.574 0.996 srgb} bind def -/col74 {0.746 0.438 0.230 srgb} bind def -/col75 {0.855 0.465 0.000 srgb} bind def -/col76 {0.852 0.719 0.000 srgb} bind def -/col77 {0.000 0.391 0.000 srgb} bind def -/col78 {0.352 0.418 0.230 srgb} bind def -/col79 {0.824 0.824 0.824 srgb} bind def -/col80 {0.555 0.555 0.641 srgb} bind def -/col81 {0.949 0.723 0.363 srgb} bind def -/col82 {0.535 0.598 0.418 srgb} bind def -/col83 {0.391 0.391 0.391 srgb} bind def -/col84 {0.715 0.898 0.996 srgb} bind def -/col85 {0.523 0.750 0.922 srgb} bind def -/col86 {0.738 0.738 0.738 srgb} bind def -/col87 {0.824 0.582 0.320 srgb} bind def -/col88 {0.594 0.820 0.992 srgb} bind def -/col89 {0.547 0.609 0.418 srgb} bind def -/col90 {0.965 0.418 0.000 srgb} bind def -/col91 {0.352 0.418 0.223 srgb} bind def -/col92 {0.547 0.609 0.418 srgb} bind def -/col93 {0.547 0.609 0.480 srgb} bind def -/col94 {0.094 0.289 0.094 srgb} bind def -/col95 {0.676 0.676 0.676 srgb} bind def -/col96 {0.965 0.738 0.352 srgb} bind def -/col97 {0.387 0.418 0.609 srgb} bind def -/col98 {0.965 0.965 0.965 srgb} bind def -/col99 {0.867 0.000 0.000 srgb} bind def -/col100 {0.676 0.676 0.676 srgb} bind def -/col101 {0.965 0.738 0.352 srgb} bind def -/col102 {0.676 0.676 0.676 srgb} bind def -/col103 {0.965 0.738 0.352 srgb} bind def -/col104 {0.387 0.418 0.609 srgb} bind def -/col105 {0.320 0.418 0.160 srgb} bind def -/col106 {0.578 0.578 0.578 srgb} bind def -/col107 {0.000 0.387 0.000 srgb} bind def -/col108 {0.000 0.387 0.289 srgb} bind def -/col109 {0.480 0.516 0.289 srgb} bind def -/col110 {0.902 0.738 0.480 srgb} bind def -/col111 {0.645 0.707 0.773 srgb} bind def -/col112 {0.418 0.418 0.578 srgb} bind def -/col113 {0.516 0.418 0.418 srgb} bind def -/col114 {0.320 0.609 0.289 srgb} bind def -/col115 {0.836 0.902 0.902 srgb} bind def -/col116 {0.320 0.387 0.387 srgb} bind def -/col117 {0.094 0.418 0.289 srgb} bind def -/col118 {0.609 0.645 0.707 srgb} bind def -/col119 {0.996 0.578 0.000 srgb} bind def -/col120 {0.996 0.578 0.000 srgb} bind def -/col121 {0.000 0.387 0.289 srgb} bind def -/col122 {0.480 0.516 0.289 srgb} bind def -/col123 {0.387 0.449 0.480 srgb} bind def -/col124 {0.902 0.738 0.480 srgb} bind def -/col125 {0.867 0.867 0.867 srgb} bind def -/col126 {0.949 0.930 0.824 srgb} bind def -/col127 {0.957 0.680 0.363 srgb} bind def -/col128 {0.582 0.805 0.598 srgb} bind def -/col129 {0.707 0.082 0.488 srgb} bind def -/col130 {0.930 0.930 0.930 srgb} bind def -/col131 {0.516 0.516 0.516 srgb} bind def -/col132 {0.480 0.480 0.480 srgb} bind def -/col133 {0.000 0.352 0.000 srgb} bind def -/col134 {0.902 0.449 0.449 srgb} bind def -/col135 {0.996 0.793 0.191 srgb} bind def -/col136 {0.160 0.473 0.289 srgb} bind def -/col137 {0.867 0.156 0.129 srgb} bind def -/col138 {0.129 0.348 0.773 srgb} bind def -/col139 {0.969 0.969 0.969 srgb} bind def -/col140 {0.898 0.898 0.898 srgb} bind def -/col141 {0.129 0.516 0.352 srgb} bind def -/col142 {0.785 0.785 0.785 srgb} bind def -/col143 {0.871 0.844 0.871 srgb} bind def -/col144 {0.965 0.949 0.965 srgb} bind def - -end -save -newpath 0 300 moveto 0 0 lineto 488 0 lineto 488 300 lineto closepath clip newpath --32.6 348.9 translate -1 -1 scale - -/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 -/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 - -$F2psBegin -10 setmiterlimit -0 slj 0 slc - 0.06299 0.06299 sc -% -% Fig objects follow -% -% -% here starts figure with depth 50 -/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 -% Polyline -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 -/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 -% 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 -/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 -% 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 -/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 -% 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 -/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 -% 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 -/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 -% 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 -/Helvetica-iso ff 210.00 scf sf -3825 5130 m -gs 1 -1 sc (Memory) col0 sh 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 -/Helvetica-iso ff 210.00 scf sf -5635 5133 m -gs 1 -1 sc (Miscelleanous) col0 sh 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 210.00 scf sf -1495 5137 m -gs 1 -1 sc (S-expressions) col0 sh gr -% here ends figure; -$F2psEnd -rs -showpage diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.fig b/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.fig deleted file mode 100644 index ea3d05372a..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.fig +++ /dev/null @@ -1,193 +0,0 @@ -#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/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.pdf b/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.pdf Binary files differdeleted file mode 100644 index 23b87a618e..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.pdf +++ /dev/null diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.png b/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.png Binary files differdeleted file mode 100644 index dd194e2dd4..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/libgcrypt-modules.png +++ /dev/null diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/mdate-sh b/plugins/MirOTR/libgcrypt-1.4.6/doc/mdate-sh deleted file mode 100644 index cd916c0a34..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/mdate-sh +++ /dev/null @@ -1,201 +0,0 @@ -#!/bin/sh -# Get modification time of a file or directory and pretty-print it. - -scriptversion=2005-06-29.22 - -# Copyright (C) 1995, 1996, 1997, 2003, 2004, 2005 Free Software -# Foundation, Inc. -# written by Ulrich Drepper <drepper@gnu.ai.mit.edu>, June 1995 -# -# 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, 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - -# As a special exception to the GNU General Public License, if you -# distribute this file as part of a program that contains a -# configuration script generated by Autoconf, you may include it under -# the same distribution terms that you use for the rest of that program. - -# This file is maintained in Automake, please report -# bugs to <bug-automake@gnu.org> or send patches to -# <automake-patches@gnu.org>. - -case $1 in - '') - echo "$0: No file. Try \`$0 --help' for more information." 1>&2 - exit 1; - ;; - -h | --h*) - cat <<\EOF -Usage: mdate-sh [--help] [--version] FILE - -Pretty-print the modification time of FILE. - -Report bugs to <bug-automake@gnu.org>. -EOF - exit $? - ;; - -v | --v*) - echo "mdate-sh $scriptversion" - exit $? - ;; -esac - -# Prevent date giving response in another language. -LANG=C -export LANG -LC_ALL=C -export LC_ALL -LC_TIME=C -export LC_TIME - -# GNU ls changes its time format in response to the TIME_STYLE -# variable. Since we cannot assume `unset' works, revert this -# variable to its documented default. -if test "${TIME_STYLE+set}" = set; then - TIME_STYLE=posix-long-iso - export TIME_STYLE -fi - -save_arg1=$1 - -# Find out how to get the extended ls output of a file or directory. -if ls -L /dev/null 1>/dev/null 2>&1; then - ls_command='ls -L -l -d' -else - ls_command='ls -l -d' -fi - -# A `ls -l' line looks as follows on OS/2. -# drwxrwx--- 0 Aug 11 2001 foo -# This differs from Unix, which adds ownership information. -# drwxrwx--- 2 root root 4096 Aug 11 2001 foo -# -# To find the date, we split the line on spaces and iterate on words -# until we find a month. This cannot work with files whose owner is a -# user named `Jan', or `Feb', etc. However, it's unlikely that `/' -# will be owned by a user whose name is a month. So we first look at -# the extended ls output of the root directory to decide how many -# words should be skipped to get the date. - -# On HPUX /bin/sh, "set" interprets "-rw-r--r--" as options, so the "x" below. -set x`ls -l -d /` - -# Find which argument is the month. -month= -command= -until test $month -do - shift - # Add another shift to the command. - command="$command shift;" - case $1 in - Jan) month=January; nummonth=1;; - Feb) month=February; nummonth=2;; - Mar) month=March; nummonth=3;; - Apr) month=April; nummonth=4;; - May) month=May; nummonth=5;; - Jun) month=June; nummonth=6;; - Jul) month=July; nummonth=7;; - Aug) month=August; nummonth=8;; - Sep) month=September; nummonth=9;; - Oct) month=October; nummonth=10;; - Nov) month=November; nummonth=11;; - Dec) month=December; nummonth=12;; - esac -done - -# Get the extended ls output of the file or directory. -set dummy x`eval "$ls_command \"\$save_arg1\""` - -# Remove all preceding arguments -eval $command - -# Because of the dummy argument above, month is in $2. -# -# On a POSIX system, we should have -# -# $# = 5 -# $1 = file size -# $2 = month -# $3 = day -# $4 = year or time -# $5 = filename -# -# On Darwin 7.7.0 and 7.6.0, we have -# -# $# = 4 -# $1 = day -# $2 = month -# $3 = year or time -# $4 = filename - -# Get the month. -case $2 in - Jan) month=January; nummonth=1;; - Feb) month=February; nummonth=2;; - Mar) month=March; nummonth=3;; - Apr) month=April; nummonth=4;; - May) month=May; nummonth=5;; - Jun) month=June; nummonth=6;; - Jul) month=July; nummonth=7;; - Aug) month=August; nummonth=8;; - Sep) month=September; nummonth=9;; - Oct) month=October; nummonth=10;; - Nov) month=November; nummonth=11;; - Dec) month=December; nummonth=12;; -esac - -case $3 in - ???*) day=$1;; - *) day=$3; shift;; -esac - -# Here we have to deal with the problem that the ls output gives either -# the time of day or the year. -case $3 in - *:*) set `date`; eval year=\$$# - case $2 in - Jan) nummonthtod=1;; - Feb) nummonthtod=2;; - Mar) nummonthtod=3;; - Apr) nummonthtod=4;; - May) nummonthtod=5;; - Jun) nummonthtod=6;; - Jul) nummonthtod=7;; - Aug) nummonthtod=8;; - Sep) nummonthtod=9;; - Oct) nummonthtod=10;; - Nov) nummonthtod=11;; - Dec) nummonthtod=12;; - esac - # For the first six month of the year the time notation can also - # be used for files modified in the last year. - if (expr $nummonth \> $nummonthtod) > /dev/null; - then - year=`expr $year - 1` - fi;; - *) year=$3;; -esac - -# The result. -echo $day $month $year - -# Local Variables: -# mode: shell-script -# sh-indentation: 2 -# eval: (add-hook 'write-file-hooks 'time-stamp) -# time-stamp-start: "scriptversion=" -# time-stamp-format: "%:y-%02m-%02d.%02H" -# time-stamp-end: "$" -# End: diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/readme.txt b/plugins/MirOTR/libgcrypt-1.4.6/doc/readme.txt deleted file mode 100644 index fd10f94900..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/readme.txt +++ /dev/null @@ -1,6 +0,0 @@ -gpgvs
-building gnupg related projects with Visual Studio
-
-for documents check them on sourceforge project site
-
-http://sourceforge.net/projects/gpgvs/
\ No newline at end of file diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/stamp-vti b/plugins/MirOTR/libgcrypt-1.4.6/doc/stamp-vti deleted file mode 100644 index 294e4abcd0..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/stamp-vti +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 9 July 2009 -@set UPDATED-MONTH July 2009 -@set EDITION 1.4.6 -@set VERSION 1.4.6 diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/texinfo.tex b/plugins/MirOTR/libgcrypt-1.4.6/doc/texinfo.tex deleted file mode 100644 index 8083622350..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/texinfo.tex +++ /dev/null @@ -1,7482 +0,0 @@ -% texinfo.tex -- TeX macros to handle Texinfo files. -% -% Load plain if necessary, i.e., if running under initex. -\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi -% -\def\texinfoversion{2006-10-04.17} -% -% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, -% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free -% Software Foundation, Inc. -% -% This texinfo.tex file 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, or (at -% your option) any later version. -% -% This texinfo.tex file 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 texinfo.tex file; see the file COPYING. If not, write -% to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -% Boston, MA 02110-1301, USA. -% -% As a special exception, when this file is read by TeX when processing -% a Texinfo source document, you may use the result without -% restriction. (This has been our intent since Texinfo was invented.) -% -% Please try the latest version of texinfo.tex before submitting bug -% reports; you can get the latest version from: -% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or -% ftp://tug.org/tex/texinfo.tex -% (and all CTAN mirrors, see http://www.ctan.org). -% The texinfo.tex in any given distribution could well be out -% of date, so if that's what you're using, please check. -% -% Send bug reports to bug-texinfo@gnu.org. Please include including a -% complete document in each bug report with which we can reproduce the -% problem. Patches are, of course, greatly appreciated. -% -% To process a Texinfo manual with TeX, it's most reliable to use the -% texi2dvi shell script that comes with the distribution. For a simple -% manual foo.texi, however, you can get away with this: -% tex foo.texi -% texindex foo.?? -% tex foo.texi -% tex foo.texi -% dvips foo.dvi -o # or whatever; this makes foo.ps. -% The extra TeX runs get the cross-reference information correct. -% Sometimes one run after texindex suffices, and sometimes you need more -% than two; texi2dvi does it as many times as necessary. -% -% It is possible to adapt texinfo.tex for other languages, to some -% extent. You can get the existing language-specific files from the -% full Texinfo distribution. -% -% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. - - -\message{Loading texinfo [version \texinfoversion]:} - -% If in a .fmt file, print the version number -% and turn on active characters that we couldn't do earlier because -% they might have appeared in the input file name. -\everyjob{\message{[Texinfo version \texinfoversion]}% - \catcode`+=\active \catcode`\_=\active} - -\message{Basics,} -\chardef\other=12 - -% We never want plain's \outer definition of \+ in Texinfo. -% For @tex, we can use \tabalign. -\let\+ = \relax - -% Save some plain tex macros whose names we will redefine. -\let\ptexb=\b -\let\ptexbullet=\bullet -\let\ptexc=\c -\let\ptexcomma=\, -\let\ptexdot=\. -\let\ptexdots=\dots -\let\ptexend=\end -\let\ptexequiv=\equiv -\let\ptexexclam=\! -\let\ptexfootnote=\footnote -\let\ptexgtr=> -\let\ptexhat=^ -\let\ptexi=\i -\let\ptexindent=\indent -\let\ptexinsert=\insert -\let\ptexlbrace=\{ -\let\ptexless=< -\let\ptexnewwrite\newwrite -\let\ptexnoindent=\noindent -\let\ptexplus=+ -\let\ptexrbrace=\} -\let\ptexslash=\/ -\let\ptexstar=\* -\let\ptext=\t - -% If this character appears in an error message or help string, it -% starts a new line in the output. -\newlinechar = `^^J - -% Use TeX 3.0's \inputlineno to get the line number, for better error -% messages, but if we're using an old version of TeX, don't do anything. -% -\ifx\inputlineno\thisisundefined - \let\linenumber = \empty % Pre-3.0. -\else - \def\linenumber{l.\the\inputlineno:\space} -\fi - -% Set up fixed words for English if not already set. -\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi -\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi -\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi -\ifx\putwordin\undefined \gdef\putwordin{in}\fi -\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi -\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi -\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi -\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi -\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi -\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi -\ifx\putwordof\undefined \gdef\putwordof{of}\fi -\ifx\putwordon\undefined \gdef\putwordon{on}\fi -\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi -\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi -\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi -\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi -\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi -\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi -\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi -% -\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi -\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi -\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi -\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi -\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi -\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi -\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi -\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi -\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi -\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi -\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi -\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi -% -\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi -\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi -\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi -\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi -\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi - -% Since the category of space is not known, we have to be careful. -\chardef\spacecat = 10 -\def\spaceisspace{\catcode`\ =\spacecat} - -% sometimes characters are active, so we need control sequences. -\chardef\colonChar = `\: -\chardef\commaChar = `\, -\chardef\dashChar = `\- -\chardef\dotChar = `\. -\chardef\exclamChar= `\! -\chardef\lquoteChar= `\` -\chardef\questChar = `\? -\chardef\rquoteChar= `\' -\chardef\semiChar = `\; -\chardef\underChar = `\_ - -% Ignore a token. -% -\def\gobble#1{} - -% The following is used inside several \edef's. -\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname} - -% Hyphenation fixes. -\hyphenation{ - Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script - ap-pen-dix bit-map bit-maps - data-base data-bases eshell fall-ing half-way long-est man-u-script - man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm - par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces - spell-ing spell-ings - stand-alone strong-est time-stamp time-stamps which-ever white-space - wide-spread wrap-around -} - -% Margin to add to right of even pages, to left of odd pages. -\newdimen\bindingoffset -\newdimen\normaloffset -\newdimen\pagewidth \newdimen\pageheight - -% For a final copy, take out the rectangles -% that mark overfull boxes (in case you have decided -% that the text looks ok even though it passes the margin). -% -\def\finalout{\overfullrule=0pt} - -% @| inserts a changebar to the left of the current line. It should -% surround any changed text. This approach does *not* work if the -% change spans more than two lines of output. To handle that, we would -% have adopt a much more difficult approach (putting marks into the main -% vertical list for the beginning and end of each change). -% -\def\|{% - % \vadjust can only be used in horizontal mode. - \leavevmode - % - % Append this vertical mode material after the current line in the output. - \vadjust{% - % We want to insert a rule with the height and depth of the current - % leading; that is exactly what \strutbox is supposed to record. - \vskip-\baselineskip - % - % \vadjust-items are inserted at the left edge of the type. So - % the \llap here moves out into the left-hand margin. - \llap{% - % - % For a thicker or thinner bar, change the `1pt'. - \vrule height\baselineskip width1pt - % - % This is the space between the bar and the text. - \hskip 12pt - }% - }% -} - -% Sometimes it is convenient to have everything in the transcript file -% and nothing on the terminal. We don't just call \tracingall here, -% since that produces some useless output on the terminal. We also make -% some effort to order the tracing commands to reduce output in the log -% file; cf. trace.sty in LaTeX. -% -\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% -\def\loggingall{% - \tracingstats2 - \tracingpages1 - \tracinglostchars2 % 2 gives us more in etex - \tracingparagraphs1 - \tracingoutput1 - \tracingmacros2 - \tracingrestores1 - \showboxbreadth\maxdimen \showboxdepth\maxdimen - \ifx\eTeXversion\undefined\else % etex gives us more logging - \tracingscantokens1 - \tracingifs1 - \tracinggroups1 - \tracingnesting2 - \tracingassigns1 - \fi - \tracingcommands3 % 3 gives us more in etex - \errorcontextlines16 -}% - -% add check for \lastpenalty to plain's definitions. If the last thing -% we did was a \nobreak, we don't want to insert more space. -% -\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount - \removelastskip\penalty-50\smallskip\fi\fi} -\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount - \removelastskip\penalty-100\medskip\fi\fi} -\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount - \removelastskip\penalty-200\bigskip\fi\fi} - -% For @cropmarks command. -% Do @cropmarks to get crop marks. -% -\newif\ifcropmarks -\let\cropmarks = \cropmarkstrue -% -% Dimensions to add cropmarks at corners. -% Added by P. A. MacKay, 12 Nov. 1986 -% -\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines -\newdimen\cornerlong \cornerlong=1pc -\newdimen\cornerthick \cornerthick=.3pt -\newdimen\topandbottommargin \topandbottommargin=.75in - -% Main output routine. -\chardef\PAGE = 255 -\output = {\onepageout{\pagecontents\PAGE}} - -\newbox\headlinebox -\newbox\footlinebox - -% \onepageout takes a vbox as an argument. Note that \pagecontents -% does insertions, but you have to call it yourself. -\def\onepageout#1{% - \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi - % - \ifodd\pageno \advance\hoffset by \bindingoffset - \else \advance\hoffset by -\bindingoffset\fi - % - % Do this outside of the \shipout so @code etc. will be expanded in - % the headline as they should be, not taken literally (outputting ''code). - \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% - \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% - % - {% - % Have to do this stuff outside the \shipout because we want it to - % take effect in \write's, yet the group defined by the \vbox ends - % before the \shipout runs. - % - \indexdummies % don't expand commands in the output. - \normalturnoffactive % \ in index entries must not stay \, e.g., if - % the page break happens to be in the middle of an example. - % We don't want .vr (or whatever) entries like this: - % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}} - % "\acronym" won't work when it's read back in; - % it needs to be - % {\code {{\tt \backslashcurfont }acronym} - \shipout\vbox{% - % Do this early so pdf references go to the beginning of the page. - \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi - % - \ifcropmarks \vbox to \outervsize\bgroup - \hsize = \outerhsize - \vskip-\topandbottommargin - \vtop to0pt{% - \line{\ewtop\hfil\ewtop}% - \nointerlineskip - \line{% - \vbox{\moveleft\cornerthick\nstop}% - \hfill - \vbox{\moveright\cornerthick\nstop}% - }% - \vss}% - \vskip\topandbottommargin - \line\bgroup - \hfil % center the page within the outer (page) hsize. - \ifodd\pageno\hskip\bindingoffset\fi - \vbox\bgroup - \fi - % - \unvbox\headlinebox - \pagebody{#1}% - \ifdim\ht\footlinebox > 0pt - % Only leave this space if the footline is nonempty. - % (We lessened \vsize for it in \oddfootingyyy.) - % The \baselineskip=24pt in plain's \makefootline has no effect. - \vskip 24pt - \unvbox\footlinebox - \fi - % - \ifcropmarks - \egroup % end of \vbox\bgroup - \hfil\egroup % end of (centering) \line\bgroup - \vskip\topandbottommargin plus1fill minus1fill - \boxmaxdepth = \cornerthick - \vbox to0pt{\vss - \line{% - \vbox{\moveleft\cornerthick\nsbot}% - \hfill - \vbox{\moveright\cornerthick\nsbot}% - }% - \nointerlineskip - \line{\ewbot\hfil\ewbot}% - }% - \egroup % \vbox from first cropmarks clause - \fi - }% end of \shipout\vbox - }% end of group with \indexdummies - \advancepageno - \ifnum\outputpenalty>-20000 \else\dosupereject\fi -} - -\newinsert\margin \dimen\margin=\maxdimen - -\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} -{\catcode`\@ =11 -\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi -% marginal hacks, juha@viisa.uucp (Juha Takala) -\ifvoid\margin\else % marginal info is present - \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi -\dimen@=\dp#1 \unvbox#1 -\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi -\ifr@ggedbottom \kern-\dimen@ \vfil \fi} -} - -% Here are the rules for the cropmarks. Note that they are -% offset so that the space between them is truly \outerhsize or \outervsize -% (P. A. MacKay, 12 November, 1986) -% -\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} -\def\nstop{\vbox - {\hrule height\cornerthick depth\cornerlong width\cornerthick}} -\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} -\def\nsbot{\vbox - {\hrule height\cornerlong depth\cornerthick width\cornerthick}} - -% Parse an argument, then pass it to #1. The argument is the rest of -% the input line (except we remove a trailing comment). #1 should be a -% macro which expects an ordinary undelimited TeX argument. -% -\def\parsearg{\parseargusing{}} -\def\parseargusing#1#2{% - \def\argtorun{#2}% - \begingroup - \obeylines - \spaceisspace - #1% - \parseargline\empty% Insert the \empty token, see \finishparsearg below. -} - -{\obeylines % - \gdef\parseargline#1^^M{% - \endgroup % End of the group started in \parsearg. - \argremovecomment #1\comment\ArgTerm% - }% -} - -% First remove any @comment, then any @c comment. -\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} -\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} - -% Each occurence of `\^^M' or `<space>\^^M' is replaced by a single space. -% -% \argremovec might leave us with trailing space, e.g., -% @end itemize @c foo -% This space token undergoes the same procedure and is eventually removed -% by \finishparsearg. -% -\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M} -\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M} -\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{% - \def\temp{#3}% - \ifx\temp\empty - % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp: - \let\temp\finishparsearg - \else - \let\temp\argcheckspaces - \fi - % Put the space token in: - \temp#1 #3\ArgTerm -} - -% If a _delimited_ argument is enclosed in braces, they get stripped; so -% to get _exactly_ the rest of the line, we had to prevent such situation. -% We prepended an \empty token at the very beginning and we expand it now, -% just before passing the control to \argtorun. -% (Similarily, we have to think about #3 of \argcheckspacesY above: it is -% either the null string, or it ends with \^^M---thus there is no danger -% that a pair of braces would be stripped. -% -% But first, we have to remove the trailing space token. -% -\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}} - -% \parseargdef\foo{...} -% is roughly equivalent to -% \def\foo{\parsearg\Xfoo} -% \def\Xfoo#1{...} -% -% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my -% favourite TeX trick. --kasal, 16nov03 - -\def\parseargdef#1{% - \expandafter \doparseargdef \csname\string#1\endcsname #1% -} -\def\doparseargdef#1#2{% - \def#2{\parsearg#1}% - \def#1##1% -} - -% Several utility definitions with active space: -{ - \obeyspaces - \gdef\obeyedspace{ } - - % Make each space character in the input produce a normal interword - % space in the output. Don't allow a line break at this space, as this - % is used only in environments like @example, where each line of input - % should produce a line of output anyway. - % - \gdef\sepspaces{\obeyspaces\let =\tie} - - % If an index command is used in an @example environment, any spaces - % therein should become regular spaces in the raw index file, not the - % expansion of \tie (\leavevmode \penalty \@M \ ). - \gdef\unsepspaces{\let =\space} -} - - -\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} - -% Define the framework for environments in texinfo.tex. It's used like this: -% -% \envdef\foo{...} -% \def\Efoo{...} -% -% It's the responsibility of \envdef to insert \begingroup before the -% actual body; @end closes the group after calling \Efoo. \envdef also -% defines \thisenv, so the current environment is known; @end checks -% whether the environment name matches. The \checkenv macro can also be -% used to check whether the current environment is the one expected. -% -% Non-false conditionals (@iftex, @ifset) don't fit into this, so they -% are not treated as enviroments; they don't open a group. (The -% implementation of @end takes care not to call \endgroup in this -% special case.) - - -% At runtime, environments start with this: -\def\startenvironment#1{\begingroup\def\thisenv{#1}} -% initialize -\let\thisenv\empty - -% ... but they get defined via ``\envdef\foo{...}'': -\long\def\envdef#1#2{\def#1{\startenvironment#1#2}} -\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}} - -% Check whether we're in the right environment: -\def\checkenv#1{% - \def\temp{#1}% - \ifx\thisenv\temp - \else - \badenverr - \fi -} - -% Evironment mismatch, #1 expected: -\def\badenverr{% - \errhelp = \EMsimple - \errmessage{This command can appear only \inenvironment\temp, - not \inenvironment\thisenv}% -} -\def\inenvironment#1{% - \ifx#1\empty - out of any environment% - \else - in environment \expandafter\string#1% - \fi -} - -% @end foo executes the definition of \Efoo. -% But first, it executes a specialized version of \checkenv -% -\parseargdef\end{% - \if 1\csname iscond.#1\endcsname - \else - % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03 - \expandafter\checkenv\csname#1\endcsname - \csname E#1\endcsname - \endgroup - \fi -} - -\newhelp\EMsimple{Press RETURN to continue.} - - -%% Simple single-character @ commands - -% @@ prints an @ -% Kludge this until the fonts are right (grr). -\def\@{{\tt\char64}} - -% This is turned off because it was never documented -% and you can use @w{...} around a quote to suppress ligatures. -%% Define @` and @' to be the same as ` and ' -%% but suppressing ligatures. -%\def\`{{`}} -%\def\'{{'}} - -% Used to generate quoted braces. -\def\mylbrace {{\tt\char123}} -\def\myrbrace {{\tt\char125}} -\let\{=\mylbrace -\let\}=\myrbrace -\begingroup - % Definitions to produce \{ and \} commands for indices, - % and @{ and @} for the aux/toc files. - \catcode`\{ = \other \catcode`\} = \other - \catcode`\[ = 1 \catcode`\] = 2 - \catcode`\! = 0 \catcode`\\ = \other - !gdef!lbracecmd[\{]% - !gdef!rbracecmd[\}]% - !gdef!lbraceatcmd[@{]% - !gdef!rbraceatcmd[@}]% -!endgroup - -% @comma{} to avoid , parsing problems. -\let\comma = , - -% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent -% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H. -\let\, = \c -\let\dotaccent = \. -\def\ringaccent#1{{\accent23 #1}} -\let\tieaccent = \t -\let\ubaraccent = \b -\let\udotaccent = \d - -% Other special characters: @questiondown @exclamdown @ordf @ordm -% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. -\def\questiondown{?`} -\def\exclamdown{!`} -\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}} -\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}} - -% Dotless i and dotless j, used for accents. -\def\imacro{i} -\def\jmacro{j} -\def\dotless#1{% - \def\temp{#1}% - \ifx\temp\imacro \ptexi - \else\ifx\temp\jmacro \j - \else \errmessage{@dotless can be used only with i or j}% - \fi\fi -} - -% The \TeX{} logo, as in plain, but resetting the spacing so that a -% period following counts as ending a sentence. (Idea found in latex.) -% -\edef\TeX{\TeX \spacefactor=1000 } - -% @LaTeX{} logo. Not quite the same results as the definition in -% latex.ltx, since we use a different font for the raised A; it's most -% convenient for us to use an explicitly smaller font, rather than using -% the \scriptstyle font (since we don't reset \scriptstyle and -% \scriptscriptstyle). -% -\def\LaTeX{% - L\kern-.36em - {\setbox0=\hbox{T}% - \vbox to \ht0{\hbox{\selectfonts\lllsize A}\vss}}% - \kern-.15em - \TeX -} - -% Be sure we're in horizontal mode when doing a tie, since we make space -% equivalent to this in @example-like environments. Otherwise, a space -% at the beginning of a line will start with \penalty -- and -% since \penalty is valid in vertical mode, we'd end up putting the -% penalty on the vertical list instead of in the new paragraph. -{\catcode`@ = 11 - % Avoid using \@M directly, because that causes trouble - % if the definition is written into an index file. - \global\let\tiepenalty = \@M - \gdef\tie{\leavevmode\penalty\tiepenalty\ } -} - -% @: forces normal size whitespace following. -\def\:{\spacefactor=1000 } - -% @* forces a line break. -\def\*{\hfil\break\hbox{}\ignorespaces} - -% @/ allows a line break. -\let\/=\allowbreak - -% @. is an end-of-sentence period. -\def\.{.\spacefactor=\endofsentencespacefactor\space} - -% @! is an end-of-sentence bang. -\def\!{!\spacefactor=\endofsentencespacefactor\space} - -% @? is an end-of-sentence query. -\def\?{?\spacefactor=\endofsentencespacefactor\space} - -% @frenchspacing on|off says whether to put extra space after punctuation. -% -\def\onword{on} -\def\offword{off} -% -\parseargdef\frenchspacing{% - \def\temp{#1}% - \ifx\temp\onword \plainfrenchspacing - \else\ifx\temp\offword \plainnonfrenchspacing - \else - \errhelp = \EMsimple - \errmessage{Unknown @frenchspacing option `\temp', must be on/off}% - \fi\fi -} - -% @w prevents a word break. Without the \leavevmode, @w at the -% beginning of a paragraph, when TeX is still in vertical mode, would -% produce a whole line of output instead of starting the paragraph. -\def\w#1{\leavevmode\hbox{#1}} - -% @group ... @end group forces ... to be all on one page, by enclosing -% it in a TeX vbox. We use \vtop instead of \vbox to construct the box -% to keep its height that of a normal line. According to the rules for -% \topskip (p.114 of the TeXbook), the glue inserted is -% max (\topskip - \ht (first item), 0). If that height is large, -% therefore, no glue is inserted, and the space between the headline and -% the text is small, which looks bad. -% -% Another complication is that the group might be very large. This can -% cause the glue on the previous page to be unduly stretched, because it -% does not have much material. In this case, it's better to add an -% explicit \vfill so that the extra space is at the bottom. The -% threshold for doing this is if the group is more than \vfilllimit -% percent of a page (\vfilllimit can be changed inside of @tex). -% -\newbox\groupbox -\def\vfilllimit{0.7} -% -\envdef\group{% - \ifnum\catcode`\^^M=\active \else - \errhelp = \groupinvalidhelp - \errmessage{@group invalid in context where filling is enabled}% - \fi - \startsavinginserts - % - \setbox\groupbox = \vtop\bgroup - % Do @comment since we are called inside an environment such as - % @example, where each end-of-line in the input causes an - % end-of-line in the output. We don't want the end-of-line after - % the `@group' to put extra space in the output. Since @group - % should appear on a line by itself (according to the Texinfo - % manual), we don't worry about eating any user text. - \comment -} -% -% The \vtop produces a box with normal height and large depth; thus, TeX puts -% \baselineskip glue before it, and (when the next line of text is done) -% \lineskip glue after it. Thus, space below is not quite equal to space -% above. But it's pretty close. -\def\Egroup{% - % To get correct interline space between the last line of the group - % and the first line afterwards, we have to propagate \prevdepth. - \endgraf % Not \par, as it may have been set to \lisppar. - \global\dimen1 = \prevdepth - \egroup % End the \vtop. - % \dimen0 is the vertical size of the group's box. - \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox - % \dimen2 is how much space is left on the page (more or less). - \dimen2 = \pageheight \advance\dimen2 by -\pagetotal - % if the group doesn't fit on the current page, and it's a big big - % group, force a page break. - \ifdim \dimen0 > \dimen2 - \ifdim \pagetotal < \vfilllimit\pageheight - \page - \fi - \fi - \box\groupbox - \prevdepth = \dimen1 - \checkinserts -} -% -% TeX puts in an \escapechar (i.e., `@') at the beginning of the help -% message, so this ends up printing `@group can only ...'. -% -\newhelp\groupinvalidhelp{% -group can only be used in environments such as @example,^^J% -where each line of input produces a line of output.} - -% @need space-in-mils -% forces a page break if there is not space-in-mils remaining. - -\newdimen\mil \mil=0.001in - -% Old definition--didn't work. -%\parseargdef\need{\par % -%% This method tries to make TeX break the page naturally -%% if the depth of the box does not fit. -%{\baselineskip=0pt% -%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak -%\prevdepth=-1000pt -%}} - -\parseargdef\need{% - % Ensure vertical mode, so we don't make a big box in the middle of a - % paragraph. - \par - % - % If the @need value is less than one line space, it's useless. - \dimen0 = #1\mil - \dimen2 = \ht\strutbox - \advance\dimen2 by \dp\strutbox - \ifdim\dimen0 > \dimen2 - % - % Do a \strut just to make the height of this box be normal, so the - % normal leading is inserted relative to the preceding line. - % And a page break here is fine. - \vtop to #1\mil{\strut\vfil}% - % - % TeX does not even consider page breaks if a penalty added to the - % main vertical list is 10000 or more. But in order to see if the - % empty box we just added fits on the page, we must make it consider - % page breaks. On the other hand, we don't want to actually break the - % page after the empty box. So we use a penalty of 9999. - % - % There is an extremely small chance that TeX will actually break the - % page at this \penalty, if there are no other feasible breakpoints in - % sight. (If the user is using lots of big @group commands, which - % almost-but-not-quite fill up a page, TeX will have a hard time doing - % good page breaking, for example.) However, I could not construct an - % example where a page broke at this \penalty; if it happens in a real - % document, then we can reconsider our strategy. - \penalty9999 - % - % Back up by the size of the box, whether we did a page break or not. - \kern -#1\mil - % - % Do not allow a page break right after this kern. - \nobreak - \fi -} - -% @br forces paragraph break (and is undocumented). - -\let\br = \par - -% @page forces the start of a new page. -% -\def\page{\par\vfill\supereject} - -% @exdent text.... -% outputs text on separate line in roman font, starting at standard page margin - -% This records the amount of indent in the innermost environment. -% That's how much \exdent should take out. -\newskip\exdentamount - -% This defn is used inside fill environments such as @defun. -\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break} - -% This defn is used inside nofill environments such as @example. -\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount - \leftline{\hskip\leftskip{\rm#1}}}} - -% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current -% paragraph. For more general purposes, use the \margin insertion -% class. WHICH is `l' or `r'. -% -\newskip\inmarginspacing \inmarginspacing=1cm -\def\strutdepth{\dp\strutbox} -% -\def\doinmargin#1#2{\strut\vadjust{% - \nobreak - \kern-\strutdepth - \vtop to \strutdepth{% - \baselineskip=\strutdepth - \vss - % if you have multiple lines of stuff to put here, you'll need to - % make the vbox yourself of the appropriate size. - \ifx#1l% - \llap{\ignorespaces #2\hskip\inmarginspacing}% - \else - \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}% - \fi - \null - }% -}} -\def\inleftmargin{\doinmargin l} -\def\inrightmargin{\doinmargin r} -% -% @inmargin{TEXT [, RIGHT-TEXT]} -% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right; -% else use TEXT for both). -% -\def\inmargin#1{\parseinmargin #1,,\finish} -\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing. - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0 > 0pt - \def\lefttext{#1}% have both texts - \def\righttext{#2}% - \else - \def\lefttext{#1}% have only one text - \def\righttext{#1}% - \fi - % - \ifodd\pageno - \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin - \else - \def\temp{\inleftmargin\lefttext}% - \fi - \temp -} - -% @include file insert text of that file as input. -% -\def\include{\parseargusing\filenamecatcodes\includezzz} -\def\includezzz#1{% - \pushthisfilestack - \def\thisfile{#1}% - {% - \makevalueexpandable - \def\temp{\input #1 }% - \expandafter - }\temp - \popthisfilestack -} -\def\filenamecatcodes{% - \catcode`\\=\other - \catcode`~=\other - \catcode`^=\other - \catcode`_=\other - \catcode`|=\other - \catcode`<=\other - \catcode`>=\other - \catcode`+=\other - \catcode`-=\other -} - -\def\pushthisfilestack{% - \expandafter\pushthisfilestackX\popthisfilestack\StackTerm -} -\def\pushthisfilestackX{% - \expandafter\pushthisfilestackY\thisfile\StackTerm -} -\def\pushthisfilestackY #1\StackTerm #2\StackTerm {% - \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}% -} - -\def\popthisfilestack{\errthisfilestackempty} -\def\errthisfilestackempty{\errmessage{Internal error: - the stack of filenames is empty.}} - -\def\thisfile{} - -% @center line -% outputs that line, centered. -% -\parseargdef\center{% - \ifhmode - \let\next\centerH - \else - \let\next\centerV - \fi - \next{\hfil \ignorespaces#1\unskip \hfil}% -} -\def\centerH#1{% - {% - \hfil\break - \advance\hsize by -\leftskip - \advance\hsize by -\rightskip - \line{#1}% - \break - }% -} -\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}} - -% @sp n outputs n lines of vertical space - -\parseargdef\sp{\vskip #1\baselineskip} - -% @comment ...line which is ignored... -% @c is the same as @comment -% @ignore ... @end ignore is another way to write a comment - -\def\comment{\begingroup \catcode`\^^M=\other% -\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% -\commentxxx} -{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}} - -\let\c=\comment - -% @paragraphindent NCHARS -% We'll use ems for NCHARS, close enough. -% NCHARS can also be the word `asis' or `none'. -% We cannot feasibly implement @paragraphindent asis, though. -% -\def\asisword{asis} % no translation, these are keywords -\def\noneword{none} -% -\parseargdef\paragraphindent{% - \def\temp{#1}% - \ifx\temp\asisword - \else - \ifx\temp\noneword - \defaultparindent = 0pt - \else - \defaultparindent = #1em - \fi - \fi - \parindent = \defaultparindent -} - -% @exampleindent NCHARS -% We'll use ems for NCHARS like @paragraphindent. -% It seems @exampleindent asis isn't necessary, but -% I preserve it to make it similar to @paragraphindent. -\parseargdef\exampleindent{% - \def\temp{#1}% - \ifx\temp\asisword - \else - \ifx\temp\noneword - \lispnarrowing = 0pt - \else - \lispnarrowing = #1em - \fi - \fi -} - -% @firstparagraphindent WORD -% If WORD is `none', then suppress indentation of the first paragraph -% after a section heading. If WORD is `insert', then do indent at such -% paragraphs. -% -% The paragraph indentation is suppressed or not by calling -% \suppressfirstparagraphindent, which the sectioning commands do. -% We switch the definition of this back and forth according to WORD. -% By default, we suppress indentation. -% -\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent} -\def\insertword{insert} -% -\parseargdef\firstparagraphindent{% - \def\temp{#1}% - \ifx\temp\noneword - \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent - \else\ifx\temp\insertword - \let\suppressfirstparagraphindent = \relax - \else - \errhelp = \EMsimple - \errmessage{Unknown @firstparagraphindent option `\temp'}% - \fi\fi -} - -% Here is how we actually suppress indentation. Redefine \everypar to -% \kern backwards by \parindent, and then reset itself to empty. -% -% We also make \indent itself not actually do anything until the next -% paragraph. -% -\gdef\dosuppressfirstparagraphindent{% - \gdef\indent{% - \restorefirstparagraphindent - \indent - }% - \gdef\noindent{% - \restorefirstparagraphindent - \noindent - }% - \global\everypar = {% - \kern -\parindent - \restorefirstparagraphindent - }% -} - -\gdef\restorefirstparagraphindent{% - \global \let \indent = \ptexindent - \global \let \noindent = \ptexnoindent - \global \everypar = {}% -} - - -% @asis just yields its argument. Used with @table, for example. -% -\def\asis#1{#1} - -% @math outputs its argument in math mode. -% -% One complication: _ usually means subscripts, but it could also mean -% an actual _ character, as in @math{@var{some_variable} + 1}. So make -% _ active, and distinguish by seeing if the current family is \slfam, -% which is what @var uses. -{ - \catcode`\_ = \active - \gdef\mathunderscore{% - \catcode`\_=\active - \def_{\ifnum\fam=\slfam \_\else\sb\fi}% - } -} -% Another complication: we want \\ (and @\) to output a \ character. -% FYI, plain.tex uses \\ as a temporary control sequence (why?), but -% this is not advertised and we don't care. Texinfo does not -% otherwise define @\. -% -% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\. -\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi} -% -\def\math{% - \tex - \mathunderscore - \let\\ = \mathbackslash - \mathactive - $\finishmath -} -\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. - -% Some active characters (such as <) are spaced differently in math. -% We have to reset their definitions in case the @math was an argument -% to a command which sets the catcodes (such as @item or @section). -% -{ - \catcode`^ = \active - \catcode`< = \active - \catcode`> = \active - \catcode`+ = \active - \gdef\mathactive{% - \let^ = \ptexhat - \let< = \ptexless - \let> = \ptexgtr - \let+ = \ptexplus - } -} - -% @bullet and @minus need the same treatment as @math, just above. -\def\bullet{$\ptexbullet$} -\def\minus{$-$} - -% @dots{} outputs an ellipsis using the current font. -% We do .5em per period so that it has the same spacing in the cm -% typewriter fonts as three actual period characters; on the other hand, -% in other typewriter fonts three periods are wider than 1.5em. So do -% whichever is larger. -% -\def\dots{% - \leavevmode - \setbox0=\hbox{...}% get width of three periods - \ifdim\wd0 > 1.5em - \dimen0 = \wd0 - \else - \dimen0 = 1.5em - \fi - \hbox to \dimen0{% - \hskip 0pt plus.25fil - .\hskip 0pt plus1fil - .\hskip 0pt plus1fil - .\hskip 0pt plus.5fil - }% -} - -% @enddots{} is an end-of-sentence ellipsis. -% -\def\enddots{% - \dots - \spacefactor=\endofsentencespacefactor -} - -% @comma{} is so commas can be inserted into text without messing up -% Texinfo's parsing. -% -\let\comma = , - -% @refill is a no-op. -\let\refill=\relax - -% If working on a large document in chapters, it is convenient to -% be able to disable indexing, cross-referencing, and contents, for test runs. -% This is done with @novalidate (before @setfilename). -% -\newif\iflinks \linkstrue % by default we want the aux files. -\let\novalidate = \linksfalse - -% @setfilename is done at the beginning of every texinfo file. -% So open here the files we need to have open while reading the input. -% This makes it possible to make a .fmt file for texinfo. -\def\setfilename{% - \fixbackslash % Turn off hack to swallow `\input texinfo'. - \iflinks - \tryauxfile - % Open the new aux file. TeX will close it automatically at exit. - \immediate\openout\auxfile=\jobname.aux - \fi % \openindices needs to do some work in any case. - \openindices - \let\setfilename=\comment % Ignore extra @setfilename cmds. - % - % If texinfo.cnf is present on the system, read it. - % Useful for site-wide @afourpaper, etc. - \openin 1 texinfo.cnf - \ifeof 1 \else \input texinfo.cnf \fi - \closein 1 - % - \comment % Ignore the actual filename. -} - -% Called from \setfilename. -% -\def\openindices{% - \newindex{cp}% - \newcodeindex{fn}% - \newcodeindex{vr}% - \newcodeindex{tp}% - \newcodeindex{ky}% - \newcodeindex{pg}% -} - -% @bye. -\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} - - -\message{pdf,} -% adobe `portable' document format -\newcount\tempnum -\newcount\lnkcount -\newtoks\filename -\newcount\filenamelength -\newcount\pgn -\newtoks\toksA -\newtoks\toksB -\newtoks\toksC -\newtoks\toksD -\newbox\boxA -\newcount\countA -\newif\ifpdf -\newif\ifpdfmakepagedest - -% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1 -% can be set). So we test for \relax and 0 as well as \undefined, -% borrowed from ifpdf.sty. -\ifx\pdfoutput\undefined -\else - \ifx\pdfoutput\relax - \else - \ifcase\pdfoutput - \else - \pdftrue - \fi - \fi -\fi - -% PDF uses PostScript string constants for the names of xref targets, -% for display in the outlines, and in other places. Thus, we have to -% double any backslashes. Otherwise, a name like "\node" will be -% interpreted as a newline (\n), followed by o, d, e. Not good. -% http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html -% (and related messages, the final outcome is that it is up to the TeX -% user to double the backslashes and otherwise make the string valid, so -% that's what we do). - -% double active backslashes. -% -{\catcode`\@=0 \catcode`\\=\active - @gdef@activebackslashdouble{% - @catcode`@\=@active - @let\=@doublebackslash} -} - -% To handle parens, we must adopt a different approach, since parens are -% not active characters. hyperref.dtx (which has the same problem as -% us) handles it with this amazing macro to replace tokens. I've -% tinkered with it a little for texinfo, but it's definitely from there. -% -% #1 is the tokens to replace. -% #2 is the replacement. -% #3 is the control sequence with the string. -% -\def\HyPsdSubst#1#2#3{% - \def\HyPsdReplace##1#1##2\END{% - ##1% - \ifx\\##2\\% - \else - #2% - \HyReturnAfterFi{% - \HyPsdReplace##2\END - }% - \fi - }% - \xdef#3{\expandafter\HyPsdReplace#3#1\END}% -} -\long\def\HyReturnAfterFi#1\fi{\fi#1} - -% #1 is a control sequence in which to do the replacements. -\def\backslashparens#1{% - \xdef#1{#1}% redefine it as its expansion; the definition is simply - % \lastnode when called from \setref -> \pdfmkdest. - \HyPsdSubst{(}{\realbackslash(}{#1}% - \HyPsdSubst{)}{\realbackslash)}{#1}% -} - -\ifpdf - \input pdfcolor - \pdfcatalog{/PageMode /UseOutlines}% - % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto). - \def\dopdfimage#1#2#3{% - \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% - \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% - % without \immediate, pdftex seg faults when the same image is - % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.) - \ifnum\pdftexversion < 14 - \immediate\pdfimage - \else - \immediate\pdfximage - \fi - \ifdim \wd0 >0pt width \imagewidth \fi - \ifdim \wd2 >0pt height \imageheight \fi - \ifnum\pdftexversion<13 - #1.pdf% - \else - {#1.pdf}% - \fi - \ifnum\pdftexversion < 14 \else - \pdfrefximage \pdflastximage - \fi} - \def\pdfmkdest#1{{% - % We have to set dummies so commands such as @code, and characters - % such as \, aren't expanded when present in a section title. - \atdummies - \activebackslashdouble - \def\pdfdestname{#1}% - \backslashparens\pdfdestname - \pdfdest name{\pdfdestname} xyz% - }}% - % - % used to mark target names; must be expandable. - \def\pdfmkpgn#1{#1}% - % - \let\linkcolor = \Blue % was Cyan, but that seems light? - \def\endlink{\Black\pdfendlink} - % Adding outlines to PDF; macros for calculating structure of outlines - % come from Petr Olsak - \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0% - \else \csname#1\endcsname \fi} - \def\advancenumber#1{\tempnum=\expnumber{#1}\relax - \advance\tempnum by 1 - \expandafter\xdef\csname#1\endcsname{\the\tempnum}} - % - % #1 is the section text, which is what will be displayed in the - % outline by the pdf viewer. #2 is the pdf expression for the number - % of subentries (or empty, for subsubsections). #3 is the node text, - % which might be empty if this toc entry had no corresponding node. - % #4 is the page number - % - \def\dopdfoutline#1#2#3#4{% - % Generate a link to the node text if that exists; else, use the - % page number. We could generate a destination for the section - % text in the case where a section has no node, but it doesn't - % seem worth the trouble, since most documents are normally structured. - \def\pdfoutlinedest{#3}% - \ifx\pdfoutlinedest\empty - \def\pdfoutlinedest{#4}% - \else - % Doubled backslashes in the name. - {\activebackslashdouble \xdef\pdfoutlinedest{#3}% - \backslashparens\pdfoutlinedest}% - \fi - % - % Also double the backslashes in the display string. - {\activebackslashdouble \xdef\pdfoutlinetext{#1}% - \backslashparens\pdfoutlinetext}% - % - \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}% - } - % - \def\pdfmakeoutlines{% - \begingroup - % Thanh's hack / proper braces in bookmarks - \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace - \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace - % - % Read toc silently, to get counts of subentries for \pdfoutline. - \def\numchapentry##1##2##3##4{% - \def\thischapnum{##2}% - \def\thissecnum{0}% - \def\thissubsecnum{0}% - }% - \def\numsecentry##1##2##3##4{% - \advancenumber{chap\thischapnum}% - \def\thissecnum{##2}% - \def\thissubsecnum{0}% - }% - \def\numsubsecentry##1##2##3##4{% - \advancenumber{sec\thissecnum}% - \def\thissubsecnum{##2}% - }% - \def\numsubsubsecentry##1##2##3##4{% - \advancenumber{subsec\thissubsecnum}% - }% - \def\thischapnum{0}% - \def\thissecnum{0}% - \def\thissubsecnum{0}% - % - % use \def rather than \let here because we redefine \chapentry et - % al. a second time, below. - \def\appentry{\numchapentry}% - \def\appsecentry{\numsecentry}% - \def\appsubsecentry{\numsubsecentry}% - \def\appsubsubsecentry{\numsubsubsecentry}% - \def\unnchapentry{\numchapentry}% - \def\unnsecentry{\numsecentry}% - \def\unnsubsecentry{\numsubsecentry}% - \def\unnsubsubsecentry{\numsubsubsecentry}% - \readdatafile{toc}% - % - % Read toc second time, this time actually producing the outlines. - % The `-' means take the \expnumber as the absolute number of - % subentries, which we calculated on our first read of the .toc above. - % - % We use the node names as the destinations. - \def\numchapentry##1##2##3##4{% - \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}% - \def\numsecentry##1##2##3##4{% - \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}% - \def\numsubsecentry##1##2##3##4{% - \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}% - \def\numsubsubsecentry##1##2##3##4{% count is always zero - \dopdfoutline{##1}{}{##3}{##4}}% - % - % PDF outlines are displayed using system fonts, instead of - % document fonts. Therefore we cannot use special characters, - % since the encoding is unknown. For example, the eogonek from - % Latin 2 (0xea) gets translated to a | character. Info from - % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100. - % - % xx to do this right, we have to translate 8-bit characters to - % their "best" equivalent, based on the @documentencoding. Right - % now, I guess we'll just let the pdf reader have its way. - \indexnofonts - \setupdatafile - \catcode`\\=\active \otherbackslash - \input \jobname.toc - \endgroup - } - % - \def\skipspaces#1{\def\PP{#1}\def\D{|}% - \ifx\PP\D\let\nextsp\relax - \else\let\nextsp\skipspaces - \ifx\p\space\else\addtokens{\filename}{\PP}% - \advance\filenamelength by 1 - \fi - \fi - \nextsp} - \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax} - \ifnum\pdftexversion < 14 - \let \startlink \pdfannotlink - \else - \let \startlink \pdfstartlink - \fi - % make a live url in pdf output. - \def\pdfurl#1{% - \begingroup - % it seems we really need yet another set of dummies; have not - % tried to figure out what each command should do in the context - % of @url. for now, just make @/ a no-op, that's the only one - % people have actually reported a problem with. - % - \normalturnoffactive - \def\@{@}% - \let\/=\empty - \makevalueexpandable - \leavevmode\Red - \startlink attr{/Border [0 0 0]}% - user{/Subtype /Link /A << /S /URI /URI (#1) >>}% - \endgroup} - \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} - \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} - \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} - \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}} - \def\maketoks{% - \expandafter\poptoks\the\toksA|ENDTOKS|\relax - \ifx\first0\adn0 - \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3 - \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6 - \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9 - \else - \ifnum0=\countA\else\makelink\fi - \ifx\first.\let\next=\done\else - \let\next=\maketoks - \addtokens{\toksB}{\the\toksD} - \ifx\first,\addtokens{\toksB}{\space}\fi - \fi - \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi - \next} - \def\makelink{\addtokens{\toksB}% - {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0} - \def\pdflink#1{% - \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}} - \linkcolor #1\endlink} - \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} -\else - \let\pdfmkdest = \gobble - \let\pdfurl = \gobble - \let\endlink = \relax - \let\linkcolor = \relax - \let\pdfmakeoutlines = \relax -\fi % \ifx\pdfoutput - - -\message{fonts,} - -% Change the current font style to #1, remembering it in \curfontstyle. -% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in -% italics, not bold italics. -% -\def\setfontstyle#1{% - \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd. - \csname ten#1\endcsname % change the current font -} - -% Select #1 fonts with the current style. -% -\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname} - -\def\rm{\fam=0 \setfontstyle{rm}} -\def\it{\fam=\itfam \setfontstyle{it}} -\def\sl{\fam=\slfam \setfontstyle{sl}} -\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} -\def\tt{\fam=\ttfam \setfontstyle{tt}} - -% Texinfo sort of supports the sans serif font style, which plain TeX does not. -% So we set up a \sf. -\newfam\sffam -\def\sf{\fam=\sffam \setfontstyle{sf}} -\let\li = \sf % Sometimes we call it \li, not \sf. - -% We don't need math for this font style. -\def\ttsl{\setfontstyle{ttsl}} - - -% Default leading. -\newdimen\textleading \textleading = 13.2pt - -% Set the baselineskip to #1, and the lineskip and strut size -% correspondingly. There is no deep meaning behind these magic numbers -% used as factors; they just match (closely enough) what Knuth defined. -% -\def\lineskipfactor{.08333} -\def\strutheightpercent{.70833} -\def\strutdepthpercent {.29167} -% -\def\setleading#1{% - \normalbaselineskip = #1\relax - \normallineskip = \lineskipfactor\normalbaselineskip - \normalbaselines - \setbox\strutbox =\hbox{% - \vrule width0pt height\strutheightpercent\baselineskip - depth \strutdepthpercent \baselineskip - }% -} - - -% Set the font macro #1 to the font named #2, adding on the -% specified font prefix (normally `cm'). -% #3 is the font's design size, #4 is a scale factor -\def\setfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4} - - -% Use cm as the default font prefix. -% To specify the font prefix, you must define \fontprefix -% before you read in texinfo.tex. -\ifx\fontprefix\undefined -\def\fontprefix{cm} -\fi -% Support font families that don't use the same naming scheme as CM. -\def\rmshape{r} -\def\rmbshape{bx} %where the normal face is bold -\def\bfshape{b} -\def\bxshape{bx} -\def\ttshape{tt} -\def\ttbshape{tt} -\def\ttslshape{sltt} -\def\itshape{ti} -\def\itbshape{bxti} -\def\slshape{sl} -\def\slbshape{bxsl} -\def\sfshape{ss} -\def\sfbshape{ss} -\def\scshape{csc} -\def\scbshape{csc} - -% Definitions for a main text size of 11pt. This is the default in -% Texinfo. -% -\def\definetextfontsizexi{ -% Text fonts (11.2pt, magstep1). -\def\textnominalsize{11pt} -\edef\mainmagstep{\magstephalf} -\setfont\textrm\rmshape{10}{\mainmagstep} -\setfont\texttt\ttshape{10}{\mainmagstep} -\setfont\textbf\bfshape{10}{\mainmagstep} -\setfont\textit\itshape{10}{\mainmagstep} -\setfont\textsl\slshape{10}{\mainmagstep} -\setfont\textsf\sfshape{10}{\mainmagstep} -\setfont\textsc\scshape{10}{\mainmagstep} -\setfont\textttsl\ttslshape{10}{\mainmagstep} -\font\texti=cmmi10 scaled \mainmagstep -\font\textsy=cmsy10 scaled \mainmagstep - -% A few fonts for @defun names and args. -\setfont\defbf\bfshape{10}{\magstep1} -\setfont\deftt\ttshape{10}{\magstep1} -\setfont\defttsl\ttslshape{10}{\magstep1} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} - -% Fonts for indices, footnotes, small examples (9pt). -\def\smallnominalsize{9pt} -\setfont\smallrm\rmshape{9}{1000} -\setfont\smalltt\ttshape{9}{1000} -\setfont\smallbf\bfshape{10}{900} -\setfont\smallit\itshape{9}{1000} -\setfont\smallsl\slshape{9}{1000} -\setfont\smallsf\sfshape{9}{1000} -\setfont\smallsc\scshape{10}{900} -\setfont\smallttsl\ttslshape{10}{900} -\font\smalli=cmmi9 -\font\smallsy=cmsy9 - -% Fonts for small examples (8pt). -\def\smallernominalsize{8pt} -\setfont\smallerrm\rmshape{8}{1000} -\setfont\smallertt\ttshape{8}{1000} -\setfont\smallerbf\bfshape{10}{800} -\setfont\smallerit\itshape{8}{1000} -\setfont\smallersl\slshape{8}{1000} -\setfont\smallersf\sfshape{8}{1000} -\setfont\smallersc\scshape{10}{800} -\setfont\smallerttsl\ttslshape{10}{800} -\font\smalleri=cmmi8 -\font\smallersy=cmsy8 - -% Fonts for title page (20.4pt): -\def\titlenominalsize{20pt} -\setfont\titlerm\rmbshape{12}{\magstep3} -\setfont\titleit\itbshape{10}{\magstep4} -\setfont\titlesl\slbshape{10}{\magstep4} -\setfont\titlett\ttbshape{12}{\magstep3} -\setfont\titlettsl\ttslshape{10}{\magstep4} -\setfont\titlesf\sfbshape{17}{\magstep1} -\let\titlebf=\titlerm -\setfont\titlesc\scbshape{10}{\magstep4} -\font\titlei=cmmi12 scaled \magstep3 -\font\titlesy=cmsy10 scaled \magstep4 -\def\authorrm{\secrm} -\def\authortt{\sectt} - -% Chapter (and unnumbered) fonts (17.28pt). -\def\chapnominalsize{17pt} -\setfont\chaprm\rmbshape{12}{\magstep2} -\setfont\chapit\itbshape{10}{\magstep3} -\setfont\chapsl\slbshape{10}{\magstep3} -\setfont\chaptt\ttbshape{12}{\magstep2} -\setfont\chapttsl\ttslshape{10}{\magstep3} -\setfont\chapsf\sfbshape{17}{1000} -\let\chapbf=\chaprm -\setfont\chapsc\scbshape{10}{\magstep3} -\font\chapi=cmmi12 scaled \magstep2 -\font\chapsy=cmsy10 scaled \magstep3 - -% Section fonts (14.4pt). -\def\secnominalsize{14pt} -\setfont\secrm\rmbshape{12}{\magstep1} -\setfont\secit\itbshape{10}{\magstep2} -\setfont\secsl\slbshape{10}{\magstep2} -\setfont\sectt\ttbshape{12}{\magstep1} -\setfont\secttsl\ttslshape{10}{\magstep2} -\setfont\secsf\sfbshape{12}{\magstep1} -\let\secbf\secrm -\setfont\secsc\scbshape{10}{\magstep2} -\font\seci=cmmi12 scaled \magstep1 -\font\secsy=cmsy10 scaled \magstep2 - -% Subsection fonts (13.15pt). -\def\ssecnominalsize{13pt} -\setfont\ssecrm\rmbshape{12}{\magstephalf} -\setfont\ssecit\itbshape{10}{1315} -\setfont\ssecsl\slbshape{10}{1315} -\setfont\ssectt\ttbshape{12}{\magstephalf} -\setfont\ssecttsl\ttslshape{10}{1315} -\setfont\ssecsf\sfbshape{12}{\magstephalf} -\let\ssecbf\ssecrm -\setfont\ssecsc\scbshape{10}{1315} -\font\sseci=cmmi12 scaled \magstephalf -\font\ssecsy=cmsy10 scaled 1315 - -% Reduced fonts for @acro in text (10pt). -\def\reducednominalsize{10pt} -\setfont\reducedrm\rmshape{10}{1000} -\setfont\reducedtt\ttshape{10}{1000} -\setfont\reducedbf\bfshape{10}{1000} -\setfont\reducedit\itshape{10}{1000} -\setfont\reducedsl\slshape{10}{1000} -\setfont\reducedsf\sfshape{10}{1000} -\setfont\reducedsc\scshape{10}{1000} -\setfont\reducedttsl\ttslshape{10}{1000} -\font\reducedi=cmmi10 -\font\reducedsy=cmsy10 - -% reset the current fonts -\textfonts -\rm -} % end of 11pt text font size definitions - - -% Definitions to make the main text be 10pt Computer Modern, with -% section, chapter, etc., sizes following suit. This is for the GNU -% Press printing of the Emacs 22 manual. Maybe other manuals in the -% future. Used with @smallbook, which sets the leading to 12pt. -% -\def\definetextfontsizex{% -% Text fonts (10pt). -\def\textnominalsize{10pt} -\edef\mainmagstep{1000} -\setfont\textrm\rmshape{10}{\mainmagstep} -\setfont\texttt\ttshape{10}{\mainmagstep} -\setfont\textbf\bfshape{10}{\mainmagstep} -\setfont\textit\itshape{10}{\mainmagstep} -\setfont\textsl\slshape{10}{\mainmagstep} -\setfont\textsf\sfshape{10}{\mainmagstep} -\setfont\textsc\scshape{10}{\mainmagstep} -\setfont\textttsl\ttslshape{10}{\mainmagstep} -\font\texti=cmmi10 scaled \mainmagstep -\font\textsy=cmsy10 scaled \mainmagstep - -% A few fonts for @defun names and args. -\setfont\defbf\bfshape{10}{\magstephalf} -\setfont\deftt\ttshape{10}{\magstephalf} -\setfont\defttsl\ttslshape{10}{\magstephalf} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} - -% Fonts for indices, footnotes, small examples (9pt). -\def\smallnominalsize{9pt} -\setfont\smallrm\rmshape{9}{1000} -\setfont\smalltt\ttshape{9}{1000} -\setfont\smallbf\bfshape{10}{900} -\setfont\smallit\itshape{9}{1000} -\setfont\smallsl\slshape{9}{1000} -\setfont\smallsf\sfshape{9}{1000} -\setfont\smallsc\scshape{10}{900} -\setfont\smallttsl\ttslshape{10}{900} -\font\smalli=cmmi9 -\font\smallsy=cmsy9 - -% Fonts for small examples (8pt). -\def\smallernominalsize{8pt} -\setfont\smallerrm\rmshape{8}{1000} -\setfont\smallertt\ttshape{8}{1000} -\setfont\smallerbf\bfshape{10}{800} -\setfont\smallerit\itshape{8}{1000} -\setfont\smallersl\slshape{8}{1000} -\setfont\smallersf\sfshape{8}{1000} -\setfont\smallersc\scshape{10}{800} -\setfont\smallerttsl\ttslshape{10}{800} -\font\smalleri=cmmi8 -\font\smallersy=cmsy8 - -% Fonts for title page (20.4pt): -\def\titlenominalsize{20pt} -\setfont\titlerm\rmbshape{12}{\magstep3} -\setfont\titleit\itbshape{10}{\magstep4} -\setfont\titlesl\slbshape{10}{\magstep4} -\setfont\titlett\ttbshape{12}{\magstep3} -\setfont\titlettsl\ttslshape{10}{\magstep4} -\setfont\titlesf\sfbshape{17}{\magstep1} -\let\titlebf=\titlerm -\setfont\titlesc\scbshape{10}{\magstep4} -\font\titlei=cmmi12 scaled \magstep3 -\font\titlesy=cmsy10 scaled \magstep4 -\def\authorrm{\secrm} -\def\authortt{\sectt} - -% Chapter fonts (14.4pt). -\def\chapnominalsize{14pt} -\setfont\chaprm\rmbshape{12}{\magstep1} -\setfont\chapit\itbshape{10}{\magstep2} -\setfont\chapsl\slbshape{10}{\magstep2} -\setfont\chaptt\ttbshape{12}{\magstep1} -\setfont\chapttsl\ttslshape{10}{\magstep2} -\setfont\chapsf\sfbshape{12}{\magstep1} -\let\chapbf\chaprm -\setfont\chapsc\scbshape{10}{\magstep2} -\font\chapi=cmmi12 scaled \magstep1 -\font\chapsy=cmsy10 scaled \magstep2 - -% Section fonts (12pt). -\def\secnominalsize{12pt} -\setfont\secrm\rmbshape{12}{1000} -\setfont\secit\itbshape{10}{\magstep1} -\setfont\secsl\slbshape{10}{\magstep1} -\setfont\sectt\ttbshape{12}{1000} -\setfont\secttsl\ttslshape{10}{\magstep1} -\setfont\secsf\sfbshape{12}{1000} -\let\secbf\secrm -\setfont\secsc\scbshape{10}{\magstep1} -\font\seci=cmmi12 -\font\secsy=cmsy10 scaled \magstep1 - -% Subsection fonts (10pt). -\def\ssecnominalsize{10pt} -\setfont\ssecrm\rmbshape{10}{1000} -\setfont\ssecit\itbshape{10}{1000} -\setfont\ssecsl\slbshape{10}{1000} -\setfont\ssectt\ttbshape{10}{1000} -\setfont\ssecttsl\ttslshape{10}{1000} -\setfont\ssecsf\sfbshape{10}{1000} -\let\ssecbf\ssecrm -\setfont\ssecsc\scbshape{10}{1000} -\font\sseci=cmmi10 -\font\ssecsy=cmsy10 - -% Reduced fonts for @acro in text (9pt). -\def\reducednominalsize{9pt} -\setfont\reducedrm\rmshape{9}{1000} -\setfont\reducedtt\ttshape{9}{1000} -\setfont\reducedbf\bfshape{10}{900} -\setfont\reducedit\itshape{9}{1000} -\setfont\reducedsl\slshape{9}{1000} -\setfont\reducedsf\sfshape{9}{1000} -\setfont\reducedsc\scshape{10}{900} -\setfont\reducedttsl\ttslshape{10}{900} -\font\reducedi=cmmi9 -\font\reducedsy=cmsy9 - -% reduce space between paragraphs -\divide\parskip by 2 - -% reset the current fonts -\textfonts -\rm -} % end of 10pt text font size definitions - - -% We provide the user-level command -% @fonttextsize 10 -% (or 11) to redefine the text font size. pt is assumed. -% -\def\xword{10} -\def\xiword{11} -% -\parseargdef\fonttextsize{% - \def\textsizearg{#1}% - \wlog{doing @fonttextsize \textsizearg}% - % - % Set \globaldefs so that documents can use this inside @tex, since - % makeinfo 4.8 does not support it, but we need it nonetheless. - % - \begingroup \globaldefs=1 - \ifx\textsizearg\xword \definetextfontsizex - \else \ifx\textsizearg\xiword \definetextfontsizexi - \else - \errhelp=\EMsimple - \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'} - \fi\fi - \endgroup -} - - -% In order for the font changes to affect most math symbols and letters, -% we have to define the \textfont of the standard families. Since -% texinfo doesn't allow for producing subscripts and superscripts except -% in the main text, we don't bother to reset \scriptfont and -% \scriptscriptfont (which would also require loading a lot more fonts). -% -\def\resetmathfonts{% - \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy - \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf - \textfont\ttfam=\tentt \textfont\sffam=\tensf -} - -% The font-changing commands redefine the meanings of \tenSTYLE, instead -% of just \STYLE. We do this because \STYLE needs to also set the -% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire -% \tenSTYLE to set the current font. -% -% Each font-changing command also sets the names \lsize (one size lower) -% and \lllsize (three sizes lower). These relative commands are used in -% the LaTeX logo and acronyms. -% -% This all needs generalizing, badly. -% -\def\textfonts{% - \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl - \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc - \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy - \let\tenttsl=\textttsl - \def\curfontsize{text}% - \def\lsize{reduced}\def\lllsize{smaller}% - \resetmathfonts \setleading{\textleading}} -\def\titlefonts{% - \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl - \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc - \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy - \let\tenttsl=\titlettsl - \def\curfontsize{title}% - \def\lsize{chap}\def\lllsize{subsec}% - \resetmathfonts \setleading{25pt}} -\def\titlefont#1{{\titlefonts\rm #1}} -\def\chapfonts{% - \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl - \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc - \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy - \let\tenttsl=\chapttsl - \def\curfontsize{chap}% - \def\lsize{sec}\def\lllsize{text}% - \resetmathfonts \setleading{19pt}} -\def\secfonts{% - \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl - \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc - \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy - \let\tenttsl=\secttsl - \def\curfontsize{sec}% - \def\lsize{subsec}\def\lllsize{reduced}% - \resetmathfonts \setleading{16pt}} -\def\subsecfonts{% - \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl - \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc - \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy - \let\tenttsl=\ssecttsl - \def\curfontsize{ssec}% - \def\lsize{text}\def\lllsize{small}% - \resetmathfonts \setleading{15pt}} -\let\subsubsecfonts = \subsecfonts -\def\reducedfonts{% - \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl - \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc - \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy - \let\tenttsl=\reducedttsl - \def\curfontsize{reduced}% - \def\lsize{small}\def\lllsize{smaller}% - \resetmathfonts \setleading{10.5pt}} -\def\smallfonts{% - \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl - \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc - \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy - \let\tenttsl=\smallttsl - \def\curfontsize{small}% - \def\lsize{smaller}\def\lllsize{smaller}% - \resetmathfonts \setleading{10.5pt}} -\def\smallerfonts{% - \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl - \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc - \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy - \let\tenttsl=\smallerttsl - \def\curfontsize{smaller}% - \def\lsize{smaller}\def\lllsize{smaller}% - \resetmathfonts \setleading{9.5pt}} - -% Set the fonts to use with the @small... environments. -\let\smallexamplefonts = \smallfonts - -% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample -% can fit this many characters: -% 8.5x11=86 smallbook=72 a4=90 a5=69 -% If we use \scriptfonts (8pt), then we can fit this many characters: -% 8.5x11=90+ smallbook=80 a4=90+ a5=77 -% For me, subjectively, the few extra characters that fit aren't worth -% the additional smallness of 8pt. So I'm making the default 9pt. -% -% By the way, for comparison, here's what fits with @example (10pt): -% 8.5x11=71 smallbook=60 a4=75 a5=58 -% -% I wish the USA used A4 paper. -% --karl, 24jan03. - - -% Set up the default fonts, so we can use them for creating boxes. -% -\definetextfontsizexi - -% Define these so they can be easily changed for other fonts. -\def\angleleft{$\langle$} -\def\angleright{$\rangle$} - -% Count depth in font-changes, for error checks -\newcount\fontdepth \fontdepth=0 - -% Fonts for short table of contents. -\setfont\shortcontrm\rmshape{12}{1000} -\setfont\shortcontbf\bfshape{10}{\magstep1} % no cmb12 -\setfont\shortcontsl\slshape{12}{1000} -\setfont\shortconttt\ttshape{12}{1000} - -%% Add scribe-like font environments, plus @l for inline lisp (usually sans -%% serif) and @ii for TeX italic - -% \smartitalic{ARG} outputs arg in italics, followed by an italic correction -% unless the following character is such as not to need one. -\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else - \ptexslash\fi\fi\fi} -\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx} -\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx} - -% like \smartslanted except unconditionally uses \ttsl. -% @var is set to this for defun arguments. -\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx} - -% like \smartslanted except unconditionally use \sl. We never want -% ttsl for book titles, do we? -\def\cite#1{{\sl #1}\futurelet\next\smartitalicx} - -\let\i=\smartitalic -\let\slanted=\smartslanted -\let\var=\smartslanted -\let\dfn=\smartslanted -\let\emph=\smartitalic - -% @b, explicit bold. -\def\b#1{{\bf #1}} -\let\strong=\b - -% @sansserif, explicit sans. -\def\sansserif#1{{\sf #1}} - -% We can't just use \exhyphenpenalty, because that only has effect at -% the end of a paragraph. Restore normal hyphenation at the end of the -% group within which \nohyphenation is presumably called. -% -\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} -\def\restorehyphenation{\hyphenchar\font = `- } - -% Set sfcode to normal for the chars that usually have another value. -% Can't use plain's \frenchspacing because it uses the `\x notation, and -% sometimes \x has an active definition that messes things up. -% -\catcode`@=11 - \def\plainfrenchspacing{% - \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m - \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m - \def\endofsentencespacefactor{1000}% for @. and friends - } - \def\plainnonfrenchspacing{% - \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000 - \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250 - \def\endofsentencespacefactor{3000}% for @. and friends - } -\catcode`@=\other -\def\endofsentencespacefactor{3000}% default - -\def\t#1{% - {\tt \rawbackslash \plainfrenchspacing #1}% - \null -} -\def\samp#1{`\tclose{#1}'\null} -\setfont\keyrm\rmshape{8}{1000} -\font\keysy=cmsy9 -\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{% - \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% - \vbox{\hrule\kern-0.4pt - \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% - \kern-0.4pt\hrule}% - \kern-.06em\raise0.4pt\hbox{\angleright}}}} -% The old definition, with no lozenge: -%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} -\def\ctrl #1{{\tt \rawbackslash \hat}#1} - -% @file, @option are the same as @samp. -\let\file=\samp -\let\option=\samp - -% @code is a modification of @t, -% which makes spaces the same size as normal in the surrounding text. -\def\tclose#1{% - {% - % Change normal interword space to be same as for the current font. - \spaceskip = \fontdimen2\font - % - % Switch to typewriter. - \tt - % - % But `\ ' produces the large typewriter interword space. - \def\ {{\spaceskip = 0pt{} }}% - % - % Turn off hyphenation. - \nohyphenation - % - \rawbackslash - \plainfrenchspacing - #1% - }% - \null -} - -% We *must* turn on hyphenation at `-' and `_' in @code. -% Otherwise, it is too hard to avoid overfull hboxes -% in the Emacs manual, the Library manual, etc. - -% Unfortunately, TeX uses one parameter (\hyphenchar) to control -% both hyphenation at - and hyphenation within words. -% We must therefore turn them both off (\tclose does that) -% and arrange explicitly to hyphenate at a dash. -% -- rms. -{ - \catcode`\-=\active \catcode`\_=\active - \catcode`\'=\active \catcode`\`=\active - % - \global\def\code{\begingroup - \catcode\rquoteChar=\active \catcode\lquoteChar=\active - \let'\codequoteright \let`\codequoteleft - % - \catcode\dashChar=\active \catcode\underChar=\active - \ifallowcodebreaks - \let-\codedash - \let_\codeunder - \else - \let-\realdash - \let_\realunder - \fi - \codex - } -} - -\def\realdash{-} -\def\codedash{-\discretionary{}{}{}} -\def\codeunder{% - % this is all so @math{@code{var_name}+1} can work. In math mode, _ - % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) - % will therefore expand the active definition of _, which is us - % (inside @code that is), therefore an endless loop. - \ifusingtt{\ifmmode - \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_. - \else\normalunderscore \fi - \discretionary{}{}{}}% - {\_}% -} -\def\codex #1{\tclose{#1}\endgroup} - -% An additional complication: the above will allow breaks after, e.g., -% each of the four underscores in __typeof__. This is undesirable in -% some manuals, especially if they don't have long identifiers in -% general. @allowcodebreaks provides a way to control this. -% -\newif\ifallowcodebreaks \allowcodebreakstrue - -\def\keywordtrue{true} -\def\keywordfalse{false} - -\parseargdef\allowcodebreaks{% - \def\txiarg{#1}% - \ifx\txiarg\keywordtrue - \allowcodebreakstrue - \else\ifx\txiarg\keywordfalse - \allowcodebreaksfalse - \else - \errhelp = \EMsimple - \errmessage{Unknown @allowcodebreaks option `\txiarg'}% - \fi\fi -} - -% @kbd is like @code, except that if the argument is just one @key command, -% then @kbd has no effect. - -% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), -% `example' (@kbd uses ttsl only inside of @example and friends), -% or `code' (@kbd uses normal tty font always). -\parseargdef\kbdinputstyle{% - \def\txiarg{#1}% - \ifx\txiarg\worddistinct - \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% - \else\ifx\txiarg\wordexample - \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% - \else\ifx\txiarg\wordcode - \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% - \else - \errhelp = \EMsimple - \errmessage{Unknown @kbdinputstyle option `\txiarg'}% - \fi\fi\fi -} -\def\worddistinct{distinct} -\def\wordexample{example} -\def\wordcode{code} - -% Default is `distinct.' -\kbdinputstyle distinct - -\def\xkey{\key} -\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% -\ifx\one\xkey\ifx\threex\three \key{#2}% -\else{\tclose{\kbdfont\look}}\fi -\else{\tclose{\kbdfont\look}}\fi} - -% For @indicateurl, @env, @command quotes seem unnecessary, so use \code. -\let\indicateurl=\code -\let\env=\code -\let\command=\code - -% @uref (abbreviation for `urlref') takes an optional (comma-separated) -% second argument specifying the text to display and an optional third -% arg as text to display instead of (rather than in addition to) the url -% itself. First (mandatory) arg is the url. Perhaps eventually put in -% a hypertex \special here. -% -\def\uref#1{\douref #1,,,\finish} -\def\douref#1,#2,#3,#4\finish{\begingroup - \unsepspaces - \pdfurl{#1}% - \setbox0 = \hbox{\ignorespaces #3}% - \ifdim\wd0 > 0pt - \unhbox0 % third arg given, show only that - \else - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0 > 0pt - \ifpdf - \unhbox0 % PDF: 2nd arg given, show only it - \else - \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url - \fi - \else - \code{#1}% only url given, so show it - \fi - \fi - \endlink -\endgroup} - -% @url synonym for @uref, since that's how everyone uses it. -% -\let\url=\uref - -% rms does not like angle brackets --karl, 17may97. -% So now @email is just like @uref, unless we are pdf. -% -%\def\email#1{\angleleft{\tt #1}\angleright} -\ifpdf - \def\email#1{\doemail#1,,\finish} - \def\doemail#1,#2,#3\finish{\begingroup - \unsepspaces - \pdfurl{mailto:#1}% - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi - \endlink - \endgroup} -\else - \let\email=\uref -\fi - -% Check if we are currently using a typewriter font. Since all the -% Computer Modern typewriter fonts have zero interword stretch (and -% shrink), and it is reasonable to expect all typewriter fonts to have -% this property, we can check that font parameter. -% -\def\ifmonospace{\ifdim\fontdimen3\font=0pt } - -% Typeset a dimension, e.g., `in' or `pt'. The only reason for the -% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt. -% -\def\dmn#1{\thinspace #1} - -\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} - -% @l was never documented to mean ``switch to the Lisp font'', -% and it is not used as such in any manual I can find. We need it for -% Polish suppressed-l. --karl, 22sep96. -%\def\l#1{{\li #1}\null} - -% Explicit font changes: @r, @sc, undocumented @ii. -\def\r#1{{\rm #1}} % roman font -\def\sc#1{{\smallcaps#1}} % smallcaps font -\def\ii#1{{\it #1}} % italic font - -% @acronym for "FBI", "NATO", and the like. -% We print this one point size smaller, since it's intended for -% all-uppercase. -% -\def\acronym#1{\doacronym #1,,\finish} -\def\doacronym#1,#2,#3\finish{% - {\selectfonts\lsize #1}% - \def\temp{#2}% - \ifx\temp\empty \else - \space ({\unsepspaces \ignorespaces \temp \unskip})% - \fi -} - -% @abbr for "Comput. J." and the like. -% No font change, but don't do end-of-sentence spacing. -% -\def\abbr#1{\doabbr #1,,\finish} -\def\doabbr#1,#2,#3\finish{% - {\plainfrenchspacing #1}% - \def\temp{#2}% - \ifx\temp\empty \else - \space ({\unsepspaces \ignorespaces \temp \unskip})% - \fi -} - -% @pounds{} is a sterling sign, which Knuth put in the CM italic font. -% -\def\pounds{{\it\$}} - -% @euro{} comes from a separate font, depending on the current style. -% We use the free feym* fonts from the eurosym package by Henrik -% Theiling, which support regular, slanted, bold and bold slanted (and -% "outlined" (blackboard board, sort of) versions, which we don't need). -% It is available from http://www.ctan.org/tex-archive/fonts/eurosym. -% -% Although only regular is the truly official Euro symbol, we ignore -% that. The Euro is designed to be slightly taller than the regular -% font height. -% -% feymr - regular -% feymo - slanted -% feybr - bold -% feybo - bold slanted -% -% There is no good (free) typewriter version, to my knowledge. -% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide. -% Hmm. -% -% Also doesn't work in math. Do we need to do math with euro symbols? -% Hope not. -% -% -\def\euro{{\eurofont e}} -\def\eurofont{% - % We set the font at each command, rather than predefining it in - % \textfonts and the other font-switching commands, so that - % installations which never need the symbol don't have to have the - % font installed. - % - % There is only one designed size (nominal 10pt), so we always scale - % that to the current nominal size. - % - % By the way, simply using "at 1em" works for cmr10 and the like, but - % does not work for cmbx10 and other extended/shrunken fonts. - % - \def\eurosize{\csname\curfontsize nominalsize\endcsname}% - % - \ifx\curfontstyle\bfstylename - % bold: - \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize - \else - % regular: - \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize - \fi - \thiseurofont -} - -% @registeredsymbol - R in a circle. The font for the R should really -% be smaller yet, but lllsize is the best we can do for now. -% Adapted from the plain.tex definition of \copyright. -% -\def\registeredsymbol{% - $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}% - \hfil\crcr\Orb}}% - }$% -} - -% @textdegree - the normal degrees sign. -% -\def\textdegree{$^\circ$} - -% Laurent Siebenmann reports \Orb undefined with: -% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38 -% so we'll define it if necessary. -% -\ifx\Orb\undefined -\def\Orb{\mathhexbox20D} -\fi - - -\message{page headings,} - -\newskip\titlepagetopglue \titlepagetopglue = 1.5in -\newskip\titlepagebottomglue \titlepagebottomglue = 2pc - -% First the title page. Must do @settitle before @titlepage. -\newif\ifseenauthor -\newif\iffinishedtitlepage - -% Do an implicit @contents or @shortcontents after @end titlepage if the -% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage. -% -\newif\ifsetcontentsaftertitlepage - \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue -\newif\ifsetshortcontentsaftertitlepage - \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue - -\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% - \endgroup\page\hbox{}\page} - -\envdef\titlepage{% - % Open one extra group, as we want to close it in the middle of \Etitlepage. - \begingroup - \parindent=0pt \textfonts - % Leave some space at the very top of the page. - \vglue\titlepagetopglue - % No rule at page bottom unless we print one at the top with @title. - \finishedtitlepagetrue - % - % Most title ``pages'' are actually two pages long, with space - % at the top of the second. We don't want the ragged left on the second. - \let\oldpage = \page - \def\page{% - \iffinishedtitlepage\else - \finishtitlepage - \fi - \let\page = \oldpage - \page - \null - }% -} - -\def\Etitlepage{% - \iffinishedtitlepage\else - \finishtitlepage - \fi - % It is important to do the page break before ending the group, - % because the headline and footline are only empty inside the group. - % If we use the new definition of \page, we always get a blank page - % after the title page, which we certainly don't want. - \oldpage - \endgroup - % - % Need this before the \...aftertitlepage checks so that if they are - % in effect the toc pages will come out with page numbers. - \HEADINGSon - % - % If they want short, they certainly want long too. - \ifsetshortcontentsaftertitlepage - \shortcontents - \contents - \global\let\shortcontents = \relax - \global\let\contents = \relax - \fi - % - \ifsetcontentsaftertitlepage - \contents - \global\let\contents = \relax - \global\let\shortcontents = \relax - \fi -} - -\def\finishtitlepage{% - \vskip4pt \hrule height 2pt width \hsize - \vskip\titlepagebottomglue - \finishedtitlepagetrue -} - -%%% Macros to be used within @titlepage: - -\let\subtitlerm=\tenrm -\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines} - -\def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines - \let\tt=\authortt} - -\parseargdef\title{% - \checkenv\titlepage - \leftline{\titlefonts\rm #1} - % print a rule at the page bottom also. - \finishedtitlepagefalse - \vskip4pt \hrule height 4pt width \hsize \vskip4pt -} - -\parseargdef\subtitle{% - \checkenv\titlepage - {\subtitlefont \rightline{#1}}% -} - -% @author should come last, but may come many times. -% It can also be used inside @quotation. -% -\parseargdef\author{% - \def\temp{\quotation}% - \ifx\thisenv\temp - \def\quotationauthor{#1}% printed in \Equotation. - \else - \checkenv\titlepage - \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi - {\authorfont \leftline{#1}}% - \fi -} - - -%%% Set up page headings and footings. - -\let\thispage=\folio - -\newtoks\evenheadline % headline on even pages -\newtoks\oddheadline % headline on odd pages -\newtoks\evenfootline % footline on even pages -\newtoks\oddfootline % footline on odd pages - -% Now make TeX use those variables -\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline - \else \the\evenheadline \fi}} -\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline - \else \the\evenfootline \fi}\HEADINGShook} -\let\HEADINGShook=\relax - -% Commands to set those variables. -% For example, this is what @headings on does -% @evenheading @thistitle|@thispage|@thischapter -% @oddheading @thischapter|@thispage|@thistitle -% @evenfooting @thisfile|| -% @oddfooting ||@thisfile - - -\def\evenheading{\parsearg\evenheadingxxx} -\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish} -\def\evenheadingyyy #1\|#2\|#3\|#4\finish{% -\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\def\oddheading{\parsearg\oddheadingxxx} -\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish} -\def\oddheadingyyy #1\|#2\|#3\|#4\finish{% -\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}% - -\def\evenfooting{\parsearg\evenfootingxxx} -\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish} -\def\evenfootingyyy #1\|#2\|#3\|#4\finish{% -\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\def\oddfooting{\parsearg\oddfootingxxx} -\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish} -\def\oddfootingyyy #1\|#2\|#3\|#4\finish{% - \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}% - % - % Leave some space for the footline. Hopefully ok to assume - % @evenfooting will not be used by itself. - \global\advance\pageheight by -12pt - \global\advance\vsize by -12pt -} - -\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}} - - -% @headings double turns headings on for double-sided printing. -% @headings single turns headings on for single-sided printing. -% @headings off turns them off. -% @headings on same as @headings double, retained for compatibility. -% @headings after turns on double-sided headings after this page. -% @headings doubleafter turns on double-sided headings after this page. -% @headings singleafter turns on single-sided headings after this page. -% By default, they are off at the start of a document, -% and turned `on' after @end titlepage. - -\def\headings #1 {\csname HEADINGS#1\endcsname} - -\def\HEADINGSoff{% -\global\evenheadline={\hfil} \global\evenfootline={\hfil} -\global\oddheadline={\hfil} \global\oddfootline={\hfil}} -\HEADINGSoff -% When we turn headings on, set the page number to 1. -% For double-sided printing, put current file name in lower left corner, -% chapter name on inside top of right hand pages, document -% title on inside top of left hand pages, and page numbers on outside top -% edge of all pages. -\def\HEADINGSdouble{% -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chapoddpage -} -\let\contentsalignmacro = \chappager - -% For single-sided printing, chapter title goes across top left of page, -% page number on top right. -\def\HEADINGSsingle{% -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapter\hfil\folio}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chappager -} -\def\HEADINGSon{\HEADINGSdouble} - -\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} -\let\HEADINGSdoubleafter=\HEADINGSafter -\def\HEADINGSdoublex{% -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chapoddpage -} - -\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} -\def\HEADINGSsinglex{% -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapter\hfil\folio}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chappager -} - -% Subroutines used in generating headings -% This produces Day Month Year style of output. -% Only define if not already defined, in case a txi-??.tex file has set -% up a different format (e.g., txi-cs.tex does this). -\ifx\today\undefined -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} -\fi - -% @settitle line... specifies the title of the document, for headings. -% It generates no output of its own. -\def\thistitle{\putwordNoTitle} -\def\settitle{\parsearg{\gdef\thistitle}} - - -\message{tables,} -% Tables -- @table, @ftable, @vtable, @item(x). - -% default indentation of table text -\newdimen\tableindent \tableindent=.8in -% default indentation of @itemize and @enumerate text -\newdimen\itemindent \itemindent=.3in -% margin between end of table item and start of table text. -\newdimen\itemmargin \itemmargin=.1in - -% used internally for \itemindent minus \itemmargin -\newdimen\itemmax - -% Note @table, @ftable, and @vtable define @item, @itemx, etc., with -% these defs. -% They also define \itemindex -% to index the item name in whatever manner is desired (perhaps none). - -\newif\ifitemxneedsnegativevskip - -\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} - -\def\internalBitem{\smallbreak \parsearg\itemzzz} -\def\internalBitemx{\itemxpar \parsearg\itemzzz} - -\def\itemzzz #1{\begingroup % - \advance\hsize by -\rightskip - \advance\hsize by -\tableindent - \setbox0=\hbox{\itemindicate{#1}}% - \itemindex{#1}% - \nobreak % This prevents a break before @itemx. - % - % If the item text does not fit in the space we have, put it on a line - % by itself, and do not allow a page break either before or after that - % line. We do not start a paragraph here because then if the next - % command is, e.g., @kindex, the whatsit would get put into the - % horizontal list on a line by itself, resulting in extra blank space. - \ifdim \wd0>\itemmax - % - % Make this a paragraph so we get the \parskip glue and wrapping, - % but leave it ragged-right. - \begingroup - \advance\leftskip by-\tableindent - \advance\hsize by\tableindent - \advance\rightskip by0pt plus1fil - \leavevmode\unhbox0\par - \endgroup - % - % We're going to be starting a paragraph, but we don't want the - % \parskip glue -- logically it's part of the @item we just started. - \nobreak \vskip-\parskip - % - % Stop a page break at the \parskip glue coming up. However, if - % what follows is an environment such as @example, there will be no - % \parskip glue; then the negative vskip we just inserted would - % cause the example and the item to crash together. So we use this - % bizarre value of 10001 as a signal to \aboveenvbreak to insert - % \parskip glue after all. Section titles are handled this way also. - % - \penalty 10001 - \endgroup - \itemxneedsnegativevskipfalse - \else - % The item text fits into the space. Start a paragraph, so that the - % following text (if any) will end up on the same line. - \noindent - % Do this with kerns and \unhbox so that if there is a footnote in - % the item text, it can migrate to the main vertical list and - % eventually be printed. - \nobreak\kern-\tableindent - \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0 - \unhbox0 - \nobreak\kern\dimen0 - \endgroup - \itemxneedsnegativevskiptrue - \fi -} - -\def\item{\errmessage{@item while not in a list environment}} -\def\itemx{\errmessage{@itemx while not in a list environment}} - -% @table, @ftable, @vtable. -\envdef\table{% - \let\itemindex\gobble - \tablecheck{table}% -} -\envdef\ftable{% - \def\itemindex ##1{\doind {fn}{\code{##1}}}% - \tablecheck{ftable}% -} -\envdef\vtable{% - \def\itemindex ##1{\doind {vr}{\code{##1}}}% - \tablecheck{vtable}% -} -\def\tablecheck#1{% - \ifnum \the\catcode`\^^M=\active - \endgroup - \errmessage{This command won't work in this context; perhaps the problem is - that we are \inenvironment\thisenv}% - \def\next{\doignore{#1}}% - \else - \let\next\tablex - \fi - \next -} -\def\tablex#1{% - \def\itemindicate{#1}% - \parsearg\tabley -} -\def\tabley#1{% - {% - \makevalueexpandable - \edef\temp{\noexpand\tablez #1\space\space\space}% - \expandafter - }\temp \endtablez -} -\def\tablez #1 #2 #3 #4\endtablez{% - \aboveenvbreak - \ifnum 0#1>0 \advance \leftskip by #1\mil \fi - \ifnum 0#2>0 \tableindent=#2\mil \fi - \ifnum 0#3>0 \advance \rightskip by #3\mil \fi - \itemmax=\tableindent - \advance \itemmax by -\itemmargin - \advance \leftskip by \tableindent - \exdentamount=\tableindent - \parindent = 0pt - \parskip = \smallskipamount - \ifdim \parskip=0pt \parskip=2pt \fi - \let\item = \internalBitem - \let\itemx = \internalBitemx -} -\def\Etable{\endgraf\afterenvbreak} -\let\Eftable\Etable -\let\Evtable\Etable -\let\Eitemize\Etable -\let\Eenumerate\Etable - -% This is the counter used by @enumerate, which is really @itemize - -\newcount \itemno - -\envdef\itemize{\parsearg\doitemize} - -\def\doitemize#1{% - \aboveenvbreak - \itemmax=\itemindent - \advance\itemmax by -\itemmargin - \advance\leftskip by \itemindent - \exdentamount=\itemindent - \parindent=0pt - \parskip=\smallskipamount - \ifdim\parskip=0pt \parskip=2pt \fi - \def\itemcontents{#1}% - % @itemize with no arg is equivalent to @itemize @bullet. - \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi - \let\item=\itemizeitem -} - -% Definition of @item while inside @itemize and @enumerate. -% -\def\itemizeitem{% - \advance\itemno by 1 % for enumerations - {\let\par=\endgraf \smallbreak}% reasonable place to break - {% - % If the document has an @itemize directly after a section title, a - % \nobreak will be last on the list, and \sectionheading will have - % done a \vskip-\parskip. In that case, we don't want to zero - % parskip, or the item text will crash with the heading. On the - % other hand, when there is normal text preceding the item (as there - % usually is), we do want to zero parskip, or there would be too much - % space. In that case, we won't have a \nobreak before. At least - % that's the theory. - \ifnum\lastpenalty<10000 \parskip=0in \fi - \noindent - \hbox to 0pt{\hss \itemcontents \kern\itemmargin}% - \vadjust{\penalty 1200}}% not good to break after first line of item. - \flushcr -} - -% \splitoff TOKENS\endmark defines \first to be the first token in -% TOKENS, and \rest to be the remainder. -% -\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% - -% Allow an optional argument of an uppercase letter, lowercase letter, -% or number, to specify the first label in the enumerated list. No -% argument is the same as `1'. -% -\envparseargdef\enumerate{\enumeratey #1 \endenumeratey} -\def\enumeratey #1 #2\endenumeratey{% - % If we were given no argument, pretend we were given `1'. - \def\thearg{#1}% - \ifx\thearg\empty \def\thearg{1}\fi - % - % Detect if the argument is a single token. If so, it might be a - % letter. Otherwise, the only valid thing it can be is a number. - % (We will always have one token, because of the test we just made. - % This is a good thing, since \splitoff doesn't work given nothing at - % all -- the first parameter is undelimited.) - \expandafter\splitoff\thearg\endmark - \ifx\rest\empty - % Only one token in the argument. It could still be anything. - % A ``lowercase letter'' is one whose \lccode is nonzero. - % An ``uppercase letter'' is one whose \lccode is both nonzero, and - % not equal to itself. - % Otherwise, we assume it's a number. - % - % We need the \relax at the end of the \ifnum lines to stop TeX from - % continuing to look for a <number>. - % - \ifnum\lccode\expandafter`\thearg=0\relax - \numericenumerate % a number (we hope) - \else - % It's a letter. - \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax - \lowercaseenumerate % lowercase letter - \else - \uppercaseenumerate % uppercase letter - \fi - \fi - \else - % Multiple tokens in the argument. We hope it's a number. - \numericenumerate - \fi -} - -% An @enumerate whose labels are integers. The starting integer is -% given in \thearg. -% -\def\numericenumerate{% - \itemno = \thearg - \startenumeration{\the\itemno}% -} - -% The starting (lowercase) letter is in \thearg. -\def\lowercaseenumerate{% - \itemno = \expandafter`\thearg - \startenumeration{% - % Be sure we're not beyond the end of the alphabet. - \ifnum\itemno=0 - \errmessage{No more lowercase letters in @enumerate; get a bigger - alphabet}% - \fi - \char\lccode\itemno - }% -} - -% The starting (uppercase) letter is in \thearg. -\def\uppercaseenumerate{% - \itemno = \expandafter`\thearg - \startenumeration{% - % Be sure we're not beyond the end of the alphabet. - \ifnum\itemno=0 - \errmessage{No more uppercase letters in @enumerate; get a bigger - alphabet} - \fi - \char\uccode\itemno - }% -} - -% Call \doitemize, adding a period to the first argument and supplying the -% common last two arguments. Also subtract one from the initial value in -% \itemno, since @item increments \itemno. -% -\def\startenumeration#1{% - \advance\itemno by -1 - \doitemize{#1.}\flushcr -} - -% @alphaenumerate and @capsenumerate are abbreviations for giving an arg -% to @enumerate. -% -\def\alphaenumerate{\enumerate{a}} -\def\capsenumerate{\enumerate{A}} -\def\Ealphaenumerate{\Eenumerate} -\def\Ecapsenumerate{\Eenumerate} - - -% @multitable macros -% Amy Hendrickson, 8/18/94, 3/6/96 -% -% @multitable ... @end multitable will make as many columns as desired. -% Contents of each column will wrap at width given in preamble. Width -% can be specified either with sample text given in a template line, -% or in percent of \hsize, the current width of text on page. - -% Table can continue over pages but will only break between lines. - -% To make preamble: -% -% Either define widths of columns in terms of percent of \hsize: -% @multitable @columnfractions .25 .3 .45 -% @item ... -% -% Numbers following @columnfractions are the percent of the total -% current hsize to be used for each column. You may use as many -% columns as desired. - - -% Or use a template: -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item ... -% using the widest term desired in each column. - -% Each new table line starts with @item, each subsequent new column -% starts with @tab. Empty columns may be produced by supplying @tab's -% with nothing between them for as many times as empty columns are needed, -% ie, @tab@tab@tab will produce two empty columns. - -% @item, @tab do not need to be on their own lines, but it will not hurt -% if they are. - -% Sample multitable: - -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item first col stuff @tab second col stuff @tab third col -% @item -% first col stuff -% @tab -% second col stuff -% @tab -% third col -% @item first col stuff @tab second col stuff -% @tab Many paragraphs of text may be used in any column. -% -% They will wrap at the width determined by the template. -% @item@tab@tab This will be in third column. -% @end multitable - -% Default dimensions may be reset by user. -% @multitableparskip is vertical space between paragraphs in table. -% @multitableparindent is paragraph indent in table. -% @multitablecolmargin is horizontal space to be left between columns. -% @multitablelinespace is space to leave between table items, baseline -% to baseline. -% 0pt means it depends on current normal line spacing. -% -\newskip\multitableparskip -\newskip\multitableparindent -\newdimen\multitablecolspace -\newskip\multitablelinespace -\multitableparskip=0pt -\multitableparindent=6pt -\multitablecolspace=12pt -\multitablelinespace=0pt - -% Macros used to set up halign preamble: -% -\let\endsetuptable\relax -\def\xendsetuptable{\endsetuptable} -\let\columnfractions\relax -\def\xcolumnfractions{\columnfractions} -\newif\ifsetpercent - -% #1 is the @columnfraction, usually a decimal number like .5, but might -% be just 1. We just use it, whatever it is. -% -\def\pickupwholefraction#1 {% - \global\advance\colcount by 1 - \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}% - \setuptable -} - -\newcount\colcount -\def\setuptable#1{% - \def\firstarg{#1}% - \ifx\firstarg\xendsetuptable - \let\go = \relax - \else - \ifx\firstarg\xcolumnfractions - \global\setpercenttrue - \else - \ifsetpercent - \let\go\pickupwholefraction - \else - \global\advance\colcount by 1 - \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a - % separator; typically that is always in the input, anyway. - \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% - \fi - \fi - \ifx\go\pickupwholefraction - % Put the argument back for the \pickupwholefraction call, so - % we'll always have a period there to be parsed. - \def\go{\pickupwholefraction#1}% - \else - \let\go = \setuptable - \fi% - \fi - \go -} - -% multitable-only commands. -% -% @headitem starts a heading row, which we typeset in bold. -% Assignments have to be global since we are inside the implicit group -% of an alignment entry. Note that \everycr resets \everytab. -\def\headitem{\checkenv\multitable \crcr \global\everytab={\bf}\the\everytab}% -% -% A \tab used to include \hskip1sp. But then the space in a template -% line is not enough. That is bad. So let's go back to just `&' until -% we encounter the problem it was intended to solve again. -% --karl, nathan@acm.org, 20apr99. -\def\tab{\checkenv\multitable &\the\everytab}% - -% @multitable ... @end multitable definitions: -% -\newtoks\everytab % insert after every tab. -% -\envdef\multitable{% - \vskip\parskip - \startsavinginserts - % - % @item within a multitable starts a normal row. - % We use \def instead of \let so that if one of the multitable entries - % contains an @itemize, we don't choke on the \item (seen as \crcr aka - % \endtemplate) expanding \doitemize. - \def\item{\crcr}% - % - \tolerance=9500 - \hbadness=9500 - \setmultitablespacing - \parskip=\multitableparskip - \parindent=\multitableparindent - \overfullrule=0pt - \global\colcount=0 - % - \everycr = {% - \noalign{% - \global\everytab={}% - \global\colcount=0 % Reset the column counter. - % Check for saved footnotes, etc. - \checkinserts - % Keeps underfull box messages off when table breaks over pages. - %\filbreak - % Maybe so, but it also creates really weird page breaks when the - % table breaks over pages. Wouldn't \vfil be better? Wait until the - % problem manifests itself, so it can be fixed for real --karl. - }% - }% - % - \parsearg\domultitable -} -\def\domultitable#1{% - % To parse everything between @multitable and @item: - \setuptable#1 \endsetuptable - % - % This preamble sets up a generic column definition, which will - % be used as many times as user calls for columns. - % \vtop will set a single line and will also let text wrap and - % continue for many paragraphs if desired. - \halign\bgroup &% - \global\advance\colcount by 1 - \multistrut - \vtop{% - % Use the current \colcount to find the correct column width: - \hsize=\expandafter\csname col\the\colcount\endcsname - % - % In order to keep entries from bumping into each other - % we will add a \leftskip of \multitablecolspace to all columns after - % the first one. - % - % If a template has been used, we will add \multitablecolspace - % to the width of each template entry. - % - % If the user has set preamble in terms of percent of \hsize we will - % use that dimension as the width of the column, and the \leftskip - % will keep entries from bumping into each other. Table will start at - % left margin and final column will justify at right margin. - % - % Make sure we don't inherit \rightskip from the outer environment. - \rightskip=0pt - \ifnum\colcount=1 - % The first column will be indented with the surrounding text. - \advance\hsize by\leftskip - \else - \ifsetpercent \else - % If user has not set preamble in terms of percent of \hsize - % we will advance \hsize by \multitablecolspace. - \advance\hsize by \multitablecolspace - \fi - % In either case we will make \leftskip=\multitablecolspace: - \leftskip=\multitablecolspace - \fi - % Ignoring space at the beginning and end avoids an occasional spurious - % blank line, when TeX decides to break the line at the space before the - % box from the multistrut, so the strut ends up on a line by itself. - % For example: - % @multitable @columnfractions .11 .89 - % @item @code{#} - % @tab Legal holiday which is valid in major parts of the whole country. - % Is automatically provided with highlighting sequences respectively - % marking characters. - \noindent\ignorespaces##\unskip\multistrut - }\cr -} -\def\Emultitable{% - \crcr - \egroup % end the \halign - \global\setpercentfalse -} - -\def\setmultitablespacing{% - \def\multistrut{\strut}% just use the standard line spacing - % - % Compute \multitablelinespace (if not defined by user) for use in - % \multitableparskip calculation. We used define \multistrut based on - % this, but (ironically) that caused the spacing to be off. - % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100. -\ifdim\multitablelinespace=0pt -\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip -\global\advance\multitablelinespace by-\ht0 -\fi -%% Test to see if parskip is larger than space between lines of -%% table. If not, do nothing. -%% If so, set to same dimension as multitablelinespace. -\ifdim\multitableparskip>\multitablelinespace -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller - %% than skip between lines in the table. -\fi% -\ifdim\multitableparskip=0pt -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller - %% than skip between lines in the table. -\fi} - - -\message{conditionals,} - -% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext, -% @ifnotxml always succeed. They currently do nothing; we don't -% attempt to check whether the conditionals are properly nested. But we -% have to remember that they are conditionals, so that @end doesn't -% attempt to close an environment group. -% -\def\makecond#1{% - \expandafter\let\csname #1\endcsname = \relax - \expandafter\let\csname iscond.#1\endcsname = 1 -} -\makecond{iftex} -\makecond{ifnotdocbook} -\makecond{ifnothtml} -\makecond{ifnotinfo} -\makecond{ifnotplaintext} -\makecond{ifnotxml} - -% Ignore @ignore, @ifhtml, @ifinfo, and the like. -% -\def\direntry{\doignore{direntry}} -\def\documentdescription{\doignore{documentdescription}} -\def\docbook{\doignore{docbook}} -\def\html{\doignore{html}} -\def\ifdocbook{\doignore{ifdocbook}} -\def\ifhtml{\doignore{ifhtml}} -\def\ifinfo{\doignore{ifinfo}} -\def\ifnottex{\doignore{ifnottex}} -\def\ifplaintext{\doignore{ifplaintext}} -\def\ifxml{\doignore{ifxml}} -\def\ignore{\doignore{ignore}} -\def\menu{\doignore{menu}} -\def\xml{\doignore{xml}} - -% Ignore text until a line `@end #1', keeping track of nested conditionals. -% -% A count to remember the depth of nesting. -\newcount\doignorecount - -\def\doignore#1{\begingroup - % Scan in ``verbatim'' mode: - \obeylines - \catcode`\@ = \other - \catcode`\{ = \other - \catcode`\} = \other - % - % Make sure that spaces turn into tokens that match what \doignoretext wants. - \spaceisspace - % - % Count number of #1's that we've seen. - \doignorecount = 0 - % - % Swallow text until we reach the matching `@end #1'. - \dodoignore{#1}% -} - -{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source. - \obeylines % - % - \gdef\dodoignore#1{% - % #1 contains the command name as a string, e.g., `ifinfo'. - % - % Define a command to find the next `@end #1'. - \long\def\doignoretext##1^^M@end #1{% - \doignoretextyyy##1^^M@#1\_STOP_}% - % - % And this command to find another #1 command, at the beginning of a - % line. (Otherwise, we would consider a line `@c @ifset', for - % example, to count as an @ifset for nesting.) - \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}% - % - % And now expand that command. - \doignoretext ^^M% - }% -} - -\def\doignoreyyy#1{% - \def\temp{#1}% - \ifx\temp\empty % Nothing found. - \let\next\doignoretextzzz - \else % Found a nested condition, ... - \advance\doignorecount by 1 - \let\next\doignoretextyyy % ..., look for another. - % If we're here, #1 ends with ^^M\ifinfo (for example). - \fi - \next #1% the token \_STOP_ is present just after this macro. -} - -% We have to swallow the remaining "\_STOP_". -% -\def\doignoretextzzz#1{% - \ifnum\doignorecount = 0 % We have just found the outermost @end. - \let\next\enddoignore - \else % Still inside a nested condition. - \advance\doignorecount by -1 - \let\next\doignoretext % Look for the next @end. - \fi - \next -} - -% Finish off ignored text. -{ \obeylines% - % Ignore anything after the last `@end #1'; this matters in verbatim - % environments, where otherwise the newline after an ignored conditional - % would result in a blank line in the output. - \gdef\enddoignore#1^^M{\endgroup\ignorespaces}% -} - - -% @set VAR sets the variable VAR to an empty value. -% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. -% -% Since we want to separate VAR from REST-OF-LINE (which might be -% empty), we can't just use \parsearg; we have to insert a space of our -% own to delimit the rest of the line, and then take it out again if we -% didn't need it. -% We rely on the fact that \parsearg sets \catcode`\ =10. -% -\parseargdef\set{\setyyy#1 \endsetyyy} -\def\setyyy#1 #2\endsetyyy{% - {% - \makevalueexpandable - \def\temp{#2}% - \edef\next{\gdef\makecsname{SET#1}}% - \ifx\temp\empty - \next{}% - \else - \setzzz#2\endsetzzz - \fi - }% -} -% Remove the trailing space \setxxx inserted. -\def\setzzz#1 \endsetzzz{\next{#1}} - -% @clear VAR clears (i.e., unsets) the variable VAR. -% -\parseargdef\clear{% - {% - \makevalueexpandable - \global\expandafter\let\csname SET#1\endcsname=\relax - }% -} - -% @value{foo} gets the text saved in variable foo. -\def\value{\begingroup\makevalueexpandable\valuexxx} -\def\valuexxx#1{\expandablevalue{#1}\endgroup} -{ - \catcode`\- = \active \catcode`\_ = \active - % - \gdef\makevalueexpandable{% - \let\value = \expandablevalue - % We don't want these characters active, ... - \catcode`\-=\other \catcode`\_=\other - % ..., but we might end up with active ones in the argument if - % we're called from @code, as @code{@value{foo-bar_}}, though. - % So \let them to their normal equivalents. - \let-\realdash \let_\normalunderscore - } -} - -% We have this subroutine so that we can handle at least some @value's -% properly in indexes (we call \makevalueexpandable in \indexdummies). -% The command has to be fully expandable (if the variable is set), since -% the result winds up in the index file. This means that if the -% variable's value contains other Texinfo commands, it's almost certain -% it will fail (although perhaps we could fix that with sufficient work -% to do a one-level expansion on the result, instead of complete). -% -\def\expandablevalue#1{% - \expandafter\ifx\csname SET#1\endcsname\relax - {[No value for ``#1'']}% - \message{Variable `#1', used in @value, is not set.}% - \else - \csname SET#1\endcsname - \fi -} - -% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined -% with @set. -% -% To get special treatment of `@end ifset,' call \makeond and the redefine. -% -\makecond{ifset} -\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}} -\def\doifset#1#2{% - {% - \makevalueexpandable - \let\next=\empty - \expandafter\ifx\csname SET#2\endcsname\relax - #1% If not set, redefine \next. - \fi - \expandafter - }\next -} -\def\ifsetfail{\doignore{ifset}} - -% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been -% defined with @set, or has been undefined with @clear. -% -% The `\else' inside the `\doifset' parameter is a trick to reuse the -% above code: if the variable is not set, do nothing, if it is set, -% then redefine \next to \ifclearfail. -% -\makecond{ifclear} -\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}} -\def\ifclearfail{\doignore{ifclear}} - -% @dircategory CATEGORY -- specify a category of the dir file -% which this file should belong to. Ignore this in TeX. -\let\dircategory=\comment - -% @defininfoenclose. -\let\definfoenclose=\comment - - -\message{indexing,} -% Index generation facilities - -% Define \newwrite to be identical to plain tex's \newwrite -% except not \outer, so it can be used within macros and \if's. -\edef\newwrite{\makecsname{ptexnewwrite}} - -% \newindex {foo} defines an index named foo. -% It automatically defines \fooindex such that -% \fooindex ...rest of line... puts an entry in the index foo. -% It also defines \fooindfile to be the number of the output channel for -% the file that accumulates this index. The file's extension is foo. -% The name of an index should be no more than 2 characters long -% for the sake of vms. -% -\def\newindex#1{% - \iflinks - \expandafter\newwrite \csname#1indfile\endcsname - \openout \csname#1indfile\endcsname \jobname.#1 % Open the file - \fi - \expandafter\xdef\csname#1index\endcsname{% % Define @#1index - \noexpand\doindex{#1}} -} - -% @defindex foo == \newindex{foo} -% -\def\defindex{\parsearg\newindex} - -% Define @defcodeindex, like @defindex except put all entries in @code. -% -\def\defcodeindex{\parsearg\newcodeindex} -% -\def\newcodeindex#1{% - \iflinks - \expandafter\newwrite \csname#1indfile\endcsname - \openout \csname#1indfile\endcsname \jobname.#1 - \fi - \expandafter\xdef\csname#1index\endcsname{% - \noexpand\docodeindex{#1}}% -} - - -% @synindex foo bar makes index foo feed into index bar. -% Do this instead of @defindex foo if you don't want it as a separate index. -% -% @syncodeindex foo bar similar, but put all entries made for index foo -% inside @code. -% -\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}} -\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}} - -% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo), -% #3 the target index (bar). -\def\dosynindex#1#2#3{% - % Only do \closeout if we haven't already done it, else we'll end up - % closing the target index. - \expandafter \ifx\csname donesynindex#2\endcsname \undefined - % The \closeout helps reduce unnecessary open files; the limit on the - % Acorn RISC OS is a mere 16 files. - \expandafter\closeout\csname#2indfile\endcsname - \expandafter\let\csname\donesynindex#2\endcsname = 1 - \fi - % redefine \fooindfile: - \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname - \expandafter\let\csname#2indfile\endcsname=\temp - % redefine \fooindex: - \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}% -} - -% Define \doindex, the driver for all \fooindex macros. -% Argument #1 is generated by the calling \fooindex macro, -% and it is "foo", the name of the index. - -% \doindex just uses \parsearg; it calls \doind for the actual work. -% This is because \doind is more useful to call from other macros. - -% There is also \dosubind {index}{topic}{subtopic} -% which makes an entry in a two-level index such as the operation index. - -\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} -\def\singleindexer #1{\doind{\indexname}{#1}} - -% like the previous two, but they put @code around the argument. -\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} -\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} - -% Take care of Texinfo commands that can appear in an index entry. -% Since there are some commands we want to expand, and others we don't, -% we have to laboriously prevent expansion for those that we don't. -% -\def\indexdummies{% - \escapechar = `\\ % use backslash in output files. - \def\@{@}% change to @@ when we switch to @ as escape char in index files. - \def\ {\realbackslash\space }% - % - % Need these in case \tex is in effect and \{ is a \delimiter again. - % But can't use \lbracecmd and \rbracecmd because texindex assumes - % braces and backslashes are used only as delimiters. - \let\{ = \mylbrace - \let\} = \myrbrace - % - % I don't entirely understand this, but when an index entry is - % generated from a macro call, the \endinput which \scanmacro inserts - % causes processing to be prematurely terminated. This is, - % apparently, because \indexsorttmp is fully expanded, and \endinput - % is an expandable command. The redefinition below makes \endinput - % disappear altogether for that purpose -- although logging shows that - % processing continues to some further point. On the other hand, it - % seems \endinput does not hurt in the printed index arg, since that - % is still getting written without apparent harm. - % - % Sample source (mac-idx3.tex, reported by Graham Percival to - % help-texinfo, 22may06): - % @macro funindex {WORD} - % @findex xyz - % @end macro - % ... - % @funindex commtest - % - % The above is not enough to reproduce the bug, but it gives the flavor. - % - % Sample whatsit resulting: - % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} - % - % So: - \let\endinput = \empty - % - % Do the redefinitions. - \commondummies -} - -% For the aux and toc files, @ is the escape character. So we want to -% redefine everything using @ as the escape character (instead of -% \realbackslash, still used for index files). When everything uses @, -% this will be simpler. -% -\def\atdummies{% - \def\@{@@}% - \def\ {@ }% - \let\{ = \lbraceatcmd - \let\} = \rbraceatcmd - % - % Do the redefinitions. - \commondummies - \otherbackslash -} - -% Called from \indexdummies and \atdummies. -% -\def\commondummies{% - % - % \definedummyword defines \#1 as \string\#1\space, thus effectively - % preventing its expansion. This is used only for control% words, - % not control letters, because the \space would be incorrect for - % control characters, but is needed to separate the control word - % from whatever follows. - % - % For control letters, we have \definedummyletter, which omits the - % space. - % - % These can be used both for control words that take an argument and - % those that do not. If it is followed by {arg} in the input, then - % that will dutifully get written to the index (or wherever). - % - \def\definedummyword ##1{\def##1{\string##1\space}}% - \def\definedummyletter##1{\def##1{\string##1}}% - \let\definedummyaccent\definedummyletter - % - \commondummiesnofonts - % - \definedummyletter\_% - % - % Non-English letters. - \definedummyword\AA - \definedummyword\AE - \definedummyword\L - \definedummyword\OE - \definedummyword\O - \definedummyword\aa - \definedummyword\ae - \definedummyword\l - \definedummyword\oe - \definedummyword\o - \definedummyword\ss - \definedummyword\exclamdown - \definedummyword\questiondown - \definedummyword\ordf - \definedummyword\ordm - % - % Although these internal commands shouldn't show up, sometimes they do. - \definedummyword\bf - \definedummyword\gtr - \definedummyword\hat - \definedummyword\less - \definedummyword\sf - \definedummyword\sl - \definedummyword\tclose - \definedummyword\tt - % - \definedummyword\LaTeX - \definedummyword\TeX - % - % Assorted special characters. - \definedummyword\bullet - \definedummyword\comma - \definedummyword\copyright - \definedummyword\registeredsymbol - \definedummyword\dots - \definedummyword\enddots - \definedummyword\equiv - \definedummyword\error - \definedummyword\euro - \definedummyword\expansion - \definedummyword\minus - \definedummyword\pounds - \definedummyword\point - \definedummyword\print - \definedummyword\result - \definedummyword\textdegree - % - % We want to disable all macros so that they are not expanded by \write. - \macrolist - % - \normalturnoffactive - % - % Handle some cases of @value -- where it does not contain any - % (non-fully-expandable) commands. - \makevalueexpandable -} - -% \commondummiesnofonts: common to \commondummies and \indexnofonts. -% -\def\commondummiesnofonts{% - % Control letters and accents. - \definedummyletter\!% - \definedummyaccent\"% - \definedummyaccent\'% - \definedummyletter\*% - \definedummyaccent\,% - \definedummyletter\.% - \definedummyletter\/% - \definedummyletter\:% - \definedummyaccent\=% - \definedummyletter\?% - \definedummyaccent\^% - \definedummyaccent\`% - \definedummyaccent\~% - \definedummyword\u - \definedummyword\v - \definedummyword\H - \definedummyword\dotaccent - \definedummyword\ringaccent - \definedummyword\tieaccent - \definedummyword\ubaraccent - \definedummyword\udotaccent - \definedummyword\dotless - % - % Texinfo font commands. - \definedummyword\b - \definedummyword\i - \definedummyword\r - \definedummyword\sc - \definedummyword\t - % - % Commands that take arguments. - \definedummyword\acronym - \definedummyword\cite - \definedummyword\code - \definedummyword\command - \definedummyword\dfn - \definedummyword\emph - \definedummyword\env - \definedummyword\file - \definedummyword\kbd - \definedummyword\key - \definedummyword\math - \definedummyword\option - \definedummyword\pxref - \definedummyword\ref - \definedummyword\samp - \definedummyword\strong - \definedummyword\tie - \definedummyword\uref - \definedummyword\url - \definedummyword\var - \definedummyword\verb - \definedummyword\w - \definedummyword\xref -} - -% \indexnofonts is used when outputting the strings to sort the index -% by, and when constructing control sequence names. It eliminates all -% control sequences and just writes whatever the best ASCII sort string -% would be for a given command (usually its argument). -% -\def\indexnofonts{% - % Accent commands should become @asis. - \def\definedummyaccent##1{\let##1\asis}% - % We can just ignore other control letters. - \def\definedummyletter##1{\let##1\empty}% - % Hopefully, all control words can become @asis. - \let\definedummyword\definedummyaccent - % - \commondummiesnofonts - % - % Don't no-op \tt, since it isn't a user-level command - % and is used in the definitions of the active chars like <, >, |, etc. - % Likewise with the other plain tex font commands. - %\let\tt=\asis - % - \def\ { }% - \def\@{@}% - % how to handle braces? - \def\_{\normalunderscore}% - % - % Non-English letters. - \def\AA{AA}% - \def\AE{AE}% - \def\L{L}% - \def\OE{OE}% - \def\O{O}% - \def\aa{aa}% - \def\ae{ae}% - \def\l{l}% - \def\oe{oe}% - \def\o{o}% - \def\ss{ss}% - \def\exclamdown{!}% - \def\questiondown{?}% - \def\ordf{a}% - \def\ordm{o}% - % - \def\LaTeX{LaTeX}% - \def\TeX{TeX}% - % - % Assorted special characters. - % (The following {} will end up in the sort string, but that's ok.) - \def\bullet{bullet}% - \def\comma{,}% - \def\copyright{copyright}% - \def\registeredsymbol{R}% - \def\dots{...}% - \def\enddots{...}% - \def\equiv{==}% - \def\error{error}% - \def\euro{euro}% - \def\expansion{==>}% - \def\minus{-}% - \def\pounds{pounds}% - \def\point{.}% - \def\print{-|}% - \def\result{=>}% - \def\textdegree{degrees}% - % - % We need to get rid of all macros, leaving only the arguments (if present). - % Of course this is not nearly correct, but it is the best we can do for now. - % makeinfo does not expand macros in the argument to @deffn, which ends up - % writing an index entry, and texindex isn't prepared for an index sort entry - % that starts with \. - % - % Since macro invocations are followed by braces, we can just redefine them - % to take a single TeX argument. The case of a macro invocation that - % goes to end-of-line is not handled. - % - \macrolist -} - -\let\indexbackslash=0 %overridden during \printindex. -\let\SETmarginindex=\relax % put index entries in margin (undocumented)? - -% Most index entries go through here, but \dosubind is the general case. -% #1 is the index name, #2 is the entry text. -\def\doind#1#2{\dosubind{#1}{#2}{}} - -% Workhorse for all \fooindexes. -% #1 is name of index, #2 is stuff to put there, #3 is subentry -- -% empty if called from \doind, as we usually are (the main exception -% is with most defuns, which call us directly). -% -\def\dosubind#1#2#3{% - \iflinks - {% - % Store the main index entry text (including the third arg). - \toks0 = {#2}% - % If third arg is present, precede it with a space. - \def\thirdarg{#3}% - \ifx\thirdarg\empty \else - \toks0 = \expandafter{\the\toks0 \space #3}% - \fi - % - \edef\writeto{\csname#1indfile\endcsname}% - % - \ifvmode - \dosubindsanitize - \else - \dosubindwrite - \fi - }% - \fi -} - -% Write the entry in \toks0 to the index file: -% -\def\dosubindwrite{% - % Put the index entry in the margin if desired. - \ifx\SETmarginindex\relax\else - \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}% - \fi - % - % Remember, we are within a group. - \indexdummies % Must do this here, since \bf, etc expand at this stage - \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now - % so it will be output as is; and it will print as backslash. - % - % Process the index entry with all font commands turned off, to - % get the string to sort by. - {\indexnofonts - \edef\temp{\the\toks0}% need full expansion - \xdef\indexsorttmp{\temp}% - }% - % - % Set up the complete index entry, with both the sort key and - % the original text, including any font commands. We write - % three arguments to \entry to the .?? file (four in the - % subentry case), texindex reduces to two when writing the .??s - % sorted result. - \edef\temp{% - \write\writeto{% - \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}% - }% - \temp -} - -% Take care of unwanted page breaks: -% -% If a skip is the last thing on the list now, preserve it -% by backing up by \lastskip, doing the \write, then inserting -% the skip again. Otherwise, the whatsit generated by the -% \write will make \lastskip zero. The result is that sequences -% like this: -% @end defun -% @tindex whatever -% @defun ... -% will have extra space inserted, because the \medbreak in the -% start of the @defun won't see the skip inserted by the @end of -% the previous defun. -% -% But don't do any of this if we're not in vertical mode. We -% don't want to do a \vskip and prematurely end a paragraph. -% -% Avoid page breaks due to these extra skips, too. -% -% But wait, there is a catch there: -% We'll have to check whether \lastskip is zero skip. \ifdim is not -% sufficient for this purpose, as it ignores stretch and shrink parts -% of the skip. The only way seems to be to check the textual -% representation of the skip. -% -% The following is almost like \def\zeroskipmacro{0.0pt} except that -% the ``p'' and ``t'' characters have catcode \other, not 11 (letter). -% -\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname} -% -% ..., ready, GO: -% -\def\dosubindsanitize{% - % \lastskip and \lastpenalty cannot both be nonzero simultaneously. - \skip0 = \lastskip - \edef\lastskipmacro{\the\lastskip}% - \count255 = \lastpenalty - % - % If \lastskip is nonzero, that means the last item was a - % skip. And since a skip is discardable, that means this - % -\skip0 glue we're inserting is preceded by a - % non-discardable item, therefore it is not a potential - % breakpoint, therefore no \nobreak needed. - \ifx\lastskipmacro\zeroskipmacro - \else - \vskip-\skip0 - \fi - % - \dosubindwrite - % - \ifx\lastskipmacro\zeroskipmacro - % If \lastskip was zero, perhaps the last item was a penalty, and - % perhaps it was >=10000, e.g., a \nobreak. In that case, we want - % to re-insert the same penalty (values >10000 are used for various - % signals); since we just inserted a non-discardable item, any - % following glue (such as a \parskip) would be a breakpoint. For example: - % - % @deffn deffn-whatever - % @vindex index-whatever - % Description. - % would allow a break between the index-whatever whatsit - % and the "Description." paragraph. - \ifnum\count255>9999 \penalty\count255 \fi - \else - % On the other hand, if we had a nonzero \lastskip, - % this make-up glue would be preceded by a non-discardable item - % (the whatsit from the \write), so we must insert a \nobreak. - \nobreak\vskip\skip0 - \fi -} - -% The index entry written in the file actually looks like -% \entry {sortstring}{page}{topic} -% or -% \entry {sortstring}{page}{topic}{subtopic} -% The texindex program reads in these files and writes files -% containing these kinds of lines: -% \initial {c} -% before the first topic whose initial is c -% \entry {topic}{pagelist} -% for a topic that is used without subtopics -% \primary {topic} -% for the beginning of a topic that is used with subtopics -% \secondary {subtopic}{pagelist} -% for each subtopic. - -% Define the user-accessible indexing commands -% @findex, @vindex, @kindex, @cindex. - -\def\findex {\fnindex} -\def\kindex {\kyindex} -\def\cindex {\cpindex} -\def\vindex {\vrindex} -\def\tindex {\tpindex} -\def\pindex {\pgindex} - -\def\cindexsub {\begingroup\obeylines\cindexsub} -{\obeylines % -\gdef\cindexsub "#1" #2^^M{\endgroup % -\dosubind{cp}{#2}{#1}}} - -% Define the macros used in formatting output of the sorted index material. - -% @printindex causes a particular index (the ??s file) to get printed. -% It does not print any chapter heading (usually an @unnumbered). -% -\parseargdef\printindex{\begingroup - \dobreak \chapheadingskip{10000}% - % - \smallfonts \rm - \tolerance = 9500 - \everypar = {}% don't want the \kern\-parindent from indentation suppression. - % - % See if the index file exists and is nonempty. - % Change catcode of @ here so that if the index file contains - % \initial {@} - % as its first line, TeX doesn't complain about mismatched braces - % (because it thinks @} is a control sequence). - \catcode`\@ = 11 - \openin 1 \jobname.#1s - \ifeof 1 - % \enddoublecolumns gets confused if there is no text in the index, - % and it loses the chapter title and the aux file entries for the - % index. The easiest way to prevent this problem is to make sure - % there is some text. - \putwordIndexNonexistent - \else - % - % If the index file exists but is empty, then \openin leaves \ifeof - % false. We have to make TeX try to read something from the file, so - % it can discover if there is anything in it. - \read 1 to \temp - \ifeof 1 - \putwordIndexIsEmpty - \else - % Index files are almost Texinfo source, but we use \ as the escape - % character. It would be better to use @, but that's too big a change - % to make right now. - \def\indexbackslash{\backslashcurfont}% - \catcode`\\ = 0 - \escapechar = `\\ - \begindoublecolumns - \input \jobname.#1s - \enddoublecolumns - \fi - \fi - \closein 1 -\endgroup} - -% These macros are used by the sorted index file itself. -% Change them to control the appearance of the index. - -\def\initial#1{{% - % Some minor font changes for the special characters. - \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt - % - % Remove any glue we may have, we'll be inserting our own. - \removelastskip - % - % We like breaks before the index initials, so insert a bonus. - \nobreak - \vskip 0pt plus 3\baselineskip - \penalty 0 - \vskip 0pt plus -3\baselineskip - % - % Typeset the initial. Making this add up to a whole number of - % baselineskips increases the chance of the dots lining up from column - % to column. It still won't often be perfect, because of the stretch - % we need before each entry, but it's better. - % - % No shrink because it confuses \balancecolumns. - \vskip 1.67\baselineskip plus .5\baselineskip - \leftline{\secbf #1}% - % Do our best not to break after the initial. - \nobreak - \vskip .33\baselineskip plus .1\baselineskip -}} - -% \entry typesets a paragraph consisting of the text (#1), dot leaders, and -% then page number (#2) flushed to the right margin. It is used for index -% and table of contents entries. The paragraph is indented by \leftskip. -% -% A straightforward implementation would start like this: -% \def\entry#1#2{... -% But this frozes the catcodes in the argument, and can cause problems to -% @code, which sets - active. This problem was fixed by a kludge--- -% ``-'' was active throughout whole index, but this isn't really right. -% -% The right solution is to prevent \entry from swallowing the whole text. -% --kasal, 21nov03 -\def\entry{% - \begingroup - % - % Start a new paragraph if necessary, so our assignments below can't - % affect previous text. - \par - % - % Do not fill out the last line with white space. - \parfillskip = 0in - % - % No extra space above this paragraph. - \parskip = 0in - % - % Do not prefer a separate line ending with a hyphen to fewer lines. - \finalhyphendemerits = 0 - % - % \hangindent is only relevant when the entry text and page number - % don't both fit on one line. In that case, bob suggests starting the - % dots pretty far over on the line. Unfortunately, a large - % indentation looks wrong when the entry text itself is broken across - % lines. So we use a small indentation and put up with long leaders. - % - % \hangafter is reset to 1 (which is the value we want) at the start - % of each paragraph, so we need not do anything with that. - \hangindent = 2em - % - % When the entry text needs to be broken, just fill out the first line - % with blank space. - \rightskip = 0pt plus1fil - % - % A bit of stretch before each entry for the benefit of balancing - % columns. - \vskip 0pt plus1pt - % - % Swallow the left brace of the text (first parameter): - \afterassignment\doentry - \let\temp = -} -\def\doentry{% - \bgroup % Instead of the swallowed brace. - \noindent - \aftergroup\finishentry - % And now comes the text of the entry. -} -\def\finishentry#1{% - % #1 is the page number. - % - % The following is kludged to not output a line of dots in the index if - % there are no page numbers. The next person who breaks this will be - % cursed by a Unix daemon. - \def\tempa{{\rm }}% - \def\tempb{#1}% - \edef\tempc{\tempa}% - \edef\tempd{\tempb}% - \ifx\tempc\tempd - \ % - \else - % - % If we must, put the page number on a line of its own, and fill out - % this line with blank space. (The \hfil is overwhelmed with the - % fill leaders glue in \indexdotfill if the page number does fit.) - \hfil\penalty50 - \null\nobreak\indexdotfill % Have leaders before the page number. - % - % The `\ ' here is removed by the implicit \unskip that TeX does as - % part of (the primitive) \par. Without it, a spurious underfull - % \hbox ensues. - \ifpdf - \pdfgettoks#1.% - \ \the\toksA - \else - \ #1% - \fi - \fi - \par - \endgroup -} - -% Like plain.tex's \dotfill, except uses up at least 1 em. -\def\indexdotfill{\cleaders - \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill} - -\def\primary #1{\line{#1\hfil}} - -\newskip\secondaryindent \secondaryindent=0.5cm -\def\secondary#1#2{{% - \parfillskip=0in - \parskip=0in - \hangindent=1in - \hangafter=1 - \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill - \ifpdf - \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. - \else - #2 - \fi - \par -}} - -% Define two-column mode, which we use to typeset indexes. -% Adapted from the TeXbook, page 416, which is to say, -% the manmac.tex format used to print the TeXbook itself. -\catcode`\@=11 - -\newbox\partialpage -\newdimen\doublecolumnhsize - -\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns - % Grab any single-column material above us. - \output = {% - % - % Here is a possibility not foreseen in manmac: if we accumulate a - % whole lot of material, we might end up calling this \output - % routine twice in a row (see the doublecol-lose test, which is - % essentially a couple of indexes with @setchapternewpage off). In - % that case we just ship out what is in \partialpage with the normal - % output routine. Generally, \partialpage will be empty when this - % runs and this will be a no-op. See the indexspread.tex test case. - \ifvoid\partialpage \else - \onepageout{\pagecontents\partialpage}% - \fi - % - \global\setbox\partialpage = \vbox{% - % Unvbox the main output page. - \unvbox\PAGE - \kern-\topskip \kern\baselineskip - }% - }% - \eject % run that output routine to set \partialpage - % - % Use the double-column output routine for subsequent pages. - \output = {\doublecolumnout}% - % - % Change the page size parameters. We could do this once outside this - % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 - % format, but then we repeat the same computation. Repeating a couple - % of assignments once per index is clearly meaningless for the - % execution time, so we may as well do it in one place. - % - % First we halve the line length, less a little for the gutter between - % the columns. We compute the gutter based on the line length, so it - % changes automatically with the paper format. The magic constant - % below is chosen so that the gutter has the same value (well, +-<1pt) - % as it did when we hard-coded it. - % - % We put the result in a separate register, \doublecolumhsize, so we - % can restore it in \pagesofar, after \hsize itself has (potentially) - % been clobbered. - % - \doublecolumnhsize = \hsize - \advance\doublecolumnhsize by -.04154\hsize - \divide\doublecolumnhsize by 2 - \hsize = \doublecolumnhsize - % - % Double the \vsize as well. (We don't need a separate register here, - % since nobody clobbers \vsize.) - \vsize = 2\vsize -} - -% The double-column output routine for all double-column pages except -% the last. -% -\def\doublecolumnout{% - \splittopskip=\topskip \splitmaxdepth=\maxdepth - % Get the available space for the double columns -- the normal - % (undoubled) page height minus any material left over from the - % previous page. - \dimen@ = \vsize - \divide\dimen@ by 2 - \advance\dimen@ by -\ht\partialpage - % - % box0 will be the left-hand column, box2 the right. - \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ - \onepageout\pagesofar - \unvbox255 - \penalty\outputpenalty -} -% -% Re-output the contents of the output page -- any previous material, -% followed by the two boxes we just split, in box0 and box2. -\def\pagesofar{% - \unvbox\partialpage - % - \hsize = \doublecolumnhsize - \wd0=\hsize \wd2=\hsize - \hbox to\pagewidth{\box0\hfil\box2}% -} -% -% All done with double columns. -\def\enddoublecolumns{% - \output = {% - % Split the last of the double-column material. Leave it on the - % current page, no automatic page break. - \balancecolumns - % - % If we end up splitting too much material for the current page, - % though, there will be another page break right after this \output - % invocation ends. Having called \balancecolumns once, we do not - % want to call it again. Therefore, reset \output to its normal - % definition right away. (We hope \balancecolumns will never be - % called on to balance too much material, but if it is, this makes - % the output somewhat more palatable.) - \global\output = {\onepageout{\pagecontents\PAGE}}% - }% - \eject - \endgroup % started in \begindoublecolumns - % - % \pagegoal was set to the doubled \vsize above, since we restarted - % the current page. We're now back to normal single-column - % typesetting, so reset \pagegoal to the normal \vsize (after the - % \endgroup where \vsize got restored). - \pagegoal = \vsize -} -% -% Called at the end of the double column material. -\def\balancecolumns{% - \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120. - \dimen@ = \ht0 - \advance\dimen@ by \topskip - \advance\dimen@ by-\baselineskip - \divide\dimen@ by 2 % target to split to - %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}% - \splittopskip = \topskip - % Loop until we get a decent breakpoint. - {% - \vbadness = 10000 - \loop - \global\setbox3 = \copy0 - \global\setbox1 = \vsplit3 to \dimen@ - \ifdim\ht3>\dimen@ - \global\advance\dimen@ by 1pt - \repeat - }% - %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}% - \setbox0=\vbox to\dimen@{\unvbox1}% - \setbox2=\vbox to\dimen@{\unvbox3}% - % - \pagesofar -} -\catcode`\@ = \other - - -\message{sectioning,} -% Chapters, sections, etc. - -% \unnumberedno is an oxymoron, of course. But we count the unnumbered -% sections so that we can refer to them unambiguously in the pdf -% outlines by their "section number". We avoid collisions with chapter -% numbers by starting them at 10000. (If a document ever has 10000 -% chapters, we're in trouble anyway, I'm sure.) -\newcount\unnumberedno \unnumberedno = 10000 -\newcount\chapno -\newcount\secno \secno=0 -\newcount\subsecno \subsecno=0 -\newcount\subsubsecno \subsubsecno=0 - -% This counter is funny since it counts through charcodes of letters A, B, ... -\newcount\appendixno \appendixno = `\@ -% -% \def\appendixletter{\char\the\appendixno} -% We do the following ugly conditional instead of the above simple -% construct for the sake of pdftex, which needs the actual -% letter in the expansion, not just typeset. -% -\def\appendixletter{% - \ifnum\appendixno=`A A% - \else\ifnum\appendixno=`B B% - \else\ifnum\appendixno=`C C% - \else\ifnum\appendixno=`D D% - \else\ifnum\appendixno=`E E% - \else\ifnum\appendixno=`F F% - \else\ifnum\appendixno=`G G% - \else\ifnum\appendixno=`H H% - \else\ifnum\appendixno=`I I% - \else\ifnum\appendixno=`J J% - \else\ifnum\appendixno=`K K% - \else\ifnum\appendixno=`L L% - \else\ifnum\appendixno=`M M% - \else\ifnum\appendixno=`N N% - \else\ifnum\appendixno=`O O% - \else\ifnum\appendixno=`P P% - \else\ifnum\appendixno=`Q Q% - \else\ifnum\appendixno=`R R% - \else\ifnum\appendixno=`S S% - \else\ifnum\appendixno=`T T% - \else\ifnum\appendixno=`U U% - \else\ifnum\appendixno=`V V% - \else\ifnum\appendixno=`W W% - \else\ifnum\appendixno=`X X% - \else\ifnum\appendixno=`Y Y% - \else\ifnum\appendixno=`Z Z% - % The \the is necessary, despite appearances, because \appendixletter is - % expanded while writing the .toc file. \char\appendixno is not - % expandable, thus it is written literally, thus all appendixes come out - % with the same letter (or @) in the toc without it. - \else\char\the\appendixno - \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi - \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi} - -% Each @chapter defines this as the name of the chapter. -% page headings and footings can use it. @section does likewise. -% However, they are not reliable, because we don't use marks. -\def\thischapter{} -\def\thissection{} - -\newcount\absseclevel % used to calculate proper heading level -\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count - -% @raisesections: treat @section as chapter, @subsection as section, etc. -\def\raisesections{\global\advance\secbase by -1} -\let\up=\raisesections % original BFox name - -% @lowersections: treat @chapter as section, @section as subsection, etc. -\def\lowersections{\global\advance\secbase by 1} -\let\down=\lowersections % original BFox name - -% we only have subsub. -\chardef\maxseclevel = 3 -% -% A numbered section within an unnumbered changes to unnumbered too. -% To achive this, remember the "biggest" unnum. sec. we are currently in: -\chardef\unmlevel = \maxseclevel -% -% Trace whether the current chapter is an appendix or not: -% \chapheadtype is "N" or "A", unnumbered chapters are ignored. -\def\chapheadtype{N} - -% Choose a heading macro -% #1 is heading type -% #2 is heading level -% #3 is text for heading -\def\genhead#1#2#3{% - % Compute the abs. sec. level: - \absseclevel=#2 - \advance\absseclevel by \secbase - % Make sure \absseclevel doesn't fall outside the range: - \ifnum \absseclevel < 0 - \absseclevel = 0 - \else - \ifnum \absseclevel > 3 - \absseclevel = 3 - \fi - \fi - % The heading type: - \def\headtype{#1}% - \if \headtype U% - \ifnum \absseclevel < \unmlevel - \chardef\unmlevel = \absseclevel - \fi - \else - % Check for appendix sections: - \ifnum \absseclevel = 0 - \edef\chapheadtype{\headtype}% - \else - \if \headtype A\if \chapheadtype N% - \errmessage{@appendix... within a non-appendix chapter}% - \fi\fi - \fi - % Check for numbered within unnumbered: - \ifnum \absseclevel > \unmlevel - \def\headtype{U}% - \else - \chardef\unmlevel = 3 - \fi - \fi - % Now print the heading: - \if \headtype U% - \ifcase\absseclevel - \unnumberedzzz{#3}% - \or \unnumberedseczzz{#3}% - \or \unnumberedsubseczzz{#3}% - \or \unnumberedsubsubseczzz{#3}% - \fi - \else - \if \headtype A% - \ifcase\absseclevel - \appendixzzz{#3}% - \or \appendixsectionzzz{#3}% - \or \appendixsubseczzz{#3}% - \or \appendixsubsubseczzz{#3}% - \fi - \else - \ifcase\absseclevel - \chapterzzz{#3}% - \or \seczzz{#3}% - \or \numberedsubseczzz{#3}% - \or \numberedsubsubseczzz{#3}% - \fi - \fi - \fi - \suppressfirstparagraphindent -} - -% an interface: -\def\numhead{\genhead N} -\def\apphead{\genhead A} -\def\unnmhead{\genhead U} - -% @chapter, @appendix, @unnumbered. Increment top-level counter, reset -% all lower-level sectioning counters to zero. -% -% Also set \chaplevelprefix, which we prepend to @float sequence numbers -% (e.g., figures), q.v. By default (before any chapter), that is empty. -\let\chaplevelprefix = \empty -% -\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz -\def\chapterzzz#1{% - % section resetting is \global in case the chapter is in a group, such - % as an @include file. - \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 - \global\advance\chapno by 1 - % - % Used for \float. - \gdef\chaplevelprefix{\the\chapno.}% - \resetallfloatnos - % - \message{\putwordChapter\space \the\chapno}% - % - % Write the actual heading. - \chapmacro{#1}{Ynumbered}{\the\chapno}% - % - % So @section and the like are numbered underneath this chapter. - \global\let\section = \numberedsec - \global\let\subsection = \numberedsubsec - \global\let\subsubsection = \numberedsubsubsec -} - -\outer\parseargdef\appendix{\apphead0{#1}} % normally apphead0 calls appendixzzz -\def\appendixzzz#1{% - \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 - \global\advance\appendixno by 1 - \gdef\chaplevelprefix{\appendixletter.}% - \resetallfloatnos - % - \def\appendixnum{\putwordAppendix\space \appendixletter}% - \message{\appendixnum}% - % - \chapmacro{#1}{Yappendix}{\appendixletter}% - % - \global\let\section = \appendixsec - \global\let\subsection = \appendixsubsec - \global\let\subsubsection = \appendixsubsubsec -} - -\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz -\def\unnumberedzzz#1{% - \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 - \global\advance\unnumberedno by 1 - % - % Since an unnumbered has no number, no prefix for figures. - \global\let\chaplevelprefix = \empty - \resetallfloatnos - % - % This used to be simply \message{#1}, but TeX fully expands the - % argument to \message. Therefore, if #1 contained @-commands, TeX - % expanded them. For example, in `@unnumbered The @cite{Book}', TeX - % expanded @cite (which turns out to cause errors because \cite is meant - % to be executed, not expanded). - % - % Anyway, we don't want the fully-expanded definition of @cite to appear - % as a result of the \message, we just want `@cite' itself. We use - % \the<toks register> to achieve this: TeX expands \the<toks> only once, - % simply yielding the contents of <toks register>. (We also do this for - % the toc entries.) - \toks0 = {#1}% - \message{(\the\toks0)}% - % - \chapmacro{#1}{Ynothing}{\the\unnumberedno}% - % - \global\let\section = \unnumberedsec - \global\let\subsection = \unnumberedsubsec - \global\let\subsubsection = \unnumberedsubsubsec -} - -% @centerchap is like @unnumbered, but the heading is centered. -\outer\parseargdef\centerchap{% - % Well, we could do the following in a group, but that would break - % an assumption that \chapmacro is called at the outermost level. - % Thus we are safer this way: --kasal, 24feb04 - \let\centerparametersmaybe = \centerparameters - \unnmhead0{#1}% - \let\centerparametersmaybe = \relax -} - -% @top is like @unnumbered. -\let\top\unnumbered - -% Sections. -\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz -\def\seczzz#1{% - \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 - \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}% -} - -\outer\parseargdef\appendixsection{\apphead1{#1}} % normally calls appendixsectionzzz -\def\appendixsectionzzz#1{% - \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 - \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}% -} -\let\appendixsec\appendixsection - -\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz -\def\unnumberedseczzz#1{% - \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 - \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}% -} - -% Subsections. -\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz -\def\numberedsubseczzz#1{% - \global\subsubsecno=0 \global\advance\subsecno by 1 - \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}% -} - -\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz -\def\appendixsubseczzz#1{% - \global\subsubsecno=0 \global\advance\subsecno by 1 - \sectionheading{#1}{subsec}{Yappendix}% - {\appendixletter.\the\secno.\the\subsecno}% -} - -\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz -\def\unnumberedsubseczzz#1{% - \global\subsubsecno=0 \global\advance\subsecno by 1 - \sectionheading{#1}{subsec}{Ynothing}% - {\the\unnumberedno.\the\secno.\the\subsecno}% -} - -% Subsubsections. -\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz -\def\numberedsubsubseczzz#1{% - \global\advance\subsubsecno by 1 - \sectionheading{#1}{subsubsec}{Ynumbered}% - {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}% -} - -\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz -\def\appendixsubsubseczzz#1{% - \global\advance\subsubsecno by 1 - \sectionheading{#1}{subsubsec}{Yappendix}% - {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}% -} - -\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz -\def\unnumberedsubsubseczzz#1{% - \global\advance\subsubsecno by 1 - \sectionheading{#1}{subsubsec}{Ynothing}% - {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}% -} - -% These macros control what the section commands do, according -% to what kind of chapter we are in (ordinary, appendix, or unnumbered). -% Define them by default for a numbered chapter. -\let\section = \numberedsec -\let\subsection = \numberedsubsec -\let\subsubsection = \numberedsubsubsec - -% Define @majorheading, @heading and @subheading - -% NOTE on use of \vbox for chapter headings, section headings, and such: -% 1) We use \vbox rather than the earlier \line to permit -% overlong headings to fold. -% 2) \hyphenpenalty is set to 10000 because hyphenation in a -% heading is obnoxious; this forbids it. -% 3) Likewise, headings look best if no \parindent is used, and -% if justification is not attempted. Hence \raggedright. - - -\def\majorheading{% - {\advance\chapheadingskip by 10pt \chapbreak }% - \parsearg\chapheadingzzz -} - -\def\chapheading{\chapbreak \parsearg\chapheadingzzz} -\def\chapheadingzzz#1{% - {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}% - \bigskip \par\penalty 200\relax - \suppressfirstparagraphindent -} - -% @heading, @subheading, @subsubheading. -\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{} - \suppressfirstparagraphindent} -\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{} - \suppressfirstparagraphindent} -\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{} - \suppressfirstparagraphindent} - -% These macros generate a chapter, section, etc. heading only -% (including whitespace, linebreaking, etc. around it), -% given all the information in convenient, parsed form. - -%%% Args are the skip and penalty (usually negative) -\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} - -%%% Define plain chapter starts, and page on/off switching for it -% Parameter controlling skip before chapter headings (if needed) - -\newskip\chapheadingskip - -\def\chapbreak{\dobreak \chapheadingskip {-4000}} -\def\chappager{\par\vfill\supereject} -\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi} - -\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} - -\def\CHAPPAGoff{% -\global\let\contentsalignmacro = \chappager -\global\let\pchapsepmacro=\chapbreak -\global\let\pagealignmacro=\chappager} - -\def\CHAPPAGon{% -\global\let\contentsalignmacro = \chappager -\global\let\pchapsepmacro=\chappager -\global\let\pagealignmacro=\chappager -\global\def\HEADINGSon{\HEADINGSsingle}} - -\def\CHAPPAGodd{% -\global\let\contentsalignmacro = \chapoddpage -\global\let\pchapsepmacro=\chapoddpage -\global\let\pagealignmacro=\chapoddpage -\global\def\HEADINGSon{\HEADINGSdouble}} - -\CHAPPAGon - -% Chapter opening. -% -% #1 is the text, #2 is the section type (Ynumbered, Ynothing, -% Yappendix, Yomitfromtoc), #3 the chapter number. -% -% To test against our argument. -\def\Ynothingkeyword{Ynothing} -\def\Yomitfromtockeyword{Yomitfromtoc} -\def\Yappendixkeyword{Yappendix} -% -\def\chapmacro#1#2#3{% - \pchapsepmacro - {% - \chapfonts \rm - % - % Have to define \thissection before calling \donoderef, because the - % xref code eventually uses it. On the other hand, it has to be called - % after \pchapsepmacro, or the headline will change too soon. - \gdef\thissection{#1}% - \gdef\thischaptername{#1}% - % - % Only insert the separating space if we have a chapter/appendix - % number, and don't print the unnumbered ``number''. - \def\temptype{#2}% - \ifx\temptype\Ynothingkeyword - \setbox0 = \hbox{}% - \def\toctype{unnchap}% - \gdef\thischapternum{}% - \gdef\thischapter{#1}% - \else\ifx\temptype\Yomitfromtockeyword - \setbox0 = \hbox{}% contents like unnumbered, but no toc entry - \def\toctype{omit}% - \gdef\thischapternum{}% - \gdef\thischapter{}% - \else\ifx\temptype\Yappendixkeyword - \setbox0 = \hbox{\putwordAppendix{} #3\enspace}% - \def\toctype{app}% - \xdef\thischapternum{\appendixletter}% - % We don't substitute the actual chapter name into \thischapter - % because we don't want its macros evaluated now. And we don't - % use \thissection because that changes with each section. - % - \xdef\thischapter{\putwordAppendix{} \appendixletter: - \noexpand\thischaptername}% - \else - \setbox0 = \hbox{#3\enspace}% - \def\toctype{numchap}% - \xdef\thischapternum{\the\chapno}% - \xdef\thischapter{\putwordChapter{} \the\chapno: - \noexpand\thischaptername}% - \fi\fi\fi - % - % Write the toc entry for this chapter. Must come before the - % \donoderef, because we include the current node name in the toc - % entry, and \donoderef resets it to empty. - \writetocentry{\toctype}{#1}{#3}% - % - % For pdftex, we have to write out the node definition (aka, make - % the pdfdest) after any page break, but before the actual text has - % been typeset. If the destination for the pdf outline is after the - % text, then jumping from the outline may wind up with the text not - % being visible, for instance under high magnification. - \donoderef{#2}% - % - % Typeset the actual heading. - \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent=\wd0 \centerparametersmaybe - \unhbox0 #1\par}% - }% - \nobreak\bigskip % no page break after a chapter title - \nobreak -} - -% @centerchap -- centered and unnumbered. -\let\centerparametersmaybe = \relax -\def\centerparameters{% - \advance\rightskip by 3\rightskip - \leftskip = \rightskip - \parfillskip = 0pt -} - - -% I don't think this chapter style is supported any more, so I'm not -% updating it with the new noderef stuff. We'll see. --karl, 11aug03. -% -\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} -% -\def\unnchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\nobreak -} -\def\chfopen #1#2{\chapoddpage {\chapfonts -\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% -\par\penalty 5000 % -} -\def\centerchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt - \hfill {\rm #1}\hfill}}\bigskip \par\nobreak -} -\def\CHAPFopen{% - \global\let\chapmacro=\chfopen - \global\let\centerchapmacro=\centerchfopen} - - -% Section titles. These macros combine the section number parts and -% call the generic \sectionheading to do the printing. -% -\newskip\secheadingskip -\def\secheadingbreak{\dobreak \secheadingskip{-1000}} - -% Subsection titles. -\newskip\subsecheadingskip -\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}} - -% Subsubsection titles. -\def\subsubsecheadingskip{\subsecheadingskip} -\def\subsubsecheadingbreak{\subsecheadingbreak} - - -% Print any size, any type, section title. -% -% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is -% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the -% section number. -% -\def\sectionheading#1#2#3#4{% - {% - % Switch to the right set of fonts. - \csname #2fonts\endcsname \rm - % - % Insert space above the heading. - \csname #2headingbreak\endcsname - % - % Only insert the space after the number if we have a section number. - \def\sectionlevel{#2}% - \def\temptype{#3}% - % - \ifx\temptype\Ynothingkeyword - \setbox0 = \hbox{}% - \def\toctype{unn}% - \gdef\thissection{#1}% - \else\ifx\temptype\Yomitfromtockeyword - % for @headings -- no section number, don't include in toc, - % and don't redefine \thissection. - \setbox0 = \hbox{}% - \def\toctype{omit}% - \let\sectionlevel=\empty - \else\ifx\temptype\Yappendixkeyword - \setbox0 = \hbox{#4\enspace}% - \def\toctype{app}% - \gdef\thissection{#1}% - \else - \setbox0 = \hbox{#4\enspace}% - \def\toctype{num}% - \gdef\thissection{#1}% - \fi\fi\fi - % - % Write the toc entry (before \donoderef). See comments in \chapmacro. - \writetocentry{\toctype\sectionlevel}{#1}{#4}% - % - % Write the node reference (= pdf destination for pdftex). - % Again, see comments in \chapmacro. - \donoderef{#3}% - % - % Interline glue will be inserted when the vbox is completed. - % That glue will be a valid breakpoint for the page, since it'll be - % preceded by a whatsit (usually from the \donoderef, or from the - % \writetocentry if there was no node). We don't want to allow that - % break, since then the whatsits could end up on page n while the - % section is on page n+1, thus toc/etc. are wrong. Debian bug 276000. - \nobreak - % - % Output the actual section heading. - \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent=\wd0 % zero if no section number - \unhbox0 #1}% - }% - % Add extra space after the heading -- half of whatever came above it. - % Don't allow stretch, though. - \kern .5 \csname #2headingskip\endcsname - % - % Do not let the kern be a potential breakpoint, as it would be if it - % was followed by glue. - \nobreak - % - % We'll almost certainly start a paragraph next, so don't let that - % glue accumulate. (Not a breakpoint because it's preceded by a - % discardable item.) - \vskip-\parskip - % - % This is purely so the last item on the list is a known \penalty > - % 10000. This is so \startdefun can avoid allowing breakpoints after - % section headings. Otherwise, it would insert a valid breakpoint between: - % - % @section sec-whatever - % @deffn def-whatever - \penalty 10001 -} - - -\message{toc,} -% Table of contents. -\newwrite\tocfile - -% Write an entry to the toc file, opening it if necessary. -% Called from @chapter, etc. -% -% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno} -% We append the current node name (if any) and page number as additional -% arguments for the \{chap,sec,...}entry macros which will eventually -% read this. The node name is used in the pdf outlines as the -% destination to jump to. -% -% We open the .toc file for writing here instead of at @setfilename (or -% any other fixed time) so that @contents can be anywhere in the document. -% But if #1 is `omit', then we don't do anything. This is used for the -% table of contents chapter openings themselves. -% -\newif\iftocfileopened -\def\omitkeyword{omit}% -% -\def\writetocentry#1#2#3{% - \edef\writetoctype{#1}% - \ifx\writetoctype\omitkeyword \else - \iftocfileopened\else - \immediate\openout\tocfile = \jobname.toc - \global\tocfileopenedtrue - \fi - % - \iflinks - {\atdummies - \edef\temp{% - \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}% - \temp - }% - \fi - \fi - % - % Tell \shipout to create a pdf destination on each page, if we're - % writing pdf. These are used in the table of contents. We can't - % just write one on every page because the title pages are numbered - % 1 and 2 (the page numbers aren't printed), and so are the first - % two pages of the document. Thus, we'd have two destinations named - % `1', and two named `2'. - \ifpdf \global\pdfmakepagedesttrue \fi -} - - -% These characters do not print properly in the Computer Modern roman -% fonts, so we must take special care. This is more or less redundant -% with the Texinfo input format setup at the end of this file. -% -\def\activecatcodes{% - \catcode`\"=\active - \catcode`\$=\active - \catcode`\<=\active - \catcode`\>=\active - \catcode`\\=\active - \catcode`\^=\active - \catcode`\_=\active - \catcode`\|=\active - \catcode`\~=\active -} - - -% Read the toc file, which is essentially Texinfo input. -\def\readtocfile{% - \setupdatafile - \activecatcodes - \input \jobname.toc -} - -\newskip\contentsrightmargin \contentsrightmargin=1in -\newcount\savepageno -\newcount\lastnegativepageno \lastnegativepageno = -1 - -% Prepare to read what we've written to \tocfile. -% -\def\startcontents#1{% - % If @setchapternewpage on, and @headings double, the contents should - % start on an odd page, unlike chapters. Thus, we maintain - % \contentsalignmacro in parallel with \pagealignmacro. - % From: Torbjorn Granlund <tege@matematik.su.se> - \contentsalignmacro - \immediate\closeout\tocfile - % - % Don't need to put `Contents' or `Short Contents' in the headline. - % It is abundantly clear what they are. - \def\thischapter{}% - \chapmacro{#1}{Yomitfromtoc}{}% - % - \savepageno = \pageno - \begingroup % Set up to handle contents files properly. - \raggedbottom % Worry more about breakpoints than the bottom. - \advance\hsize by -\contentsrightmargin % Don't use the full line length. - % - % Roman numerals for page numbers. - \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi -} - - -% Normal (long) toc. -\def\contents{% - \startcontents{\putwordTOC}% - \openin 1 \jobname.toc - \ifeof 1 \else - \readtocfile - \fi - \vfill \eject - \contentsalignmacro % in case @setchapternewpage odd is in effect - \ifeof 1 \else - \pdfmakeoutlines - \fi - \closein 1 - \endgroup - \lastnegativepageno = \pageno - \global\pageno = \savepageno -} - -% And just the chapters. -\def\summarycontents{% - \startcontents{\putwordShortTOC}% - % - \let\numchapentry = \shortchapentry - \let\appentry = \shortchapentry - \let\unnchapentry = \shortunnchapentry - % We want a true roman here for the page numbers. - \secfonts - \let\rm=\shortcontrm \let\bf=\shortcontbf - \let\sl=\shortcontsl \let\tt=\shortconttt - \rm - \hyphenpenalty = 10000 - \advance\baselineskip by 1pt % Open it up a little. - \def\numsecentry##1##2##3##4{} - \let\appsecentry = \numsecentry - \let\unnsecentry = \numsecentry - \let\numsubsecentry = \numsecentry - \let\appsubsecentry = \numsecentry - \let\unnsubsecentry = \numsecentry - \let\numsubsubsecentry = \numsecentry - \let\appsubsubsecentry = \numsecentry - \let\unnsubsubsecentry = \numsecentry - \openin 1 \jobname.toc - \ifeof 1 \else - \readtocfile - \fi - \closein 1 - \vfill \eject - \contentsalignmacro % in case @setchapternewpage odd is in effect - \endgroup - \lastnegativepageno = \pageno - \global\pageno = \savepageno -} -\let\shortcontents = \summarycontents - -% Typeset the label for a chapter or appendix for the short contents. -% The arg is, e.g., `A' for an appendix, or `3' for a chapter. -% -\def\shortchaplabel#1{% - % This space should be enough, since a single number is .5em, and the - % widest letter (M) is 1em, at least in the Computer Modern fonts. - % But use \hss just in case. - % (This space doesn't include the extra space that gets added after - % the label; that gets put in by \shortchapentry above.) - % - % We'd like to right-justify chapter numbers, but that looks strange - % with appendix letters. And right-justifying numbers and - % left-justifying letters looks strange when there is less than 10 - % chapters. Have to read the whole toc once to know how many chapters - % there are before deciding ... - \hbox to 1em{#1\hss}% -} - -% These macros generate individual entries in the table of contents. -% The first argument is the chapter or section name. -% The last argument is the page number. -% The arguments in between are the chapter number, section number, ... - -% Chapters, in the main contents. -\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}} -% -% Chapters, in the short toc. -% See comments in \dochapentry re vbox and related settings. -\def\shortchapentry#1#2#3#4{% - \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}% -} - -% Appendices, in the main contents. -% Need the word Appendix, and a fixed-size box. -% -\def\appendixbox#1{% - % We use M since it's probably the widest letter. - \setbox0 = \hbox{\putwordAppendix{} M}% - \hbox to \wd0{\putwordAppendix{} #1\hss}} -% -\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}} - -% Unnumbered chapters. -\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}} -\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}} - -% Sections. -\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}} -\let\appsecentry=\numsecentry -\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}} - -% Subsections. -\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}} -\let\appsubsecentry=\numsubsecentry -\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}} - -% And subsubsections. -\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}} -\let\appsubsubsecentry=\numsubsubsecentry -\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}} - -% This parameter controls the indentation of the various levels. -% Same as \defaultparindent. -\newdimen\tocindent \tocindent = 15pt - -% Now for the actual typesetting. In all these, #1 is the text and #2 is the -% page number. -% -% If the toc has to be broken over pages, we want it to be at chapters -% if at all possible; hence the \penalty. -\def\dochapentry#1#2{% - \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip - \begingroup - \chapentryfonts - \tocentry{#1}{\dopageno\bgroup#2\egroup}% - \endgroup - \nobreak\vskip .25\baselineskip plus.1\baselineskip -} - -\def\dosecentry#1#2{\begingroup - \secentryfonts \leftskip=\tocindent - \tocentry{#1}{\dopageno\bgroup#2\egroup}% -\endgroup} - -\def\dosubsecentry#1#2{\begingroup - \subsecentryfonts \leftskip=2\tocindent - \tocentry{#1}{\dopageno\bgroup#2\egroup}% -\endgroup} - -\def\dosubsubsecentry#1#2{\begingroup - \subsubsecentryfonts \leftskip=3\tocindent - \tocentry{#1}{\dopageno\bgroup#2\egroup}% -\endgroup} - -% We use the same \entry macro as for the index entries. -\let\tocentry = \entry - -% Space between chapter (or whatever) number and the title. -\def\labelspace{\hskip1em \relax} - -\def\dopageno#1{{\rm #1}} -\def\doshortpageno#1{{\rm #1}} - -\def\chapentryfonts{\secfonts \rm} -\def\secentryfonts{\textfonts} -\def\subsecentryfonts{\textfonts} -\def\subsubsecentryfonts{\textfonts} - - -\message{environments,} -% @foo ... @end foo. - -% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. -% -% Since these characters are used in examples, it should be an even number of -% \tt widths. Each \tt character is 1en, so two makes it 1em. -% -\def\point{$\star$} -\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} -\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} -\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} -\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} - -% The @error{} command. -% Adapted from the TeXbook's \boxit. -% -\newbox\errorbox -% -{\tentt \global\dimen0 = 3em}% Width of the box. -\dimen2 = .55pt % Thickness of rules -% The text. (`r' is open on the right, `e' somewhat less so on the left.) -\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt} -% -\setbox\errorbox=\hbox to \dimen0{\hfil - \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. - \advance\hsize by -2\dimen2 % Rules. - \vbox{% - \hrule height\dimen2 - \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. - \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. - \kern3pt\vrule width\dimen2}% Space to right. - \hrule height\dimen2} - \hfil} -% -\def\error{\leavevmode\lower.7ex\copy\errorbox} - -% @tex ... @end tex escapes into raw Tex temporarily. -% One exception: @ is still an escape character, so that @end tex works. -% But \@ or @@ will get a plain tex @ character. - -\envdef\tex{% - \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 - \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 - \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie - \catcode `\%=14 - \catcode `\+=\other - \catcode `\"=\other - \catcode `\|=\other - \catcode `\<=\other - \catcode `\>=\other - \escapechar=`\\ - % - \let\b=\ptexb - \let\bullet=\ptexbullet - \let\c=\ptexc - \let\,=\ptexcomma - \let\.=\ptexdot - \let\dots=\ptexdots - \let\equiv=\ptexequiv - \let\!=\ptexexclam - \let\i=\ptexi - \let\indent=\ptexindent - \let\noindent=\ptexnoindent - \let\{=\ptexlbrace - \let\+=\tabalign - \let\}=\ptexrbrace - \let\/=\ptexslash - \let\*=\ptexstar - \let\t=\ptext - \let\frenchspacing=\plainfrenchspacing - % - \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% - \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% - \def\@{@}% -} -% There is no need to define \Etex. - -% Define @lisp ... @end lisp. -% @lisp environment forms a group so it can rebind things, -% including the definition of @end lisp (which normally is erroneous). - -% Amount to narrow the margins by for @lisp. -\newskip\lispnarrowing \lispnarrowing=0.4in - -% This is the definition that ^^M gets inside @lisp, @example, and other -% such environments. \null is better than a space, since it doesn't -% have any width. -\def\lisppar{\null\endgraf} - -% This space is always present above and below environments. -\newskip\envskipamount \envskipamount = 0pt - -% Make spacing and below environment symmetrical. We use \parskip here -% to help in doing that, since in @example-like environments \parskip -% is reset to zero; thus the \afterenvbreak inserts no space -- but the -% start of the next paragraph will insert \parskip. -% -\def\aboveenvbreak{{% - % =10000 instead of <10000 because of a special case in \itemzzz and - % \sectionheading, q.v. - \ifnum \lastpenalty=10000 \else - \advance\envskipamount by \parskip - \endgraf - \ifdim\lastskip<\envskipamount - \removelastskip - % it's not a good place to break if the last penalty was \nobreak - % or better ... - \ifnum\lastpenalty<10000 \penalty-50 \fi - \vskip\envskipamount - \fi - \fi -}} - -\let\afterenvbreak = \aboveenvbreak - -% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will -% also clear it, so that its embedded environments do the narrowing again. -\let\nonarrowing=\relax - -% @cartouche ... @end cartouche: draw rectangle w/rounded corners around -% environment contents. -\font\circle=lcircle10 -\newdimen\circthick -\newdimen\cartouter\newdimen\cartinner -\newskip\normbskip\newskip\normpskip\newskip\normlskip -\circthick=\fontdimen8\circle -% -\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth -\def\ctr{{\hskip 6pt\circle\char'010}} -\def\cbl{{\circle\char'012\hskip -6pt}} -\def\cbr{{\hskip 6pt\circle\char'011}} -\def\carttop{\hbox to \cartouter{\hskip\lskip - \ctl\leaders\hrule height\circthick\hfil\ctr - \hskip\rskip}} -\def\cartbot{\hbox to \cartouter{\hskip\lskip - \cbl\leaders\hrule height\circthick\hfil\cbr - \hskip\rskip}} -% -\newskip\lskip\newskip\rskip - -\envdef\cartouche{% - \ifhmode\par\fi % can't be in the midst of a paragraph. - \startsavinginserts - \lskip=\leftskip \rskip=\rightskip - \leftskip=0pt\rightskip=0pt % we want these *outside*. - \cartinner=\hsize \advance\cartinner by-\lskip - \advance\cartinner by-\rskip - \cartouter=\hsize - \advance\cartouter by 18.4pt % allow for 3pt kerns on either - % side, and for 6pt waste from - % each corner char, and rule thickness - \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip - % Flag to tell @lisp, etc., not to narrow margin. - \let\nonarrowing = t% - \vbox\bgroup - \baselineskip=0pt\parskip=0pt\lineskip=0pt - \carttop - \hbox\bgroup - \hskip\lskip - \vrule\kern3pt - \vbox\bgroup - \kern3pt - \hsize=\cartinner - \baselineskip=\normbskip - \lineskip=\normlskip - \parskip=\normpskip - \vskip -\parskip - \comment % For explanation, see the end of \def\group. -} -\def\Ecartouche{% - \ifhmode\par\fi - \kern3pt - \egroup - \kern3pt\vrule - \hskip\rskip - \egroup - \cartbot - \egroup - \checkinserts -} - - -% This macro is called at the beginning of all the @example variants, -% inside a group. -\def\nonfillstart{% - \aboveenvbreak - \hfuzz = 12pt % Don't be fussy - \sepspaces % Make spaces be word-separators rather than space tokens. - \let\par = \lisppar % don't ignore blank lines - \obeylines % each line of input is a line of output - \parskip = 0pt - \parindent = 0pt - \emergencystretch = 0pt % don't try to avoid overfull boxes - \ifx\nonarrowing\relax - \advance \leftskip by \lispnarrowing - \exdentamount=\lispnarrowing - \else - \let\nonarrowing = \relax - \fi - \let\exdent=\nofillexdent -} - -% If you want all examples etc. small: @set dispenvsize small. -% If you want even small examples the full size: @set dispenvsize nosmall. -% This affects the following displayed environments: -% @example, @display, @format, @lisp -% -\def\smallword{small} -\def\nosmallword{nosmall} -\let\SETdispenvsize\relax -\def\setnormaldispenv{% - \ifx\SETdispenvsize\smallword - \smallexamplefonts \rm - \fi -} -\def\setsmalldispenv{% - \ifx\SETdispenvsize\nosmallword - \else - \smallexamplefonts \rm - \fi -} - -% We often define two environments, @foo and @smallfoo. -% Let's do it by one command: -\def\makedispenv #1#2{ - \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2} - \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2} - \expandafter\let\csname E#1\endcsname \afterenvbreak - \expandafter\let\csname Esmall#1\endcsname \afterenvbreak -} - -% Define two synonyms: -\def\maketwodispenvs #1#2#3{ - \makedispenv{#1}{#3} - \makedispenv{#2}{#3} -} - -% @lisp: indented, narrowed, typewriter font; @example: same as @lisp. -% -% @smallexample and @smalllisp: use smaller fonts. -% Originally contributed by Pavel@xerox. -% -\maketwodispenvs {lisp}{example}{% - \nonfillstart - \tt\quoteexpand - \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special. - \gobble % eat return -} -% @display/@smalldisplay: same as @lisp except keep current font. -% -\makedispenv {display}{% - \nonfillstart - \gobble -} - -% @format/@smallformat: same as @display except don't narrow margins. -% -\makedispenv{format}{% - \let\nonarrowing = t% - \nonfillstart - \gobble -} - -% @flushleft: same as @format, but doesn't obey \SETdispenvsize. -\envdef\flushleft{% - \let\nonarrowing = t% - \nonfillstart - \gobble -} -\let\Eflushleft = \afterenvbreak - -% @flushright. -% -\envdef\flushright{% - \let\nonarrowing = t% - \nonfillstart - \advance\leftskip by 0pt plus 1fill - \gobble -} -\let\Eflushright = \afterenvbreak - - -% @quotation does normal linebreaking (hence we can't use \nonfillstart) -% and narrows the margins. We keep \parskip nonzero in general, since -% we're doing normal filling. So, when using \aboveenvbreak and -% \afterenvbreak, temporarily make \parskip 0. -% -\envdef\quotation{% - {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip - \parindent=0pt - % - % @cartouche defines \nonarrowing to inhibit narrowing at next level down. - \ifx\nonarrowing\relax - \advance\leftskip by \lispnarrowing - \advance\rightskip by \lispnarrowing - \exdentamount = \lispnarrowing - \else - \let\nonarrowing = \relax - \fi - \parsearg\quotationlabel -} - -% We have retained a nonzero parskip for the environment, since we're -% doing normal filling. -% -\def\Equotation{% - \par - \ifx\quotationauthor\undefined\else - % indent a bit. - \leftline{\kern 2\leftskip \sl ---\quotationauthor}% - \fi - {\parskip=0pt \afterenvbreak}% -} - -% If we're given an argument, typeset it in bold with a colon after. -\def\quotationlabel#1{% - \def\temp{#1}% - \ifx\temp\empty \else - {\bf #1: }% - \fi -} - - -% LaTeX-like @verbatim...@end verbatim and @verb{<char>...<char>} -% If we want to allow any <char> as delimiter, -% we need the curly braces so that makeinfo sees the @verb command, eg: -% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org -% -% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. -% -% [Knuth] p.344; only we need to do the other characters Texinfo sets -% active too. Otherwise, they get lost as the first character on a -% verbatim line. -\def\dospecials{% - \do\ \do\\\do\{\do\}\do\$\do\&% - \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% - \do\<\do\>\do\|\do\@\do+\do\"% -} -% -% [Knuth] p. 380 -\def\uncatcodespecials{% - \def\do##1{\catcode`##1=\other}\dospecials} -% -% [Knuth] pp. 380,381,391 -% Disable Spanish ligatures ?` and !` of \tt font -\begingroup - \catcode`\`=\active\gdef`{\relax\lq} -\endgroup -% -% Setup for the @verb command. -% -% Eight spaces for a tab -\begingroup - \catcode`\^^I=\active - \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }} -\endgroup -% -\def\setupverb{% - \tt % easiest (and conventionally used) font for verbatim - \def\par{\leavevmode\endgraf}% - \catcode`\`=\active - \tabeightspaces - % Respect line breaks, - % print special symbols as themselves, and - % make each space count - % must do in this order: - \obeylines \uncatcodespecials \sepspaces -} - -% Setup for the @verbatim environment -% -% Real tab expansion -\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount -% -\def\starttabbox{\setbox0=\hbox\bgroup} - -% Allow an option to not replace quotes with a regular directed right -% quote/apostrophe (char 0x27), but instead use the undirected quote -% from cmtt (char 0x0d). The undirected quote is ugly, so don't make it -% the default, but it works for pasting with more pdf viewers (at least -% evince), the lilypond developers report. xpdf does work with the -% regular 0x27. -% -\def\codequoteright{% - \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax - '% - \else - \char'15 - \fi -} -% -% and a similar option for the left quote char vs. a grave accent. -% Modern fonts display ASCII 0x60 as a grave accent, so some people like -% the code environments to do likewise. -% -\def\codequoteleft{% - \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax - `% - \else - \char'22 - \fi -} -% -\begingroup - \catcode`\^^I=\active - \gdef\tabexpand{% - \catcode`\^^I=\active - \def^^I{\leavevmode\egroup - \dimen0=\wd0 % the width so far, or since the previous tab - \divide\dimen0 by\tabw - \multiply\dimen0 by\tabw % compute previous multiple of \tabw - \advance\dimen0 by\tabw % advance to next multiple of \tabw - \wd0=\dimen0 \box0 \starttabbox - }% - } - \catcode`\'=\active - \gdef\rquoteexpand{\catcode\rquoteChar=\active \def'{\codequoteright}}% - % - \catcode`\`=\active - \gdef\lquoteexpand{\catcode\lquoteChar=\active \def`{\codequoteleft}}% - % - \gdef\quoteexpand{\rquoteexpand \lquoteexpand}% -\endgroup - -% start the verbatim environment. -\def\setupverbatim{% - \let\nonarrowing = t% - \nonfillstart - % Easiest (and conventionally used) font for verbatim - \tt - \def\par{\leavevmode\egroup\box0\endgraf}% - \catcode`\`=\active - \tabexpand - \quoteexpand - % Respect line breaks, - % print special symbols as themselves, and - % make each space count - % must do in this order: - \obeylines \uncatcodespecials \sepspaces - \everypar{\starttabbox}% -} - -% Do the @verb magic: verbatim text is quoted by unique -% delimiter characters. Before first delimiter expect a -% right brace, after last delimiter expect closing brace: -% -% \def\doverb'{'<char>#1<char>'}'{#1} -% -% [Knuth] p. 382; only eat outer {} -\begingroup - \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other - \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next] -\endgroup -% -\def\verb{\begingroup\setupverb\doverb} -% -% -% Do the @verbatim magic: define the macro \doverbatim so that -% the (first) argument ends when '@end verbatim' is reached, ie: -% -% \def\doverbatim#1@end verbatim{#1} -% -% For Texinfo it's a lot easier than for LaTeX, -% because texinfo's \verbatim doesn't stop at '\end{verbatim}': -% we need not redefine '\', '{' and '}'. -% -% Inspired by LaTeX's verbatim command set [latex.ltx] -% -\begingroup - \catcode`\ =\active - \obeylines % - % ignore everything up to the first ^^M, that's the newline at the end - % of the @verbatim input line itself. Otherwise we get an extra blank - % line in the output. - \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}% - % We really want {...\end verbatim} in the body of the macro, but - % without the active space; thus we have to use \xdef and \gobble. -\endgroup -% -\envdef\verbatim{% - \setupverbatim\doverbatim -} -\let\Everbatim = \afterenvbreak - - -% @verbatiminclude FILE - insert text of file in verbatim environment. -% -\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude} -% -\def\doverbatiminclude#1{% - {% - \makevalueexpandable - \setupverbatim - \input #1 - \afterenvbreak - }% -} - -% @copying ... @end copying. -% Save the text away for @insertcopying later. -% -% We save the uninterpreted tokens, rather than creating a box. -% Saving the text in a box would be much easier, but then all the -% typesetting commands (@smallbook, font changes, etc.) have to be done -% beforehand -- and a) we want @copying to be done first in the source -% file; b) letting users define the frontmatter in as flexible order as -% possible is very desirable. -% -\def\copying{\checkenv{}\begingroup\scanargctxt\docopying} -\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}} -% -\def\insertcopying{% - \begingroup - \parindent = 0pt % paragraph indentation looks wrong on title page - \scanexp\copyingtext - \endgroup -} - -\message{defuns,} -% @defun etc. - -\newskip\defbodyindent \defbodyindent=.4in -\newskip\defargsindent \defargsindent=50pt -\newskip\deflastargmargin \deflastargmargin=18pt - -% Start the processing of @deffn: -\def\startdefun{% - \ifnum\lastpenalty<10000 - \medbreak - \else - % If there are two @def commands in a row, we'll have a \nobreak, - % which is there to keep the function description together with its - % header. But if there's nothing but headers, we need to allow a - % break somewhere. Check specifically for penalty 10002, inserted - % by \defargscommonending, instead of 10000, since the sectioning - % commands also insert a nobreak penalty, and we don't want to allow - % a break between a section heading and a defun. - % - \ifnum\lastpenalty=10002 \penalty2000 \fi - % - % Similarly, after a section heading, do not allow a break. - % But do insert the glue. - \medskip % preceded by discardable penalty, so not a breakpoint - \fi - % - \parindent=0in - \advance\leftskip by \defbodyindent - \exdentamount=\defbodyindent -} - -\def\dodefunx#1{% - % First, check whether we are in the right environment: - \checkenv#1% - % - % As above, allow line break if we have multiple x headers in a row. - % It's not a great place, though. - \ifnum\lastpenalty=10002 \penalty3000 \fi - % - % And now, it's time to reuse the body of the original defun: - \expandafter\gobbledefun#1% -} -\def\gobbledefun#1\startdefun{} - -% \printdefunline \deffnheader{text} -% -\def\printdefunline#1#2{% - \begingroup - % call \deffnheader: - #1#2 \endheader - % common ending: - \interlinepenalty = 10000 - \advance\rightskip by 0pt plus 1fil - \endgraf - \nobreak\vskip -\parskip - \penalty 10002 % signal to \startdefun and \dodefunx - % Some of the @defun-type tags do not enable magic parentheses, - % rendering the following check redundant. But we don't optimize. - \checkparencounts - \endgroup -} - -\def\Edefun{\endgraf\medbreak} - -% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn; -% the only thing remainnig is to define \deffnheader. -% -\def\makedefun#1{% - \expandafter\let\csname E#1\endcsname = \Edefun - \edef\temp{\noexpand\domakedefun - \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}% - \temp -} - -% \domakedefun \deffn \deffnx \deffnheader -% -% Define \deffn and \deffnx, without parameters. -% \deffnheader has to be defined explicitly. -% -\def\domakedefun#1#2#3{% - \envdef#1{% - \startdefun - \parseargusing\activeparens{\printdefunline#3}% - }% - \def#2{\dodefunx#1}% - \def#3% -} - -%%% Untyped functions: - -% @deffn category name args -\makedefun{deffn}{\deffngeneral{}} - -% @deffn category class name args -\makedefun{defop}#1 {\defopon{#1\ \putwordon}} - -% \defopon {category on}class name args -\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } - -% \deffngeneral {subind}category name args -% -\def\deffngeneral#1#2 #3 #4\endheader{% - % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}. - \dosubind{fn}{\code{#3}}{#1}% - \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% -} - -%%% Typed functions: - -% @deftypefn category type name args -\makedefun{deftypefn}{\deftypefngeneral{}} - -% @deftypeop category class type name args -\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}} - -% \deftypeopon {category on}class type name args -\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } - -% \deftypefngeneral {subind}category type name args -% -\def\deftypefngeneral#1#2 #3 #4 #5\endheader{% - \dosubind{fn}{\code{#4}}{#1}% - \defname{#2}{#3}{#4}\defunargs{#5\unskip}% -} - -%%% Typed variables: - -% @deftypevr category type var args -\makedefun{deftypevr}{\deftypecvgeneral{}} - -% @deftypecv category class type var args -\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}} - -% \deftypecvof {category of}class type var args -\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} } - -% \deftypecvgeneral {subind}category type var args -% -\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{% - \dosubind{vr}{\code{#4}}{#1}% - \defname{#2}{#3}{#4}\defunargs{#5\unskip}% -} - -%%% Untyped variables: - -% @defvr category var args -\makedefun{defvr}#1 {\deftypevrheader{#1} {} } - -% @defcv category class var args -\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}} - -% \defcvof {category of}class var args -\def\defcvof#1#2 {\deftypecvof{#1}#2 {} } - -%%% Type: -% @deftp category name args -\makedefun{deftp}#1 #2 #3\endheader{% - \doind{tp}{\code{#2}}% - \defname{#1}{}{#2}\defunargs{#3\unskip}% -} - -% Remaining @defun-like shortcuts: -\makedefun{defun}{\deffnheader{\putwordDeffunc} } -\makedefun{defmac}{\deffnheader{\putwordDefmac} } -\makedefun{defspec}{\deffnheader{\putwordDefspec} } -\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} } -\makedefun{defvar}{\defvrheader{\putwordDefvar} } -\makedefun{defopt}{\defvrheader{\putwordDefopt} } -\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} } -\makedefun{defmethod}{\defopon\putwordMethodon} -\makedefun{deftypemethod}{\deftypeopon\putwordMethodon} -\makedefun{defivar}{\defcvof\putwordInstanceVariableof} -\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof} - -% \defname, which formats the name of the @def (not the args). -% #1 is the category, such as "Function". -% #2 is the return type, if any. -% #3 is the function name. -% -% We are followed by (but not passed) the arguments, if any. -% -\def\defname#1#2#3{% - % Get the values of \leftskip and \rightskip as they were outside the @def... - \advance\leftskip by -\defbodyindent - % - % How we'll format the type name. Putting it in brackets helps - % distinguish it from the body text that may end up on the next line - % just below it. - \def\temp{#1}% - \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi} - % - % Figure out line sizes for the paragraph shape. - % The first line needs space for \box0; but if \rightskip is nonzero, - % we need only space for the part of \box0 which exceeds it: - \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip - % The continuations: - \dimen2=\hsize \advance\dimen2 by -\defargsindent - % (plain.tex says that \dimen1 should be used only as global.) - \parshape 2 0in \dimen0 \defargsindent \dimen2 - % - % Put the type name to the right margin. - \noindent - \hbox to 0pt{% - \hfil\box0 \kern-\hsize - % \hsize has to be shortened this way: - \kern\leftskip - % Intentionally do not respect \rightskip, since we need the space. - }% - % - % Allow all lines to be underfull without complaint: - \tolerance=10000 \hbadness=10000 - \exdentamount=\defbodyindent - {% - % defun fonts. We use typewriter by default (used to be bold) because: - % . we're printing identifiers, they should be in tt in principle. - % . in languages with many accents, such as Czech or French, it's - % common to leave accents off identifiers. The result looks ok in - % tt, but exceedingly strange in rm. - % . we don't want -- and --- to be treated as ligatures. - % . this still does not fix the ?` and !` ligatures, but so far no - % one has made identifiers using them :). - \df \tt - \def\temp{#2}% return value type - \ifx\temp\empty\else \tclose{\temp} \fi - #3% output function name - }% - {\rm\enskip}% hskip 0.5 em of \tenrm - % - \boldbrax - % arguments will be output next, if any. -} - -% Print arguments in slanted roman (not ttsl), inconsistently with using -% tt for the name. This is because literal text is sometimes needed in -% the argument list (groff manual), and ttsl and tt are not very -% distinguishable. Prevent hyphenation at `-' chars. -% -\def\defunargs#1{% - % use sl by default (not ttsl), - % tt for the names. - \df \sl \hyphenchar\font=0 - % - % On the other hand, if an argument has two dashes (for instance), we - % want a way to get ttsl. Let's try @var for that. - \let\var=\ttslanted - #1% - \sl\hyphenchar\font=45 -} - -% We want ()&[] to print specially on the defun line. -% -\def\activeparens{% - \catcode`\(=\active \catcode`\)=\active - \catcode`\[=\active \catcode`\]=\active - \catcode`\&=\active -} - -% Make control sequences which act like normal parenthesis chars. -\let\lparen = ( \let\rparen = ) - -% Be sure that we always have a definition for `(', etc. For example, -% if the fn name has parens in it, \boldbrax will not be in effect yet, -% so TeX would otherwise complain about undefined control sequence. -{ - \activeparens - \global\let(=\lparen \global\let)=\rparen - \global\let[=\lbrack \global\let]=\rbrack - \global\let& = \& - - \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} - \gdef\magicamp{\let&=\amprm} -} - -\newcount\parencount - -% If we encounter &foo, then turn on ()-hacking afterwards -\newif\ifampseen -\def\amprm#1 {\ampseentrue{\bf\ }} - -\def\parenfont{% - \ifampseen - % At the first level, print parens in roman, - % otherwise use the default font. - \ifnum \parencount=1 \rm \fi - \else - % The \sf parens (in \boldbrax) actually are a little bolder than - % the contained text. This is especially needed for [ and ] . - \sf - \fi -} -\def\infirstlevel#1{% - \ifampseen - \ifnum\parencount=1 - #1% - \fi - \fi -} -\def\bfafterword#1 {#1 \bf} - -\def\opnr{% - \global\advance\parencount by 1 - {\parenfont(}% - \infirstlevel \bfafterword -} -\def\clnr{% - {\parenfont)}% - \infirstlevel \sl - \global\advance\parencount by -1 -} - -\newcount\brackcount -\def\lbrb{% - \global\advance\brackcount by 1 - {\bf[}% -} -\def\rbrb{% - {\bf]}% - \global\advance\brackcount by -1 -} - -\def\checkparencounts{% - \ifnum\parencount=0 \else \badparencount \fi - \ifnum\brackcount=0 \else \badbrackcount \fi -} -\def\badparencount{% - \errmessage{Unbalanced parentheses in @def}% - \global\parencount=0 -} -\def\badbrackcount{% - \errmessage{Unbalanced square braces in @def}% - \global\brackcount=0 -} - - -\message{macros,} -% @macro. - -% To do this right we need a feature of e-TeX, \scantokens, -% which we arrange to emulate with a temporary file in ordinary TeX. -\ifx\eTeXversion\undefined - \newwrite\macscribble - \def\scantokens#1{% - \toks0={#1}% - \immediate\openout\macscribble=\jobname.tmp - \immediate\write\macscribble{\the\toks0}% - \immediate\closeout\macscribble - \input \jobname.tmp - } -\fi - -\def\scanmacro#1{% - \begingroup - \newlinechar`\^^M - \let\xeatspaces\eatspaces - % Undo catcode changes of \startcontents and \doprintindex - % When called from @insertcopying or (short)caption, we need active - % backslash to get it printed correctly. Previously, we had - % \catcode`\\=\other instead. We'll see whether a problem appears - % with macro expansion. --kasal, 19aug04 - \catcode`\@=0 \catcode`\\=\active \escapechar=`\@ - % ... and \example - \spaceisspace - % - % Append \endinput to make sure that TeX does not see the ending newline. - % I've verified that it is necessary both for e-TeX and for ordinary TeX - % --kasal, 29nov03 - \scantokens{#1\endinput}% - \endgroup -} - -\def\scanexp#1{% - \edef\temp{\noexpand\scanmacro{#1}}% - \temp -} - -\newcount\paramno % Count of parameters -\newtoks\macname % Macro name -\newif\ifrecursive % Is it recursive? - -% List of all defined macros in the form -% \definedummyword\macro1\definedummyword\macro2... -% Currently is also contains all @aliases; the list can be split -% if there is a need. -\def\macrolist{} - -% Add the macro to \macrolist -\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname} -\def\addtomacrolistxxx#1{% - \toks0 = \expandafter{\macrolist\definedummyword#1}% - \xdef\macrolist{\the\toks0}% -} - -% Utility routines. -% This does \let #1 = #2, with \csnames; that is, -% \let \csname#1\endcsname = \csname#2\endcsname -% (except of course we have to play expansion games). -% -\def\cslet#1#2{% - \expandafter\let - \csname#1\expandafter\endcsname - \csname#2\endcsname -} - -% Trim leading and trailing spaces off a string. -% Concepts from aro-bend problem 15 (see CTAN). -{\catcode`\@=11 -\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }} -\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@} -\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @} -\def\unbrace#1{#1} -\unbrace{\gdef\trim@@@ #1 } #2@{#1} -} - -% Trim a single trailing ^^M off a string. -{\catcode`\^^M=\other \catcode`\Q=3% -\gdef\eatcr #1{\eatcra #1Q^^MQ}% -\gdef\eatcra#1^^MQ{\eatcrb#1Q}% -\gdef\eatcrb#1Q#2Q{#1}% -} - -% Macro bodies are absorbed as an argument in a context where -% all characters are catcode 10, 11 or 12, except \ which is active -% (as in normal texinfo). It is necessary to change the definition of \. - -% It's necessary to have hard CRs when the macro is executed. This is -% done by making ^^M (\endlinechar) catcode 12 when reading the macro -% body, and then making it the \newlinechar in \scanmacro. - -\def\scanctxt{% - \catcode`\"=\other - \catcode`\+=\other - \catcode`\<=\other - \catcode`\>=\other - \catcode`\@=\other - \catcode`\^=\other - \catcode`\_=\other - \catcode`\|=\other - \catcode`\~=\other -} - -\def\scanargctxt{% - \scanctxt - \catcode`\\=\other - \catcode`\^^M=\other -} - -\def\macrobodyctxt{% - \scanctxt - \catcode`\{=\other - \catcode`\}=\other - \catcode`\^^M=\other - \usembodybackslash -} - -\def\macroargctxt{% - \scanctxt - \catcode`\\=\other -} - -% \mbodybackslash is the definition of \ in @macro bodies. -% It maps \foo\ => \csname macarg.foo\endcsname => #N -% where N is the macro parameter number. -% We define \csname macarg.\endcsname to be \realbackslash, so -% \\ in macro replacement text gets you a backslash. - -{\catcode`@=0 @catcode`@\=@active - @gdef@usembodybackslash{@let\=@mbodybackslash} - @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname} -} -\expandafter\def\csname macarg.\endcsname{\realbackslash} - -\def\macro{\recursivefalse\parsearg\macroxxx} -\def\rmacro{\recursivetrue\parsearg\macroxxx} - -\def\macroxxx#1{% - \getargs{#1}% now \macname is the macname and \argl the arglist - \ifx\argl\empty % no arguments - \paramno=0% - \else - \expandafter\parsemargdef \argl;% - \fi - \if1\csname ismacro.\the\macname\endcsname - \message{Warning: redefining \the\macname}% - \else - \expandafter\ifx\csname \the\macname\endcsname \relax - \else \errmessage{Macro name \the\macname\space already defined}\fi - \global\cslet{macsave.\the\macname}{\the\macname}% - \global\expandafter\let\csname ismacro.\the\macname\endcsname=1% - \addtomacrolist{\the\macname}% - \fi - \begingroup \macrobodyctxt - \ifrecursive \expandafter\parsermacbody - \else \expandafter\parsemacbody - \fi} - -\parseargdef\unmacro{% - \if1\csname ismacro.#1\endcsname - \global\cslet{#1}{macsave.#1}% - \global\expandafter\let \csname ismacro.#1\endcsname=0% - % Remove the macro name from \macrolist: - \begingroup - \expandafter\let\csname#1\endcsname \relax - \let\definedummyword\unmacrodo - \xdef\macrolist{\macrolist}% - \endgroup - \else - \errmessage{Macro #1 not defined}% - \fi -} - -% Called by \do from \dounmacro on each macro. The idea is to omit any -% macro definitions that have been changed to \relax. -% -\def\unmacrodo#1{% - \ifx #1\relax - % remove this - \else - \noexpand\definedummyword \noexpand#1% - \fi -} - -% This makes use of the obscure feature that if the last token of a -% <parameter list> is #, then the preceding argument is delimited by -% an opening brace, and that opening brace is not consumed. -\def\getargs#1{\getargsxxx#1{}} -\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs} -\def\getmacname #1 #2\relax{\macname={#1}} -\def\getmacargs#1{\def\argl{#1}} - -% Parse the optional {params} list. Set up \paramno and \paramlist -% so \defmacro knows what to do. Define \macarg.blah for each blah -% in the params list, to be ##N where N is the position in that list. -% That gets used by \mbodybackslash (above). - -% We need to get `macro parameter char #' into several definitions. -% The technique used is stolen from LaTeX: let \hash be something -% unexpandable, insert that wherever you need a #, and then redefine -% it to # just before using the token list produced. -% -% The same technique is used to protect \eatspaces till just before -% the macro is used. - -\def\parsemargdef#1;{\paramno=0\def\paramlist{}% - \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,} -\def\parsemargdefxxx#1,{% - \if#1;\let\next=\relax - \else \let\next=\parsemargdefxxx - \advance\paramno by 1% - \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname - {\xeatspaces{\hash\the\paramno}}% - \edef\paramlist{\paramlist\hash\the\paramno,}% - \fi\next} - -% These two commands read recursive and nonrecursive macro bodies. -% (They're different since rec and nonrec macros end differently.) - -\long\def\parsemacbody#1@end macro% -{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% -\long\def\parsermacbody#1@end rmacro% -{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% - -% This defines the macro itself. There are six cases: recursive and -% nonrecursive macros of zero, one, and many arguments. -% Much magic with \expandafter here. -% \xdef is used so that macro definitions will survive the file -% they're defined in; @include reads the file inside a group. -\def\defmacro{% - \let\hash=##% convert placeholders to macro parameter chars - \ifrecursive - \ifcase\paramno - % 0 - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\scanmacro{\temp}}% - \or % 1 - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \noexpand\braceorline - \expandafter\noexpand\csname\the\macname xxx\endcsname}% - \expandafter\xdef\csname\the\macname xxx\endcsname##1{% - \egroup\noexpand\scanmacro{\temp}}% - \else % many - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \noexpand\csname\the\macname xx\endcsname}% - \expandafter\xdef\csname\the\macname xx\endcsname##1{% - \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% - \expandafter\expandafter - \expandafter\xdef - \expandafter\expandafter - \csname\the\macname xxx\endcsname - \paramlist{\egroup\noexpand\scanmacro{\temp}}% - \fi - \else - \ifcase\paramno - % 0 - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% - \or % 1 - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \noexpand\braceorline - \expandafter\noexpand\csname\the\macname xxx\endcsname}% - \expandafter\xdef\csname\the\macname xxx\endcsname##1{% - \egroup - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% - \else % many - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \expandafter\noexpand\csname\the\macname xx\endcsname}% - \expandafter\xdef\csname\the\macname xx\endcsname##1{% - \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% - \expandafter\expandafter - \expandafter\xdef - \expandafter\expandafter - \csname\the\macname xxx\endcsname - \paramlist{% - \egroup - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% - \fi - \fi} - -\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}} - -% \braceorline decides whether the next nonwhitespace character is a -% {. If so it reads up to the closing }, if not, it reads the whole -% line. Whatever was read is then fed to the next control sequence -% as an argument (by \parsebrace or \parsearg) -\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx} -\def\braceorlinexxx{% - \ifx\nchar\bgroup\else - \expandafter\parsearg - \fi \macnamexxx} - - -% @alias. -% We need some trickery to remove the optional spaces around the equal -% sign. Just make them active and then expand them all to nothing. -\def\alias{\parseargusing\obeyspaces\aliasxxx} -\def\aliasxxx #1{\aliasyyy#1\relax} -\def\aliasyyy #1=#2\relax{% - {% - \expandafter\let\obeyedspace=\empty - \addtomacrolist{#1}% - \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}% - }% - \next -} - - -\message{cross references,} - -\newwrite\auxfile - -\newif\ifhavexrefs % True if xref values are known. -\newif\ifwarnedxrefs % True if we warned once that they aren't known. - -% @inforef is relatively simple. -\def\inforef #1{\inforefzzz #1,,,,**} -\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, - node \samp{\ignorespaces#1{}}} - -% @node's only job in TeX is to define \lastnode, which is used in -% cross-references. The @node line might or might not have commas, and -% might or might not have spaces before the first comma, like: -% @node foo , bar , ... -% We don't want such trailing spaces in the node name. -% -\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse} -% -% also remove a trailing comma, in case of something like this: -% @node Help-Cross, , , Cross-refs -\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse} -\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}} - -\let\nwnode=\node -\let\lastnode=\empty - -% Write a cross-reference definition for the current node. #1 is the -% type (Ynumbered, Yappendix, Ynothing). -% -\def\donoderef#1{% - \ifx\lastnode\empty\else - \setref{\lastnode}{#1}% - \global\let\lastnode=\empty - \fi -} - -% @anchor{NAME} -- define xref target at arbitrary point. -% -\newcount\savesfregister -% -\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi} -\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} -\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} - -% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an -% anchor), which consists of three parts: -% 1) NAME-title - the current sectioning name taken from \thissection, -% or the anchor name. -% 2) NAME-snt - section number and type, passed as the SNT arg, or -% empty for anchors. -% 3) NAME-pg - the page number. -% -% This is called from \donoderef, \anchor, and \dofloat. In the case of -% floats, there is an additional part, which is not written here: -% 4) NAME-lof - the text as it should appear in a @listoffloats. -% -\def\setref#1#2{% - \pdfmkdest{#1}% - \iflinks - {% - \atdummies % preserve commands, but don't expand them - \edef\writexrdef##1##2{% - \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef - ##1}{##2}}% these are parameters of \writexrdef - }% - \toks0 = \expandafter{\thissection}% - \immediate \writexrdef{title}{\the\toks0 }% - \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. - \writexrdef{pg}{\folio}% will be written later, during \shipout - }% - \fi -} - -% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is -% the node name, #2 the name of the Info cross-reference, #3 the printed -% node name, #4 the name of the Info file, #5 the name of the printed -% manual. All but the node name can be omitted. -% -\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} -\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} -\def\ref#1{\xrefX[#1,,,,,,,]} -\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup - \unsepspaces - \def\printedmanual{\ignorespaces #5}% - \def\printedrefname{\ignorespaces #3}% - \setbox1=\hbox{\printedmanual\unskip}% - \setbox0=\hbox{\printedrefname\unskip}% - \ifdim \wd0 = 0pt - % No printed node name was explicitly given. - \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax - % Use the node name inside the square brackets. - \def\printedrefname{\ignorespaces #1}% - \else - % Use the actual chapter/section title appear inside - % the square brackets. Use the real section title if we have it. - \ifdim \wd1 > 0pt - % It is in another manual, so we don't have it. - \def\printedrefname{\ignorespaces #1}% - \else - \ifhavexrefs - % We know the real title if we have the xref values. - \def\printedrefname{\refx{#1-title}{}}% - \else - % Otherwise just copy the Info node name. - \def\printedrefname{\ignorespaces #1}% - \fi% - \fi - \fi - \fi - % - % Make link in pdf output. - \ifpdf - \leavevmode - \getfilename{#4}% - {\turnoffactive - % See comments at \activebackslashdouble. - {\activebackslashdouble \xdef\pdfxrefdest{#1}% - \backslashparens\pdfxrefdest}% - % - \ifnum\filenamelength>0 - \startlink attr{/Border [0 0 0]}% - goto file{\the\filename.pdf} name{\pdfxrefdest}% - \else - \startlink attr{/Border [0 0 0]}% - goto name{\pdfmkpgn{\pdfxrefdest}}% - \fi - }% - \linkcolor - \fi - % - % Float references are printed completely differently: "Figure 1.2" - % instead of "[somenode], p.3". We distinguish them by the - % LABEL-title being set to a magic string. - {% - % Have to otherify everything special to allow the \csname to - % include an _ in the xref name, etc. - \indexnofonts - \turnoffactive - \expandafter\global\expandafter\let\expandafter\Xthisreftitle - \csname XR#1-title\endcsname - }% - \iffloat\Xthisreftitle - % If the user specified the print name (third arg) to the ref, - % print it instead of our usual "Figure 1.2". - \ifdim\wd0 = 0pt - \refx{#1-snt}{}% - \else - \printedrefname - \fi - % - % if the user also gave the printed manual name (fifth arg), append - % "in MANUALNAME". - \ifdim \wd1 > 0pt - \space \putwordin{} \cite{\printedmanual}% - \fi - \else - % node/anchor (non-float) references. - % - % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not - % insert empty discretionaries after hyphens, which means that it will - % not find a line break at a hyphen in a node names. Since some manuals - % are best written with fairly long node names, containing hyphens, this - % is a loss. Therefore, we give the text of the node name again, so it - % is as if TeX is seeing it for the first time. - \ifdim \wd1 > 0pt - \putwordsection{} ``\printedrefname'' \putwordin{} \cite{\printedmanual}% - \else - % _ (for example) has to be the character _ for the purposes of the - % control sequence corresponding to the node, but it has to expand - % into the usual \leavevmode...\vrule stuff for purposes of - % printing. So we \turnoffactive for the \refx-snt, back on for the - % printing, back off for the \refx-pg. - {\turnoffactive - % Only output a following space if the -snt ref is nonempty; for - % @unnumbered and @anchor, it won't be. - \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% - \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi - }% - % output the `[mynode]' via a macro so it can be overridden. - \xrefprintnodename\printedrefname - % - % But we always want a comma and a space: - ,\space - % - % output the `page 3'. - \turnoffactive \putwordpage\tie\refx{#1-pg}{}% - \fi - \fi - \endlink -\endgroup} - -% This macro is called from \xrefX for the `[nodename]' part of xref -% output. It's a separate macro only so it can be changed more easily, -% since square brackets don't work well in some documents. Particularly -% one that Bob is working on :). -% -\def\xrefprintnodename#1{[#1]} - -% Things referred to by \setref. -% -\def\Ynothing{} -\def\Yomitfromtoc{} -\def\Ynumbered{% - \ifnum\secno=0 - \putwordChapter@tie \the\chapno - \else \ifnum\subsecno=0 - \putwordSection@tie \the\chapno.\the\secno - \else \ifnum\subsubsecno=0 - \putwordSection@tie \the\chapno.\the\secno.\the\subsecno - \else - \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno - \fi\fi\fi -} -\def\Yappendix{% - \ifnum\secno=0 - \putwordAppendix@tie @char\the\appendixno{}% - \else \ifnum\subsecno=0 - \putwordSection@tie @char\the\appendixno.\the\secno - \else \ifnum\subsubsecno=0 - \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno - \else - \putwordSection@tie - @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno - \fi\fi\fi -} - -% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. -% If its value is nonempty, SUFFIX is output afterward. -% -\def\refx#1#2{% - {% - \indexnofonts - \otherbackslash - \expandafter\global\expandafter\let\expandafter\thisrefX - \csname XR#1\endcsname - }% - \ifx\thisrefX\relax - % If not defined, say something at least. - \angleleft un\-de\-fined\angleright - \iflinks - \ifhavexrefs - \message{\linenumber Undefined cross reference `#1'.}% - \else - \ifwarnedxrefs\else - \global\warnedxrefstrue - \message{Cross reference values unknown; you must run TeX again.}% - \fi - \fi - \fi - \else - % It's defined, so just use it. - \thisrefX - \fi - #2% Output the suffix in any case. -} - -% This is the macro invoked by entries in the aux file. Usually it's -% just a \def (we prepend XR to the control sequence name to avoid -% collisions). But if this is a float type, we have more work to do. -% -\def\xrdef#1#2{% - \expandafter\gdef\csname XR#1\endcsname{#2}% remember this xref value. - % - % Was that xref control sequence that we just defined for a float? - \expandafter\iffloat\csname XR#1\endcsname - % it was a float, and we have the (safe) float type in \iffloattype. - \expandafter\let\expandafter\floatlist - \csname floatlist\iffloattype\endcsname - % - % Is this the first time we've seen this float type? - \expandafter\ifx\floatlist\relax - \toks0 = {\do}% yes, so just \do - \else - % had it before, so preserve previous elements in list. - \toks0 = \expandafter{\floatlist\do}% - \fi - % - % Remember this xref in the control sequence \floatlistFLOATTYPE, - % for later use in \listoffloats. - \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0{#1}}% - \fi -} - -% Read the last existing aux file, if any. No error if none exists. -% -\def\tryauxfile{% - \openin 1 \jobname.aux - \ifeof 1 \else - \readdatafile{aux}% - \global\havexrefstrue - \fi - \closein 1 -} - -\def\setupdatafile{% - \catcode`\^^@=\other - \catcode`\^^A=\other - \catcode`\^^B=\other - \catcode`\^^C=\other - \catcode`\^^D=\other - \catcode`\^^E=\other - \catcode`\^^F=\other - \catcode`\^^G=\other - \catcode`\^^H=\other - \catcode`\^^K=\other - \catcode`\^^L=\other - \catcode`\^^N=\other - \catcode`\^^P=\other - \catcode`\^^Q=\other - \catcode`\^^R=\other - \catcode`\^^S=\other - \catcode`\^^T=\other - \catcode`\^^U=\other - \catcode`\^^V=\other - \catcode`\^^W=\other - \catcode`\^^X=\other - \catcode`\^^Z=\other - \catcode`\^^[=\other - \catcode`\^^\=\other - \catcode`\^^]=\other - \catcode`\^^^=\other - \catcode`\^^_=\other - % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc. - % in xref tags, i.e., node names. But since ^^e4 notation isn't - % supported in the main text, it doesn't seem desirable. Furthermore, - % that is not enough: for node names that actually contain a ^ - % character, we would end up writing a line like this: 'xrdef {'hat - % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first - % argument, and \hat is not an expandable control sequence. It could - % all be worked out, but why? Either we support ^^ or we don't. - % - % The other change necessary for this was to define \auxhat: - % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter - % and then to call \auxhat in \setq. - % - \catcode`\^=\other - % - % Special characters. Should be turned off anyway, but... - \catcode`\~=\other - \catcode`\[=\other - \catcode`\]=\other - \catcode`\"=\other - \catcode`\_=\other - \catcode`\|=\other - \catcode`\<=\other - \catcode`\>=\other - \catcode`\$=\other - \catcode`\#=\other - \catcode`\&=\other - \catcode`\%=\other - \catcode`+=\other % avoid \+ for paranoia even though we've turned it off - % - % This is to support \ in node names and titles, since the \ - % characters end up in a \csname. It's easier than - % leaving it active and making its active definition an actual \ - % character. What I don't understand is why it works in the *value* - % of the xrdef. Seems like it should be a catcode12 \, and that - % should not typeset properly. But it works, so I'm moving on for - % now. --karl, 15jan04. - \catcode`\\=\other - % - % Make the characters 128-255 be printing characters. - {% - \count1=128 - \def\loop{% - \catcode\count1=\other - \advance\count1 by 1 - \ifnum \count1<256 \loop \fi - }% - }% - % - % @ is our escape character in .aux files, and we need braces. - \catcode`\{=1 - \catcode`\}=2 - \catcode`\@=0 -} - -\def\readdatafile#1{% -\begingroup - \setupdatafile - \input\jobname.#1 -\endgroup} - -\message{insertions,} -% including footnotes. - -\newcount \footnoteno - -% The trailing space in the following definition for supereject is -% vital for proper filling; pages come out unaligned when you do a -% pagealignmacro call if that space before the closing brace is -% removed. (Generally, numeric constants should always be followed by a -% space to prevent strange expansion errors.) -\def\supereject{\par\penalty -20000\footnoteno =0 } - -% @footnotestyle is meaningful for info output only. -\let\footnotestyle=\comment - -{\catcode `\@=11 -% -% Auto-number footnotes. Otherwise like plain. -\gdef\footnote{% - \let\indent=\ptexindent - \let\noindent=\ptexnoindent - \global\advance\footnoteno by \@ne - \edef\thisfootno{$^{\the\footnoteno}$}% - % - % In case the footnote comes at the end of a sentence, preserve the - % extra spacing after we do the footnote number. - \let\@sf\empty - \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi - % - % Remove inadvertent blank space before typesetting the footnote number. - \unskip - \thisfootno\@sf - \dofootnote -}% - -% Don't bother with the trickery in plain.tex to not require the -% footnote text as a parameter. Our footnotes don't need to be so general. -% -% Oh yes, they do; otherwise, @ifset (and anything else that uses -% \parseargline) fails inside footnotes because the tokens are fixed when -% the footnote is read. --karl, 16nov96. -% -\gdef\dofootnote{% - \insert\footins\bgroup - % We want to typeset this text as a normal paragraph, even if the - % footnote reference occurs in (for example) a display environment. - % So reset some parameters. - \hsize=\pagewidth - \interlinepenalty\interfootnotelinepenalty - \splittopskip\ht\strutbox % top baseline for broken footnotes - \splitmaxdepth\dp\strutbox - \floatingpenalty\@MM - \leftskip\z@skip - \rightskip\z@skip - \spaceskip\z@skip - \xspaceskip\z@skip - \parindent\defaultparindent - % - \smallfonts \rm - % - % Because we use hanging indentation in footnotes, a @noindent appears - % to exdent this text, so make it be a no-op. makeinfo does not use - % hanging indentation so @noindent can still be needed within footnote - % text after an @example or the like (not that this is good style). - \let\noindent = \relax - % - % Hang the footnote text off the number. Use \everypar in case the - % footnote extends for more than one paragraph. - \everypar = {\hang}% - \textindent{\thisfootno}% - % - % Don't crash into the line above the footnote text. Since this - % expands into a box, it must come within the paragraph, lest it - % provide a place where TeX can split the footnote. - \footstrut - \futurelet\next\fo@t -} -}%end \catcode `\@=11 - -% In case a @footnote appears in a vbox, save the footnote text and create -% the real \insert just after the vbox finished. Otherwise, the insertion -% would be lost. -% Similarily, if a @footnote appears inside an alignment, save the footnote -% text to a box and make the \insert when a row of the table is finished. -% And the same can be done for other insert classes. --kasal, 16nov03. - -% Replace the \insert primitive by a cheating macro. -% Deeper inside, just make sure that the saved insertions are not spilled -% out prematurely. -% -\def\startsavinginserts{% - \ifx \insert\ptexinsert - \let\insert\saveinsert - \else - \let\checkinserts\relax - \fi -} - -% This \insert replacement works for both \insert\footins{foo} and -% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}. -% -\def\saveinsert#1{% - \edef\next{\noexpand\savetobox \makeSAVEname#1}% - \afterassignment\next - % swallow the left brace - \let\temp = -} -\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}} -\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1} - -\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi} - -\def\placesaveins#1{% - \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname - {\box#1}% -} - -% eat @SAVE -- beware, all of them have catcode \other: -{ - \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-) - \gdef\gobblesave @SAVE{} -} - -% initialization: -\def\newsaveins #1{% - \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}% - \next -} -\def\newsaveinsX #1{% - \csname newbox\endcsname #1% - \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts - \checksaveins #1}% -} - -% initialize: -\let\checkinserts\empty -\newsaveins\footins -\newsaveins\margin - - -% @image. We use the macros from epsf.tex to support this. -% If epsf.tex is not installed and @image is used, we complain. -% -% Check for and read epsf.tex up front. If we read it only at @image -% time, we might be inside a group, and then its definitions would get -% undone and the next image would fail. -\openin 1 = epsf.tex -\ifeof 1 \else - % Do not bother showing banner with epsf.tex v2.7k (available in - % doc/epsf.tex and on ctan). - \def\epsfannounce{\toks0 = }% - \input epsf.tex -\fi -\closein 1 -% -% We will only complain once about lack of epsf.tex. -\newif\ifwarnednoepsf -\newhelp\noepsfhelp{epsf.tex must be installed for images to - work. It is also included in the Texinfo distribution, or you can get - it from ftp://tug.org/tex/epsf.tex.} -% -\def\image#1{% - \ifx\epsfbox\undefined - \ifwarnednoepsf \else - \errhelp = \noepsfhelp - \errmessage{epsf.tex not found, images will be ignored}% - \global\warnednoepsftrue - \fi - \else - \imagexxx #1,,,,,\finish - \fi -} -% -% Arguments to @image: -% #1 is (mandatory) image filename; we tack on .eps extension. -% #2 is (optional) width, #3 is (optional) height. -% #4 is (ignored optional) html alt text. -% #5 is (ignored optional) extension. -% #6 is just the usual extra ignored arg for parsing this stuff. -\newif\ifimagevmode -\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup - \catcode`\^^M = 5 % in case we're inside an example - \normalturnoffactive % allow _ et al. in names - % If the image is by itself, center it. - \ifvmode - \imagevmodetrue - \nobreak\bigskip - % Usually we'll have text after the image which will insert - % \parskip glue, so insert it here too to equalize the space - % above and below. - \nobreak\vskip\parskip - \nobreak - \line\bgroup - \fi - % - % Output the image. - \ifpdf - \dopdfimage{#1}{#2}{#3}% - \else - % \epsfbox itself resets \epsf?size at each figure. - \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi - \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi - \epsfbox{#1.eps}% - \fi - % - \ifimagevmode \egroup \bigbreak \fi % space after the image -\endgroup} - - -% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables, -% etc. We don't actually implement floating yet, we always include the -% float "here". But it seemed the best name for the future. -% -\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish} - -% There may be a space before second and/or third parameter; delete it. -\def\eatcommaspace#1, {#1,} - -% #1 is the optional FLOATTYPE, the text label for this float, typically -% "Figure", "Table", "Example", etc. Can't contain commas. If omitted, -% this float will not be numbered and cannot be referred to. -% -% #2 is the optional xref label. Also must be present for the float to -% be referable. -% -% #3 is the optional positioning argument; for now, it is ignored. It -% will somehow specify the positions allowed to float to (here, top, bottom). -% -% We keep a separate counter for each FLOATTYPE, which we reset at each -% chapter-level command. -\let\resetallfloatnos=\empty -% -\def\dofloat#1,#2,#3,#4\finish{% - \let\thiscaption=\empty - \let\thisshortcaption=\empty - % - % don't lose footnotes inside @float. - % - % BEWARE: when the floats start float, we have to issue warning whenever an - % insert appears inside a float which could possibly float. --kasal, 26may04 - % - \startsavinginserts - % - % We can't be used inside a paragraph. - \par - % - \vtop\bgroup - \def\floattype{#1}% - \def\floatlabel{#2}% - \def\floatloc{#3}% we do nothing with this yet. - % - \ifx\floattype\empty - \let\safefloattype=\empty - \else - {% - % the floattype might have accents or other special characters, - % but we need to use it in a control sequence name. - \indexnofonts - \turnoffactive - \xdef\safefloattype{\floattype}% - }% - \fi - % - % If label is given but no type, we handle that as the empty type. - \ifx\floatlabel\empty \else - % We want each FLOATTYPE to be numbered separately (Figure 1, - % Table 1, Figure 2, ...). (And if no label, no number.) - % - \expandafter\getfloatno\csname\safefloattype floatno\endcsname - \global\advance\floatno by 1 - % - {% - % This magic value for \thissection is output by \setref as the - % XREFLABEL-title value. \xrefX uses it to distinguish float - % labels (which have a completely different output format) from - % node and anchor labels. And \xrdef uses it to construct the - % lists of floats. - % - \edef\thissection{\floatmagic=\safefloattype}% - \setref{\floatlabel}{Yfloat}% - }% - \fi - % - % start with \parskip glue, I guess. - \vskip\parskip - % - % Don't suppress indentation if a float happens to start a section. - \restorefirstparagraphindent -} - -% we have these possibilities: -% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap -% @float Foo,lbl & no caption: Foo 1.1 -% @float Foo & @caption{Cap}: Foo: Cap -% @float Foo & no caption: Foo -% @float ,lbl & Caption{Cap}: 1.1: Cap -% @float ,lbl & no caption: 1.1 -% @float & @caption{Cap}: Cap -% @float & no caption: -% -\def\Efloat{% - \let\floatident = \empty - % - % In all cases, if we have a float type, it comes first. - \ifx\floattype\empty \else \def\floatident{\floattype}\fi - % - % If we have an xref label, the number comes next. - \ifx\floatlabel\empty \else - \ifx\floattype\empty \else % if also had float type, need tie first. - \appendtomacro\floatident{\tie}% - \fi - % the number. - \appendtomacro\floatident{\chaplevelprefix\the\floatno}% - \fi - % - % Start the printed caption with what we've constructed in - % \floatident, but keep it separate; we need \floatident again. - \let\captionline = \floatident - % - \ifx\thiscaption\empty \else - \ifx\floatident\empty \else - \appendtomacro\captionline{: }% had ident, so need a colon between - \fi - % - % caption text. - \appendtomacro\captionline{\scanexp\thiscaption}% - \fi - % - % If we have anything to print, print it, with space before. - % Eventually this needs to become an \insert. - \ifx\captionline\empty \else - \vskip.5\parskip - \captionline - % - % Space below caption. - \vskip\parskip - \fi - % - % If have an xref label, write the list of floats info. Do this - % after the caption, to avoid chance of it being a breakpoint. - \ifx\floatlabel\empty \else - % Write the text that goes in the lof to the aux file as - % \floatlabel-lof. Besides \floatident, we include the short - % caption if specified, else the full caption if specified, else nothing. - {% - \atdummies - % - % since we read the caption text in the macro world, where ^^M - % is turned into a normal character, we have to scan it back, so - % we don't write the literal three characters "^^M" into the aux file. - \scanexp{% - \xdef\noexpand\gtemp{% - \ifx\thisshortcaption\empty - \thiscaption - \else - \thisshortcaption - \fi - }% - }% - \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident - \ifx\gtemp\empty \else : \gtemp \fi}}% - }% - \fi - \egroup % end of \vtop - % - % place the captured inserts - % - % BEWARE: when the floats start floating, we have to issue warning - % whenever an insert appears inside a float which could possibly - % float. --kasal, 26may04 - % - \checkinserts -} - -% Append the tokens #2 to the definition of macro #1, not expanding either. -% -\def\appendtomacro#1#2{% - \expandafter\def\expandafter#1\expandafter{#1#2}% -} - -% @caption, @shortcaption -% -\def\caption{\docaption\thiscaption} -\def\shortcaption{\docaption\thisshortcaption} -\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption} -\def\defcaption#1#2{\egroup \def#1{#2}} - -% The parameter is the control sequence identifying the counter we are -% going to use. Create it if it doesn't exist and assign it to \floatno. -\def\getfloatno#1{% - \ifx#1\relax - % Haven't seen this figure type before. - \csname newcount\endcsname #1% - % - % Remember to reset this floatno at the next chap. - \expandafter\gdef\expandafter\resetallfloatnos - \expandafter{\resetallfloatnos #1=0 }% - \fi - \let\floatno#1% -} - -% \setref calls this to get the XREFLABEL-snt value. We want an @xref -% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we -% first read the @float command. -% -\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}% - -% Magic string used for the XREFLABEL-title value, so \xrefX can -% distinguish floats from other xref types. -\def\floatmagic{!!float!!} - -% #1 is the control sequence we are passed; we expand into a conditional -% which is true if #1 represents a float ref. That is, the magic -% \thissection value which we \setref above. -% -\def\iffloat#1{\expandafter\doiffloat#1==\finish} -% -% #1 is (maybe) the \floatmagic string. If so, #2 will be the -% (safe) float type for this float. We set \iffloattype to #2. -% -\def\doiffloat#1=#2=#3\finish{% - \def\temp{#1}% - \def\iffloattype{#2}% - \ifx\temp\floatmagic -} - -% @listoffloats FLOATTYPE - print a list of floats like a table of contents. -% -\parseargdef\listoffloats{% - \def\floattype{#1}% floattype - {% - % the floattype might have accents or other special characters, - % but we need to use it in a control sequence name. - \indexnofonts - \turnoffactive - \xdef\safefloattype{\floattype}% - }% - % - % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE. - \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax - \ifhavexrefs - % if the user said @listoffloats foo but never @float foo. - \message{\linenumber No `\safefloattype' floats to list.}% - \fi - \else - \begingroup - \leftskip=\tocindent % indent these entries like a toc - \let\do=\listoffloatsdo - \csname floatlist\safefloattype\endcsname - \endgroup - \fi -} - -% This is called on each entry in a list of floats. We're passed the -% xref label, in the form LABEL-title, which is how we save it in the -% aux file. We strip off the -title and look up \XRLABEL-lof, which -% has the text we're supposed to typeset here. -% -% Figures without xref labels will not be included in the list (since -% they won't appear in the aux file). -% -\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish} -\def\listoffloatsdoentry#1-title\finish{{% - % Can't fully expand XR#1-lof because it can contain anything. Just - % pass the control sequence. On the other hand, XR#1-pg is just the - % page number, and we want to fully expand that so we can get a link - % in pdf output. - \toksA = \expandafter{\csname XR#1-lof\endcsname}% - % - % use the same \entry macro we use to generate the TOC and index. - \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}% - \writeentry -}} - -\message{localization,} -% and i18n. - -% @documentlanguage is usually given very early, just after -% @setfilename. If done too late, it may not override everything -% properly. Single argument is the language abbreviation. -% It would be nice if we could set up a hyphenation file here. -% -\parseargdef\documentlanguage{% - \tex % read txi-??.tex file in plain TeX. - % Read the file if it exists. - \openin 1 txi-#1.tex - \ifeof 1 - \errhelp = \nolanghelp - \errmessage{Cannot read language file txi-#1.tex}% - \else - \input txi-#1.tex - \fi - \closein 1 - \endgroup -} -\newhelp\nolanghelp{The given language definition file cannot be found or -is empty. Maybe you need to install it? In the current directory -should work if nowhere else does.} - - -% @documentencoding should change something in TeX eventually, most -% likely, but for now just recognize it. -\let\documentencoding = \comment - - -% Page size parameters. -% -\newdimen\defaultparindent \defaultparindent = 15pt - -\chapheadingskip = 15pt plus 4pt minus 2pt -\secheadingskip = 12pt plus 3pt minus 2pt -\subsecheadingskip = 9pt plus 2pt minus 2pt - -% Prevent underfull vbox error messages. -\vbadness = 10000 - -% Don't be so finicky about underfull hboxes, either. -\hbadness = 2000 - -% Following George Bush, just get rid of widows and orphans. -\widowpenalty=10000 -\clubpenalty=10000 - -% Use TeX 3.0's \emergencystretch to help line breaking, but if we're -% using an old version of TeX, don't do anything. We want the amount of -% stretch added to depend on the line length, hence the dependence on -% \hsize. We call this whenever the paper size is set. -% -\def\setemergencystretch{% - \ifx\emergencystretch\thisisundefined - % Allow us to assign to \emergencystretch anyway. - \def\emergencystretch{\dimen0}% - \else - \emergencystretch = .15\hsize - \fi -} - -% Parameters in order: 1) textheight; 2) textwidth; -% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip; -% 7) physical page height; 8) physical page width. -% -% We also call \setleading{\textleading}, so the caller should define -% \textleading. The caller should also set \parskip. -% -\def\internalpagesizes#1#2#3#4#5#6#7#8{% - \voffset = #3\relax - \topskip = #6\relax - \splittopskip = \topskip - % - \vsize = #1\relax - \advance\vsize by \topskip - \outervsize = \vsize - \advance\outervsize by 2\topandbottommargin - \pageheight = \vsize - % - \hsize = #2\relax - \outerhsize = \hsize - \advance\outerhsize by 0.5in - \pagewidth = \hsize - % - \normaloffset = #4\relax - \bindingoffset = #5\relax - % - \ifpdf - \pdfpageheight #7\relax - \pdfpagewidth #8\relax - \fi - % - \setleading{\textleading} - % - \parindent = \defaultparindent - \setemergencystretch -} - -% @letterpaper (the default). -\def\letterpaper{{\globaldefs = 1 - \parskip = 3pt plus 2pt minus 1pt - \textleading = 13.2pt - % - % If page is nothing but text, make it come out even. - \internalpagesizes{46\baselineskip}{6in}% - {\voffset}{.25in}% - {\bindingoffset}{36pt}% - {11in}{8.5in}% -}} - -% Use @smallbook to reset parameters for 7x9.25 trim size. -\def\smallbook{{\globaldefs = 1 - \parskip = 2pt plus 1pt - \textleading = 12pt - % - \internalpagesizes{7.5in}{5in}% - {\voffset}{.25in}% - {\bindingoffset}{16pt}% - {9.25in}{7in}% - % - \lispnarrowing = 0.3in - \tolerance = 700 - \hfuzz = 1pt - \contentsrightmargin = 0pt - \defbodyindent = .5cm -}} - -% Use @smallerbook to reset parameters for 6x9 trim size. -% (Just testing, parameters still in flux.) -\def\smallerbook{{\globaldefs = 1 - \parskip = 1.5pt plus 1pt - \textleading = 12pt - % - \internalpagesizes{7.4in}{4.8in}% - {-.2in}{-.4in}% - {0pt}{14pt}% - {9in}{6in}% - % - \lispnarrowing = 0.25in - \tolerance = 700 - \hfuzz = 1pt - \contentsrightmargin = 0pt - \defbodyindent = .4cm -}} - -% Use @afourpaper to print on European A4 paper. -\def\afourpaper{{\globaldefs = 1 - \parskip = 3pt plus 2pt minus 1pt - \textleading = 13.2pt - % - % Double-side printing via postscript on Laserjet 4050 - % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm. - % To change the settings for a different printer or situation, adjust - % \normaloffset until the front-side and back-side texts align. Then - % do the same for \bindingoffset. You can set these for testing in - % your texinfo source file like this: - % @tex - % \global\normaloffset = -6mm - % \global\bindingoffset = 10mm - % @end tex - \internalpagesizes{51\baselineskip}{160mm} - {\voffset}{\hoffset}% - {\bindingoffset}{44pt}% - {297mm}{210mm}% - % - \tolerance = 700 - \hfuzz = 1pt - \contentsrightmargin = 0pt - \defbodyindent = 5mm -}} - -% Use @afivepaper to print on European A5 paper. -% From romildo@urano.iceb.ufop.br, 2 July 2000. -% He also recommends making @example and @lisp be small. -\def\afivepaper{{\globaldefs = 1 - \parskip = 2pt plus 1pt minus 0.1pt - \textleading = 12.5pt - % - \internalpagesizes{160mm}{120mm}% - {\voffset}{\hoffset}% - {\bindingoffset}{8pt}% - {210mm}{148mm}% - % - \lispnarrowing = 0.2in - \tolerance = 800 - \hfuzz = 1.2pt - \contentsrightmargin = 0pt - \defbodyindent = 2mm - \tableindent = 12mm -}} - -% A specific text layout, 24x15cm overall, intended for A4 paper. -\def\afourlatex{{\globaldefs = 1 - \afourpaper - \internalpagesizes{237mm}{150mm}% - {\voffset}{4.6mm}% - {\bindingoffset}{7mm}% - {297mm}{210mm}% - % - % Must explicitly reset to 0 because we call \afourpaper. - \globaldefs = 0 -}} - -% Use @afourwide to print on A4 paper in landscape format. -\def\afourwide{{\globaldefs = 1 - \afourpaper - \internalpagesizes{241mm}{165mm}% - {\voffset}{-2.95mm}% - {\bindingoffset}{7mm}% - {297mm}{210mm}% - \globaldefs = 0 -}} - -% @pagesizes TEXTHEIGHT[,TEXTWIDTH] -% Perhaps we should allow setting the margins, \topskip, \parskip, -% and/or leading, also. Or perhaps we should compute them somehow. -% -\parseargdef\pagesizes{\pagesizesyyy #1,,\finish} -\def\pagesizesyyy#1,#2,#3\finish{{% - \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi - \globaldefs = 1 - % - \parskip = 3pt plus 2pt minus 1pt - \setleading{\textleading}% - % - \dimen0 = #1 - \advance\dimen0 by \voffset - % - \dimen2 = \hsize - \advance\dimen2 by \normaloffset - % - \internalpagesizes{#1}{\hsize}% - {\voffset}{\normaloffset}% - {\bindingoffset}{44pt}% - {\dimen0}{\dimen2}% -}} - -% Set default to letter. -% -\letterpaper - - -\message{and turning on texinfo input format.} - -% Define macros to output various characters with catcode for normal text. -\catcode`\"=\other -\catcode`\~=\other -\catcode`\^=\other -\catcode`\_=\other -\catcode`\|=\other -\catcode`\<=\other -\catcode`\>=\other -\catcode`\+=\other -\catcode`\$=\other -\def\normaldoublequote{"} -\def\normaltilde{~} -\def\normalcaret{^} -\def\normalunderscore{_} -\def\normalverticalbar{|} -\def\normalless{<} -\def\normalgreater{>} -\def\normalplus{+} -\def\normaldollar{$}%$ font-lock fix - -% This macro is used to make a character print one way in \tt -% (where it can probably be output as-is), and another way in other fonts, -% where something hairier probably needs to be done. -% -% #1 is what to print if we are indeed using \tt; #2 is what to print -% otherwise. Since all the Computer Modern typewriter fonts have zero -% interword stretch (and shrink), and it is reasonable to expect all -% typewriter fonts to have this, we can check that font parameter. -% -\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi} - -% Same as above, but check for italic font. Actually this also catches -% non-italic slanted fonts since it is impossible to distinguish them from -% italic fonts. But since this is only used by $ and it uses \sl anyway -% this is not a problem. -\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi} - -% Turn off all special characters except @ -% (and those which the user can use as if they were ordinary). -% Most of these we simply print from the \tt font, but for some, we can -% use math or other variants that look better in normal text. - -\catcode`\"=\active -\def\activedoublequote{{\tt\char34}} -\let"=\activedoublequote -\catcode`\~=\active -\def~{{\tt\char126}} -\chardef\hat=`\^ -\catcode`\^=\active -\def^{{\tt \hat}} - -\catcode`\_=\active -\def_{\ifusingtt\normalunderscore\_} -\let\realunder=_ -% Subroutine for the previous macro. -\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em } - -\catcode`\|=\active -\def|{{\tt\char124}} -\chardef \less=`\< -\catcode`\<=\active -\def<{{\tt \less}} -\chardef \gtr=`\> -\catcode`\>=\active -\def>{{\tt \gtr}} -\catcode`\+=\active -\def+{{\tt \char 43}} -\catcode`\$=\active -\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix - -% If a .fmt file is being used, characters that might appear in a file -% name cannot be active until we have parsed the command line. -% So turn them off again, and have \everyjob (or @setfilename) turn them on. -% \otherifyactive is called near the end of this file. -\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} - -% Used sometimes to turn off (effectively) the active characters even after -% parsing them. -\def\turnoffactive{% - \normalturnoffactive - \otherbackslash -} - -\catcode`\@=0 - -% \backslashcurfont outputs one backslash character in current font, -% as in \char`\\. -\global\chardef\backslashcurfont=`\\ -\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work - -% \realbackslash is an actual character `\' with catcode other, and -% \doublebackslash is two of them (for the pdf outlines). -{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}} - -% In texinfo, backslash is an active character; it prints the backslash -% in fixed width font. -\catcode`\\=\active -@def@normalbackslash{{@tt@backslashcurfont}} -% On startup, @fixbackslash assigns: -% @let \ = @normalbackslash - -% \rawbackslash defines an active \ to do \backslashcurfont. -% \otherbackslash defines an active \ to be a literal `\' character with -% catcode other. -@gdef@rawbackslash{@let\=@backslashcurfont} -@gdef@otherbackslash{@let\=@realbackslash} - -% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of -% the literal character `\'. -% -@def@normalturnoffactive{% - @let\=@normalbackslash - @let"=@normaldoublequote - @let~=@normaltilde - @let^=@normalcaret - @let_=@normalunderscore - @let|=@normalverticalbar - @let<=@normalless - @let>=@normalgreater - @let+=@normalplus - @let$=@normaldollar %$ font-lock fix - @unsepspaces -} - -% Make _ and + \other characters, temporarily. -% This is canceled by @fixbackslash. -@otherifyactive - -% If a .fmt file is being used, we don't want the `\input texinfo' to show up. -% That is what \eatinput is for; after that, the `\' should revert to printing -% a backslash. -% -@gdef@eatinput input texinfo{@fixbackslash} -@global@let\ = @eatinput - -% On the other hand, perhaps the file did not have a `\input texinfo'. Then -% the first `\' in the file would cause an error. This macro tries to fix -% that, assuming it is called before the first `\' could plausibly occur. -% Also turn back on active characters that might appear in the input -% file name, in case not using a pre-dumped format. -% -@gdef@fixbackslash{% - @ifx\@eatinput @let\ = @normalbackslash @fi - @catcode`+=@active - @catcode`@_=@active -} - -% Say @foo, not \foo, in error messages. -@escapechar = `@@ - -% These look ok in all fonts, so just make them not special. -@catcode`@& = @other -@catcode`@# = @other -@catcode`@% = @other - - -@c Local variables: -@c eval: (add-hook 'write-file-hooks 'time-stamp) -@c page-delimiter: "^\\\\message" -@c time-stamp-start: "def\\\\texinfoversion{" -@c time-stamp-format: "%:y-%02m-%02d.%02H" -@c time-stamp-end: "}" -@c End: - -@c vim:sw=2: - -@ignore - arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115 -@end ignore diff --git a/plugins/MirOTR/libgcrypt-1.4.6/doc/version.texi b/plugins/MirOTR/libgcrypt-1.4.6/doc/version.texi deleted file mode 100644 index 294e4abcd0..0000000000 --- a/plugins/MirOTR/libgcrypt-1.4.6/doc/version.texi +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 9 July 2009 -@set UPDATED-MONTH July 2009 -@set EDITION 1.4.6 -@set VERSION 1.4.6 |
