putty-source/doc/pageant.but

\C{pageant} Using \i{Pageant} for authentication

Pageant is an SSH \i{authentication agent}. It holds your \i{private key}s
in memory, already decoded, so that you can use them often
\I{passwordless login}without needing to type a \i{passphrase}.

\H{pageant-start} Getting started with Pageant

Before you run Pageant, you need to have a private key in \c{*.\i{PPK}}
format. See \k{pubkey} to find out how to generate and use one.

When you run Pageant, it will put an icon of a computer wearing a
hat into the \ii{System tray}. It will then sit and do nothing, until you
load a private key into it. (You may need to use Windows'
\q{Show hidden icons} arrow to see the Pageant icon.)

If you click the Pageant icon with the right mouse button, you will
see a menu. Select \q{View Keys} from this menu. The Pageant main
window will appear. (You can also bring this window up by
double-clicking on the Pageant icon.)

The Pageant window contains a list box. This shows the private keys
Pageant is holding. When you start Pageant, it has no keys, so the
list box will be empty. After you add one or more keys, they will
show up in the list box.

To add a key to Pageant, press the \q{Add Key} button. Pageant will
bring up a file dialog, labelled \q{Select Private Key File}. Find
your private key file in this dialog, and press \q{Open}.

Pageant will now load the private key. If the key is protected by a
passphrase, Pageant will ask you to type the passphrase. When the
key has been loaded, it will appear in the list in the Pageant
window.

Now start PuTTY and open an SSH session to a site that accepts your
key. PuTTY will notice that Pageant is running, retrieve the key
automatically from Pageant, and use it to authenticate. You can now
open as many PuTTY sessions as you like without having to type your
passphrase again.

(PuTTY can be configured not to try to use Pageant, but it will try
by default. See \k{config-ssh-tryagent} and
\k{using-cmdline-agentauth} for more information.)

When you want to shut down Pageant, click the right button on the
Pageant icon in the System tray, and select \q{Exit} from the menu.
Closing the Pageant main window does \e{not} shut down Pageant.

If you want Pageant to stay running but forget all the keys it has
acquired, select \q{Remove All Keys} from the System tray menu.

\H{pageant-mainwin} The Pageant main window

The Pageant main window appears when you left-click on the Pageant
system tray icon, or alternatively right-click and select \q{View
Keys} from the menu. You can use it to keep track of what keys are
currently loaded into Pageant, and to add new ones or remove the
existing keys.

\S{pageant-mainwin-keylist} The key list box

The large list box in the Pageant main window lists the private keys
that are currently loaded into Pageant. The list might look
something like this:

\c Ed25519    SHA256:TddlQk20DVs4LRcAsIfDN9pInKpY06D+h4kSHwWAj4w
\c RSA  2048  SHA256:8DFtyHm3kQihgy52nzX96qMcEVOq7/yJmmwQQhBWYFg

For each key, the list box will tell you:

\b The type of the key. Currently, this can be
\q{RSA} (an RSA key for use with the SSH-2 protocol),
\q{DSA} (a DSA key for use with the SSH-2 protocol),
\q{\i{NIST}} (an ECDSA key for use with the SSH-2 protocol),
\q{Ed25519} (an Ed25519 key for use with the SSH-2 protocol),
\q{Ed448} (an Ed448 key for use with the SSH-2 protocol),
or \q{SSH-1} (an RSA key for use with the old SSH-1 protocol).
(If the key has an associated certificate, this is shown here with a
\q{cert} suffix.)

\b The size (in bits) of the key, for key types that come in different
sizes. (For ECDSA \q{NIST} keys, this is indicated as \q{p256} or
\q{p384} or \q{p521}.)

\b The \I{key fingerprint}fingerprint for the public key. This should be
the same fingerprint given by PuTTYgen, and (hopefully) also the same
fingerprint shown by remote utilities such as \i\c{ssh-keygen} when
applied to your \c{authorized_keys} file.

\lcont{
For SSH-2 keys, by default this is shown in the \q{SHA256} format. You
can change to the older \q{MD5} format (which looks like \c{aa:bb:cc:...})
with the \q{Fingerprint type} drop-down, but bear in mind that this
format is less secure and should be avoided for comparison purposes
where possible.

If some of the keys loaded into Pageant have certificates attached,
then Pageant will default to showing the fingerprint of the underlying
key. This way, a certified and uncertified version of the same key
will have the same fingerprint, so you can see that they match. You
can instead use the \q{Fingerprint type} drop-down to ask for a
different fingerprint to be shown for certified keys, which includes
the certificate as part of the fingerprinted data. That way you can
tell two certificates apart.
}

\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,
press the \q{Add Key} button in the Pageant main window, or
alternatively right-click on the Pageant icon in the system tray and
select \q{Add Key} from there.

Pageant will bring up a file dialog, labelled \q{Select Private Key
File}. Find your private key file in this dialog, and press
\q{Open}. If you want to add more than one key at once, you can
select multiple files using Shift-click (to select several adjacent
files) or Ctrl-click (to select non-adjacent files).

Pageant will now load the private key(s). If a key is protected by a
passphrase, Pageant will ask you to type the passphrase.

(This is not the only way to add a private key to Pageant. You can
also add one from a remote system by using agent forwarding; see
\k{pageant-forward} for details.)

\S{pageant-mainwin-remkey} The \q{Remove Key} button

If you need to remove a key from Pageant, select that key in the
list box, and press the \q{Remove Key} button. Pageant will remove
the key from its memory.

You can apply this to keys you added using the \q{Add Key} button,
or to keys you added remotely using agent forwarding (see
\k{pageant-forward}); it makes no difference.

\H{pageant-cmdline} The Pageant command line

Pageant can be made to do things automatically when it starts up, by
\I{command-line arguments}specifying instructions on its command line.
If you're starting Pageant from the Windows GUI, you can arrange this
by editing the properties of the \i{Windows shortcut} that it was
started from.

If Pageant is already running, invoking it again with the options
below causes actions to be performed with the existing instance, not a
new one.

\S{pageant-cmdline-loadkey} Making Pageant automatically load keys
on startup

Pageant can automatically load one or more private keys when it
starts up, if you provide them on the Pageant command line. Your
command line might then look like:

\c C:\PuTTY\pageant.exe d:\main.ppk d:\secondary.ppk

If the keys are stored encrypted, Pageant will request the
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
initialised itself and loaded any keys specified on its command
line. This program (perhaps a PuTTY, or a WinCVS making use of
Plink, or whatever) will then be able to use the keys Pageant has
loaded.

You do this by specifying the \I{-c-pageant}\c{-c} option followed
by the command, like this:

\c C:\PuTTY\pageant.exe d:\main.ppk -c C:\PuTTY\putty.exe

\S{pageant-cmdline-openssh} Integrating with \i{Windows OpenSSH}

Windows's own port of OpenSSH uses the same mechanism as Pageant to
talk to its SSH agent (Windows named pipes). This means that Windows
OpenSSH can talk directly to Pageant, if it knows where to find
Pageant's named pipe.

When Pageant starts up, it can optionally write out a file containing
an OpenSSH configuration directive that tells the Windows \c{ssh.exe}
where to find Pageant. If you include this file from your Windows SSH
configuration, then \c{ssh.exe} should automatically use Pageant as
its agent, so that you can keep your keys in one place and have both
SSH clients able to use them.

The option is \i\c{--openssh-config}, and you follow it with a filename.

To refer to this file from your main OpenSSH configuration, you can
use the \cq{Include} directive. For example, you might run Pageant
like this (with your own username substituted, of course):

\c pageant --openssh-config C:\Users\Simon\.ssh\pageant.conf

and then add a directive like this to your main \cq{.ssh\\config} file
(assuming that lives in the same directory that you just put
\cw{pageant.conf}):

\c Include pageant.conf

\s{Note}: this technique only works with \e{Windows's} port of
OpenSSH, which lives at \cw{C:\\Windows\\System32\\OpenSSH\\ssh.exe}
if you have it installed. (If not, it can be installed as a Windows
optional feature, e.g., via Settings > Apps & features > Optional
features > Add a feature > OpenSSH Client.)

There are other versions of OpenSSH for Windows, notably the one that
comes with Windows \cw{git}. Those will likely not work with the same
configuration, because they tend to depend on Unix emulation layers
like MinGW or MSys, so they won't speak Windows native pathname syntax
or understand named pipes. The above instructions will only work with
Windows's own version of OpenSSH.

So, if you want to use Windows \cw{git} with an SSH key held in
Pageant, you'll have to set the environment variable \cw{GIT_SSH}, to
point at a different program. You could point it at
\cw{c:\\Windows\\System32\\OpenSSH\\ssh.exe} once you've done this
setup \dash but it's just as easy to point it at Plink!

\S{pageant-cmdline-unix} Unix-domain sockets: integrating with WSL 1

Pageant can listen on the WinSock implementation of \q{Unix-domain
sockets}. These interoperate with the Unix-domain sockets found in the
original Windows Subsystem for Linux (now known as WSL 1). So if you
ask Pageant to listen on one of these, then your WSL 1 processes can
talk directly to Pageant.

To configure this, run Pageant with the option \c{--unix}, followed
with a pathname. Then, in WSL 1, set the environment variable
\cw{SSH_AUTH_SOCK} to point at the WSL translation of that pathname.

For example, you might run

\c pageant --unix C:\Users\Simon\.ssh\agent.sock

and in WSL 1, set the environment variable

\c SSH_AUTH_SOCK=/mnt/c/Users/Simon/.ssh/agent.sock

Alternatively, you can add a line to your \cw{.ssh/config} file inside
WSL that says

\c IdentityAgent /mnt/c/Users/Simon/.ssh/agent.sock

although doing it like that may mean that \cw{ssh-add} commands won't
find the agent, even though \cw{ssh} itself will.

\s{Security note}: Unix-domain sockets are protected against access by
other users by the file protections on their containing directory. So
if your Windows machine is multiuser, make sure you create the socket
inside a directory that other users can't access at all. (In fact,
that's a good idea on general principles.)

\s{Compatibility note}: WSL 2 processes cannot talk to Pageant by this
mechanism, because WSL 2's Unix-domain sockets are managed by a
separate Linux kernel, and not by the same kernel that WinSock talks
to.

\S{pageant-cmdline-keylist} Starting with the key list visible

Start Pageant with the \i\c{--keylist} option to show the main window
as soon as it starts up.

\S{pageant-cmdline-restrict-acl} Restricting the \i{Windows process ACL}

Pageant supports the same \i\c{-restrict-acl} option as the other
PuTTY utilities to lock down the Pageant process's access control;
see \k{using-cmdline-restrict-acl} for why you might want to do this.

By default, if Pageant is started with \c{-restrict-acl}, it won't
pass this to any PuTTY sessions started from its System Tray submenu.
Use \c{-restrict-putty-acl} to change this. (Again, see
\k{using-cmdline-restrict-acl} for details.)

\H{pageant-forward} Using \i{agent forwarding}

Agent forwarding is a mechanism that allows applications on your SSH
server machine to talk to the agent on your client machine.

Note that at present, whether agent forwarding in SSH-2 is available
depends on your server. Pageant's protocol is compatible with the
\i{OpenSSH} server, but the \i\cw{ssh.com} server uses a different
agent protocol, which PuTTY does not yet support.

To enable agent forwarding, first start Pageant. Then set up a PuTTY
SSH session in which \q{Allow agent forwarding} is enabled (see
\k{config-ssh-agentfwd}). Open the session as normal. (Alternatively,
you can use the \c{-A} command line option; see
\k{using-cmdline-agent} for details.)

If this has worked, your applications on the server should now have
access to a Unix domain socket which the SSH server will forward
back to PuTTY, and PuTTY will forward on to the agent. To check that
this has actually happened, you can try this command on Unix server
machines:

\c unixbox:~$ echo $SSH_AUTH_SOCK
\c /tmp/ssh-XXNP18Jz/agent.28794
\c unixbox:~$

If the result line comes up blank, agent forwarding has not been
enabled at all.

Now if you run \c{ssh} on the server and use it to connect through
to another server that accepts one of the keys in Pageant, you
should be able to log in without a password:

\c unixbox:~$ ssh -v otherunixbox
\c [...]
\c debug: next auth method to try is publickey
\c debug: userauth_pubkey_agent: trying agent key my-putty-key
\c debug: ssh-userauth2 successful: method publickey
\c [...]

If you enable agent forwarding on \e{that} SSH connection as well
(see the manual for your server-side SSH client to find out how to
do this), your authentication keys will still be available on the
next machine you connect to - two SSH connections away from where
they're actually stored.

In addition, if you have a private key on one of the SSH servers,
you can send it all the way back to Pageant using the local
\i\c{ssh-add} command:

\c unixbox:~$ ssh-add ~/.ssh/id_rsa
\c Need passphrase for /home/fred/.ssh/id_rsa
\c Enter passphrase for /home/fred/.ssh/id_rsa:
\c Identity added: /home/fred/.ssh/id_rsa (/home/simon/.ssh/id_rsa)
\c unixbox:~$

and then it's available to every machine that has agent forwarding
available (not just the ones downstream of the place you added it).

\H{pageant-deferred-decryption} Loading keys without decrypting them

You can add keys to Pageant \e{without} decrypting them. The key
file will be held in Pageant's memory still encrypted, and when a
client program first tries to use the key, Pageant will display a
dialog box prompting for the passphrase so that the key can be
decrypted.

This works the same way whether the key is used by an instance of
PuTTY running locally, or a remote client connecting to Pageant
through agent forwarding.

To add a key to Pageant in this encrypted form, press the \q{Add Key
(encrypted)} button in the Pageant main window, or alternatively
right-click on the Pageant icon in the system tray and select \q{Add
Key (encrypted)} from there. Pageant will bring up a file dialog, in
just the same way as it would for the plain \q{Add Key} button. But it
won't ask for a passphrase. Instead, the key will be listed in the
main window with \q{(encrypted)} after it.

To start Pageant up in the first place with encrypted keys loaded into
it, you can use the \cq{--encrypted} option on the command line. For
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. 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.

You can also \q{re-encrypt} all keys that were added encrypted by
choosing \q{Re-encrypt All Keys} from the System tray menu.
(Note that this does \e{not} discard cleartext keys that were not
previously added encrypted!)

\s{CAUTION}: When Pageant displays a prompt to decrypt an
already-loaded key, it cannot give keyboard focus to the prompt dialog
box. As far as I know this is a deliberate defensive measure by
Windows, against malicious software. So make sure you click in the
prompt window before typing your passphrase, or else the passphrase
might be sent to somewhere you didn't want to trust with it!

\H{pageant-security} Security considerations

\I{security risk}Using Pageant for public-key authentication gives you the
convenience of being able to open multiple SSH sessions without
having to type a passphrase every time, but also gives you the
security benefit of never storing a decrypted private key on disk.
Many people feel this is a good compromise between security and
convenience.

It \e{is} a compromise, however. Holding your decrypted private keys
in Pageant is better than storing them in easy-to-find disk files,
but still less secure than not storing them anywhere at all. This is
for two reasons:

\b Windows unfortunately provides no way to protect pieces of memory
from being written to the system \i{swap file}. So if Pageant is holding
your private keys for a long period of time, it's possible that
decrypted private key data may be written to the system swap file,
and an attacker who gained access to your hard disk later on might
be able to recover that data. (However, if you stored an unencrypted
key in a disk file they would \e{certainly} be able to recover it.)

\b Although, like most modern operating systems, Windows prevents
programs from accidentally accessing one another's memory space, it
does allow programs to access one another's memory space
deliberately, for special purposes such as debugging. This means
that if you allow a virus, trojan, or other malicious program on to
your Windows system while Pageant is running, it could access the
memory of the Pageant process, extract your decrypted authentication
keys, and send them back to its master.

Similarly, use of agent \e{forwarding} is a security improvement on
other methods of one-touch authentication, but not perfect. Holding
your keys in Pageant on your Windows box has a security advantage
over holding them on the remote server machine itself (either in an
agent or just unencrypted on disk), because if the server machine
ever sees your unencrypted private key then the sysadmin or anyone
who cracks the machine can steal the keys and pretend to be you for
as long as they want.

However, the sysadmin of the server machine can always pretend to be
you \e{on that machine}. So if you forward your agent to a server
machine, then the sysadmin of that machine can access the forwarded
agent connection and request signatures from any of your private keys,
and can therefore log in to other machines as you. They can only do
this to a limited extent - when the agent forwarding disappears they
lose the ability - but using Pageant doesn't actually \e{prevent} the
sysadmin (or hackers) on the server from doing this.

Therefore, if you don't trust the sysadmin of a server machine, you
should \e{never} use agent forwarding to that machine. (Of course
you also shouldn't store private keys on that machine, type
passphrases into it, or log into other machines from it in any way
at all; Pageant is hardly unique in this respect.)