* configure.ac (NEED_GPG_ERROR_VERSION): Set to 0.7.
[gnupg.git] / README
diff --git a/README b/README
index 84fc896..5b4a690 100644 (file)
--- a/README
+++ b/README
@@ -1,22 +1,56 @@
-GnuPG 1.9 is a temporary project to work on GnuPG extensions; it is a
-merke fo gnupg 1.3 and the old newpg package.  It will eventually lead
-to a GnuPG 2.0 release.
+                   The GNU Privacy Guard 2
+                  =========================
+                       Version 1.9.x
 
-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
 
+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.
+
+
+BUILD INSTRUCTIONS
+==================
+
+GnuPG 1.9 depends on the following packages:
+
+  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
+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
+try to build GnuPG to see whether your already installed versions are
+sufficient).
+
+As with all packages, you just have to do
 
-You need the libgpg-error package.  Libassuan, Libksba and Libgcrypt
-are also required to build it.
+ ./configure
+ make
+ make install
 
-Keybox is designed to be source include-able.
+(Before doing install you might need to become root.)
 
-A texinfo manual `gnupg.info' will get installed.  Some commands and
-options given below.
+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
@@ -177,6 +211,12 @@ scdaemon:
   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.
 
 
 FILES
@@ -261,7 +301,22 @@ private-keys-v1.d/
         about.
 
 
-How to specify a user ID
+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
@@ -339,17 +394,21 @@ modes for gpgsm, here is the entire list of ways to specify a key:
  * [NEW] Exact match by subject's DN
 
    This is indicated by a leading slash, directly followed by the
-   rfc2253 encoded DN of the subject.
+   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=Henrich Heine,O=Poets,L=Paris,C=FR
+      /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
+   issuer.  This should return the Root cert of the issuer.  See note
+   above.
 
    Example:
 
@@ -359,7 +418,7 @@ modes for gpgsm, here is the entire list of ways to specify a key:
 
    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.
+   the RFC2253 encoded DN of the issuer. See note above.
 
    Example:
 
@@ -390,21 +449,17 @@ data.
 Some of the search modes are not yet implemented ;-)
 
 
-How to import a private key
+HOW TO IMPORT A PRIVATE KEY
 ===========================
 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. 
+file.  
 
- gpgsm --call-protect-tool --p12-import --store  foo.p12
+ gpgsm --import  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". 
+This require that the gpg-agent is running.
 
-How to export a private key
+
+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.
@@ -412,3 +467,45 @@ 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 part of GnuPG, supports the OpenPGP smartcard
+(surprise!); see http://g10code.com/p-card.html.
+
+[Fixme: We need to explain this further]
+
+
+GPGSM, the CMS (S/MIME) part of GnuPG, 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.
+
+The other card we currently support is the Telesec NetKey card with
+the NKS 2.0 card application.
+
+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
+
+  gpgsm --learn-card
+
+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.
+
+For selecting the driver, see the options of scdaemon.  A useful
+debugging flag is "--debug 2048" showing the communication between
+scdaemon and the reader.
+
+[fixme: write more stuff]
+
+
+
+
+