Pageant: docs / help for deferred decryption.

Also, ensure -E/--fptype in Unix Pageant is (correctly) documented
everywhere.

doc/man-pageant.but

@@ -8,16 +8,16 @@
 
 \S{pageant-manpage-synopsis} SYNOPSIS
 
-\c pageant ( -X | -T | --permanent | --debug ) [ key-file... ]
+\c pageant ( -X | -T | --permanent | --debug ) [ [ --encrypted ] key-file... ]
-\e bbbbbbb   bb   bb   bbbbbbbbbbb   bbbbbbb     iiiiiiii
+\e bbbbbbb   bb   bb   bbbbbbbbbbb   bbbbbbb       bbbbbbbbbbb   iiiiiiii
-\c pageant [ key-file... ] --exec command [ args... ]
+\c pageant [ [ --encrypted ] key-file... ] --exec command [ args... ]
-\e bbbbbbb   iiiiiiii      bbbbbb iiiiiii   iiii
+\e bbbbbbb       bbbbbbbbb   iiiiiiii      bbbbbb iiiiiii   iiii
-\c pageant -a key-file...
+\c pageant -a [ --encrypted ] key-file...
-\e bbbbbbb bb iiiiiiii
+\e bbbbbbb bb   bbbbbbbbbbb   iiiiiiii
-\c pageant ( -d | --public | --public-openssh ) key-identifier...
+\c pageant ( -d | -r | --public | --public-openssh ) key-identifier...
-\e bbbbbbb   bb   bbbbbbbb   bbbbbbbbbbbbbbbb   iiiiiiiiiiiiii
+\e bbbbbbb   bb   bb   bbbbbbbb   bbbbbbbbbbbbbbbb   iiiiiiiiiiiiii
-\c pageant -D
+\c pageant ( -D | -R )
-\e bbbbbbb bb
+\e bbbbbbb   bb   bb
 \c pageant -l [ --fptype format ]
 \e bbbbbbb bb   bbbbbbbb iiiiii
 \c pageant --askpass prompt
@@ -41,7 +41,8 @@ extract their public half.
 
 The agent protocol used by \c{pageant} is compatible with the PuTTY
 tools and also with other implementations such as OpenSSH's SSH client
-and \e{ssh-agent(1)}.
+and \e{ssh-agent(1)}. Some \c{pageant} features are implemented with
+protocol extensions, so will only work if \c{pageant} is on both ends.
 
 To run \c{pageant} as an agent, you must provide an option to tell it
 what its \e{lifetime} should be. Typically you would probably want
@@ -75,18 +76,32 @@ extra command-line arguments, e.g.
 \c eval $(pageant -T ~/.ssh/key.ppk)
 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
 
-in which case Pageant will prompt for the keys' passphrases (if any)
+in which case Pageant will immediately prompt for the keys' passphrases
-and start the agent with those keys already loaded. Passphrase prompts
+(if any) and start the agent with those keys already loaded in
-will use the controlling terminal if one is available, or failing that
+cleartext form. Passphrase prompts will use the controlling terminal if
-the GUI if one of those is available. (The prompt method can be
+one is available, or failing that the GUI if one of those is available.
-overridden with the \cw{--gui-prompt} or \cw{--tty-prompt} options.)
+(The prompt method can be overridden with the \cw{--gui-prompt} or
-If neither is available, no passphrase prompting can be done.
+\cw{--tty-prompt} options.) If neither is available, no passphrase
+prompting can be done.
+
+Alternatively, you can start an agent with keys stored in encrypted
+form:
+
+\c eval $(pageant -T --encrypted ~/.ssh/key.ppk)
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+
+In this case, Pageant will not prompt for a passphrase at startup;
+instead, it will prompt the first time a client tries to use the key.
+(Pageant will need access to a GUI so that it can pop up a passphrase
+prompt when required, unless it's running in \cw{--debug} mode.)
 
 To use Pageant to talk to an existing agent, you can add new keys
 using \cw{-a}, list the current set of keys' fingerprints and comments
 with \cw{-l}, extract the full public half of any key using
-\cw{--public} or \cw{--public-openssh}, delete a key using \cw{-d}, or
+\cw{--public} or \cw{--public-openssh}, delete a specific key or
-delete all keys using \cw{-D}.
+all keys using \cw{-d} or \cw{-D} respectively, or request
+re-encryption of a specific key or all keys using \cw{-r} or \cw{-R}
+respectively.
 
 \S{pageant-manpage-lifetime} LIFETIME
 
@@ -163,7 +178,8 @@ before it manages to happen.
 
 \dd Pageant will run in the foreground, without forking. It will print
 its environment variable setup commands on standard output, and then it
-will log all agent activity to standard output as well. This is useful
+will log all agent activity to standard output as well; any passphrase
+prompts will need to be answered on standard input. This is useful
 for debugging what Pageant itself is doing, or what another process is
 doing to it.
 
@@ -175,21 +191,27 @@ already have set.
 
 \dt \cw{-a} \e{key-files}
 
-\dd Load the specified private key file(s), decrypt them if necessary
+\dd Load the specified private key file(s) and add them to the
-by prompting for their passphrases (with the same choice of user
+already-running agent. Unless \cw{--encrypted} is also specified,
-interfaces as in agent mode), and add them to the already-running agent.
+\c{pageant} will decrypt them if necessary by prompting for their
+passphrases (with the same choice of user interfaces as in agent
+mode).
 
 \lcont{
-
 The private key files must be in PuTTY's \cw{.ppk} file format.
-
 }
 
 \dt \cw{-l}
 
 \dd List the keys currently in the running agent. Each key's
-fingerprint and comment string will be shown. (Use the
+fingerprint and comment string will be shown. (Use the \cw{-E}
-\cw{--fptype} opton to change the fingerprint format.)
+option to change the fingerprint format.)
+
+\lcont{
+Keys that will require a passphrase on their next use are listed as
+\q{encrypted}. Keys that can be returned to this state with \cw{-r}
+are listed as \q{re-encryptable}.
+}
 
 \dt \cw{--public} \e{key-identifiers}
 
@@ -253,6 +275,25 @@ using \cw{pageant -a}.
 \dd Delete all keys from the agent's memory, leaving it completely
 empty.
 
+\dt \cw{-r} \e{key-identifiers}
+
+\dd \q{Re-encrypt} each specified key in the agent's memory -
+that is, forget any cleartext version, so that the user will be
+prompted for a passphrase again next time the key is used.
+(For this to be possible, the key must previously have been added
+with the \cw{--encrypted} option.)
+
+\lcont{
+(Holding encrypted keys is a Pageant extension, so this option and
+\cw{-R} are unlikely to work with other agents.)
+}
+
+\dt \cw{-R}
+
+\dd \q{Re-encrypt} all possible keys in the agent's memory.
+(This may leave some keys in cleartext, if they were not previously
+added with the \cw{--encrypted} option.)
+
 \S{pageant-manpage-askpass} SSH-ASKPASS REPLACEMENT
 
 \dt \cw{--askpass} \e{prompt}
@@ -308,18 +349,35 @@ respectively. If neither option is given, Pageant will guess based on
 whether the environment variable \cw{SHELL} has a value ending in
 \cq{csh}.
 
-\dt \cw{--fptype sha256}, \cw{--fptype md5}
+\dt \cw{--encrypted}, \cw{--no-decrypt}
+
+\dd When adding keys to the agent (at startup or later), keep them
+in encrypted form until the first attempt to use them; the user will
+be prompted for a passphrase then. Once decrypted, a key that was
+added in this way can be \q{re-encrypted} with the \cw{-r} or \cw{-R}
+client options.
+
+\lcont{
+The \cw{--encrypted} option makes no difference for key files which
+do not have a passphrase.
+
+(Storing keys in encrypted form is a Pageant extension; other agent
+implementations are unlikely to support it.)
+}
+
+\dt \cw{-E} \e{fingerprint-type}, \cw{--fptype} \e{fingerprint-type}
 
 \dd Specify the fingerprint format to print. Only applicable when
-listing fingerprints with \cw{-l}.
+listing fingerprints with \cw{-l}. The available formats are
+\cw{sha256} (the default) and \cw{md5}.
 
 \dt \cw{--gui-prompt}, \cw{--tty-prompt}
 
 \dd Force Pageant to prompt for key passphrases with a particular
 method (GUI or terminal) rather than trying to guess the most
 appropriate method as described above. (These options are relevant
-whenever an encrypted key filename is specified to \c{pageant},
+whenever a key file is specified to \c{pageant} that needs
-and in \c{--askpass} mode.)
+immediate decryption, and in \c{--askpass} mode.)
 
 \dt \cw{--help}
 

doc/pageant.but

@@ -91,6 +91,9 @@ less secure and should be avoided for comparison purposes where possible.
 
 \b The comment attached to the key.
 
+\b The state of deferred decryption, if enabled for this key.
+See \k{pageant-deferred-decryption}.
+
 \S{pageant-mainwin-addkey} The \q{Add Key} button
 
 To add a key to Pageant by reading it out of a local disk file,
@@ -148,6 +151,9 @@ passphrases on startup.
 If Pageant is already running, this syntax loads keys into the
 existing Pageant.
 
+You can specify the \cq{--encrypted} option to defer decryption of
+these keys; see \k{pageant-deferred-decryption}.
+
 \S{pageant-cmdline-command} Making Pageant run another program
 
 You can arrange for Pageant to start another program once it has
@@ -258,8 +264,10 @@ example:
 \c C:\PuTTY\pageant.exe --encrypted d:\main.ppk
 
 After a key has been decrypted for the first use, it remains
-decrypted, so that it can be used again. You can do this using the
+decrypted, so that it can be used again. The main window will list
-\q{Re-encrypt} button in the Pageant main window.
+the key with \q{(\i{re-encryptable})} after it. You can revert it
+to the previous state, where a passphrase is required, using the
+\q{\i{Re-encrypt}} button in the Pageant main window.
 
 \s{CAUTION}: When Pageant displays a prompt to decrypt an
 already-loaded key, it cannot give keyboard focus to the prompt dialog

unix/uxpgnt.c

@@ -183,14 +183,16 @@ static void usage(void)
 {
     printf("Pageant: SSH agent\n");
     printf("%s\n", ver);
-    printf("Usage: pageant <lifetime> [key files]\n");
+    printf("Usage: pageant <lifetime> [[--encrypted] key files]\n");
-    printf("       pageant [key files] --exec <command> [args]\n");
+    printf("       pageant [[--encrypted] key files] --exec <command> [args]\n");
-    printf("       pageant -a [key files]\n");
+    printf("       pageant -a [--encrypted] [key files]\n");
     printf("       pageant -d [key identifiers]\n");
+    printf("       pageant -D\n");
+    printf("       pageant -r [key identifiers]\n");
+    printf("       pageant -R\n");
     printf("       pageant --public [key identifiers]\n");
     printf("       pageant ( --public-openssh | -L ) [key identifiers]\n");
-    printf("       pageant -l\n");
+    printf("       pageant -l [-E fptype]\n");
-    printf("       pageant -D\n");
     printf("Lifetime options, for running Pageant as an agent:\n");
     printf("  -X           run with the lifetime of the X server\n");
     printf("  -T           run with the lifetime of the controlling tty\n");
@@ -204,9 +206,13 @@ static void usage(void)
     printf("  --public-openssh, -L   print public keys in OpenSSH format\n");
     printf("  -d           delete key(s) from the agent\n");
     printf("  -D           delete all keys from the agent\n");
+    printf("  -r           re-encrypt keys in the agent (forget cleartext\n");
+    printf("  -R           re-encrypt all possible keys in the agent\n");
     printf("Other options:\n");
     printf("  -v           verbose mode (in agent mode)\n");
     printf("  -s -c        force POSIX or C shell syntax (in agent mode)\n");
+    printf("  --encrypted  when adding keys, don't decrypt\n");
+    printf("  -E alg, --fptype alg   fingerprint type for -l (sha256, md5)\n");
     printf("  --tty-prompt force tty-based passphrase prompt\n");
     printf("  --gui-prompt force GUI-based passphrase prompt\n");
     printf("  --askpass <prompt>   behave like a standalone askpass program\n");
@@ -1507,8 +1513,8 @@ int main(int argc, char **argv)
             has_lifetime = true;
 
         if (has_lifetime && has_client_actions) {
-            fprintf(stderr, "pageant: client key actions (-a, -d, -D, -l, -L)"
+            fprintf(stderr, "pageant: client key actions (-a, -d, -D, -r, -R, "
-                    " do not go with an agent lifetime option\n");
+                    "-l, -L) do not go with an agent lifetime option\n");
             exit(1);
         }
         if (!has_lifetime && has_agent_actions) {