tools: Fix option parsing for gpg-zip.
[gnupg.git] / README
diff --git a/README b/README
index 54357c3..55b2f03 100644 (file)
--- a/README
+++ b/README
@@ -1,10 +1,10 @@
 
                    GnuPG - The GNU Privacy Guard
                   -------------------------------
-                           Version 1.3.91
+                            Version 1.4.20
 
-           Copyright 1998, 1999, 2000, 2001, 2002, 2003,
-                2004 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
     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.
-    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.
 
-    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,
@@ -47,6 +49,7 @@
 
     Installation
     ------------
+
     Please read the file INSTALL and the sections in this file
     related to the installation.  Here is a quick summary:
 
@@ -54,7 +57,8 @@
        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"
+       "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"
 
 
     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
     ------------------------
+
     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
+       $ gpg --verify gnupg-x.y.z.tar.gz.sig
 
-       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:
+       This checks that the detached signature gnupg-x.y.z.tar.gz.sig
+       is indeed a signature of gnupg-x.y.z.tar.gz.  The key currently
+       used to create this signature is:
 
-       "pub  1024D/57548DCD 1998-07-07 Werner Koch (gnupg 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"
        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
+        $ gpg --fingerprint 0x4F25E3B6
 
        with the fingerprint published elsewhere.
 
 
 
     b) If you don't have any of the above programs, you have to verify
-       the MD5 checksum:
+       the SHA1 checksum:
 
-       $ md5sum gnupg-x.y.z.tar.gz
+       $ sha1sum gnupg-x.y.z.tar.gz
 
        This should yield an output _similar_ to this:
 
-       fd9351b26b3189c1d577f0970f9dcadc  gnupg-x.y.z.tar.gz
+       fd9351b26b3189c1d577f0970f9dcadc1234abcd  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.
     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:
 
-       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:
 
-       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
-    along with the program. 
+    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
     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.
     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..
+    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
         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"
 
 
     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):
+    * 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"
 
-    * By a fingerprint:
-
-       "1234343434343434C434343434343434"
-       "123434343434343C3434343434343734349A3434"
-       "0E12343434343434343434EAB3484343434343434"
+    * By the short keyid:
 
-      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:
 
 
        "<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"
 
     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),
 
     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.
 
 
-    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.
 
-    --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:
                     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.
-  
+
      --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.
+
      --without-readline
-                     Do not include support for the readline libary
+                     Do not include support for the readline library
                      even if it is available.  The default is to check
-                     whether the readline libarry is a availbale and
+                     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.
                      (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
-                    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.
-                    
+
      --disable-exec
                     Disable all remote program execution.  This
                    disables photo ID viewing as well as all keyserver
      --disable-twofish
      --disable-sha256
      --disable-sha512
-                   Removes support for the selected symmetric
+                   Removes support for the selected symmetric or hash
                    algorithm.  This can give a smaller gpg binary for
                    places where space is tight.
 
                    The public key preference list can be updated to
                    match the list of available algorithms by using
                    "gpg --edit-key (thekey)", and running the
-                   "updpref" command.
+                   "setpref" command.
 
      --enable-minimal
-                   Build the smallest gpg possible (disables all
-                   optional algorithms, disables keyserver access,
-                   and disables photo IDs).  Specifically, this means
-                   --disable-rsa --disable-idea, --disable-cast5,
-                   --disable-blowfish, --disable-aes,
-                   --disable-twofish, --disable-sha256,
-                   --disable-sha512, --without-bzip2, and
-                   --disable-exec.  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.
+                   Build the smallest gpg binary possible (disables
+                   all optional algorithms, disables keyserver
+                   access, and disables photo IDs).  Specifically,
+                   this means --disable-rsa --disable-idea,
+                   --disable-cast5, --disable-blowfish,
+                   --disable-aes, --disable-twofish,
+                   --disable-sha256, --disable-sha512,
+                   --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
+                   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
                     to include support if all required libraries are
                     available.
 
+     --disable-agent-support
+                    Do not include support for the gpg-agent.  The
+                    default is to include support.
+
      --enable-selinux-support
                     This prevents access to certain files and won't
                     allow import or export of secret keys.
 
+     --enable-noexecstack
+                    Pass option --noexecstack to as.  Autodetect wether
+                    the tool chain actually support this.
+
+     --disable-gnupg-iconv
+                    If iconv is available it is used to convert
+                    between utf-8 and the system character set.  This
+                    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 explicitly disables
+                    the use of iconv.  Note, that iconv is also
+                    disabled if gettext has been disabled.
+
 
     Installation Problems
     ---------------------
+
     If you get unresolved externals "gettext" you should run configure
     again with the option "--with-included-gettext"; this is version
     0.12.1 which is available at ftp.gnu.org.
     This doesn't matter and we know about it (actually it is due to
     some warning options which we have enabled for gcc)
 
+    If you are cross-compiling and you get an error either building a
+    tool called "yat2m" or running that tool, the problem is most
+    likely a bad or missing native compiler.  We require a standard
+    C-89 compiler to produce an executable to be run on the build
+    platform.  You can explicitly set such a compiler with configure
+    arguments. On HP/UX you might want to try: "CC_FOR_BUILD=c89".
+
+
 
     Specific problems on some machines
     ----------------------------------
 
         ./configure --with-libiconv-prefix=/sw
 
-    * Compaq C V6.2 for alpha:
-
-        You may want to use the option "-msg-disable ptrmismatch1"
-        to get rid of the sign/unsigned char mismatch warnings.
-
     * IBM RS/6000 running AIX:
 
        Due to a change in gcc (since version 2.8) the MPI stuff may
 
          ./configure ac_cv_sys_symbol_underscore=yes
 
+
     The Random Device
     -----------------
 
     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
 
     Creating an RPM package
     -----------------------
+
     The file scripts/gnupg.spec is used to build a RPM package (both
     binary and src):
       1. copy the spec file into /usr/src/redhat/SPECS
     rpm in /usr/src/redhat/SRPMS
 
 
+    Building Universal Binaries on Apple OS X
+    -----------------------------------------
+
+    You can build a universal ("fat") binary that will work on both
+    PPC and Intel Macs with something like:
+
+    ./configure CFLAGS="-arch ppc -arch i386" --disable-endian-check \
+               --disable-dependency-tracking --disable-asm
+
+    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.  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.x
+    -----------------------
+
+    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
+    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
     ---------------------------
 
-    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.
 
        gnupg-announce@gnupg.org    For important announcements like
                                    new versions and such stuff.
                                    This is a moderated list and has
-                                   very low traffic.
+                                   very low traffic.  Do not post to
+                                   this list.
 
        gnupg-users@gnupg.org       For general user discussion and
-                                   help.
+                                   help (English).
+
+        gnupg-de@gnupg.org          German speaking counterpart of
+                                    gnupg-users.
+
+        gnupg-ru@gnupg.org          Russian speaking counterpart of
+                                    gnupg-users.
 
        gnupg-devel@gnupg.org       GnuPG developers main forum.
 
     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 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.
+    of the authors directly as we are busy working on improvements and
+    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/