(create_duptable, destroy_duptable)
[gnupg.git] / README
diff --git a/README b/README
index 7796a94..5b4a690 100644 (file)
--- a/README
+++ b/README
@@ -1,19 +1,56 @@
-GnuPG 1.9 is a temporary protect to work on GnuPG extensions.  It will
-eventually lead to a GnuPG 2.0 release.
+                   The GNU Privacy Guard 2
+                  =========================
+                       Version 1.9.x
 
-jnlib/  utility functions
-assuan/ assuan protocol library
-kbx/    keybox library
-sm/     the gpgsm program
-agent/  the gpg-agent
-scd/    the smartcard daemon
 
-Libksba and Libgcrypt are required to build it.  
+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
+
+ ./configure
+ make
+ make install
+
+(Before doing install you might need to become root.)
 
-Assuan and Keybox are both designed to be source include-able.
+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.
 
-A texinfo manual `gnupg.info' will get installed.  Some commands and
-options given below.
+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
@@ -24,14 +61,33 @@ gpgsm:
 
 --learn-card
 
-   Read tinformation about the private keys from the smartcard and
+   Read information about the private keys from the smartcard and
    import the certificates from there.
 
 --export
 
-    Export all certificates storein the Keybox or those specified on
-    the commandline.  When using --armor a few informational lines are
-    prepended before each block.
+   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
@@ -75,7 +131,7 @@ gpgsm:
 
   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 envrionment varaibale DIRMNGR_INFO is not set or a running
+  the environment varaibale DIRMNGR_INFO is not set or a running
   dirmngr can't be connected.
 
 --no-secmem-warning
@@ -116,8 +172,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.
 
@@ -129,17 +185,38 @@ gpg-agent:
 --pinentry-program <path_to_pinentry_program>
 
   Specify the PINentry program.  The default value is
-  "../../pinentry/kpinentry/kpinentry" so you most likely want to
-  specify it. 
+  "<prefix>/bin/pinentry" so you most likely want to specify it.
 
 --no-grab
 
-  Tel the pinentry not to grab keybourd and mouse.  You most likely
+  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.
 
 
 FILES
@@ -174,10 +251,15 @@ gpg.conf
         Options for gpg.  Note that old versions of gpg use the
         filename `options' instead of `gpg.conf'.
 
+gpg.conf-1.9.x
+
+        Options for gpg; tried before gpg.conf
+
+
 policies.txt
 
         A list of allowed CA policies.  This file should give the
-        object identifiers of the policies line by line.  emptry lines
+        object identifiers of the policies line by line.  Empty lines
         and lines startung with a hash mark are ignored.
 
         ++++++++++
@@ -219,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
@@ -297,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:
 
@@ -317,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:
 
@@ -348,25 +449,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
 
- gpg-protect-tool --p12-import --store  foo.p12
+This require 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.
 
- gpg-protect-tool --p12-export  foo.key  >foo.p12
+ 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]
+
+
+