mirror of
git://git.gnupg.org/gnupg.git
synced 2025-07-02 22:46:30 +02:00
doc fixes
This commit is contained in:
Werner Koch
parent
6374763c98
commit
90af581b08
12 changed files with 327 additions and 548 deletions
|
|
@ -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.
|
||||
|
|
|
|||
16
doc/HACKING
16
doc/HACKING
|
|
@ -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
|
||||
==========
|
||||
|
||||
|
|
|
|||
|
|
@ -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 \
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
62
doc/gpg.texi
62
doc/gpg.texi
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 *************** ****************
|
||||
|
|
|
|||
160
doc/specify-user-id.texi
Normal file
160
doc/specify-user-id.texi
Normal file
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
16
doc/yat2m.c
16
doc/yat2m.c
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue