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