Taken from NewPG
authorWerner Koch <wk@gnupg.org>
Thu, 9 Jan 2003 13:24:01 +0000 (13:24 +0000)
committerWerner Koch <wk@gnupg.org>
Thu, 9 Jan 2003 13:24:01 +0000 (13:24 +0000)
doc/assuan.texi [new file with mode: 0644]
doc/contrib.texi [new file with mode: 0644]
doc/fdl.texi [new file with mode: 0644]
doc/gnupg.texi [new file with mode: 0644]
doc/gpg-agent.texi [new file with mode: 0644]
doc/gpgsm.texi [new file with mode: 0644]
doc/gpl.texi [new file with mode: 0644]
doc/scdaemon.texi [new file with mode: 0644]

diff --git a/doc/assuan.texi b/doc/assuan.texi
new file mode 100644 (file)
index 0000000..fbf513a
--- /dev/null
@@ -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 (file)
index 0000000..0b250ee
--- /dev/null
@@ -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 (file)
index 0000000..6e40e6d
--- /dev/null
@@ -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 (file)
index 0000000..de243a8
--- /dev/null
@@ -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 (file)
index 0000000..6148448
--- /dev/null
@@ -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 (file)
index 0000000..4d91bda
--- /dev/null
@@ -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 (file)
index 0000000..ca0508f
--- /dev/null
@@ -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 (file)
index 0000000..55f9f8a
--- /dev/null
@@ -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.
+