typo fixes
[gnupg.git] / README
diff --git a/README b/README
index 42099d6..c14534e 100644 (file)
--- a/README
+++ b/README
@@ -1,22 +1,63 @@
-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.
+
+You should use this GnuPG version if you want to use the gpg-agent or
+gpgsm (the S/MIME variant of gpg).  Note that the gpg-agent is also
+helpful when using the standard gpg versions (1.2.x or 1.3.x).
+
+
+BUILD INSTRUCTIONS
+==================
+
+GnuPG 1.9 depends on the following packages:
+
+  libgpg-error (ftp://ftp.gnupg.org/gcrypt/libgpg-error/)
+  libgcrypt    (ftp://ftp.gnupg.org/gcrypt/libgcrypt/)
+  libassuan    (ftp://ftp.gnupg.org/gcrypt/alpha/libassuan/)
+  libksba      (ftp://ftp.gnupg.org/gcrypt/alpha/libksba/)
+  
+If you use the configure option --enable-agent-only, libksba is not
+required.
 
-You need the libgpg-error package.  Libassuan, Libksba and Libgcrypt
-are also required to build it.
+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/ .
 
-Keybox is designed to be source include-able.
+You should get the latest versions of course, the GnuPG configure
+script complains if a version is not sufficient.
 
-A texinfo manual `gnupg.info' will get installed.  Some commands and
-options given below.
+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
+
+ ./configure
+ make
+ make install
+
+(Before doing install you might need to become root.)
+
+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 or 1.3
+installation. gpg2 behaves just like gpg; it is however suggested to
+keep using gpg 1.2.x or 1.3.x.
+
+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
@@ -37,7 +78,7 @@ gpgsm:
    prepended before each block.
 
 
-gpg2:
+gpg2: (Note that these card commands are also available with gpg 1.3.x)
 -----
 
 --card-status
@@ -138,8 +179,8 @@ gpgsm:
 
 --with-key-data
 
-  Displays extra information with the --list-keys commands.  Especiall
-  a line tagged "grp" si printed which tells you the keygrip of a
+  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.
 
@@ -177,6 +218,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
@@ -228,9 +275,10 @@ policies.txt
 
 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.
+        A list of trusted certificates. The file will be created
+        automagically with some explaining comments.  By using
+        gpg-agent's option --allow-mark-trusted, gpg-agent may add new
+        entries after user confirmation.
 
 random_seed
 
@@ -261,7 +309,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 +402,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 +426,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:
 
@@ -377,7 +444,7 @@ modes for gpgsm, here is the entire list of ways to specify a key:
         *Heine
 
 
-Please note that we have reused the hash mark indentifier which was
+Please note that we have reused the hash mark identifier 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.
@@ -390,25 +457,63 @@ 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 --import  foo.p12
 
- gpgsm --call-protect-tool --p12-import --store  foo.p12
+This requires that the gpg-agent is running.
 
-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
+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.
+format. However there is no MAC applied.
+
+ gpgsm --export-secret-key-p12 userID  >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 cards we currently support are the Telesec NetKey card with
+the NKS 2.0 card application and all generic DINSIG cards.
+
+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]
+
+
 
- gpgsm --call-protect-tool --p12-export  foo.key  >foo.p12