1
0
mirror of git://git.gnupg.org/gnupg.git synced 2024-12-22 10:19:57 +01:00

Update docs from master.

* doc/gpg-agent.texi: Update from master.
* doc/gpg.texi: Ditto.
* doc/gpgsm.texi: Ditto.
* doc/gpl.texi: Ditto.
* doc/yat2m.c: Ditto.
--

(updated from commit d6798d261cbe6519ef5b3ebb474e2ad348442c0c)
This commit is contained in:
Werner Koch 2013-04-18 14:40:43 +02:00
parent e24e92d7e2
commit 681338bfd3
5 changed files with 146 additions and 38 deletions

View File

@ -796,6 +796,14 @@ certificate is that it will be possible to use the same keypair for
different protocols, thereby saving space on the token used to keep the different protocols, thereby saving space on the token used to keep the
secret keys. secret keys.
@ifset gpgtwoone
The @command{gpg-agent} may send status messages during a command or when
returning from a command to inform a client about the progress or result of an
operation. For example, the @var{INQUIRE_MAXLEN} status message may be sent
during a server inquire to inform the client of the maximum usable length of
the inquired data (which should not be exceeded).
@end ifset
@menu @menu
* Agent PKDECRYPT:: Decrypting a session key * Agent PKDECRYPT:: Decrypting a session key
* Agent PKSIGN:: Signing a Hash * Agent PKSIGN:: Signing a Hash
@ -804,6 +812,10 @@ secret keys.
* Agent EXPORT:: Exporting a Secret Key * Agent EXPORT:: Exporting a Secret Key
* Agent ISTRUSTED:: Importing a Root Certificate * Agent ISTRUSTED:: Importing a Root Certificate
* Agent GET_PASSPHRASE:: Ask for a passphrase * Agent GET_PASSPHRASE:: Ask for a passphrase
* Agent CLEAR_PASSPHRASE:: Expire a cached passphrase
@ifset gpgtwoone
* Agent PRESET_PASSPHRASE:: Set a passphrase for a keygrip
@end ifset
* Agent GET_CONFIRMATION:: Ask for confirmation * Agent GET_CONFIRMATION:: Ask for confirmation
* Agent HAVEKEY:: Check whether a key is available * Agent HAVEKEY:: Check whether a key is available
* Agent LEARN:: Register a smartcard * Agent LEARN:: Register a smartcard
@ -972,7 +984,12 @@ option allows to choose the storage location. To get the secret key out
of the PSE, a special export tool has to be used. of the PSE, a special export tool has to be used.
@example @example
@ifset gpgtwoone
GENKEY [--no-protection] [--preset] [<cache_nonce>]
@end ifset
@ifclear gpgtwoone
GENKEY GENKEY
@end ifclear
@end example @end example
Invokes the key generation process and the server will then inquire Invokes the key generation process and the server will then inquire
@ -1017,6 +1034,13 @@ Here is an example session:
S OK key created S OK key created
@end example @end example
@ifset gpgtwoone
The @option{--no-protection} option may be used to prevent prompting for a
passphrase to protect the secret key while leaving the secret key unprotected.
The @option{--preset} option may be used to add the passphrase to the cache
using the default cache parameters.
@end ifset
@node Agent IMPORT @node Agent IMPORT
@subsection Importing a Secret Key @subsection Importing a Secret Key
@ -1173,6 +1197,52 @@ may be used to invalidate the cache entry for a passphrase. The
function returns with OK even when there is no cached passphrase. function returns with OK even when there is no cached passphrase.
@node Agent CLEAR_PASSPHRASE
@subsection Remove a cached passphrase
Use this command to remove a cached passphrase.
@example
@ifset gpgtwoone
CLEAR_PASSPHRASE [--mode=normal] <cache_id>
@end ifset
@ifclear gpgtwoone
CLEAR_PASSPHRASE <cache_id>
@end ifclear
@end example
@ifset gpgtwoone
The @option{--mode=normal} option can be used to clear a @var{cache_id} that
was set by gpg-agent.
@end ifset
@ifset gpgtwoone
@node Agent PRESET_PASSPHRASE
@subsection Set a passphrase for a keygrip
This command adds a passphrase to the cache for the specified @var{keygrip}.
@example
PRESET_PASSPHRASE [--inquire] <string_or_keygrip> <timeout> [<hexstring>]
@end example
The passphrase is a hexidecimal string when specified. When not specified, the
passphrase will be retrieved from the pinentry module unless the
@option{--inquire} option was specified in which case the passphrase will be
retrieved from the client.
The @var{timeout} parameter keeps the passphrase cached for the specified
number of seconds. A value of @code{-1} means infinate while @code{0} means
the default (currently only a timeout of -1 is allowed, which means to never
expire it).
@end ifset
@node Agent GET_CONFIRMATION @node Agent GET_CONFIRMATION
@subsection Ask for confirmation @subsection Ask for confirmation
@ -1225,12 +1295,22 @@ option given the certificates are send back.
@subsection Change a Passphrase @subsection Change a Passphrase
@example @example
@ifset gpgtwoone
PASSWD [--cache-nonce=<c>] [--passwd-nonce=<s>] [--preset] @var{keygrip}
@end ifset
@ifclear gpgtwoone
PASSWD @var{keygrip} PASSWD @var{keygrip}
@end ifclear
@end example @end example
This command is used to interactively change the passphrase of the key This command is used to interactively change the passphrase of the key
identified by the hex string @var{keygrip}. identified by the hex string @var{keygrip}.
@ifset gpgtwoone
The @option{--preset} option may be used to add the new passphrase to the
cache using the default cache parameters.
@end ifset
@node Agent UPDATESTARTUPTTY @node Agent UPDATESTARTUPTTY
@subsection Change the standard display @subsection Change the standard display

View File

@ -388,7 +388,7 @@ safeguard against accidental deletion of multiple keys.
@item --delete-secret-key @code{name} @item --delete-secret-key @code{name}
@opindex delete-secret-key @opindex delete-secret-key
Remove key from the secret and public keyring. In batch mode the key Remove key from the secret keyring. In batch mode the key
must be specified by fingerprint. must be specified by fingerprint.
@item --delete-secret-and-public-key @code{name} @item --delete-secret-and-public-key @code{name}
@ -1293,9 +1293,7 @@ encoded in the character set as specified by
@option{--display-charset}. These options affect all following @option{--display-charset}. These options affect all following
arguments. Both options may be used multiple times. arguments. Both options may be used multiple times.
@ifset gpgone @anchor{gpg-option --options}
@anchor{option --options}
@end ifset
@item --options @code{file} @item --options @code{file}
@opindex options @opindex options
Read options from @code{file} and do not try to read them from the Read options from @code{file} and do not try to read them from the
@ -2418,7 +2416,7 @@ check. @code{value} may be any printable string; it will be encoded in
UTF8, so you should check that your @option{--display-charset} is set UTF8, so you should check that your @option{--display-charset} is set
correctly. If you prefix @code{name} with an exclamation mark (!), the correctly. If you prefix @code{name} with an exclamation mark (!), the
notation data will be flagged as critical notation data will be flagged as critical
(rfc2440:5.2.3.15). @option{--sig-notation} sets a notation for data (rfc4880:5.2.3.16). @option{--sig-notation} sets a notation for data
signatures. @option{--cert-notation} sets a notation for key signatures signatures. @option{--cert-notation} sets a notation for key signatures
(certifications). @option{--set-notation} sets both. (certifications). @option{--set-notation} sets both.
@ -2440,7 +2438,7 @@ meaningful when using the OpenPGP smartcard.
@opindex sig-policy-url @opindex sig-policy-url
@opindex cert-policy-url @opindex cert-policy-url
@opindex set-policy-url @opindex set-policy-url
Use @code{string} as a Policy URL for signatures (rfc2440:5.2.3.19). If Use @code{string} as a Policy URL for signatures (rfc4880:5.2.3.20). If
you prefix it with an exclamation mark (!), the policy URL packet will you prefix it with an exclamation mark (!), the policy URL packet will
be flagged as critical. @option{--sig-policy-url} sets a policy url for be flagged as critical. @option{--sig-policy-url} sets a policy url for
data signatures. @option{--cert-policy-url} sets a policy url for key data signatures. @option{--cert-policy-url} sets a policy url for key
@ -2611,6 +2609,26 @@ Note that this passphrase is only used if the option @option{--batch}
has also been given. This is different from @command{gpg}. has also been given. This is different from @command{gpg}.
@end ifclear @end ifclear
@ifset gpgtwoone
@item --pinentry-mode @code{mode}
@opindex pinentry-mode
Set the pinentry mode to @code{mode}. Allowed values for @code{mode}
are:
@table @asis
@item default
Use the default of the agent, which is @code{ask}.
@item ask
Force the use of the Pinentry.
@item cancel
Emulate use of Pinentry's cancel button.
@item error
Return a Pinentry error (``No Pinentry'').
@item loopback
Redirect Pinentry queries to the caller. Note that in contrast to
Pinentry the user is not prompted again if he enters a bad password.
@end table
@end ifset
@item --command-fd @code{n} @item --command-fd @code{n}
@opindex command-fd @opindex command-fd
This is a replacement for the deprecated shared-memory IPC mode. This is a replacement for the deprecated shared-memory IPC mode.
@ -2909,7 +2927,7 @@ current home directory (@pxref{option --homedir}).
This is the standard configuration file read by @command{@gpgname} on This is the standard configuration file read by @command{@gpgname} on
startup. It may contain any valid long option; the leading two dashes startup. It may contain any valid long option; the leading two dashes
may not be entered and the option may not be abbreviated. This default may not be entered and the option may not be abbreviated. This default
name may be changed on the command line (@pxref{option --options}). name may be changed on the command line (@pxref{gpg-option --options}).
You should backup this file. You should backup this file.
@end table @end table
@ -3290,21 +3308,23 @@ If you don't give any of them, no user ID is created.
@item Expire-Date: @var{iso-date}|(@var{number}[d|w|m|y]) @item Expire-Date: @var{iso-date}|(@var{number}[d|w|m|y])
Set the expiration date for the key (and the subkey). It may either Set the expiration date for the key (and the subkey). It may either
be entered in ISO date format (2000-08-15) or as number of days, be entered in ISO date format (e.g. "20000815T145012") or as number of
weeks, month or years. The special notation "seconds=N" is also days, weeks, month or years after the creation date. The special
allowed to directly give an Epoch value. Without a letter days are notation "seconds=N" is also allowed to specify a number of seconds
assumed. Note that there is no check done on the overflow of the type since creation. Without a letter days are assumed. Note that there
used by OpenPGP for timestamps. Thus you better make sure that the is no check done on the overflow of the type used by OpenPGP for
given value make sense. Although OpenPGP works with time intervals, timestamps. Thus you better make sure that the given value make
GnuPG uses an absolute value internally and thus the last year we can sense. Although OpenPGP works with time intervals, GnuPG uses an
represent is 2105. absolute value internally and thus the last year we can represent is
2105.
@item Ceation-Date: @var{iso-date} @item Ceation-Date: @var{iso-date}
Set the creation date of the key as stored in the key information and Set the creation date of the key as stored in the key information and
which is also part of the fingerprint calculation. Either a date like which is also part of the fingerprint calculation. Either a date like
"1986-04-26" or a full timestamp like "19860426T042640" may be used. "1986-04-26" or a full timestamp like "19860426T042640" may be used.
The time is considered to be UTC. If it is not given the current time The time is considered to be UTC. The special notation "seconds=N"
is used. may be used to directly specify a the number of seconds since Epoch
(Unix time). If it is not given the current time is used.
@item Preferences: @var{string} @item Preferences: @var{string}
Set the cipher, hash, and compression preference values for this key. Set the cipher, hash, and compression preference values for this key.

View File

@ -319,6 +319,7 @@ in the option file.
@table @gnupgtabopt @table @gnupgtabopt
@anchor{gpgsm-option --options}
@item --options @var{file} @item --options @var{file}
@opindex options @opindex options
Reads configuration from @var{file} instead of from the default Reads configuration from @var{file} instead of from the default
@ -760,8 +761,8 @@ current home directory (@pxref{option --homedir}).
This is the standard configuration file read by @command{gpgsm} on This is the standard configuration file read by @command{gpgsm} on
startup. It may contain any valid long option; the leading two dashes startup. It may contain any valid long option; the leading two dashes
may not be entered and the option may not be abbreviated. This default may not be entered and the option may not be abbreviated. This default
name may be changed on the command line (@pxref{option name may be changed on the command line (@pxref{gpgsm-option --options}).
--options}). You should backup this file. You should backup this file.
@item policies.txt @item policies.txt

View File

@ -659,12 +659,15 @@ an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee. copy of the Program in return for a fee.
@end enumerate
@iftex @iftex
@heading END OF TERMS AND CONDITIONS @heading END OF TERMS AND CONDITIONS
@end iftex @end iftex
@ifinfo @ifinfo
@center END OF TERMS AND CONDITIONS @center END OF TERMS AND CONDITIONS
@end ifinfo @end ifinfo
@unnumberedsec How to Apply These Terms to Your New Programs @unnumberedsec How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest If you develop a new program, and you want it to be of the greatest
@ -675,8 +678,10 @@ terms.
To do so, attach the following notices to the program. It is safest To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least state the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found. the ``copyright'' line and a pointer to where the full notice is
@smallexample found.
@example
@var{one line to give the program's name and a brief idea of what it does.} @var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) @var{year} @var{name of author} Copyright (C) @var{year} @var{name of author}
@ -692,17 +697,21 @@ General Public License for more details.
You should have received a copy of the GNU General Public License You should have received a copy of the GNU General Public License
along with this program. If not, see @url{http://www.gnu.org/licenses/}. along with this program. If not, see @url{http://www.gnu.org/licenses/}.
@end smallexample @end example
@noindent
Also add information on how to contact you by electronic and paper mail. Also add information on how to contact you by electronic and paper mail.
@noindent
If the program does terminal interaction, make it output a short If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode: notice like this when it starts in an interactive mode:
@smallexample @smallexample
@var{program} Copyright (C) @var{year} @var{name of author} @var{program} Copyright (C) @var{year} @var{name of author}
This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. This program comes with ABSOLUTELY NO WARRANTY; for details
This is free software, and you are welcome to redistribute it under certain conditions; type @samp{show c} for details. type @samp{show w}. This is free software, and you are
welcome to redistribute it under certain conditions;
type @samp{show c} for details.
@end smallexample @end smallexample
The hypothetical commands @samp{show w} and @samp{show c} should show The hypothetical commands @samp{show w} and @samp{show c} should show
@ -721,5 +730,3 @@ library, you may consider it more useful to permit linking proprietary
applications with the library. If this is what you want to do, use applications with the library. If this is what you want to do, use
the GNU Lesser General Public License instead of this License. But the GNU Lesser General Public License instead of this License. But
first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}.
@end enumerate

View File

@ -414,7 +414,7 @@ static void
start_page (char *name) start_page (char *name)
{ {
if (verbose) if (verbose)
inf ("starting page `%s'", name); inf ("starting page '%s'", name);
assert (!thepage.name); assert (!thepage.name);
thepage.name = xstrdup (name); thepage.name = xstrdup (name);
thepage.n_sections = 0; thepage.n_sections = 0;
@ -434,7 +434,7 @@ write_th (FILE *fp)
p = strrchr (name, '.'); p = strrchr (name, '.');
if (!p || !p[1]) if (!p || !p[1])
{ {
err ("no section name in man page `%s'", thepage.name); err ("no section name in man page '%s'", thepage.name);
free (name); free (name);
return -1; return -1;
} }
@ -591,7 +591,7 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
ignore_args = 1; /* Parameterized macros are not yet supported. */ ignore_args = 1; /* Parameterized macros are not yet supported. */
} }
else else
inf ("texinfo command `%s' not supported (%.*s)", command, inf ("texinfo command '%s' not supported (%.*s)", command,
((s = memchr (rest, '\n', len)), (s? (s-rest) : len)), rest); ((s = memchr (rest, '\n', len)), (s? (s-rest) : len)), rest);
} }
@ -605,7 +605,7 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
i--; i--;
if (i) if (i)
{ {
err ("closing brace for command `%s' not found", command); err ("closing brace for command '%s' not found", command);
return len; return len;
} }
if (n > 2 && !ignore_args) if (n > 2 && !ignore_args)
@ -780,13 +780,13 @@ finish_page (void)
return; /* No page active. */ return; /* No page active. */
if (verbose) if (verbose)
inf ("finishing page `%s'", thepage.name); inf ("finishing page '%s'", thepage.name);
if (opt_select) if (opt_select)
{ {
if (!strcmp (opt_select, thepage.name)) if (!strcmp (opt_select, thepage.name))
{ {
inf ("selected `%s'", thepage.name ); inf ("selected '%s'", thepage.name );
fp = stdout; fp = stdout;
} }
else else
@ -798,10 +798,10 @@ finish_page (void)
} }
else if (opt_store) else if (opt_store)
{ {
inf ("writing `%s'", thepage.name ); inf ("writing '%s'", thepage.name );
fp = fopen ( thepage.name, "w" ); fp = fopen ( thepage.name, "w" );
if (!fp) if (!fp)
die ("failed to create `%s': %s\n", thepage.name, strerror (errno)); die ("failed to create '%s': %s\n", thepage.name, strerror (errno));
} }
else else
fp = stdout; fp = stdout;
@ -1162,7 +1162,7 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
} }
if (!incfp) if (!incfp)
err ("can't open include file `%s':%s", err ("can't open include file '%s':%s",
incname, strerror (errno)); incname, strerror (errno));
else else
{ {