Update docs from master.
authorWerner Koch <wk@gnupg.org>
Thu, 18 Apr 2013 12:40:43 +0000 (14:40 +0200)
committerWerner Koch <wk@gnupg.org>
Mon, 22 Apr 2013 15:29:57 +0000 (17:29 +0200)
* 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
doc/gpg.texi
doc/gpgsm.texi
doc/gpl.texi
doc/yat2m.c

index 4c7f13f..dcd96fb 100644 (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
 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] [<cache_nonce>]
+@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] <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
 @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=<c>] [--passwd-nonce=<s>] [--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
index 420326b..cec4581 100644 (file)
@@ -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.
index bdb0378..6a84391 100644 (file)
@@ -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
index 7f9a48a..d13e9e4 100644 (file)
@@ -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
index a22176c..5dc81bf 100644 (file)
@@ -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
                 {