nhyatt/putty-source
1
0
Fork 0
mirror of https://git.tartarus.org/simon/putty.git synced 2025-01-09 09:27:59 +00:00
Code Issues Projects Releases Wiki Activity

Pageant: docs / help for deferred decryption.

Browse Source 
Also, ensure -E/--fptype in Unix Pageant is (correctly) documented
everywhere.
This commit is contained in:
Jacob Nevins 2021-04-05 18:35:38 +01:00
parent 909ab05b96
commit 8592ab843c
3 changed files with 112 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
doc/man-pageant.but
View File

@ -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}

12
doc/pageant.but
View File

@ -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

20
unix/uxpgnt.c
View File

@ -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(" pageant [key files] --exec <command> [args]\n");
printf(" pageant -a [key files]\n");
printf("Usage: pageant <lifetime> [[--encrypted] key files]\n");
printf(" pageant [[--encrypted] key files] --exec <command> [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 <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)"
" 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) {