Update head to match stable 1.0

1 files changed, 490 insertions, 10 deletions

diff --git a/README b/README
index c5c91a472..de3093ec2 100644
--- a/README
+++ b/README
@@ -1,17 +1,497 @@
+
 		    GnuPG - The GNU Privacy Guard
 		   -------------------------------
-			    Version 1.1
+			    Version 1.0
+
+    Copyright 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+
+    This file is free software; as a special exception the author gives
+    unlimited permission to copy and/or distribute it, with or without
+    modifications, as long as this notice is preserved.
+
+    This file is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
+    implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+    Intro
+    -----
+
+    GnuPG is GNU's tool for secure communication and data storage.
+    It can be used to encrypt data and to create digital signatures.
+    It includes an advanced key management facility and is compliant
+    with the proposed OpenPGP Internet standard as described in RFC2440.
+
+    GnuPG works best on GNU/Linux or *BSD systems.  Most other Unices
+    are also supported but are not as well tested as the Free Unices.
+    See http://www.gnupg.org/gnupg.html#supsys for a list of systems
+    which are known to work.
+
+    See the file COPYING for copyright and warranty information.
+
+    Because GnuPG does not use use any patented algorithm it cannot be
+    compatible with PGP2 versions.  PGP 2.x uses IDEA (which is patented
+    worldwide).
+
+    The default algorithms are DSA and ElGamal.  ElGamal for signing
+    is still available, but because of the larger size of such
+    signatures it is deprecated (Please note that the GnuPG
+    implementation of ElGamal signatures is *not* insecure).  Symmetric
+    algorithms are: AES, 3DES, Blowfish, CAST5 and Twofish 
+    Digest algorithms available are MD5, RIPEMD160 and SHA1.
+
+
+    Installation
+    ------------
+
+    Please read the file INSTALL!
+
+    Here is a quick summary:
+
+    1) Check that you have unmodified sources.	The below on how to do this.
+       Don't skip it - this is an important step!
+
+    2)	Unpack the TAR.  With GNU tar you can do it this way:
+	"tar xzvf gnupg-x.y.z.tar.gz"
+
+    3) "cd gnupg-x.y.z"
+
+    4)	"./configure"
+
+    5) "make"
+
+    6) "make install"
+
+    7) You end up with a "gpg" binary in /usr/local/bin.
+       Note: Because some old programs rely on the existence of a
+       binary named "gpgm" (which was build by some Beta versions
+       of GnuPG); you may want to install a symbolic link to it:
+       "cd /usr/local/bin; ln -s gpg gpgm"
+
+    8) To avoid swapping out of sensitive data, you can install "gpg" as
+       suid root.  If you don't do so, you may want to add the option
+       "no-secmem-warning" to ~/.gnupg/options
+
+
+    How to Verify the Source
+    ------------------------
+
+    In order to check that the version of GnuPG which you are going to
+    install is an original and unmodified one, you can do it in one of
+    the following ways:
+
+    a) If you already have a trusted Version of GnuPG installed, you
+       can simply check the supplied signature:
+
+	$ gpg --verify gnupg-x.y.z.tar.gz.asc
+
+       This checks that the detached signature gnupg-x.y.z.tar.gz.asc
+       is indeed a a signature of gnupg-x.y.z.tar.gz.  The key used to
+       create this signature is:
+
+       "pub  1024D/57548DCD 1998-07-07 Werner Koch (gnupg sig) <dd9jn@gnu.org>"
+
+       If you do not have this key, you can get it from the source in
+       the file doc/samplekeys.asc (use "gpg --import  doc/samplekeys.asc"
+       to add it to the keyring) or from any keyserver.  You have to
+       make sure that this is really the key and not a faked one. You
+       can do this by comparing the output of:
+
+		$ gpg --fingerprint 0x57548DCD
+
+       with the elsewhere published fingerprint
+
+       Please note, that you have to use an old version of GnuPG to
+       do all this stuff.  *Never* use the version which you are going
+       to check!
+
+
+    b) If you don't have any of the above programs, you have to verify
+       the MD5 checksum:
+
+	$ md5sum gnupg-x.y.z.tar.gz
+
+       This should yield an output _similar_ to this:
+
+	fd9351b26b3189c1d577f0970f9dcadc  gnupg-x.y.z.tar.gz
+
+       Now check that this checksum is _exactly_ the same as the one
+       published via the announcement list and probably via Usenet.
+
+
+
+    Documentation
+    -------------
+
+    The manual will be distributed separate under the name "gph".
+    An online version of the latest manual draft is available at the
+    GnuPG web pages:
+
+	http://www.gnupg.org/gph/
+
+    A list of frequently asked questions is available in GnuPG's
+    distibution in the file doc/FAQ and online as:
+
+	http://www.gnupg.org/faq.html
+
+    A couple of HOWTO documents are available online; for a listing see:
+
+	http://www.gnupg.org/docs.html#howtos
+
+    A man page with a description of all commands and options gets installed
+    along with the program. 
+
+
+    Introduction
+    ------------
+
+    Here is a brief overview on how to use GnuPG - it is strongly suggested
+    that you read the manual and other information about the use of
+    cryptography.  GnuPG is only a tool, secure usage requires that
+    YOU KNOW WHAT YOU ARE DOING.
+
+    If you already have a DSA key from PGP 5 (they call them DH/ElGamal)
+    you can simply copy the pgp keyrings over the GnuPG keyrings after
+    running gpg once to create the correct directory.
+
+    The normal way to create a key is
+
+	gpg --gen-key
+
+    This asks some questions and then starts key generation. To create
+    good random numbers for the key parameters, GnuPG needs to gather
+    enough noise (entropy) from your system.  If you see no progress
+    during key generation you should start some other activities such
+    as mouse moves or hitting on the CTRL and SHIFT keys.
+
+    Generate a key ONLY on a machine where you have direct physical
+    access - don't do it over the network or on a machine used also
+    by others - especially if you have no access to the root account.
+
+    When you are asked for a passphrase use a good one which you can
+    easy remember.  Don't make the passphrase too long because you have
+    to type it for every decryption or signing; but, - AND THIS IS VERY
+    IMPORTANT - use a good one that is not easily to guess because the
+    security of the whole system relies on your secret key and the
+    passphrase that protects it when someone gains access to your secret
+    keyring.  A good way to select a passphrase is to figure out a short
+    nonsense sentence which makes some sense for you and modify it by
+    inserting extra spaces, non-letters and changing the case of some
+    characters - this is really easy to remember especially if you
+    associate some pictures with it.
+
+    Next, you should create a revocation certificate in case someone
+    gets knowledge of your secret key or you forgot your passphrase
+
+	gpg --gen-revoke your_user_id
+
+    Run this command and store the revocation certificate away.  The output
+    is always ASCII armored, so that you can print it and (hopefully
+    never) re-create it if your electronic media fails.
+
+    Now you can use your key to create digital signatures
+
+	gpg -s file
+
+    This creates a file "file.gpg" which is compressed and has a
+    signature attached.
+
+	gpg -sa file
+
+    Same as above, but creates a file "file.asc" which is ASCII armored
+    and and ready for sending by mail.	It is better to use your
+    mailers features to create signatures (The mailer uses GnuPG to do
+    this) because the mailer has the ability to MIME encode such
+    signatures - but this is not a security issue.
+
+	gpg -s -o out file
+
+    Creates a signature of "file", but writes the output to the file
+    "out".
+
+    Everyone who knows your public key (you can and should publish
+    your key by putting it on a key server, a web page or in your .plan
+    file) is now able to check whether you really signed this text
+
+	gpg --verify file
+
+    GnuPG now checks whether the signature is valid and prints an
+    appropriate message.  If the signature is good, you know at least
+    that the person (or machine) has access to the secret key which
+    corresponds to the published public key.
+
+    If you run gpg without an option it will verify the signature and
+    create a new file that is identical to the original.  gpg can also
+    run as a filter, so that you can pipe data to verify trough it
+
+	cat signed-file | gpg | wc -l
+
+    which will check the signature of signed-file and then display the
+    number of lines in the original file.
+
+    To send a message encrypted to someone you can use
+
+	gpg -e -r heine file
+
+    This encrypts "file" with the public key of the user "heine" and
+    writes it to "file.gpg"
+
+	echo "hello" | gpg -ea -r heine | mail heine
+
+    Ditto, but encrypts "hello\n" and mails it as ASCII armored message
+    to the user with the mail address heine.
+
+	gpg -se -r heine file
+
+    This encrypts "file" with the public key of "heine" and writes it
+    to "file.gpg" after signing it with your user id.
+
+	gpg -se -r heine -u Suttner file
+
+    Ditto, but sign the file with your alternative user id "Suttner"
+
+
+    GnuPG has some options to help you publish public keys.  This is
+    called "exporting" a key, thus
+
+	gpg --export >all-my-keys
+
+    exports all the keys in the keyring and writes them (in a binary
+    format) to "all-my-keys".  You may then mail "all-my-keys" as an
+    MIME attachment to someone else or put it on an FTP server. To
+    export only some user IDs, you give them as arguments on the command
+    line.
+
+    To mail a public key or put it on a web page you have to create
+    the key in ASCII armored format
+
+	gpg --export --armor | mail panther@tiger.int
+
+    This will send all your public keys to your friend panther.
+
+    If you have received a key from someone else you can put it
+    into your public keyring.  This is called "importing"
+
+	gpg --import [filenames]
+
+    New keys are appended to your keyring and already existing
+    keys are updated. Note that GnuPG does not import keys that
+    are not self-signed.
+
+    Because anyone can claim that a public key belongs to her
+    we must have some way to check that a public key really belongs
+    to the owner.  This can be achieved by comparing the key during
+    a phone call.  Sure, it is not very easy to compare a binary file
+    by reading the complete hex dump of the file - GnuPG (and nearly
+    every other program used for management of cryptographic keys)
+    provides other solutions.
+
+	gpg --fingerprint <username>
+
+    prints the so called "fingerprint" of the given username which
+    is a sequence of hex bytes (which you may have noticed in mail
+    sigs or on business cards) that uniquely identifies the public
+    key - different keys will always have different fingerprints.
+    It is easy to compare fingerprints by phone and I suggest
+    that you print your fingerprint on the back of your business
+    card.  To see the fingerprints of the secondary keys, you can
+    give the command twice; but this is normally not needed.
+
+    If you don't know the owner of the public key you are in trouble.
+    Suppose however that friend of yours knows someone who knows someone
+    who has met the owner of the public key at some computer conference.
+    Suppose that all the people between you and the public key holder
+    may now act as introducers to you.	Introducers signing keys thereby
+    certify that they know the owner of the keys they sign.  If you then
+    trust all the introducers to have correctly signed other keys, you
+    can be be sure that the other key really belongs to the one who
+    claims to own it..
+
+    There are 2 steps to validate a key:
+	1. First check that there is a complete chain
+	   of signed keys from the public key you want to use
+	   and your key and verify each signature.
+	2. Make sure that you have full trust in the certificates
+	   of all the introduces between the public key holder and
+	   you.
+    Step 2 is the more complicated part because there is no easy way
+    for a computer to decide who is trustworthy and who is not.  GnuPG
+    leaves this decision to you and will ask you for a trust value
+    (here also referenced as the owner-trust of a key) for every key
+    needed to check the chain of certificates.	You may choose from:
+      a) "I don't know" - then it is not possible to use any
+	 of the chains of certificates, in which this key is used
+	 as an introducer, to validate the target key.	Use this if
+	 you don't know the introducer.
+      b) "I do not trust" - Use this if you know that the introducer
+	 does not do a good job in certifying other keys.  The effect
+	 is the same as with a) but for a) you may later want to
+	 change the value because you got new information about this
+	 introducer.
+      c) "I trust marginally" - Use this if you assume that the
+	 introducer knows what he is doing.  Together with some
+	 other marginally trusted keys, GnuPG validates the target
+	 key then as good.
+      d) "I fully trust" - Use this if you really know that this
+	 introducer does a good job when certifying other keys.
+	 If all the introducer are of this trust value, GnuPG
+	 normally needs only one chain of signatures to validate
+	 a target key okay. (But this may be adjusted with the help
+	 of some options).
+    This information is confidential because it gives your personal
+    opinion on the trustworthiness of someone else.  Therefore this data
+    is not stored in the keyring but in the "trustdb"
+    (~/.gnupg/trustdb.gpg).  Do not assign a high trust value just
+    because the introducer is a friend of yours - decide how well she
+    understands the implications of key signatures and you may want to
+    tell her more about public key cryptography so you can later change
+    the trust value you assigned.
+
+    Okay, here is how GnuPG helps you with key management.  Most stuff
+    is done with the --edit-key command
+
+	gpg --edit-key <keyid or username>
+
+    GnuPG displays some information about the key and then prompts
+    for a command (enter "help" to see a list of commands and see
+    the man page for a more detailed explanation).  To sign a key
+    you select the user ID you want to sign by entering the number
+    that is displayed in the leftmost column (or do nothing if the
+    key has only one user ID) and then enter the command "sign" and
+    follow all the prompts.  When you are ready, give the command
+    "save" (or use "quit" to cancel your actions).
+
+    If you want to sign the key with another of your user IDs, you
+    must give an "-u" option on the command line together with the
+    "--edit-key".
+
+    Normally you want to sign only one user ID because GnuPG
+    uses only one and this keeps the public key certificate
+    small.  Because such key signatures are very important you
+    should make sure that the signatories of your key sign a user ID
+    which is very likely to stay for a long time - choose one with an
+    email address you have full control of or do not enter an email
+    address at all.  In future GnuPG will have a way to tell which
+    user ID is the one with an email address you prefer - because
+    you have no signatures on this email address it is easy to change
+    this address.  Remember, your signatories sign your public key (the
+    primary one) together with one of your user IDs - so it is not possible
+    to change the user ID later without voiding all the signatures.
+
+    Tip: If you hear about a key signing party on a computer conference
+    join it because this is a very convenient way to get your key
+    certified (But remember that signatures have nothing to to with the
+    trust you assign to a key).
+
+
+    8 Ways to Specify a User ID
+    --------------------------
+    There are several ways to specify a user ID, here are some examples.
+
+    * Only by the short keyid (prepend a zero if it begins with A..F):
+
+	"234567C4"
+	"0F34E556E"
+	"01347A56A"
+	"0xAB123456
+
+    * By a complete keyid:
+
+	"234AABBCC34567C4"
+	"0F323456784E56EAB"
+	"01AB3FED1347A5612"
+	"0x234AABBCC34567C4"
+
+    * By a fingerprint:
+
+	"1234343434343434C434343434343434"
+	"123434343434343C3434343434343734349A3434"
+	"0E12343434343434343434EAB3484343434343434"
+
+      The first one is MD5 the others are ripemd160 or sha1.
+
+    * By an exact string:
+
+	"=Heinrich Heine <heinrichh@uni-duesseldorf.de>"
+
+    * By an email address:
+
+	"<heinrichh@uni-duesseldorf.de>"
+
+    * By word match
+
+	"+Heinrich Heine duesseldorf"
+
+      All words must match exactly (not case sensitive) and appear in
+      any order in the user ID.  Words are any sequences of letters,
+      digits, the underscore and characters with bit 7 set.
+
+    * Or by the usual substring:
+
+	"Heine"
+	"*Heine"
+
+      The '*' indicates substring search explicitly.
+
+
+    Batch mode
+    ----------
+    If you use the option "--batch", GnuPG runs in non-interactive mode and
+    never prompts for input data.  This does not even allow entering the
+    passphrase.  Until we have a better solution (something like ssh-agent),
+    you can use the option "--passphrase-fd n", which works like PGP's
+    PGPPASSFD.
+
+    Batch mode also causes GnuPG to terminate as soon as a BAD signature is
+    detected.
+
+
+    Exit status
+    -----------
+    GnuPG returns with an exit status of 1 if in batch mode and a bad signature
+    has been detected or 2 or higher for all other errors.  You should parse
+    stderr or, better, the output of the fd specified with --status-fd to get
+    detailed information about the errors.
+
+
+    How to Get More Information
+    ---------------------------
+
+    The primary WWW page is "http://www.gnupg.org"
+    The primary FTP site is "ftp://ftp.gnupg.org/gcrypt/"
+
+    See http://www.gnupg.org/mirrors.html for a list of mirrors
+    and use them if possible.  You may also find GnuPG mirrored on
+    some of the regular GNU mirrors.
+
+    We have some mailing lists dedicated to GnuPG:
+
+	gnupg-announce@gnupg.org    For important announcements like
+				    new versions and such stuff.
+				    This is a moderated list and has
+				    very low traffic.
+
+	gnupg-users@gnupg.org	    For general user discussion and
+				    help.
+
+	gnupg-devel@gnupg.org	    GnuPG developers main forum.
+
+    You subscribe to one of the list by sending mail with a subject
+    of "subscribe" to x-request@gnupg.org, where x is the name of the
+    mailing list (gnupg-announce, gnupg-users, etc.).  An archive of
+    the mailing lists is available at http://lists.gnupg.org .
 
-	WARNING:  This is the current development branch
-		  of GnuPG.  THIS SHOULD NOT BE USED IN
-		  A PRODUCTION ENVIRONMENT.  It will
-		  change quite often and may have serious
-		  problems.  Use the GnuPG from the stable
-		  Branch 1.0.x	for real work.	The next
-		  stable release will be 1.2
+    The gnupg.org domain is hosted in Germany to avoid possible legal
+    problems (technical advices may count as a violation of ITAR).
 
-If you are looking for the CVS from the stable tree, use 
+    Please direct bug reports to <gnupg-bugs@gnu.org> or post
+    them direct to the mailing list <gnupg-devel@gnupg.org>.
 
-cvs -z3 -d :pserver:anoncvs@cvs.gnupg.org:/cvs/gnupg co -r STABLE-BRANCH-1-0 gnupg
+    Please direct questions about GnuPG to the users mailing list or
+    one of the pgp newsgroups; please do not direct questions to one
+    of the authors directly as we are busy working on improvements
+    and bug fixes.  Both mailing lists are watched by the authors
+    and we try to answer questions when time allows us to do so.
 
+    Commercial grade support for GnuPG is available; please see
+    the GNU service directory or search other resources.