tools: Fix option parsing for gpg-zip.
[gnupg.git] / README
diff --git a/README b/README
index 0e20a37..55b2f03 100644 (file)
--- a/README
+++ b/README
@@ -1,10 +1,10 @@
 
                    GnuPG - The GNU Privacy Guard
                   -------------------------------
 
                    GnuPG - The GNU Privacy Guard
                   -------------------------------
-                           Version 1.4.6
+                            Version 1.4.20
 
 
-        Copyright 1998, 1999, 2000, 2001, 2002, 2003, 2004,
-                2005, 2006 Free Software Foundation, Inc.
+        Copyright 1998-2015 Free Software Foundation, Inc.
+         Copyright 1997-2015 Werner Koch
 
     This file is free software; as a special exception the author
     gives unlimited permission to copy and/or distribute it, with or
 
     This file is free software; as a special exception the author
     gives unlimited permission to copy and/or distribute it, with or
     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
     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.
+    with the proposed OpenPGP Internet standard as described in RFC4880.
 
     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.
 
     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/download/supported_systems.html for a
+    See https://gnupg.org/download/supported_systems.html for a
     list of systems which are known to work.
 
     list of systems which are known to work.
 
-    See the file COPYING for copyright and warranty information.
+    GnuPG is distributed under the terms of the GNU General Public
+    License.  See the files AUTHORS and COPYING for copyright and
+    warranty information.
 
 
-    Because GnuPG does not use use any patented algorithms it is not
-    by default fully compatible with PGP 2.x, which uses the patented
-    IDEA algorithm.  See http://www.gnupg.org/why-not-idea.html for
-    more information on this subject, including what to do if you are
-    legally entitled to use IDEA.
+    Because GnuPG does not use any patented algorithms it used not to
+    be fully compatible with PGP 2.  Now, that the patent on the IDEA
+    cipher algorithm has expired, we support that algorithm and thus
+    provide full compatibility with PGP 2.  This allows the decryption
+    of data once encrypted using PGP 2.
 
 
-    The default public key algorithms are DSA and Elgamal, but RSA is
+    The default public key algorithm is RSA, but DSA and Elgamal are
     also supported.  Symmetric algorithms available are AES (with 128,
     192, and 256 bit keys), 3DES, Blowfish, CAST5 and Twofish.  Digest
     algorithms available are MD5, RIPEMD/160, SHA-1, SHA-256, SHA-384,
     also supported.  Symmetric algorithms available are AES (with 128,
     192, and 256 bit keys), 3DES, Blowfish, CAST5 and Twofish.  Digest
     algorithms available are MD5, RIPEMD/160, SHA-1, SHA-256, SHA-384,
@@ -55,7 +57,7 @@
        this.  Don't skip it - this is an important step!
 
     2) Unpack the tarball.  With GNU tar you can do it this way:
        this.  Don't skip it - this is an important step!
 
     2) Unpack the tarball.  With GNU tar you can do it this way:
-       "tar xzvf gnupg-x.y.z.tar.gz".  If got a bzip2 compressed
+       "tar xzvf gnupg-x.y.z.tar.gz".  If you got a bzip2 compressed
        tarball you need to use: "tar xjvf gnupg-x.y.z.tar.bz2".
 
     3) "cd gnupg-x.y.z"
        tarball you need to use: "tar xjvf gnupg-x.y.z.tar.bz2".
 
     3) "cd gnupg-x.y.z"
 
     7) You end up with a "gpg" binary in /usr/local/bin.
 
 
     7) You end up with a "gpg" binary in /usr/local/bin.
 
-    8) To avoid swapping out of sensitive data, you can install "gpg"
-       setuid root.  If you don't do so, you may want to add the
-       option "no-secmem-warning" to ~/.gnupg/gpg.conf
+    8) To avoid swapping out of sensitive data, you may need to
+       install "gpg" setuid root.  If you don't do so, you may want to
+       add the option "no-secmem-warning" to ~/.gnupg/gpg.conf.  Note
+       that on modern GNU/Linux systems swapping protection does not
+       anymore require GPG to be installed setuid root.
 
 
     How to Verify the Source
 
 
     How to Verify the Source
@@ -89,7 +93,8 @@
        is indeed a signature of gnupg-x.y.z.tar.gz.  The key currently
        used to create this signature is:
 
        is indeed a signature of gnupg-x.y.z.tar.gz.  The key currently
        used to create this signature is:
 
-       "pub  1024R/1CE0C630 2006-01-01 Werner Koch (dist sig) <dd9jn@gnu.org>"
+       "pub   2048R/4F25E3B6 2011-01-12 [expires: 2019-12-31]
+       "uid                  Werner Koch (dist sig)
 
        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"
 
        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"
        make sure that this is really the key and not a faked one. You
        can do this by comparing the output of:
 
        make sure that this is really the key and not a faked one. You
        can do this by comparing the output of:
 
-               $ gpg --fingerprint 0x1CE0C630
+        $ gpg --fingerprint 0x4F25E3B6
 
        with the fingerprint published elsewhere.
 
 
        with the fingerprint published elsewhere.
 
     An online version of the latest manual draft is available at the
     GnuPG web pages:
 
     An online version of the latest manual draft is available at the
     GnuPG web pages:
 
-       http://www.gnupg.org/documentation/
+       https://gnupg.org/documentation/
 
     A list of frequently asked questions is available in the GnuPG
     distribution in the file doc/FAQ and online as:
 
 
     A list of frequently asked questions is available in the GnuPG
     distribution in the file doc/FAQ and online as:
 
-       http://www.gnupg.org/documentation/faqs.html
+       https://gnupg.org/documentation/faqs.html
 
     A couple of HOWTO documents are available online; for a listing see:
 
 
     A couple of HOWTO documents are available online; for a listing see:
 
-       http://www.gnupg.org/documentation/howtos.html
+       https://gnupg.org/documentation/howtos.html
 
     A man page with a description of all commands and options gets installed
 
     A man page with a description of all commands and options gets installed
-    along with the program. 
+    along with the program.
 
 
     Introduction
 
 
     Introduction
     card.  To see the fingerprints of the secondary keys, you can
     give the command twice; but this is normally not needed.
 
     card.  To see the fingerprints of the secondary keys, you can
     give the command twice; but this is normally not needed.
 
+    NEVER use the keyid to verify a key - always use the complete
+    fingerprint.  The keyid is just a convenience handle to identify a
+    key by a short semi-unique name which is trivial to spoof.  You
+    may want to put the line "keyid-format long" into your gpg.conf to
+    tell gpg to print the long keyid (which is still spoof-able).
+
     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.
     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.
     claims to own it.
 
     There are 2 steps to validate a key:
     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.
        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:
     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
       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
         normally needs only one chain of signatures to validate
         a target key okay. (But this may be adjusted with the help
         of some options).
         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"
     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"
 
     There are several ways to specify a user ID, here are some examples.
 
 
     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):
+    * By a fingerprint:
 
 
-       "234567C4"
-       "0F34E556E"
-       "01347A56A"
-       "0xAB123456
+       "1234343434343434C434343434343434"
+       "123434343434343C3434343434343734349A3434"
+       "0E12343434343434343434EAB3484343434343434"
 
 
-    * By a complete keyid:
+      The first one is a short fingerprint for PGP 2.x style keys.
+      The others are long fingerprints for OpenPGP keys.
+
+    * By a complete keyid (prepend a zero if it begins with A..F):
 
        "234AABBCC34567C4"
        "0F323456784E56EAB"
        "01AB3FED1347A5612"
        "0x234AABBCC34567C4"
 
 
        "234AABBCC34567C4"
        "0F323456784E56EAB"
        "01AB3FED1347A5612"
        "0x234AABBCC34567C4"
 
-    * By a fingerprint:
+    * By the short keyid:
 
 
-       "1234343434343434C434343434343434"
-       "123434343434343C3434343434343734349A3434"
-       "0E12343434343434343434EAB3484343434343434"
-
-      The first one is a short fingerprint for PGP 2.x style keys.
-      The others are long fingerprints for OpenPGP keys.
+       "234567C4"
+       "0F34E556E"
+       "01347A56A"
+       "0xAB123456
 
     * By an exact string:
 
 
     * By an exact string:
 
 
        "<heinrichh@uni-duesseldorf.de>"
 
 
        "<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"
     * Or by the usual substring:
 
        "Heine"
     detailed information about the errors.
 
 
     detailed information about the errors.
 
 
-    Configure options 
+    Configure options
     -----------------
 
     -----------------
 
-    Here is a list of configure options which are sometime useful 
+    Here is a list of configure options which are sometime useful
     for installation.
 
     for installation.
 
-    --enable-static-rnd=<name> 
+    --enable-static-rnd=<name>
                      Force the use of the random byte gathering
                     module <name>.  Default is either to use /dev/random
                     or the auto mode.  Value for name:
                      Force the use of the random byte gathering
                     module <name>.  Default is either to use /dev/random
                     or the auto mode.  Value for name:
                     linux - Use the module which accesses /dev/random.
                             This is the first choice and the default one
                             for GNU/Linux or *BSD.
                     linux - Use the module which accesses /dev/random.
                             This is the first choice and the default one
                             for GNU/Linux or *BSD.
-                      auto - Compile linux, egd and unix in and 
+                      auto - Compile linux, egd and unix in and
                              automagically select at runtime.
                              automagically select at runtime.
-  
+
      --with-egd-socket=<name>
                      This is only used when EGD is used as random
                      gatherer. GnuPG uses by default "~/.gnupg/entropy"
      --with-egd-socket=<name>
                      This is only used when EGD is used as random
                      gatherer. GnuPG uses by default "~/.gnupg/entropy"
                      "~/" uses the socket in the home directory of the user
                      and one starting with a "=" uses a socket in the
                      GnuPG home directory which is "~/.gnupg" by default.
                      "~/" uses the socket in the home directory of the user
                      and one starting with a "=" uses a socket in the
                      GnuPG home directory which is "~/.gnupg" by default.
+
      --without-readline
                      Do not include support for the readline library
                      even if it is available.  The default is to check
                      whether the readline library is a available and
                      use it to allow fancy command line editing.
      --without-readline
                      Do not include support for the readline library
                      even if it is available.  The default is to check
                      whether the readline library is a available and
                      use it to allow fancy command line editing.
-  
+
      --with-included-zlib
                      Forces usage of the local zlib sources. Default is
                     to use the (shared) library of the system.
      --with-included-zlib
                      Forces usage of the local zlib sources. Default is
                     to use the (shared) library of the system.
                      (e.g. SunOS 5.7 on UltraSparc-2) and might give
                      you a bus error.
 
                      (e.g. SunOS 5.7 on UltraSparc-2) and might give
                      you a bus error.
 
-     --disable-dynload 
+     --disable-dynload
                     If you have problems with dynamic loading, this
                     option disables all dynamic loading stuff.  Note
                     that the use of dynamic linking is very limited.
 
      --disable-asm
                     If you have problems with dynamic loading, this
                     option disables all dynamic loading stuff.  Note
                     that the use of dynamic linking is very limited.
 
      --disable-asm
-                    Do not use assembler modules.  It is not possible 
+                    Do not use assembler modules.  It is not possible
                     to use this on some CPU types.
                     to use this on some CPU types.
-                    
+
      --disable-exec
                     Disable all remote program execution.  This
                    disables photo ID viewing as well as all keyserver
      --disable-exec
                     Disable all remote program execution.  This
                    disables photo ID viewing as well as all keyserver
                    --disable-cast5, --disable-blowfish,
                    --disable-aes, --disable-twofish,
                    --disable-sha256, --disable-sha512,
                    --disable-cast5, --disable-blowfish,
                    --disable-aes, --disable-twofish,
                    --disable-sha256, --disable-sha512,
-                   --without-bzip2, --disable-exec, 
+                   --without-bzip2, --disable-exec,
                     --disable-card-support and
                    --disable-agent-support.
                     Configure command lines are read from left to
                    right, so if you want to have an "almost minimal"
                    configuration, you can do (for example)
                    "--enable-minimal --enable-rsa" to have RSA added
                     --disable-card-support and
                    --disable-agent-support.
                     Configure command lines are read from left to
                    right, so if you want to have an "almost minimal"
                    configuration, you can do (for example)
                    "--enable-minimal --enable-rsa" to have RSA added
-                   to the minimal build.
+                   to the minimal build.  Adding the option
+                    --disable-nls may be useful too.
 
      --enable-key-cache=SIZE
                     Set the internal key and UID cache size.  This has
 
      --enable-key-cache=SIZE
                     Set the internal key and UID cache size.  This has
 
      --enable-selinux-support
                     This prevents access to certain files and won't
 
      --enable-selinux-support
                     This prevents access to certain files and won't
-                    allow import or export of secret keys. 
+                    allow import or export of secret keys.
 
      --enable-noexecstack
 
      --enable-noexecstack
-                    Pass option --noexecstack to as.  Autdetect wether
+                    Pass option --noexecstack to as.  Autodetect wether
                     the tool chain actually support this.
 
      --disable-gnupg-iconv
                     the tool chain actually support this.
 
      --disable-gnupg-iconv
                     is in general the preferable solution.  However
                     the code is new and under some cirumstances it may
                     give different output than with the limited old
                     is in general the preferable solution.  However
                     the code is new and under some cirumstances it may
                     give different output than with the limited old
-                    support.  This option allows to explicity disable
+                    support.  This option explicitly disables
                     the use of iconv.  Note, that iconv is also
                     disabled if gettext has been disabled.
 
                     the use of iconv.  Note, that iconv is also
                     disabled if gettext has been disabled.
 
 
     Random devices are available in Linux, FreeBSD and OpenBSD.
     Operating systems without a random devices must use another
 
     Random devices are available in Linux, FreeBSD and OpenBSD.
     Operating systems without a random devices must use another
-    entropy collector. 
+    entropy collector.
 
     This collector works by running a lot of commands that yield more
     or less unpredictable output and feds this as entropy into the
 
     This collector works by running a lot of commands that yield more
     or less unpredictable output and feds this as entropy into the
 
     If you are doing the build on a OS X 10.4 (Tiger) PPC machine you
     may need to add "-isysroot /Developer/SDKs/MacOSX10.4u.sdk" to
 
     If you are doing the build on a OS X 10.4 (Tiger) PPC machine you
     may need to add "-isysroot /Developer/SDKs/MacOSX10.4u.sdk" to
-    those CFLAGS.  Note that any third-party libraries you may link
-    with need to be universal as well.  All Apple-supplied libraries
-    (even libraries not originally written by Apple like curl, zip,
-    and BZ2) are universal.
+    those CFLAGS.  This additional isysroot is not necessary on Intel
+    Tiger boxes, or any OS X 10.5 (Leopard) or later boxes.
+
+    Note that when building a universal binary, any third-party
+    libraries you may link with need to be universal as well.  All
+    Apple-supplied libraries (even libraries not originally written by
+    Apple like curl, zip, and BZ2) are universal.
 
 
 
 
-    GnuPG 1.4 and GnuPG 2.0
+    GnuPG 1.4 and GnuPG 2.x
     -----------------------
 
     -----------------------
 
-    GnuPG 2.0 is a newer version of GnuPG with additional support for
+    GnuPG 2.x is a newer version of GnuPG with additional support for
     S/MIME.  It has a different design philosophy that splits
     functionality up into several modules.  Both versions may be
     S/MIME.  It has a different design philosophy that splits
     functionality up into several modules.  Both versions may be
-    installed simultaneously without any conflict (gpg is called gpg2
-    in GnuPG 2).  In fact, the gpg version from GnuPG 1.4 is able to
-    make use of the gpg-agent as included in GnuPG 2 and allows for
-    seamless passphrase caching.  The advantage of GnupG 1.4 is its
-    smaller size and no dependency on other modules at run and build
-    time.
+    installed simultaneously without any conflict (gpg is usually
+    installed under the name gpg2 in GnuPG-2).  In fact, the GPG
+    version from GnuPG 1.4 is able to make use of the gpg-agent as
+    included in GnuPG-2 and allows for seamless passphrase caching.
+    The advantage of GnuPG 1.4 is its somewhat smaller size and no
+    dependency on other modules at run and build time.  The drawback
+    of 1.4 is its much older code base and that only minimal
+    maintainance is done.  It is highly suggested to switch to 2.x
+    unless your system is not supported by 2.x.
 
 
     How to Get More Information
     ---------------------------
 
 
 
     How to Get More Information
     ---------------------------
 
-    The primary WWW page is "http://www.gnupg.org"
-    The primary FTP site is "ftp://ftp.gnupg.org/gcrypt/"
+    The primary WWW page is https://gnupg.org
+               or using TOR http://ic6au7wa3f6naxjq.onion
 
 
-    See http://www.gnupg.org/download/mirrors.html for a list of
+    The primary FTP site is ftp://ftp.gnupg.org/gcrypt/
+                         or https://gnupg.org/ftp/gcrypt/
+
+    See https://gnupg.org/download/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.
 
     mirrors and use them if possible.  You may also find GnuPG
     mirrored on some of the regular GNU mirrors.
 
     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 are available at
     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 are available at
-    http://www.gnupg.org/documentation/mailing-lists.html
+    https://gnupg.org/documentation/mailing-lists.html
 
 
-    Please direct bug reports to http://bugs.gnupg.org or post
+    Please direct bug reports to https://bugs.gnupg.org or post
     them direct to the mailing list <gnupg-devel@gnupg.org>.
 
     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
     them direct to the mailing list <gnupg-devel@gnupg.org>.
 
     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.  The English and German 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
-    http://www.gnupg.org/service.html .
+    bug fixes.  The English and German GnuPG 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; for a listing of
+    offers see https://gnupg.org/service.html .  Maintaining and
+    improving GnuPG is costly.  Since 2001, g10 Code GmbH, a German
+    company owned and headed by GnuPG's principal author Werner Koch,
+    is bearing the majority of these costs.  To help them carry on
+    this work, they need your support.  See https://gnupg.org/donate/