1 \versionid $Id: pageant.but,v 1.5 2001/11/25 17:32:39 simon Exp $
3 \C{pageant} Using Pageant for authentication
5 Pageant is an SSH authentication agent. It holds your private keys
6 in memory, already decoded, so that you can use them often without
7 needing to type a passphrase.
9 \H{pageant-start} Getting started with Pageant
11 Before you run Pageant, you need to have a private key. See
12 \k{pubkey} to find out how to generate and use one.
14 When you run Pageant, it will put an icon of a computer wearing a
15 hat into the System tray. It will then sit and do nothing.
17 If you click the Pageant icon with the right mouse button, you will
18 see a menu. Select \q{View Keys} from this menu. The Pageant main
19 window will appear. (You can also bring this window up by
20 double-clicking on the Pageant icon.)
22 The Pageant window contains a list box. This shows the private keys
23 Pageant is holding. When you start Pageant, it has no keys, so the
24 list box will be empty.
26 To add a key to Pageant, press the \q{Add Key} button. Pageant will
27 bring up a file dialog, labelled \q{Select Private Key File}. Find
28 your private key file in this dialog, and press \q{Open}.
30 Pageant will now load the private key. If the key is protected by a
31 passphrase, Pageant will ask you to type the passphrase. When the
32 key has been loaded, it will appear in the list in the Pageant
35 Now start PuTTY and open an SSH session to a site that accepts your
36 key. PuTTY will notice that Pageant is running, retrieve the key
37 automatically from Pageant, and use it to authenticate. You can now
38 open as many PuTTY sessions as you like without having to type your
41 When you want to shut down Pageant, click the right button on the
42 Pageant icon in the System tray, and select \q{Exit} from the menu.
43 Closing the Pageant main window does \e{not} shut down Pageant.
45 \H{pageant-forward} Using agent forwarding
47 Agent forwarding is a mechanism that allows applications on your SSH
48 server machine to talk to the agent on your client machine.
50 Note that at present, agent forwarding in SSH2 is only available
51 when your SSH server is OpenSSH. The \cw{ssh.com} server uses a
52 different agent protocol which they have not published. If you would
53 like PuTTY to be able to support agent forwarding to an \cw{ssh.com}
54 server, please write to \cw{ssh.com} and explain to them that they
55 are hurting themselves and their users by keeping their protocol
58 To enable agent forwarding, first start Pageant. Then set up a PuTTY
59 SSH session in which \q{Allow agent forwarding} is enabled (see
60 \k{config-ssh-agentfwd}). Open the session as normal.
62 If this has worked, your applications on the server should now have
63 access to a Unix domain socket which the SSH server will forward
64 back to PuTTY, and PuTTY will forward on to the agent. To check that
65 this has actually happened, you can try this command on Unix server
68 \c unixbox:~$ echo $SSH_AUTH_SOCK
69 \c /tmp/ssh-XXNP18Jz/agent.28794
72 If the result line comes up blank, agent forwarding has not been
75 Now if you run \c{ssh} on the server and use it to connect through
76 to another server that accepts one of the keys in Pageant, you
77 should be able to log in without a password:
79 \c unixbox:~$ ssh -v otherunixbox
81 \c debug: next auth method to try is publickey
82 \c debug: userauth_pubkey_agent: trying agent key my-putty-key
83 \c debug: ssh-userauth2 successful: method publickey
86 If you enable agent forwarding on \e{that} SSH connection as well
87 (see the manual for your server-side SSH client to find out how to
88 do this), your authentication keys will still be available on the
89 next machine you connect to - two SSH connections away from where
90 they're actually stored.
92 In addition, if you have a private key on one of the SSH servers,
93 you can send it all the way back to Pageant using the local
96 \c unixbox:~$ ssh-add ~/.ssh/id_rsa
97 \c Need passphrase for /home/fred/.ssh/id_rsa
98 \c Enter passphrase for /home/fred/.ssh/id_rsa:
99 \c Identity added: /home/fred/.ssh/id_rsa (/home/simon/.ssh/id_rsa)
102 and then it's available to every machine that has agent forwarding
103 available (not just the ones downstream of the place you added it).
105 \H{pageant-security} Security considerations
107 Using Pageant for public-key authentication gives you the
108 convenience of being able to open multiple SSH sessions without
109 having to type a passphrase every time, but also gives you the
110 security benefit of never storing a decrypted private key on disk.
111 Many people feel this is a good compromise between security and
114 It \e{is} a compromise, however. Holding your decrypted private keys
115 in Pageant is better than storing them in easy-to-find disk files,
116 but still less secure than not storing them anywhere at all. This is
119 \b Windows unfortunately provides no way to protect pieces of memory
120 from being written to the system swap file. So if Pageant is holding
121 your private keys for a long period of time, it's possible that
122 decrypted private key data may be written to the system swap file,
123 and an attacker who gained access to your hard disk later on might
124 be able to recover that data. (However, if you stored an unencrypted
125 key in a disk file they would \e{certainly} be able to recover it.)
127 \b Although, like most modern operating systems, Windows prevents
128 programs from accidentally accessing one another's memory space, it
129 does allow programs to access one another's memory space
130 deliberately, for special purposes such as debugging. This means
131 that if you allow a virus, trojan, or other malicious program on to
132 your Windows system while Pageant is running, it could access the
133 memory of the Pageant process, extract your decrypted authentication
134 keys, and send them back to its master.
136 Similarly, use of agent \e{forwarding} is a security improvement on
137 other methods of one-touch authentication, but not perfect. Holding
138 your keys in Pageant on your Windows box has a security advantage
139 over holding them on the remote server machine itself (either in an
140 agent or just unencrypted on disk), because if the server machine
141 ever sees your unencrypted private key then the sysadmin or anyone
142 who cracks the machine can steal the keys and pretend to be you for
143 as long as they want.
145 However, the sysadmin of the server machine can always pretend to be
146 you \e{on that machine}. So if you forward your agent to a server
147 machine, then the sysadmin of that machine can access the forwarded
148 agent connection and request signatures from your public keys, and
149 can therefore log in to other machines as you. They can only do this
150 to a limited extent - when the agent forwarding disappears they lose
151 the ability - but using Pageant doesn't actually \e{prevent} the
152 sysadmin (or hackers) on the server from doing this.
154 Therefore, if you don't trust the sysadmin of a server machine, you
155 should \e{never} use agent forwarding to that machine. (Of course
156 you also shouldn't store private keys on that machine, type
157 passphrases into it, or log into other machines from it in any way
158 at all; Pageant is hardly unique in this respect.)
~mdw / sgt / putty / blob