diff options
| -rw-r--r-- | doc/assuan.texi | 189 | ||||
| -rw-r--r-- | doc/contrib.texi | 63 | ||||
| -rw-r--r-- | doc/fdl.texi | 401 | ||||
| -rw-r--r-- | doc/gnupg.texi | 171 | ||||
| -rw-r--r-- | doc/gpg-agent.texi | 739 | ||||
| -rw-r--r-- | doc/gpgsm.texi | 738 | ||||
| -rw-r--r-- | doc/gpl.texi | 397 | ||||
| -rw-r--r-- | doc/scdaemon.texi | 297 |
8 files changed, 2995 insertions, 0 deletions
diff --git a/doc/assuan.texi b/doc/assuan.texi new file mode 100644 index 000000000..fbf513ad8 --- /dev/null +++ b/doc/assuan.texi @@ -0,0 +1,189 @@ +@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 modula 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 new file mode 100644 index 000000000..0b250eecc --- /dev/null +++ b/doc/contrib.texi @@ -0,0 +1,63 @@ +@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 desgned the system and wrote most of the original code. + +@end itemize + +FIXME: We need to copy a lot of credits from GnupG 1.0 to here. + + +We'd also like to thank the folks who have contributed time and energy in +testing GnuPG: + +@itemize @bullet +@item +Joe R. Hacker + +@item +And many others +@end itemize + +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/fdl.texi b/doc/fdl.texi new file mode 100644 index 000000000..6e40e6df9 --- /dev/null +++ b/doc/fdl.texi @@ -0,0 +1,401 @@ +@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 new file mode 100644 index 000000000..de243a8f7 --- /dev/null +++ b/doc/gnupg.texi @@ -0,0 +1,171 @@ +\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 administartion 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 + +* 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 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 new file mode 100644 index 000000000..61484485f --- /dev/null +++ b/doc/gpg-agent.texi @@ -0,0 +1,739 @@ +@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. + +@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 @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 --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{path} +@opindex pinentry-program +Use program @var{path} as the PIN entry. The default is installation +dependend and can be shown with the @code{--version} command. + +@item --scdaemon-program @var{path} +@opindex scdaemon-program +Use program @var{path} 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 SIGUSR1 +@cpindex SIGUSR1 +This signal increases the verbosity of the logging by one up to a value +of 5. + +@item SIGUSR2 +@cpindex SIGUSR2 +This signal decreases the verbosity of the logging by one. + +@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. + +@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 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 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/gpgsm.texi b/doc/gpgsm.texi new file mode 100644 index 000000000..4d91bda5b --- /dev/null +++ b/doc/gpgsm.texi @@ -0,0 +1,738 @@ +@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 filenames given as arguments should have an +absulte path 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 +@opindex list-keys +List all available certificates stored in the local key database. + +@item --list-secret-keys +@opindex list-secret-keys +List all available keys whenre a secret key is available. + +@item --list-external-keys @var{pattern} +@opindex list-keys +List certificates matching @var{pattern} using an external server. This +utilies the @code{dirmngr} service. + +@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 --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. + +@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. + +@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 filename of the +secret key. + +@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 @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-no-path-validation +@opindex debug-no-path-validation +This is actually not a debugging option but only useful as such. It +lets gpgsm bypass all certificate path validation checks. + +@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. + +@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 new file mode 100644 index 000000000..ca0508fad --- /dev/null +++ b/doc/gpl.texi @@ -0,0 +1,397 @@ +@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 new file mode 100644 index 000000000..55f9f8a0f --- /dev/null +++ b/doc/scdaemon.texi @@ -0,0 +1,297 @@ +@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. + +@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. + +@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 @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. + + +@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. +@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. + |