pageant(1) PuTTY tool suite pageant(1)

NAME

pageant - PuTTY SSH authentication agent

SYNOPSIS

pageant ( -X | -T | --permanent | --debug | --foreground ) [ [ --encrypted ] key-file... ]
pageant [ [ --encrypted ] key-file... ] --exec command [ args... ]
pageant -a [ --encrypted ] key-file...
pageant ( -d | -r | --public | --public-openssh ) key-identifier...
pageant ( -D | -R )
pageant -l [ --fptype format ]
pageant --askpass prompt

DESCRIPTION

pageant is both an SSH authentication agent, and also a tool for
communicating with an already-running agent.

When running as an SSH agent, it listens on a Unix-domain socket for
connections from client processes running under your user id. Clients
can load SSH private keys into the agent, or request signatures on a
given message from a key already in the agent. This permits one-touch
authentication by SSH client programs, if Pageant is holding a key
that the server they are connecting to will accept.

pageant can also act as a client program itself, communicating with
an already-running agent to add or remove keys, list the keys, or
extract their public half.

The agent protocol used by pageant is compatible with the PuTTY tools
and also with other implementations such as OpenSSH's SSH client and
ssh-agent(1). Some pageant features are implemented with protocol
extensions, so will only work if pageant is on both ends.

To run pageant as an agent, you must provide an option to tell it
what its lifetime should be. Typically you would probably want
Pageant to last for the duration of a login session, in which case
you should use either -X or -T, depending on whether your login
session is GUI or purely terminal-based respectively. For example, in
your X session startup script you might write

eval $(pageant -X)

which will cause Pageant to start running, monitor the X server to
notice when your session terminates (and then it will terminate too),
and print on standard output some shell commands to set environment
variables that client processes will need to find the running agent.

In a terminal-based login, you could do almost exactly the same thing
but with -T:

eval $(pageant -T)

This will cause Pageant to tie its lifetime to that of your
controlling terminal: when you log out, and the terminal device
ceases to be associated with your session, Pageant will notice that
it has no controlling terminal any more, and will terminate
automatically.

In either of these modes, you can also add one or more private keys
as extra command-line arguments, e.g.

eval $(pageant -T ~/.ssh/key.ppk)

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 --gui-
prompt or --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:

eval $(pageant -T --encrypted ~/.ssh/key.ppk)

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 --debug mode.)

To use Pageant to talk to an existing agent, you can add new keys
using -a, list the current set of keys' fingerprints and comments
with -l, extract the full public half of any key using --public or
--public-openssh, delete a specific key or all keys using -d or -D
respectively, or request re-encryption of a specific key or all keys
using -r or -R respectively.

LIFETIME

The following options are called lifetime modes. They all request
Pageant to operate in agent mode; each one specifies a different
method for Pageant to start up and know when to shut down.

-X Pageant will open a connection to your X display, and when
that connection is lost, it will terminate. This gives it the
same lifetime as your GUI login session, so in this mode it is
suitable for running from a startup script such as .xsession.
The actual agent will be a subprocess; the main Pageant
process will terminate immediately, after printing
environment-variable setting commands on standard output which
should be installed in any process wanting to communicate with
the agent.

The usual approach would be to run

eval $(pageant -X)

in an X session startup script. However, other possibilities
exist, such as directing the standard output of `pageant -X'
to a file which is then sourced by any new shell.

-T Pageant will tie its lifetime to that of the login session
running on its controlling terminal, by noticing when it
ceases to have a controlling terminal (which will
automatically happen as a side effect of the session leader
process terminating). Like -X, Pageant will print environment-
variable commands on standard output.

--exec command
Pageant will run the provided command as a subprocess,
preloaded with the appropriate environment variables to access
the agent it starts up. When the subprocess terminates,
Pageant will terminate as well.

All arguments on Pageant's command line after --exec will be
treated as part of the command to run, even if they look like
other valid Pageant options or key files.

--permanent
Pageant will fork off a subprocess to be the agent, and print
environment-variable commands on standard output, like -X and
-T. However, in this case, it will make no effort to limit its
lifetime in any way; it will simply run permanently, unless
manually killed. The environment variable SSH_AGENT_PID, set
by the commands printed by Pageant, permits the agent process
to be found for this purpose.

This option is not recommended, because any method of manually
killing the agent carries the risk of the session terminating
unexpectedly before it manages to happen.

--debug
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; 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.

--foreground
Like --debug, Pageant will run in the foreground, without
forking. It will print its environment variable setup commands
on standard output. Unlike --debug, Pageant will not
automatically log agent activity to standard output, nor will
it force passphrase prompts to standard input. This is useful
if Pageant is spawned by a parent process that controls or
otherwise programmatically interfaces with Pageant.

After Pageant prints its environment setup commands, it closes
its standard output. So if the parent process has run it in a
pipe to retrieve the environment setup commands, it can simply
read until it receives EOF, instead of having to know how many
lines of output to expect.

CLIENT OPTIONS

The following options tell Pageant to operate in client mode,
contacting an existing agent via environment variables that it should
already have set.

-a key-files
Load the specified private key file(s) and add them to the
already-running agent. Unless --encrypted is also specified,
pageant will decrypt them if necessary by prompting for their
passphrases (with the same choice of user interfaces as in
agent mode).

The private key files must be in PuTTY's .ppk file format.

-l List the keys currently in the running agent. Each key's
fingerprint and comment string will be shown. (Use the -E
option to change the fingerprint format.)

Keys that will require a passphrase on their next use are
listed as `encrypted'. Keys that can be returned to this state
with -r are listed as `re-encryptable'.

--public key-identifiers
Print the public half of each specified key, in the RFC 4716
standard format (multiple lines, starting with `---- BEGIN
SSH2 PUBLIC KEY ----').

Each key-identifier can be any of the following:

+o The name of a file containing the key, either the whole
key (again in .ppk format) or just its public half.

+o The key's comment string, as shown by pageant -l.

+o Enough of one of the key's fingerprint formats to be
unique among keys currently loaded into the agent.

If Pageant can uniquely identify one key by interpreting the
key-identifier in any of these ways, it will assume that key
was the one you meant. If it cannot, you will have to specify
more detail.

If you find that your desired key-identifier string can be
validly interpreted as more than one of the above kinds of
identification, you can disambiguate by prefixing it as
follows:

`file:'
to indicate that it is a filename

`comment:'
to indicate that it is a comment string

`fp:' to indicate that it is a fingerprint; any fingerprint
format will be matched

`sha256:' or `md5:'
to indicate that it is a fingerprint of a specific
format

`sha256-cert:' or `md5-cert:'
to indicate that it is a fingerprint of a specific
format, and specifically matches the fingerprint of the
public key including a certificate if any

--public-openssh key-identifiers, -L key-identifiers
Print the public half of each specified key, in the one-line
format used by OpenSSH, suitable for putting in
.ssh/authorized_keys files.

-d key-identifiers
Delete each specified key from the agent's memory, so that the
agent will no longer serve it to clients unless it is loaded
in again using pageant -a.

-D Delete all keys from the agent's memory, leaving it completely
empty.

-r key-identifiers
`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 --encrypted option.)

(Holding encrypted keys is a Pageant extension, so this option
and -R are unlikely to work with other agents.)

-R `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 --encrypted option.)

--test-sign key-identifier


--test-sign-with-flags=flags key-identifier
Sign arbitrary data with the given key. This mode is only
likely to be useful when testing pageant itself.

The data to sign is taken from standard input, signed by the
agent with the key identified by key-identifier, and the
resulting signature emitted on standard output (as a binary
blob in the format defined by the SSH specifications).

flags is a number representing a combination of flag bits
defined by the SSH agent protocol.

SSH-ASKPASS REPLACEMENT
--askpass prompt
With this option, pageant acts as an ssh-askpass(1)
replacement, rather than performing any SSH agent
functionality. This may be useful if you prefer Pageant's GUI
prompt style, which minimises information leakage about your
passphrase length in its visual feedback, compared to other
ssh-askpass(1) implementations.

pageant --askpass implements the standard ssh-askpass(1)
interface: it can be passed a prompt to display (as a single
argument) and, if successful, prints the passphrase on
standard output and returns a zero exit status. Typically you
would use the environment variable SSH_ASKPASS to tell other
programs to use pageant in this way.

OPTIONS

-v Verbose mode. When Pageant runs in agent mode, this option
causes it to log all agent activity to its standard error. For
example, you might run

eval $(pageant -X -v 2>~/.pageant.log)

and expect a list of all signatures requested by agent clients
to build up in that log file.

The log information is the same as that produced by the
--debug lifetime option, but --debug sends it to standard
output (since that is the main point of debugging mode)
whereas -v in all other lifetime modes sends the same log data
to standard error (being a by-product of the program's main
purpose). Using -v in --debug mode has no effect: the log
still goes to standard output.

-s, -c Force Pageant to output its environment setup commands in the
style of POSIX / Bourne shells (-s) or C shells (-c)
respectively. If neither option is given, Pageant will guess
based on whether the environment variable SHELL has a value
ending in `csh'.

--symlink fixed-path
When operating in agent mode, as well as creating a uniquely
named listening socket, pageant will also create (or update) a
symbolic link at fixed-path pointing to that socket.

This allows access to an agent instance by setting the
SSH_AUTH_SOCK environment variable to fixed-path, rather than
having to use the value invented by pageant when it starts.
It's mainly expected to be useful for debugging.

--encrypted, --no-decrypt
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 `re-encrypted' with the
-r or -R client options.

The --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.)

-E fingerprint-type, --fptype fingerprint-type
Specify the fingerprint format to print. Only applicable when
listing fingerprints with -l. The available formats are sha256
(the default) and md5.

--gui-prompt, --tty-prompt
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 a key file is specified to pageant that
needs immediate decryption, and in --askpass mode.)

--help Print a brief summary of command-line options and terminate.

--version, -V
Print the version of Pageant.

-- Cause all subsequent arguments to be treated as key file
names, even if they look like options.

PuTTY tool suite 2015-05-19 pageant(1)