From 681338bfd344f6928e1e3037c948c46c2e589bd3 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Thu, 18 Apr 2013 14:40:43 +0200 Subject: [PATCH] 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) --- doc/gpg-agent.texi | 80 ++++++++++++++++++++++++++++++++++++++++++++++ doc/gpg.texi | 54 +++++++++++++++++++++---------- doc/gpgsm.texi | 5 +-- doc/gpl.texi | 27 ++++++++++------ doc/yat2m.c | 18 +++++------ 5 files changed, 146 insertions(+), 38 deletions(-) diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi index 4c7f13f33..dcd96fb33 100644 --- a/doc/gpg-agent.texi +++ b/doc/gpg-agent.texi @@ -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 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 * Agent PKDECRYPT:: Decrypting a session key * Agent PKSIGN:: Signing a Hash @@ -804,6 +812,10 @@ secret keys. * Agent EXPORT:: Exporting a Secret Key * Agent ISTRUSTED:: Importing a Root Certificate * 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 HAVEKEY:: Check whether a key is available * 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. @example +@ifset gpgtwoone + GENKEY [--no-protection] [--preset] [] +@end ifset +@ifclear gpgtwoone GENKEY +@end ifclear @end example Invokes the key generation process and the server will then inquire @@ -1017,6 +1034,13 @@ Here is an example session: S OK key created @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 @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. + +@node Agent CLEAR_PASSPHRASE +@subsection Remove a cached passphrase + +Use this command to remove a cached passphrase. + +@example +@ifset gpgtwoone + CLEAR_PASSPHRASE [--mode=normal] +@end ifset +@ifclear gpgtwoone + CLEAR_PASSPHRASE +@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] [] +@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 @subsection Ask for confirmation @@ -1225,12 +1295,22 @@ option given the certificates are send back. @subsection Change a Passphrase @example +@ifset gpgtwoone + PASSWD [--cache-nonce=] [--passwd-nonce=] [--preset] @var{keygrip} +@end ifset +@ifclear gpgtwoone PASSWD @var{keygrip} +@end ifclear @end example This command is used to interactively change the passphrase of the key 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 @subsection Change the standard display diff --git a/doc/gpg.texi b/doc/gpg.texi index 420326b5d..cec458158 100644 --- a/doc/gpg.texi +++ b/doc/gpg.texi @@ -388,7 +388,7 @@ safeguard against accidental deletion of multiple keys. @item --delete-secret-key @code{name} @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. @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 arguments. Both options may be used multiple times. -@ifset gpgone -@anchor{option --options} -@end ifset +@anchor{gpg-option --options} @item --options @code{file} @opindex options 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 correctly. If you prefix @code{name} with an exclamation mark (!), the 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 (certifications). @option{--set-notation} sets both. @@ -2440,7 +2438,7 @@ meaningful when using the OpenPGP smartcard. @opindex sig-policy-url @opindex cert-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 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 @@ -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}. @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} @opindex command-fd 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 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 - 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. @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]) 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, -weeks, month or years. The special notation "seconds=N" is also -allowed to directly give an Epoch value. Without a letter days are -assumed. Note that there is no check done on the overflow of the type -used by OpenPGP for timestamps. Thus you better make sure that the -given value make sense. Although OpenPGP works with time intervals, -GnuPG uses an absolute value internally and thus the last year we can -represent is 2105. +be entered in ISO date format (e.g. "20000815T145012") or as number of +days, weeks, month or years after the creation date. The special +notation "seconds=N" is also allowed to specify a number of seconds +since creation. Without a letter days are assumed. Note that there +is no check done on the overflow of the type used by OpenPGP for +timestamps. Thus you better make sure that the given value make +sense. Although OpenPGP works with time intervals, GnuPG uses an +absolute value internally and thus the last year we can represent is +2105. @item Ceation-Date: @var{iso-date} 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 "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 -is used. +The time is considered to be UTC. The special notation "seconds=N" +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} Set the cipher, hash, and compression preference values for this key. diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi index bdb03783e..6a84391e3 100644 --- a/doc/gpgsm.texi +++ b/doc/gpgsm.texi @@ -319,6 +319,7 @@ in the option file. @table @gnupgtabopt +@anchor{gpgsm-option --options} @item --options @var{file} @opindex options 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 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 -name may be changed on the command line (@pxref{option - --options}). You should backup this file. +name may be changed on the command line (@pxref{gpgsm-option --options}). +You should backup this file. @item policies.txt diff --git a/doc/gpl.texi b/doc/gpl.texi index 7f9a48a13..d13e9e4ab 100644 --- a/doc/gpl.texi +++ b/doc/gpl.texi @@ -228,7 +228,7 @@ terms of section 4, provided that you also meet all of these conditions: @enumerate a -@item +@item The work must carry prominent notices stating that you modified it, and giving a relevant date. @@ -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 copy of the Program in return for a fee. +@end enumerate + @iftex @heading END OF TERMS AND CONDITIONS @end iftex @ifinfo @center END OF TERMS AND CONDITIONS @end ifinfo + @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 @@ -675,9 +678,11 @@ terms. 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 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. -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} +the ``copyright'' line and a pointer to where the full notice is +found. + +@example +@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} This program is free software: you can redistribute it and/or modify @@ -692,17 +697,21 @@ General Public License for more details. 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/}. -@end smallexample +@end example +@noindent 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 notice like this when it starts in an interactive mode: @smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; 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. +@var{program} Copyright (C) @var{year} @var{name of author} +This program comes with ABSOLUTELY NO WARRANTY; 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 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 the GNU Lesser General Public License instead of this License. But first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. - -@end enumerate diff --git a/doc/yat2m.c b/doc/yat2m.c index a22176cd4..5dc81bf59 100644 --- a/doc/yat2m.c +++ b/doc/yat2m.c @@ -414,7 +414,7 @@ static void start_page (char *name) { if (verbose) - inf ("starting page `%s'", name); + inf ("starting page '%s'", name); assert (!thepage.name); thepage.name = xstrdup (name); thepage.n_sections = 0; @@ -434,7 +434,7 @@ write_th (FILE *fp) p = strrchr (name, '.'); 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); 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. */ } 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); } @@ -605,7 +605,7 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len, i--; if (i) { - err ("closing brace for command `%s' not found", command); + err ("closing brace for command '%s' not found", command); return len; } if (n > 2 && !ignore_args) @@ -780,13 +780,13 @@ finish_page (void) return; /* No page active. */ if (verbose) - inf ("finishing page `%s'", thepage.name); + inf ("finishing page '%s'", thepage.name); if (opt_select) { if (!strcmp (opt_select, thepage.name)) { - inf ("selected `%s'", thepage.name ); + inf ("selected '%s'", thepage.name ); fp = stdout; } else @@ -798,10 +798,10 @@ finish_page (void) } else if (opt_store) { - inf ("writing `%s'", thepage.name ); + inf ("writing '%s'", thepage.name ); fp = fopen ( thepage.name, "w" ); 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 fp = stdout; @@ -1162,7 +1162,7 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause) } if (!incfp) - err ("can't open include file `%s':%s", + err ("can't open include file '%s':%s", incname, strerror (errno)); else {