Improve ssh card key diagnostic message.
[gnupg.git] / README
diff --git a/README b/README
index 3eb745d..03da25e 100644 (file)
--- a/README
+++ b/README
@@ -1,34 +1,51 @@
-                   The GNU Privacy Guard 2
-                  =========================
-                       Version 1.9.x
+                       The GNU Privacy Guard 2
+                      =========================
+                             Version 2.1
 
 
+   THIS IS A DEVELOPMENT VERSION AND NOT INTENDED FOR REGULAR USE.
 
 
-GnuPG 1.9 is the future version of GnuPG; it is based on the gnupg-1.3
-code and the previous newpg package.  It will eventually lead to a
-GnuPG 2.0 release.  Note that GnuPG 1.3 and 1.9 are not always in sync
-and thus features and bug fixes done in 1.3 are not necessary
-available in 1.9.
+      Copyright 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+     2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
+
+
+INTRODUCTION
+============
+
+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 RFC4880 and the S/MIME
+standard as described by several RFCs.
+
+GnuPG is distributed under the terms of the GNU General Public
+License.  See the file COPYING for details.  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 2.0 is the stable version of GnuPG integrating support for
+OpenPGP and S/MIME.  It does not conflict with an installed 1.4
+OpenPGP-only version.
 
 
 BUILD INSTRUCTIONS
 ==================
 
 
 
 BUILD INSTRUCTIONS
 ==================
 
-GnuPG 1.9 depends on the following packages:
+GnuPG 2.1 depends on the following packages:
+
+  libgpg-error (ftp://ftp.gnupg.org/gcrypt/libgpg-error/)
+  libgcrypt    (ftp://ftp.gnupg.org/gcrypt/libgcrypt/)
+  libksba      (ftp://ftp.gnupg.org/gcrypt/libksba/)
+  libassuan    (ftp://ftp.gnupg.org/gcrypt/libassuan/)
 
 
-  libgpg-error (ftp://ftp.gnupg.org/gcrypt/alpha/libgpg-error/)
-  libgcrypt    (ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/)
-  libassuan    (ftp://ftp.gnupg.org/gcrypt/alpha/libassuan/)
-  libksba      (ftp://ftp.gnupg.org/gcrypt/alpha/libksba/)
-  
-You also need the pinentry package for most function of GnupG; however
-it is not a build requirement.  pinentry is available at
+You also need the Pinentry package for most function of GnuPG; however
+it is not a build requirement.  Pinentry is available at
 ftp://ftp.gnupg.org/gcrypt/pinentry/ .
 
 You should get the latest versions of course, the GnuPG configure
 script complains if a version is not sufficient.
 
 After building and installing the above packages in the order as given
 ftp://ftp.gnupg.org/gcrypt/pinentry/ .
 
 You should get the latest versions of course, the GnuPG configure
 script complains if a version is not sufficient.
 
 After building and installing the above packages in the order as given
-above, you may now continue with GnupG installation (you may also just
+above, you may now continue with GnuPG installation (you may also just
 try to build GnuPG to see whether your already installed versions are
 sufficient).
 
 try to build GnuPG to see whether your already installed versions are
 sufficient).
 
@@ -42,474 +59,137 @@ As with all packages, you just have to do
 
 If everything succeeds, you have a working GnuPG with support for
 S/MIME and smartcards.  Note that there is no binary gpg but a gpg2 so
 
 If everything succeeds, you have a working GnuPG with support for
 S/MIME and smartcards.  Note that there is no binary gpg but a gpg2 so
-that this package won't confict with a GnuPG 1.2 or1.3
-installation. gpg2 behaves just like gpg and it is possible to symlink
-oto gpg if you want to use gpg 1.9.
-
-In case of problem please ask on gpa-dev@gnupg.org for advise.  Note
-that this release is only expected to build on GNU and *BSD systems.
-
-A texinfo manual named `gnupg.info' will get installed.  Some commands
-and options given below.  See also the section `SMARTCARD INTRO'.
-
-
-COMMANDS
-========
-
-gpgsm:
-------
-
---learn-card
-
-   Read information about the private keys from the smartcard and
-   import the certificates from there.
-
---export
-
-   Export all certificates stored in the Keybox or those specified on
-   the command line.  When using --armor a few informational lines are
-   prepended before each block.
-
-
-gpg2:
------
-
---card-status
-
-   Show information pertaining smartcards implementing the OpenPGP
-   application.
-
---change-pin
-
-   Offers a menu to change the PIN of OpenPGP smartcards and to reset
-   the retry counters.
-
---card-edit
-
-   Offers a menu to change any data object on the card and to generate
-   the keys. 
-
-
-OPTIONS
-=======
-
-gpgsm:
-------
-
---include-certs <n>
-
-  Using N of -2 includes all certificate except for the Root cert,
-  -1 includes all certs, 0 does not include any certs, 1 includes only
-  the signers cert (this is the default) and all other positives
-  values include up to N certs starting with the signer cert.
-  
---policy-file <filename>
-
-  Chnage the deault name of the policy file
-
---enable-policy-checks
---disable-policy-checks
-
-  By default policy checks are enabled.  These options may be used to
-  change it.
-
---enable-crl-checks
---disable-crl-checks
-
-  By default the CRL checks are enabled and the DirMngr is used to
-  check for revoked certificates.  The disable option is most useful
-  with a off-line connection to suppres this check.
-
---agent-program <path_to_agent_program>
-
-  Specify an agent program to be used for secret key operations.  The
-  default value is "../agent/gpg-agent".  This is only used as a
-  fallback when the envrionment varaibale GPG_AGENT_INFO is not set or
-  a running agent can't be connected.
-  
---dirmngr-program <path_to_dirmgr_program>
-
-  Specify a dirmngr program to be used for CRL checks.  The default
-  value is "/usr/sbin/dirmngr".  This is only used as a fallback when
-  the environment varaibale DIRMNGR_INFO is not set or a running
-  dirmngr can't be connected.
-
---no-secmem-warning
-
-  Don't print the warning "no secure memory"
-
---armor
-
-  Create PEM ecoded output.  Default is binary output. 
-
---base64 
-
-  Create Base-64 encoded output; i.e. PEM without the header lines.
-
---assume-armor
-
-  Assume the input data is PEM encoded.  Default is to autodetect the
-  encoding but this is may fail.
-
---assume-base64
-
-  Assume the input data is plain base-64 encoded.
-
---assume-binary
-
-  Assume the input data is binary encoded.
-
---server
-
-  Run in server mode.  This is used by GPGME to control gpgsm.  See
-  the assuan specification regarding gpgsm about the used protocol.
-  Some options are ignored in server mode.
-
---local-user  <user_id>
-
-  Set the user to be used for signing.  The default is the first
-  secret key found in the database.
-
---with-key-data
-
-  Displays extra information with the --list-keys commands.  Especially
-  a line tagged "grp" is printed which tells you the keygrip of a
-  key.  This is string is for example used as the filename of the
-  secret key.
-
-
-
-gpg-agent:
----------
-
---pinentry-program <path_to_pinentry_program>
-
-  Specify the PINentry program.  The default value is
-  "<prefix>/bin/pinentry" so you most likely want to specify it.
-
---no-grab
-
-  Tell the pinentry not to grab keybourd and mouse.  You most likely
-  want to give this option during testing and development to avoid
-  lockups in case of bugs.
-
-                     
-scdaemon:
---------
-
---ctapi-driver <libraryname>
-
-  The default for Scdaemon is to use the PC/SC API currently provided
-  by libpcsclite.so.  As an alternative the ctAPI can be used by
-  specify this option with the appropriate driver name
-  (e.g. libtowitoko.so).
-
---reader-port <portname>
-
-  This specifies the port of the chipcard reader.  For PC/SC this is
-  currently ignored and the first PC/SC reader is used.  For the
-  ctAPI, a number must be specified (the default is 32768 for the
-  first USB port).
-
---disable-ccid 
-
-  Disable the integrated support for CCID compliant readers.  This
-  allows to fall back to one of the other drivers even if the internal
-  CCID driver can handle the reader.  Note, that CCID support is only
-  available if libusb was available at build time.
+that this package won't conflict with a GnuPG 1.4 installation.  gpg2
+behaves just like gpg.
 
 
+In case of problem please ask on gnupg-users@gnupg.org for advise.
 
 
-FILES
-=====
+Note that the PKITS tests are always skipped unless you copy the PKITS
+test data file into the tests/pkits directory.  There is no need to
+run these test and some of them may even fail because the test scripts
+are not yet complete.
 
 
-The default home directory is ~/.gnupg.  It can be changed by
-either the --homedir option or by seting the environment variable
-GNUPGHOME.  This is a list of files usually found in this directory:
+You may run
 
 
-gpgsm.conf 
+  gpgconf --list-dirs
 
 
-        Options for gpgsm.  Options are the same as the command line
-        options but don't enter the leading dashes and give arguments
-        without an equal sign.  Blank lines and lines starting with a
-        hash mark as the first non whitye space character are ignored.
+to view the default directories used by GnuPG.
 
 
-gpg-agent.conf
-        
-        Options for gpg-agent
 
 
-scdaemon.conf
+MIGRATION FROM 1.4 or 2.0 to 2.1
+================================
 
 
-        Options for scdaemon.
+The major change in 2.1 is that gpg-agent now takes care of the
+OpenPGP secret keys (those managed by GPG).  The former secring.gpg
+will not be used anymore.  Newly generated keys are generated and
+stored in the agent's key store (~/.gnupg/private-keys-v1.d/).  To
+migrate your existing keys to the agent you should run this command
 
 
-dirmngr.conf 
+  gpg2 --import ~/.gnupg/secring.gpg
 
 
-        Options for the DirMngr which is not part of this package and
-        the option file wilol most likely be moved to /etc
+The agent will you ask for the passphrase of each key.  You may use
+the Cancel button of the Pinentry to skip importing this key.  If you
+want to stop the import process and you use one of the latest
+pinentries, you should close the pinentry window instead of hitting
+the cancel button.  Secret keys already imported are skipped by the
+import command.  It is advisable to keep the secring.gpg for use with
+older versions of GPG.
 
 
-gpg.conf
-        
-        Options for gpg.  Note that old versions of gpg use the
-        filename `options' instead of `gpg.conf'.
+Note that gpg-agent now uses a fixed socket by default.  All tools
+will start the gpg-agent as needed.  In general there is no more need
+to set the GPG_AGENT_INFO environment variable.  The SSH_AUTH_SOCK
+environment variable should be set to a fixed value.
 
 
-gpg.conf-1.9.x
+GPG's smartcard commands --card-edit and --card-status as well as some
+of the card related sub-commands of --edit-key are not yet fully
+supported.  However, signing and decryption with a smartcard does
+work.
 
 
-        Options for gpg; tried before gpg.conf
+The Dirmngr is now part of GnuPG proper.  Thus there is no more need
+to install the separate dirmngr package.  The directroy layout of
+Dirmngr changed to make use of the GnuPG directories; for example you
+use /etc/gnupg/trusted-certs and /var/lib/gnupg/extra-certs.  Dirmngr
+needs to be started as a system daemon.
 
 
 
 
-policies.txt
 
 
-        A list of allowed CA policies.  This file should give the
-        object identifiers of the policies line by line.  Empty lines
-        and lines startung with a hash mark are ignored.
+DOCUMENTATION
+=============
 
 
-        ++++++++++
-        2.289.9.9  
-        ++++++++++
+The complete documentation is in the texinfo manual named
+`gnupg.info'.  Run "info gnupg" to read it.  If you want a a printable
+copy of the manual, change to the "doc" directory and enter "make pdf"
+For a HTML version enter "make html" and point your browser to
+gnupg.html/index.html.  Standard man pages for all components are
+provided as well.  An online version of the manual is available at
+http://www.gnupg.org/documentation/manuals/gnupg/ .  A version of the
+manual pertaining to the current development snapshot is at
+http://www.gnupg.org/documentation/manuals/gnupg-devel/ .
 
 
-trustlist.txt
 
 
-        A list of trusted certificates usually maintained by
-        gpg-agent.  It can however be edited manually.  The file will
-        be created automagically with some explaining comments.
+GNUPG 1.4 AND GNUPG 2.0
+=======================
 
 
-random_seed
+GnuPG 2.0 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 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.
 
 
-        Used internally for keeping the state of the RNG over
-        invocations.
 
 
-pubring.kbx
-
-        The database file with the certificates. 
-
-pubring.gpg
-
-        The database file with the OpenPGP public keys.  This will
-        eventually be merged with pubring.kbx
-
-secring.gpg
-
-        The database file with the OpenPGP secret keys.  This will be
-        removed when gpg is changed to make use of the gpg-agent.
-
-
-private-keys-v1.d/
-
-        Directory holding the private keys maintained by gpg-agent.
-        For detailed info see agent/keyformat.txt. Note that there is
-        a helper tool gpg-protect-tool which may be used to protect or
-        unprotect keys.  This is however nothing a user should care
-        about.
-
-
-SOURCE FILES
-============
-
-Here is a list of directories with source files:
-
-jnlib/  utility functions
-kbx/    keybox library
-g10/    the gpg program here called gpg2
-sm/     the gpgsm program
-agent/  the gpg-agent
-scd/    the smartcard daemon
-doc/    documentation
-
-
-
-HOW TO SPECIFY A USER ID
-========================
-
-Due to the way X.509 certificates are made up we need a few new ways
-to specify a certificate (aka key in OpenPGP).  In addition to the
-ways a user ID can be specified with gpg, I have implemented 3 new
-modes for gpgsm, here is the entire list of ways to specify a key:
-
- * By keyID.
-
-   This format is deducded from the length of the string and its
-   content or "0x" prefix. For use with OpenPGP a exclamation mark may
-   be appended to force use of the specified (sub)key.
-
-   As with v34 OpenPGP keys, the keyID of an X509 certificate are the
-   low 64 bits of the SHA-1 fingerprint.  The use of keyIDs is just a
-   shortcut, for all automated processing the fingerprint should be
-   used.
-
-   Examples:
-
-       234567C4
-       0F34E556E
-       01347A56A
-       0xAB123456
-
-       234AABBCC34567C4
-       0F323456784E56EAB
-       01AB3FED1347A5612
-       0x234AABBCC34567C4
-
- * By fingerprint
-
-   This is format is deduced from the length of the string and its
-   content or "0x" prefix.  Note, that only the 20 byte fingerprint is
-   used with GPGSM (SHA-1 hash of the certificate).  For use with
-   OpenPGP a exclamation mark may be appended to force use of the
-   specified (sub)key.
-
-   Examples:
-
-       1234343434343434C434343434343434
-       123434343434343C3434343434343734349A3434
-       0E12343434343434343434EAB3484343434343434
-       0xE12343434343434343434EAB3484343434343434
-
- * Exact match on OpenPGP user ID
-
-   This is denoted by a leading equal sign. It does not make much
-   sense for X.509.
-
-   Example:
-
-       =Heinrich Heine <heinrichh@uni-duesseldorf.de>
-
- * Exact match on an email address.
-
-   This is indicated by enclosing the email address in the usual way
-   with left and right angles
-
-   Example:
-
-       <heinrichh@uni-duesseldorf.de>
-
- * Word match
-
-   All words must match exactly (not case sensitive) but can appear in
-   any order in the user ID or a subjects name.  Words are any
-   sequences of letters, digits, the underscore and all characters
-   with bit 7 set.
-
-   Example:
-
-       +Heinrich Heine duesseldorf
-
- * [NEW] Exact match by subject's DN
-
-   This is indicated by a leading slash, directly followed by the
-   rfc2253 encoded DN of the subject.  Note that you can't use the
-   string printed by "gpgsm --list-keys" because that one as been
-   reordered and modified for better readability; use --with-colons to 
-   print the raw (but standard escaped) rfc2253 string 
-
-   Example:
-
-      /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
-
- * [NEW] Excact match by issuer's DN
-
-   This is indicated by a leading hash mark, directly followed by a
-   slash and then directly followed by the rfc2253 encoded DN of the
-   issuer.  This should return the Root cert of the issuer.  See note
-   above.
-
-   Example:
-
-      #/CN=Root Cert,O=Poets,L=Paris,C=FR
-
- * [NEW] Exact match by serial number and subject's DN
-
-   This is indicated by a hash mark, followed by the hexadecmal
-   representation of the serial number, the followed by a slahs and
-   the RFC2253 encoded DN of the issuer. See note above.
-
-   Example:
-
-      #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
-
- * Substring match
-
-   By case insensitive substring matching.  This is the default mode
-   but applications may want to explicitly indicate this by putting
-   the asterisk in front.
-
-   Example:
-
-        Heine
-        *Heine
-
-
-Please note that we have reused the hash mark indentifier which was
-used in old GnuPG versions to indicate the so called local-id.  It is
-not anymore used and there should be no conflict when used with X.509
-stuff.
-
-Using the rfc2253 format of DNs has the drawback that it is not
-possible to map them back to the original encoding, however we don't
-have to do this, because our key database stores this encoding as meta
-data.
-
-Some of the search modes are not yet implemented ;-)
-
-
-HOW TO IMPORT A PRIVATE KEY
+HOW TO GET MORE INFORMATION
 ===========================
 ===========================
-There is some limited support to import a private key from a PKCS-12
-file.  Note, that this does only import the private key and not any
-certificates available in that file. 
-
- gpgsm --call-protect-tool --p12-import --store  foo.p12
-
-This require that the gpg-agent is running, alternative you may give
-the passphrase on the commandline using the option "-P <passphrase>" -
-however this is in general not a good idea.  If that key already
-exists, the protect-tool refuses to store it unless you use the option
-"--force". 
-
-HOW TO EXPORT A PRIVATE KEY
-===========================
-There is also limited support to export a private key in PKCS-12
-format. However the certificate is not stored and there is no MAC applied.
-
- gpgsm --call-protect-tool --p12-export  foo.key  >foo.p12
-
-
-SMARTCARD INTRO
-===============
-
-GPG, the OpenPGP implementation supports the OpenPGP smartcard
-(surprise!); see http://g10code.com/p-card.html.
 
 
-[Fixme: We need to explain this further]
+The primary WWW page is "http://www.gnupg.org"
+The primary FTP site is "ftp://ftp.gnupg.org/gcrypt/"
 
 
+See http://www.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.
 
 
-GPGSM, the CMS (S/MIME) implementation supports two kinds of
-smartcards.  The most flexible way is to use PKCS#15 compliant cards,
-however you must have build GnuPG with support for the OpenSC library.
-The build process automagically detects the presence of this library
-and will include support for these cards.
+We have some mailing lists dedicated to GnuPG:
 
 
-The other card we currently support is the Telesec NetKey card with
-the NKS 2.0 card application.
+   gnupg-announce@gnupg.org   For important announcements like new
+                              versions and such stuff.  This is a
+                              moderated list and has very low traffic.
+                              Do not post to this list.
 
 
-Before GPGSM can make use of a new card it must gather some
-information, like the card's serial number, the public keys and the
-certificates stored on the card.  Thus for a new card you need to run
-the command
+   gnupg-users@gnupg.org      For general user discussion and
+                              help (English).
 
 
-  gpgsm --learn-card
+   gnupg-de@gnupg.org         German speaking counterpart of
+                              gnupg-users.
 
 
-once.  This is also a good test to see whether your card reader is
-properly installed. See below in case of error.  Once this has been
-done you may use the keys stored on the card in the same way you use
-keys stored on the disk.  gpgsm automagically knows whether a card is
-required and will pop up the pinentry to ask you to insert the
-correct card.
+   gnupg-ru@gnupg.org         Russian speaking counterpart of
+                              gnupg-users.
 
 
-For selecting the driver, see the options of scdaemon.  A useful
-debugging flag is "--debug 2048" showing the communication between
-scdaemon and the reader.
+   gnupg-devel@gnupg.org      GnuPG developers main forum.
 
 
-[fixme: write more stuff]
+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 are available at http://www.gnupg.org/documentation/mailing-lists.html
 
 
+Please direct bug reports to http://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.
+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 .
 
 
 
 
+  This file is Free Software; as a special exception the authors gives
+  unlimited permission to copy and/or distribute it, with or without
+  modifications, as long as this notice is preserved. For conditions
+  of the whole package, please see the file COPYING.  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.