gnupg/README

                   The GNU Privacy Guard 2
                  =========================
                       Version 1.9.x


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.3.x as well as some of
the old 1.2.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 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.)

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. gpg2 is not even build by default.

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: (Note that these card commands are also available with gpg 1.3.x)
-----

--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.


FILES
=====

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:

gpgsm.conf 

        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.

gpg-agent.conf
        
        Options for gpg-agent

scdaemon.conf

        Options for scdaemon.

dirmngr.conf 

        Options for the DirMngr which is not part of this package and
        the option file wilol most likely be moved to /etc

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.  Empty lines
        and lines startung with a hash mark are ignored.

        ++++++++++
        2.289.9.9  
        ++++++++++

trustlist.txt

        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

        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

 * 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

 * 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

 * Exact match by serial number and issuer's DN

   This is indicated by a hash mark, followed by the hexadecmal
   representation of the serial number, the followed by a slash 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 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.

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
===========================
There is some limited support to import a private key from a PKCS-12
file.  

 gpgsm --import  foo.p12

This requires that the gpg-agent is running.


HOW TO EXPORT A PRIVATE KEY
===========================
There is also limited support to export a private key in PKCS-12
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]