[svn] GnuPG - r4247 - in trunk: . doc doc/examples
svn author wk
cvs at cvs.gnupg.org
Fri Sep 8 19:02:10 CEST 2006
Author: wk
Date: 2006-09-08 19:02:06 +0200 (Fri, 08 Sep 2006)
New Revision: 4247
Added:
trunk/doc/specify-user-id.texi
Modified:
trunk/README
trunk/doc/ChangeLog
trunk/doc/HACKING
trunk/doc/Makefile.am
trunk/doc/examples/scd-event
trunk/doc/gnupg.texi
trunk/doc/gpg-agent.texi
trunk/doc/gpg.texi
trunk/doc/gpgsm.texi
trunk/doc/tools.texi
trunk/doc/yat2m.c
Log:
doc fixes
Modified: trunk/README
===================================================================
--- trunk/README 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/README 2006-09-08 17:02:06 UTC (rev 4247)
@@ -11,9 +11,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 @@
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 @@
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 at gnupg.org for advise. Note
+In case of problem please ask on gnupg-users at 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
-========
+DOCUMENTATION
+==================
-See the info documentation ("info gnupg") for a full list of commands
-and options.
+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.
-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 at 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 at 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.
-
-
-
-
-
Modified: trunk/doc/ChangeLog
===================================================================
--- trunk/doc/ChangeLog 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/ChangeLog 2006-09-08 17:02:06 UTC (rev 4247)
@@ -1,3 +1,10 @@
+2006-09-08 Werner Koch <wk at 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 at g10code.com>
* scdaemon.texi (Scdaemon Configuration): New.
Modified: trunk/doc/HACKING
===================================================================
--- trunk/doc/HACKING 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/HACKING 2006-09-08 17:02:06 UTC (rev 4247)
@@ -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
==========
Modified: trunk/doc/Makefile.am
===================================================================
--- trunk/doc/Makefile.am 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/Makefile.am 2006-09-08 17:02:06 UTC (rev 4247)
@@ -27,7 +27,7 @@
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 \
Modified: trunk/doc/examples/scd-event
===================================================================
--- trunk/doc/examples/scd-event 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/examples/scd-event 2006-09-08 17:02:06 UTC (rev 4247)
@@ -36,12 +36,12 @@
--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
Modified: trunk/doc/gnupg.texi
===================================================================
--- trunk/doc/gnupg.texi 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/gnupg.texi 2006-09-08 17:02:06 UTC (rev 4247)
@@ -118,6 +118,7 @@
* 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 @@
@include gpg-agent.texi
@include scdaemon.texi
+ at node Specify a User ID
+ at chapter How to Specify a User Id
+ at anchor{how-to-specify-a-user-id}
+ at include specify-user-id.texi
+
+
@include tools.texi
@include sysnotes.texi
Modified: trunk/doc/gpg-agent.texi
===================================================================
--- trunk/doc/gpg-agent.texi 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/gpg-agent.texi 2006-09-08 17:02:06 UTC (rev 4247)
@@ -500,6 +500,14 @@
# Key added on 2005-02-25 15:08:29
5A6592BF45DC73BD876874A28FD4639282E29B52 0
@end example
+
+ at 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
Modified: trunk/doc/gpg.texi
===================================================================
--- trunk/doc/gpg.texi 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/gpg.texi 2006-09-08 17:02:06 UTC (rev 4247)
@@ -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,60 +2455,16 @@
@end table
+ at c *******************************************
+ at c *************** ****************
+ at c *************** USER ID ****************
+ at c *************** ****************
+ at c *******************************************
@mansect how to specify a user id
- at chapheading How to specify a user ID
+ at ifset isman
+ at include specify-user-id.texi
+ at end ifset
-There are different ways to specify a user ID to GnuPG; here are some
-examples:
-
- at table @asis
-
- at item
-
- at item 234567C4
- at itemx 0F34E556E
- at itemx 01347A56A
- at itemx 0xAB123456
-Here the key ID is given in the usual short form.
-
- at item 234AABBCC34567C4
- at itemx 0F323456784E56EAB
- at itemx 01AB3FED1347A5612
- at 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).
-
- at item 1234343434343434C434343434343434
- at itemx 123434343434343C3434343434343734349A3434
- at itemx 0E12343434343434343434EAB3484343434343434
- at 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).
-
- at item =Heinrich Heine <heinrichh@@uni-duesseldorf.de>
-Using an exact to match string. The equal sign indicates this.
-
- at item <heinrichh@@uni-duesseldorf.de>
-Using the email address part which must match exactly. The left angle bracket
-indicates this email address mode.
-
- at item @@heinrichh
-Match within the <email.address> part of a user ID. The at sign
-indicates this email address mode.
-
- at item Heine
- at 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.
- at 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.
-
@mansect return vaue
@chapheading RETURN VALUE
Modified: trunk/doc/gpgsm.texi
===================================================================
--- trunk/doc/gpgsm.texi 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/gpgsm.texi 2006-09-08 17:02:06 UTC (rev 4247)
@@ -105,18 +105,19 @@
@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 @@
Set the user(s) to be used for signing. The default is the first
secret key found in the database.
+
+ at item --recipient @var{name}
+ at itemx -r
+ at 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 @@
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
+ at table @code
+ at item none
+no debugging at all.
+ at item basic
+some basic debug messages
+ at item advanced
+more verbose debug messages
+ at item expert
+even more detailed messages
+ at item guru
+all of the debug messages you can get
+ at 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 @@
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
+ at table @code
+ at item 0 (1)
+X.509 or OpenPGP protocol related data
+ at item 1 (2)
+values of big number integers
+ at item 2 (4)
+low level crypto operations
+ at item 5 (32)
+memory allocation
+ at item 6 (64)
+caching
+ at item 7 (128)
+show memory statistics.
+ at item 9 (512)
+write hashed data to files named @code{dbgmd-000*}
+ at item 10 (1024)
+trace Assuan protocol
+ at end table
Note, that all flags set using this option may get overriden by
@code{--debug-level}.
@@ -580,6 +589,15 @@
All the long options may also be given in the configuration file after
stripping off the two leading dashes.
+ at c *******************************************
+ at c *************** ****************
+ at c *************** USER ID ****************
+ at c *************** ****************
+ at c *******************************************
+ at mansect how to specify a user id
+ at ifset isman
+ at include specify-user-id.texi
+ at end ifset
@c *******************************************
@c *************** ****************
Added: trunk/doc/specify-user-id.texi
===================================================================
--- trunk/doc/specify-user-id.texi 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/specify-user-id.texi 2006-09-08 17:02:06 UTC (rev 4247)
@@ -0,0 +1,160 @@
+ at 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
+ at command{gpgsm}. Here is the entire list of ways to specify a key:
+
+ at itemize @bullet
+
+ at item By key Id.
+This format is deduced from the length of the string and its content or
+ at 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}.
+
+ at cartouche
+ at example
+234567C4
+0F34E556E
+01347A56A
+0xAB123456
+
+234AABBCC34567C4
+0F323456784E56EAB
+01AB3FED1347A5612
+0x234AABBCC34567C4
+ at end example
+ at end cartouche
+
+
+
+ at 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.
+
+ at cartouche
+ at example
+1234343434343434C434343434343434
+123434343434343C3434343434343734349A3434
+0E12343434343434343434EAB3484343434343434
+0xE12343434343434343434EAB3484343434343434
+ at end example
+ at end cartouche
+
+ at 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.)
+
+ at 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.
+
+ at cartouche
+ at example
+=Heinrich Heine <heinrichh@@uni-duesseldorf.de>
+ at end example
+ at end cartouche
+
+ at 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.
+
+ at cartouche
+ at example
+<heinrichh@@uni-duesseldorf.de>
+ at end example
+ at end cartouche
+
+
+ at 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.
+
+ at cartouche
+ at example
++Heinrich Heine duesseldorf
+ at end example
+ at end cartouche
+
+ at 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
+
+ at cartouche
+ at example
+/CN=Heinrich Heine,O=Poets,L=Paris,C=FR
+ at end example
+ at end cartouche
+
+ at 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.
+
+ at cartouche
+ at example
+#/CN=Root Cert,O=Poets,L=Paris,C=FR
+ at end example
+ at end cartouche
+
+
+ at 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.
+
+ at cartouche
+ at example
+#4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
+ at end example
+ at end cartouche
+
+
+ at 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.
+
+ at cartouche
+ at example
+Heine
+*Heine
+ at end example
+ at end cartouche
+
+ at 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.
+
+
+
Modified: trunk/doc/tools.texi
===================================================================
--- trunk/doc/tools.texi 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/tools.texi 2006-09-08 17:02:06 UTC (rev 4247)
@@ -948,13 +948,13 @@
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
- at subsection List of all commands and options.
- at mancont
+ at subsection List of all options.
@noindent
@command{gpg-connect-agent} is invoked this way:
@@ -962,6 +962,7 @@
@example
gpg-connect-agent [options]
@end example
+ at mancont
@noindent
The following options may be used:
@@ -990,13 +991,49 @@
@end table
+ at mansect control commands
+ at node Controlling gpg-connect-agent
+ at 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{/}).
+
+
+ at table @code
+
+ at item /echo @var{args}
+Just print @var{args}.
+
+ at item /definqfile @var{name} @var{file}
+
+Use content of @var{file} for inquiries with @var{name}.
+ at var{name} may be an asterisk (@code{*} to match any inquiry.
+
+ at 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
+
+ at item /showdef
+Print all definitions
+
+ at item /cleardef
+Delete all definitions
+
+ at item /help
+Print a list of available control commands.
+
+ at end table
+
+
+ at ifset isman
@mansect see also
@command{gpg-agent}(1),
@command{scdaemon}(1)
@include see-also-note.texi
+ at end ifset
-
@c
@c GPGPARSEMAIL
@c
Modified: trunk/doc/yat2m.c
===================================================================
--- trunk/doc/yat2m.c 2006-09-07 15:13:33 UTC (rev 4246)
+++ trunk/doc/yat2m.c 2006-09-08 17:02:06 UTC (rev 4247)
@@ -456,7 +456,6 @@
{ "opindex", 1 },
{ "cpindex", 1 },
{ "cindex", 1 },
- { "node", 1 },
{ "noindent", 0 },
{ "section", 1 },
{ "chapter", 1 },
@@ -465,6 +464,8 @@
{ "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 @@
{
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 @@
}
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;
More information about the Gnupg-commits
mailing list