Consistently use a single notation to refer to SSH protocol versions, as
[u/mdw/putty] / doc / pageant.but
1 \define{versionidpageant} \versionid $Id$
2
3 \C{pageant} Using Pageant for authentication
4
5 \cfg{winhelp-topic}{pageant.general}
6
7 Pageant is an SSH authentication agent. It holds your private keys
8 in memory, already decoded, so that you can use them often without
9 needing to type a passphrase.
10
11 \H{pageant-start} Getting started with Pageant
12
13 Before you run Pageant, you need to have a private key in \c{*.PPK}
14 format. See \k{pubkey} to find out how to generate and use one.
15
16 When you run Pageant, it will put an icon of a computer wearing a
17 hat into the System tray. It will then sit and do nothing, until you
18 load a private key into it.
19
20 If you click the Pageant icon with the right mouse button, you will
21 see a menu. Select \q{View Keys} from this menu. The Pageant main
22 window will appear. (You can also bring this window up by
23 double-clicking on the Pageant icon.)
24
25 The Pageant window contains a list box. This shows the private keys
26 Pageant is holding. When you start Pageant, it has no keys, so the
27 list box will be empty. After you add one or more keys, they will
28 show up in the list box.
29
30 To add a key to Pageant, press the \q{Add Key} button. Pageant will
31 bring up a file dialog, labelled \q{Select Private Key File}. Find
32 your private key file in this dialog, and press \q{Open}.
33
34 Pageant will now load the private key. If the key is protected by a
35 passphrase, Pageant will ask you to type the passphrase. When the
36 key has been loaded, it will appear in the list in the Pageant
37 window.
38
39 Now start PuTTY and open an SSH session to a site that accepts your
40 key. PuTTY will notice that Pageant is running, retrieve the key
41 automatically from Pageant, and use it to authenticate. You can now
42 open as many PuTTY sessions as you like without having to type your
43 passphrase again.
44
45 When you want to shut down Pageant, click the right button on the
46 Pageant icon in the System tray, and select \q{Exit} from the menu.
47 Closing the Pageant main window does \e{not} shut down Pageant.
48
49 \H{pageant-mainwin} The Pageant main window
50
51 The Pageant main window appears when you left-click on the Pageant
52 system tray icon, or alternatively right-click and select \q{View
53 Keys} from the menu. You can use it to keep track of what keys are
54 currently loaded into Pageant, and to add new ones or remove the
55 existing keys.
56
57 \S{pageant-mainwin-keylist} The key list box
58
59 \cfg{winhelp-topic}{pageant.keylist}
60
61 The large list box in the Pageant main window lists the private keys
62 that are currently loaded into Pageant. The list might look
63 something like this:
64
65 \c ssh1 1024 22:c3:68:3b:09:41:36:c3:39:83:91:ae:71:b2:0f:04 k1
66 \c ssh-rsa 1023 74:63:08:82:95:75:e1:7c:33:31:bb:cb:00:c0:89:8b k2
67
68 For each key, the list box will tell you:
69
70 \b The type of the key. Currently, this can be \c{ssh1} (an RSA key
71 for use with the SSH-1 protocol), \c{ssh-rsa} (an RSA key for use
72 with the SSH-2 protocol), or \c{ssh-dss} (a DSA key for use with
73 the SSH-2 protocol).
74
75 \b The size (in bits) of the key.
76
77 \b The fingerprint for the public key. This should be the same
78 fingerprint given by PuTTYgen, and (hopefully) also the same
79 fingerprint shown by remote utilities such as \c{ssh-keygen} when
80 applied to your \c{authorized_keys} file.
81
82 \b The comment attached to the key.
83
84 \S{pageant-mainwin-addkey} The \q{Add Key} button
85
86 \cfg{winhelp-topic}{pageant.addkey}
87
88 To add a key to Pageant by reading it out of a local disk file,
89 press the \q{Add Key} button in the Pageant main window, or
90 alternatively right-click on the Pageant icon in the system tray and
91 select \q{Add Key} from there.
92
93 Pageant will bring up a file dialog, labelled \q{Select Private Key
94 File}. Find your private key file in this dialog, and press
95 \q{Open}. If you want to add more than one key at once, you can
96 select multiple files using Shift-click (to select several adjacent
97 files) or Ctrl-click (to select non-adjacent files).
98
99 Pageant will now load the private key(s). If a key is protected by a
100 passphrase, Pageant will ask you to type the passphrase.
101
102 (This is not the only way to add a private key to Pageant. You can
103 also add one from a remote system by using agent forwarding; see
104 \k{pageant-forward} for details.)
105
106 \S{pageant-mainwin-remkey} The \q{Remove Key} button
107
108 \cfg{winhelp-topic}{pageant.remkey}
109
110 If you need to remove a key from Pageant, select that key in the
111 list box, and press the \q{Remove Key} button. Pageant will remove
112 the key from its memory.
113
114 You can apply this to keys you added using the \q{Add Key} button,
115 or to keys you added remotely using agent forwarding (see
116 \k{pageant-forward}); it makes no difference.
117
118 \H{pageant-cmdline} The Pageant command line
119
120 Pageant can be made to do things automatically when it starts up, by
121 specifying instructions on its command line. If you're starting
122 Pageant from the Windows GUI, you can arrange this by editing the
123 properties of the Windows shortcut that it was started from.
124
125 \S{pageant-cmdline-loadkey} Making Pageant automatically load keys
126 on startup
127
128 Pageant can automatically load one or more private keys when it
129 starts up, if you provide them on the Pageant command line. Your
130 command line might then look like:
131
132 \c C:\PuTTY\pageant.exe d:\main.ppk d:\secondary.ppk
133
134 If the keys are stored encrypted, Pageant will request the
135 passphrases on startup.
136
137 \S{pageant-cmdline-command} Making Pageant run another program
138
139 You can arrange for Pageant to start another program once it has
140 initialised itself and loaded any keys specified on its command
141 line. This program (perhaps a PuTTY, or a WinCVS making use of
142 Plink, or whatever) will then be able to use the keys Pageant has
143 loaded.
144
145 You do this by specifying the \c{-c} option followed by the command,
146 like this:
147
148 \c C:\PuTTY\pageant.exe d:\main.ppk -c C:\PuTTY\putty.exe
149
150 \H{pageant-forward} Using agent forwarding
151
152 Agent forwarding is a mechanism that allows applications on your SSH
153 server machine to talk to the agent on your client machine.
154
155 Note that at present, agent forwarding in SSH-2 is only available
156 when your SSH server is OpenSSH. The \cw{ssh.com} server uses a
157 different agent protocol, which PuTTY does not yet support.
158
159 To enable agent forwarding, first start Pageant. Then set up a PuTTY
160 SSH session in which \q{Allow agent forwarding} is enabled (see
161 \k{config-ssh-agentfwd}). Open the session as normal. (Alternatively,
162 you can use the \c{-A} command line option; see
163 \k{using-cmdline-agent} for details.)
164
165 If this has worked, your applications on the server should now have
166 access to a Unix domain socket which the SSH server will forward
167 back to PuTTY, and PuTTY will forward on to the agent. To check that
168 this has actually happened, you can try this command on Unix server
169 machines:
170
171 \c unixbox:~$ echo $SSH_AUTH_SOCK
172 \c /tmp/ssh-XXNP18Jz/agent.28794
173 \c unixbox:~$
174
175 If the result line comes up blank, agent forwarding has not been
176 enabled at all.
177
178 Now if you run \c{ssh} on the server and use it to connect through
179 to another server that accepts one of the keys in Pageant, you
180 should be able to log in without a password:
181
182 \c unixbox:~$ ssh -v otherunixbox
183 \c [...]
184 \c debug: next auth method to try is publickey
185 \c debug: userauth_pubkey_agent: trying agent key my-putty-key
186 \c debug: ssh-userauth2 successful: method publickey
187 \c [...]
188
189 If you enable agent forwarding on \e{that} SSH connection as well
190 (see the manual for your server-side SSH client to find out how to
191 do this), your authentication keys will still be available on the
192 next machine you connect to - two SSH connections away from where
193 they're actually stored.
194
195 In addition, if you have a private key on one of the SSH servers,
196 you can send it all the way back to Pageant using the local
197 \c{ssh-add} command:
198
199 \c unixbox:~$ ssh-add ~/.ssh/id_rsa
200 \c Need passphrase for /home/fred/.ssh/id_rsa
201 \c Enter passphrase for /home/fred/.ssh/id_rsa:
202 \c Identity added: /home/fred/.ssh/id_rsa (/home/simon/.ssh/id_rsa)
203 \c unixbox:~$
204
205 and then it's available to every machine that has agent forwarding
206 available (not just the ones downstream of the place you added it).
207
208 \H{pageant-security} Security considerations
209
210 Using Pageant for public-key authentication gives you the
211 convenience of being able to open multiple SSH sessions without
212 having to type a passphrase every time, but also gives you the
213 security benefit of never storing a decrypted private key on disk.
214 Many people feel this is a good compromise between security and
215 convenience.
216
217 It \e{is} a compromise, however. Holding your decrypted private keys
218 in Pageant is better than storing them in easy-to-find disk files,
219 but still less secure than not storing them anywhere at all. This is
220 for two reasons:
221
222 \b Windows unfortunately provides no way to protect pieces of memory
223 from being written to the system swap file. So if Pageant is holding
224 your private keys for a long period of time, it's possible that
225 decrypted private key data may be written to the system swap file,
226 and an attacker who gained access to your hard disk later on might
227 be able to recover that data. (However, if you stored an unencrypted
228 key in a disk file they would \e{certainly} be able to recover it.)
229
230 \b Although, like most modern operating systems, Windows prevents
231 programs from accidentally accessing one another's memory space, it
232 does allow programs to access one another's memory space
233 deliberately, for special purposes such as debugging. This means
234 that if you allow a virus, trojan, or other malicious program on to
235 your Windows system while Pageant is running, it could access the
236 memory of the Pageant process, extract your decrypted authentication
237 keys, and send them back to its master.
238
239 Similarly, use of agent \e{forwarding} is a security improvement on
240 other methods of one-touch authentication, but not perfect. Holding
241 your keys in Pageant on your Windows box has a security advantage
242 over holding them on the remote server machine itself (either in an
243 agent or just unencrypted on disk), because if the server machine
244 ever sees your unencrypted private key then the sysadmin or anyone
245 who cracks the machine can steal the keys and pretend to be you for
246 as long as they want.
247
248 However, the sysadmin of the server machine can always pretend to be
249 you \e{on that machine}. So if you forward your agent to a server
250 machine, then the sysadmin of that machine can access the forwarded
251 agent connection and request signatures from your public keys, and
252 can therefore log in to other machines as you. They can only do this
253 to a limited extent - when the agent forwarding disappears they lose
254 the ability - but using Pageant doesn't actually \e{prevent} the
255 sysadmin (or hackers) on the server from doing this.
256
257 Therefore, if you don't trust the sysadmin of a server machine, you
258 should \e{never} use agent forwarding to that machine. (Of course
259 you also shouldn't store private keys on that machine, type
260 passphrases into it, or log into other machines from it in any way
261 at all; Pageant is hardly unique in this respect.)