From 8592ab843cbaee78fc55f0aa05089d70986e16b0 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Mon, 5 Apr 2021 18:35:38 +0100 Subject: [PATCH] Pageant: docs / help for deferred decryption. Also, ensure -E/--fptype in Unix Pageant is (correctly) documented everywhere. --- doc/man-pageant.but | 120 ++++++++++++++++++++++++++++++++------------ doc/pageant.but | 12 ++++- unix/uxpgnt.c | 20 +++++--- 3 files changed, 112 insertions(+), 40 deletions(-) diff --git a/doc/man-pageant.but b/doc/man-pageant.but index 5db0799c..5e31c8b9 100644 --- a/doc/man-pageant.but +++ b/doc/man-pageant.but @@ -8,16 +8,16 @@ \S{pageant-manpage-synopsis} SYNOPSIS -\c pageant ( -X | -T | --permanent | --debug ) [ key-file... ] -\e bbbbbbb bb bb bbbbbbbbbbb bbbbbbb iiiiiiii -\c pageant [ key-file... ] --exec command [ args... ] -\e bbbbbbb iiiiiiii bbbbbb iiiiiii iiii -\c pageant -a key-file... -\e bbbbbbb bb iiiiiiii -\c pageant ( -d | --public | --public-openssh ) key-identifier... -\e bbbbbbb bb bbbbbbbb bbbbbbbbbbbbbbbb iiiiiiiiiiiiii -\c pageant -D -\e bbbbbbb bb +\c pageant ( -X | -T | --permanent | --debug ) [ [ --encrypted ] key-file... ] +\e bbbbbbb bb bb bbbbbbbbbbb bbbbbbb bbbbbbbbbbb iiiiiiii +\c pageant [ [ --encrypted ] key-file... ] --exec command [ args... ] +\e bbbbbbb bbbbbbbbb iiiiiiii bbbbbb iiiiiii iiii +\c pageant -a [ --encrypted ] key-file... +\e bbbbbbb bb bbbbbbbbbbb iiiiiiii +\c pageant ( -d | -r | --public | --public-openssh ) key-identifier... +\e bbbbbbb bb bb bbbbbbbb bbbbbbbbbbbbbbbb iiiiiiiiiiiiii +\c pageant ( -D | -R ) +\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) -and start the agent with those keys already loaded. Passphrase prompts -will use the controlling terminal if one is available, or failing that -the GUI if one of those is available. (The prompt method can be -overridden with the \cw{--gui-prompt} or \cw{--tty-prompt} options.) -If neither is available, no passphrase prompting can be done. +in which case Pageant will immediately prompt for the keys' passphrases +(if any) and start the agent with those keys already loaded in +cleartext form. Passphrase prompts will use the controlling terminal if +one is available, or failing that the GUI if one of those is available. +(The prompt method can be overridden with the \cw{--gui-prompt} or +\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 -delete all keys using \cw{-D}. +\cw{--public} or \cw{--public-openssh}, delete a specific key or +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 -by prompting for their passphrases (with the same choice of user -interfaces as in agent mode), and add them to the already-running agent. +\dd Load the specified private key file(s) and add them to the +already-running agent. Unless \cw{--encrypted} is also specified, +\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 -\cw{--fptype} opton to change the fingerprint format.) +fingerprint and comment string will be shown. (Use the \cw{-E} +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}, -and in \c{--askpass} mode.) +whenever a key file is specified to \c{pageant} that needs +immediate decryption, and in \c{--askpass} mode.) \dt \cw{--help} diff --git a/doc/pageant.but b/doc/pageant.but index e2bc88d8..d6a5b7d4 100644 --- a/doc/pageant.but +++ b/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 -\q{Re-encrypt} button in the Pageant main window. +decrypted, so that it can be used again. The main window will list +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 diff --git a/unix/uxpgnt.c b/unix/uxpgnt.c index 9f542acd..4adca625 100644 --- a/unix/uxpgnt.c +++ b/unix/uxpgnt.c @@ -183,14 +183,16 @@ static void usage(void) { printf("Pageant: SSH agent\n"); printf("%s\n", ver); - printf("Usage: pageant [key files]\n"); - printf(" pageant [key files] --exec [args]\n"); - printf(" pageant -a [key files]\n"); + printf("Usage: pageant [[--encrypted] key files]\n"); + printf(" pageant [[--encrypted] key files] --exec [args]\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 -D\n"); + printf(" pageant -l [-E fptype]\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 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)" - " do not go with an agent lifetime option\n"); + fprintf(stderr, "pageant: client key actions (-a, -d, -D, -r, -R, " + "-l, -L) do not go with an agent lifetime option\n"); exit(1); } if (!has_lifetime && has_agent_actions) {