doc fixes
authorWerner Koch <wk@gnupg.org>
Fri, 8 Sep 2006 17:02:06 +0000 (17:02 +0000)
committerWerner Koch <wk@gnupg.org>
Fri, 8 Sep 2006 17:02:06 +0000 (17:02 +0000)
12 files changed:
README
doc/ChangeLog
doc/HACKING
doc/Makefile.am
doc/examples/scd-event
doc/gnupg.texi
doc/gpg-agent.texi
doc/gpg.texi
doc/gpgsm.texi
doc/specify-user-id.texi [new file with mode: 0644]
doc/tools.texi
doc/yat2m.c

diff --git a/README b/README
index 6ae0e79..008b84b 100644 (file)
--- a/README
+++ b/README
@@ -11,9 +11,9 @@ 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.4.x as well as some of
-the old 1.2.x).  There are no problems installing 1.4 and 1.9
-alongside; in dact we suggest to do this.
+helpful when using the standard gpg versions (1.4.x) the old 1.2.x).
+There are no problems installing 1.4 and 1.9 alongside; in fact we
+suggest to do this.
 
 
 BUILD INSTRUCTIONS
@@ -23,12 +23,9 @@ GnuPG 1.9 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/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/ .
@@ -51,452 +48,21 @@ 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
-that this package won't conflict 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.
+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-dev@gnupg.org for advise.  Note
+In case of problem please ask on gnupg-users@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. man pages for
-all major components are also provided. Some commands and options
-given below.  See also the section `SMARTCARD INTRO'.
-
-
-COMMANDS
-========
-
-See the info documentation ("info gnupg") for a full list of commands
-and options.
-
-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.
-
-
-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>
-
-  Change the default 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 an 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 variable 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 variable 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 encoded 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 keyboard 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 setting 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 white 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 will 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 starting 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 deducted from the length of the string and its
-   content or "0x" prefix. For use with OpenPGP an 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 an 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
-
- * Exact 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 and
-http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
-
-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.
-
 
 
+DOCUMENTATION
+==================
 
+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
+gnupg.pdf".  For a HTML version enter "make gnupg.html" and point your
+browser to gnupg.html/index.html.  Standard man pages for all
+components are provided as well.
 
index 87238a8..ae2e157 100644 (file)
@@ -1,3 +1,10 @@
+2006-09-08  Werner Koch  <wk@g10code.com>
+
+       * yat2m.c (parse_file): Ignore @node lines immediately.
+       (proc_texi_cmd): No special @end ifset processing anymore.
+
+       * specify-user-id.texi: New.  Factored out of gpg.texi and ../README.
+
 2006-09-07  Werner Koch  <wk@g10code.com>
 
        * scdaemon.texi (Scdaemon Configuration): New.
index eee9f62..5efb6c9 100644 (file)
@@ -6,6 +6,22 @@
                   ===> Under construction <=======
 
 
+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
+
+
+
+
 CVS Access
 ==========
 
index dcef09c..ec40202 100644 (file)
@@ -27,7 +27,7 @@ EXTRA_DIST = DETAILS HACKING TRANSLATE OpenPGP KEYSERVER samplekeys.asc \
              gnupg-card-architecture.eps gnupg-card-architecture.png \
              gnupg-card-architecture.pdf \
              faq.raw FAQ faq.html gnupg7.texi \
-             opt-homedir.texi see-also-note.texi \
+             opt-homedir.texi see-also-note.texi specify-user-id.texi \
             $(examples)
 
 BUILT_SOURCES = gnupg-card-architecture.eps gnupg-card-architecture.png \
index 1d03187..938465f 100755 (executable)
@@ -36,12 +36,12 @@ Options:
   --reader-port N        Reports change for port N
   --old-code 0xNNNN      Previous status code
   --old-code 0xNNNN      Current status code
-  --status USABLE|ACTIVE|PRESENT}NOCARD 
+  --status USABLE|ACTIVE|PRESENT|NOCARD 
                          Human readable status code
 
 Environment:
 
-GNUPGHOME=DIR            Set to the active hmedir
+GNUPGHOME=DIR            Set to the active homedir
 
 EOF
           exit 0
index fbd1b99..304984b 100644 (file)
@@ -118,6 +118,7 @@ the administration and the architecture.
 * Invoking GPGSM::      Using the S/MIME protocol.
 * Invoking GPG-AGENT::  How to launch the secret key daemon.
 * Invoking SCDAEMON::   How to handle Smartcards.
+* Specify a User ID::   How to Specify a User Id.
 
 * Helper Tools::        Description of small helper tools
 
@@ -152,6 +153,12 @@ the administration and the architecture.
 @include gpg-agent.texi
 @include scdaemon.texi
 
+@node Specify a User ID
+@chapter How to Specify a User Id
+@anchor{how-to-specify-a-user-id}
+@include specify-user-id.texi
+
+
 @include tools.texi
 
 @include sysnotes.texi
index a26f25b..c9a89b9 100644 (file)
@@ -500,6 +500,14 @@ agent. By default they may all be found in the current home directory
   # Key added on 2005-02-25 15:08:29
   5A6592BF45DC73BD876874A28FD4639282E29B52 0
   @end example
+
+@item private-keys-v1.d/
+
+  This is the directory where gpg-agent stores the private keys.  Each
+  key is stored in a file with the name made up of the keygrip and the
+  suffix @file{key}.
+
+
 @end table
 
 Note that on larger installations, it is useful to put predefined
index 94f62cd..219ff15 100644 (file)
@@ -30,7 +30,7 @@
 
 @mansect description
 @command{gpg2} is the OpenPGP part of the GNU Privacy Guard (GnuPG). It
-is a tool to provide digitla encryption and signing services using the
+is a tool to provide digital encryption and signing services using the
 OpenPGP standard. @command{gpg2} features complete key management and
 all bells and whistles you can expect from a decent OpenPGP
 implementation.
@@ -2455,59 +2455,15 @@ user for the filename.
 @end table
 
 
+@c *******************************************
+@c ***************            ****************
+@c ***************  USER ID   ****************
+@c ***************            ****************
+@c *******************************************
 @mansect how to specify a user id
-@chapheading How to specify a user ID
-
-There are different ways to specify a user ID to GnuPG; here are some
-examples:
-
-@table @asis
-
-@item
-
-@item 234567C4
-@itemx 0F34E556E
-@itemx 01347A56A
-@itemx 0xAB123456
-Here the key ID is given in the usual short form.
-
-@item 234AABBCC34567C4
-@itemx 0F323456784E56EAB
-@itemx 01AB3FED1347A5612
-@itemx 0x234AABBCC34567C4
-Here the key ID is given in the long form as used by OpenPGP
-(you can get the long key ID using the option --with-colons).
-
-@item 1234343434343434C434343434343434
-@itemx 123434343434343C3434343434343734349A3434
-@itemx 0E12343434343434343434EAB3484343434343434
-@itemx 0xE12343434343434343434EAB3484343434343434
-The best way to specify a key ID is by using the fingerprint of
-the key. This avoids any ambiguities in case that there are duplicated
-key IDs (which are really rare for the long key IDs).
-
-@item =Heinrich Heine <heinrichh@@uni-duesseldorf.de>
-Using an exact to match string. The equal sign indicates this.
-
-@item <heinrichh@@uni-duesseldorf.de>
-Using the email address part which must match exactly. The left angle bracket
-indicates this email address mode.
-
-@item @@heinrichh
-Match within the <email.address> part of a user ID. The at sign
-indicates this email address mode.
-
-@item Heine
-@itemx *Heine
-By case insensitive substring matching. This is the default mode but
-applications may want to explicitly indicate this by putting the asterisk
-in front.
-@end table
-
-Note that you can append an exclamation mark (!) to key IDs or
-fingerprints. This flag tells GnuPG to use the specified primary or
-secondary key and not to try and calculate which primary or secondary
-key to use.
+@ifset isman
+@include specify-user-id.texi
+@end ifset
 
 @mansect return vaue
 @chapheading RETURN VALUE
index 4680128..5de9efb 100644 (file)
@@ -105,18 +105,19 @@ abbreviate this command.
 @table @gnupgtabopt
 @item --encrypt
 @opindex encrypt
-Perform an encryption.
+Perform an encryption.  The keys the data is encrypted too must be set
+using the option @option{--recipient}.
 
 @item --decrypt
 @opindex decrypt
-Perform a decryption; the type of input is automatically detmerined.  It
+Perform a decryption; the type of input is automatically determined.  It
 may either be in binary form or PEM encoded; automatic determination of
 base-64 encoding is not done.
 
 @item --sign
 @opindex sign
 Create a digital signature.  The key used is either the fist one found
-in the keybox or thise set with the -u option
+in the keybox or those set with the @option{--local-user} option.
 
 @item --verify
 @opindex verify
@@ -428,6 +429,14 @@ Assume the input data is binary encoded.
 Set the user(s) to be used for signing.  The default is the first
 secret key found in the database.
 
+
+@item --recipient @var{name}
+@itemx -r
+@opindex recipient
+Encrypt to the user id @var{name}.  There are several ways a user id
+may be given (@pxref{how-to-specify-a-user-id}).
+
+
 @item --output @var{file}
 @itemx -o @var{file}
 @opindex output
@@ -500,18 +509,18 @@ Include ephemeral flagged keys in the output of key listings.
 Select the debug level for investigating problems. @var{level} may be
 one of:
 
-   @table @code
-   @item none
-   no debugging at all.
-   @item basic  
-   some basic debug messages
-   @item advanced
-   more verbose debug messages
-   @item expert
-   even more detailed messages
-   @item guru
-   all of the debug messages you can get
-   @end table
+@table @code
+@item none
+no debugging at all.
+@item basic  
+some basic debug messages
+@item advanced
+more verbose debug messages
+@item expert
+even more detailed messages
+@item guru
+all of the debug messages you can get
+@end table
 
 How these messages are mapped to the actual debugging flags is not
 specified and may change with newer releaes of this program. They are
@@ -524,24 +533,24 @@ at any time without notice; using @code{--debug-levels} is the
 preferred method to select the debug verbosity.  FLAGS are bit encoded
 and may be given in usual C-Syntax. The currently defined bits are:
 
-   @table @code
-   @item 0  (1)
-   X.509 or OpenPGP protocol related data
-   @item 1  (2)  
-   values of big number integers 
-   @item 2  (4)
-   low level crypto operations
-   @item 5  (32)
-   memory allocation
-   @item 6  (64)
-   caching
-   @item 7  (128)
-   show memory statistics.
-   @item 9  (512)
-   write hashed data to files named @code{dbgmd-000*}
-   @item 10 (1024)
-   trace Assuan protocol
-   @end table
+@table @code
+@item 0  (1)
+X.509 or OpenPGP protocol related data
+@item 1  (2)  
+values of big number integers 
+@item 2  (4)
+low level crypto operations
+@item 5  (32)
+memory allocation
+@item 6  (64)
+caching
+@item 7  (128)
+show memory statistics.
+@item 9  (512)
+write hashed data to files named @code{dbgmd-000*}
+@item 10 (1024)
+trace Assuan protocol
+@end table
 
 Note, that all flags set using this option may get overriden by
 @code{--debug-level}.
@@ -580,6 +589,15 @@ package and may be revised or removed at any time without notice.
 All the long options may also be given in the configuration file after
 stripping off the two leading dashes.
 
+@c *******************************************
+@c ***************            ****************
+@c ***************  USER ID   ****************
+@c ***************            ****************
+@c *******************************************
+@mansect how to specify a user id
+@ifset isman
+@include specify-user-id.texi
+@end ifset
 
 @c *******************************************
 @c ***************            ****************
diff --git a/doc/specify-user-id.texi b/doc/specify-user-id.texi
new file mode 100644 (file)
index 0000000..01df989
--- /dev/null
@@ -0,0 +1,160 @@
+@c Include file to allow for different placements in man pages and the manual
+
+There are different ways to specify a user ID to GnuPG.  Some of them
+are only valid for @command{gpg} others are only good for
+@command{gpgsm}.  Here is the entire list of ways to specify a key:
+
+@itemize @bullet
+
+@item By key Id. 
+This format is deduced from the length of the string and its content or
+@code{0x} prefix. The key Id of an X.509 certificate are the low 64 bits
+of its SHA-1 fingerprint.  The use of key Ids is just a shortcut, for
+all automated processing the fingerprint should be used.
+
+When using @command{gpg} an exclamation mark may be appended to force
+using the specified primary or secondary key and not to try and
+calculate which primary or secondary key to use.
+
+The last four lines of the example give the key ID in their long form as
+internally used by the OpenPGP protocol. You can see the long key ID
+using the option @option{--with-colons}.
+
+@cartouche
+@example
+234567C4
+0F34E556E
+01347A56A
+0xAB123456
+
+234AABBCC34567C4
+0F323456784E56EAB
+01AB3FED1347A5612
+0x234AABBCC34567C4
+@end example
+@end cartouche
+
+
+
+@item By fingerprint.
+This format is deduced from the length of the string and its content or
+the @code{0x} prefix.  Note, that only the 20 byte version fingerprint
+is available with @command{gpgsm} (i.e. the SHA-1 hash of the
+certificate).
+
+When using @command{gpg} an exclamation mark may be appended to force
+using the specified primary or secondary key and not to try and
+calculate which primary or secondary key to use.
+
+The best way to specify a key Id is by using the fingerprint.  This
+avoids any ambiguities in case that there are duplicated key IDs.
+
+@cartouche
+@example
+1234343434343434C434343434343434
+123434343434343C3434343434343734349A3434
+0E12343434343434343434EAB3484343434343434
+0xE12343434343434343434EAB3484343434343434
+@end example
+@end cartouche
+
+@noindent
+(@command{gpgsm} also accepts colons between each pair of hexadecimal
+digits because this is the de-facto standard on how to present X.509
+fingerprints.)
+
+@item By exact match on OpenPGP user ID.
+This is denoted by a leading equal sign. It does not make sense for
+X.509 certificates.
+
+@cartouche
+@example 
+=Heinrich Heine <heinrichh@@uni-duesseldorf.de>
+@end example
+@end cartouche
+
+@item By exact match on an email address.
+This is indicated by enclosing the email address in the usual way
+with left and right angles.
+
+@cartouche
+@example
+<heinrichh@@uni-duesseldorf.de>
+@end example
+@end cartouche
+
+
+@item By 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.
+
+@cartouche
+@example
++Heinrich Heine duesseldorf
+@end example
+@end cartouche
+
+@item By exact match on the subject's DN.
+This is indicated by a leading slash, directly followed by the RFC-2253
+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) RFC-2253 string
+
+@cartouche
+@example
+/CN=Heinrich Heine,O=Poets,L=Paris,C=FR
+@end example
+@end cartouche
+
+@item By exact match on the 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.
+
+@cartouche
+@example
+#/CN=Root Cert,O=Poets,L=Paris,C=FR
+@end example
+@end cartouche
+
+
+@item By exact match on 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
+RFC-2253 encoded DN of the issuer. See note above.
+
+@cartouche
+@example
+#4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
+@end example
+@end cartouche
+
+
+@item By substring match.
+This is the default mode but applications may want to explicitly
+indicate this by putting the asterisk in front.  Match is not case
+sensitive.
+
+@cartouche
+@example
+Heine
+*Heine
+@end example
+@end cartouche
+
+@end itemize
+
+
+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 RFC-2253 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.
+
+
+
index 07fcfd2..4e9a80d 100644 (file)
@@ -948,13 +948,13 @@ It is very similar to running @command{gpg-agent} in server mode; but
 here we connect to a running instance.
 
 @menu
-* Invoking gpg-connect-agent::   List of all commands and options.
+* Invoking gpg-connect-agent::       List of all options.
+* Controlling gpg-connect-agent::    Control commands.
 @end menu
 
 @manpause
 @node Invoking gpg-connect-agent
-@subsection List of all commands and options.
-@mancont
+@subsection List of all options.
 
 @noindent
 @command{gpg-connect-agent} is invoked this way:
@@ -962,6 +962,7 @@ here we connect to a running instance.
 @example
 gpg-connect-agent [options]
 @end example
+@mancont
 
 @noindent
 The following options may be used:
@@ -990,11 +991,47 @@ be used to directly connect to any Assuan style socket server.
 
 @end table
 
+@mansect control commands
+@node Controlling gpg-connect-agent
+@subsection Control commands.
+
+While reading Assuan commands, gpg-agent also allows a few special
+commands to control its operation.  These control commands all start
+with a slash (@code{/}).
+
+
+@table @code
+
+@item /echo @var{args}
+Just print @var{args}.
+
+@item /definqfile @var{name} @var{file}
+
+Use content of @var{file} for inquiries with @var{name}.
+@var{name} may be an asterisk (@code{*} to match any inquiry.
+
+@item /definqprog @var{name} @var{prog}
+Run @var{prog} for inquiries matching @var{name} and pass the
+entire line to it as command line arguments
+
+@item /showdef
+Print all definitions
+
+@item /cleardef
+Delete all definitions
+
+@item /help
+Print a list of available control commands.
+
+@end table
+
+
+@ifset isman
 @mansect see also
 @command{gpg-agent}(1), 
 @command{scdaemon}(1)
 @include see-also-note.texi
-
+@end ifset
 
 
 @c
index c47e2fe..266107c 100644 (file)
@@ -456,7 +456,6 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
     { "opindex", 1 },
     { "cpindex", 1 },
     { "cindex",  1 },
-    { "node",    1 },
     { "noindent", 0 },
     { "section", 1 },
     { "chapter", 1 },
@@ -465,6 +464,8 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
     { "item",    2, ".TP\n.B " },
     { "itemx",   2, ".TP\n.B " },
     { "table",   3 }, 
+    { "itemize",   3 }, 
+    { "bullet",  0, "* " },
     { "end",     4 },
     { "quotation",1, ".RS\n\\fB" },
     { "ifset",   1 },
@@ -523,11 +524,6 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
             {
               fputs ("\\fR\n.RE\n", fp);
             }
-          else if (n >= 5 && !memcmp (s, "ifset", 5)
-              && (!n || s[5] == ' ' || s[5] == '\t' || s[5] == '\n'))
-            {
-              fputs ("\\fR\n.RE\n", fp);
-            }
           /* Now throw away the entire line. */
           s = memchr (rest, '\n', len);
           return s? (s-rest)+1 : len;  
@@ -832,6 +828,14 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
         }
       line[--n] = 0;
 
+      if (n >= 5 && !memcmp (line, "@node", 5)
+          && (line[5]==' '||line[5]=='\t'||!line[5]))
+        {
+          /* Completey ignore @node lines.  */
+          continue;
+        }
+
+
       if (skip_sect_line)
         {
           skip_sect_line = 0;