See ChangeLog: Mon Sep 6 19:59:08 CEST 1999 Werner Koch

15 files changed, 3591 insertions, 116 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index c5bdf3c98..ae5cdb506 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,5 +1,7 @@
 ## Process this file with automake to create Makefile.in
 
+SUBDIRS = gph
+
 EXTRA_DIST = DETAILS gpg.sgml gpg.1 FAQ HACKING OpenPGP
 
 man_MANS = gpg.1
@@ -15,21 +17,13 @@ else
 endif
 
 
-%.txt : %.sgml
-	sgml2txt -c latin $*
+%.dvi: %.sgml
+	db2dvi $<
 
-%.html : %.sgml
-	sgml2html -c latin $*
+%.ps: %.dvi
+	dvips -o $@ $<
 
-%.dvi : %.sgml
-	-rm $*.sgml.tmp
-	mv $*.sgml $*.sgml.tmp
-	sed -e '/<!entity/  s/"IGNORE">/"INCLUDE">/' $*.sgml.tmp >$*.sgml
-	sgml2latex -b -l deutsch -c latin $* ; mv $*.sgml.tmp $*.sgml
+%/%.html: %.sgml
+	-db2html $<
 
-%.ps : %.sgml
-	-rm $*.sgml.tmp
-	mv $*.sgml $*.sgml.tmp
-	sed -e '/<!entity/  s/"IGNORE">/"INCLUDE">/' $*.sgml.tmp >$*.sgml
-	sgml2latex -b -l deutsch -c latin -o ps $* ; mv $*.sgml.tmp $*.sgml
 
diff --git a/doc/credits-1.0 b/doc/credits-1.0
new file mode 100644
index 000000000..977910652
--- /dev/null
+++ b/doc/credits-1.0
@@ -0,0 +1,41 @@
+The GNU Privacy Guard has been created by the GnuPG team:
+Matthew Skala, Michael Roth, Niklas Hernaeus, Rémi Guyomarch
+and Werner Koch.  Gael Queri, Gregory Steuck, Janusz A. Urbanowicz,
+Marco d'Itri, Thiago Jung Bauermann, Urko Lusa and Walter Koch
+did the official translations.	Mike Ashley is working on the
+GNU Privacy Handbook.
+
+The following people helped greatly by suggesting improvements,
+testing, fixing bugs, providing resources and doing other important
+tasks:	Allan Clark, Anand Kumria, Ariel T Glenn, Bodo Moeller,
+Bryan Fullerton, Brian Moore, Brian Warner, Caskey L. Dickson,
+Cees van de Griend, Charles Levert, Christian von Roques,
+Christopher Oliver, Christian Recktenwald, Daniel Eisenbud,
+Daniel Koenig, David Ellement, Detlef Lannert, Dirk Lattermann,
+Ed Boraas, Enzo Michelangeli, Ernst Molitor, Fabio Coatti,
+Felix von Leitner, Frank Heckenbach, Frank Stajano, Gaël Quéri,
+Greg Louis, Greg Troxel, Gregory Steuck, Geoff Keating, Harald Denker,
+Hendrik Buschkamp, Holger Schurig, Hugh Daniel, Ian McKellar,
+Janusz A. Urbanowicz, James Troup, Jean-loup Gailly, Jens Bachem,
+Joachim Backes, John A. Martin, Johnny Teveßen, Jörg Schilling,
+Jun Kuriyama, Karl Fogel, Karsten Thygesen, Katsuhiro Kondou,
+Kazu Yamamoto, Lars Kellogg-Stedman, Marco d'Itri, Mark Adler,
+Mark Elbrecht, Markus Friedl, Martin Kahlert, Martin Hamilton,
+Martin Schulte, Matthew Skala, Max Valianskiy, Michael Roth,
+Michael Sobolev, Nicolas Graner, NIIBE Yutaka, Niklas Hernaeus,
+Nimrod Zimerman, N J Doye, Oliver Haakert, Oskari Jääskeläinen,
+Paul D. Smith, Philippe Laliberte, Peter Gutmann, QingLong,
+Ralph Gillen, Rat, Reinhard Wobst, Rémi Guyomarch, Reuben Sumner,
+Roland Rosenfeld, Ross Golder, Serge Munhoven, SL Baur, Stefan Karrmann,
+Stefan Keller, Steffen Ullrich, Steffen Zahn, Steven Bakker,
+Susanne Schultz, Thiago Jung Bauermann, Thomas Roessler, Tom Spindler,
+Tom Zerucha, Tomas Fasth, Thomas Mikkelsen, Ulf Möller, Urko Lusa,
+Walter Koch, Wim Vandeputte and Gerlinde Klaes.
+
+This software has been made possible by the previous work of
+Chris Wedgwood, Jean-loup Gailly, Jon Callas, Mark Adler, Martin Hellmann
+Paul Kendall, Philip R. Zimmermann, Peter Gutmann, Philip A. Nelson,
+Taher ElGamal, Torbjorn Granlund, Whitfield Diffie, some unknown NSA
+mathematicians and all the folks who have worked hard to create complete
+and free operating systems.
+
diff --git a/doc/gpg.sgml b/doc/gpg.sgml
index a5595400f..7f6d0ea05 100644
--- a/doc/gpg.sgml
+++ b/doc/gpg.sgml
@@ -253,7 +253,7 @@ with -u.</para></listitem></varlistentry>
     <term>lsign</term>
     <listitem><para>
 Same as --sign but the signature is marked as
-non-exportbale and will therefore never be used
+non-exportable and will therefore never be used
 by others.  This may be used to make keys valid
 only in the local environment.</para></listitem></varlistentry>
     <varlistentry>
diff --git a/doc/gph/ChangeLog b/doc/gph/ChangeLog
new file mode 100644
index 000000000..138703e59
--- /dev/null
+++ b/doc/gph/ChangeLog
@@ -0,0 +1,5 @@
+Fri Sep  3 13:24:45 1999  Werner Koch  (wk@gnupg.org)
+
+	* Makefile.am: New
+
+
diff --git a/doc/gph/Makefile.am b/doc/gph/Makefile.am
new file mode 100644
index 000000000..179e54645
--- /dev/null
+++ b/doc/gph/Makefile.am
@@ -0,0 +1,38 @@
+# GPH - GNU Privacy Handbook
+
+PARTS = manual.sgml c1.sgml c2.sgml c3.sgml c4.sgml c5.sgml c6.sgml \
+	signatures.fig
+
+EXTRA_DIST = $(PARTS) index.html
+BUILT_SOURCES = index.html
+
+index.html: $(PARTS) signatures.jpg
+	db2html manual.sgml
+	cp signatures.jpg manual/signatures.jpg
+	echo '<html><body>' >index.html
+	echo '<ul>'         >>index.html
+	echo '<li><a href="manual/book1.html">GnuPG User Manual</a>' >>index.html
+	echo '</ul>'          >>index.html
+	echo '</body></html>' >>index.html
+	-rm -r manual.junk
+	(cd manual; rm -r stylesheet-images; ls | grep -v distfiles >distfiles)
+
+%.dvi: %.sgml
+	db2dvi $<
+
+%.ps: %.dvi
+	dvips -o $@ $<
+
+%/%.html: %.sgml
+	db2html $<
+
+
+%.png: %.fig
+	fig2dev -L png $< $@
+
+%.jpg: %.fig
+	fig2dev -L jpeg $< $@
+
+%.eps: %.fig
+	fig2dev -L ps  $< $@
+
diff --git a/doc/gph/c1.sgml b/doc/gph/c1.sgml
new file mode 100644
index 000000000..2839f7c62
--- /dev/null
+++ b/doc/gph/c1.sgml
@@ -0,0 +1,627 @@
+<chapter id="intro" xreflabel="1">
+<docinfo>
+<date>
+$Id$
+</date>
+</docinfo>
+<title>
+Getting Started
+</title>
+
+<para>
+&Gnupg; is a tool for secure communication.
+This chapter is a quick-start guide that covers the core functionality
+of &gnupg;.
+This includes keypair creation, exchanging and verifying keys, encrypting
+and decrypting documents, and making and verifying signatures.
+It does not explain in detail the concepts behind public-key cryptography,
+encryption, and digital signatures.
+This is covered in Chapter <xref linkend="concepts">.
+It also does not explain how to use &gnupg; wisely.
+This is covered in Chapters <xref linkend="management"> and 
+<xref linkend="wise">.
+</para>
+
+<para>
+&Gnupg; uses public-key cryptography so that users may communicate securely.
+In a public-key system, each user has a public/private keypair.
+A user's private key is kept secret; it need never be revealed.
+The public key may be given to anyone with whom the user wants to
+communicate.
+&Gnupg; uses a somewhat more sophisticated scheme in which a user has
+a primary keypair and then zero or more additional subordinate keypairs.
+The primary and subordinate keypairs are bundled to facilitate key
+management and the bundle can often be considered simply as one keypair.
+</para>
+
+<sect1>
+<title>
+Generating a new keypair
+</title>
+
+<para>
+The command-line option <link linkend="gen-key"><option>--gen-key</option></link>
+is used to create a new primary keypair.
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --gen-key</userinput>
+gpg (GnuPG) 0.9.4; Copyright (C) 1999 Free Software Foundation, Inc.
+This program comes with ABSOLUTELY NO WARRANTY.
+This is free software, and you are welcome to redistribute it
+under certain conditions. See the file COPYING for details.
+
+Please select what kind of key you want:
+   (1) DSA and ElGamal (default)
+   (2) DSA (sign only)
+   (4) ElGamal (sign and encrypt)
+Your selection?
+</screen>
+
+<!--
+REWRITE
+From Thomas Zander (zander@microweb.nl):
+In GPG you can create 3 type of keypairs. A keypair is the combination
+of a publ ic key and a private key, see chapter X. A DSA keypair can
+only be used to sign a message. A ElGamal subordinate keypair can be
+used for encryption as well as s igning, but is not as compatible with
+former standards.
+
+Option 1 creates 2 keypairs; a DSA (signing) and a ElGamal (Encryption).
+Option 2 creates a DSA keypair (Signing)
+Option 4 creates a ElGemal keypair (Signing & Encryption).
+
+note: option 3 xxxx
+
+This doesn't quite work, but I agree the following paragraph is rough.
+-->
+
+&Gnupg; is able to create several different types of keypairs, but a primary
+key must be capable of making signatures.
+There are therefore only three options.
+Option 1 actually creates two keypairs.
+A DSA keypair is the primary keypair usable only for making signatures.
+An ElGamal subordinate keypair is also created for encryption. 
+Option 2 is similar but creates only a DSA keypair.
+Option 4<footnote><para>Option 3 is to generate an ElGamal keypair that is
+not usable for making signatures.</para></footnote> creates a single ElGamal 
+keypair usable for both making signatures and performing encryption.
+In all cases it is possible to later add additional subkeys for encryption
+and signing.
+For most users the default option is fine.
+</para>
+
+<para>
+You must also choose a key size.
+The size of a DSA key must be between 512 and 1024 bits, and an ElGamal
+key may be of any size.
+&Gnupg;, however, requires that keys be no smaller than 768 bits.
+Therefore, if Option 1 was chosen and you choose a keysize larger than
+1024 bits, the ElGamal key will have the requested size, but the DSA
+key will be 1024 bits.
+
+<screen width="80">
+About to generate a new ELG-E keypair.
+              minimum keysize is  768 bits
+              default keysize is 1024 bits
+    highest suggested keysize is 2048 bits
+What keysize do you want? (1024)
+</screen>
+
+The longer the key the more secure it is against brute-force attacks,
+but for almost all purposes the default keysize is adequate since
+it would be cheaper to circumvent the encryption than try to break it.
+Also, encryption and decryption will be slower as the
+key size is increased, and a larger keysize may affect signature length.
+Once selected, the keysize can never be changed.
+</para>
+
+<para>
+Finally, you must choose an expiration date.
+If Option 1 was chosen, the expiration date will be used for both the
+ElGamal and DSA keypairs.
+
+<screen width="80">
+Please specify how long the key should be valid.
+         0 = key does not expire
+      &lt;n>  = key expires in n days
+      &lt;n>w = key expires in n weeks
+      &lt;n>m = key expires in n months
+      &lt;n>y = key expires in n years
+Key is valid for? (0) 
+</screen>
+
+For most users a key that does not expire is adequate.
+The expiration time should be chosen with care, however,
+since although it is possible to change the expiration date after the key
+is created, it may be difficult to communicate a change
+to users who have your public key.
+</para>
+
+<para>
+You must provide a user ID in addition to the key parameters.
+The user ID is used to associate the key being created with a real
+person.
+
+<screen width="80">
+You need a User-ID to identify your key; the software constructs the user id
+from Real Name, Comment and Email Address in this form:
+    "Heinrich Heine (Der Dichter) &lt;heinrichh@duesseldorf.de>"
+
+Real name: 
+</screen>
+
+Only one user ID is created when a key is created, but it is possible
+to create additional user IDs if you want to use the key in two or
+more contexts, &eg;, as an employee at work and a political activist
+on the side.
+A user ID should be created carefully since it cannot be edited after
+it is created.
+</para>
+
+<para>
+&Gnupg; needs a passphrase to protect the primary and subordinate 
+private keys that you keep in your possession.
+
+<screen width="80">
+You need a Passphrase to protect your private key.    
+
+Enter passphrase: 
+</screen>
+
+There is no limit on the length of a passphrase, and it should be
+carefully chosen.
+From the perspective of security, the passphrase to unlock the private
+key is one of the weakest points in &gnupg; (and other public-key 
+encryption systems as well) since it is the only protection you 
+have if another individual gets your private key.
+Ideally, the passphrase should not use words from a dictionary and
+should mix the case of alphabetic characters as well as use 
+non-alphabetic characters.
+A good passphrase is crucial to the secure use of &gnupg;.
+</para>
+
+<sect2 id="revocation">
+<title>
+Generating a revocation certificate
+</title>
+
+<para>
+After your keypair is created you should immediately generate a revocation
+certificate for the primary public key using the option
+<link linkend="gen-revoke"><option>--gen-revoke</option></link>.
+If you forget your passphrase or if your private key is compromised 
+or lost, this revocation certificate may be published to notify others
+that the public key should no longer be used.
+A revoked public key can still be used to verify signatures made
+by you in the past, but it cannot be used to encrypt future messages
+to you.
+It also does not affect your ability to decrypt messages sent to
+you in the past if you still do have access to the private key.
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --output revoke.asc --gen-revoke mykey</userinput>
+[...]
+</screen>
+
+The argument <userinput>mykey</userinput> must be a <emphasis>key
+specifier</emphasis>,
+either the key ID of your primary keypair or any part of a user ID
+that identifies your keypair.
+The generated certificate will be left in the file
+<parameter>revoke.asc</parameter>.
+If the <link linkend="output"><option>--output</option></link> option is 
+omitted, the result will be placed on standard output.
+Since the certificate is short, you may wish to print a hardcopy of
+the certificate to store somewhere safe such as your safe deposit box.
+The certificate should not be stored where others can access it since
+anybody can publish the revocation certificate and render the
+corresponding public key useless.
+</para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>
+Exchanging keys
+</title>
+
+<para>
+To communicate with others you must exchange public keys.
+To list the keys on your public keyring use the command-line 
+option <link linkend="list-keys"><option>--list-keys</option></link>.
+</para>
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --list-keys</userinput>
+/users/alice/.gnupg/pubring.gpg
+---------------------------------------
+pub  1024D/BB7576AC 1999-06-04 Alice (Judge) &lt;alice@cyb.org>
+sub  1024g/78E9A8FA 1999-06-04
+</screen>
+
+<sect2>
+<title>
+Exporting a public key
+</title>
+
+<para>
+To send your public key to a correspondent you must first export it.
+The command-line option <link linkend="export"><option>--export</option></link>
+is used to do this.
+It takes an additional argument identifying the public key to export.
+As with the <option>--gen-revoke</option> option, either the key ID or any part of
+the user ID may be used to identify the key to export.
+</para>
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --output alice.gpg --export alice@cyb.org</userinput>
+</screen>
+
+<para>
+The key is exported in a binary format, but this can be inconvenient
+when the key is to be sent though email or published on a web page.
+&Gnupg; therefore supports a command-line option 
+<link linkend="armor"><option>--armor</option></link><footnote>
+<para>Many
+command-line options that are frequently used can also be set in a
+<link linkend="optionsfile">configuration file</link>.
+</para>
+</footnote>
+that that 
+causes output to be generated in an ASCII-armored format similar to
+uuencoded documents.
+In general, any output from &gnupg;, &eg;, keys, encrypted documents, and
+signatures, can be ASCII-armored by adding the <option>--armor</option> option.
+</para>
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --armor --export alice@cyb.org</userinput>
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: GnuPG v0.9.7 (GNU/Linux)
+Comment: For info see http://www.gnupg.org
+
+[...]
+-----END PGP PUBLIC KEY BLOCK-----
+</screen>
+</sect2>
+
+<sect2>
+<title>
+Importing a public key
+</title>
+
+<para>
+A public key may be added to your public keyring with the
+<link linkend="import"><option>--import</option></link> option.
+</para>
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --import blake.gpg</userinput>
+gpg: key 9E98BC16: public key imported
+gpg: Total number processed: 1
+gpg:               imported: 1
+<prompt>alice%</prompt> <userinput>gpg --list-keys</userinput>
+/users/alice/.gnupg/pubring.gpg
+---------------------------------------
+pub  1024D/BB7576AC 1999-06-04 Alice (Judge) &lt;alice@cyb.org>
+sub  1024g/78E9A8FA 1999-06-04
+
+pub  1024D/9E98BC16 1999-06-04 Blake (Executioner) &lt;blake@cyb.org>
+sub  1024g/5C8CBD41 1999-06-04
+</screen>
+
+<para>
+Once a key is imported it should be validated.
+&Gnupg; uses a powerful and flexible trust model that does not require
+you to personally validate each key you import.
+Some keys may need to be personally validated, however.
+A key is validated by verifying the key's fingerprint and then signing
+the key to certify it as a valid key.
+A key's fingerprint can be quickly viewed with the
+<link linkend="fingerprint"><option>--fingerprint</option></link>
+command-line option, but in order to certify the key you must edit it.
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --edit-key blake@cyb.org</userinput>
+
+pub  1024D/9E98BC16  created: 1999-06-04 expires: never      trust: -/q
+sub  1024g/5C8CBD41  created: 1999-06-04 expires: never     
+(1)  Blake (Executioner) &lt;blake@cyb.org>
+
+<prompt>Command></prompt> <userinput>fpr</userinput>
+pub  1024D/9E98BC16 1999-06-04 Blake (Executioner) &lt;blake@cyb.org>
+             Fingerprint: 268F 448F CCD7 AF34 183E  52D8 9BDE 1A08 9E98 BC16
+</screen>
+
+Key verification is a weak point in public-key cryptography, so you
+must be sure that the fingerprint is correct.
+The fingerprint displayed should be checked with the key's owner.
+This may be done in person or over the phone or through any other means
+as long as you can guarantee that you are communicating with the key's
+true owner.
+Once verified you may sign the key to validate it.
+</para>
+
+<screen width="80">
+<prompt>Command></prompt> <userinput>sign</userinput>
+             
+pub  1024D/9E98BC16  created: 1999-06-04 expires: never      trust: -/q
+             Fingerprint: 268F 448F CCD7 AF34 183E  52D8 9BDE 1A08 9E98 BC16
+
+     Blake (Executioner) &lt;blake@cyb.org>
+
+Are you really sure that you want to sign this key
+with your key: "Alice (Judge) &lt;alice@cyb.org>"
+
+Really sign?
+</screen>
+
+<para>
+Once signed you can check the key to list the signatures on it and
+see the signature that you have added.
+Every user ID on the key will have one or more self-signatures as well
+as a signature for each user that has validated the key.
+</para>
+
+<screen width="80">
+<prompt>Command></prompt> <userinput>check</userinput>
+uid  Blake (Executioner) &lt;blake@cyb.org>
+sig!       9E98BC16 1999-06-04   [self-signature]
+sig!       BB7576AC 1999-06-04   Alice (Judge) &lt;alice@cyb.org>
+</screen>
+</sect2>
+</sect1>
+
+<sect1>
+<title>
+Encrypting and decrypting documents
+</title>
+
+<para>
+To encrypt a document the option 
+<link linkend="encrypt"><option>--encrypt</option></link> is used.
+You must have the public keys of the intended recipients.
+The software expects the name of the document to encrypt as input or, if
+omitted, on standard input.
+The encrypted result is placed on standard output or as specified using
+the option <option>--output</option>.
+The document is compressed for additional security in addition to
+encrypting it.
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --output doc.gpg --encrypt --recipient blake@cyb.org doc</userinput>
+</screen>
+
+The <link linkend="recipient"><option>--recipient</option></link> option
+is used once for each recipient and takes an extra argument specifying
+the public key to which the document should be encrypted.
+The encrypted document can only be decrypted by someone with a private
+key that complements one of the recipients' public keys.
+In particular, you cannot decrypt a document encrypted by you unless
+you included your own public key in the recipient list.
+</para>
+
+<para>
+To decrypt a message the option 
+<link linkend="decrypt"><option>--decrypt</option></link> is used.
+You need the private key to which the message was encrypted.
+Similar to the encryption process, the document to decrypt is
+input, and the decrypted result is output.
+</para>
+
+<screen width="80">
+<prompt>blake%</prompt> <userinput>gpg --output doc --decrypt doc.gpg</userinput>
+
+You need a passphrase to unlock the secret key for
+user: "Blake (Executioner) &lt;blake@cyb.org>"
+1024-bit ELG-E key, ID 5C8CBD41, created 1999-06-04 (main key ID 9E98BC16)
+
+Enter passphrase: 
+</screen>
+
+<para>
+Documents may also be encrypted without using public-key cryptography.
+Instead, only a symmetric cipher is used to encrypt the document.
+The key used to drive the symmetric cipher is derived from a passphrase
+supplied when the document is encrypted, and for good security, it
+should not be the same passphrase that you use to protect your private key.
+Symmetric encryption is useful for securing documents when the
+passphrase does not need to be communicated to others.
+A document can be encrypted with a symmetric cipher by using the
+<link linkend="symmetric"><option>--symmetric</option></link> option.
+</para>
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --output doc.gpg --symmetric doc</userinput>
+Enter passphrase: 
+</screen>
+</sect1>
+
+<sect1>
+<title>
+Making and verifying signatures
+</title>
+
+<para>
+A digital signature certifies and timestamps a document.
+If the document is subsequently modified in any way, a verification
+of the signature will fail.
+A digital signature can serve the same purpose as a hand-written signature
+with the additional benefit of being tamper-resistant.
+The &gnupg; source distribution, for example, is signed so that users can
+verify that the source code has not been modified since it was packaged.
+</para>
+
+<para>
+Creating and verifying signatures uses the public/private keypair
+in an operation different from encryption and decryption.
+A signature is created using the private key of the signer.
+The signature is verified using the corresponding public key.
+A consequence is that it is difficult to deny that you made a digital
+signature since that would imply your private key had been compromised.
+</para>
+
+<para>
+The command-line option <link linkend="sign"><option>--sign</option></link> is
+used to make a digital signature.
+The document to sign is input, and the signed document is output.
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --output doc.sig --sign doc</userinput>
+
+You need a passphrase to unlock the private key for
+user: "Alice (Judge) &lt;alice@cyb.org>"
+1024-bit DSA key, ID BB7576AC, created 1999-06-04
+
+Enter passphrase: 
+</screen>
+
+The document is compressed before signed, and the output is in binary
+format.
+</para>
+
+<para>
+Given a signed document, you can either check the signature or
+check the signature and recover the original document.
+To check the signature use the 
+<link linkend="verify"><option>--verify</option></link> option.
+To verify the signature and extract the document use the
+<option>--decrypt</option>
+option.
+The signed document to verify and recover is input and the recovered
+document is output.
+</para>
+
+<screen width="80">
+<prompt>blake%</prompt> <userinput>gpg --output doc --decrypt doc.sig</userinput>
+gpg: Signature made Fri Jun  4 12:02:38 1999 CDT using DSA key ID BB7576AC
+gpg: Good signature from "Alice (Judge) &lt;alice@cyb.org>"
+</screen>
+
+<sect2>
+<title>
+Clearsigned documents
+</title>
+
+<para>
+A common use of digital signatures is to sign usenet postings or
+email messages.
+In such situations it is undesirable to compress the document while
+signing it.
+The option 
+<link linkend="clearsign"><option>--clearsign</option></link> 
+causes the document to be wrapped in an ASCII-armored signature but 
+otherwise does not modify the document.
+</para>
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --clearsign doc</userinput>
+
+You need a passphrase to unlock the secret key for
+user: "Alice (Judge) &lt;alice@cyb.org>"
+1024-bit DSA key, ID BB7576AC, created 1999-06-04
+
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA1
+
+[...]
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v0.9.7 (GNU/Linux)
+Comment: For info see http://www.gnupg.org
+
+iEYEARECAAYFAjdYCQoACgkQJ9S6ULt1dqz6IwCfQ7wP6i/i8HhbcOSKF4ELyQB1
+oCoAoOuqpRqEzr4kOkQqHRLE/b8/Rw2k
+=y6kj
+-----END PGP SIGNATURE-----
+</screen>
+</sect2>
+
+<sect2>
+<title>
+Detached signatures
+</title>
+
+<para>
+A signed document has limited usefulness.
+Other users must recover the original document from the signed
+version, and even with clearsigned documents, the signed document
+must be edited to recover the original.
+Therefore, there is a third method for signing a document that
+creates a detached signature.
+A detached signature is created using the 
+<link linkend="detach-sig"><option>--detach-sig</option></link>
+option.
+</para>
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --output doc.sig --detach-sig doc</userinput>
+
+You need a passphrase to unlock the secret key for
+user: "Alice (Judge) &lt;alice@cyb.org>"
+1024-bit DSA key, ID BB7576AC, created 1999-06-04
+
+Enter passphrase: 
+</screen>
+
+<para>
+Both the document and detached signature are needed to verify
+the signature.
+The <option>--verify</option> option can be to check the 
+signature.
+</para>
+
+<screen width="80">
+<prompt>blake%</prompt> <userinput>gpg --verify doc.sig doc</userinput>
+gpg: Signature made Fri Jun  4 12:38:46 1999 CDT using DSA key ID BB7576AC
+gpg: Good signature from "Alice (Judge) &lt;alice@cyb.org>"
+</screen>
+</sect2>
+</sect1>
+</chapter>
+
+<!--
+In the "Getting Started" chapter, it would be interesting to provide
+a checklist of assumptions that the reader can consult to determine
+whether or not she fits the "most users" profile.  Perhaps put this
+at the end of the chapter (perhaps w/ forward pointer?).  You could
+include cross references for each item on the list.  For example:
+
+    23.  Your use of public key encryption has property X with attribute Y.
+         (see Section 3.4.1 for a more detailed discussion of other
+          attributes of property X)
+
+What prompted this was wondering, as I read through the generating keypair
+section, "under what circumstances would these defaults be inappropriate?"
+
+The notion of using the same key with different user IDs "as an employee at
+work and a political activist on the side" is interesting.  Knowing one,
+could you be traced to the other?  (Are they separate numeric ids, and is
+that enough?)  (seems someone could just match the public keys)
+
+It's a very nice touch that you don't cover every single prompt that the
+system throws at you, but instead treat them functionally.  For example,
+I can imagine other books going through the "Comment:" and "Email Address:"
+prompts.
+-->
+
+<!--
+"Key verification is a weak point in public-key cryptography ..."
+Saying "weak point" makes it sound like a slam on public key stuff.
+Although we've talked about weaknesses of the trust model, I'm guessing
+the point here is that communication is only secure if you verify the
+identity of the key's owner.
+
+Key verification can be done through any means "as long as you can
+guarantee that you are communicating with the key's true owner".
+I suspect we'd also like to prevent leaking information that an
+interceptor could use to pose as us in a key verification step with
+another party.  I suppose the notion of bootstrapping may not be widely
+appreciated as an analogy.
+
+I'm almost inclined to want to see a section in the Getting Started
+guide called "Why you should read the rest of this book".  Failing
+that, or perhaps better yet, maybe it would work to have some margin
+notes that point to other sections of the book for more information
+("a discussion of trust models begins on p. 95").
+-->
+
diff --git a/doc/gph/c2.sgml b/doc/gph/c2.sgml
new file mode 100644
index 000000000..b045ed4ee
--- /dev/null
+++ b/doc/gph/c2.sgml
@@ -0,0 +1,345 @@
+<chapter id="concepts" xreflabel="2">
+<docinfo>
+<date>
+$Id$
+</date>
+</docinfo>
+<title>
+Concepts
+</title>
+
+<para>
+&Gnupg; makes uses of several cryptographic concepts including 
+<firstterm>symmetric ciphers</firstterm>, 
+<firstterm>public-key ciphers</firstterm>, and 
+<firstterm>one-way hashing</firstterm>.
+You can make basic use &gnupg; without fully understanding these concepts,
+but in order to use it wisely some understanding of them is necessary.
+</para>
+
+<para>
+This chapter introduces the basic cryptographic concepts used in GnuPG.
+Other books cover these topics in much more detail.
+A good book with which to pursue further study is 
+<ulink url="http://www.counterpane.com/schneier.html">Bruce 
+Schneier</ulink>'s
+<ulink url="http://www.counterpane.com/applied.html">"Applied 
+Cryptography"</ulink>.
+</para>
+
+<sect1>
+<title>
+Symmetric ciphers
+</title>
+
+<para>
+A symmetric cipher is a cipher that uses the same key for both encryption
+and decryption.
+Two parties communicating using a symmetric cipher must agree on the
+key beforehand.
+Once they agree, the sender encrypts a message using the key, sends it
+to the receiver, and the receiver decrypts the message using the key.
+As an example, the German Enigma is a symmetric cipher, and daily keys
+were distributed as code books.
+Each day, a sending or receiving radio operator would consult his copy
+of the code book to find the day's key.
+Radio traffic for that day was then encrypted and decrypted using the
+day's key.
+Modern examples of symmetric ciphers include 3DES, Blowfish, and IDEA.
+</para>
+
+<para>
+A good cipher puts all the security in the key and none in the algorithm.
+In other words, it should be no help to an attacker if he knows which
+cipher is being used.
+Only if he obtains the key would knowledge of the algorithm be needed.
+The ciphers used in &gnupg; have this property.
+</para>
+
+<para>
+Since all the security is in the key, then it is important that it be
+very difficult to guess the key.
+In other words, the set of possible keys, &ie;, the <emphasis>key
+space</emphasis>, needs
+to be large.
+While at Los Alamos, Richard Feynman was famous for his ability to
+crack safes.
+To encourage the mystique he even carried around a set of tools
+including an old stethoscope.
+In reality, he used a variety of tricks to reduce the number of
+combinations he had to try to a small number and then simply guessed
+until he found the right combination.
+In other words, he reduced the size of the key space.
+</para>
+
+<para>
+Britain used machines to guess keys during World War 2.
+The German Enigma had a very large key space, but the British built
+speciailzed computing engines, the Bombes, to mechanically try 
+keys until the day's key was found.
+This meant that sometimes they found the day's key within hours of
+the new key's use, but it also meant that on some days they never
+did find the right key.
+The Bombes were not general-purpose computers but were precursors
+to modern-day computers.
+</para>
+
+<para>
+Today, computers can guess keys very quickly, and this is why key
+size is important in modern cryptosystems.
+The cipher DES uses a 56-bit key, which means that there are
+<!-- inlineequation -->
+2<superscript>56</superscript> possible keys.
+<!-- inlineequation -->
+2<superscript>56</superscript> is 72,057,594,037,927,936 keys.
+This is a lot of keys, but a general-purpose computer can check the
+entire key space in a matter of days.
+A specialized computer can check it in hours.
+On the other hand, more recently designed ciphers such as 3DES, 
+Blowfish, and IDEA
+<!-- inlineequation -->
+all use 128-bit keys, which means there are 2<superscript>128</superscript> 
+possible keys.
+This is many, many more keys, and even if all the computers on the
+planet cooperated, it could still take more time than the age of
+the universe to find the key.
+</para>
+</sect1>
+
+<sect1>
+<title>
+Public-key ciphers
+</title>
+
+<para>
+The primary problem with symmetric ciphers is not their security but
+with key exchange.
+Once the sender and receiver have exchanged keys, that key can be
+used to securely communicate, but what secure communication channel
+was used to communicate the key itself?
+In particular, it would probably be much easier for an attacker to work
+to intercept the key than it is to try all the keys in the key space.
+Another problem is the number of keys needed.
+<!-- inlineequation -->
+If there are <emphasis>n</emphasis> people who need to communicate, then 
+<!-- inlineequation -->
+<emphasis>n(n-1)/2</emphasis> keys
+are needed for each pair of people to communicate privately.
+This may be ok for a small number of people but quickly becomes unwieldly
+for large groups of people.
+</para>
+
+<para>
+Public-key ciphers were invented to avoid the key-exchange problem
+entirely.
+A public-key cipher uses a pair of keys for sending messages.
+The two keys belong to the person receiving the message.
+One key is a <emphasis>public key</emphasis> and may be given to anybody.
+The other key is a <emphasis>private key</emphasis> and is kept 
+secret by the owner.
+A sender encrypts a message using the public key and once encrypted,
+only the private key may be used to decrypt it.
+</para>
+
+<para>
+This protocol solves the key-exchange problem inherent with symmetric
+ciphers.
+There is no need for the sender and receiver to agree
+upon a key.
+All that is required is that some time before secret communication the
+sender gets a copy of the receiver's public key.
+Furthermore, the one public key can be used by anybody wishing to
+communicate with the receiver.
+<!-- inlineequation -->
+So only <emphasis>n</emphasis> keypairs are needed for <emphasis>n</emphasis> 
+people to communicate secretly
+with one another,
+</para>
+
+<para>
+Public-key ciphers are based on one-way trapdoor functions.
+A one-way function is a function that is easy to compute,
+but the inverse is hard to compute.
+For example, it is easy to multiply two prime numbers together to get
+a composite, but it is difficult to factor a composite into its prime
+components.a
+A one-way trapdoor function is similar, but it has a trapdoor.
+That is, if some piece of information is known, it becomes easy
+to compute the inverse.
+For example, if you have a number made of two prime factors, then knowing
+one of the factors makes it easy to compute the second.
+Given a public-key cipher based on prime factorization, the public
+key contains a composite number made from two large prime factors, and
+the encryption algorithm uses that composite to encrypt the
+message.
+The algorithm to decrypt the message requires knowing the prime factors,
+so decryption is easy if you have the private key containing one of the
+factors but extremely difficult if you do not have it.
+</para>
+
+<para>
+As with good symmetric ciphers, with a good public-key cipher all of the
+security rests with the key.
+Therefore, key size is a measure of the system's security, but
+one cannot compare the size of a symmetric cipher key and a public-key
+cipher key as a measure of their relative security.
+In a brute-force attack on a symmetric cipher with a key size of 80 bits,
+<!-- inlineequation -->
+the attacker must enumerate up to 2<superscript>81</superscript>-1 keys to 
+find the right key.
+In a brute-force attack on a public-key cipher with a key size of 512 bits,
+the attacker must factor a composite number encoded in 512 bits (up to
+155 decimal digits).
+The workload for the attacker is fundamentally different depending on
+the cipher he is attacking.
+While 128 bits is sufficient for symmetric ciphers, given today's factoring
+technology public keys with 1024 bits are recommended for most purposes.
+</para>
+</sect1>
+
+<sect1>
+<title>
+Hybrid ciphers
+</title>
+
+<para>
+Public-key ciphers are no panacea.
+Many symmetric ciphers are stronger from a security standpoint,
+and public-key encryption and decryption are more expensive than the
+corresponding operations in symmetric systems.
+Public-key ciphers are nevertheless an effective tool for distributing
+symmetric cipher keys, and that is how they are used in hybrid cipher
+systems.
+</para>
+
+<para>
+A hybrid cipher uses both a symmetric cipher and a public-key cipher.
+It works by using a public-key cipher to share a key for the symmetric
+cipher.
+The actual message being sent is then encrypted using the key and sent
+to the recipient.
+Since symmetric key sharing is secure, the symmetric key used is different
+for each message sent.
+Hence it is sometimes called a session key.
+</para>
+
+<para>
+Both PGP and &gnupg; use hybrid ciphers.
+The session key, encrypted using the public-key cipher, and the message
+being sent, encrypted with the symmetric cipher, are automatically
+combined in one package.
+The recipient uses his private-key to decrypt the session key and the
+session key is then used to decrypt the message.
+</para>
+
+<para>
+A hybrid cipher is no stronger than the public-key cipher or symmetric
+cipher it uses, whichever is weaker.
+In PGP and &gnupg;, the public-key cipher is probably the weaker of
+the pair.
+Fortunately, however, if an attacker could decrypt a session key it
+would only be useful for reading the one message encrypted with that
+session key.
+The attacker would have to start over and decrypt another session
+key in order to read any other message.
+</para>
+</sect1>
+
+<sect1>
+<title>
+Digital signatures
+</title>
+
+<para>
+A hash function is a many-to-one function that maps its input to a
+value in a finite set.
+Typically this set is a range of natural numbers.
+<!-- inlineequation -->
+A simple ehash function is <emphasis>f</emphasis>(<emphasis>x</emphasis>) = 0 
+for all integers <emphasis>x</emphasis>.
+A more interesting hash function is 
+<emphasis>f</emphasis>(<emphasis>x</emphasis>) = <emphasis>x</emphasis> 
+<emphasis>mod</emphasis> 37, which
+maps <emphasis>x</emphasis> to the remainder of dividing <emphasis>x</emphasis> by 37.
+</para>
+
+<para>
+A document's digital signature is the result of applying a hash
+function to the document.
+To be useful, however, the hash function needs to satisfy two
+important properties.
+First, it should be hard to find two documents that hash to the
+same value.
+Second, given a hash value it should be hard to recover the document
+that produced that value.
+</para>
+
+<para>
+Some public-key ciphers<footnote><para>
+The cipher must have the property that the actual public key or private
+key could be used by the encryption algorithm as the public key.
+RSA is an example of such an algorithm while ElGamal is not an example.
+</para>
+</footnote> could be used to sign documents.
+The signer encrypts the document with his <emphasis>private</emphasis> key.
+Anybody wishing to check the signature and see the document simply
+uses the signer's public key to decrypt the document.
+This algorithm does satisfy the two properties needed from a good hash
+function, but in practice, this algorithm is too slow to be useful.
+</para>
+
+<para>
+An alternative is to use hash functions designed to satisfy these
+two important properties.
+SHA and MD5 are examples of such algorithms.
+Using such an algorithm, a document is signed by hashing it, and
+the hash value is the signature.
+Another person can check the signature by also hashing their copy of the
+document and comparing the hash value they get with the hash value of
+the original document.
+If they match, it is almost certain that the documents are identical.
+</para>
+
+<para>
+Of course, the problem now is using a hash function for digital
+signatures without permitting an attacker to interfere with signature
+checking.
+If the document and signature are sent unencrypted, an attacker could
+modify the document and generate a corresponding signature without the
+recipient's knowledge.
+If only the document is encrypted, an attacker could tamper with the
+signature and cause a signature check to fail.
+A third option is to use a hybrid public-key encryption to encrypt both
+the signature and document.
+The signer uses his private key, and anybody can use his public key
+to check the signature and document.
+This sounds good but is actually nonsense.
+If this algorithm truly secured the document it would also
+secure it from tampering and there would be no need for the signature.
+The more serious problem, however, is that this does not protect either
+the signature or document from tampering.
+With this algorithm, only the session key for the symmetric cipher
+is encrypted using the signer's private key.
+Anybody can use the public key to recover the session key.
+Therefore, it is straightforward for an attacker to recover the session
+key and use it to encrypt substitute documents and signatures to send
+to others in the sender's name.
+</para>
+
+<para>
+An algorithm that does work is to use a public key algorithm to
+encrypt only the signature.
+In particular, the hash value is encrypted using the signer's private
+key, and anbody can check the signature using the public key.
+The signed document can be sent using any other encryption algorithm
+including none if it is a public document.
+If the document is modified the signature check will fail, but this
+is precisely what the signature check is supposed to catch.
+The Digital Signature Standard (DSA) is a public key signature 
+algorithm that works as just described.
+DSA is the primary signing algorithm used in &Gnupg;.
+</para>
+
+</sect1>
+</chapter>
+
diff --git a/doc/gph/c3.sgml b/doc/gph/c3.sgml
new file mode 100644
index 000000000..541cf6c9d
--- /dev/null
+++ b/doc/gph/c3.sgml
@@ -0,0 +1,885 @@
+<chapter id="management" xreflabel="3">
+<docinfo>
+<date>
+$Id$
+</date>
+</docinfo>
+<title>
+Key Management
+</title>
+
+<para>
+Key tampering is a major security weakness with public-key cryptography.
+An eavesdropper may tamper with a user's keyrings or forge a
+user's public key and post it for others to download and use.
+For example, suppose Chloe wants to monitor the messages that Alice
+sends to Blake.
+She could mount what is called a <firstterm>man in the 
+middle</firstterm> attack.
+In this attack, Chloe creates a new public/private keypair.
+She replaces Alice's copy of Blake's public key with the new public key.
+She then intercepts the messages that Alice sends to Blake.
+For each intercept, she decrypts it using the new private key, reencrypts
+it using Blake's true public key, and forwards the reencrypted
+message to Blake.
+All messages sent from Alice to Blake can now be read by Chloe.
+</para>
+
+<para>
+Good key management is crucial in order to ensure not just the integrity
+of your keyrings but the integrity of other users' keyrings as well.
+The core of key management in &gnupg; is the notion of signing keys.
+Key signing has two main purposes: it permits you to detect tampering
+on your keyring, and it allows you to certify that a key truly belongs
+to the person named by a user ID on the key.
+Key signatures are also used in a scheme known as the <firstterm>web of 
+trust</firstterm> to extend certification to keys not directly signed by you 
+but signed by others you trust.
+Responsible users who practice good key management can defeat key
+tampering as a practical attack on secure communication with &gnupg;.
+</para>
+
+<sect1>
+<title>
+Managing your own keypair
+</title>
+
+<para>
+A keypair has a public key and a private key.
+A public key consists of 
+the public portion of the master signing key,
+the public portions of the subordinate signing and encryption subkeys, and 
+a set of user IDs used to associate the public key with a real person.
+Each piece has data about itself.
+For a key, this data includes its ID, when it was created, when it
+will expire, etc.
+For a user ID, this data includes the name of the real person it identifies,
+an optional comment, and an email address.
+The structure of the private key is similar, except that it contains only
+the private portions of the keys, and there is no user ID information.
+</para>
+
+<para>
+The command-line option 
+<link linkend="edit-key"><option>--edit-key</option></link>
+may be used to view a keypair.
+For example,
+
+<screen width="80">
+<prompt>chloe%</prompt> <userinput>gpg --edit-key chloe@cyb.org</userinput>
+Secret key is available.
+
+pub  1024D/26B6AAE1  created: 1999-06-15 expires: never      trust: -/u
+sub  2048g/0CF8CB7A  created: 1999-06-15 expires: never     
+sub  1792G/08224617  created: 1999-06-15 expires: 2002-06-14
+sub   960D/B1F423E7  created: 1999-06-15 expires: 2002-06-14
+(1)  Chloe (Jester) &lt;chloe@cyb.org>
+(2)  Chloe (Plebian) &lt;chloe@tel.net>
+<prompt>Command></prompt>
+</screen>
+
+The public key is displayed along with an indication of whether
+or not the private key is available.
+Information about each component of the public key is then listed.
+The first column indicates the type of the key.
+The keyword <literal>pub</literal> identifies the public master signing key,
+and the keyword <literal>sub</literal> identifies a public subordinate key.
+The second column indicates the key's bit length, type, and ID.
+The type is <literal>D</literal> for a DSA key, <literal>g</literal> for an 
+encryption-only
+ElGamal key, and <literal>G</literal> for an ElGamal key that may be used for
+both encryption and signing.
+The creation date and expiration date are given in columns three and four.
+The user IDs are listed following the keys.
+</para>
+
+<para>
+More information about the key can be obtained with interactive commands.
+The command <link linkend="toggle"><command>toggle</command></link> 
+switches between the public and private
+components of a keypair if indeed both components are available.
+
+<screen width="80">
+<prompt>Command></prompt> <userinput>toggle</userinput>
+               
+sec  1024D/26B6AAE1  created: 1999-06-15 expires: never     
+sbb  2048g/0CF8CB7A  created: 1999-06-15 expires: never     
+sbb  1792G/08224617  created: 1999-06-15 expires: 2002-06-14
+sbb   960D/B1F423E7  created: 1999-06-15 expires: 2002-06-14
+(1)  Chloe (Jester) &lt;chloe@cyb.org>
+(2)  Chloe (Plebian) &lt;chloe@tel.net>
+</screen>
+
+The information provided is similar to the listing for the public-key
+component.
+The keyword <literal>sec</literal> identifies the private master signing key,
+and the keyword <literal>sbb</literal> identifies the private subordinates keys.
+The user IDs from the public key are also listed for convenience.
+</para>
+
+<sect2>
+<title id="integrity">
+Key integrity
+</title>
+
+<para>
+When you distribute your public key, you are distributing the public
+components of your master and subordinate keys as well as the user IDs.
+Distributing this material alone, however, is a security risk since
+it is possible for an attacker to tamper with the key.
+The public key can be modified by adding or substituting keys, or by
+adding or changing user IDs.
+By tampering with a user ID, the attacker could change the user ID's email
+address to have email redirected to himself.
+By changing one of the encryption keys, the attacker would
+also be able to decrypt the messages redirected to him.
+</para>
+
+<para>
+Using digital signatures is a solution to this problem.
+When data is signed by a private key, the corresponding public key
+is bound to the signed data.
+In other words, only the corresponding public key can be used to
+verify the signature and ensure that the data has not been modified.
+A public key can be protected from tampering by using its corresponding
+private master key to sign the public key components and user IDs, thus
+binding the components to the public master key.
+Signing public key components with the corresponding private master
+signing key is called <firstterm>self-signing</firstterm>, and a public key that has
+self-signed user IDs bound to it is called a <firstterm>certificate</firstterm>.
+</para>
+
+<!--
+%\begin{figure}
+%Blank
+%\caption{This should depict how self-signatures bind information to
+%a public key.}\label{fig:selfsignedkey}
+%\end{figure}
+%
+%As an example, Figure~\ref{fig:selfsignedkey} illustrates Chloe's public
+%key, which has been self-signed to bind the user IDs and public subkeys
+%to the public master key.
+%The signatures on the user IDs can be checked with the \texttt{check}
+%command from the key edit menu.
+-->
+
+<para>
+As an example, Chloe has two user IDs and three subkeys.
+The signatures on the user IDs can be checked with the command
+<link linkend="check"><command>check</command></link> from the key edit menu.
+
+<screen width="80">
+<prompt>chloe%</prompt> <userinput>gpg --edit-key chloe</userinput>
+Secret key is available.
+
+pub  1024D/26B6AAE1  created: 1999-06-15 expires: never      trust: -/u
+sub  2048g/0CF8CB7A  created: 1999-06-15 expires: never     
+sub  1792G/08224617  created: 1999-06-15 expires: 2002-06-14
+sub   960D/B1F423E7  created: 1999-06-15 expires: 2002-06-14
+(1)  Chloe (Jester) &lt;chloe@cyb.org>
+(2)  Chloe (Plebian) &lt;chloe@tel.net>
+
+<prompt>Command></prompt> <userinput>check</userinput>
+uid  Chloe (Jester) &lt;chloe@cyb.org>
+sig!       26B6AAE1 1999-06-15   [self-signature]
+uid  Chloe (Plebian) &lt;chloe@tel.net>
+sig!       26B6AAE1 1999-06-15   [self-signature]
+</screen>
+
+As expected, the signing key for each signature is the master signing
+key with key ID <literal>0x26B6AAE1</literal>.
+The self-signatures on the subkeys are present in the public key, but
+they are not shown by the &gnupg; interface.
+</para>
+</sect2>
+
+<sect2>
+<title>
+Adding and deleting key components
+</title>
+
+<para>
+Both new subkeys and new user IDs may be added to your keypair after
+it has been created.
+A user ID is added using the command 
+<link linkend="adduid"><command>adduid</command></link>.
+You are prompted for a real name, email address, and comment just
+as when you create an initial keypair.
+A subkey is added using the command 
+<link linkend="addkey"><command>addkey</command></link>.
+The interface is similar to the interface used when creating an initial
+keypair.
+The subkey may be a DSA signing key, and encrypt-only ElGamal
+key, or a sign-and-encrypt ElGamal key.
+When a subkey or user ID is generated it is self-signed using your 
+master signing key, which is why you must supply your passphrase
+when the key is generated.
+</para>
+
+<para>
+Additional user IDs are useful when you need multiple identities.
+For example, you may have an identity for your job and an identity
+for your work as a political activist.
+Coworkers will know you by your work user ID.
+Coactivists will know you by your activist user ID.
+Since those groups of people may not overlap, though, each group
+may not trust the other user ID.
+Both user IDs are therefore necessary.
+</para>
+
+<para>
+Additional subkeys are also useful.
+The user IDs associated with your public master key are validated by
+the people with whom you
+communicate, and changing the master key therefore requires recertification.
+This may be difficult and time consuming if you communicate with
+many people.
+On the other hand, it is good to periodically change encryption subkeys.
+If a key is broken, all the data encrypted with that key will be
+vulnerable.
+By changing keys, however, only the data encrypted with the one broken
+key will be revealed.
+</para>
+
+<para>
+Subkeys and user IDs may also be deleted.
+To delete a subkey or user ID you must first select it using the
+<link linkend="key"><command>key</command></link> or 
+<link linkend="uid"><command>uid</command></link> commands respectively.
+These commands are toggles.
+For example, the command <command>key <parameter>2</parameter></command> 
+selects the second subkey,
+and invoking <command>key <parameter>2</parameter></command> again 
+deselects it.
+If no extra argument is given, all subkeys or user IDs are deselected.
+Once the user IDs to be deleted are selected, the command
+<link linkend="deluid"><command>deluid</command></link>
+actually deletes the user IDs from your key.
+Similarly, the command <link linkend="delkey"><command>delkey</command></link>
+deletes all selected subkeys from both your public and private keys.
+</para>
+
+<para>
+For local keyring management, deleting key components is a good way
+to trim other people's public keys of unnecessary material.
+Deleting user IDs and subkeys on your own key, however, is not always
+wise since it complicates key distribution.
+By default, when a user imports your updated public key it will be merged
+with the old copy of your public key on his ring if it exists.
+The components from both keys are combined in the merge, and this
+effectively restores any components you deleted.
+To properly update the key, the user must first delete the old version
+of your key and then import the new version.
+This puts an extra burden on the people with whom you communicate.
+Furthermore, if you send your key to a keyserver, the merge will
+happen regardless, and anybody who downloads your key from a keyserver
+will never see your key with components deleted.
+Consequently, for updating your own key it is better to revoke key
+components instead of deleting them.
+</para>
+</sect2>
+
+<sect2>
+<title>
+Revoking key components
+</title>
+
+<para>
+To revoke a subkey it must be selected.
+Once selected it may be revoked with the 
+<link linkend="revkey"><command>revkey</command></link> command.
+The key is revoked by adding a revocation self-signature to the key.
+Unlike the command-line option <option>--gen-revoke</option>, the effect of
+revoking a subkey is immediate.
+</para>
+
+<screen width="80">
+<prompt>Command></prompt> <userinput>revkey</userinput>
+Do you really want to revoke this key? y
+                                        
+You need a passphrase to unlock the secret key for
+user: "Chloe (Jester) &lt;chloe@cyb.org>"
+1024-bit DSA key, ID B87DBA93, created 1999-06-28
+
+                  
+pub  1024D/B87DBA93  created: 1999-06-28 expires: never      trust: -/u
+sub  2048g/B7934539  created: 1999-06-28 expires: never     
+sub  1792G/4E3160AD  created: 1999-06-29 expires: 2000-06-28
+rev! subkey has been revoked: 1999-06-29
+sub   960D/E1F56448  created: 1999-06-29 expires: 2000-06-28
+(1)  Chloe (Jester) &lt;chloe@cyb.org>
+(2)  Chloe (Plebian) &lt;chloe@tel.net>
+</screen>
+
+<para>
+A user ID is revoked differently.
+Normally, a user ID collects signatures that attest that the user ID
+describes the person who actually owns the associated key.
+In theory, a user ID describes a person forever, since that person will
+never change.
+In practice, though, elements of the user ID such as the email address
+and comment may change over time, thus invalidating the user ID.
+</para>
+
+<para>
+The OpenPGP
+<comment>First reference to OpenPGP</comment>
+specification does not support user ID revocation, but
+a user ID can effectively be revoked by revoking the self-signature
+on the user ID.
+For the security reasons described 
+<link linkend="integrity">previously</link>,
+correspondents will not trust a user ID with no valid self-signature.
+</para>
+
+<para>
+A signature is revoked by using the command 
+<link linkend="revsig"><command>revsig</command></link>.
+Since you may have signed any number of user IDs, the user interface
+prompts you to decide for each signature whether or not to revoke it.
+</para>
+
+<screen width="80">
+<prompt>Command></prompt> <userinput>revsig</userinput>
+You have signed these user IDs:
+     Chloe (Jester) &lt;chloe@cyb.org>
+   signed by B87DBA93 at 1999-06-28
+     Chloe (Plebian) &lt;chloe@tel.net>
+   signed by B87DBA93 at 1999-06-28
+user ID: "Chloe (Jester) &lt;chloe@cyb.org>"
+signed with your key B87DBA93 at 1999-06-28
+Create a revocation certificate for this signature? (y/N)n
+user ID: "Chloe (Plebian) &lt;chloe@tel.net>"                
+signed with your key B87DBA93 at 1999-06-28
+Create a revocation certificate for this signature? (y/N)y
+You are about to revoke these signatures:                 
+     Chloe (Plebian) &lt;chloe@tel.net>
+   signed by B87DBA93 at 1999-06-28
+Really create the revocation certificates? (y/N)y
+                                                 
+You need a passphrase to unlock the secret key for
+user: "Chloe (Jester) &lt;chloe@cyb.org>"
+1024-bit DSA key, ID B87DBA93, created 1999-06-28
+
+                  
+pub  1024D/B87DBA93  created: 1999-06-28 expires: never      trust: -/u
+sub  2048g/B7934539  created: 1999-06-28 expires: never     
+sub  1792G/4E3160AD  created: 1999-06-29 expires: 2000-06-28
+rev! subkey has been revoked: 1999-06-29
+sub   960D/E1F56448  created: 1999-06-29 expires: 2000-06-28
+(1)  Chloe (Jester) &lt;chloe@cyb.org>
+(2)  Chloe (Plebian) &lt;chloe@tel.net>
+</screen>
+
+<para>
+A revoked user ID is indicated by the revocation signature on 
+the ID when the signatures on the key's user IDs are listed.
+</para>
+
+<screen width="80">
+<prompt>Command></prompt> <userinput>check</userinput>
+uid  Chloe (Jester) &lt;chloe@cyb.org>
+sig!       B87DBA93 1999-06-28   [self-signature]
+uid  Chloe (Plebian) &lt;chloe@tel.net>
+rev!       B87DBA93 1999-06-29   [revocation]
+sig!       B87DBA93 1999-06-28   [self-signature]
+</screen>
+
+<para>
+Revoking both subkeys and self-signatures on user IDs adds revocation
+self-signatures to the key.
+Since signatures are being added and no material is deleted, a 
+revocation will always be visible to others when your updated public
+key is distributed and merged with older copies of it.
+Revocation therefore guarantees that everybody has a consistent
+copy of your public key.
+</para>
+</sect2>
+
+<sect2>
+<title>
+Updating a key's expiration time
+</title>
+
+<para>
+The expiration time of a key may be updated with the command
+<link linkend="expire"><command>expire</command></link> from the key edit menu.
+If no key is selected the expiration time of the primary key
+is updated.
+Otherwise the expiration time of the selected subordinate key
+is updated.
+</para>
+
+<para>
+A key's expiration time is associated with the key's self-signature.
+The expiration time is updated by deleting the old self-signature
+and adding a new self-signature.
+Since correspondents will not have deleted the old self-signature, they
+will see an additional self-signature on the key when they update
+their copy of your key.
+The latest self-signature takes precedence, however, so all correspondents
+will unambiguously know the expiration times of your keys.
+</para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>
+Validating other keys on your public keyring
+</title>
+
+<para>
+In Chapter <xref linkend="intro"> a procedure was given to validate your
+correspondents' public keys: a correspondent's key is validated by
+personally checking his key's fingerprint and then signing his public
+key with your private key.
+By personally checking the fingerprint you can be sure that the
+key really does belong to him, and since you have signed they key, you
+can be sure to detect any tampering with it in the future.
+Unfortunately, this procedure is awkward when either you must validate
+a large number of keys or communicate with people whom you do not
+know personally.
+</para>
+
+<para>
+&Gnupg; addresses this problem with a mechanism popularly known
+as the <firstterm>web of trust</firstterm>.
+In the web of trust model, responsibility for validating public
+keys is delegated to people you trust.
+For example, suppose
+<itemizedlist spacing="compact">
+<listitem>
+<para>
+Alice has signed Blake's key, and
+</para>
+</listitem>
+<listitem>
+<para>
+Blake has signed Chloe's key and Dharma's key.
+</para>
+</listitem>
+</itemizedlist>
+
+If Alice trusts Blake to properly validate keys that he signs, then
+Alice can infer that Chloe's and Dharma's keys are valid without 
+having to personally check them.
+She simply uses her validated copy of Blake's public key to
+check that Blake's signatures on Chloe's and Dharma's are good.
+In general, assuming that Alice fully trusts everybody to properly
+validate keys they sign, then any key signed by a valid key is also
+considered valid.
+The root is Alice's key, which is axiomatically assumed to be valid.
+</para>
+
+<sect2>
+<title>
+Trust in a key's owner
+</title>
+
+<para>
+In practice trust is subjective.
+For example, Blake's key is valid to Alice since she signed it, but she
+may not trust Blake to properly validate keys that he signs.
+In that case, she would not take Chloe's and Dharma's key as valid
+based on Blake's signatures alone.
+The web of trust model accounts for this by associating with each
+public key on your keyring an indication of how much you trust the
+key's owner.
+There are four trust levels.
+
+<variablelist>
+<varlistentry>
+<term>
+unknown
+</term>
+<listitem>
+<para>
+Nothing is known about the owner's judgement in key signing.
+Keys on your public keyring that you do not own initially have
+this trust level.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+none
+</term>
+<listitem>
+<para>
+The owner is known to improperly sign other keys.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+marginal
+</term>
+<listitem>
+<para>
+The owner understands the implications of key signing and 
+properly validates keys before signing them.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+full
+</term>
+<listitem>
+<para>
+The owner has an excellent understanding of key signing,
+and his signature on a key would be as good as your own.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+A key's trust level is something that you alone assign to the
+key, and it is considered private information.
+It is not packaged with the key when it is exported; it is even
+stored separately from your keyrings in a separate database.
+</para>
+
+<para>
+The &gnupg; key editor may be used to adjust your trust in a key's owner.
+The command is <link linkend="trust"><command>trust</command></link>.
+In this example Alice edits her trust in Blake and then updates
+the trust database to recompute which keys are valid based on her new
+trust in Blake.
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --edit-key blake</userinput>
+
+pub  1024D/8B927C8A  created: 1999-07-02 expires: never      trust: q/f
+sub  1024g/C19EA233  created: 1999-07-02 expires: never     
+(1)  Blake (Executioner) &lt;blake@cyb.org>
+
+<prompt>Command></prompt> <userinput>trust</userinput>
+pub  1024D/8B927C8A  created: 1999-07-02 expires: never      trust: q/f
+sub  1024g/C19EA233  created: 1999-07-02 expires: never     
+(1)  Blake (Executioner) &lt;blake@cyb.org>
+
+Please decide how far you trust this user to correctly
+verify other users' keys (by looking at passports,
+checking fingerprints from different sources...)?
+
+ 1 = Don't know
+ 2 = I do NOT trust
+ 3 = I trust marginally
+ 4 = I trust fully
+ s = please show me more information
+ m = back to the main menu
+
+<prompt>Your decision?</prompt> <userinput>3</userinput>
+                
+pub  1024D/8B927C8A  created: 1999-07-02 expires: never      trust: m/f
+sub  1024g/C19EA233  created: 1999-07-02 expires: never     
+(1)  Blake (Executioner) &lt;blake@cyb.org>
+
+<prompt>Command></prompt> <userinput>quit</userinput>
+[...]
+</screen>
+
+Trust in the key's owner and the key's validity are indicated to the
+right when the key is displayed.
+Trust in the owner is displayed first and the key's validity is 
+<!-- HERE, need to fix quotation marks -->
+second<footnote>
+<para>
+&Gnupg; overloads the word "trust" by using it to mean
+trust in an owner and trust in a key.
+This can be confusing.
+Sometimes trust in an owner is referred to as
+<firstterm>owner-trust</firstterm> to
+distinguish it from trust in a key.
+<!-- HERE, need to fix quotation marks -->
+Throughout this manual, however, "trust" is used to 
+mean trust in a key's
+<!-- HERE, need to fix quotation marks -->
+owner, and "validity" is used to mean trust that a key 
+belongs to the human associated with the key ID.
+</para>
+</footnote>.
+The four trust/validity levels are abbreviated: unknown (<literal>q</literal>),
+none (<literal>n</literal>), marginal (<literal>m</literal>), and 
+full (<literal>f</literal>).
+In this case, Blake's key is fully valid since Alice signed it herself.
+She initially has an unknown trust in Blake to properly sign other keys
+but decides to trust him marginally.
+</para>
+</sect2>
+
+<sect2>
+<title>
+Using trust to validate keys
+</title>
+
+<para>
+The web of trust allows a more elaborate algorithm to be used to
+validate a key.
+Formerly, a key was considered valid only if you signed it personally.
+<!-- HERE, math -->
+A more flexible algorithm can now be used: a key <emphasis>K</emphasis> is considered valid
+if it meets two conditions:
+<orderedlist spacing="compact">
+<listitem>
+<para>
+it is signed by enough valid keys, meaning
+<itemizedlist spacing="compact">
+<listitem>
+<para>
+you have signed it personally, 
+</para>
+</listitem>
+<listitem>
+<para>
+it has been signed by one fully trusted key, or
+</para>
+</listitem>
+<listitem>
+<para>
+it has been signed by three marginally trusted keys; and
+</para>
+</listitem>
+</itemizedlist>
+</para>
+</listitem>
+<listitem>
+<para>
+<!-- HERE, math -->
+the path of signed keys leading from <emphasis>K</emphasis> back 
+to your own key is five steps or shorter.
+</para>
+</listitem>
+</orderedlist>
+
+The path length, number of marginally trusted keys required, and number
+of fully trusted keys required may be adjusted.
+The numbers given above are the default values used by &gnupg;.
+</para>
+
+<para>
+<xref linkend="wot-examples"> shows a web of trust rooted at Alice.
+The graph illustrates who has signed who's keys.
+The table shows which keys Alice considers valid based on her
+trust in the other members of the web.
+<comment>Potential bug: <option>--completes-needed</option> on command 
+line seems to be ignored when combined with <option>--update-trustdb</option>.
+Value is taken correctly if put in options file, however.</comment>
+This example assumes that two marginally-trusted keys or one
+fully-trusted key is needed to validate another key.
+The maximum path length is three.
+</para>
+
+<para>
+When computing valid keys in the example, Blake and Dharma's are
+always considered fully valid since they were signed directly
+by Alice.
+The validity of the other keys depends on trust.
+In the first case, Dharma is trusted fully, which implies 
+that Chloe's and Francis's keys will be considered valid.
+In the second example, Blake and Dharma are trusted marginally.
+Since two marginally trusted keys are needed to fully validate a
+key, Chloe's key will be considered fully valid, but Francis's 
+key will be considered only marginally valid.
+In the case where Chloe and Dharma are marginally trusted,
+Chloe's key will be marginally valid since Dharma's key is
+fully valid.
+Francis's key, however, will also be considered marginally
+valid since only a fully valid key can be used to validate
+other keys, and Dharma's key is the only fully valid key
+that has been used to sign Francis's key.
+When marginal trust in Blake is added, Chloe's key becomes
+fully valid and can then be used to fully validate Francis's
+key and marginally validate Elena's key.
+Lastly, when Blake, Chloe, and Elena are fully trusted, this is
+still insufficient to validate Geoff's key since the maximum
+certification path is three, but the path length from Geoff
+back to Alice is four.
+</para>
+
+<para>
+The web of trust model is a flexible approach to the problem of safe
+public key exchange.
+It permits you to tune &gnupg; to reflect how you use it.
+At one extreme you may insist on multiple, short paths from your
+<!-- HERE, math -->
+key to another key <emphasis>K</emphasis> in order to trust it.
+On the other hand, you may be satisfied with longer paths and
+<!-- HERE, math -->
+perhaps as little as one path from your key to the other 
+key <emphasis>K</emphasis>.
+<!-- HERE, math -->
+Requiring multiple, short paths is a strong guarantee 
+that <emphasis>K</emphasis> belongs to whom your think it does.
+The price, of course, is that it is more difficult to validate keys
+since you must personally sign more keys than if you accepted fewer
+and longer paths.
+</para>
+
+<figure id="wot-examples" float=1>
+<title>
+A hypothetical web of trust
+</title>
+<!--
+The graph indicates who has signed who's keys.
+The table, in which names have been abbreviated, shows which keys are 
+valid depending on how Alice trusts other members in the web.
+Alice considers different keys valid depending on how she trusts
+the members of the web.
+-->
+
+<graphic fileref="signatures.jpg"></graphic>
+
+<informaltable frame="all">
+<tgroup cols="4" rowsep="1" colsep="1">
+<colspec colname="one" colnum="1">
+<colspec colname="two" colnum="2">
+<colspec colname="three" colnum="3">
+<colspec colname="four" colnum="4">
+<spanspec spanname="lefthalf" namest="one" nameend="two" align="center">
+<spanspec spanname="righthalf" namest="three" nameend="four" align="center">
+
+<thead>
+<colspec
+<row>
+<entry spanname="lefthalf">trust</entry>
+<entry spanname="righthalf">validity</entry>
+</row>
+<row>
+<entry align="center">marginal</entry>
+<entry align="center">full</entry>
+<entry align="center">marginal</entry>
+<entry align="center">full</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry></entry>
+<entry>Dharma</entry>
+<entry></entry>
+<entry>Blake, Chloe, Dharma, Francis</entry>
+</row>
+
+<row>
+<entry>Blake, Dharma</entry>
+<entry></entry>
+<entry>Francis</entry>
+<entry>Blake, Chloe, Dharma</entry>
+</row>
+
+<row>
+<entry>Chloe, Dharma</entry>
+<entry></entry>
+<entry>Chloe, Francis</entry>
+<entry>Blake, Dharma</entry>
+</row>
+
+<row>
+<entry>Blake, Chloe, Dharma</entry>
+<entry></entry>
+<entry>Elena</entry>
+<entry>Blake, Chloe, Dharma, Francis</entry>
+</row>
+
+<row>
+<entry></entry>
+<entry>Blake, Chloe, Elena</entry>
+<entry></entry>
+<entry>Blake, Chloe, Elena, Francis</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+</figure>
+</sect2>
+</sect1>
+
+<sect1>
+<title>
+Distributing keys
+</title>
+
+<para>
+Ideally, you distribute your key by personally giving it to your
+correspondents.
+In practice, however, keys are often distributed by email or some
+other electronic communication medium.
+Distribution by email is good practice when you have only a few
+correspondents, and even if you have many correspondents, you can use
+an alternative means such as posting your public key on your World Wide
+Web homepage.
+This is unacceptable, however, if people who need your public key do
+not know where to find it on the Web.
+</para>
+
+<para>
+To solve this problem public key servers are used to collect
+and distribute public keys.
+A public key received by the server is either added to the server's
+database or merged with the existing key if already present.
+When a key request comes to the server, the server consults its
+database and returns the requested public key if found.
+</para>
+
+<para>
+A keyserver is also valuable when many people are frequently signing other
+people's keys.
+Without a keyserver, when Blake sign's Alice's key then Blake would send
+Alice a copy of her public key signed by him so that Alice could
+add the updated key to her ring as well as distribute it to all of her
+correspondents.
+Going through this effort fulfills Alice's and Blake's responsibility 
+to the community at large in building tight webs of trust and thus
+improving the security of PGP.
+It is nevertheless a nuisance if key signing is frequent.
+</para>
+
+<para>
+Using a keyserver makes the process somewhat easier.
+When Blake signs Alice's key he sends the signed key to the key server.
+The key server adds Blake's signature to its copy of Alice's key.
+Individuals interested in updating their copy of Alice's key then consult
+the keyserver on their own initiative to retrieve the updated key.
+Alice need never be involved with distribution and can retrieve signatures
+on her key simply by querying a keyserver.
+<comment><option>--keyserver</option> must come before
+<option>--send-key</option> or <option>--recv-key</option>.  
+This appears to be a bug.</comment>
+</para>
+
+<para>
+One or more keys may be sent to a keyserver using the command-line
+option <link linkend="send-keys"><option>--send-keys</option></link>.
+The option takes one or more key specifiers and sends the specified
+keys to the key server.
+The key server to which to send the keys is specified with the
+command-line option <link linkend="keyserver"><option>--keyserver</option></link>.
+Similarly, the option 
+<link linkend="recv-keys"><option>--recv-keys</option></link> is used 
+to retrieve keys from a keyserver, but the option <option>--recv-keys</option>
+requires a key ID be used to specify the key.
+In the following example Alice sends her public key to the keyserver
+<parameter>certserver.pgp.com</parameter> and then updates her copy 
+of Blake's key from the same keyserver.
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --keyserver certserver.pgp.com --recv-key 0xBB7576AC</userinput>
+gpg: requesting key BB7576AC from certserver.pgp.com ...
+gpg: key BB7576AC: 1 new signature
+
+gpg: Total number processed: 1
+gpg:         new signatures: 1
+<prompt>alice%</prompt> <userinput>gpg --keyserver certserver.pgp.com --send-key blake@cyb.org</userinput>
+gpg: success sending to 'certserver.pgp.com' (status=200)
+</screen>
+
+There are several popular keyservers in use around the world.
+The major keyservers synchronize themselves, so it is fine to
+pick a keyserver close to you on the Internet and then use it
+regularly for sending and receiving keys.
+</para>
+</sect1>
+
+</chapter>
+
diff --git a/doc/gph/c4.sgml b/doc/gph/c4.sgml
new file mode 100644
index 000000000..1932da7ae
--- /dev/null
+++ b/doc/gph/c4.sgml
@@ -0,0 +1,433 @@
+<chapter id="wise" xreflabel="4">
+<docinfo>
+<date>
+$Id$
+</date>
+</docinfo>
+<title>
+Daily use of &Gnupg;
+</title>
+
+<para>
+&Gnupg; is a complex tool with technical, social, and legal issues
+surrounding it.
+Technically, it has been designed to be used in situations having
+drastically different security needs.
+This complicates key management.
+Socially, using &gnupg; is not strictly a personal decision.
+To use &gnupg effectively both parties communicating must use it.
+Finally, as of 1999, laws regarding digital encryption, and in particular
+whether or not using &gnupg; is legal, vary from country to country and 
+is currently being debated by many national governments.
+</para>
+
+<para>
+This chapter addresses these issues.
+It gives practical advice on how to use &gnupg; to meet your security needs.
+It also suggests ways to promote the use of &gnupg; for secure
+communication between yourself and your colleagues when your colleagues
+are not currently using &gnupg;.
+Finally, the legal status of &gnupg; is outlined given the current status
+of encryption laws in the world.
+</para>
+
+<sect1>
+<title>
+Defining your security needs
+</title>
+
+<para>
+&Gnupg; is a tool you use to protect your privacy.
+Your privacy is protected if you can correspond with others without
+eavesdroppers reading those messages.
+</para>
+
+<para>
+How you should use &gnupg; depends on the determination and resourcefulness
+of those who might want to read your encrypted messages.
+An eavesdropper may be an unscrupulous system administrator casually
+scanning your mail, it might be an industrial spy trying to collect
+your company's secrets, or it might be a law enforcement agency trying
+to prosecute you.
+Using &gnupg; to protect against casual eavesdropping is going to be
+different than using &gnupg; to protect against a determined adversary.
+Your goal, ultimately, is to make it more expensive to recover the
+unencrypted data than that data is worth.
+</para>
+
+<para>
+Customizing your use of &gnupg; revolves around three issues:
+<itemizedlist spacing="compact">
+<listitem>
+<para>
+the key size of your public/private keypair,
+</para>
+</listitem>
+
+<listitem>
+<para>
+protecting your private key, and
+</para>
+</listitem>
+
+<listitem>
+<para>
+managing your web of trust.
+</para>
+</listitem>
+</itemizedlist>
+
+A well-chosen key size protects you against brute-force attacks on
+encrypted messages.
+Protecting your private key prevents an attacker from simply using your
+private key to decrypt encrypted messages and sign messages in your name.
+Correctly managing your web of trust prevents attackers from masquarading
+as people with whom you communicate.
+Ultimately, addressing these issues with respect to your own security
+needs is how you balance the extra work required to use &gnupg; with
+the privacy it gives you.
+</para>
+
+<sect2>
+<title>
+Choosing a key size
+</title>
+
+<para>
+Selecting a key size depends on the key.
+In OpenPGP, a public/private keypair usually has multiple keys.
+At the least it has a master signing key, and it probably has one or
+more additional subkeys for encryption.
+Using default key generation parameters with &gnupg;, the master
+key will be a DSA key, and the subkeys will be ElGamal keys.
+</para>
+
+<para>
+DSA allows a key size up to 1024 bits.
+This is not especially good given today's factoring technology, but
+that is what the standard specifies.
+Without question, you should use 1024 bit DSA keys.
+</para>
+
+<para>
+ElGamal keys, on the other hand, may be of any size.
+Since &gnupg; is a hybrid public-key system, the public key is used
+to encrypt a 128-bit session key, and the private key is used to
+decrypt it.
+Key size nevertheless affects encryption and decryption speed
+since the cost of these algorithms is exponential in the size of
+the key.
+Larger keys also take more time to generate and take more space
+to store.
+Ultimately, there are diminishing returns on the extra security
+a large key provides you.
+After all, if the key is large enough to resist a brute-force
+attack, an eavesdropper will merely switch to some other method for
+obtaining your plaintext data.
+Examples of other methods include robbing your home or office
+and mugging you.
+1024 bits is thus the recommended key size.
+If you genuinely need a larger key size then you probably already
+know this and should be consulting an expert in data security.
+</para>
+</sect2>
+
+<sect2>
+<title>
+Protecting your private key
+</title>
+
+<para>
+Protecting your private key is the most important job you have to
+use &gnupg; correctly.
+If someone obtains your private key, then all data encrypted to
+the private key can be decrypted and signatures can be made in your name.
+If you lose your private key, then you will no longer be able to 
+decrypt documents encrypted to you in the future or in the past,
+and you will not be able to make signatures.
+Losing sole possession of your private key is catastrophic.
+</para>
+
+<para>
+Regardless of how you use &gnupg; you should store the public
+key's <link linkend="revocation">revocation certificate</link> 
+and a backup of your private key on write-protected media in a safe place.
+For example, you could burn them on a CD-ROM and store them in your
+safe deposit box at the bank in a sealed envelope.
+Alternatively, you could store them on a floppy and hide it in your
+house.
+Whatever you do, they should be put on media that is safe to store
+for as long as you expect to keep the key, and you should store
+them more carefully than the copy of your private key you use daily.
+</para>
+
+<para>
+To help safeguard your key, &Gnupg; does not store your raw
+private key on disk.
+Instead it encrypts it using a symmetric encryption algorithm.
+That is why you need a passphrase to access the key.
+Thus there are two barriers an attacker must cross to access your private
+key: (1) he must actually acquire the key, and (2) he must get past
+the encryption.
+</para>
+
+<para>
+Safely storing your private key is important, but there is a cost.
+Ideally, you would keep the private key on a removable, write-protected disk
+such as a floppy disk, and you would use it on a single-user machine 
+not connected to a network.
+This may be inconvenient or impossible for you to do.
+For example, you may not own your own machine and must use a computer 
+at work or school, or it may mean you have to physically disconnect
+your computer from your cable modem every time you want to use &gnupg;
+</para>
+
+<para>
+This does not mean you cannot or should not use &gnupg;.
+It means only that you have decided that the data you are protecting is
+important enough to encrypt but not so important as to take extra
+steps to make the first barrier stronger.
+It is your choice.
+</para>
+
+<para>
+A good passphrase is absolutely critical when using &gnupg;.
+Any attacker who gains access to your private key must bypass the 
+encryption on the private key.
+Instead of brute-force guessing the key, an attacker will almost
+certainly instead try to guess the passphrase.
+</para>
+
+<para>
+The motivation for trying passphrases is that most people choose
+a passphrase that is easier to guess than a random 128-bit key.
+If the passphrase is a word, it is much cheaper to try all the
+words in the dictionaries of the world's languages.
+Even if the word is permuted, &eg, k3wldood, it is still easier
+to try dictionary words with a catalog of permutations.
+The same problem applies to quotations.
+In general, passphrases based on natural-language utterances
+are poor passphrases since there is little randomness and lots
+of redundancy in natural language.
+You should avoid natural language passphrases if you can.
+</para>
+
+<para>
+A good passphrase is one that you can remember but is hard for
+someone to guess.
+It should include characters from the whole range of printable characters
+on your keyboard.
+This includes uppercase alphabetics characters, numbers, and special
+characters such as <literal>}</literal> and <literal>|</literal>.
+Be creative and spend a little time considering your passphrase; a
+good choice is important to ensure your privacy.
+</para>
+</sect2>
+
+<!--
+<sect2>
+<title>
+Reacting to a compromised private key
+</title>
+
+<para>
+Despite your precautions you may lose sole access to your private key.
+For example, you may forget the passphrase, or someone who you think 
+can bypass the encryption gets access to it.
+In that case then you need to spread the word that your key is no 
+longer valid.
+To do that you use the key revocation certificate you should have generated
+when you created the key.
+Importing it onto your public keyring will revoke the public key
+of the keypair you no longer wish to use.
+It is then up to you to distribute the revoked public key to all 
+those who may encrypt documents to you.
+</para>
+
+<para>
+A revoked public key only prevents future use of the private key.
+Others will neither be able to encrypt documents to the key nor will
+they be able to check signatures made with the private key.
+Documents signed in the past can still be checked, however, and
+documents encrypted in the past can still be decrypted.
+</para>
+
+<para>
+It is important that you protect the revocation certificate carefully.
+Anybody can add the certificate to your public key and distribute it,
+and there is no way to revoke a revocation certificate.
+Therefore, you should store the revocation certificate in a safe
+place such as with the backup of your private key.
+</para>
+</sect2>
+-->
+
+<sect2>
+<title>
+Managing your web of trust
+</title>
+
+<para>
+As with protecting your private key, managing your web of trust is
+another aspect of using &gnupg; that requires balancing security against
+ease of use.
+If you are using &gnupg; to protect against casual eavesdropping and
+forgeries then you can afford to be relatively trusting of other
+people's signatures.
+On the other hand, if you are concerned that there may be a determined
+attacker interested in invading your privacy, then
+you should be much less trusting of other signatures and spend more time 
+personally verifying signatures.
+</para>
+
+<para>
+Regardless of your own security needs, through, you should 
+<emphasis>always be careful</emphasis> when signing other keys.
+It is selfish to sign a key with just enough confidence in the key's
+validity to satisfy your own security needs.
+Others, with more stringent security needs, may want to depend on 
+your signature.
+If they cannot depend on you then that weakens the web of trust
+and makes it more difficult for all &gnupg; users to communicate.
+Use the same care in signing keys that you would like others to use when
+you depend on their signatures.
+</para>
+
+<para>
+In practice, managing your web of trust reduces to assigning trust to 
+others and tuning the options 
+<link linkend="marginals-needed"><option>--marginals-needed</option></link>
+and 
+<link linkend="completes-needed"><option>--completes-needed</option></link>.
+Any key you personally sign will be considered valid, but except for small
+groups, it will not be practical to personally sign the key of every person
+with whom you communicate.
+You will therefore have to assign trust to others.
+</para>
+
+<para>
+It is probably wise to be accurate when assigning trust and then
+use the options to tune how careful &gnupg; is with key validation.
+As a concrete example, you may fully trust a few close friends that
+you know are careful with key signing and then marginally
+trust all others on your keyring.
+From there, you may set <option>--completes-needed</option> to
+<literal>1</literal> and <option>--marginals-needed</option> to
+<literal>2</literal>.
+If you are more concerned with security you might choose values of
+<literal>1</literal> and <literal>3</literal> or <literal>2</literal>
+and <literal>3</literal> respectively.
+If you are less concerned with privacy attacks and just want some
+reasonable confidence about validity, set the values to <literal>1</literal>
+and <literal>1</literal>.
+In general, higher numbers for these options imply that more people
+would be needed to conspire against you in order to have a key validated
+that does not actually belong to the person whom you think it does.
+</para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>
+Building your web of trust
+</title>
+
+<para>
+Wanting to use &gnupg; yourself is not enough.
+In order to use to communicate securely with others you must have
+a web of trust.
+At first glance, however, building a web of trust is a daunting task.
+The people with whom you communicate need to use 
+&gnupg;<footnote><para>In this section, &gnupg; refers to the 
+&gnupg; implementation of OpenPGP as well as other implementations 
+such as NAI's PGP product.</para></footnote>, and there needs to be enough 
+key signing so that keys can be considered valid.
+These are not technical problems; they are social problems.
+Nevertheless, you must overcome these problems if you want to 
+use &gnupg;.
+</para>
+
+<para>
+When getting started using &gnupg; it is important to realize that you
+need not securely communicate with every one of your correspondents.
+Start with a small circle of people, perhaps just yourself and
+one or two others who also want to exercise their right
+to privacy.
+Generate your keys and sign each other's public keys.
+This is your initial web of trust.
+By doing this you will appreciate the value of a small, robust
+web of trust and will be more cautious as you grow your web
+in the future.
+</para>
+
+<para>
+In addition to those in your initial web of trust, you may want to
+communicate securely with others who are also using &gnupg;.
+Doing so, however, can be awkward for two reasons:
+(1) you do not always know when someone uses or is willing to use
+&gnupg;, and (2) if you do know of someone who uses it, you may still have
+trouble validating their key.
+The first reason occurs because people do not always advertise that
+they use &gnupg;.
+The way to change this behavior is to set the example and advertise 
+that you use &gnupg;.
+There are at least three ways to do this: you can sign messages you mail
+to others or post to message boards, you can put your public key on your
+web page, or, if you put your key on a keyserver, you can put your key
+ID in your email signature.
+If you advertise your key then you make it that much more acceptable
+for others to advertise their keys.
+Furthermore, you make it easier for others to start communicating
+with you securely since you have taken the initiative and made it clear
+that you use &gnupg;.
+</para>
+
+<para>
+Key validation is more difficult.
+If you do not personally know the person whose key you want to sign,
+then it is not possible to sign the key yourself.
+You must rely on the signatures of others and hope to find a chain
+of signatures leading from the key in question back to your own.
+To have any chance of finding a chain, you must take the intitive
+and get your key signed by others outside of your intitial web of trust.
+An effective way to accomplish this is to participate in key
+signing parties.
+If you are going to a conference look ahead of time for a key
+signing party, and if you do not see one being held, offer to 
+<ulink url="http://www.herrons.com/kb2nsx/keysign.html">hold one</ulink>.
+You can also be more passive and carry your fingerprint with you
+for impromptu key exchanges.
+In such a situation the person to whom you gave the fingerprint
+would verify it and sign your public key once he returned home.
+</para>
+
+<para>
+Keep in mind, though, that this is optional.
+You have no obligation to either publically advertise your key or
+sign other people's keys.
+The power of &gnupg; is that it is flexible enough to adapt to your
+security needs whatever they may be.
+The social reality, however, is that you will need to take the initiative
+if you want to grow your web of trust and use &gnupg; for as much of 
+your communication as possible.
+</para>
+</sect1>
+
+<sect1>
+<title>
+Using &Gnupg; legally
+</title>
+
+<para>
+The legal status of encryption software varies from country to country,
+and law regarding encryption software is rapidly evolving.
+<ulink url="http://cwis.kub.nl/~frw/people/koops/bertjaap.htm">Bert-Japp 
+Koops</ulink> has an excellent 
+<ulink url="http://cwis.kub.nl/~frw/people/koops/lawsurvy.htm">Crypto
+Law Survey</ulink> to which you should refer for the legal status of
+encryption software in your country.
+</para>
+
+</sect1>
+</chapter>
+
diff --git a/doc/gph/c5.sgml b/doc/gph/c5.sgml
new file mode 100644
index 000000000..b847e5853
--- /dev/null
+++ b/doc/gph/c5.sgml
@@ -0,0 +1,38 @@
+<chapter id="Modules" xreflabel="5">
+<docinfo>
+<date>
+$Id$
+</date>
+</docinfo>
+<title>
+Programming with &Gnupg;
+</title>
+
+<para>...</para>
+
+<sect1>
+<title>
+Using &gpg in batch mode
+</title>
+
+<para>...</para>
+
+<sect2>
+<title>
+Invoking &gpg from mail clients
+</title>
+
+<para>...</para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>
+Writing extension modules
+</title>
+
+<para>...</para>
+</sect1>
+
+</chapter>
+
diff --git a/doc/gph/c6.sgml b/doc/gph/c6.sgml
new file mode 100644
index 000000000..1b82a8c9a
--- /dev/null
+++ b/doc/gph/c6.sgml
@@ -0,0 +1,804 @@
+<reference>
+<docinfo>
+<date>
+$Id$
+</date>
+</docinfo>
+<title>
+Command Reference
+</title>
+
+<partintro>
+<sect1>
+<title>
+Key specifiers
+</title>
+
+<para>
+Many commands and options require a <firstterm>key specifier</firstterm>.
+A key specifier is the key ID or any portion of ther user ID of
+a key.
+Consider the following example.
+
+<screen width="80">
+<prompt>alice%</prompt> <userinput>gpg --list-keys chloe</userinput>
+pub  1024D/B87DBA93 1999-06-28 Chloe (Jester) &lt;chloe@cyb.org>
+uid                            Chloe (Plebian) &lt;chloe@tel.net>
+sub  2048g/B7934539 1999-06-28
+</screen>
+
+For this key, <literal>0xB87DBA93</literal>,
+<literal>Chloe</literal>,
+<literal>Plebian</literal>, and
+<literal>oe@tel</literal>
+are all examples of key specifiers that match the above key.
+</para>
+</sect1>
+</partintro>
+
+<refentry id="send-keys">
+<refnamediv>
+<refname>
+send-keys
+</refname>
+<refpurpose>
+send keys to a key server
+</refpurpose>
+
+
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+send-keys <replaceable class="parameter">key</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command sends a public key to a keyserver.  
+The parameter <replaceable class="parameter">key</replaceable> specifies 
+the public key that should be uploaded.
+The command requires the option
+<link linkend="keyserver"><option>keyserver</option></link> to specify
+to which keyserver &gpg; should send the keys.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="recv-keys">
+<refnamediv>
+<refname>
+recv-keys
+</refname>
+<refpurpose>
+retrieve keys from a key server
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>recv-keys</option> <replaceable class="parameter">key-id key-id ...</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command downloads one or more public keys from a keyserver.  
+Each <replaceable class="parameter">key-id</replaceable> is a key ID.
+The command requires the option
+<link linkend="keyserver"><option>keyserver</option></link> to 
+specify from which keyserver &gpg; should download the keys.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="encrypt">
+<refnamediv>
+<refname>
+encrypt
+</refname>
+<refpurpose>
+encrypt a document
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>encrypt</option> <replaceable class="parameter">filename</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command encrypts the document 
+<replaceable class="parameter">filename</replaceable> to
+recipients specified using the 
+option <link linkend="recipient"><option>recipient</option></link>.
+If the parameter <replaceable class="parameter">filename</replaceable>
+is omitted, then the document to encrypt is taken from standard input.
+If the option <option>recipient</option> is omitted,
+&gpg; will prompt for a recipient.
+If the option <link linkend="output"><option>output</option></link> is used,
+&gpg; will output the encrypted information to the specified file.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="decrypt">
+<refnamediv>
+<refname>
+decrypt
+</refname>
+<refpurpose>
+decrypt an encrypted document
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>decrypt</option> <replaceable class="parameter">filename</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command decrypts <replaceable class="parameter">filename</replaceable>
+and puts the result on standard output.
+If the parameter <replaceable class="parameter">filename</replaceable>
+is omitted, then the document to decrypt is taken from standard input.
+Use the option <link linkend="output"><option>output</option></link>
+to output the decrypted message to a file instead.
+</para>
+</refsect1>
+</refentry>
+
+
+<refentry id="clearsign">
+<refnamediv>
+<refname>
+clearsign
+</refname>
+<refpurpose>
+make a cleartext signature
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>clearsign</option> <replaceable class="parameter">filename</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command signs a message that can be verified to ensure that the 
+original message has not been changed.
+Verification of the signed message is done using the command
+<link linkend="verify"><option>verify</option></link>.
+
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="fingerprint">
+<refnamediv>
+<refname>
+fingerprint
+</refname>
+<refpurpose>
+display key fingerprints
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>fingerprint</option> <replaceable class="parameter">name ...</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command prints the fingerprints of the specified public keys.
+The parameter <replaceable class="parameter">name</replaceable> is a
+key specifier.
+If no parameter <replaceable class="parameter">name</replaceable> is
+provided, &gpg; will print the fingerprints of all the keys on 
+your public keyring.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="detach-sig">
+<refnamediv>
+<refname>
+detach-sig
+</refname>
+<refpurpose>
+make a detached signature
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>detach-sig</option> <replaceable class="parameter">filename</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command creates a signature file that can be used 
+to verify that the orginal file 
+<replaceable class="parameter">filename</replaceable> has not
+been changed.  
+Verification of the file using a detached signature is done using the 
+command <link linkend="verify"><option>verify</option></link>.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="gen-key">
+<refnamediv>
+<refname>
+gen-key
+</refname>
+<refpurpose>
+generate a new keypair
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>gen-key</option>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command generates a private/public key pair for use in encrypting, 
+decrypting, and signing of messages.
+You will br prompted for the kind of key you wish to create, the key 
+size, and the key's expiration date.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="symmetric">
+<refnamediv>
+<refname>
+symmetric
+</refname>
+<refpurpose>
+encrypt a document using only a symmetric encryption algorithm
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>symmetric</option> <replaceable class="parameter">filename</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command encrypts a document using a symmetric algorithm with
+a key derived from a passphrase supplied by you during execution.
+The key should be selected to make it difficult to randomly guess the key.
+To decrypt a document encrypted in this manner use the command.
+<link linkend="decrypt"><option>decrypt</option></link>.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="list-keys">
+<refnamediv>
+<refname>
+list-keys
+</refname>
+<refpurpose>
+list information about the specified keys
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>list-keys</option> <replaceable class="parameter">key ...</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command lists the public key specified by the key specifiers on the
+command line.
+If no key specifier is given, &gpg; will print all of the keys on the 
+public keyring.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="import">
+<refnamediv>
+<refname>
+import
+</refname>
+<refpurpose>
+import keys to a local keyring
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>import</option> <replaceable class="parameter">filename</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command imports one or more public keys onto the user's public 
+keyring from the file <replaceable class="parameter">filename</replaceable>.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="verify">
+<refnamediv>
+<refname>
+verify
+</refname>
+<refpurpose>
+verify a signed document
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>verify</option> <replaceable class="parameter">signature document</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command verifies a document against a signature
+to ensure that the document has not been altered since the signature
+was created.
+If <replaceable class="parameter">signature</replaceable> is omitted,
+&gpg; will look in <replaceable class="parameter">document</replaceable>
+for a clearsign signature.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="gen-revoke">
+<refnamediv>
+<refname>
+gen-revoke
+</refname>
+<refpurpose>
+generate a revocation certificate for a public/private keypair
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>gen-revoke</option> <replaceable class="parameter">key</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command generates a revocation certificate for a public/private 
+key pair.  
+The parameter <replaceable class="parameter">key</replaceable> is 
+a key specifier.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="export">
+<refnamediv>
+<refname>
+export
+</refname>
+<refpurpose>
+export keys from a local keyring
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>export</option> <replaceable class="parameter">key key ...</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command exports the public keys components of the keys specified
+by the key specifiers <replaceable class="parameter">key key ...</replaceable>.
+The export command by default sends its output to standard output.  
+This key file can later be imported into another keyring using the command
+<link linkend="import"><option>import</option></link>.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="edit-key">
+<refnamediv>
+<refname>
+edit-key
+</refname>
+<refpurpose>
+presents a menu for operating on keys
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>edit-key</option> <replaceable class="parameter">key</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This command presents a menu which enables you to perform
+key-related taskes.
+The key specifier <replaceable class="parameter">key</replaceable>
+specifies the key pair to be edited.
+If the specifier matches more than one key pair, &gpg; issues
+an error and exits.
+</para>
+
+<para>
+Key listings displayed during key editing show the key with its
+secondary keys and all user ids.
+Selected keys or user ids are indicated by an asterisk.
+The trust and validity values are displayed with the primary key: 
+the first is the assigned trust and the second is the
+calculated validity.
+Letters are used for the values:
+
+<informaltable>
+<tgroup cols="2" rowsep="1" colsep="1">
+<thead>
+<row>
+<entry>Letter</entry>
+<entry>Meaning</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry>
+-
+</entry>
+<entry>
+No ownertrust assigned / not yet calculated.
+</entry>
+</row>
+<row>
+<entry>
+e
+</entry>
+<entry>
+Trust calculation has failed.
+</entry>
+</row>
+
+<row>
+<entry>
+q
+</entry>
+<entry>
+Not enough information for calculation.
+</entry>
+</row>
+
+<row>
+<entry>
+n
+</entry>
+<entry>
+Never trust this key.
+</entry>
+</row>
+
+<row>
+<entry>
+m
+</entry>
+<entry>
+Marginally trusted.
+</entry>
+</row>
+
+<row>
+<entry>
+f
+</entry>
+<entry>
+Fully trusted.
+</entry>
+</row>
+
+<row>
+<entry>
+u
+</entry>
+<entry>
+Ultimately trusted.
+</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+</para>
+
+<para>
+The following lists each key editing command and a description
+of its behavior.
+</para>
+
+<refsect2 id="sign">
+<title>
+sign
+</title>
+
+<para>
+Makes a signature on the current key.
+If th  key is not yet signed by the default user or the user 
+given with the option
+<link linkend="local-user"><option>local-user</option></link>, 
+the program displays the information of the key again, together with
+its  fingerprint and asks whether it should be signed.
+This question is repeated for all users specified with the option
+<option>local-user</option>.
+</para>
+</refsect2>
+
+<refsect2 id="lsign">
+<title>
+lsign
+</title>
+
+<para>
+Same as <link linkend="sign">sign</link>, but the signature is
+marked as non-exportable and will therefore never be used by others.
+This may be used to make keys valid only in the local environment.
+</para>
+</refsect2>
+
+<refsect2 id="revsig">
+<title>
+revsig
+</title>
+
+<para>
+Revoke a signature.
+Asks for each signature makde by a one of the private keys whether
+a revocation certificate should be generated.
+</para>
+</refsect2>
+
+<refsect2 id="trust">
+<title>
+trust
+</title>
+
+<para>
+Change the owner trust value.
+This updates the trust database immediately and no save is required.
+</para>
+</refsect2>
+
+<refsect2 id="disable">
+<title>
+disable
+</title>
+
+<para>
+Disable the key.
+A disabled key cannot normally be used for encryption.
+</para>
+</refsect2>
+
+<refsect2 id="enable">
+<title>
+enable
+</title>
+
+<para>
+Enable a key that has been previously
+<link linkend="disable">disabled</link>.
+</para>
+</refsect2>
+
+<refsect2 id="adduid">
+<title>
+adduid
+</title>
+
+<para>
+Add a new user id to the current key.
+</para>
+</refsect2>
+
+<refsect2 id="deluid">
+<title>
+deluid
+</title>
+
+<para>
+Delete a user id from the current key.
+</para>
+</refsect2>
+
+<refsect2 id="addkey">
+<title>
+addkey
+</title>
+
+<para>
+Add a new subkey to the current key.
+</para>
+</refsect2>
+
+<refsect2 id="delkey">
+<title>
+delkey
+</title>
+
+<para>
+Delete a subkey from the current key.
+</para>
+</refsect2>
+
+<refsect2 id="revkey">
+<title>
+revkey
+</title>
+
+<para>
+Revoke a subkey of the current key.
+</para>
+</refsect2>
+
+<refsect2 id="expire">
+<title>
+expire
+</title>
+
+<para>
+Change a key expiration time.
+If a subkey is selected, the time of that key will be changed.
+With no selection the expiration time of the current primary key is changed.
+</para>
+</refsect2>
+
+<refsect2 id="key">
+<title>
+key n
+</title>
+
+<para>
+Toggle selection of subkey with index n.
+Use 0 to deselect all.
+</para>
+</refsect2>
+
+<refsect2 id="uid">
+<title>
+uid n
+</title>
+
+<para>
+Toggle selection of user id with index n.
+Use 0 to deselect all.
+</para>
+</refsect2>
+
+<refsect2 id="passwd">
+<title>
+toggle
+</title>
+
+<para>
+Change the passphrase of the private key of the selected key pair.
+</para>
+</refsect2>
+
+<refsect2 id="toggle">
+<title>
+toggle
+</title>
+
+<para>
+Toggle between public and private key listings.
+</para>
+</refsect2>
+
+<refsect2 id="check">
+<title>
+check
+</title>
+
+<para>
+Check all selected user ids.
+</para>
+</refsect2>
+
+<refsect2 id="pref">
+<title>
+pref
+</title>
+
+<para>
+List preferences.
+</para>
+</refsect2>
+
+<refsect2 id="save">
+<title>
+save
+</title>
+
+<para>
+Save all changes to the current key and quit.
+</para>
+</refsect2>
+
+<refsect2 id="quit">
+<title>
+save
+</title>
+
+<para>
+Quit without updating the current key.
+</para>
+</refsect2>
+
+</refsect1>
+</refentry>
+</reference>
diff --git a/doc/gph/c7.sgml b/doc/gph/c7.sgml
new file mode 100644
index 000000000..17f3186f1
--- /dev/null
+++ b/doc/gph/c7.sgml
@@ -0,0 +1,251 @@
+<reference>
+<docinfo>
+<date>
+$Id$
+</date>
+</docinfo>
+<title>
+Options Reference
+</title>
+
+<partintro>
+<sect1 id="optionsfile">
+<title>
+Setting options
+</title>
+
+<para>
+Options may be specified on the command line or in an options file.
+The default location of the options file is
+<literal>~/.gnupg/options</literal>.
+When specifying options in the options file, omit the leading two
+dashes and instead use simply the option name followed by any
+arguments.
+Lines in the file with a hash (<literal>#</literal>) as the 
+first non-white-space character are ignored.
+</para>
+</sect1>
+</partintro>
+
+<refentry id="keyserver">
+<refnamediv>
+<refname>
+keyserver
+</refname>
+<refpurpose>
+specify the keyserver to use to locate keys
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>keyserver</option> <replaceable class="parameter">server-name</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This option is used in conjunction with either 
+<link linkend="recv-keys"><option>recv-keys</option></link> or 
+<link linkend="send-keys"><option>send-keys</option></link> to specify a
+keyserver to manage public key distribution.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="output">
+<refnamediv>
+<refname>
+output
+</refname>
+<refpurpose>
+specify the file in which to place output
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>output</option> <replaceable class="parameter">file-name</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This is a description.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="recipient">
+<refnamediv>
+<refname>
+recipient
+</refname>
+<refpurpose>
+specify the recipient of a public-key encrypted document
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This is a description.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="armor">
+<refnamediv>
+<refname>
+armor
+</refname>
+<refpurpose>
+ASCII-armor encrypted or signed output
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This is a description.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="no-greeting">
+<refnamediv>
+<refname>
+no-greeting
+</refname>
+<refpurpose>
+suppress the opening copyright notice but do not enter batch mode
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+This is a description.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="local-user">
+<refnamediv>
+<refname>
+local-user
+</refname>
+<refpurpose>
+specifies a user id to use for signing
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>localuser</option> <replaceable class="parameter">name</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+Use <replaceable class="parameter">name</replaceable> as the user ID to sign.
+This option is silently ignored for the list commands, so that it can be 
+used in an options file.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="completes-needed">
+<refnamediv>
+<refname>
+completes-needed
+</refname>
+<refpurpose>
+specifies the number of fully-trusted people needed to validate a new key.
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>completes-needed</option> <replaceable class="parameter">n</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+A public key on your keyring is validated using those signatures on
+the key that were made by other valid keys on your keyring.
+The option specifies the number of signatures needed if you fully
+trust the owners of the keys that made the signatures.
+Your trust in a key's owner is set with the command 
+<link linkend="edit-key"><option>edit-key</option></link>.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="marginals-needed">
+<refnamediv>
+<refname>
+marginals-needed
+</refname>
+<refpurpose>
+specifies the number of marginally-trusted people needed to validate
+a new key.
+</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+<option>marginals-needed</option> <replaceable class="parameter">n</replaceable>
+</synopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>
+Description
+</title>
+
+<para>
+A public key on your keyring is validated using those signatures on
+the key that were made by other valid keys on your keyring.
+The option specifies the number of signatures needed if you marginally
+trust the owners of the keys that made the signatures.
+Your trust in a key's owner is set with the command 
+<link linkend="edit-key"><option>edit-key</option></link>.
+</para>
+</refsect1>
+</refentry>
+</reference>
+
diff --git a/doc/gph/manual.sgml b/doc/gph/manual.sgml
new file mode 100644
index 000000000..f573bfd4f
--- /dev/null
+++ b/doc/gph/manual.sgml
@@ -0,0 +1,71 @@
+<!--
+  ToDo
+  - acknowledge Joergen Grahn for his xfig version of Figure 3.1
+  - 'inlineequation' marks places where formatting is ok now but not
+    semantically correct.
+  - need some story for formatting math
+       From Tom Goulet (tomg@iaw.on.ca):
+       > and the <SUP> tag doesn't seem to do much under Lynx, consider just
+       > using a ^ to show powers.
+ -->
+
+<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!--ArborText, Inc., 1988-1995, v.4001-->
+<!NOTATION drw SYSTEM "DRW">
+<!ENTITY gpg "<application>gpg</application>">
+<!ENTITY gnupg "GnuPG">
+<!ENTITY Gnupg "GnuPG">
+<!ENTITY eg "e.g.">
+<!ENTITY ie "i.e.">
+<!ENTITY chapter1 SYSTEM "c1.sgml">
+<!ENTITY chapter2 SYSTEM "c2.sgml">
+<!ENTITY chapter3 SYSTEM "c3.sgml">
+<!ENTITY chapter4 SYSTEM "c4.sgml">
+<!ENTITY chapter5 SYSTEM "c5.sgml">
+<!ENTITY chapter6 SYSTEM "c6.sgml">
+<!ENTITY chapter7 SYSTEM "c7.sgml">
+]>
+<book>
+<bookinfo>
+<title>The GNU Privacy Handbook</title>
+<date>
+August 25, 1999
+</date>
+<copyright>
+<year>1999</year>
+<holder>Free Software Foundation</holder>
+</copyright>
+<abstract>
+<para>
+Please direct questions, bug reports, or suggesstions concerning
+this manual to the maintainer, Mike Ashley (<email>jashley@acm.org</email>).
+Contributors to this manual also include Matthew Copeland and
+Joergen Grahn.
+</para>
+
+<para>
+This manual may be redistributed under the terms of the
+<ulink url="http://www.gnu.org/copyleft/gpl.html">GNU General Public
+License</ulink>.
+</para>
+<para> <!-- I have added this note (wk 06.09.99) -->
+PLEASE NOTE, THAT THIS IS A DRAFT VERSION OF THE MANUAL AND NOT A COMPLETE
+AND CORRECT MANUAL.  CONSIDER IT AS WORK IN PROGRESS.  The latest draft of
+the manual should be available online;
+<ulink url="http://www.gnupg.org/docs.html">www.gnupg.org</ulink> has a link
+to it.
+</para>
+</abstract>
+</bookinfo>
+
+<toc></toc>
+
+&chapter1
+&chapter2
+&chapter3
+&chapter4
+&chapter5
+&chapter6
+&chapter7
+</book>
+
diff --git a/doc/gph/signatures.fig b/doc/gph/signatures.fig
new file mode 100644
index 000000000..57fdfe6f6
--- /dev/null
+++ b/doc/gph/signatures.fig
@@ -0,0 +1,44 @@
+#FIG 3.2
+Landscape
+Center
+Inches
+Letter  
+100.00
+Single
+-2
+1200 2
+6 600 300 9450 2625
+6 1500 300 9450 2625
+2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+	1 1 3.00 90.00 180.00
+	 1575 1050 2475 1950
+2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+	1 1 3.00 90.00 180.00
+	 3675 1950 4575 1050
+2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+	1 1 3.00 90.00 180.00
+	 5775 1050 6675 1050
+2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+	1 1 3.00 90.00 180.00
+	 7875 1050 8475 1050
+2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+	1 1 3.00 90.00 180.00
+	 3600 525 4500 1050
+2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+	1 1 3.00 90.00 180.00
+	 3675 1950 5100 2550
+2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+	1 1 3.00 90.00 180.00
+	 5175 1200 5625 2325
+4 0 0 100 0 14 18 0.0000 4 180 825 6825 1125 Elena\001
+4 0 0 100 0 14 18 0.0000 4 180 825 8625 1125 Geoff\001
+4 0 0 100 0 14 18 0.0000 4 180 825 4725 1125 Chloe\001
+4 0 0 100 0 14 18 0.0000 4 180 825 2625 525 Blake\001
+4 0 0 100 0 14 18 0.0000 4 180 990 2550 2025 Dharma\001
+4 0 0 100 0 14 18 0.0000 4 180 1155 5175 2625 Francis\001
+-6
+2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2
+	1 1 3.00 90.00 180.00
+	 1575 1050 2475 450
+4 0 0 100 0 14 18 0.0000 4 180 825 600 1125 Alice\001
+-6
diff --git a/doc/manual.sgml b/doc/manual.sgml
deleted file mode 100644
index 56e8e92b4..000000000
--- a/doc/manual.sgml
+++ /dev/null
@@ -1,101 +0,0 @@
-<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
-<!entity gnupg	    "GnuPG">
-<!entity wwwgnu     "http://www.gnu.org">
-<!entity wwwgnupg   "http://www.gnupg.org">
-]>
-<book>
-  <bookinfo>
-    <title>The GNU Privacy Guard Manual</title>
-    <titleabbrev>GnuPG-Man</titleabbrev>
-    <edition>v0.0.0</edition>
-    <authorgroup>
-      <!-- Replace with your name and delete mine -->
-      <author>
-	<firstname>Joe</firstname>
-	<othername>D.</othername>
-	<surname>Foo</surname>
-	<authorblurb>
-	    <para><email>joe@somewhere</email></para>
-	</authorblurb>
-      </author>
-      <author>
-	  <firstname>Werner</firstname>
-	  <surname>Koch</surname>
-	  <authorblurb>
-	      <para><email>wk@gnupg.org</email></para>
-	  </authorblurb>
-      </author>
-    </authorgroup>
-    <!-- note, it is possible to give more than 1 year -->
-    <copyright><year>1999</year>
-	       <holder>Free Software Foundation, Inc.</holder>
-    </copyright>
-    <!-- We have to check, whether this is the right wording -->
-    <legalnotice>
-      <para>This manual 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.</para>
-
-      <para>This manual 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.</para>
-
-      <para>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</para>
-
-      <para>For more details see the file COPYING in the source
-	distribution of &gnupg;.</para>
-    </legalnotice>
-  </bookinfo>
-
-  <!-- Insert the table of contents -->
-  <toc></toc>
-
-<!--*******************************************
-    *********  the first chapter  *************
-    *******************************************-->
-  <chapter id="intro">
-    <title>Introduction</title>
-    <sect1 id="feedback">
-      <title>Feedback</title>
-      <!-- Hope we can remove this ;-) -->
-      <para>Well, I'm German and I find it hard to express myself in
-	English. So if you find some phrases and/or words that I used
-	in a wrong way (and you will find them :-) ), please send me a
-	mail, to let me correct this. Please send me notes about
-	typos, too.
-    </sect1>
-
-
-    <sect1 id="whatis">
-	<title>What is &gnupg;</title>
-      <para><ulink url="&wwwgnupg;">&gnupg;</> is a tool for digital
-	encryption and signing;
-	it is part of the <ulink url="&wwwgnu;">GNU Project</>.
-
-      <para>It has these features:
-      <itemizedlist>
-	<listitem>
-	  <para>Exciting feature 1
-	</listitem>
-	<listitem>
-	  <para>Exciting feature 2
-	</listitem>
-      </itemizedlist>
-
-      <para>How to find out the version of &gnupg;
-      <screen>
-	<prompt/$/ <userinput>gpg --version</>
-      </screen>
-
-    </sect1>
-
-  </chapter>
-
-</book>