FreeBSD Manual Pages

home | help

pageant(1) PuTTY tool suite pageant(1)

NAME
pageant - PuTTY SSH authentication agent

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

When running as an SSH agent, it listens on a Unix-domain socket for con-
nections 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 al-
ready-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 ex-
tra 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 nei-
ther 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 re-
quired, 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-en-
cryption 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 con-
nection is lost, it will terminate. This gives it the same lifetime
as your GUI login session, so in this mode it is suitable for run-
ning from a startup script such as .xsession. The actual agent will
be a subprocess; the main Pageant process will terminate immedi-
ately, after printing environment-variable setting commands on stan-
dard output which should be installed in any process wanting to com-
municate 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 ef-
fect 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 envi-
ronment-variable commands on standard output, like -X and -T. How-
ever, 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 unex-
pectedly before it manages to happen.

--debugPageant 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 an-
other 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 ac-
tivity 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 stan-
dard format (multiple lines, starting with `---- BEGIN SSH2 PUBLIC
KEY ----').

Each key-identifier can be any of the following:

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

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

* 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 us-
ing 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 possi-
ble, 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 signa-
ture emitted on standard output (as a binary blob in the format de-
fined 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 use-
ful if you prefer Pageant's GUI prompt style, which minimises infor-
mation 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 life-
time 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 nei-
ther option is given, Pageant will guess based on whether the envi-
ronment 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 list-
ing fingerprints with -l. The available formats are sha256 (the de-
fault) 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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pageant&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages