diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 102 | ||||
| -rw-r--r-- | doc/Makefile.am | 28 | ||||
| -rw-r--r-- | doc/assuan.texi | 189 | ||||
| -rw-r--r-- | doc/contrib.texi | 124 | ||||
| -rw-r--r-- | doc/debugging.texi | 82 | ||||
| -rw-r--r-- | doc/fdl.texi | 401 | ||||
| -rw-r--r-- | doc/gnupg.texi | 174 | ||||
| -rw-r--r-- | doc/gpg-agent.texi | 791 | ||||
| -rw-r--r-- | doc/gpg.texi | 1806 | ||||
| -rw-r--r-- | doc/gpgsm.texi | 848 | ||||
| -rw-r--r-- | doc/gpl.texi | 397 | ||||
| -rw-r--r-- | doc/scdaemon.texi | 387 |
12 files changed, 0 insertions, 5329 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog deleted file mode 100644 index bcc288125..000000000 --- a/doc/ChangeLog +++ /dev/null @@ -1,102 +0,0 @@ -2004-06-18 Werner Koch <[email protected]> - - * debugging.texi: New. - * gnupg.texi: Include it. - -2004-05-11 Werner Koch <[email protected]> - - * gpgsm.texi (Esoteric Options): Add --debug-allow-core-dump. - -2004-05-03 Werner Koch <[email protected]> - - * gpg-agent.texi (Agent Options): Add --allow-mark-trusted. - -2004-02-03 Werner Koch <[email protected]> - - * contrib.texi (Contributors): Updated from the gpg 1.2.3 thanks - list. - * gpgsm.texi, gpg-agent.texi, scdaemon.texi: Language cleanups. - -2003-12-01 Werner Koch <[email protected]> - - * gpgsm.texi (Certificate Options): Add --{enable,disable}-ocsp. - -2003-11-17 Werner Koch <[email protected]> - - * scdaemon.texi (Scdaemon Options): Added --allow-admin and - --deny-admin. - -2003-10-27 Werner Koch <[email protected]> - - * gpg-agent.texi (Agent GET_CONFIRMATION): New. - -2002-12-04 Werner Koch <[email protected]> - - * gpg-agent.texi (Agent Signals): New. - -2002-12-03 Werner Koch <[email protected]> - - * gpgsm.texi (Operational Commands): Add --passwd and - --call-protect-tool. - * gpg-agent.texi (Agent PASSWD): New - -2002-11-13 Werner Koch <[email protected]> - - * gpg-agent.texi (Invoking GPG-AGENT): Tell about GPG_TTY. - -2002-11-12 Werner Koch <[email protected]> - - * gpgsm.texi (Operational Commands): Add --call-dirmngr. - -2002-09-25 Werner Koch <[email protected]> - - * gpg-agent.texi (Agent Options): Add --keep-tty and --keep-display. - -2002-09-12 Werner Koch <[email protected]> - - * gpg-agent.texi (Invoking GPG-AGENT): Explained how to start only - one instance. - -2002-08-28 Werner Koch <[email protected]> - - * gpg-agent.texi (Agent Options): Explained more options. - * scdaemon.texi (Scdaemon Options): Ditto. - -2002-08-09 Werner Koch <[email protected]> - - * Makefile.am (gnupg_TEXINFOS): Include contrib.texi. - -2002-08-06 Werner Koch <[email protected]> - - * gpgsm.texi: Added more options. - -2002-07-26 Werner Koch <[email protected]> - - * assuan.texi: New. - * gpgsm.texi, scdaemon.texi, gpg-agent.texi: Documented the Assuan - protocol used. - -2002-07-22 Werner Koch <[email protected]> - - * gnupg.texi, scdaemon.texi, gpg-agent.texi: New. - * contrib.texi, gpl.texi, fdl.texi: New. - * gpgsm.texi: Made this an include file for gnupg.texi. - * Makefile.am: Build gnupg.info instead of gpgsm.info. - -2002-06-04 Werner Koch <[email protected]> - - * gpgsm.texi (Invocation): Described the various debug flags. - -2002-05-14 Werner Koch <[email protected]> - - * Makefile.am, gpgsm.texi: New. - - Copyright 2002 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/doc/Makefile.am b/doc/Makefile.am deleted file mode 100644 index d1d72e834..000000000 --- a/doc/Makefile.am +++ /dev/null @@ -1,28 +0,0 @@ -# Copyright (C) 2002 Free Software Foundation, Inc. -# -# This file is part of GnuPG. -# -# GnuPG 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. -# -# GnuPG 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 - -## Process this file with automake to produce Makefile.in - -info_TEXINFOS = gnupg.texi - -gnupg_TEXINFOS = \ - gpgsm.texi gpg-agent.texi scdaemon.texi assuan.texi\ - debugging.texi contrib.texi gpl.texi fdl.texi - -DISTCLEANFILES = gnupg.tmp gnupg.ops - diff --git a/doc/assuan.texi b/doc/assuan.texi deleted file mode 100644 index 2e2219263..000000000 --- a/doc/assuan.texi +++ /dev/null @@ -1,189 +0,0 @@ -@c Copyright (C) 2002 Free Software Foundation, Inc. -@c This is part of the GnuPG manual. -@c For copying conditions, see the file gnupg.texi. - -@node Assuan -@chapter Description of the Assuan protocol. - -The architecture of the modular GnuPG system is based on a couple of -highly specialized modules which make up a network of client server -communication. A common framework for intermodule communication is -therefore needed and should be implemented in a library. - -Goals: - -@itemize @bullet -@item Common framework for module communication -@item Easy debugging -@item Easy module testing -@item Extendible -@item Optional authentication and encryption facility -@item Usable to access external hardware -@end itemize - - -Design criteria: - -@itemize @bullet -@item Client Server with back channel -@item Use a mainly text based protocol -@item Escape certain control characters -@item Allow indefinite data length -@item Request confidentiality for parts of the communication -@item Dummy module should allow direct linking of client and server. -@item Inline data or descriptor passing for bulk data -@item No protection against DoS needed -@item Subliminal channels are not an issue -@end itemize - -Implementation: - -The implementation is line based with a maximum line size of 1000 -octects. The default IPC mechanism are Unix Domain Sockets. - -On a connect request the server responds either with an okay or an error -status. For authentication check the server may send an Inquiry -Response prior to the first Okay, it may also issue Status messages. -The server must check that the client is allowed to connect, this is -done by requesting the credentials for the peer and comparing them to -those of the server. This avoids attacks based on wrong socket -permissions. - -It may choose to delay the first response in case of an error. The -server never closes the connection - however the lower protocol may do -so after some time of inactivity or when the connection is in an error -state. - -All textual messages are assumed to be in UTF-8 unless otherwise noted. - - -Server responses: - -@table @code -@item OK [<arbitary debugging information>] -Request was successful. - -@item ERR @var{errorcode} [<human readable error description>] -Request could not be fulfilled. The error codes are mostly application -specific except for a few common ones. - -@item S @var{keyword} <status information depending on keyword> -Informational output by the server, still processing the request. - -@item # <string> -Comment line issued only for debugging purposes. Totally ignored. - -@item D <raw data> -Raw data returned to client. There must be exactly one space after the -'D'. The values for '%', CR and LF must be percent escaped; this is -encoded as %25, %0D and %0A. Only uppercase letters should be used in -the hexadecimal representation. Other characters may be percent escaped -for easier debugging. All these Data lines are considered one data -stream up to the OK or ERR response. Status and Inquiry Responses -may be mixed with the Data lines. - -@item INQUIRE @var{keyword}> <parameters> -Server needs further information from the client. The client should -answer with a command which is allowed after an inquiry. Note that the -server does not confirm that client command but either continues -processing or ends processing with an error status. Not all commands -are allowed. -@end table - - -A client should only check the first letter of each line and then skip -over to the next token (except for data lines where the raw data starts -exactly after 2 bytes). Lines larger than 1000 bytes should be -treated as a communication error. (The rationale for having a line -length limit is to allow for easier multiplexing of multiple channels). - - -Client requests: - -The server waits for client requests after he sent an Okay or Error. -The client should not issue a request in other cases with the -exception of the CANCEL command. - -@example -@var{command} <parameters> -@end example - -@var{command} is a one word string without preceding white space. -Parameters are command specific, CR, LF and the percent signs should be -percent escaped as described above. To send a backslash as the last -character it should also be percent escaped. Percent escaping is -allowed anywhere in the parameters but not in the command. The line -ends with a CR, LF or just a LF. - -Not yet implemented feature: If there is a need for a parameter list -longer than the line length limit (1000 characters including command and -CR, LF), the last character of the line (right before the CR/LF or LF) -must be a non-escape encoded backslash. The following line is then -expected to be a continuation of the line with the backslash replaced by -a blank and the line ending removed. - -@example -D <raw data> -@end example - -Raw data to the server. There must be exactly one space after the 'D'. -The values for '%', CR and LF must be percent escaped; this is encoded -as %25, %0D and %0A. Only uppercase letters should be used in the -hexadecimal representation. Other characters may be percent escaped for -easier debugging. All these Data lines are considered one data stream -up to the OKAY or ERROR response. Status and Inquiry Responses may be -mixed with the Data lines. - -@example -END -@end example - - - -Lines beginning with a @code{#} or empty lines are ignored. This is -useful to comment test scripts. - - -Although the commands are application specific, some of them are used by -all protocols and partly directly supported by the Assuan library: - -@table @code -@item CANCEL -his is the one special command which aborts the current request. it can -be sent at any time and the server will stop its operation right before -it would send the next response line (of any type). - -@item BYE -Close the connect, the server will reply with an @code{OK}. - -@item AUTH -Not yet specified as we don't implement it in the first phase. See my -mail to gpa-dev on 2001-10-25 about the rationale for measurements -against local attacks. - -@item RESET -Reset the connection but not any existing authentication. The server -should release all resources associated with the connection. - -@item END -Used by a client to mark the end of raw data. The server may send END -to indicate a partial end of data. -@end table - - -Error Codes: - -Here we keep a list of error codes used in any Assuan based -protocol. The format is the string @code{ERR}, white space, the error -number, white space, a textual description of the error. - -@table @code - -@item 100 Unknown Command -@item 101 Not Implemented - -@item 301 certificate has been revoked [DirMngr] -@item 302 no CRL known for this certificate [DirMngr] -@item 303 CRL is too old and a new one could not be retrieved [DirMngr] - -@end table diff --git a/doc/contrib.texi b/doc/contrib.texi deleted file mode 100644 index 035b6c251..000000000 --- a/doc/contrib.texi +++ /dev/null @@ -1,124 +0,0 @@ -@c Copyright (C) 2002 Free Software Foundation, Inc. -@c This is part of the GnuPG manual. -@c For copying conditions, see the file gnupg.texi. - -@node Contributors -@unnumbered Contributors to GnuPG -@cindex contributors - -The GnuPG project would like to thank its many contributors. Without -them the project would not have been nearly as successful as it has -been. Any omissions in this list are accidental. Feel free to contact -the maintainer if you have been left out or some of your contributions -are not listed. Please keep this list in alphabetical order. - -@itemize @bullet - -@item -Bernhard Herzog did extensive testing and tracked down a lot of bugs - -@item -Bernhard Reiter made sure that we met the specifications and the -deadlines. He did extensive testing and came up with a lot of suggestions. - -@item -Jan-Oliver Wagner made sure that we met the specifications and the -deadlines. He did extensive testing and came up with a lot of suggestions. - -@item -Karl-Heinz Zimmer had to struggle with all the bugs and misconceptions -while working on Kmail integration. - -@item -Marcus Brinkman cleaned up the Assuan code and fixed bugs all over the place. - -@item -Steffen Hansen had a hard time to write the dirmngr due to -underspecified interfaces. - -@item -Thomas Koester did extensive testing and tracked down a lot of bugs - -@item -Werner Koch designed the system and wrote most of the original code. - -@end itemize - -We'd also like to thank these folks who have contributed a lot of time -and energy working on GnuPG over the years: - -David Shaw, Matthew Skala, Michael Roth, Niklas Hernaeus, Nils -Ellmenreich, R�mi Guyomarch, Stefan Bellon, Timo Schulz and Werner -Koch wrote the code. Birger Langkjer, Daniel Resare, Dokianakis -Theofanis, Edmund GRIMLEY EVANS, Ga�l Qu�ri, Gregory Steuck, Nagy -Ferenc L�szl�, Ivo Timmermans, Jacobo Tarri'o Barreiro, Janusz -Aleksander Urbanowicz, Jedi Lin, Jouni Hiltunen, Laurentiu Buzdugan, -Magda Procha'zkova', Michael Anckaert, Michal Majer, Marco d'Itri, -Nilgun Belma Buguner, Pedro Morais, Tedi Heriyanto, Thiago Jung -Bauermann, Rafael Caetano dos Santos, Toomas Soome, Urko Lusa, Walter -Koch, Yosiaki IIDA did the official translations. Mike Ashley wrote -and maintains the GNU Privacy Handbook. David Scribner is the current -FAQ editor. Lorenzo Cappelletti maintains the web site. - -The following people helped greatly by suggesting improvements, -testing, fixing bugs, providing resources and doing other important -tasks: Adam Mitchell, Albert Chin, Alec Habig, Allan Clark, Anand -Kumria, Andreas Haumer, Anthony Mulcahy, Ariel T Glenn, Bob Mathews, -Bodo Moeller, Brendan O'Dea, Brenno de Winter, Brian M. Carlson, Brian -Moore, Brian Warner, Bryan Fullerton, Caskey L. Dickson, Cees van de -Griend, Charles Levert, Chip Salzenberg, Chris Adams, Christian Biere, -Christian Kurz, Christian von Roques, Christopher Oliver, Christian -Recktenwald, Dan Winship, Daniel Eisenbud, Daniel Koening, Dave -Dykstra, David C Niemi, David Champion, David Ellement, David -Hallinan, David Hollenberg, David Mathog, David R. Bergstein, Detlef -Lannert, Dimitri, Dirk Lattermann, Dirk Meyer, Disastry, Douglas -Calvert, Ed Boraas, Edmund GRIMLEY EVANS, Edwin Woudt, Enzo -Michelangeli, Ernst Molitor, Fabio Coatti, Felix von Leitner, fish -stiqz, Florian Weimer, Francesco Potorti, Frank Donahoe, Frank -Heckenbach, Frank Stajano, Frank Tobin, Gabriel Rosenkoetter, Ga�l -Qu�ri, Gene Carter, Geoff Keating, Georg Schwarz, Giampaolo Tomassoni, -Gilbert Fernandes, Greg Louis, Greg Troxel, Gregory Steuck, Gregery -Barton, Harald Denker, Holger Baust, Hendrik Buschkamp, Holger -Schurig, Holger Smolinski, Holger Trapp, Hugh Daniel, Huy Le, Ian -McKellar, Ivo Timmermans, Jan Krueger, Jan Niehusmann, Janusz -A. Urbanowicz, James Troup, Jean-loup Gailly, Jeff Long, Jeffery Von -Ronne, Jens Bachem, Jeroen C. van Gelderen, J Horacio MG, J. Michael -Ashley, Jim Bauer, Jim Small, Joachim Backes, Joe Rhett, John -A. Martin, Johnny Teve�en, J�rg Schilling, Jos Backus, Joseph Walton, -Juan F. Codagnone, Jun Kuriyama, Kahil D. Jallad, Karl Fogel, Karsten -Thygesen, Katsuhiro Kondou, Kazu Yamamoto, Keith Clayton, Kevin Ryde, -Klaus Singvogel, Kurt Garloff, Lars Kellogg-Stedman, L. Sassaman, M -Taylor, Marcel Waldvogel, Marco d'Itri, Marco Parrone, Marcus -Brinkmann, Mark Adler, Mark Elbrecht, Mark Pettit, Markus Friedl, -Martin Kahlert, Martin Hamilton, Martin Schulte, Matt Kraai, Matthew -Skala, Matthew Wilcox, Matthias Urlichs, Max Valianskiy, Michael -Engels, Michael Fischer v. Mollard, Michael Roth, Michael Sobolev, -Michael Tokarev, Nicolas Graner, Mike McEwan, Neal H Walfield, Nelson -H. F. Beebe, NIIBE Yutaka, Niklas Hernaeus, Nimrod Zimerman, N J Doye, -Oliver Haakert, Oskari J��skel�inen, Pascal Scheffers, Paul D. Smith, -Per Cederqvist, Phil Blundell, Philippe Laliberte, Peter Fales, Peter -Gutmann, Peter Marschall, Peter Valchev, Piotr Krukowiecki, QingLong, -Ralph Gillen, Rat, Reinhard Wobst, R�mi Guyomarch, Reuben Sumner, -Richard Outerbridge, Robert Joop, Roddy Strachan, Roger Sondermann, -Roland Rosenfeld, Roman Pavlik, Ross Golder, Ryan Malayter, Sam -Roberts, Sami Tolvanen, Sean MacLennan, Sebastian Klemke, Serge -Munhoven, SL Baur, Stefan Bellon, Dr.Stefan.Dalibor, Stefan Karrmann, -Stefan Keller, Steffen Ullrich, Steffen Zahn, Steven Bakker, Steven -Murdoch, Susanne Schultz, Ted Cabeen, Thiago Jung Bauermann, Thijmen -Klok, Thomas Roessler, Tim Mooney, Timo Schulz, Todd Vierling, TOGAWA -Satoshi, Tom Spindler, Tom Zerucha, Tomas Fasth, Tommi Komulainen, -Thomas Klausner, Tomasz Kozlowski, Thomas Mikkelsen, Ulf M�ller, Urko -Lusa, Vincent P. Broman, Volker Quetschke, W Lewis, Walter Hofmann, -Walter Koch, Wayne Chapeskie, Wim Vandeputte, Winona Brown, Yosiaki -IIDA, Yoshihiro Kajiki and Gerlinde Klaes. - -This software has been made possible by the previous work of Chris -Wedgwood, Jean-loup Gailly, Jon Callas, Mark Adler, Martin Hellmann -Paul Kendall, Philip R. Zimmermann, Peter Gutmann, Philip A. Nelson, -Taher ElGamal, Torbjorn Granlund, Whitfield Diffie, some unknown NSA -mathematicians and all the folks who have worked hard to create -complete and free operating systems. - -And finally we'd like to thank everyone who uses these tools, submits -bug reports and generally reminds us why we're doing this work in the -first place. diff --git a/doc/debugging.texi b/doc/debugging.texi deleted file mode 100644 index e5e3e43fd..000000000 --- a/doc/debugging.texi +++ /dev/null @@ -1,82 +0,0 @@ -@c Copyright (C) 2004 Free Software Foundation, Inc. -@c This is part of the GnuPG manual. -@c For copying conditions, see the file gnupg.texi. - -@node Debugging -@chapter How to solve problems - -Everone knows that software often does not do what it should do and thus -there is a need to track down problems. We call this debugging in a -reminiscent to the moth jamming a relay in a Mark II box back in 1947. - -Most of the probelsm a merely configuration and user problems but -nevertheless there are the most annoying ones and reposnible for may -gray hairs. We try to give some guidelines here on how to identify and -solve the problem at hand. - - -@menu -* Debugging Tools:: Description of some useful tools - -@end menu - - -@node Debugging Tools -@section Debugging Tools - -The GnuPG distribution comes with a couple of tools, useful to help find -and solving problems. - -@menu -* kbxutil:: Scrutinizing a keybox file. -@end menu - -@node kbxutil -@subsection Scrutinizing a keybox file - -A keybox is a file fomat used to store public keys along with meta -information and indices. The commonly used one is the file -@file{pubring.kbx} in the @file{.gnupg} directory. It contains all -X.509 certificates as well as OpenPGP keys@footnote{Well, OpenPGP keys -are not implemented, @command{gpg} still used the keyring file -@file{pubring.gpg}} . - -@noindent -When called the standard way, e.g.: - -@samp{kbxutil ~/.gnupg/pubring.kbx} - -@noindent -it lists all records (called @acronym{blobs}) with there meta-information -in a human readable format. - -@noindent -To see statistics on the keybox in question, run it using - -@samp{kbxutil --stats ~/.gnupg/pubring.kbx} - -@noindent -and you get an output like: - -@example -Total number of blobs: 99 - header: 1 - empty: 0 - openpgp: 0 - x509: 98 - non flagged: 81 - secret flagged: 0 - ephemeral flagged: 17 -@end example - -In this example you see that the keybox does not have any OpenPGP keys -but contains 98 X.509 cerificates and a total of 17 keys or certificates -are flagges as ephemeral, meaning that they are only temporary stored -(cached) in the keybox and won't get listed using the usual commands -provided by @command{gpgsm} or @command{gpg}. 81 certifcates are stored -in a standard way and directly available from @command{gpgsm}. - - - - - diff --git a/doc/fdl.texi b/doc/fdl.texi deleted file mode 100644 index 6e40e6df9..000000000 --- a/doc/fdl.texi +++ /dev/null @@ -1,401 +0,0 @@ -@node GNU Free Documentation License -@appendix GNU Free Documentation License - -@cindex FDL, GNU Free Documentation License -@center Version 1.1, March 2000 - -@display -Copyright @copyright{} 2000 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 - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -written document @dfn{free} in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The ``Document'', below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as ``you''. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input format, -@acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed -for human modification. Opaque formats include PostScript, -@acronym{PDF}, proprietary formats that can be read and edited only by -proprietary word processors, @acronym{SGML} or @acronym{XML} for which -the @acronym{DTD} and/or processing tools are not generally available, -and the machine-generated @acronym{HTML} produced by some word -processors for output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has less than five). - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section entitled ``History'', and its title, and add to -it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -In any section entitled ``Acknowledgments'' or ``Dedications'', -preserve the section's title, and preserve in the section all the -substance and tone of each of the contributor acknowledgments -and/or dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section as ``Endorsements'' -or to conflict in title with any Invariant Section. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections entitled ``History'' -in the various original documents, forming one section entitled -``History''; likewise combine any sections entitled ``Acknowledgments'', -and any sections entitled ``Dedications''. You must delete all sections -entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an ``aggregate'', and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document 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 -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation 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. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. -@end enumerate - -@page -@appendixsubsec ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being @var{list their titles}, with the - Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have no Invariant Sections, write ``with no Invariant Sections'' -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write ``no Front-Cover Texts'' instead of -``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: diff --git a/doc/gnupg.texi b/doc/gnupg.texi deleted file mode 100644 index 58c995b38..000000000 --- a/doc/gnupg.texi +++ /dev/null @@ -1,174 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename gnupg.info - -@include version.texi - -@macro copyrightnotice -Copyright @copyright{} 2002 Free Software Foundation, Inc. -@end macro -@macro permissionnotice -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License'', the Front-Cover -texts being (a) (see below), and with the Back-Cover Texts being (b) -(see below). A copy of the license is included in the section entitled -``GNU Free Documentation License''. - -(a) The FSF's Front-Cover Text is: - - A GNU Manual - -(b) The FSF's Back-Cover Text is: - - You have freedom to copy and modify this GNU Manual, like GNU - software. Copies published by the Free Software Foundation raise - funds for GNU development. -@end macro - - -@settitle Using the GNU Privacy Guard - -@c Create a separate index for command line options. -@defcodeindex op -@c Merge the standard indexes into a single one. -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@syncodeindex pg cp -@syncodeindex tp cp - -@c printing stuff taken from gcc. -@macro gnupgtabopt{body} -@code{\body\} -@end macro -@macro gnupgoptlist{body} -@smallexample -\body\ -@end smallexample -@end macro -@c Makeinfo handles the above macro OK, TeX needs manual line breaks; -@c they get lost at some point in handling the macro. But if @macro is -@c used here rather than @alias, it produces double line breaks. -@iftex -@alias gol = * -@end iftex -@ifnottex -@macro gol -@end macro -@end ifnottex - - -@c Change the font used for @def... commands, since the default -@c proportional one used is bad for names starting __. -@tex -\global\setfont\defbf\ttbshape{10}{\magstep1} -@end tex - -@c %**end of header - -@ifnottex -@dircategory GNU Utilities -@direntry -* gpg: (gnupg). OpenPGP encryption and signing tool. -* gpgsm: (gnupg). S/MIME encryption and signing tool. -@end direntry -This file documents the use and the internals of the GNU Privacy Guard. - -This is Edition @value{EDITION}, last updated @value{UPDATED}, of -@cite{The `GNU Privacy Guard' Manual}, for Version @value{VERSION}. -@sp 1 -Published by the Free Software Foundation@* -59 Temple Place - Suite 330@* -Boston, MA 02111-1307 USA -@sp 1 -@copyrightnotice{} -@sp 1 -@permissionnotice{} -@end ifnottex - -@setchapternewpage odd - -@titlepage -@title Using the GNU Privacy Guard -@subtitle Version @value{VERSION} -@subtitle @value{UPDATED} -@author Werner Koch @code{(wk@@gnupg.org)} - -@page -@vskip 0pt plus 1filll -@copyrightnotice{} -@sp 2 -@permissionnotice{} -@end titlepage -@summarycontents -@contents -@page - - -@node Top -@top Introduction -@cindex introduction - -This manual documents how to use the GNU Privay Guard system as well as -the administration and the architecture. - -@c * Gpg:: Using the OpenPGP protocol. -@menu -* Invoking GPGSM:: Using the S/MIME protocol. -* Invoking GPG-AGENT:: How to launch the secret key daemon. -* Invoking SCDAEMON:: How to handle Smartcards. - -Developer information - -* Assuan:: Description of the Assuan protocol. - -Miscellaneous - -* Debugging:: How to solve problems -* Copying:: GNU General Public License says - how you can copy and share GnuPG -* GNU Free Documentation License:: How you can copy and share this manual. -* Contributors:: People who have contributed to GnuPG. - -Indices - -* Option Index:: Index to command line options. -* Index:: Index of concepts and symbol names. -@end menu - -@include gpgsm.texi -@include gpg-agent.texi -@include scdaemon.texi - -@include assuan.texi - -@include debugging.texi - -@include gpl.texi -@include fdl.texi - -@include contrib.texi - -@c --------------------------------------------------------------------- -@c Indexes -@c --------------------------------------------------------------------- - -@node Option Index -@unnumbered Option Index - -@printindex op - -@node Index -@unnumbered Index - -@printindex cp - -@c --------------------------------------------------------------------- -@c Epilogue -@c --------------------------------------------------------------------- - -@bye - - diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi deleted file mode 100644 index aad0fbb68..000000000 --- a/doc/gpg-agent.texi +++ /dev/null @@ -1,791 +0,0 @@ -@c Copyright (C) 2002 Free Software Foundation, Inc. -@c This is part of the GnuPG manual. -@c For copying conditions, see the file gnupg.texi. - -@node Invoking GPG-AGENT -@chapter Invoking GPG-AGENT -@cindex GPG-AGENT command options -@cindex command options -@cindex options, GPG-AGENT command - -@c man begin DESCRIPTION - -@sc{gpg-agent} is a daemon to manage secret (private) keys independelty -from any protocol. It is used as a backend for @sc{gpg} and @sc{gpgsm} -as well as for a couple of other utilities. - -@noindent -The usual way to run the agent is from the @code{~/.xsession} file: - -@example -eval `gpg-agent --daemon` -@end example - -@noindent -If you don't use an X server, you can also put this into your regular -startup file @code{~/.profile} or @code{.bash_profile}. It is best not -to run multiple instance of the gpg-agent, so you should make sure that -only is running: @sc{gpg-agent} uses an environment variable to inform -clients about the communication parameters. You can write the -content of this environment variable to a file so that you can test for -a running agent. This short script may do the job: - -@smallexample -if test -f $HOME/.gpg-agent-info && \ - kill -0 `cut -d: -f 2 $HOME/.gpg-agent-info` 2>/dev/null; then - GPG_AGENT_INFO=`cat $HOME/.gpg-agent-info` - export GPG_AGENT_INFO -else - eval `gpg-agent --daemon` - echo $GPG_AGENT_INFO >$HOME/.gpg-agent-info -fi -@end smallexample - -@noindent -If you want to use a curses based pinentry (which is usually also the -fallback mode for a GUI based pinentry), you should add these lines to -your @code{.bashrc} or whatever initialization file is used for all shell -invocations: - -@smallexample -GPG_TTY=`tty` -export GPG_TTY -@end smallexample - -It is important that this environment variable always reflects the -output of the @code{tty} command. - -@c man end - -@noindent -@xref{Option Index}, for an index to GPG-AGENTS's commands and options. - -@menu -* Agent Commands:: List of all commands. -* Agent Options:: List of all options. -* Agent Signals:: Use of some signals. -* Agent Examples:: Some usage examples. -* Agent Protocol:: The protocol the agent uses. -@end menu - -@c man begin COMMANDS - -@node Agent Commands -@section Commands - -Commands are not distinguished from options execpt for the fact that -only one one command is allowed. - -@table @gnupgtabopt -@item --version -@opindex version -Print the program version and licensing information. Not that you can -abbreviate this command. - -@item --help, -h -@opindex help -Print a usage message summarizing the most usefule command-line options. -Not that you can abbreviate this command. - -@item --dump-options -@opindex dump-options -Print a list of all available options and commands. Not that you can -abbreviate this command. - -@item --server -@opindex server -Run in server mode and wait for commands on the @code{stdin}. The -default mode is to create a socket and listen for commands there. - -@item --daemon -@opindex daemon -Run the program in the background. This option is required to prevent -it from being accidently running in the background. A common way to do -this is: -@example -@end example -$ eval `gpg-agent --daemon` -@end table - - -@c man begin OPTIONS - -@node Agent Options -@section Option Summary - -@table @gnupgtabopt - -@item --options @var{file} -@opindex options -Reads configuration from @var{file} instead of from the default -per-user configuration file. The default configuration file is named -@file{gpg-agent.conf} and expected in the @file{.gnupg} directory directly -below the home directory of the user. - -@item -v -@item --verbose -@opindex v -@opindex verbose -Outputs additional information while running. -You can increase the verbosity by giving several -verbose commands to @sc{gpgsm}, such as @samp{-vv}. - -@item -q -@item --quiet -@opindex q -@opindex quiet -Try to be as quiet as possible. - -@item --batch -@opindex batch -Don't invoke a pinentry or do any other thing requiring human interaction. - -@item --faked-system-time @var{epoch} -@opindex faked-system-time -This option is only useful for testing; it sets the system time back or -forth to @var{epoch} which is the number of seconds elapsed since the year -1970. - -@item --debug-level @var{level} -@opindex debug-level -Select the debug level for investigating problems. @var{level} may be -one of: - - @table @code - @item none - no debugging at all. - @item basic - some basic debug messages - @item advanced - more verbose debug messages - @item expert - even more detailed messages - @item guru - all of the debug messages you can get - @end table - -How these messages are mapped to the actual debugging flags is not -specified and may change with newer releaes of this program. They are -however carefully selected to best aid in debugging. - -@item --debug @var{flags} -@opindex debug -This option is only useful for debugging and the behaviour may change at -any time without notice. FLAGS are bit encoded and may be given in -usual C-Syntax. The currently defined bits are: - - @table @code - @item 0 (1) - X.509 or OpenPGP protocol related data - @item 1 (2) - values of big number integers - @item 2 (4) - low level crypto operations - @item 5 (32) - memory allocation - @item 6 (64) - caching - @item 7 (128) - show memory statistics. - @item 9 (512) - write hashed data to files named @code{dbgmd-000*} - @item 10 (1024) - trace Assuan protocol - @item 12 (4096) - bypass all certificate validation - @end table - -@item --debug-all -@opindex debug-all -Same as @code{--debug=0xffffffff} - -@item --debug-wait @var{n} -@opindex debug-wait -When running in server mode, wait @var{n} seconds before entering the -actual processing loop and print the pid. This gives time to attach a -debugger. - -@item --no-detach -@opindex no-detach -Don't detach the process from the console. This is manly usefule for -debugging. - -@item -s -@itemx --sh -@itemx -c -@itemx --csh -@opindex s -@opindex sh -@opindex c -@opindex csh -Format the info output in daemon mode for use with the standard Bourne -shell respective the C-shell . The default ist to guess it based on the -environment variable @code{SHELL} which is in almost all cases -sufficient. - -@item --no-grab -@opindex no-grab -Tell the pinentryo not to grab the keyboard and mouse. This option -should in general not be used to avaoid X-sniffing attacks. - -@item --log-file @var{file} -@opindex log-file -Append all logging output to @var{file}. This is very helpful in -seeing what the agent actually does. - -@item --disable-pth -@opindex disable-pth -Don't allow multiple connections. This option is in general not very -useful. - -@item --allow-mark-trusted -@opindex allow-mark-trusted -Allow clients to mark keys as trusted, i.e. put them into the -@code{trustlist.txt} file. This is by default not allowed to make it -harder for users to inadvertly accept Root-CA keys. - -@item --ignore-cache-for-signing -@opindex ignore-cache-for-signing -This option will let gpg-agent bypass the passphrase cache for all -signing operation. Note that there is also a per-session option to -control this behaviour but this command line option takes precedence. - -@item --default-cache-ttl @var{n} -@opindex default-cache-ttl -Set the time a cache entry is valid to @var{n} seconds. The default are -600 seconds. - -@item --pinentry-program @var{filename} -@opindex pinentry-program -Use program @var{filename} as the PIN entry. The default is installation -dependend and can be shown with the @code{--version} command. - -@item --scdaemon-program @var{filename} -@opindex scdaemon-program -Use program @var{filename} as the Smartcard daemon. The default is -installation dependend and can be shown with the @code{--version} -command. - - -@item --display @var{string} -@itemx --ttyname @var{string} -@itemx --ttytype @var{string} -@itemx --lc-type @var{string} -@itemx --lc-messages @var{string} -@opindex display -@opindex ttyname -@opindex ttytype -@opindex lc-type -@opindex lc-messa -These options are used with the server mode to pass localization -information. - -@item --keep-tty -@itemx --keep-display -@opindex keep-tty -@opindex keep-display -Ignore requests to change change the current @sc{tty} respective the X -window system's @code{DISPLAY} variable. This is useful to lock the -pinentry to pop up at the @sc{tty} or display you started the agent. - - -@end table - -All the long options may also be given in the configuration file after -stripping off the two leading dashes. - -@c -@c Agent Signals -@c -@node Agent Signals -@section Use of some signals. -A running @command{gpg-agent} may be controlled by signals, i.e. using -the @command{kill} command to send a signal to the process. - -Here is a list of supported signals: - -@table @gnupgtabopt - -@item SIGHUP -@cpindex SIGHUP -This signals flushes all chached passphrases and when the program was -started with a configuration file, the configuration file is read again. -Only certain options are honored: @code{quiet}, @code{verbose}, -@code{debug}, @code{debug-all}, @code{no-grab}, @code{pinentry-program}, -@code{default-cache-ttl} and @code{ignore-cache-for-signing}. -@code{scdaemon-program} is also supported but due to the current -implementation, which calls the scdaemon only once, it is not of much -use. - - -@item SIGTERM -@cpindex SIGTERM -Shuts down the process but waits until all current requests are -fulfilled. If the process has received 3 of these signals and requests -are still pending, a shutdown is forced. - -@item SIGINT -@cpindex SIGINT -Shuts down the process immediately. - - -@item SIGUSR1 -@itemx SIGUSR2 -@cpindex SIGUSR1 -@cpindex SIGUSR2 -These signals are used for internal purposes. - -@end table - -@c -@c Examples -@c -@node Agent Examples -@section Examples - -@c man begin EXAMPLES - -@example -$ eval `gpg-agent --daemon` -@end example - -@c man end - - -@c -@c Assuan Protocol -@c -@node Agent Protocol -@section Agent's Assuan Protocol - -The gpg-agent should be started by the login shell and set an -environment variable to tell clients about the socket to be used. -Clients should deny to access an agent with a socket name which does -not match its own configuration. An application may choose to start -an instance of the gpgagent if it does not figure that any has been -started; it should not do this if a gpgagent is running but not -usable. Because gpg-agent can only be used in background mode, no -special command line option is required to activate the use of the -protocol. - -To identify a key we use a thing called keygrip which is the SHA-1 hash -of an canoncical encoded S-Expression of the the public key as used in -Libgcrypt. For the purpose of this interface the keygrip is given as a -hex string. The advantage of using this and not the hash of a -certificate is that it will be possible to use the same keypair for -different protocols, thereby saving space on the token used to keep the -secret keys. - -@menu -* Agent PKDECRYPT:: Decrypting a session key -* Agent PKSIGN:: Signing a Hash -* Agent GENKEY:: Generating a Key -* Agent IMPORT:: Importing a Secret Key -* Agent EXPORT:: Exporting a Secret Key -* Agent ISTRUSTED:: Importing a Root Certificate -* Agent GET_PASSPHRASE:: Ask for a passphrase -* Agent GET_CONFIRMATION:: Ask for confirmation -* Agent HAVEKEY:: Check whether a key is available -* Agent LEARN:: Register a smartcard -* Agent PASSWD:: Change a Passphrase -@end menu - -@node Agent PKDECRYPT -@subsection Decrypting a session key - -The client asks the server to decrypt a session key. The encrypted -session key should have all information needed to select the -appropriate secret key or to delegate it to a smartcard. - -@example - SETKEY <keyGrip> -@end example - -Tell the server about the key to be used for decryption. If this is -not used, gpg-agent may try to figure out the key by trying to -decrypt the message with each key available. - -@example - PKDECRYPT -@end example - -The agent checks whether this command is allowed and then does an -INQUIRY to get the ciphertext the client should then send the cipher -text. - -@example - S: INQUIRE CIPHERTEXT - C: D (xxxxxx - C: D xxxx) - C: END -@end example - -Please note that the server may send status info lines while reading the -data lines from the client. The data send is a SPKI like S-Exp with -this structure: - -@example - (enc-val - (<algo> - (<param_name1> <mpi>) - ... - (<param_namen> <mpi>))) -@end example - -Where algo is a string with the name of the algorithm; see the libgcrypt -documentation for a list of valid algorithms. The number and names of -the parameters depend on the algorithm. The agent does return an error -if there is an inconsistency. - -If the decryption was successful the decrypted data is returned by -means of "D" lines. - -Here is an example session: - -@example - C: PKDECRYPT - S: INQUIRE CIPHERTEXT - C: D (enc-val elg (a 349324324) - C: D (b 3F444677CA))) - C: END - S: # session key follows - S: D 1234567890ABCDEF0 - S: OK descryption successful -@end example - - -@node Agent PKSIGN -@subsection Signing a Hash - -The client ask the agent to sign a given hash value. A default key -will be chosen if no key has been set. To set a key a client first -uses: - -@example - SIGKEY <keyGrip> -@end example - -This can be used multiple times to create multiple signature, the list -of keys is reset with the next PKSIGN command or a RESET. The server -test whether the key is a valid key to sign something and responds with -okay. - -@example - SETHASH <hexstring> -@end example - -The client can use this command to tell the server about the data -(which usually is a hash) to be signed. - -The actual signing is done using - -@example - PKSIGN <options> -@end example - -Options are not yet defined, but my later be used to choosen among -different algorithms (e.g. pkcs 1.5) - -The agent does then some checks, asks for the passphrase and -if SETHASH has not been used asks the client for the data to sign: - -@example - S: INQUIRE HASHVAL - C: D ABCDEF012345678901234 - C: END -@end example - -As a result the server returns the signature as an SPKI like S-Exp -in "D" lines: - -@example - (sig-val - (<algo> - (<param_name1> <mpi>) - ... - (<param_namen> <mpi>))) -@end example - - -The operation is affected by the option - -@example - OPTION use-cache-for-signing=0|1 -@end example - -The default of @code{1} uses the cache. Setting this option to @code{0} -will lead gpg-agent to ignore the passphrase cache. Note, that there is -also a global command line option for gpg-agent to globally disable the -caching. - - -Here is an example session: - -@example - C: SIGKEY <keyGrip> - S: OK key available - C: SIGKEY <keyGrip> - S: OK key available - C: PKSIGN - S: # I did ask the user whether he really wants to sign - S: # I did ask the user for the passphrase - S: INQUIRE HASHVAL - C: D ABCDEF012345678901234 - C: END - S: # signature follows - S: D (sig-val rsa (s 45435453654612121212)) - S: OK -@end example - - -@node Agent GENKEY -@subsection Generating a Key - -This is used to create a new keypair and store the secret key inside the -active PSE -w which is in most cases a Soft-PSE. An not yet defined -option allows to choose the storage location. To get the secret key out -of the PSE, a special export tool has to be used. - -@example - GENKEY -@end example - -Invokes the key generation process and the server will then inquire -on the generation parameters, like: - -@example - S: INQUIRE KEYPARM - C: D (genkey (rsa (nbits 1024))) - C: END -@end example - -The format of the key parameters which depends on the algorithm is of -the form: - -@example - (genkey - (algo - (parameter_name_1 ....) - .... - (parameter_name_n ....))) -@end example - -If everything succeeds, the server returns the *public key* in a SPKI -like S-Expression like this: - -@example - (public-key - (rsa - (n <mpi>) - (e <mpi>))) -@end example - -Here is an example session: - -@example - C: GENKEY - S: INQUIRE KEYPARM - C: D (genkey (rsa (nbits 1024))) - C: END - S: D (public-key - S: D (rsa (n 326487324683264) (e 10001))) - S OK key created -@end example - -@node Agent IMPORT -@subsection Importing a Secret Key - -This operation is not yet supportted by GpgAgent. Specialized tools -are to be used for this. - -There is no actual need because we can expect that secret keys -created by a 3rd party are stored on a smartcard. If we have -generated the key ourself, we do not need to import it. - -@node Agent EXPORT -@subsection Export a Secret Key - -Not implemented. - -Should be done by an extra tool. - -@node Agent ISTRUSTED -@subsection Importing a Root Certificate - -Actually we do not import a Root Cert but provide a way to validate -any piece of data by storing its Hash along with a description and -an identifier in the PSE. Here is the interface desription: - -@example - ISTRUSTED <fingerprint> -@end example - -Check whether the OpenPGP primary key or the X.509 certificate with the -given fingerprint is an ultimately trusted key or a trusted Root CA -certificate. The fingerprint should be given as a hexstring (without -any blanks or colons or whatever in between) and may be left padded with -00 in case of an MD5 fingerprint. GPGAgent will answer with: - -@example - OK -@end example - -The key is in the table of trusted keys. - -@example - ERR 304 (Not Trusted) -@end example - -The key is not in this table. - -Gpg needs the entire list of trusted keys to maintain the web of -trust; the following command is therefore quite helpful: - -@example - LISTTRUSTED -@end example - -GpgAgent returns a list of trusted keys line by line: - -@example - S: D 000000001234454556565656677878AF2F1ECCFF P - S: D 340387563485634856435645634856438576457A P - S: D FEDC6532453745367FD83474357495743757435D S - S: OK -@end example - -The first item on a line is the hexified fingerprint where MD5 -ingerprints are @code{00} padded to the left and the second item is a -flag to indicate the type of key (so that gpg is able to only take care -of PGP keys). P = OpenPGP, S = S/MIME. A client should ignore the rest -of the line, so that we can extend the format in the future. - -Finally a client should be able to mark a key as trusted: - -@example - MARKTRUSTED @var{fingerprint} "P"|"S" -@end example - -The server will then pop up a window to ask the user whether she -really trusts this key. For this it will probably ask for a text to -be displayed like this: - -@example - S: INQUIRE TRUSTDESC - C: D Do you trust the key with the fingerprint @@FPR@@ - C: D bla fasel blurb. - C: END - S: OK -@end example - -Known sequences with the pattern @@foo@@ are replaced according to this -table: - -@table @code -@item @@FPR16@@ -Format the fingerprint according to gpg rules for a v3 keys. -@item @@FPR20@@ -Format the fingerprint according to gpg rules for a v4 keys. -@item @@FPR@@ -Choose an appropriate format to format the fingerprint. -@item @@@@ -Replaced by a single @code{@@} -@end table - -@node Agent GET_PASSPHRASE -@subsection Ask for a passphrase - -This function is usually used to ask for a passphrase to be used for -conventional encryption, but may also be used by programs which need -special handling of passphrases. This command uses a syntax which helps -clients to use the agent with minimum effort. - -@example - GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}] -@end example - -@var{cache_id} is expected to be a hex string used for caching a -passphrase. Use a @code{X} to bypass the cache. With no other -arguments the agent returns a cached passphrase or an error. - -@var{error_message} is either a single @code{X} for no error message or -a string to be shown as an error message like (e.g. "invalid -passphrase"). Blanks must be percent escaped or replaced by @code{+}'. - -@var{prompt} is either a single @code{X} for a default prompt or the -text to be shown as the prompt. Blanks must be percent escaped or -replaced by @code{+}. - -@var{description} is a text shown above the entry field. Blanks must be -percent escaped or replaced by @code{+}. - -The agent either returns with an error or with a OK followed by the -hex encoded passphrase. Note that the length of the strings is -implicitly limited by the maximum length of a command. - -@example - CLEAR_PASSPHRASE @var{cache_id} -@end example - -may be used to invalidate the cache entry for a passphrase. The -function returns with OK even when there is no cached passphrase. - - -@node Agent GET_CONFIRMATION -@subsection Ask for confirmation - -This command may be used to ask for a simple confirmation by -presenting a text and 2 bottonts: Okay and Cancel. - -@example - GET_CONFIRMATION @var{description} -@end example - -@var{description}is displayed along with a Okay and Cancel -button. Blanks must be percent escaped or replaced by @code{+}. A -@code{X} may be used to display confirmation dialog with a default -text. - -The agent either returns with an error or with a OK. Note, that the -length of @var{description} is implicitly limited by the maximum -length of a command. - - - -@node Agent HAVEKEY -@subsection Check whether a key is available - -This can be used to see whether a secret key is available. It does -not return any information on whether the key is somehow protected. - -@example - HAVEKEY @var{keygrip} -@end example - -The Agent answers either with OK or @code{No_Secret_Key} (208). The -caller may want to check for other error codes as well. - - -@node Agent LEARN -@subsection Register a smartcard - -@example - LEARN [--send] -@end example - -This command is used to register a smartcard. With the --send -option given the certificates are send back. - - -@node Agent PASSWD -@subsection Change a Passphrase - -@example - PASSWD @var{keygrip} -@end example - -This command is used to interactively change the passphrase of the key -indentified by the hex string @var{keygrip}. - - - diff --git a/doc/gpg.texi b/doc/gpg.texi deleted file mode 100644 index 4ed4f1f76..000000000 --- a/doc/gpg.texi +++ /dev/null @@ -1,1806 +0,0 @@ -\input texinfo -@c This Texinfo document has been automatically generated by -@c docbook2texi from a DocBook documentation. The tool used -@c can be found at: -@c <URL:http://shell.ipoline.com/~elmert/hacks/docbook2X/> -@c Please send any bug reports, improvements, comments, -@c patches, etc. to Steve Cheng <[email protected]>. - -@setfilename gpg.info -@dircategory GnuPG -@direntry -* gpg: (gpg). GnuPG encryption and signing tool. -@end direntry - -@node top -@top gpg -@menu -@end menu - -@majorheading Name -gpg ---- encryption and signing tool</> - -@majorheading Synopsis - -@majorheading DESCRIPTION -@code{gpg} is the main program for the GnuPG system. - -This man page only lists the commands and options available. -For more verbose documentation get the GNU Privacy Handbook (GPH) or -one of the other documents at http://www.gnupg.org/docs.html . - -Please remember that option parsing stops as soon as a non option is -encountered, you can explicitly stop option parsing by using the -special option "---". - -@majorheading COMMANDS -@code{gpg} recognizes these commands: - -@table @asis -@item -s, ---sign -Make a signature. This command may be combined -with ---encrypt. - -@item ---clearsign -Make a clear text signature. - -@item -b, ---detach-sign -Make a detached signature. - -@item -e, ---encrypt -Encrypt data. This option may be combined with ---sign. - -@item -c, ---symmetric -Encrypt with a symmetric cipher using a passphrase. The default -symmetric cipher used is CAST5, but may be chosen with the ----cipher-algo option. - -@item ---store -Store only (make a simple RFC1991 packet). - -@item ---decrypt @code{file} -Decrypt @code{file} (or stdin if no file is specified) and -write it to stdout (or the file specified with ----output). If the decrypted file is signed, the -signature is also verified. This command differs -from the default operation, as it never writes to the -filename which is included in the file and it -rejects files which don't begin with an encrypted -message. - -@item ---verify @code{sigfile} @code{signed-files} -Assume that @code{sigfile} is a signature and verify it -without generating any output. With no arguments, -the signature packet is read from stdin. If -only a sigfile is given, it may be a complete -signature or a detached signature, in which case -the signed stuff is expected in a file without the -".sig" or ".asc" extension. -With more than -1 argument, the first should be a detached signature -and the remaining files are the signed stuff. To read the signed -stuff from stdin, use @samp{-} as the second filename. -For security reasons a detached signature cannot read the signed -material from stdin without denoting it in the above way. - -@item ---verify-files @code{files} -This is a special version of the ---verify command which does not work with -detached signatures. The command expects the files to be verified either -on the command line or reads the filenames from stdin; each name must be on -separate line. The command is intended for quick checking of many files. - -@item ---encrypt-files @code{files} -This is a special version of the ---encrypt command. The command expects -the files to be encrypted either on the command line or reads the filenames -from stdin; each name must be on separate line. The command is intended -for a quick encryption of multiple files. - -@item ---decrypt-files @code{files} -The same as ---encrypt-files with the difference that files will be -decrypted. The syntax or the filenames is the same. - -@item ---list-keys @code{names} -@itemx ---list-public-keys @code{names} -List all keys from the public keyrings, or just the ones given on the -command line. - -Avoid using the output of this command in scripts or other programs as -it is likely to change as GnuPG changes. See ---with-colons for a -machine-parseable key listing command that is appropriate for use in -scripts and other programs. - -@item ---list-secret-keys @code{names} -List all keys from the secret keyrings, or just the ones given on the -command line. A '#' after the letters 'sec' means that the secret key -is not usable (for example, if it was created via ----export-secret-subkeys). - -@item ---list-sigs @code{names} -Same as ---list-keys, but the signatures are listed too. - -For each signature listed, there are several flags in between the -"sig" tag and keyid. These flags give additional information about -each signature. From left to right, they are the numbers 1-3 for -certificate check level (see ---default-cert-check-level), "L" for a -local or non-exportable signature (see ---lsign-key), "R" for a -nonRevocable signature (see ---nrsign-key), "P" for a signature that -contains a policy URL (see ---cert-policy-url), "N" for a signature -that contains a notation (see ---cert-notation), "X" for an eXpired -signature (see ---ask-cert-expire), and the numbers 1-9 or "T" for 10 -and above to indicate trust signature levels (see the ---edit-key -command "tsign"). - -@item ---check-sigs @code{names} -Same as ---list-sigs, but the signatures are verified. - -@item ---fingerprint @code{names} -List all keys with their fingerprints. This is the -same output as ---list-keys but with the additional output -of a line with the fingerprint. May also be combined -with ---list-sigs or --check-sigs. -If this command is given twice, the fingerprints of all -secondary keys are listed too. - -@item ---list-packets -List only the sequence of packets. This is mainly -useful for debugging. - -@item ---gen-key -Generate a new key pair. This command is normally only used -interactively. - -There is an experimental feature which allows you to create keys -in batch mode. See the file @file{doc/DETAILS} -in the source distribution on how to use this. - -@item ---edit-key @code{name} -Present a menu which enables you to do all key -related tasks: - -@table @asis -@item sign -Make a signature on key of user @code{name} -If the key is not yet signed by the default -user (or the users given with -u), the -program displays the information of the key -again, together with its fingerprint and -asks whether it should be signed. This -question is repeated for all users specified -with -u. - -@item lsign -Same as ---sign but the signature is marked as -non-exportable and will therefore never be used -by others. This may be used to make keys valid -only in the local environment. - -@item nrsign -Same as ---sign but the signature is marked as non-revocable and can -therefore never be revoked. - -@item nrlsign -Combines the functionality of nrsign and lsign to make a signature -that is both non-revocable and -non-exportable. - -@item tsign -Make a trust signature. This is a signature that combines the notions -of certification (like a regular signature), and trust (like the -"trust" command). It is generally only useful in distinct communities -or groups. - -@item revsig -Revoke a signature. For every signature which has been generated by -one of the secret keys, GnuPG asks whether a revocation certificate -should be generated. - -@item trust -Change the owner trust value. This updates the -trust-db immediately and no save is required. - -@item disable -@itemx enable -Disable or enable an entire key. A disabled key can not normally be -used for encryption. - -@item adduid -Create an alternate user id. - -@item addphoto -Create a photographic user id. This will prompt for a JPEG file that -will be embedded into the user ID. A very large JPEG will make for a -very large key. - -@item deluid -Delete a user id. - -@item revuid -Revoke a user id. - -@item addkey -Add a subkey to this key. - -@item delkey -Remove a subkey. - -@item addrevoker -Add a designated revoker. This takes one optional argument: -"sensitive". If a designated revoker is marked as sensitive, it will -not be exported by default (see -export-options). - -@item revkey -Revoke a subkey. - -@item expire -Change the key expiration time. If a subkey is selected, the -expiration time of this subkey will be changed. With no selection, -the key expiration of the primary key is changed. - -@item passwd -Change the passphrase of the secret key. - -@item primary -Flag the current user id as the primary one, removes the primary user -id flag from all other user ids and sets the timestamp of all affected -self-signatures one second ahead. Note that setting a photo user ID -as primary makes it primary over other photo user IDs, and setting a -regular user ID as primary makes it primary over other regular user -IDs. - -@item uid @code{n} -Toggle selection of user id with index @code{n}. -Use 0 to deselect all. - -@item key @code{n} -Toggle selection of subkey with index @code{n}. -Use 0 to deselect all. - -@item check -Check all selected user ids. - -@item showphoto -Display the selected photographic user -id. - -@item pref -List preferences from the selected user ID. This shows the actual -preferences, without including any implied preferences. - -@item showpref -More verbose preferences listing for the selected user ID. This shows -the preferences in effect by including the implied preferences of -3DES (cipher), SHA-1 (digest), and Uncompressed (compression) if they -are not already included in the preference list. - -@item setpref @code{string} -Set the list of user ID preferences to @code{string}, this should be a -string similar to the one printed by "pref". Using an empty string -will set the default preference string, using "none" will set the -preferences to nil. Use "gpg ---version" to get a list of available -algorithms. This command just initializes an internal list and does -not change anything unless another command (such as "updpref") which -changes the self-signatures is used. - -@item updpref -Change the preferences of all user IDs (or just of the selected ones -to the current list of preferences. The timestamp of all affected -self-signatures will be advanced by one second. Note that while you -can change the preferences on an attribute user ID (aka "photo ID"), -GnuPG does not select keys via attribute user IDs so these preferences -will not be used by GnuPG. - -@item toggle -Toggle between public and secret key listing. - -@item save -Save all changes to the key rings and quit. - -@item quit -Quit the program without updating the -key rings. - -@end table - -The listing shows you the key with its secondary -keys and all user ids. Selected keys or user ids -are indicated by an asterisk. The trust value is -displayed with the primary key: the first is the -assigned owner trust and the second is the calculated -trust value. Letters are used for the values: - -@table @asis -@item - -No ownertrust assigned / not yet calculated. - -@item e -Trust -calculation has failed; probably due to an expired key. - -@item q -Not enough information for calculation. - -@item n -Never trust this key. - -@item m -Marginally trusted. - -@item f -Fully trusted. - -@item u -Ultimately trusted. - -@end table - -@item ---sign-key @code{name} -Signs a public key with your secret key. This is a shortcut version of -the subcommand "sign" from ---edit. - -@item ---lsign-key @code{name} -Signs a public key with your secret key but marks it as -non-exportable. This is a shortcut version of the subcommand "lsign" -from ---edit. - -@item ---nrsign-key @code{name} -Signs a public key with your secret key but marks it as non-revocable. -This is a shortcut version of the subcommand "nrsign" from ---edit. - -@item ---delete-key @code{name} -Remove key from the public keyring. In batch mode either ---yes is -required or the key must be specified by fingerprint. This is a -safeguard against accidental deletion of multiple keys. - -@item ---delete-secret-key @code{name} -Remove key from the secret and public keyring. In batch mode the key -must be specified by fingerprint. - -@item ---delete-secret-and-public-key @code{name} -Same as ---delete-key, but if a secret key exists, it will be removed -first. In batch mode the key must be specified by fingerprint. - -@item ---gen-revoke -Generate a revocation certificate for the complete key. To revoke -a subkey or a signature, use the ---edit command. - -@item ---desig-revoke -Generate a designated revocation certificate for a key. This allows a -user (with the permission of the keyholder) to revoke someone else's -key. - -@item ---export @code{names} -Either export all keys from all keyrings (default -keyrings and those registered via option ---keyring), -or if at least one name is given, those of the given -name. The new keyring is written to stdout or to -the file given with option "output". Use together -with ---armor to mail those keys. - -@item ---send-keys @code{names} -Same as ---export but sends the keys to a keyserver. -Option ---keyserver must be used to give the name -of this keyserver. Don't send your complete keyring -to a keyserver - select only those keys which are new -or changed by you. - -@item ---export-all @code{names} -Same as ---export, but also exports keys which -are not compatible with OpenPGP. - -@item ---export-secret-keys @code{names} -@itemx ---export-secret-subkeys @code{names} -Same as ---export, but exports the secret keys instead. -This is normally not very useful and a security risk. -The second form of the command has the special property to -render the secret part of the primary key useless; this is -a GNU extension to OpenPGP and other implementations can -not be expected to successfully import such a key. -See the option ---simple-sk-checksum if you want to import such an -exported key with an older OpenPGP implementation. - -@item ---import @code{files} -@itemx ---fast-import @code{files} -Import/merge keys. This adds the given keys to the -keyring. The fast version is currently just a synonym. - -There are a few other options which control how this command works. -Most notable here is the ---merge-only option which does not insert new keys -but does only the merging of new signatures, user-IDs and subkeys. - -@item ---recv-keys @code{key IDs} -Import the keys with the given key IDs from a keyserver. Option ----keyserver must be used to give the name of this keyserver. - -@item ---refresh-keys @code{key IDs} -Request updates from a keyserver for keys that already exist on the -local keyring. This is useful for updating a key with the latest -signatures, user IDs, etc. Option ---keyserver must be used to give -the name of this keyserver. - -@item ---search-keys @code{names} -Search the keyserver for the given names. Multiple names given here -will be joined together to create the search string for the keyserver. -Option ---keyserver must be used to give the name of this keyserver. - -@item ---update-trustdb -Do trust database maintenance. This command iterates over all keys -and builds the Web-of-Trust. This is an interactive command because it -may have to ask for the "ownertrust" values for keys. The user has to -give an estimation of how far she trusts the owner of the displayed -key to correctly certify (sign) other keys. GnuPG only asks for the -ownertrust value if it has not yet been assigned to a key. Using the ----edit-key menu, the assigned value can be changed at any time. - -@item ---check-trustdb -Do trust database maintenance without user interaction. From time to -time the trust database must be updated so that expired keys or -signatures and the resulting changes in the Web-of-Trust can be -tracked. Normally, GnuPG will calculate when this is required and do -it automatically unless ---no-auto-check-trustdb is set. This command -can be used to force a trust database check at any time. The -processing is identical to that of ---update-trustdb but it skips keys -with a not yet defined "ownertrust". - -For use with cron jobs, this command can be used together with ---batch -in which case the trust database check is done only if a check is -needed. To force a run even in batch mode add the option ---yes. - -@item ---export-ownertrust -Send the ownertrust values to stdout. This is useful for backup -purposes as these values are the only ones which can't be re-created -from a corrupted trust DB. - -@item ---import-ownertrust @code{files} -Update the trustdb with the ownertrust values stored -in @code{files} (or stdin if not given); existing -values will be overwritten. - -@item ---rebuild-keydb-caches -When updating from version 1.0.6 to 1.0.7 this command should be used -to create signature caches in the keyring. It might be handy in other -situations too. - -@item ---print-md @code{algo} @code{files} -@itemx ---print-mds @code{files} -Print message digest of algorithm ALGO for all given files or stdin. -With the second form (or a deprecated "*" as algo) digests for all -available algorithms are printed. - -@item ---gen-random @code{0|1|2} @code{count} -Emit COUNT random bytes of the given quality level. If count is not given -or zero, an endless sequence of random bytes will be emitted. -PLEASE, don't use this command unless you know what you are doing; it may -remove precious entropy from the system! - -@item ---gen-prime @code{mode} @code{bits} @code{qbits} -Use the source, Luke :-). The output format is still subject to change. - -@item ---version -Print version information along with a list -of supported algorithms. - -@item ---warranty -Print warranty information. - -@item -h, ---help -Print usage information. This is a really long list even though it -doesn't list all options. For every option, consult this manual. - -@end table - -@majorheading OPTIONS -Long options can be put in an options file (default -"~/.gnupg/gpg.conf"). Short option names will not work - for example, -"armor" is a valid option for the options file, while "a" is not. Do -not write the 2 dashes, but simply the name of the option and any -required arguments. Lines with a hash ('#') as the first -non-white-space character are ignored. Commands may be put in this -file too, but that is not generally useful as the command will execute -automatically with every execution of gpg. - -@code{gpg} recognizes these options: - -@table @asis -@item -a, ---armor -Create ASCII armored output. - -@item -o, ---output @code{file} -Write output to @code{file}. - -@item ---mangle-dos-filenames -@itemx ---no-mangle-dos-filenames -Older version of Windows cannot handle filenames with more than one -dot. ---mangle-dos-filenames causes GnuPG to replace (rather than add -to) the extension of an output filename to avoid this problem. This -option is off by default and has no effect on non-Windows platforms. - -@item -u, ---local-user @code{name} -Use @code{name} as the user ID to sign. -This option is silently ignored for the list commands, -so that it can be used in an options file. - -@item ---default-key @code{name} -Use @code{name} as default user ID for signatures. If this -is not used the default user ID is the first user ID -found in the secret keyring. - -@item -r, ---recipient @code{name} -@itemx -Encrypt for user id @code{name}. If this option or ---hidden-recipient -is not specified, GnuPG asks for the user-id unless ----default-recipient is given. - -@item -R, ---hidden-recipient @code{name} -@itemx -Encrypt for user id @code{name}, but hide the keyid of the key. This -option hides the receiver of the message and is a countermeasure -against traffic analysis. If this option or ---recipient is not -specified, GnuPG asks for the user-id unless ---default-recipient is -given. - -@item ---default-recipient @code{name} -Use @code{name} as default recipient if option ---recipient is not used and -don't ask if this is a valid one. @code{name} must be non-empty. - -@item ---default-recipient-self -Use the default key as default recipient if option ---recipient is not used and -don't ask if this is a valid one. The default key is the first one from the -secret keyring or the one set with ---default-key. - -@item ---no-default-recipient -Reset ---default-recipient and --default-recipient-self. - -@item ---encrypt-to @code{name} -Same as ---recipient but this one is intended for use -in the options file and may be used with -your own user-id as an "encrypt-to-self". These keys -are only used when there are other recipients given -either by use of ---recipient or by the asked user id. -No trust checking is performed for these user ids and -even disabled keys can be used. - -@item ---hidden-encrypt-to @code{name} -Same as ---hidden-recipient but this one is intended for use in the -options file and may be used with your own user-id as a hidden -"encrypt-to-self". These keys are only used when there are other -recipients given either by use of ---recipient or by the asked user id. -No trust checking is performed for these user ids and even disabled -keys can be used. - -@item ---no-encrypt-to -Disable the use of all ---encrypt-to and --hidden-encrypt-to keys. - -@item -v, ---verbose -Give more information during processing. If used -twice, the input data is listed in detail. - -@item -q, ---quiet -Try to be as quiet as possible. - -@item -z @code{n}, ---compress @code{n} -Set compression level to @code{n}. A value of 0 for @code{n} -disables compression. Default is to use the default -compression level of zlib (normally 6). - -@item -t, ---textmode -@itemx ---no-textmode -Use canonical text mode. ---no-textmode disables this option. If -t -(but not ---textmode) is used together with armoring and signing, this -enables clearsigned messages. This kludge is needed for command-line -compatibility with command-line versions of PGP; normally you would -use ---sign or --clearsign to select the type of the signature. - -@item -n, ---dry-run -Don't make any changes (this is not completely implemented). - -@item -i, ---interactive -Prompt before overwriting any files. - -@item ---batch -@itemx ---no-batch -Use batch mode. Never ask, do not allow interactive commands. ----no-batch disables this option. - -@item ---no-tty -Make sure that the TTY (terminal) is never used for any output. -This option is needed in some cases because GnuPG sometimes prints -warnings to the TTY if ---batch is used. - -@item ---yes -Assume "yes" on most questions. - -@item ---no -Assume "no" on most questions. - -@item ---default-cert-check-level @code{n} -The default to use for the check level when signing a key. - -0 means you make no particular claim as to how carefully you verified -the key. - -1 means you believe the key is owned by the person who claims to own -it but you could not, or did not verify the key at all. This is -useful for a "persona" verification, where you sign the key of a -pseudonymous user. - -2 means you did casual verification of the key. For example, this -could mean that you verified that the key fingerprint and checked the -user ID on the key against a photo ID. - -3 means you did extensive verification of the key. For example, this -could mean that you verified the key fingerprint with the owner of the -key in person, and that you checked, by means of a hard to forge -document with a photo ID (such as a passport) that the name of the key -owner matches the name in the user ID on the key, and finally that you -verified (by exchange of email) that the email address on the key -belongs to the key owner. - -Note that the examples given above for levels 2 and 3 are just that: -examples. In the end, it is up to you to decide just what "casual" -and "extensive" mean to you. - -This option defaults to 0. - -@item ---trusted-key @code{long key ID} -Assume that the specified key (which must be given -as a full 8 byte key ID) is as trustworthy as one of -your own secret keys. This option is useful if you -don't want to keep your secret keys (or one of them) -online but still want to be able to check the validity of a given -recipient's or signator's key. - -@item ---trust-model @code{pgp|classic|always} -Set what trust model GnuPG should follow. The models are: - -@table @asis -@item pgp -This is the web-of-trust combined with trust signatures as used in PGP -5.x and later. This is the default trust model. - -@item classic -This is the standard web-of-trust as used in PGP 2.x and earlier. - -@item always -Skip key validation and assume that used keys are always fully -trusted. You won't use this unless you have installed some external -validation scheme. This option also suppresses the "[uncertain]" tag -printed with signature checks when there is no evidence that the user -ID is bound to the key. - -@end table - -@item ---always-trust -Identical to `---trust-model always' - -@item ---keyserver @code{name} -Use @code{name} as your keyserver. This is the server that ---recv-keys, ----send-keys, and --search-keys will communicate with to receive keys -from, send keys to, and search for keys on. The format of the -@code{name} is a URI: `scheme:[//]keyservername[:port]' The scheme is -the type of keyserver: "hkp" for the Horowitz (or compatible) -keyservers, "ldap" for the NAI LDAP keyserver, or "mailto" for the -Horowitz email keyserver. Note that your particular installation of -GnuPG may have other keyserver types available as well. Keyserver -schemes are case-insensitive. - -Most keyservers synchronize with each other, so there is generally no -need to send keys to more than one server. Using the command "host -l -pgp.net | grep wwwkeys" gives you a list of HKP keyservers. When -using one of the wwwkeys servers, due to load balancing using -round-robin DNS you may notice that you get a different key server -each time. - -@item ---keyserver-options @code{parameters} -This is a space or comma delimited string that gives options for the -keyserver. Options can be prepended with a `no-' to give the opposite -meaning. Valid import-options or export-options may be used here as -well to apply to importing (---recv-key) or exporting (--send-key) a -key from a keyserver. While not all options are available for all -keyserver types, some common options are: - -@table @asis -@item include-revoked -When searching for a key with ---search-keys, include keys that are -marked on the keyserver as revoked. Note that this option is always -set when using the NAI HKP keyserver, as this keyserver does not -differentiate between revoked and unrevoked keys. - -@item include-disabled -When searching for a key with ---search-keys, include keys that are -marked on the keyserver as disabled. Note that this option is not -used with HKP keyservers. - -@item include-subkeys -When receiving a key, include subkeys as potential targets. Note that -this option is not used with HKP keyservers, as they do not support -retrieving keys by subkey id. - -@item use-temp-files -On most Unix-like platforms, GnuPG communicates with the keyserver -helper program via pipes, which is the most efficient method. This -option forces GnuPG to use temporary files to communicate. On some -platforms (such as Win32 and RISC OS), this option is always enabled. - -@item keep-temp-files -If using `use-temp-files', do not delete the temp files after using -them. This option is useful to learn the keyserver communication -protocol by reading the temporary files. - -@item verbose -Tell the keyserver helper program to be more verbose. This option can -be repeated multiple times to increase the verbosity level. - -@item honor-http-proxy -For keyserver schemes that use HTTP (such as HKP), try to access the -keyserver over the proxy set with the environment variable -"http_proxy". - -@item auto-key-retrieve -This option enables the automatic retrieving of keys from a keyserver -when verifying signatures made by keys that are not on the local -keyring. - -Note that this option makes a "web bug" like behavior possible. -Keyserver operators can see which keys you request, so by sending you -a message signed by a brand new key (which you naturally will not have -on your local keyring), the operator can tell both your IP address and -the time when you verified the signature. - -@end table - -@item ---import-options @code{parameters} -This is a space or comma delimited string that gives options for -importing keys. Options can be prepended with a `no-' to give the -opposite meaning. The options are: - -@table @asis -@item allow-local-sigs -Allow importing key signatures marked as "local". This is not -generally useful unless a shared keyring scheme is being used. -Defaults to no. - -@item repair-pks-subkey-bug -During import, attempt to repair the damage caused by the PKS -keyserver bug (pre version 0.9.6) that mangles keys with multiple -subkeys. Note that this cannot completely repair the damaged key as -some crucial data is removed by the keyserver, but it does at least -give you back one subkey. Defaults to no for regular ---import and to -yes for keyserver ---recv-keys. - -@end table - -@item ---export-options @code{parameters} -This is a space or comma delimited string that gives options for -exporting keys. Options can be prepended with a `no-' to give the -opposite meaning. The options are: - -@table @asis -@item include-non-rfc -Include non-RFC compliant keys in the export. Defaults to yes. - -@item include-local-sigs -Allow exporting key signatures marked as "local". This is not -generally useful unless a shared keyring scheme is being used. -Defaults to no. - -@item include-attributes -Include attribute user IDs (photo IDs) while exporting. This is -useful to export keys if they are going to be used by an OpenPGP -program that does not accept attribute user IDs. Defaults to yes. - -@item include-sensitive-revkeys -Include designated revoker information that was marked as -"sensitive". Defaults to no. - -@end table - -@item ---list-options @code{parameters} -This is a space or comma delimited string that gives options used when -listing keys and signatures (that is, ---list-keys, --list-sigs, ----list-public-keys, --list-secret-keys, and the --edit-key functions). -Options can be prepended with a `no-' to give the opposite meaning. -The options are: - -@table @asis -@item show-photos -Causes ---list-keys, --list-sigs, --list-public-keys, and ----list-secret-keys to display any photo IDs attached to the key. -Defaults to no. See also ---photo-viewer. - -@item show-policy-url -Show policy URLs in the ---list-sigs or --check-sigs listings. -Defaults to no. - -@item show-notation -Show signature notations in the ---list-sigs or --check-sigs listings. -Defaults to no. - -@item show-keyserver-url -Show any preferred keyserver URL in the ---list-sigs or --check-sigs -listings. Defaults to no. - -@item show-validity -Display the calculated validity of keys and user IDs during key -listings. Defaults to no. - -@item show-long-keyid -Display all 64 bits (16 digits) of key IDs during key listings, rather -than the more common 32 bit (8 digit) IDs. Defaults to no. - -@item show-unusable-uids -Show revoked and expired user IDs in key listings. Defaults to no. - -@item show-keyring -Display the keyring name at the head of key listings to show which -keyring a given key resides on. Defaults to no. - -@item show-sig-expire -Show signature expiration dates (if any) during ---list-sigs or ----check-sigs listings. Defaults to no. - -@end table - -@item ---verify-options @code{parameters} -This is a space or comma delimited string that gives options used when -verifying signatures. Options can be prepended with a `no-' to give -the opposite meaning. The options are: - -@table @asis -@item show-photos -Display any photo IDs present on the key that issued the signature. -Defaults to no. See also ---photo-viewer. - -@item show-policy-url -Show policy URLs in the signature being verified. Defaults to no. - -@item show-notation -Show signature notations in the signature being verified. Defaults to -no. - -@item show-keyserver-url -Show any preferred keyserver URL in the signature being verified. -Defaults to no. - -@item show-validity -Display the calculated validity of the user IDs on the key that issued -the signature. Defaults to no. - -@item show-long-keyid -Display all 64 bits (16 digits) of key IDs during signature -verification, rather than the more common 32 bit (8 digit) IDs. -Defaults to no. - -@item show-unusable-uids -Show revoked and expired user IDs during signature verification. -Defaults to no. - -@end table - -@item ---show-photos -@itemx ---no-show-photos -Causes ---list-keys, --list-sigs, --list-public-keys, ----list-secret-keys, and verifying a signature to also display the -photo ID attached to the key, if any. See also ---photo-viewer. These -options are deprecated. Use `---list-options [no-]show-photos' and/or -`---verify-options [no-]show-photos' instead. - -@item ---photo-viewer @code{string} -This is the command line that should be run to view a photo ID. "%i" -will be expanded to a filename containing the photo. "%I" does the -same, except the file will not be deleted once the viewer exits. -Other flags are "%k" for the key ID, "%K" for the long key ID, "%f" -for the key fingerprint, "%t" for the extension of the image type -(e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"), -and "%%" for an actual percent sign. If neither %i or %I are present, -then the photo will be supplied to the viewer on standard input. - -The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k' -stdin". Note that if your image viewer program is not secure, then -executing it from GnuPG does not make it secure. - -@item ---exec-path @code{string} -Sets a list of directories to search for photo viewers and keyserver -helpers. If not provided, keyserver helpers use the compiled-in -default directory, and photo viewers use the $PATH environment -variable. - -@item ---show-keyring -Display the keyring name at the head of key listings to show which -keyring a given key resides on. This option is deprecated: use -`---list-options [no-]show-keyring' instead. - -@item ---keyring @code{file} -Add @code{file} to the list of keyrings. If @code{file} begins with a -tilde and a slash, these are replaced by the HOME directory. If the -filename does not contain a slash, it is assumed to be in the GnuPG -home directory ("~/.gnupg" if ---homedir is not used). The filename -may be prefixed with a scheme: - -"gnupg-ring:" is the default one. - -It might make sense to use it together with ---no-default-keyring. - -@item ---secret-keyring @code{file} -Same as ---keyring but for the secret keyrings. - -@item ---primary-keyring @code{file} -Designate @code{file} as the primary public keyring. This means that -newly imported keys (via ---import or keyserver --recv-from) will go to -this keyring. - -@item ---trustdb-name @code{file} -Use @code{file} instead of the default trustdb. If @code{file} begins -with a tilde and a slash, these are replaced by the HOME directory. If -the filename does not contain a slash, it is assumed to be in the -GnuPG home directory ("~/.gnupg" if ---homedir is not used). - -@item ---homedir @code{directory} -Set the name of the home directory to @code{directory} If this -option is not used it defaults to "~/.gnupg". It does -not make sense to use this in a options file. This -also overrides the environment variable "GNUPGHOME". - -@item ---charset @code{name} -Set the name of the native character set. This is used -to convert some strings to proper UTF-8 encoding. If this option is not used, the default character set is determined -from the current locale. A verbosity level of 3 shows the used one. -Valid values for @code{name} are: - -@table @asis -@item iso-8859-1 -This is the Latin 1 set. - -@item iso-8859-2 -The Latin 2 set. - -@item iso-8859-15 -This is currently an alias for -the Latin 1 set. - -@item koi8-r -The usual Russian set (rfc1489). - -@item utf-8 -Bypass all translations and assume -that the OS uses native UTF-8 encoding. - -@end table - -@item ---utf8-strings -@itemx ---no-utf8-strings -Assume that the arguments are already given as UTF8 strings. The default -(---no-utf8-strings) -is to assume that arguments are encoded in the character set as specified -by ---charset. These options affect all following arguments. Both options may -be used multiple times. - -@item ---options @code{file} -Read options from @code{file} and do not try to read -them from the default options file in the homedir -(see ---homedir). This option is ignored if used -in an options file. - -@item ---no-options -Shortcut for "---options /dev/null". This option is -detected before an attempt to open an option file. -Using this option will also prevent the creation of a -"~./gnupg" homedir. - -@item ---load-extension @code{name} -Load an extension module. If @code{name} does not contain a slash it is -searched for in the directory configured when GnuPG was built -(generally "/usr/local/lib/gnupg"). Extensions are not generally -useful anymore, and the use of this option is deprecated. - -@item ---debug @code{flags} -Set debugging flags. All flags are or-ed and @code{flags} may -be given in C syntax (e.g. 0x0042). - -@item ---debug-all -Set all useful debugging flags. - -@item ---enable-progress-filter -Enable certain PROGRESS status outputs. This option allows frontends -to display a progress indicator while gpg is processing larger files. -There is a slight performance overhead using it. - -@item ---status-fd @code{n} -Write special status strings to the file descriptor @code{n}. -See the file DETAILS in the documentation for a listing of them. - -@item ---logger-fd @code{n} -Write log output to file descriptor @code{n} and not to stderr. - -@item ---attribute-fd @code{n} -Write attribute subpackets to the file descriptor @code{n}. This is -most useful for use with ---status-fd, since the status messages are -needed to separate out the various subpackets from the stream -delivered to the file descriptor. - -@item ---sk-comments -@itemx ---no-sk-comments -Include secret key comment packets when exporting secret keys. This -is a GnuPG extension to the OpenPGP standard, and is off by default. -Please note that this has nothing to do with the comments in clear -text signatures or armor headers. ---no-sk-comments disables this -option. - -@item ---comment @code{string} -@itemx ---no-comments -Use @code{string} as a comment string in clear text signatures and -ASCII armored messages or keys (see ---armor). The default behavior is -not to use a comment string. ---comment may be repeated multiple times -to get multiple comment strings. ---no-comments removes all comments. - -@item ---emit-version -@itemx ---no-emit-version -Force inclusion of the version string in ASCII armored output. ----no-emit-version disables this option. - -@item ---sig-notation @code{name=value} -@itemx ---cert-notation @code{name=value} -@itemx -N, ---set-notation @code{name=value} -Put the name value pair into the signature as notation data. -@code{name} must consist only of printable characters or spaces, and -must contain a '@@' character. This is to help prevent pollution of -the IETF reserved notation namespace. The ---expert flag overrides the -'@@' check. @code{value} may be any printable string; it will be -encoded in UTF8, so you should check that your ---charset is set -correctly. If you prefix @code{name} with an exclamation mark, the -notation data will be flagged as critical (rfc2440:5.2.3.15). ----sig-notation sets a notation for data signatures. --cert-notation -sets a notation for key signatures (certifications). ---set-notation -sets both. - -There are special codes that may be used in notation names. "%k" will -be expanded into the key ID of the key being signed, "%K" into the -long key ID of the key being signed, "%f" into the fingerprint of the -key being signed, "%s" into the key ID of the key making the -signature, "%S" into the long key ID of the key making the signature, -"%g" into the fingerprint of the key making the signature (which might -be a subkey), "%p" into the fingerprint of the primary key of the key -making the signature, and "%%" results in a single "%". %k, %K, and -%f are only meaningful when making a key signature (certification). - -@item ---show-notation -@itemx ---no-show-notation -Show signature notations in the ---list-sigs or --check-sigs listings -as well as when verifying a signature with a notation in it. These -options are deprecated. Use `---list-options [no-]show-notation' -and/or `---verify-options [no-]show-notation' instead. - -@item ---sig-policy-url @code{string} -@itemx ---cert-policy-url @code{string} -@itemx ---set-policy-url @code{string} -Use @code{string} as a Policy URL for signatures (rfc2440:5.2.3.19). -If you prefix it with an exclamation mark, the policy URL packet will -be flagged as critical. ---sig-policy-url sets a a policy url for data -signatures. ---cert-policy-url sets a policy url for key signatures -(certifications). ---set-policy-url sets both. - -The same %-expandos used for notation data are available here as well. - -@item ---show-policy-url -@itemx ---no-show-policy-url -Show policy URLs in the ---list-sigs or --check-sigs listings as well -as when verifying a signature with a policy URL in it. These options -are deprecated. Use `---list-options [no-]show-policy-url' and/or -`---verify-options [no-]show-policy-url' instead. - -@item ---sig-keyserver-url @code{string} -Use @code{string} as a preferred keyserver URL for data signatures. If -you prefix it with an exclamation mark, the keyserver URL packet will -be flagged as critical. - -The same %-expandos used for notation data are available here as well. - -@item ---set-filename @code{string} -Use @code{string} as the filename which is stored inside messages. -This overrides the default, which is to use the actual filename of the -file being encrypted. - -@item ---for-your-eyes-only -@itemx ---no-for-your-eyes-only -Set the `for your eyes only' flag in the message. This causes GnuPG -to refuse to save the file unless the ---output option is given, and -PGP to use the "secure viewer" with a Tempest-resistant font to -display the message. This option overrides ---set-filename. ----no-for-your-eyes-only disables this option. - -@item ---use-embedded-filename -Try to create a file with a name as embedded in the data. -This can be a dangerous option as it allows to overwrite files. - -@item ---completes-needed @code{n} -Number of completely trusted users to introduce a new -key signer (defaults to 1). - -@item ---marginals-needed @code{n} -Number of marginally trusted users to introduce a new -key signer (defaults to 3) - -@item ---max-cert-depth @code{n} -Maximum depth of a certification chain (default is 5). - -@item ---cipher-algo @code{name} -Use @code{name} as cipher algorithm. Running the program -with the command ---version yields a list of supported -algorithms. If this is not used the cipher algorithm is -selected from the preferences stored with the key. - -@item ---digest-algo @code{name} -Use @code{name} as the message digest algorithm. Running the program -with the command ---version yields a list of supported algorithms. - -@item ---compress-algo @code{name} -Use compression algorithm @code{name}. "zlib" is RFC1950 ZLIB -compression. "zip" is RFC-1951 ZIP compression which is used by PGP. -"uncompressed" or "none" disables compression. If this option is not -used, the default behavior is to examine the recipient key preferences -to see which algorithms the recipient supports. If all else fails, -ZIP is used for maximum compatibility. Note, however, that ZLIB may -give better compression results if that is more important, as the -compression window size is not limited to 8k. - -@item ---cert-digest-algo @code{name} -Use @code{name} as the message digest algorithm used when signing a -key. Running the program with the command ---version yields a list of -supported algorithms. Be aware that if you choose an algorithm that -GnuPG supports but other OpenPGP implementations do not, then some -users will not be able to use the key signatures you make, or quite -possibly your entire key. - -@item ---s2k-cipher-algo @code{name} -Use @code{name} as the cipher algorithm used to protect secret keys. -The default cipher is CAST5. This cipher is also used for -conventional encryption if ---personal-cipher-preferences and ----cipher-algo is not given. - -@item ---s2k-digest-algo @code{name} -Use @code{name} as the digest algorithm used to mangle the passphrases. -The default algorithm is SHA-1. - -@item ---s2k-mode @code{n} -Selects how passphrases are mangled. If @code{n} is 0 a plain -passphrase (which is not recommended) will be used, a 1 adds a salt to -the passphrase and a 3 (the default) iterates the whole process a -couple of times. Unless ---rfc1991 is used, this mode is also used for -conventional encryption. - -@item ---simple-sk-checksum -Secret keys are integrity protected by using a SHA-1 checksum. This -method will be part of an enhanced OpenPGP specification but GnuPG -already uses it as a countermeasure against certain attacks. Old -applications don't understand this new format, so this option may be -used to switch back to the old behaviour. Using this this option -bears a security risk. Note that using this option only takes effect -when the secret key is encrypted - the simplest way to make this -happen is to change the passphrase on the key (even changing it to the -same value is acceptable). - -@item ---disable-cipher-algo @code{name} -Never allow the use of @code{name} as cipher algorithm. -The given name will not be checked so that a later loaded algorithm -will still get disabled. - -@item ---disable-pubkey-algo @code{name} -Never allow the use of @code{name} as public key algorithm. -The given name will not be checked so that a later loaded algorithm -will still get disabled. - -@item ---no-sig-cache -Do not cache the verification status of key signatures. -Caching gives a much better performance in key listings. However, if -you suspect that your public keyring is not save against write -modifications, you can use this option to disable the caching. It -probably does not make sense to disable it because all kind of damage -can be done if someone else has write access to your public keyring. - -@item ---no-sig-create-check -GnuPG normally verifies each signature right after creation to protect -against bugs and hardware malfunctions which could leak out bits from -the secret key. This extra verification needs some time (about 115% -for DSA keys), and so this option can be used to disable it. -However, due to the fact that the signature creation needs manual -interaction, this performance penalty does not matter in most settings. - -@item ---auto-check-trustdb -@itemx ---no-auto-check-trustdb -If GnuPG feels that its information about the Web-of-Trust has to be -updated, it automatically runs the ---check-trustdb command internally. -This may be a time consuming process. ---no-auto-check-trustdb -disables this option. - -@item ---throw-keyid -Do not put the keyids into encrypted packets. This option hides the -receiver of the message and is a countermeasure against traffic -analysis. It may slow down the decryption process because all -available secret keys are tried. - -@item ---no-throw-keyid -Resets the ---throw-keyid option. - -@item ---not-dash-escaped -This option changes the behavior of cleartext signatures -so that they can be used for patch files. You should not -send such an armored file via email because all spaces -and line endings are hashed too. You can not use this -option for data which has 5 dashes at the beginning of a -line, patch files don't have this. A special armor header -line tells GnuPG about this cleartext signature option. - -@item ---escape-from-lines -@itemx ---no-escape-from-lines -Because some mailers change lines starting with "From " to ">From -" it is good to handle such lines in a special way when creating -cleartext signatures to prevent the mail system from breaking the -signature. Note that all other PGP versions do it this way too. -Enabled by default. ---no-escape-from-lines disables this option. - -@item ---passphrase-fd @code{n} -Read the passphrase from file descriptor @code{n}. If you use -0 for @code{n}, the passphrase will be read from stdin. This -can only be used if only one passphrase is supplied. -Don't use this option if you can avoid it. - -@item ---command-fd @code{n} -This is a replacement for the deprecated shared-memory IPC mode. -If this option is enabled, user input on questions is not expected -from the TTY but from the given file descriptor. It should be used -together with ---status-fd. See the file doc/DETAILS in the source -distribution for details on how to use it. - -@item ---use-agent -@itemx ---no-use-agent -Try to use the GnuPG-Agent. Please note that this agent is still under -development. With this option, GnuPG first tries to connect to the -agent before it asks for a passphrase. ---no-use-agent disables this -option. - -@item ---gpg-agent-info -Override the value of the environment variable -@samp{GPG_AGENT_INFO}. This is only used when ---use-agent has been given - -@item Compliance options -These options control what GnuPG is compliant to. Only one of these -options may be active at a time. Note that the default setting of -this is nearly always the correct one. See the INTEROPERABILITY WITH -OTHER OPENPGP PROGRAMS section below before using one of these -options. - -@table @asis -@item ---gnupg -Use standard GnuPG behavior. This is essentially OpenPGP behavior -(see ---openpgp), but with some additional workarounds for common -compatibility problems in different versions of PGP. This is the -default option, so it is not generally needed, but it may be useful to -override a different compliance option in the gpg.conf file. - -@item ---openpgp -Reset all packet, cipher and digest options to strict OpenPGP -behavior. Use this option to reset all previous options like ----rfc1991, --force-v3-sigs, --s2k-*, --cipher-algo, --digest-algo and ----compress-algo to OpenPGP compliant values. All PGP workarounds are -disabled. - -@item ---rfc2440 -Reset all packet, cipher and digest options to strict RFC-2440 -behavior. Note that this is currently the same thing as ---openpgp. - -@item ---rfc1991 -Try to be more RFC-1991 (PGP 2.x) compliant. - -@item ---pgp2 -Set up all options to be as PGP 2.x compliant as possible, and warn if -an action is taken (e.g. encrypting to a non-RSA key) that will create -a message that PGP 2.x will not be able to handle. Note that `PGP -2.x' here means `MIT PGP 2.6.2'. There are other versions of PGP 2.x -available, but the MIT release is a good common baseline. - -This option implies `---rfc1991 --disable-mdc --no-force-v4-certs ----no-sk-comment --escape-from-lines --force-v3-sigs ----no-ask-sig-expire --no-ask-cert-expire --cipher-algo IDEA ----digest-algo MD5 --compress-algo 1'. It also disables --textmode -when encrypting. - -@item ---pgp6 -Set up all options to be as PGP 6 compliant as possible. This -restricts you to the ciphers IDEA (if the IDEA plugin is installed), -3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the -compression algorithms none and ZIP. This also disables ----throw-keyid, and making signatures with signing subkeys as PGP 6 -does not understand signatures made by signing subkeys. - -This option implies `---disable-mdc --no-sk-comment --escape-from-lines ----force-v3-sigs --no-ask-sig-expire' - -@item ---pgp7 -Set up all options to be as PGP 7 compliant as possible. This is -identical to ---pgp6 except that MDCs are not disabled, and the list of -allowable ciphers is expanded to add AES128, AES192, AES256, and -TWOFISH. - -@item ---pgp8 -Set up all options to be as PGP 8 compliant as possible. PGP 8 is a -lot closer to the OpenPGP standard than previous versions of PGP, so -all this does is disable ---throw-keyid and set --escape-from-lines. -The allowed algorithms list is the same as ---pgp7 with the addition of -the SHA-256 digest algorithm. - -@end table - -@item ---force-v3-sigs -@itemx ---no-force-v3-sigs -OpenPGP states that an implementation should generate v4 signatures -but PGP versions 5 and higher only recognize v4 signatures on key -material. This option forces v3 signatures for signatures on data. -Note that this option overrides ---ask-sig-expire, as v3 signatures -cannot have expiration dates. ---no-force-v3-sigs disables this -option. - -@item ---force-v4-certs -@itemx ---no-force-v4-certs -Always use v4 key signatures even on v3 keys. This option also -changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1. ----no-force-v4-certs disables this option. - -@item ---force-mdc -Force the use of encryption with a modification detection code. This -is always used with the newer ciphers (those with a blocksize greater -than 64 bits), or if all of the recipient keys indicate MDC support in -their feature flags. - -@item ---disable-mdc -Disable the use of the modification detection code. Note that by -using this option, the encrypted message becomes vulnerable to a -message modification attack. - -@item ---allow-non-selfsigned-uid -@itemx ---no-allow-non-selfsigned-uid -Allow the import and use of keys with user IDs which are not -self-signed. This is not recommended, as a non self-signed user ID is -trivial to forge. ---no-allow-non-selfsigned-uid disables. - -@item ---allow-freeform-uid -Disable all checks on the form of the user ID while generating a new -one. This option should only be used in very special environments as -it does not ensure the de-facto standard format of user IDs. - -@item ---ignore-time-conflict -GnuPG normally checks that the timestamps associated with keys and -signatures have plausible values. However, sometimes a signature -seems to be older than the key due to clock problems. This option -makes these checks just a warning. See also ---ignore-valid-from for -timestamp issues on subkeys. - -@item ---ignore-valid-from -GnuPG normally does not select and use subkeys created in the future. -This option allows the use of such keys and thus exhibits the -pre-1.0.7 behaviour. You should not use this option unless you there -is some clock problem. See also ---ignore-time-conflict for timestamp -issues with signatures. - -@item ---ignore-crc-error -The ASCII armor used by OpenPGP is protected by a CRC checksum against -transmission errors. Sometimes it happens that the CRC gets mangled -somewhere on the transmission channel but the actual content (which is -protected by the OpenPGP protocol anyway) is still okay. This option -will let gpg ignore CRC errors. - -@item ---ignore-mdc-error -This option changes a MDC integrity protection failure into a warning. -This can be useful if a message is partially corrupt, but it is -necessary to get as much data as possible out of the corrupt message. -However, be aware that a MDC protection failure may also mean that the -message was tampered with intentionally by an attacker. - -@item ---lock-once -Lock the databases the first time a lock is requested -and do not release the lock until the process -terminates. - -@item ---lock-multiple -Release the locks every time a lock is no longer -needed. Use this to override a previous ---lock-once -from a config file. - -@item ---lock-never -Disable locking entirely. This option should be used only in very -special environments, where it can be assured that only one process -is accessing those files. A bootable floppy with a stand-alone -encryption system will probably use this. Improper usage of this -option may lead to data and key corruption. - -@item ---no-random-seed-file -GnuPG uses a file to store its internal random pool over invocations. -This makes random generation faster; however sometimes write operations -are not desired. This option can be used to achieve that with the cost of -slower random generation. - -@item ---no-verbose -Reset verbose level to 0. - -@item ---no-greeting -Suppress the initial copyright message. - -@item ---no-secmem-warning -Suppress the warning about "using insecure memory". - -@item ---no-permission-warning -Suppress the warning about unsafe file and home directory (---homedir) -permissions. Note that the permission checks that GnuPG performs are -not intended to be authoritative, but rather they simply warn about -certain common permission problems. Do not assume that the lack of a -warning means that your system is secure. - -Note that the warning for unsafe ---homedir permissions cannot be -supressed in the gpg.conf file, as this would allow an attacker to -place an unsafe gpg.conf file in place, and use this file to supress -warnings about itself. The ---homedir permissions warning may only be -supressed on the command line. - -@item ---no-mdc-warning -Suppress the warning about missing MDC integrity protection. - -@item ---no-armor -Assume the input data is not in ASCII armored format. - -@item ---no-default-keyring -Do not add the default keyrings to the list of -keyrings. - -@item ---skip-verify -Skip the signature verification step. This may be -used to make the decryption faster if the signature -verification is not needed. - -@item ---with-colons -Print key listings delimited by colons. Note that the output will be -encoded in UTF-8 regardless of any ---charset setting. This format is -useful when GnuPG is called from scripts and other programs as it is -easily machine parsed. The details of this format are documented in -the file doc/DETAILS, which is included in the GnuPG source -distribution. - -@item ---with-key-data -Print key listings delimited by colons (like ---with-colons) and print the public key data. - -@item ---with-fingerprint -Same as the command ---fingerprint but changes only the format of the output -and may be used together with another command. - -@item ---fast-list-mode -Changes the output of the list commands to work faster; this is achieved -by leaving some parts empty. Some applications don't need the user ID and -the trust information given in the listings. By using this options they -can get a faster listing. The exact behaviour of this option may change -in future versions. - -@item ---fixed-list-mode -Do not merge primary user ID and primary key in ---with-colon listing -mode and print all timestamps as seconds since 1970-01-01. - -@item ---list-only -Changes the behaviour of some commands. This is like ---dry-run but -different in some cases. The semantic of this command may be extended in -the future. Currently it only skips the actual decryption pass and -therefore enables a fast listing of the encryption keys. - -@item ---no-literal -This is not for normal use. Use the source to see for what it might be useful. - -@item ---set-filesize -This is not for normal use. Use the source to see for what it might be useful. - -@item ---emulate-md-encode-bug -GnuPG versions prior to 1.0.2 had a bug in the way a signature was encoded. -This options enables a workaround by checking faulty signatures again with -the encoding used in old versions. This may only happen for ElGamal signatures -which are not widely used. - -@item ---show-session-key -Display the session key used for one message. See ---override-session-key -for the counterpart of this option. - -We think that Key-Escrow is a Bad Thing; however the user should -have the freedom to decide whether to go to prison or to reveal the content of -one specific message without compromising all messages ever encrypted for one -secret key. DON'T USE IT UNLESS YOU ARE REALLY FORCED TO DO SO. - -@item ---override-session-key @code{string} -Don't use the public key but the session key @code{string}. The format of this -string is the same as the one printed by ---show-session-key. This option -is normally not used but comes handy in case someone forces you to reveal the -content of an encrypted message; using this option you can do this without -handing out the secret key. - -@item ---ask-sig-expire -@itemx ---no-ask-sig-expire -When making a data signature, prompt for an expiration time. If this -option is not specified, the expiration time is "never". ----no-ask-sig-expire disables this option. - -@item ---ask-cert-expire -@itemx ---no-ask-cert-expire -When making a key signature, prompt for an expiration time. If this -option is not specified, the expiration time is "never". ----no-ask-cert-expire disables this option. - -@item ---expert -@itemx ---no-expert -Allow the user to do certain nonsensical or "silly" things like -signing an expired or revoked key, or certain potentially incompatible -things like generating deprecated key types. This also disables -certain warning messages about potentially incompatible actions. As -the name implies, this option is for experts only. If you don't fully -understand the implications of what it allows you to do, leave this -off. ---no-expert disables this option. - -@item ---merge-only -Don't insert new keys into the keyrings while doing an import. - -@item ---allow-secret-key-import -This is an obsolete option and is not used anywhere. - -@item ---try-all-secrets -Don't look at the key ID as stored in the message but try all secret keys in -turn to find the right decryption key. This option forces the behaviour as -used by anonymous recipients (created by using ---throw-keyid) and might come -handy in case where an encrypted message contains a bogus key ID. - -@item ---enable-special-filenames -This options enables a mode in which filenames of the form -@file{-&n}, where n is a non-negative decimal number, -refer to the file descriptor n and not to a file with that name. - -@item ---no-expensive-trust-checks -Experimental use only. - -@item ---group @code{name=value1 value2 value3 ...} -Sets up a named group, which is similar to aliases in email programs. -Any time the group name is a recipient (-r or ---recipient), it will -be expanded to the values specified. - -The values are @code{key IDs} or fingerprints, but any key description -is accepted. Note that a value with spaces in it will be treated as -two different values. Note also there is only one level of expansion -- you cannot make an group that points to another group. When used -from the command line, it may be necessary to quote the argument to -this option to prevent the shell from treating it as multiple -arguments. - -@item ---no-groups -Clear the ---group list. - -@item ---preserve-permissions -Don't change the permissions of a secret keyring back to user -read/write only. Use this option only if you really know what you are doing. - -@item ---personal-cipher-preferences @code{string} -Set the list of personal cipher preferences to @code{string}, this list -should be a string similar to the one printed by the command "pref" in -the edit menu. This allows the user to factor in their own preferred -algorithms when algorithms are chosen via recipient key preferences. -The most highly ranked cipher in this list is also used for the ----symmetric encryption command. - -@item ---personal-digest-preferences @code{string} -Set the list of personal digest preferences to @code{string}, this list -should be a string similar to the one printed by the command "pref" in -the edit menu. This allows the user to factor in their own preferred -algorithms when algorithms are chosen via recipient key preferences. -The most highly ranked digest algorithm in this list is algo used when -signing without encryption (e.g. ---clearsign or --sign). The default -value is SHA-1. - -@item ---personal-compress-preferences @code{string} -Set the list of personal compression preferences to @code{string}, this -list should be a string similar to the one printed by the command -"pref" in the edit menu. This allows the user to factor in their own -preferred algorithms when algorithms are chosen via recipient key -preferences. The most highly ranked algorithm in this list is also -used when there are no recipient keys to consider (e.g. ---symmetric). - -@item ---default-preference-list @code{string} -Set the list of default preferences to @code{string}, this list should -be a string similar to the one printed by the command "pref" in the -edit menu. This affects both key generation and "updpref" in the edit -menu. - -@end table - -@majorheading How to specify a user ID -There are different ways to specify a user ID to GnuPG; here are some -examples: - -@table @asis -@item -@item 234567C4 -@itemx 0F34E556E -@itemx 01347A56A -@itemx 0xAB123456 -Here the key ID is given in the usual short form. - -@item 234AABBCC34567C4 -@itemx 0F323456784E56EAB -@itemx 01AB3FED1347A5612 -@itemx 0x234AABBCC34567C4 -Here the key ID is given in the long form as used by OpenPGP -(you can get the long key ID using the option ---with-colons). - -@item 1234343434343434C434343434343434 -@itemx 123434343434343C3434343434343734349A3434 -@itemx 0E12343434343434343434EAB3484343434343434 -@itemx 0xE12343434343434343434EAB3484343434343434 -The best way to specify a key ID is by using the fingerprint of -the key. This avoids any ambiguities in case that there are duplicated -key IDs (which are really rare for the long key IDs). - -@item =Heinrich Heine <heinrichh@@uni-duesseldorf.de> -Using an exact to match string. The equal sign indicates this. - -@item <heinrichh@@uni-duesseldorf.de> -Using the email address part which must match exactly. The left angle bracket -indicates this email address mode. - -@item +Heinrich Heine duesseldorf -All words must match exactly (not case sensitive) but can appear in -any order in the user ID. Words are any sequences of letters, -digits, the underscore and all characters with bit 7 set. - -@item Heine -@itemx *Heine -By case insensitive substring matching. This is the default mode but -applications may want to explicitly indicate this by putting the asterisk -in front. - -@end table - -Note that you can append an exclamation mark to key IDs or -fingerprints. This flag tells GnuPG to use exactly the given primary -or secondary key and not to try to figure out which secondary or -primary key to use. - -@majorheading RETURN VALUE -The program returns 0 if everything was fine, 1 if at least -a signature was bad, and other error codes for fatal errors. - -@majorheading EXAMPLES -@table @asis -@item gpg -se -r @code{Bob} @code{file} -sign and encrypt for user Bob - -@item gpg ---clearsign @code{file} -make a clear text signature - -@item gpg -sb @code{file} -make a detached signature - -@item gpg ---list-keys @code{user_ID} -show keys - -@item gpg ---fingerprint @code{user_ID} -show fingerprint - -@item gpg ---verify @code{pgpfile} -@itemx gpg ---verify @code{sigfile} @code{files} -Verify the signature of the file but do not output the data. The second form -is used for detached signatures, where @code{sigfile} is the detached -signature (either ASCII armored of binary) and @code{files} are the signed -data; if this is not given the name of the file holding the signed data is -constructed by cutting off the extension (".asc" or ".sig") of -@code{sigfile} or by asking the user for the filename. - -@end table - -@majorheading ENVIRONMENT -@table @asis -@item HOME -Used to locate the default home directory. - -@item GNUPGHOME -If set directory used instead of "~/.gnupg". - -@item GPG_AGENT_INFO -Used to locate the gpg-agent; only honored when ----use-agent is set. The value consists of 3 colon delimited fields: -The first is the path to the Unix Domain Socket, the second the PID of -the gpg-agent and the protocol version which should be set to 1. When -starting the gpg-agent as described in its documentation, this -variable is set to the correct value. The option ---gpg-agent-info can -be used to override it. - -@item http_proxy -Only honored when the keyserver-option -honor-http-proxy is set. - -@end table - -@majorheading FILES -@table @asis -@item ~/.gnupg/secring.gpg -The secret keyring - -@item ~/.gnupg/secring.gpg.lock -and the lock file - -@item ~/.gnupg/pubring.gpg -The public keyring - -@item ~/.gnupg/pubring.gpg.lock -and the lock file - -@item ~/.gnupg/trustdb.gpg -The trust database - -@item ~/.gnupg/trustdb.gpg.lock -and the lock file - -@item ~/.gnupg/random_seed -used to preserve the internal random pool - -@item ~/.gnupg/gpg.conf -Default configuration file - -@item ~/.gnupg/options -Old style configuration file; only used when gpg.conf -is not found - -@item /usr[/local]/share/gnupg/options.skel -Skeleton options file - -@item /usr[/local]/lib/gnupg/ -Default location for extensions - -@end table - -@majorheading WARNINGS -Use a *good* password for your user account and a *good* passphrase -to protect your secret key. This passphrase is the weakest part of the -whole system. Programs to do dictionary attacks on your secret keyring -are very easy to write and so you should protect your "~/.gnupg/" -directory very well. - -Keep in mind that, if this program is used over a network (telnet), it -is *very* easy to spy out your passphrase! - -If you are going to verify detached signatures, make sure that the -program knows about it; either be giving both filenames on the -command line or using @samp{-} to specify stdin. - -@majorheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS -GnuPG tries to be a very flexible implementation of the OpenPGP -standard. In particular, GnuPG implements many of the "optional" -parts of the standard, such as the RIPEMD/160 hash, and the ZLIB -compression algorithms. It is important to be aware that not all -OpenPGP programs implement these optional algorithms and that by -forcing their use via the ---cipher-algo, --digest-algo, ----cert-digest-algo, or --compress-algo options in GnuPG, it is -possible to create a perfectly valid OpenPGP message, but one that -cannot be read by the intended recipient. - -For example, as of this writing, no version of official PGP supports -the BLOWFISH cipher algorithm. If you use it, no PGP user will be -able to decrypt your message. The same thing applies to the ZLIB -compression algorithm. By default, GnuPG uses the OpenPGP preferences -system that will always do the right thing and create messages that -are usable by all recipients, regardless of which OpenPGP program they -use. Only override this safe default if you know what you are doing. - -If you absolutely must override the safe default, or if the -preferences on a given key are invalid for some reason, you are far -better off using the ---pgp2, --pgp6, --pgp7, or --pgp8 options. These -options are safe as they do not force any particular algorithms in -violation of OpenPGP, but rather reduce the available algorithms to a -"PGP-safe" list. - -@majorheading BUGS -On many systems this program should be installed as setuid(root). This -is necessary to lock memory pages. Locking memory pages prevents the -operating system from writing memory pages to disk. If you get no -warning message about insecure memory your operating system supports -locking without being root. The program drops root privileges as soon -as locked memory is allocated. - -@bye diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi deleted file mode 100644 index 4bb688c44..000000000 --- a/doc/gpgsm.texi +++ /dev/null @@ -1,848 +0,0 @@ -@c Copyright (C) 2002 Free Software Foundation, Inc. -@c This is part of the GnuPG manual. -@c For copying conditions, see the file gnupg.texi. - -@node Invoking GPGSM -@chapter Invoking GPGSM -@cindex GPGSM command options -@cindex command options -@cindex options, GPGSM command - -@c man begin DESCRIPTION - -@sc{gpgsm} is a tool similar to @sc{gpg} to provide digital encryption -and signing servicesd on X.509 certificates and the CMS protocoll. It -is mainly used as a backend for S/MIME mail processing. @sc{gpgsm} -includes a full features certificate management and complies with all -rules defined for the German Sphinx project. - -@c man end - -@xref{Option Index}, for an index to GPGSM's commands and options. - -@menu -* GPGSM Commands:: List of all commands. -* GPGSM Options:: List of all options. -* GPGSM Examples:: Some usage examples. - -Developer information: -* Unattended Usage:: Using @sc{gpgsm} from other programs. -* GPGSM Protocol:: The protocol the server mode uses. -@end menu - -@c man begin COMMANDS - -@node GPGSM Commands -@section Commands - -Commands are not distinguished from options execpt for the fact that -only one one command is allowed. - -@menu -* General Commands:: Commands not specific to the functionality. -* Operational Commands:: Commands to select the type of operation. -* Certificate Management:: How to manage certificates. -@end menu - -@node General Commands -@subsection Commands not specific to the function - -@table @gnupgtabopt -@item --version -@opindex version -Print the program version and licensing information. Not that you can -abbreviate this command. - -@item --help, -h -@opindex help -Print a usage message summarizing the most usefule command-line options. -Not that you can abbreviate this command. - -@item --dump-options -@opindex dump-options -Print a list of all available options and commands. Not that you can -abbreviate this command. -@end table - - - -@node Operational Commands -@subsection Commands to select the type of operation - -@table @gnupgtabopt -@item --encrypt -@opindex encrypt -Perform an encryption. - -@item --decrypt -@opindex decrypt -Perform a decryption; the type of input is automatically detmerined. It -may either be in binary form or PEM encoded; automatic determination of -base-64 encoding is not done. - -@item --sign -@opindex sign -Create a digital signature. The key used is either the fist one found -in the keybox or thise set with the -u option - -@item --verify -@opindex verify -Check a signature file for validity. Depending on the arguments a -detached signatrue may also be checked. - -@item --server -@opindex server -Run in server mode and wait for commands on the @code{stdin}. - -@item --call-dirmngr @var{command} [@var{args}] -@opindex call-dirmngr -Behave as a Dirmngr client issuing the request @var{command} with the -optional list of @var{args}. The output of the Dirmngr is printed -stdout. Please note that file names given as arguments should have an -absulte file name (i.e. commencing with @code{/} because they are -passed verbatim to the Dirmngr and the working directory of the -Dirmngr might not be the same as the one of this client. Currently it -is not possible to pass data via stdin to the Dirmngr. @var{command} -should not contain spaces. - -This is command is required for certain maintaining tasks of the dirmngr -where a dirmngr must be able to call back to gpgsm. See the Dirmngr -manual for details. - -@item --call-protect-tool @var{arguments} -@opindex call-protect-tool -Certain maintenance operations are done by an external program call -@command{gpg-protect-tool}; this is usually not installed in a directory -listed in the PATH variable. This command provides a simple wrapper to -access this tool. @var{arguments} are passed verbatim to this command; -use @samp{--help} to get a list of supported operations. - - -@end table - - -@node Certificate Management -@subsection How to manage the certificate and keys - -@table @gnupgtabopt -@item --gen-key -@opindex gen-key -Generate a new key and a certificate request. - -@item --list-keys -@itemx -k -@opindex list-keys -List all available certificates stored in the local key database. - -@item --list-secret-keys -@itemx -K -@opindex list-secret-keys -List all available certificates for which a corresponding a secret key -is available. - -@item --list-external-keys @var{pattern} -@opindex list-keys -List certificates matching @var{pattern} using an external server. This -utilizes the @code{dirmngr} service. - -@item --dump-keys -@opindex dump-keys -List all available certificates stored in the local key database using a -format useful mainly for debugging. - -@item --dump-secret-keys -@opindex dump-secret-keys -List all available certificates for which a corresponding a secret key -is available using a format useful mainly for debugging. - -@item --dump-external-keys @var{pattern} -@opindex dump-keys -List certificates matching @var{pattern} using an external server. -This utilizes the @code{dirmngr} service. It uses a format useful -mainly for debugging. - -@item --keydb-clear-some-cert-flags -@opindex keydb-clear-some-cert-flags -This is a debugging aid to reset certain flags in the key database -which are used to cache certain certificate stati. It is especially -useful if a bad CRL or a weird running OCSP reponder did accidently -revoke certificate. There is no security issue with this command -because gpgsm always make sure that the validity of a certificate is -checked right before it is used. - -@item --delete-keys @var{pattern} -@opindex delete-keys -Delete the keys matching @var{pattern}. - -@item --export [@var{pattern}] -@opindex export -Export all certificates stored in the Keybox or those specified by the -optional @var{pattern}. When using along with the @code{--armor} option -a few informational lines are prepended before each block. - -@item --export-secret-key-p12 @var{key-id} -@opindex export -Export the private key and the certificate identified by @var{key-id} -in a PKCS#12 format. When using along with the @code{--armor} option -a few informational lines are prepended to the output. Note, that the -PKCS#12 format is higly insecure and this command is only provided if -there is no other way to exchange the private key. - -@item --learn-card -@opindex learn-card -Read information about the private keys from the smartcard and import -the certificates from there. This command utilizes the @sc{gpg-agent} -and in turn the @sc{scdaemon}. - -@item --passwd @var{user_id} -@opindex passwd -Change the passphrase of the private key belonging to the certificate -specified as @var{user_id}. Note, that changing the passphrase/PIN of a -smartcard is not yet supported. - -@end table - - -@node GPGSM Options -@section Option Summary - -GPGSM comes features a bunch ofoptions to control the exact behaviour -and to change the default configuration. - -@menu -* Configuration Options:: How to change the configuration. -* Certificate Options:: Certificate related options. -* Input and Output:: Input and Output. -* CMS Options:: How to change how the CMS is created. -* Esoteric Options:: Doing things one usually don't want to do. -@end menu - -@c man begin OPTIONS - -@node Configuration Options -@subsection How to change the configuration - -These options are used to change the configuraton and are usually found -in the option file. - -@table @gnupgtabopt - -@item --options @var{file} -@opindex options -Reads configuration from @var{file} instead of from the default -per-user configuration file. The default configuration file is named -@file{gpgsm.conf} and expected in the @file{.gnupg} directory directly -below the home directory of the user. - -@item -v -@item --verbose -@opindex v -@opindex verbose -Outputs additional information while running. -You can increase the verbosity by giving several -verbose commands to @sc{gpgsm}, such as @samp{-vv}. - -@item --policy-file @var{filename} -@opindex policy-file -Change the default name of the policy file to @var{filename}. - -@item --agent-program @var{file} -@opindex agent-program -Specify an agent program to be used for secret key operations. The -default value is the @file{/usr/local/bin/gpg-agent}. This is only used -as a fallback when the envrionment variable @code{GPG_AGENT_INFO} is not -set or a running agent can't be connected. - -@item --dirmngr-program @var{file} -@opindex dirmnr-program -Specify a dirmngr program to be used for @acronym{CRL} checks. The -default value is @file{/usr/sbin/dirmngr}. This is only used as a -fallback when the environment variable @code{DIRMNGR_INFO} is not set or -a running dirmngr can't be connected. - -@item --no-secmem-warning -@opindex no-secmem-warning -Don't print a warning when the so called "secure memory" can't be used. - - - -@end table - - -@node Certificate Options -@subsection Certificate related options - -@table @gnupgtabopt - -@item --enable-policy-checks -@itemx --disable-policy-checks -@opindex enable-policy-checks -@opindex disable-policy-checks -By default policy checks are enabled. These options may be used to -change it. - -@item --enable-crl-checks -@itemx --disable-crl-checks -@opindex enable-crl-checks -@opindex disable-crl-checks -By default the @acronym{CRL} checks are enabled and the DirMngr is used -to check for revoked certificates. The disable option is most useful -with an off-line network connection to suppress this check. - -@item --force-crl-refresh -@opindex force-crl-refresh -Tell the dirmngr to reload the CRL for each request. For better -performance, the dirmngr will actually optimize this by suppressing -the loading for short time intervalls (e.g. 30 minutes). This option -is useful to make sure that a fresh CRL is available for certificates -hold in the keybox. The suggested way of doing this is by using it -along with the option @code{--with-validation} for a ke listing -command. This option should not be used in a configuration file. - -@item --enable-ocsp -@itemx --disable-ocsp -@opindex enable-ocsp -@opindex disable-ocsp -Be default @acronym{OCSP} checks are disabled. The enable opton may -be used to enable OCSP checks via Dirmngr. If @acronym{CRL} checks -are also enabled, CRLs willbe used as a fallback if for some reason an -OCSP request won't succeed. - -@end table - -@node Input and Output -@subsection Input and Output - -@table @gnupgtabopt -@item --armor -@itemx -a -@opindex armor -@opindex -a -Create PEM encoded output. Default is binary output. - -@item --base64 -@opindex base64 -Create Base-64 encoded output; i.e. PEM without the header lines. - -@item --assume-armor -@opindex assume-armor -Assume the input data is PEM encoded. Default is to autodetect the -encoding but this is may fail. - -@item --assume-base64 -@opindex assume-base64 -Assume the input data is plain base-64 encoded. - -@item --assume-binary -@opindex assume-binary -Assume the input data is binary encoded. - -@item --local-user @var{user_id} -@item -u @var{user_id} -@opindex local-user -@opindex -u -Set the user(s) to be used for signing. The default is the first -secret key found in the database. - -@item --with-key-data -@opindex with-key-data -Displays extra information with the @code{--list-keys} commands. Especially -a line tagged @code{grp} is printed which tells you the keygrip of a -key. This string is for example used as the file name of the -secret key. - -@item --with-validation -@opindex with-validation -When doing a key listing, do a full validation check for each key and -print the result. This is usually a slow operation because it -requires a CRL lookup and other operations. - -@item --with-md5-fingerprint -For standard key listings, also print the MD5 fingerprint of the -certificate. - -@end table - -@node CMS Options -@subsection How to change how the CMS is created. - -@table @gnupgtabopt -@item --include-certs @var{n} -Using @var{n} of -2 includes all certificate except for the root cert, --1 includes all certs, 0 does not include any certs, 1 includes only -the signers cert (this is the default) and all other positive -values include up to @var{n} certificates starting with the signer cert. - -@end table - - - -@node Esoteric Options -@subsection Doing things one usually don't want todo. - - -@table @gnupgtabopt - -@item --faked-system-time @var{epoch} -@opindex faked-system-time -This option is only useful for testing; it sets the system time back or -forth to @var{epoch} which is the number of seconds elapsed since the year -1970. - -@item --debug-level @var{level} -@opindex debug-level -Select the debug level for investigating problems. @var{level} may be -one of: - - @table @code - @item none - no debugging at all. - @item basic - some basic debug messages - @item advanced - more verbose debug messages - @item expert - even more detailed messages - @item guru - all of the debug messages you can get - @end table - -How these messages are mapped to the actual debugging flags is not -specified and may change with newer releaes of this program. They are -however carefully selected to best aid in debugging. - -@item --debug @var{flags} -@opindex debug -This option is only useful for debugging and the behaviour may change -at any time without notice; using @code{--debug-levels} is the -preferred method to select the debug verbosity. FLAGS are bit encoded -and may be given in usual C-Syntax. The currently defined bits are: - - @table @code - @item 0 (1) - X.509 or OpenPGP protocol related data - @item 1 (2) - values of big number integers - @item 2 (4) - low level crypto operations - @item 5 (32) - memory allocation - @item 6 (64) - caching - @item 7 (128) - show memory statistics. - @item 9 (512) - write hashed data to files named @code{dbgmd-000*} - @item 10 (1024) - trace Assuan protocol - @end table - -Note, that all flags set using this option may get overriden by -@code{--debug-level}. - -@item --debug-all -@opindex debug-all -Same as @code{--debug=0xffffffff} - -@item --debug-allow-core-dump -@opindex debug-allow-core-dump -Usually gpgsm tries to avoid dumping core by well written code and by -disabling core dumps for security reasons. However, bugs are pretty -durable beasts and to squash them it is sometimes useful to have a core -dump. This option enables core dumps unless the Bad Thing happened -before the option parsing. - -@item --debug-no-chain-validation -@opindex debug-no-chain-validation -This is actually not a debugging option but only useful as such. It -lets gpgsm bypass all certificate chain validation checks. - -@item --debug-ignore-expiration -@opindex debug-ignore-expiration -This is actually not a debugging option but only useful as such. It -lets gpgsm ignore all notAfter dates, this is used by the regresssion -tests. - -@end table - -All the long options may also be given in the configuration file after -stripping off the two leading dashes. - - - -@c -@c Examples -@c -@node GPGSM Examples -@section Examples - -@c man begin EXAMPLES - -@example -$ gpgsm -er goo@@bar.net <plaintext >ciphertext -@end example - -@c man end - - - -@c --------------------------------- -@c The machine interface -@c -------------------------------- -@node Unattended Usage -@section Unattended Usage - -@sc{gpgsm} is often used as a backend engine by other software. To help -with this a machine interface has been defined to have an unambiguous -way to do this. This is most likely used with the @code{--server} command -but may also be used in the standard operation mode by using the -@code{--status-fd} option. - -@menu -* Automated signature checking:: Automated signature checking. -@end menu - -@node Automated signature checking,,,Unattended Usage -@section Automated signature checking - -It is very important to understand the semantics used with signature -verification. Checking a signature is not as simple as it may sound and -so the ooperation si a bit complicated. In mosted cases it is required -to look at several status lines. Here is a table of all cases a signed -message may have: - -@table @asis -@item The signature is valid -This does mean that the signature has been successfully verified, the -certificates are all sane. However there are two subcases with -important information: One of the certificates may have expired or a -signature of a message itself as expired. It is a sound practise to -consider such a signature still as valid but additional information -should be displayed. Depending on the subcase @sc{gpgsm} will issue -these status codes: - @table @asis - @item signature valid and nothing did expire - @code{GOODSIG}, @code{VALIDSIG}, @code{TRUST_FULLY} - @item signature valid but at least one certificate has expired - @code{EXPKEYSIG}, @code{VALIDSIG}, @code{TRUST_FULLY} - @item signature valid but expired - @code{EXPSIG}, @code{VALIDSIG}, @code{TRUST_FULLY} - Note, that this case is currently not implemented. - @end table - -@item The signature is invalid -This means that the signature verification failed (this is an indication -of af a transfer error, a programm error or tampering with the message). -@sc{gpgsm} issues one of these status codes sequences: - @table @code - @item @code{BADSIG} - @item @code{GOODSIG}, @code{VALIDSIG} @code{TRUST_NEVER} - @end table - -@item Error verifying a signature -For some reason the signature could not be verified, i.e. it can't be -decided whether the signature is valid or invalid. A common reason for -this is a missing certificate. - -@end table - - -@c -@c Assuan Protocol -@c -@node GPGSM Protocol -@section The Protocol the Server Mode Uses. - -Description of the protocol used to access GPGSM. GPGSM does implement -the Assuan protocol and in addition provides a regular command line -interface which exhibits a full client to this protocol (but uses -internal linking). To start gpgsm as a server the commandline "gpgsm ---server" must be used. Additional options are provided to select the -communication method (i.e. the name of the socket). - -We assume that the connection has already been established; see the -Assuan manual for details. - -@menu -* GPGSM ENCRYPT:: Encrypting a message. -* GPGSM DECRYPT:: Decrypting a message. -* GPGSM SIGN:: Signing a message. -* GPGSM VERIFY:: Verifying a message. -* GPGSM GENKEY:: Generating a key. -* GPGSM LISTKEYS:: List available keys. -* GPGSM EXPORT:: Export certificates. -* GPGSM IMPORT:: Import certificates. -* GPGSM DELETE:: Delete certificates. -@end menu - - -@node GPGSM ENCRYPT -@subsection Encrypting a Message - -Before encrytion can be done the recipient must be set using the -command: - -@example - RECIPIENT @var{userID} -@end example - -Set the recipient for the encryption. @var{userID} should be the -internal representation of the key; the server may accept any other way -of specification. If this is a valid and trusted recipient the server -does respond with OK, otherwise the return is an ERR with the reason why -the recipient can't be used, the encryption will then not be done for -this recipient. If the policy is not to encrypt at all if not all -recipients are valid, the client has to take care of this. All -@code{RECIPIENT} commands are cumulative until a @code{RESET} or an -successful @code{ENCRYPT} command. - -@example - INPUT FD=@var{n} [--armor|--base64|--binary] -@end example - -Set the file descriptor for the message to be encrypted to @var{n}. -Obviously the pipe must be open at that point, the server establishes -its own end. If the server returns an error the client should consider -this session failed. - -The @code{--armor} option may be used to advice the server that the -input data is in @acronym{PEM} format, @code{--base64} advices that a -raw base-64 encoding is used, @code{--binary} advices of raw binary -input (@acronym{BER}). If none of these options is used, the server -tries to figure out the used encoding, but this may not always be -correct. - -@example - OUTPUT FD=@var{n} [--armor|--base64] -@end example - -Set the file descriptor to be used for the output (i.e. the encrypted -message). Obviously the pipe must be open at that point, the server -establishes its own end. If the server returns an error he client -should consider this session failed. - -The option armor encodes the output in @acronym{PEM} format, the -@code{--base64} option applies just a base 64 encoding. No option -creates binary output (@acronym{BER}). - -The actual encryption is done using the command - -@example - ENCRYPT -@end example - -It takes the plaintext from the @code{INPUT} command, writes to the -ciphertext to the file descriptor set with the @code{OUTPUT} command, -take the recipients from all the recipients set so far. If this command -fails the clients should try to delete all output currently done or -otherwise mark it as invalid. GPGSM does ensure that there won't be any -security problem with leftover data on the output in this case. - -This command should in general not fail, as all necessary checks have -been done while setting the recipients. The input and output pipes are -closed. - - -@node GPGSM DECRYPT -@subsection Decrypting a message - -Input and output FDs are set the same way as in encryption, but -@code{INPUT} refers to the ciphertext and output to the plaintext. There -is no need to set recipients. GPGSM automatically strips any -@acronym{S/MIME} headers from the input, so it is valid to pass an -entire MIME part to the INPUT pipe. - -The encryption is done by using the command - -@example - DECRYPT -@end example - -It performs the decrypt operation after doing some check on the internal -state. (e.g. that all needed data has been set). Because it utilizes -the GPG-Agent for the session key decryption, there is no need to ask -the client for a protecting passphrase - GpgAgent takes care of this by -requesting this from the user. - - -@node GPGSM SIGN -@subsection Signing a Message - -Signing is usually done with these commands: - -@example - INPUT FD=@var{n} [--armor|--base64|--binary] -@end example - -This tells GPGSM to read the data to sign from file descriptor @var{n}. - -@example - OUTPUT FD=@var{m} [--armor|--base64] -@end example - -Write the output to file descriptor @var{m}. If a detached signature is -requested, only the signature is written. - -@example - SIGN [--detached] -@end example - -Sign the data set with the INPUT command and write it to the sink set by -OUTPUT. With @code{--detached}, a detached signature is created -(surprise). - -The key used for signining is the default one or the one specified in -the configuration file. To get finer control over the keys, it is -possible to use the command - -@example - SIGNER @var{userID} -@end example - -to the signer's key. @var{userID} should be the -internal representation of the key; the server may accept any other way -of specification. If this is a valid and trusted recipient the server -does respond with OK, otherwise the return is an ERR with the reason why -the key can't be used, the signature will then not be created using -this key. If the policy is not to sign at all if not all -keys are valid, the client has to take care of this. All -@code{SIGNER} commands are cumulative until a @code{RESET} is done. -Note that a @code{SIGN} does not reset this list of signers which is in -contrats to the @code{RECIPIENT} command. - - -@node GPGSM VERIFY -@subsection Verifying a Message - -To verify a mesage the command: - -@example - VERIFY -@end example - -is used. It does a verify operation on the message send to the input FD. -The result is written out using status lines. If an output FD was -given, the signed text will be written to that. If the signature is a -detached one, the server will inquire about the signed material and the -client must provide it. - -@node GPGSM GENKEY -@subsection Generating a Key - -This is used to generate a new keypair, store the secret part in the -@acronym{PSE} and the public key in the key database. We will probably -add optional commands to allow the client to select whether a hardware -token is used to store the key. Configuration options to GPGSM can be -used to restrict the use of this command. - -@example - GENKEY -@end example - -GPGSM checks whether this command is allowed and then does an -INQUIRY to get the key parameters, the client should then send the -key parameters in the native format: - -@example - S: INQUIRE KEY_PARAM native - C: D foo:fgfgfg - C: D bar - C: END -@end example - -Please note that the server may send Status info lines while reading the -data lines from the client. After this the key generation takes place -and the server eventually does send an ERR or OK response. Status lines -may be issued as a progress indicator. - - -@node GPGSM LISTKEYS -@subsection List available keys - -To list the keys in the internal database or using an external key -provider, the command: - -@example - LISTKEYS @var{pattern} -@end example - -is used. To allow multiple patterns (which are ORed during the search) -quoting is required: Spaces are to be translated into "+" or into "%20"; -in turn this requires that the usual escape quoting rules are done. - -@example - LISTSECRETKEYS @var{pattern} -@end example - -Lists only the keys where a secret key is available. - -The list commands commands are affected by the option - -@example - OPTION list-mode=@var{mode} -@end example - -where mode may be: -@table @code -@item 0 -Use default (which is usually the same as 1). -@item 1 -List only the internal keys. -@item 2 -List only the external keys. -@item 3 -List internal and external keys. -@end table - -Note that options are valid for the entire session. - - -@node GPGSM EXPORT -@subsection Export certificates - -To export certificate from the internal key database the command: - -@example - EXPORT @var{pattern} -@end example - -is used. To allow multiple patterns (which are ORed) quoting is -required: Spaces are to be translated into "+" or into "%20"; in turn -this requires that the usual escape quoting rules are done. - -The format of the output depends on what was set with the OUTPUT -command. When using @acronym{PEM} encoding a few informational lines -are prepended. - - -@node GPGSM IMPORT -@subsection Import certificates - -To import certificates into the internal key database, the command - -@example - IMPORT -@end example - -is used. The data is expected on the file descriptor set with the -@code{INPUT} command. Certain checks are performend on the -certificate. Note that the code will also handle PKCS\#12 files and -import private keys; a helper program is used for that. - - -@node GPGSM DELETE -@subsection Delete certificates - -To delete certificate the command - -@example - DELKEYS @var{pattern} -@end example - -is used. To allow multiple patterns (which are ORed) quoting is -required: Spaces are to be translated into "+" or into "%20"; in turn -this requires that the usual escape quoting rules are done. - -The certificates must be specified unambiguously otherwise an error is -returned. - diff --git a/doc/gpl.texi b/doc/gpl.texi deleted file mode 100644 index ca0508fad..000000000 --- a/doc/gpl.texi +++ /dev/null @@ -1,397 +0,0 @@ -@node Copying -@appendix 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 - -@appendixsubsec 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 -@appendixsubsec 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 -@unnumberedsec 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/doc/scdaemon.texi b/doc/scdaemon.texi deleted file mode 100644 index 51ec4b34c..000000000 --- a/doc/scdaemon.texi +++ /dev/null @@ -1,387 +0,0 @@ -@c Copyright (C) 2002 Free Software Foundation, Inc. -@c This is part of the GnuPG manual. -@c For copying conditions, see the file gnupg.texi. - -@node Invoking SCDAEMON -@chapter Invoking the SCDAEMON -@cindex SCDAEMON command options -@cindex command options -@cindex options, SCDAEMON command - -@c man begin DESCRIPTION - -The @sc{scdaeon} is a daemon to manage smartcards. It is usually -invoked by gpg-agent and in general not used directly. - -@c man end - -@xref{Option Index}, for an index to GPG-AGENTS's commands and options. - -@menu -* Scdaemon Commands:: List of all commands. -* Scdaemon Options:: List of all options. -* Scdaemon Examples:: Some usage examples. -* Scdaemon Protocol:: The protocol the daemon uses. -@end menu - -@c man begin COMMANDS - -@node Scdaemon Commands -@section Commands - -Commands are not distinguished from options execpt for the fact that -only one one command is allowed. - -@table @gnupgtabopt -@item --version -@opindex version -Print the program version and licensing information. Not that you can -abbreviate this command. - -@item --help, -h -@opindex help -Print a usage message summarizing the most usefule command-line options. -Not that you can abbreviate this command. - -@item --dump-options -@opindex dump-options -Print a list of all available options and commands. Not that you can -abbreviate this command. - -@item --server -@opindex server -Run in server mode and wait for commands on the @code{stdin}. This is -default mode is to create a socket and listen for commands there. - -@item --daemon -@opindex daemon -Run the program in the background. This option is required to prevent -it from being accidently running in the background. - -@item --print-atr -@opindex print-atr -This is mainly a debugging command, used to print the ATR -(Answer-To-Reset) of a card and exit immediately. - -@end table - - -@c man begin OPTIONS - -@node Scdaemon Options -@section Option Summary - -@table @gnupgtabopt - -@item --options @var{file} -@opindex options -Reads configuration from @var{file} instead of from the default -per-user configuration file. The default configuration file is named -@file{scdaemon.conf} and expected in the @file{.gnupg} directory directly -below the home directory of the user. - -@item -v -@item --verbose -@opindex v -@opindex verbose -Outputs additional information while running. -You can increase the verbosity by giving several -verbose commands to @sc{gpgsm}, such as @samp{-vv}. - -@item --debug-level @var{level} -@opindex debug-level -Select the debug level for investigating problems. @var{level} may be -one of: - - @table @code - @item none - no debugging at all. - @item basic - some basic debug messages - @item advanced - more verbose debug messages - @item expert - even more detailed messages - @item guru - all of the debug messages you can get - @end table - -How these messages are mapped to the actual debugging flags is not -specified and may change with newer releaes of this program. They are -however carefully selected to best aid in debugging. - -@item --debug @var{flags} -@opindex debug -This option is only useful for debugging and the behaviour may change at -any time without notice. FLAGS are bit encoded and may be given in -usual C-Syntax. The currently defined bits are: - - @table @code - @item 0 (1) - X.509 or OpenPGP protocol related data - @item 1 (2) - values of big number integers - @item 2 (4) - low level crypto operations - @item 5 (32) - memory allocation - @item 6 (64) - caching - @item 7 (128) - show memory statistics. - @item 9 (512) - write hashed data to files named @code{dbgmd-000*} - @item 10 (1024) - trace Assuan protocol - @item 12 (4096) - bypass all certificate validation - @end table - -@item --debug-all -@opindex debug-all -Same as @code{--debug=0xffffffff} - -@item --debug-wait @var{n} -@opindex debug-wait -When running in server mode, wait @var{n} seconds before entering the -actual processing loop and print the pid. This gives time to attach a -debugger. - -@item --debug-sc @var{n} -@opindex debug-sc -Set the debug level of the OpenSC library to @var{n}. - -@item --no-detach -@opindex no-detach -Don't detach the process from the console. This is manly usefule for -debugging. - -@item --log-file @var{file} -@opindex log-file -Append all logging output to @var{file}. This is very helpful in -seeing what the agent actually does. - -@item --reader-port @var{number} -When the program has been build without OpenSC support, this option must -be used to specify the port of the card terminal. A value of 0 refers -to the first serial device; add 32768 to access USB devices. The -default is 32768 (first USB device). - -@item --ctapi-driver @var{library} -Use @var{library} to access the smartcard reader. The current default -is @code{libtowitoko.so}. - - -@item --allow-admin -@itemx --deny-admin -@opindex allow-admin -@opindex deny-admin -This enables the use of Admin class commands for card application -where this is supported. Currently we support it for the OpenPGP -card. Deny is the default. This commands is useful to inhibit -accidental access to admin class command which could ultimately lock -the card through worng PIN numbers. - -@end table - -All the long options may also be given in the configuration file after -stripping off the two leading dashes. - - -@c -@c Examples -@c -@node Scdaemon Examples -@section Examples - -@c man begin EXAMPLES - -@example -$ scdaemon --server -v -@end example - -@c man end - -@c -@c Assuan Protocol -@c -@node Scdaemon Protocol -@section Scdaemon's Assuan Protocol - -The SC-Daemon should be started by the system to provide access to -external tokens. Using Smartcards on a multi-user system does not -make much sense expcet for system services, but in this case no -regular user accounts are hosted on the machine. - -A client connects to the SC-Daemon by connecting to the socket named -@file{/var/run/scdaemon/socket}, configuration information is read from -@var{/etc/scdaemon.conf} - -Each connection acts as one session, SC-Daemon takes care of -syncronizing access to a token between sessions. - -@menu -* Scdaemon SERIALNO:: Return the serial number. -* Scdaemon LEARN:: Read all useful information from the card. -* Scdaemon READCERT:: Return a certificate. -* Scdaemon READKEY:: Return a public key. -* Scdaemon PKSIGN:: Signing data with a Smartcard. -* Scdaemon PKDECRYPT:: Decrypting data with a Smartcard. -* Scdaemon GETATTR:: Read an attribute's value. -* Scdaemon SETATTR:: Update an attribute's value. -* Scdaemon GENKEY:: Generate a new key on-card. -* Scdaemon RANDOM:: Return random bytes generate on-card. -* Scdaemon PASSWD:: Change PINs. -* Scdaemon CHECKPIN:: Perform a VERIFY operation. -@end menu - -@node Scdaemon SERIALNO -@subsection Return the serial number - -This command should be used to check for the presence of a card. It is -special in that it can be used to reset the card. Most other commands -will return an error when a card change has been detected and the use of -this function is therefore required. - -Background: We want to keep the client clear of handling card changes -between operations; i.e. the client can assume that all operations are -done on the same card unless he call this function. - -@example - SERIALNO -@end example - -Return the serial number of the card using a status reponse like: - -@example - S SERIALNO D27600000000000000000000 0 -@end example - -The trailing 0 should be ignored for now, it is reserved for a future -extension. The serial number is the hex encoded value identified by -the @code{0x5A} tag in the GDO file (FIX=0x2F02). - - - -@node Scdaemon LEARN -@subsection Read all useful information from the card - -@example - LEARN [--force] -@end example - -Learn all useful information of the currently inserted card. When -used without the force options, the command might do an INQUIRE -like this: - -@example - INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp> -@end example - -The client should just send an @code{END} if the processing should go on -or a @code{CANCEL} to force the function to terminate with a cancel -error message. The response of this command is a list of status lines -formatted as this: - -@example - S KEYPAIRINFO @var{hexstring_with_keygrip} @var{hexstring_with_id} -@end example - -If there is no certificate yet stored on the card a single "X" is -returned in @var{hexstring_with_keygrip}. - -@node Scdaemon READCERT -@subsection Return a certificate - -@example - READCERT @var{hexified_certid} -@end example - -This function is used to read a certificate identified by -@var{hexified_certid} from the card. - - -@node Scdaemon READKEY -@subsection Return a public key - -@example -READKEY @var{hexified_certid} -@end example - -Return the public key for the given cert or key ID as an standard -S-Expression. - - - -@node Scdaemon PKSIGN -@subsection Signing data with a Smartcard - -To sign some data the caller should use the command - -@example - SETDATA @var{hexstring} -@end example - -to tell scdaemon about the data to be signed. The data must be given in -hex notation. The actual signing is done using the command - -@example - PKSIGN @var{keyid} -@end example - -where @var{keyid} is the hexified ID of the key to be used. The key id -may have been retrieved using the command @code{LEARN}. - - -@node Scdaemon PKDECRYPT -@subsection Decrypting data with a Smartcard - -To decrypt some data the caller should use the command - -@example - SETDATA @var{hexstring} -@end example - -to tell scdaemon about the data to be decrypted. The data must be given in -hex notation. The actual decryption is then done using the command - -@example - PKDECRYPT @var{keyid} -@end example - -where @var{keyid} is the hexified ID of the key to be used. - - -@node Scdaemon GETATTR -@subsection Read an attribute's value. - -TO BE WRITTEN. - -@node Scdaemon SETATTR -@subsection Update an attribute's value. - -TO BE WRITTEN. - -@node Scdaemon GENKEY -@subsection Generate a new key on-card. - -TO BE WRITTEN. - -@node Scdaemon RANDOM -@subsection Return random bytes generate on-card. - -TO BE WRITTEN. - - -@node Scdaemon PASSWD -@subsection Change PINs. - -TO BE WRITTEN. - - -@node Scdaemon CHECKPIN -@subsection Perform a VERIFY operation. - -TO BE WRITTEN. - - |