summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorWerner Koch <wk@gnupg.org>2003-01-09 14:24:01 +0100
committerWerner Koch <wk@gnupg.org>2003-01-09 14:24:01 +0100
commite9177199289d39863e29526cb4986ec4a7d9bba8 (patch)
tree5bf169aae63dd2649de0027708e9f35c02ab43ef /doc
parentUpdated from latest NewPG project (diff)
downloadgnupg2-e9177199289d39863e29526cb4986ec4a7d9bba8.tar.xz
gnupg2-e9177199289d39863e29526cb4986ec4a7d9bba8.zip
Taken from NewPG
Diffstat (limited to 'doc')
-rw-r--r--doc/assuan.texi189
-rw-r--r--doc/contrib.texi63
-rw-r--r--doc/fdl.texi401
-rw-r--r--doc/gnupg.texi171
-rw-r--r--doc/gpg-agent.texi739
-rw-r--r--doc/gpgsm.texi738
-rw-r--r--doc/gpl.texi397
-rw-r--r--doc/scdaemon.texi297
8 files changed, 2995 insertions, 0 deletions
diff --git a/doc/assuan.texi b/doc/assuan.texi
new file mode 100644
index 000000000..fbf513ad8
--- /dev/null
+++ b/doc/assuan.texi
@@ -0,0 +1,189 @@
+@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file gnupg.texi.
+
+@node Assuan
+@chapter Description of the Assuan protocol.
+
+The architecture of the modula GnuPG system is based on a couple of
+highly specialized modules which make up a network of client server
+communication. A common framework for intermodule communication is
+therefore needed and should be implemented in a library.
+
+Goals:
+
+@itemize @bullet
+@item Common framework for module communication
+@item Easy debugging
+@item Easy module testing
+@item Extendible
+@item Optional authentication and encryption facility
+@item Usable to access external hardware
+@end itemize
+
+
+Design criteria:
+
+@itemize @bullet
+@item Client Server with back channel
+@item Use a mainly text based protocol
+@item Escape certain control characters
+@item Allow indefinite data length
+@item Request confidentiality for parts of the communication
+@item Dummy module should allow direct linking of client and server.
+@item Inline data or descriptor passing for bulk data
+@item No protection against DoS needed
+@item Subliminal channels are not an issue
+@end itemize
+
+Implementation:
+
+The implementation is line based with a maximum line size of 1000
+octects. The default IPC mechanism are Unix Domain Sockets.
+
+On a connect request the server responds either with an okay or an error
+status. For authentication check the server may send an Inquiry
+Response prior to the first Okay, it may also issue Status messages.
+The server must check that the client is allowed to connect, this is
+done by requesting the credentials for the peer and comparing them to
+those of the server. This avoids attacks based on wrong socket
+permissions.
+
+It may choose to delay the first response in case of an error. The
+server never closes the connection - however the lower protocol may do
+so after some time of inactivity or when the connection is in an error
+state.
+
+All textual messages are assumed to be in UTF-8 unless otherwise noted.
+
+
+Server responses:
+
+@table @code
+@item OK [<arbitary debugging information>]
+Request was successful.
+
+@item ERR @var{errorcode} [<human readable error description>]
+Request could not be fulfilled. The error codes are mostly application
+specific except for a few common ones.
+
+@item S @var{keyword} <status information depending on keyword>
+Informational output by the server, still processing the request.
+
+@item # <string>
+Comment line issued only for debugging purposes. Totally ignored.
+
+@item D <raw data>
+Raw data returned to client. There must be exactly one space after the
+'D'. The values for '%', CR and LF must be percent escaped; this is
+encoded as %25, %0D and %0A. Only uppercase letters should be used in
+the hexadecimal representation. Other characters may be percent escaped
+for easier debugging. All these Data lines are considered one data
+stream up to the OK or ERR response. Status and Inquiry Responses
+may be mixed with the Data lines.
+
+@item INQUIRE @var{keyword}> <parameters>
+Server needs further information from the client. The client should
+answer with a command which is allowed after an inquiry. Note that the
+server does not confirm that client command but either continues
+processing or ends processing with an error status. Not all commands
+are allowed.
+@end table
+
+
+A client should only check the first letter of each line and then skip
+over to the next token (except for data lines where the raw data starts
+exactly after 2 bytes). Lines larger than 1000 bytes should be
+treated as a communication error. (The rationale for having a line
+length limit is to allow for easier multiplexing of multiple channels).
+
+
+Client requests:
+
+The server waits for client requests after he sent an Okay or Error.
+The client should not issue a request in other cases with the
+exception of the CANCEL command.
+
+@example
+@var{command} <parameters>
+@end example
+
+@var{command} is a one word string without preceding white space.
+Parameters are command specific, CR, LF and the percent signs should be
+percent escaped as described above. To send a backslash as the last
+character it should also be percent escaped. Percent escaping is
+allowed anywhere in the parameters but not in the command. The line
+ends with a CR, LF or just a LF.
+
+Not yet implemented feature: If there is a need for a parameter list
+longer than the line length limit (1000 characters including command and
+CR, LF), the last character of the line (right before the CR/LF or LF)
+must be a non-escape encoded backslash. The following line is then
+expected to be a continuation of the line with the backslash replaced by
+a blank and the line ending removed.
+
+@example
+D <raw data>
+@end example
+
+Raw data to the server. There must be exactly one space after the 'D'.
+The values for '%', CR and LF must be percent escaped; this is encoded
+as %25, %0D and %0A. Only uppercase letters should be used in the
+hexadecimal representation. Other characters may be percent escaped for
+easier debugging. All these Data lines are considered one data stream
+up to the OKAY or ERROR response. Status and Inquiry Responses may be
+mixed with the Data lines.
+
+@example
+END
+@end example
+
+
+
+Lines beginning with a @code{#} or empty lines are ignored. This is
+useful to comment test scripts.
+
+
+Although the commands are application specific, some of them are used by
+all protocols and partly directly supported by the Assuan library:
+
+@table @code
+@item CANCEL
+his is the one special command which aborts the current request. it can
+be sent at any time and the server will stop its operation right before
+it would send the next response line (of any type).
+
+@item BYE
+Close the connect, the server will reply with an @code{OK}.
+
+@item AUTH
+Not yet specified as we don't implement it in the first phase. See my
+mail to gpa-dev on 2001-10-25 about the rationale for measurements
+against local attacks.
+
+@item RESET
+Reset the connection but not any existing authentication. The server
+should release all resources associated with the connection.
+
+@item END
+Used by a client to mark the end of raw data. The server may send END
+to indicate a partial end of data.
+@end table
+
+
+Error Codes:
+
+Here we keep a list of error codes used in any Assuan based
+protocol. The format is the string @code{ERR}, white space, the error
+number, white space, a textual description of the error.
+
+@table @code
+
+@item 100 Unknown Command
+@item 101 Not Implemented
+
+@item 301 certificate has been revoked [DirMngr]
+@item 302 no CRL known for this certificate [DirMngr]
+@item 303 CRL is too old and a new one could not be retrieved [DirMngr]
+
+@end table
diff --git a/doc/contrib.texi b/doc/contrib.texi
new file mode 100644
index 000000000..0b250eecc
--- /dev/null
+++ b/doc/contrib.texi
@@ -0,0 +1,63 @@
+@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file gnupg.texi.
+
+@node Contributors
+@unnumbered Contributors to GnuPG
+@cindex contributors
+
+The GnuPG project would like to thank its many contributors. Without
+them the project would not have been nearly as successful as it has
+been. Any omissions in this list are accidental. Feel free to contact
+the maintainer if you have been left out or some of your contributions
+are not listed. Please keep this list in alphabetical order.
+
+@itemize @bullet
+
+@item
+Bernhard Herzog did extensive testing and tracked down a lot of bugs
+
+@item
+Bernhard Reiter made sure that we met the specifications and the
+deadlines. He did extensive testing and came up with a lot of suggestions.
+
+@item
+Jan-Oliver Wagner made sure that we met the specifications and the
+deadlines. He did extensive testing and came up with a lot of suggestions.
+
+@item
+Karl-Heinz Zimmer had to struggle with all the bugs and misconceptions
+while working on Kmail integration.
+
+@item
+Marcus Brinkman cleaned up the Assuan code and fixed bugs all over the place.
+
+@item
+Steffen Hansen had a hard time to write the dirmngr due to
+underspecified interfaces.
+
+@item
+Thomas Koester did extensive testing and tracked down a lot of bugs
+
+@item
+Werner Koch desgned the system and wrote most of the original code.
+
+@end itemize
+
+FIXME: We need to copy a lot of credits from GnupG 1.0 to here.
+
+
+We'd also like to thank the folks who have contributed time and energy in
+testing GnuPG:
+
+@itemize @bullet
+@item
+Joe R. Hacker
+
+@item
+And many others
+@end itemize
+
+And finally we'd like to thank everyone who uses these tools, submits
+bug reports and generally reminds us why we're doing this work in the
+first place.
diff --git a/doc/fdl.texi b/doc/fdl.texi
new file mode 100644
index 000000000..6e40e6df9
--- /dev/null
+++ b/doc/fdl.texi
@@ -0,0 +1,401 @@
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@cindex FDL, GNU Free Documentation License
+@center Version 1.1, March 2000
+
+@display
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
+@acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
+@acronym{PDF}, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+@end enumerate
+
+@page
+@appendixsubsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+@end group
+@end smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
diff --git a/doc/gnupg.texi b/doc/gnupg.texi
new file mode 100644
index 000000000..de243a8f7
--- /dev/null
+++ b/doc/gnupg.texi
@@ -0,0 +1,171 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename gnupg.info
+
+@include version.texi
+
+@macro copyrightnotice
+Copyright @copyright{} 2002 Free Software Foundation, Inc.
+@end macro
+@macro permissionnotice
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being ``GNU General Public License'', the Front-Cover
+texts being (a) (see below), and with the Back-Cover Texts being (b)
+(see below). A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+
+(a) The FSF's Front-Cover Text is:
+
+ A GNU Manual
+
+(b) The FSF's Back-Cover Text is:
+
+ You have freedom to copy and modify this GNU Manual, like GNU
+ software. Copies published by the Free Software Foundation raise
+ funds for GNU development.
+@end macro
+
+
+@settitle Using the GNU Privacy Guard
+
+@c Create a separate index for command line options.
+@defcodeindex op
+@c Merge the standard indexes into a single one.
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+
+@c printing stuff taken from gcc.
+@macro gnupgtabopt{body}
+@code{\body\}
+@end macro
+@macro gnupgoptlist{body}
+@smallexample
+\body\
+@end smallexample
+@end macro
+@c Makeinfo handles the above macro OK, TeX needs manual line breaks;
+@c they get lost at some point in handling the macro. But if @macro is
+@c used here rather than @alias, it produces double line breaks.
+@iftex
+@alias gol = *
+@end iftex
+@ifnottex
+@macro gol
+@end macro
+@end ifnottex
+
+
+@c Change the font used for @def... commands, since the default
+@c proportional one used is bad for names starting __.
+@tex
+\global\setfont\defbf\ttbshape{10}{\magstep1}
+@end tex
+
+@c %**end of header
+
+@ifnottex
+@dircategory GNU Utilities
+@direntry
+* gpg: (gnupg). OpenPGP encryption and signing tool.
+* gpgsm: (gnupg). S/MIME encryption and signing tool.
+@end direntry
+This file documents the use and the internals of the GNU Privacy Guard.
+
+This is Edition @value{EDITION}, last updated @value{UPDATED}, of
+@cite{The `GNU Privacy Guard' Manual}, for Version @value{VERSION}.
+@sp 1
+Published by the Free Software Foundation@*
+59 Temple Place - Suite 330@*
+Boston, MA 02111-1307 USA
+@sp 1
+@copyrightnotice{}
+@sp 1
+@permissionnotice{}
+@end ifnottex
+
+@setchapternewpage odd
+
+@titlepage
+@title Using the GNU Privacy Guard
+@subtitle Version @value{VERSION}
+@subtitle @value{UPDATED}
+@author Werner Koch @code{(wk@@gnupg.org)}
+
+@page
+@vskip 0pt plus 1filll
+@copyrightnotice{}
+@sp 2
+@permissionnotice{}
+@end titlepage
+@summarycontents
+@contents
+@page
+
+
+@node Top
+@top Introduction
+@cindex introduction
+
+This manual documents how to use the GNU Privay Guard system as well as
+the administartion and the architecture.
+
+@c * Gpg:: Using the OpenPGP protocol.
+@menu
+* Invoking GPGSM:: Using the S/MIME protocol.
+* Invoking GPG-AGENT:: How to launch the secret key daemon.
+* Invoking SCDAEMON:: How to handle Smartcards.
+
+Developer information
+
+* Assuan:: Description of the Assuan protocol.
+
+Miscellaneous
+
+* Copying:: GNU General Public License says
+ how you can copy and share GnuPG
+* GNU Free Documentation License:: How you can copy and share this manual.
+* Contributors:: People who have contributed to GnuPG.
+
+Indices
+
+* Option Index:: Index to command line options.
+* Index:: Index of concepts and symbol names.
+@end menu
+
+@include gpgsm.texi
+@include gpg-agent.texi
+@include scdaemon.texi
+
+@include assuan.texi
+
+@include gpl.texi
+@include fdl.texi
+
+@include contrib.texi
+
+@c ---------------------------------------------------------------------
+@c Indexes
+@c ---------------------------------------------------------------------
+
+@node Option Index
+@unnumbered Option Index
+
+@printindex op
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@c ---------------------------------------------------------------------
+@c Epilogue
+@c ---------------------------------------------------------------------
+
+@bye
+
+
diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi
new file mode 100644
index 000000000..61484485f
--- /dev/null
+++ b/doc/gpg-agent.texi
@@ -0,0 +1,739 @@
+@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file gnupg.texi.
+
+@node Invoking GPG-AGENT
+@chapter Invoking GPG-AGENT
+@cindex GPG-AGENT command options
+@cindex command options
+@cindex options, GPG-AGENT command
+
+@c man begin DESCRIPTION
+
+@sc{gpg-agent} is a daemon to manage secret (private) keys independelty
+from any protocol. It is used as a backend for @sc{gpg} and @sc{gpgsm}
+as well as for a couple of other utilities.
+
+@noindent
+The usual way to run the agent is from the @code{~/.xsession} file:
+
+@example
+eval `gpg-agent --daemon`
+@end example
+
+@noindent
+If you don't use an X server, you can also put this into your regular
+startup file @code{~/.profile} or @code{.bash_profile}. It is best not
+to run multiple instance of the gpg-agent, so you should make sure that
+only is running: @sc{gpg-agent} uses an environment variable to inform
+clients about the communication parameters. You can write the
+content of this environment variable to a file so that you can test for
+a running agent. This short script may do the job:
+
+@smallexample
+if test -f $HOME/.gpg-agent-info && \
+ kill -0 `cut -d: -f 2 $HOME/.gpg-agent-info` 2>/dev/null; then
+ GPG_AGENT_INFO=`cat $HOME/.gpg-agent-info`
+ export GPG_AGENT_INFO
+else
+ eval `gpg-agent --daemon`
+ echo $GPG_AGENT_INFO >$HOME/.gpg-agent-info
+fi
+@end smallexample
+
+@noindent
+If you want to use a curses based pinentry (which is usually also the
+fallback mode for a GUI based pinentry), you should add these lines to
+your @code{.bashrc} or whatever initialization file is used for all shell
+invocations:
+
+@smallexample
+GPG_TTY=`tty`
+export GPG_TTY
+@end smallexample
+
+It is important that this environment variable always reflects the
+output of the @code{tty} command.
+
+@c man end
+
+@noindent
+@xref{Option Index}, for an index to GPG-AGENTS's commands and options.
+
+@menu
+* Agent Commands:: List of all commands.
+* Agent Options:: List of all options.
+* Agent Signals:: Use of some signals.
+* Agent Examples:: Some usage examples.
+* Agent Protocol:: The protocol the agent uses.
+@end menu
+
+@c man begin COMMANDS
+
+@node Agent Commands
+@section Commands
+
+Commands are not distinguished from options execpt for the fact that
+only one one command is allowed.
+
+@table @gnupgtabopt
+@item --version
+@opindex version
+Print the program version and licensing information. Not that you can
+abbreviate this command.
+
+@item --help, -h
+@opindex help
+Print a usage message summarizing the most usefule command-line options.
+Not that you can abbreviate this command.
+
+@item --dump-options
+@opindex dump-options
+Print a list of all available options and commands. Not that you can
+abbreviate this command.
+
+@item --server
+@opindex server
+Run in server mode and wait for commands on the @code{stdin}. The
+default mode is to create a socket and listen for commands there.
+
+@item --daemon
+@opindex daemon
+Run the program in the background. This option is required to prevent
+it from being accidently running in the background. A common way to do
+this is:
+@example
+@end example
+$ eval `gpg-agent --daemon`
+@end table
+
+
+@c man begin OPTIONS
+
+@node Agent Options
+@section Option Summary
+
+@table @gnupgtabopt
+
+@item --options @var{file}
+@opindex options
+Reads configuration from @var{file} instead of from the default
+per-user configuration file.
+
+@item -v
+@item --verbose
+@opindex v
+@opindex verbose
+Outputs additional information while running.
+You can increase the verbosity by giving several
+verbose commands to @sc{gpgsm}, such as @samp{-vv}.
+
+@item -q
+@item --quiet
+@opindex q
+@opindex quiet
+Try to be as quiet as possible.
+
+@item --batch
+@opindex batch
+Don't invoke a pinentry or do any other thing requiring human interaction.
+
+@item --faked-system-time @var{epoch}
+@opindex faked-system-time
+This option is only useful for testing; it sets the system time back or
+forth to @var{epoch} which is the number of seconds elapsed since the year
+1970.
+
+@item --debug @var{flags}
+@opindex debug
+This option is only useful for debugging and the behaviour may change at
+any time without notice. FLAGS are bit encoded and may be given in
+usual C-Syntax. The currently defined bits are:
+ @table @code
+ @item 0 (1)
+ X.509 or OpenPGP protocol related data
+ @item 1 (2)
+ values of big number integers
+ @item 2 (4)
+ low level crypto operations
+ @item 5 (32)
+ memory allocation
+ @item 6 (64)
+ caching
+ @item 7 (128)
+ show memory statistics.
+ @item 9 (512)
+ write hashed data to files named @code{dbgmd-000*}
+ @item 10 (1024)
+ trace Assuan protocol
+ @item 12 (4096)
+ bypass all certificate validation
+ @end table
+
+@item --debug-all
+@opindex debug-all
+Same as @code{--debug=0xffffffff}
+
+@item --debug-wait @var{n}
+@opindex debug-wait
+When running in server mode, wait @var{n} seconds before entering the
+actual processing loop and print the pid. This gives time to attach a
+debugger.
+
+@item --no-detach
+@opindex no-detach
+Don't detach the process from the console. This is manly usefule for
+debugging.
+
+@item -s
+@itemx --sh
+@itemx -c
+@itemx --csh
+@opindex s
+@opindex sh
+@opindex c
+@opindex csh
+Format the info output in daemon mode for use with the standard Bourne
+shell respective the C-shell . The default ist to guess it based on the
+environment variable @code{SHELL} which is in almost all cases
+sufficient.
+
+@item --no-grab
+@opindex no-grab
+Tell the pinentryo not to grab the keyboard and mouse. This option
+should in general not be used to avaoid X-sniffing attacks.
+
+@item --log-file @var{file}
+@opindex log-file
+Append all logging output to @var{file}. This is very helpful in
+seeing what the agent actually does.
+
+@item --disable-pth
+@opindex disable-pth
+Don't allow multiple connections. This option is in general not very
+useful.
+
+@item --ignore-cache-for-signing
+@opindex ignore-cache-for-signing
+This option will let gpg-agent bypass the passphrase cache for all
+signing operation. Note that there is also a per-session option to
+control this behaviour but this command line option takes precedence.
+
+@item --default-cache-ttl @var{n}
+@opindex default-cache-ttl
+Set the time a cache entry is valid to @var{n} seconds. The default are
+600 seconds.
+
+@item --pinentry-program @var{path}
+@opindex pinentry-program
+Use program @var{path} as the PIN entry. The default is installation
+dependend and can be shown with the @code{--version} command.
+
+@item --scdaemon-program @var{path}
+@opindex scdaemon-program
+Use program @var{path} as the Smartcard daemon. The default is installation
+dependend and can be shown with the @code{--version} command.
+
+
+@item --display @var{string}
+@itemx --ttyname @var{string}
+@itemx --ttytype @var{string}
+@itemx --lc-type @var{string}
+@itemx --lc-messages @var{string}
+@opindex display
+@opindex ttyname
+@opindex ttytype
+@opindex lc-type
+@opindex lc-messa
+These options are used with the server mode to pass localization
+information.
+
+@item --keep-tty
+@itemx --keep-display
+@opindex keep-tty
+@opindex keep-display
+Ignore requests to change change the current @sc{tty} respective the X
+window system's @code{DISPLAY} variable. This is useful to lock the
+pinentry to pop up at the @sc{tty} or display you started the agent.
+
+
+@end table
+
+All the long options may also be given in the configuration file after
+stripping off the two leading dashes.
+
+@c
+@c Agent Signals
+@c
+@node Agent Signals
+@section Use of some signals.
+A running @command{gpg-agent} may be controlled by signals, i.e. using
+the @command{kill} command to send a signal to the process.
+
+Here is a list of supported signals:
+
+@table @gnupgtabopt
+
+@item SIGHUP
+@cpindex SIGHUP
+This signals flushes all chached passphrases and when the program was
+started with a configuration file, the configuration file is read again.
+Only certain options are honored: @code{quiet}, @code{verbose},
+@code{debug}, @code{debug-all}, @code{no-grab}, @code{pinentry-program},
+@code{default-cache-ttl} and @code{ignore-cache-for-signing}.
+@code{scdaemon-program} is also supported but due to the current
+implementation, which calls the scdaemon only once, it is not of much
+use.
+
+
+@item SIGUSR1
+@cpindex SIGUSR1
+This signal increases the verbosity of the logging by one up to a value
+of 5.
+
+@item SIGUSR2
+@cpindex SIGUSR2
+This signal decreases the verbosity of the logging by one.
+
+@item SIGTERM
+@cpindex SIGTERM
+Shuts down the process but waits until all current requests are
+fulfilled. If the process has received 3 of these signals and requests
+are still pending, a shutdown is forced.
+
+@item SIGINT
+@cpindex SIGINT
+Shuts down the process immediately.
+
+@end table
+
+@c
+@c Examples
+@c
+@node Agent Examples
+@section Examples
+
+@c man begin EXAMPLES
+
+@example
+$ eval `gpg-agent --daemon`
+@end example
+
+@c man end
+
+
+@c
+@c Assuan Protocol
+@c
+@node Agent Protocol
+@section Agent's Assuan Protocol
+
+The gpg-agent should be started by the login shell and set an
+environment variable to tell clients about the socket to be used.
+Clients should deny to access an agent with a socket name which does
+not match its own configuration. An application may choose to start
+an instance of the gpgagent if it does not figure that any has been
+started; it should not do this if a gpgagent is running but not
+usable. Because gpg-agent can only be used in background mode, no
+special command line option is required to activate the use of the
+protocol.
+
+To identify a key we use a thing called keygrip which is the SHA-1 hash
+of an canoncical encoded S-Expression of the the public key as used in
+Libgcrypt. For the purpose of this interface the keygrip is given as a
+hex string. The advantage of using this and not the hash of a
+certificate is that it will be possible to use the same keypair for
+different protocols, thereby saving space on the token used to keep the
+secret keys.
+
+@menu
+* Agent PKDECRYPT:: Decrypting a session key
+* Agent PKSIGN:: Signing a Hash
+* Agent GENKEY:: Generating a Key
+* Agent IMPORT:: Importing a Secret Key
+* Agent EXPORT:: Exporting a Secret Key
+* Agent ISTRUSTED:: Importing a Root Certificate
+* Agent GET_PASSPHRASE:: Ask for a passphrase
+* Agent HAVEKEY:: Check whether a key is available
+* Agent LEARN:: Register a smartcard
+* Agent PASSWD:: Change a Passphrase
+@end menu
+
+@node Agent PKDECRYPT
+@subsection Decrypting a session key
+
+The client asks the server to decrypt a session key. The encrypted
+session key should have all information needed to select the
+appropriate secret key or to delegate it to a smartcard.
+
+@example
+ SETKEY <keyGrip>
+@end example
+
+Tell the server about the key to be used for decryption. If this is
+not used, gpg-agent may try to figure out the key by trying to
+decrypt the message with each key available.
+
+@example
+ PKDECRYPT
+@end example
+
+The agent checks whether this command is allowed and then does an
+INQUIRY to get the ciphertext the client should then send the cipher
+text.
+
+@example
+ S: INQUIRE CIPHERTEXT
+ C: D (xxxxxx
+ C: D xxxx)
+ C: END
+@end example
+
+Please note that the server may send status info lines while reading the
+data lines from the client. The data send is a SPKI like S-Exp with
+this structure:
+
+@example
+ (enc-val
+ (<algo>
+ (<param_name1> <mpi>)
+ ...
+ (<param_namen> <mpi>)))
+@end example
+
+Where algo is a string with the name of the algorithm; see the libgcrypt
+documentation for a list of valid algorithms. The number and names of
+the parameters depend on the algorithm. The agent does return an error
+if there is an inconsistency.
+
+If the decryption was successful the decrypted data is returned by
+means of "D" lines.
+
+Here is an example session:
+
+@example
+ C: PKDECRYPT
+ S: INQUIRE CIPHERTEXT
+ C: D (enc-val elg (a 349324324)
+ C: D (b 3F444677CA)))
+ C: END
+ S: # session key follows
+ S: D 1234567890ABCDEF0
+ S: OK descryption successful
+@end example
+
+
+@node Agent PKSIGN
+@subsection Signing a Hash
+
+The client ask the agent to sign a given hash value. A default key
+will be chosen if no key has been set. To set a key a client first
+uses:
+
+@example
+ SIGKEY <keyGrip>
+@end example
+
+This can be used multiple times to create multiple signature, the list
+of keys is reset with the next PKSIGN command or a RESET. The server
+test whether the key is a valid key to sign something and responds with
+okay.
+
+@example
+ SETHASH <hexstring>
+@end example
+
+The client can use this command to tell the server about the data
+(which usually is a hash) to be signed.
+
+The actual signing is done using
+
+@example
+ PKSIGN <options>
+@end example
+
+Options are not yet defined, but my later be used to choosen among
+different algorithms (e.g. pkcs 1.5)
+
+The agent does then some checks, asks for the passphrase and
+if SETHASH has not been used asks the client for the data to sign:
+
+@example
+ S: INQUIRE HASHVAL
+ C: D ABCDEF012345678901234
+ C: END
+@end example
+
+As a result the server returns the signature as an SPKI like S-Exp
+in "D" lines:
+
+@example
+ (sig-val
+ (<algo>
+ (<param_name1> <mpi>)
+ ...
+ (<param_namen> <mpi>)))
+@end example
+
+
+The operation is affected by the option
+
+@example
+ OPTION use-cache-for-signing=0|1
+@end example
+
+The default of @code{1} uses the cache. Setting this option to @code{0}
+will lead gpg-agent to ignore the passphrase cache. Note, that there is
+also a global command line option for gpg-agent to globally disable the
+caching.
+
+
+Here is an example session:
+
+@example
+ C: SIGKEY <keyGrip>
+ S: OK key available
+ C: SIGKEY <keyGrip>
+ S: OK key available
+ C: PKSIGN
+ S: # I did ask the user whether he really wants to sign
+ S: # I did ask the user for the passphrase
+ S: INQUIRE HASHVAL
+ C: D ABCDEF012345678901234
+ C: END
+ S: # signature follows
+ S: D (sig-val rsa (s 45435453654612121212))
+ S: OK
+@end example
+
+
+@node Agent GENKEY
+@subsection Generating a Key
+
+This is used to create a new keypair and store the secret key inside the
+active PSE -w which is in most cases a Soft-PSE. An not yet defined
+option allows to choose the storage location. To get the secret key out
+of the PSE, a special export tool has to be used.
+
+@example
+ GENKEY
+@end example
+
+Invokes the key generation process and the server will then inquire
+on the generation parameters, like:
+
+@example
+ S: INQUIRE KEYPARM
+ C: D (genkey (rsa (nbits 1024)))
+ C: END
+@end example
+
+The format of the key parameters which depends on the algorithm is of
+the form:
+
+@example
+ (genkey
+ (algo
+ (parameter_name_1 ....)
+ ....
+ (parameter_name_n ....)))
+@end example
+
+If everything succeeds, the server returns the *public key* in a SPKI
+like S-Expression like this:
+
+@example
+ (public-key
+ (rsa
+ (n <mpi>)
+ (e <mpi>)))
+@end example
+
+Here is an example session:
+
+@example
+ C: GENKEY
+ S: INQUIRE KEYPARM
+ C: D (genkey (rsa (nbits 1024)))
+ C: END
+ S: D (public-key
+ S: D (rsa (n 326487324683264) (e 10001)))
+ S OK key created
+@end example
+
+@node Agent IMPORT
+@subsection Importing a Secret Key
+
+This operation is not yet supportted by GpgAgent. Specialized tools
+are to be used for this.
+
+There is no actual need because we can expect that secret keys
+created by a 3rd party are stored on a smartcard. If we have
+generated the key ourself, we do not need to import it.
+
+@node Agent EXPORT
+@subsection Export a Secret Key
+
+Not implemented.
+
+Should be done by an extra tool.
+
+@node Agent ISTRUSTED
+@subsection Importing a Root Certificate
+
+Actually we do not import a Root Cert but provide a way to validate
+any piece of data by storing its Hash along with a description and
+an identifier in the PSE. Here is the interface desription:
+
+@example
+ ISTRUSTED <fingerprint>
+@end example
+
+Check whether the OpenPGP primary key or the X.509 certificate with the
+given fingerprint is an ultimately trusted key or a trusted Root CA
+certificate. The fingerprint should be given as a hexstring (without
+any blanks or colons or whatever in between) and may be left padded with
+00 in case of an MD5 fingerprint. GPGAgent will answer with:
+
+@example
+ OK
+@end example
+
+The key is in the table of trusted keys.
+
+@example
+ ERR 304 (Not Trusted)
+@end example
+
+The key is not in this table.
+
+Gpg needs the entire list of trusted keys to maintain the web of
+trust; the following command is therefore quite helpful:
+
+@example
+ LISTTRUSTED
+@end example
+
+GpgAgent returns a list of trusted keys line by line:
+
+@example
+ S: D 000000001234454556565656677878AF2F1ECCFF P
+ S: D 340387563485634856435645634856438576457A P
+ S: D FEDC6532453745367FD83474357495743757435D S
+ S: OK
+@end example
+
+The first item on a line is the hexified fingerprint where MD5
+ingerprints are @code{00} padded to the left and the second item is a
+flag to indicate the type of key (so that gpg is able to only take care
+of PGP keys). P = OpenPGP, S = S/MIME. A client should ignore the rest
+of the line, so that we can extend the format in the future.
+
+Finally a client should be able to mark a key as trusted:
+
+@example
+ MARKTRUSTED @var{fingerprint} "P"|"S"
+@end example
+
+The server will then pop up a window to ask the user whether she
+really trusts this key. For this it will probably ask for a text to
+be displayed like this:
+
+@example
+ S: INQUIRE TRUSTDESC
+ C: D Do you trust the key with the fingerprint @@FPR@@
+ C: D bla fasel blurb.
+ C: END
+ S: OK
+@end example
+
+Known sequences with the pattern @@foo@@ are replaced according to this
+table:
+
+@table @code
+@item @@FPR16@@
+Format the fingerprint according to gpg rules for a v3 keys.
+@item @@FPR20@@
+Format the fingerprint according to gpg rules for a v4 keys.
+@item @@FPR@@
+Choose an appropriate format to format the fingerprint.
+@item @@@@
+Replaced by a single @code{@@}
+@end table
+
+@node Agent GET_PASSPHRASE
+@subsection Ask for a passphrase
+
+This function is usually used to ask for a passphrase to be used for
+conventional encryption, but may also be used by programs which need
+special handling of passphrases. This command uses a syntax which helps
+clients to use the agent with minimum effort.
+
+@example
+ GET_PASSPHRASE @var{cache_id} [@var{error_message} @var{prompt} @var{description}]
+@end example
+
+@var{cache_id} is expected to be a hex string used for caching a
+passphrase. Use a @code{X} to bypass the cache. With no other
+arguments the agent returns a cached passphrase or an error.
+
+@var{error_message} is either a single @code{X} for no error message or
+a string to be shown as an error message like (e.g. "invalid
+passphrase"). Blanks must be percent escaped or replaced by @code{+}'.
+
+@var{prompt} is either a single @code{X} for a default prompt or the
+text to be shown as the prompt. Blanks must be percent escaped or
+replaced by @code{+}.
+
+@var{description} is a text shown above the entry field. Blanks must be
+percent escaped or replaced by @code{+}.
+
+The agent either returns with an error or with a OK followed by the
+hex encoded passphrase. Note that the length of the strings is
+implicitly limited by the maximum length of a command.
+
+@example
+ CLEAR_PASSPHRASE @var{cache_id}
+@end example
+
+may be used to invalidate the cache entry for a passphrase. The
+function returns with OK even when there is no cached passphrase.
+
+
+@node Agent HAVEKEY
+@subsection Check whether a key is available
+
+This can be used to see whether a secret key is available. It does
+not return any information on whether the key is somehow protected.
+
+@example
+ HAVEKEY @var{keygrip}
+@end example
+
+The Agent answers either with OK or @code{No_Secret_Key} (208). The
+caller may want to check for other error codes as well.
+
+
+@node Agent LEARN
+@subsection Register a smartcard
+
+@example
+ LEARN [--send]
+@end example
+
+This command is used to register a smartcard. With the --send
+option given the certificates are send back.
+
+
+@node Agent PASSWD
+@subsection Change a Passphrase
+
+@example
+ PASSWD @var{keygrip}
+@end example
+
+This command is used to interactively change the passphrase of the key
+indentified by the hex string @var{keygrip}.
+
+
+
diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi
new file mode 100644
index 000000000..4d91bda5b
--- /dev/null
+++ b/doc/gpgsm.texi
@@ -0,0 +1,738 @@
+@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file gnupg.texi.
+
+@node Invoking GPGSM
+@chapter Invoking GPGSM
+@cindex GPGSM command options
+@cindex command options
+@cindex options, GPGSM command
+
+@c man begin DESCRIPTION
+
+@sc{gpgsm} is a tool similar to @sc{gpg} to provide digital encryption
+and signing servicesd on X.509 certificates and the CMS protocoll. It
+is mainly used as a backend for S/MIME mail processing. @sc{gpgsm}
+includes a full features certificate management and complies with all
+rules defined for the German Sphinx project.
+
+@c man end
+
+@xref{Option Index}, for an index to GPGSM's commands and options.
+
+@menu
+* GPGSM Commands:: List of all commands.
+* GPGSM Options:: List of all options.
+* GPGSM Examples:: Some usage examples.
+
+Developer information:
+* Unattended Usage:: Using @sc{gpgsm} from other programs.
+* GPGSM Protocol:: The protocol the server mode uses.
+@end menu
+
+@c man begin COMMANDS
+
+@node GPGSM Commands
+@section Commands
+
+Commands are not distinguished from options execpt for the fact that
+only one one command is allowed.
+
+@menu
+* General Commands:: Commands not specific to the functionality.
+* Operational Commands:: Commands to select the type of operation.
+* Certificate Management:: How to manage certificates.
+@end menu
+
+@node General Commands
+@subsection Commands not specific to the function
+
+@table @gnupgtabopt
+@item --version
+@opindex version
+Print the program version and licensing information. Not that you can
+abbreviate this command.
+
+@item --help, -h
+@opindex help
+Print a usage message summarizing the most usefule command-line options.
+Not that you can abbreviate this command.
+
+@item --dump-options
+@opindex dump-options
+Print a list of all available options and commands. Not that you can
+abbreviate this command.
+@end table
+
+
+
+@node Operational Commands
+@subsection Commands to select the type of operation
+
+@table @gnupgtabopt
+@item --encrypt
+@opindex encrypt
+Perform an encryption.
+
+@item --decrypt
+@opindex decrypt
+Perform a decryption; the type of input is automatically detmerined. It
+may either be in binary form or PEM encoded; automatic determination of
+base-64 encoding is not done.
+
+@item --sign
+@opindex sign
+Create a digital signature. The key used is either the fist one found
+in the keybox or thise set with the -u option
+
+@item --verify
+@opindex verify
+Check a signature file for validity. Depending on the arguments a
+detached signatrue may also be checked.
+
+@item --server
+@opindex server
+Run in server mode and wait for commands on the @code{stdin}.
+
+@item --call-dirmngr @var{command} [@var{args}]
+@opindex call-dirmngr
+Behave as a Dirmngr client issuing the request @var{command} with the
+optional list of @var{args}. The output of the Dirmngr is printed
+stdout. Please note that filenames given as arguments should have an
+absulte path because they are passed verbatim to the Dirmngr and the
+working directory of the Dirmngr might not be the same as the one of
+this client. Currently it is not possible to pass data via stdin to the
+Dirmngr. @var{command} should not contain spaces.
+
+This is command is required for certain maintaining tasks of the dirmngr
+where a dirmngr must be able to call back to gpgsm. See the Dirmngr
+manual for details.
+
+@item --call-protect-tool @var{arguments}
+@opindex call-protect-tool
+Certain maintenance operations are done by an external program call
+@command{gpg-protect-tool}; this is usually not installed in a directory
+listed in the PATH variable. This command provides a simple wrapper to
+access this tool. @var{arguments} are passed verbatim to this command;
+use @samp{--help} to get a list of supported operations.
+
+
+@end table
+
+
+@node Certificate Management
+@subsection How to manage the certificate and keys
+
+@table @gnupgtabopt
+@item --gen-key
+@opindex gen-key
+Generate a new key and a certificate request.
+
+@item --list-keys
+@opindex list-keys
+List all available certificates stored in the local key database.
+
+@item --list-secret-keys
+@opindex list-secret-keys
+List all available keys whenre a secret key is available.
+
+@item --list-external-keys @var{pattern}
+@opindex list-keys
+List certificates matching @var{pattern} using an external server. This
+utilies the @code{dirmngr} service.
+
+@item --delete-keys @var{pattern}
+@opindex delete-keys
+Delete the keys matching @var{pattern}.
+
+@item --export [@var{pattern}]
+@opindex export
+Export all certificates stored in the Keybox or those specified by the
+optional @var{pattern}. When using along with the @code{--armor} option
+a few informational lines are prepended before each block.
+
+@item --learn-card
+@opindex learn-card
+Read information about the private keys from the smartcard and import
+the certificates from there. This command utilizes the @sc{gpg-agent}
+and in turn the @sc{scdaemon}.
+
+@item --passwd @var{user_id}
+@opindex passwd
+Change the passphrase of the private key belonging to the certificate
+specified as @var{user_id}. Note, that changing the passphrase/PIN of a
+smartcard is not yet supported.
+
+@end table
+
+
+@node GPGSM Options
+@section Option Summary
+
+GPGSM comes features a bunch ofoptions to control the exact behaviour
+and to change the default configuration.
+
+@menu
+* Configuration Options:: How to change the configuration.
+* Certificate Options:: Certificate related options.
+* Input and Output:: Input and Output.
+* CMS Options:: How to change how the CMS is created.
+* Esoteric Options:: Doing things one usually don't want to do.
+@end menu
+
+@c man begin OPTIONS
+
+@node Configuration Options
+@subsection How to change the configuration
+
+These options are used to change the configuraton and are usually found
+in the option file.
+
+@table @gnupgtabopt
+
+@item --options @var{file}
+@opindex options
+Reads configuration from @var{file} instead of from the default
+per-user configuration file.
+
+@item -v
+@item --verbose
+@opindex v
+@opindex verbose
+Outputs additional information while running.
+You can increase the verbosity by giving several
+verbose commands to @sc{gpgsm}, such as @samp{-vv}.
+
+@item --policy-file @var{filename}
+@opindex policy-file
+Change the default name of the policy file to @var{filename}.
+
+@item --agent-program @var{file}
+@opindex agent-program
+Specify an agent program to be used for secret key operations. The
+default value is the @file{/usr/local/bin/gpg-agent}. This is only used
+as a fallback when the envrionment variable @code{GPG_AGENT_INFO} is not
+set or a running agent can't be connected.
+
+@item --dirmngr-program @var{file}
+@opindex dirmnr-program
+Specify a dirmngr program to be used for @acronym{CRL} checks. The
+default value is @file{/usr/sbin/dirmngr}. This is only used as a
+fallback when the environment variable @code{DIRMNGR_INFO} is not set or
+a running dirmngr can't be connected.
+
+@item --no-secmem-warning
+@opindex no-secmem-warning
+Don't print a warning when the so called "secure memory" can't be used.
+
+
+
+@end table
+
+
+@node Certificate Options
+@subsection Certificate related options
+
+@table @gnupgtabopt
+
+@item --enable-policy-checks
+@itemx --disable-policy-checks
+@opindex enable-policy-checks
+@opindex disable-policy-checks
+By default policy checks are enabled. These options may be used to
+change it.
+
+@item --enable-crl-checks
+@itemx --disable-crl-checks
+@opindex enable-crl-checks
+@opindex disable-crl-checks
+By default the @acronym{CRL} checks are enabled and the DirMngr is used
+to check for revoked certificates. The disable option is most useful
+with an off-line network connection to suppress this check.
+
+@end table
+
+@node Input and Output
+@subsection Input and Output
+
+@table @gnupgtabopt
+@item --armor
+@itemx -a
+@opindex armor
+@opindex -a
+Create PEM encoded output. Default is binary output.
+
+@item --base64
+@opindex base64
+Create Base-64 encoded output; i.e. PEM without the header lines.
+
+@item --assume-armor
+@opindex assume-armor
+Assume the input data is PEM encoded. Default is to autodetect the
+encoding but this is may fail.
+
+@item --assume-base64
+@opindex assume-base64
+Assume the input data is plain base-64 encoded.
+
+@item --assume-binary
+@opindex assume-binary
+Assume the input data is binary encoded.
+
+@item --local-user @var{user_id}
+@item -u @var{user_id}
+@opindex local-user
+@opindex -u
+Set the user(s) to be used for signing. The default is the first
+secret key found in the database.
+
+@item --with-key-data
+@opindex with-key-data
+Displays extra information with the @code{--list-keys} commands. Especially
+a line tagged @code{grp} is printed which tells you the keygrip of a
+key. This string is for example used as the filename of the
+secret key.
+
+@end table
+
+@node CMS Options
+@subsection How to change how the CMS is created.
+
+@table @gnupgtabopt
+@item --include-certs @var{n}
+Using @var{n} of -2 includes all certificate except for the root cert,
+-1 includes all certs, 0 does not include any certs, 1 includes only
+the signers cert (this is the default) and all other positive
+values include up to @var{n} certificates starting with the signer cert.
+
+@end table
+
+
+
+@node Esoteric Options
+@subsection Doing things one usually don't want todo.
+
+
+@table @gnupgtabopt
+
+@item --faked-system-time @var{epoch}
+@opindex faked-system-time
+This option is only useful for testing; it sets the system time back or
+forth to @var{epoch} which is the number of seconds elapsed since the year
+1970.
+
+@item --debug @var{flags}
+@opindex debug
+This option is only useful for debugging and the behaviour may change at
+any time without notice. FLAGS are bit encoded and may be given in
+usual C-Syntax. The currently defined bits are:
+ @table @code
+ @item 0 (1)
+ X.509 or OpenPGP protocol related data
+ @item 1 (2)
+ values of big number integers
+ @item 2 (4)
+ low level crypto operations
+ @item 5 (32)
+ memory allocation
+ @item 6 (64)
+ caching
+ @item 7 (128)
+ show memory statistics.
+ @item 9 (512)
+ write hashed data to files named @code{dbgmd-000*}
+ @item 10 (1024)
+ trace Assuan protocol
+ @item 12 (4096)
+ bypass all certificate validation
+ @end table
+
+@item --debug-all
+@opindex debug-all
+Same as @code{--debug=0xffffffff}
+
+@item --debug-no-path-validation
+@opindex debug-no-path-validation
+This is actually not a debugging option but only useful as such. It
+lets gpgsm bypass all certificate path validation checks.
+
+@end table
+
+All the long options may also be given in the configuration file after
+stripping off the two leading dashes.
+
+
+
+@c
+@c Examples
+@c
+@node GPGSM Examples
+@section Examples
+
+@c man begin EXAMPLES
+
+@example
+$ gpgsm -er goo@@bar.net <plaintext >ciphertext
+@end example
+
+@c man end
+
+
+
+@c ---------------------------------
+@c The machine interface
+@c --------------------------------
+@node Unattended Usage
+@section Unattended Usage
+
+@sc{gpgsm} is often used as a backend engine by other software. To help
+with this a machine interface has been defined to have an unambiguous
+way to do this. This is most likely used with the @code{--server} command
+but may also be used in the standard operation mode by using the
+@code{--status-fd} option.
+
+@menu
+* Automated signature checking:: Automated signature checking.
+@end menu
+
+@node Automated signature checking,,,Unattended Usage
+@section Automated signature checking
+
+It is very important to understand the semantics used with signature
+verification. Checking a signature is not as simple as it may sound and
+so the ooperation si a bit complicated. In mosted cases it is required
+to look at several status lines. Here is a table of all cases a signed
+message may have:
+
+@table @asis
+@item The signature is valid
+This does mean that the signature has been successfully verified, the
+certificates are all sane. However there are two subcases with
+important information: One of the certificates may have expired or a
+signature of a message itself as expired. It is a sound practise to
+consider such a signature still as valid but additional information
+should be displayed. Depending on the subcase @sc{gpgsm} will issue
+these status codes:
+ @table @asis
+ @item signature valid and nothing did expire
+ @code{GOODSIG}, @code{VALIDSIG}, @code{TRUST_FULLY}
+ @item signature valid but at least one certificate has expired
+ @code{EXPKEYSIG}, @code{VALIDSIG}, @code{TRUST_FULLY}
+ @item signature valid but expired
+ @code{EXPSIG}, @code{VALIDSIG}, @code{TRUST_FULLY}
+ Note, that this case is currently not implemented.
+ @end table
+
+@item The signature is invalid
+This means that the signature verification failed (this is an indication
+of af a transfer error, a programm error or tampering with the message).
+@sc{gpgsm} issues one of these status codes sequences:
+ @table @code
+ @item @code{BADSIG}
+ @item @code{GOODSIG}, @code{VALIDSIG} @code{TRUST_NEVER}
+ @end table
+
+@item Error verifying a signature
+For some reason the signature could not be verified, i.e. it can't be
+decided whether the signature is valid or invalid. A common reason for
+this is a missing certificate.
+
+@end table
+
+
+@c
+@c Assuan Protocol
+@c
+@node GPGSM Protocol
+@section The Protocol the Server Mode Uses.
+
+Description of the protocol used to access GPGSM. GPGSM does implement
+the Assuan protocol and in addition provides a regular command line
+interface which exhibits a full client to this protocol (but uses
+internal linking). To start gpgsm as a server the commandline "gpgsm
+--server" must be used. Additional options are provided to select the
+communication method (i.e. the name of the socket).
+
+We assume that the connection has already been established; see the
+Assuan manual for details.
+
+@menu
+* GPGSM ENCRYPT:: Encrypting a message.
+* GPGSM DECRYPT:: Decrypting a message.
+* GPGSM SIGN:: Signing a message.
+* GPGSM VERIFY:: Verifying a message.
+* GPGSM GENKEY:: Generating a key.
+* GPGSM LISTKEYS:: List available keys.
+* GPGSM EXPORT:: Export certificates.
+* GPGSM IMPORT:: Import certificates.
+* GPGSM DELETE:: Delete certificates.
+@end menu
+
+
+@node GPGSM ENCRYPT
+@subsection Encrypting a Message
+
+Before encrytion can be done the recipient must be set using the
+command:
+
+@example
+ RECIPIENT @var{userID}
+@end example
+
+Set the recipient for the encryption. @var{userID} should be the
+internal representation of the key; the server may accept any other way
+of specification. If this is a valid and trusted recipient the server
+does respond with OK, otherwise the return is an ERR with the reason why
+the recipient can't be used, the encryption will then not be done for
+this recipient. If the policy is not to encrypt at all if not all
+recipients are valid, the client has to take care of this. All
+@code{RECIPIENT} commands are cumulative until a @code{RESET} or an
+successful @code{ENCRYPT} command.
+
+@example
+ INPUT FD=@var{n} [--armor|--base64|--binary]
+@end example
+
+Set the file descriptor for the message to be encrypted to @var{n}.
+Obviously the pipe must be open at that point, the server establishes
+its own end. If the server returns an error the client should consider
+this session failed.
+
+The @code{--armor} option may be used to advice the server that the
+input data is in @acronym{PEM} format, @code{--base64} advices that a
+raw base-64 encoding is used, @code{--binary} advices of raw binary
+input (@acronym{BER}). If none of these options is used, the server
+tries to figure out the used encoding, but this may not always be
+correct.
+
+@example
+ OUTPUT FD=@var{n} [--armor|--base64]
+@end example
+
+Set the file descriptor to be used for the output (i.e. the encrypted
+message). Obviously the pipe must be open at that point, the server
+establishes its own end. If the server returns an error he client
+should consider this session failed.
+
+The option armor encodes the output in @acronym{PEM} format, the
+@code{--base64} option applies just a base 64 encoding. No option
+creates binary output (@acronym{BER}).
+
+The actual encryption is done using the command
+
+@example
+ ENCRYPT
+@end example
+
+It takes the plaintext from the @code{INPUT} command, writes to the
+ciphertext to the file descriptor set with the @code{OUTPUT} command,
+take the recipients from all the recipients set so far. If this command
+fails the clients should try to delete all output currently done or
+otherwise mark it as invalid. GPGSM does ensure that there won't be any
+security problem with leftover data on the output in this case.
+
+This command should in general not fail, as all necessary checks have
+been done while setting the recipients. The input and output pipes are
+closed.
+
+
+@node GPGSM DECRYPT
+@subsection Decrypting a message
+
+Input and output FDs are set the same way as in encryption, but
+@code{INPUT} refers to the ciphertext and output to the plaintext. There
+is no need to set recipients. GPGSM automatically strips any
+@acronym{S/MIME} headers from the input, so it is valid to pass an
+entire MIME part to the INPUT pipe.
+
+The encryption is done by using the command
+
+@example
+ DECRYPT
+@end example
+
+It performs the decrypt operation after doing some check on the internal
+state. (e.g. that all needed data has been set). Because it utilizes
+the GPG-Agent for the session key decryption, there is no need to ask
+the client for a protecting passphrase - GpgAgent takes care of this by
+requesting this from the user.
+
+
+@node GPGSM SIGN
+@subsection Signing a Message
+
+Signing is usually done with these commands:
+
+@example
+ INPUT FD=@var{n} [--armor|--base64|--binary]
+@end example
+
+This tells GPGSM to read the data to sign from file descriptor @var{n}.
+
+@example
+ OUTPUT FD=@var{m} [--armor|--base64]
+@end example
+
+Write the output to file descriptor @var{m}. If a detached signature is
+requested, only the signature is written.
+
+@example
+ SIGN [--detached]
+@end example
+
+Sign the data set with the INPUT command and write it to the sink set by
+OUTPUT. With @code{--detached}, a detached signature is created
+(surprise).
+
+The key used for signining is the default one or the one specified in
+the configuration file. To get finer control over the keys, it is
+possible to use the command
+
+@example
+ SIGNER @var{userID}
+@end example
+
+to the signer's key. @var{userID} should be the
+internal representation of the key; the server may accept any other way
+of specification. If this is a valid and trusted recipient the server
+does respond with OK, otherwise the return is an ERR with the reason why
+the key can't be used, the signature will then not be created using
+this key. If the policy is not to sign at all if not all
+keys are valid, the client has to take care of this. All
+@code{SIGNER} commands are cumulative until a @code{RESET} is done.
+Note that a @code{SIGN} does not reset this list of signers which is in
+contrats to the @code{RECIPIENT} command.
+
+
+@node GPGSM VERIFY
+@subsection Verifying a Message
+
+To verify a mesage the command:
+
+@example
+ VERIFY
+@end example
+
+is used. It does a verify operation on the message send to the input FD.
+The result is written out using status lines. If an output FD was
+given, the signed text will be written to that. If the signature is a
+detached one, the server will inquire about the signed material and the
+client must provide it.
+
+@node GPGSM GENKEY
+@subsection Generating a Key
+
+This is used to generate a new keypair, store the secret part in the
+@acronym{PSE} and the public key in the key database. We will probably
+add optional commands to allow the client to select whether a hardware
+token is used to store the key. Configuration options to GPGSM can be
+used to restrict the use of this command.
+
+@example
+ GENKEY
+@end example
+
+GPGSM checks whether this command is allowed and then does an
+INQUIRY to get the key parameters, the client should then send the
+key parameters in the native format:
+
+@example
+ S: INQUIRE KEY_PARAM native
+ C: D foo:fgfgfg
+ C: D bar
+ C: END
+@end example
+
+Please note that the server may send Status info lines while reading the
+data lines from the client. After this the key generation takes place
+and the server eventually does send an ERR or OK response. Status lines
+may be issued as a progress indicator.
+
+
+@node GPGSM LISTKEYS
+@subsection List available keys
+
+To list the keys in the internal database or using an external key
+provider, the command:
+
+@example
+ LISTKEYS @var{pattern}
+@end example
+
+is used. To allow multiple patterns (which are ORed during the search)
+quoting is required: Spaces are to be translated into "+" or into "%20";
+in turn this requires that the usual escape quoting rules are done.
+
+@example
+ LISTSECRETKEYS @var{pattern}
+@end example
+
+Lists only the keys where a secret key is available.
+
+The list commands commands are affected by the option
+
+@example
+ OPTION list-mode=@var{mode}
+@end example
+
+where mode may be:
+@table @code
+@item 0
+Use default (which is usually the same as 1).
+@item 1
+List only the internal keys.
+@item 2
+List only the external keys.
+@item 3
+List internal and external keys.
+@end table
+
+Note that options are valid for the entire session.
+
+
+@node GPGSM EXPORT
+@subsection Export certificates
+
+To export certificate from the internal key database the command:
+
+@example
+ EXPORT @var{pattern}
+@end example
+
+is used. To allow multiple patterns (which are ORed) quoting is
+required: Spaces are to be translated into "+" or into "%20"; in turn
+this requires that the usual escape quoting rules are done.
+
+The format of the output depends on what was set with the OUTPUT
+command. When using @acronym{PEM} encoding a few informational lines
+are prepended.
+
+
+@node GPGSM IMPORT
+@subsection Import certificates
+
+To import certificates into the internal key database, the command
+
+@example
+ IMPORT
+@end example
+
+is used. The data is expected on the file descriptor set with the
+@code{INPUT} command. Certain checks are performend on the certificate.
+
+@node GPGSM DELETE
+@subsection Delete certificates
+
+To delete certificate the command
+
+@example
+ DELKEYS @var{pattern}
+@end example
+
+is used. To allow multiple patterns (which are ORed) quoting is
+required: Spaces are to be translated into "+" or into "%20"; in turn
+this requires that the usual escape quoting rules are done.
+
+The certificates must be specified unambiguously otherwise an error is
+returned.
+
diff --git a/doc/gpl.texi b/doc/gpl.texi
new file mode 100644
index 000000000..ca0508fad
--- /dev/null
+++ b/doc/gpl.texi
@@ -0,0 +1,397 @@
+@node Copying
+@appendix GNU GENERAL PUBLIC LICENSE
+
+@cindex GPL, GNU General Public License
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
+59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@appendixsubsec Preamble
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software---to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+ We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+@iftex
+@appendixsubsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate
+@item
+This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The ``Program'', below,
+refers to any such program or work, and a ``work based on the Program''
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term ``modification''.) Each licensee is addressed as ``you''.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+@item
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+@item
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+@enumerate a
+@item
+You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+@item
+If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License. (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+@end enumerate
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+@item
+You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+@enumerate a
+@item
+Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+@item
+Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+@item
+Accompany it with the information you received as to the offer
+to distribute corresponding source code. (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+@end enumerate
+
+The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+@item
+You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+@item
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and ``any
+later version'', you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+@item
+If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
+
+@item
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+@end enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+@page
+@unnumberedsec How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the ``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the program's name and an idea of what it does.}
+Copyright (C) 19@var{yy} @var{name of author}
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+type `show w'. This is free software, and you are welcome
+to redistribute it under certain conditions; type `show c'
+for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than @samp{show w} and
+@samp{show c}; they could even be mouse-clicks or menu items---whatever
+suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the program, if
+necessary. Here is a sample; alter the names:
+
+@smallexample
+@group
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written
+by James Hacker.
+
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end group
+@end smallexample
+
+This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Library General
+Public License instead of this License.
diff --git a/doc/scdaemon.texi b/doc/scdaemon.texi
new file mode 100644
index 000000000..55f9f8a0f
--- /dev/null
+++ b/doc/scdaemon.texi
@@ -0,0 +1,297 @@
+@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file gnupg.texi.
+
+@node Invoking SCDAEMON
+@chapter Invoking the SCDAEMON
+@cindex SCDAEMON command options
+@cindex command options
+@cindex options, SCDAEMON command
+
+@c man begin DESCRIPTION
+
+The @sc{scdaeon} is a daemon to manage smartcards. It is usually
+invoked by gpg-agent and in general not used directly.
+
+@c man end
+
+@xref{Option Index}, for an index to GPG-AGENTS's commands and options.
+
+@menu
+* Scdaemon Commands:: List of all commands.
+* Scdaemon Options:: List of all options.
+* Scdaemon Examples:: Some usage examples.
+* Scdaemon Protocol:: The protocol the daemon uses.
+@end menu
+
+@c man begin COMMANDS
+
+@node Scdaemon Commands
+@section Commands
+
+Commands are not distinguished from options execpt for the fact that
+only one one command is allowed.
+
+@table @gnupgtabopt
+@item --version
+@opindex version
+Print the program version and licensing information. Not that you can
+abbreviate this command.
+
+@item --help, -h
+@opindex help
+Print a usage message summarizing the most usefule command-line options.
+Not that you can abbreviate this command.
+
+@item --dump-options
+@opindex dump-options
+Print a list of all available options and commands. Not that you can
+abbreviate this command.
+
+@item --server
+@opindex server
+Run in server mode and wait for commands on the @code{stdin}. This is
+default mode is to create a socket and listen for commands there.
+
+@item --daemon
+@opindex daemon
+Run the program in the background. This option is required to prevent
+it from being accidently running in the background.
+
+@end table
+
+
+@c man begin OPTIONS
+
+@node Scdaemon Options
+@section Option Summary
+
+@table @gnupgtabopt
+
+@item --options @var{file}
+@opindex options
+Reads configuration from @var{file} instead of from the default
+per-user configuration file.
+
+@item -v
+@item --verbose
+@opindex v
+@opindex verbose
+Outputs additional information while running.
+You can increase the verbosity by giving several
+verbose commands to @sc{gpgsm}, such as @samp{-vv}.
+
+@item --debug @var{flags}
+@opindex debug
+This option is only useful for debugging and the behaviour may change at
+any time without notice. FLAGS are bit encoded and may be given in
+usual C-Syntax. The currently defined bits are:
+ @table @code
+ @item 0 (1)
+ X.509 or OpenPGP protocol related data
+ @item 1 (2)
+ values of big number integers
+ @item 2 (4)
+ low level crypto operations
+ @item 5 (32)
+ memory allocation
+ @item 6 (64)
+ caching
+ @item 7 (128)
+ show memory statistics.
+ @item 9 (512)
+ write hashed data to files named @code{dbgmd-000*}
+ @item 10 (1024)
+ trace Assuan protocol
+ @item 12 (4096)
+ bypass all certificate validation
+ @end table
+
+@item --debug-all
+@opindex debug-all
+Same as @code{--debug=0xffffffff}
+
+@item --debug-wait @var{n}
+@opindex debug-wait
+When running in server mode, wait @var{n} seconds before entering the
+actual processing loop and print the pid. This gives time to attach a
+debugger.
+
+@item --debug-sc @var{n}
+@opindex debug-sc
+Set the debug level of the OpenSC library to @var{n}.
+
+@item --no-detach
+@opindex no-detach
+Don't detach the process from the console. This is manly usefule for
+debugging.
+
+@item --log-file @var{file}
+@opindex log-file
+Append all logging output to @var{file}. This is very helpful in
+seeing what the agent actually does.
+
+
+@end table
+
+All the long options may also be given in the configuration file after
+stripping off the two leading dashes.
+
+
+@c
+@c Examples
+@c
+@node Scdaemon Examples
+@section Examples
+
+@c man begin EXAMPLES
+
+@example
+$ scdaemon --server -v
+@end example
+
+@c man end
+
+@c
+@c Assuan Protocol
+@c
+@node Scdaemon Protocol
+@section Scdaemon's Assuan Protocol
+
+The SC-Daemon should be started by the system to provide access to
+external tokens. Using Smartcards on a multi-user system does not
+make much sense expcet for system services, but in this case no
+regular user accounts are hosted on the machine.
+
+A client connects to the SC-Daemon by connecting to the socket named
+@file{/var/run/scdaemon/socket}, configuration information is read from
+@var{/etc/scdaemon.conf}
+
+Each connection acts as one session, SC-Daemon takes care of
+syncronizing access to a token between sessions.
+
+@menu
+* Scdaemon SERIALNO:: Return the serial number.
+* Scdaemon LEARN:: Read all useful information from the card.
+* Scdaemon READCERT:: Return a certificate.
+* Scdaemon READKEY:: Return a public key.
+* Scdaemon PKSIGN:: Signing data with a Smartcard.
+* Scdaemon PKDECRYPT:: Decrypting data with a Smartcard.
+@end menu
+
+@node Scdaemon SERIALNO
+@subsection Return the serial number
+
+This command should be used to check for the presence of a card. It is
+special in that it can be used to reset the card. Most other commands
+will return an error when a card change has been detected and the use of
+this function is therefore required.
+
+Background: We want to keep the client clear of handling card changes
+between operations; i.e. the client can assume that all operations are
+done on the same card unless he call this function.
+
+@example
+ SERIALNO
+@end example
+
+Return the serial number of the card using a status reponse like:
+
+@example
+ S SERIALNO D27600000000000000000000 0
+@end example
+
+The trailing 0 should be ignored for now, it is reserved for a future
+extension. The serial number is the hex encoded value identified by
+the @code{0x5A} tag in the GDO file (FIX=0x2F02).
+
+
+
+@node Scdaemon LEARN
+@subsection Read all useful information from the card
+
+@example
+ LEARN [--force]
+@end example
+
+Learn all useful information of the currently inserted card. When
+used without the force options, the command might do an INQUIRE
+like this:
+
+@example
+ INQUIRE KNOWNCARDP <hexstring_with_serialNumber> <timestamp>
+@end example
+
+The client should just send an @code{END} if the processing should go on
+or a @code{CANCEL} to force the function to terminate with a cancel
+error message. The response of this command is a list of status lines
+formatted as this:
+
+@example
+ S KEYPAIRINFO @var{hexstring_with_keygrip} @var{hexstring_with_id}
+@end example
+
+If there is no certificate yet stored on the card a single "X" is
+returned in @var{hexstring_with_keygrip}.
+
+@node Scdaemon READCERT
+@subsection Return a certificate
+
+@example
+ READCERT @var{hexified_certid}
+@end example
+
+This function is used to read a certificate identified by
+@var{hexified_certid} from the card.
+
+
+@node Scdaemon READKEY
+@subsection Return a public key
+
+@example
+READKEY @var{hexified_certid}
+@end example
+
+Return the public key for the given cert or key ID as an standard
+S-Expression.
+
+
+
+@node Scdaemon PKSIGN
+@subsection Signing data with a Smartcard
+
+To sign some data the caller should use the command
+
+@example
+ SETDATA @var{hexstring}
+@end example
+
+to tell scdaemon about the data to be signed. The data must be given in
+hex notation. The actual signing is done using the command
+
+@example
+ PKSIGN @var{keyid}
+@end example
+
+where @var{keyid} is the hexified ID of the key to be used. The key id
+may have been retrieved using the command @code{LEARN}.
+
+
+@node Scdaemon PKDECRYPT
+@subsection Decrypting data with a Smartcard
+
+To decrypt some data the caller should use the command
+
+@example
+ SETDATA @var{hexstring}
+@end example
+
+to tell scdaemon about the data to be decrypted. The data must be given in
+hex notation. The actual decryption is then done using the command
+
+@example
+ PKDECRYPT @var{keyid}
+@end example
+
+where @var{keyid} is the hexified ID of the key to be used.
+