39a938f7 |
1 | \define{versionidpageant} \versionid $Id$ |
8f1529bc |
2 | |
421406a4 |
3 | \C{pageant} Using \i{Pageant} for authentication |
e5b0d077 |
4 | |
ecea795f |
5 | \cfg{winhelp-topic}{pageant.general} |
6 | |
421406a4 |
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}. |
e5b0d077 |
10 | |
e5b0d077 |
11 | \H{pageant-start} Getting started with Pageant |
12 | |
421406a4 |
13 | Before you run Pageant, you need to have a private key in \c{*.\i{PPK}} |
8cee3b72 |
14 | format. See \k{pubkey} to find out how to generate and use one. |
e5b0d077 |
15 | |
16 | When you run Pageant, it will put an icon of a computer wearing a |
421406a4 |
17 | hat into the \ii{System tray}. It will then sit and do nothing, until you |
ecea795f |
18 | load a private key into it. |
e5b0d077 |
19 | |
20 | If you click the Pageant icon with the right mouse button, you will |
d60c975d |
21 | see a menu. Select \q{View Keys} from this menu. The Pageant main |
e5b0d077 |
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 |
ecea795f |
27 | list box will be empty. After you add one or more keys, they will |
28 | show up in the list box. |
e5b0d077 |
29 | |
d60c975d |
30 | To add a key to Pageant, press the \q{Add Key} button. Pageant will |
e5b0d077 |
31 | bring up a file dialog, labelled \q{Select Private Key File}. Find |
d60c975d |
32 | your private key file in this dialog, and press \q{Open}. |
e5b0d077 |
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 |
d60c975d |
46 | Pageant icon in the System tray, and select \q{Exit} from the menu. |
e5b0d077 |
47 | Closing the Pageant main window does \e{not} shut down Pageant. |
48 | |
ecea795f |
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 | |
35cffede |
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 |
ecea795f |
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 |
2e85c969 |
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). |
ecea795f |
74 | |
75 | \b The size (in bits) of the key. |
76 | |
421406a4 |
77 | \b The \I{key fingerprint}fingerprint for the public key. This should be |
78 | the same fingerprint given by PuTTYgen, and (hopefully) also the same |
79 | fingerprint shown by remote utilities such as \i\c{ssh-keygen} when |
ecea795f |
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 | |
3a65c351 |
118 | \H{pageant-cmdline} The Pageant command line |
119 | |
120 | Pageant can be made to do things automatically when it starts up, by |
421406a4 |
121 | \I{command-line arguments}specifying instructions on its command line. |
122 | If you're starting Pageant from the Windows GUI, you can arrange this |
123 | by editing the properties of the \i{Windows shortcut} that it was |
124 | started from. |
3a65c351 |
125 | |
126 | \S{pageant-cmdline-loadkey} Making Pageant automatically load keys |
127 | on startup |
128 | |
129 | Pageant can automatically load one or more private keys when it |
130 | starts up, if you provide them on the Pageant command line. Your |
131 | command line might then look like: |
132 | |
8cee3b72 |
133 | \c C:\PuTTY\pageant.exe d:\main.ppk d:\secondary.ppk |
3a65c351 |
134 | |
135 | If the keys are stored encrypted, Pageant will request the |
136 | passphrases on startup. |
137 | |
138 | \S{pageant-cmdline-command} Making Pageant run another program |
139 | |
140 | You can arrange for Pageant to start another program once it has |
141 | initialised itself and loaded any keys specified on its command |
142 | line. This program (perhaps a PuTTY, or a WinCVS making use of |
143 | Plink, or whatever) will then be able to use the keys Pageant has |
144 | loaded. |
145 | |
421406a4 |
146 | You do this by specifying the \I{-c-pageant}\c{-c} option followed |
147 | by the command, like this: |
3a65c351 |
148 | |
8cee3b72 |
149 | \c C:\PuTTY\pageant.exe d:\main.ppk -c C:\PuTTY\putty.exe |
3a65c351 |
150 | |
421406a4 |
151 | \H{pageant-forward} Using \i{agent forwarding} |
e5b0d077 |
152 | |
8f1529bc |
153 | Agent forwarding is a mechanism that allows applications on your SSH |
154 | server machine to talk to the agent on your client machine. |
155 | |
2e85c969 |
156 | Note that at present, agent forwarding in SSH-2 is only available |
421406a4 |
157 | when your SSH server is \i{OpenSSH}. The \i\cw{ssh.com} server uses a |
62ea2c64 |
158 | different agent protocol, which PuTTY does not yet support. |
8f1529bc |
159 | |
160 | To enable agent forwarding, first start Pageant. Then set up a PuTTY |
161 | SSH session in which \q{Allow agent forwarding} is enabled (see |
e2a197cf |
162 | \k{config-ssh-agentfwd}). Open the session as normal. (Alternatively, |
163 | you can use the \c{-A} command line option; see |
164 | \k{using-cmdline-agent} for details.) |
8f1529bc |
165 | |
166 | If this has worked, your applications on the server should now have |
167 | access to a Unix domain socket which the SSH server will forward |
168 | back to PuTTY, and PuTTY will forward on to the agent. To check that |
169 | this has actually happened, you can try this command on Unix server |
170 | machines: |
171 | |
172 | \c unixbox:~$ echo $SSH_AUTH_SOCK |
173 | \c /tmp/ssh-XXNP18Jz/agent.28794 |
174 | \c unixbox:~$ |
175 | |
176 | If the result line comes up blank, agent forwarding has not been |
177 | enabled at all. |
178 | |
179 | Now if you run \c{ssh} on the server and use it to connect through |
180 | to another server that accepts one of the keys in Pageant, you |
181 | should be able to log in without a password: |
182 | |
183 | \c unixbox:~$ ssh -v otherunixbox |
184 | \c [...] |
185 | \c debug: next auth method to try is publickey |
186 | \c debug: userauth_pubkey_agent: trying agent key my-putty-key |
187 | \c debug: ssh-userauth2 successful: method publickey |
188 | \c [...] |
189 | |
190 | If you enable agent forwarding on \e{that} SSH connection as well |
191 | (see the manual for your server-side SSH client to find out how to |
192 | do this), your authentication keys will still be available on the |
193 | next machine you connect to - two SSH connections away from where |
194 | they're actually stored. |
195 | |
196 | In addition, if you have a private key on one of the SSH servers, |
197 | you can send it all the way back to Pageant using the local |
421406a4 |
198 | \i\c{ssh-add} command: |
8f1529bc |
199 | |
200 | \c unixbox:~$ ssh-add ~/.ssh/id_rsa |
201 | \c Need passphrase for /home/fred/.ssh/id_rsa |
202 | \c Enter passphrase for /home/fred/.ssh/id_rsa: |
203 | \c Identity added: /home/fred/.ssh/id_rsa (/home/simon/.ssh/id_rsa) |
204 | \c unixbox:~$ |
205 | |
206 | and then it's available to every machine that has agent forwarding |
207 | available (not just the ones downstream of the place you added it). |
e5b0d077 |
208 | |
209 | \H{pageant-security} Security considerations |
210 | |
421406a4 |
211 | \I{security risk}Using Pageant for public-key authentication gives you the |
8f1529bc |
212 | convenience of being able to open multiple SSH sessions without |
213 | having to type a passphrase every time, but also gives you the |
214 | security benefit of never storing a decrypted private key on disk. |
215 | Many people feel this is a good compromise between security and |
216 | convenience. |
217 | |
218 | It \e{is} a compromise, however. Holding your decrypted private keys |
219 | in Pageant is better than storing them in easy-to-find disk files, |
220 | but still less secure than not storing them anywhere at all. This is |
221 | for two reasons: |
222 | |
223 | \b Windows unfortunately provides no way to protect pieces of memory |
421406a4 |
224 | from being written to the system \i{swap file}. So if Pageant is holding |
8f1529bc |
225 | your private keys for a long period of time, it's possible that |
226 | decrypted private key data may be written to the system swap file, |
227 | and an attacker who gained access to your hard disk later on might |
228 | be able to recover that data. (However, if you stored an unencrypted |
229 | key in a disk file they would \e{certainly} be able to recover it.) |
230 | |
231 | \b Although, like most modern operating systems, Windows prevents |
232 | programs from accidentally accessing one another's memory space, it |
233 | does allow programs to access one another's memory space |
234 | deliberately, for special purposes such as debugging. This means |
235 | that if you allow a virus, trojan, or other malicious program on to |
236 | your Windows system while Pageant is running, it could access the |
237 | memory of the Pageant process, extract your decrypted authentication |
238 | keys, and send them back to its master. |
239 | |
240 | Similarly, use of agent \e{forwarding} is a security improvement on |
241 | other methods of one-touch authentication, but not perfect. Holding |
242 | your keys in Pageant on your Windows box has a security advantage |
243 | over holding them on the remote server machine itself (either in an |
244 | agent or just unencrypted on disk), because if the server machine |
245 | ever sees your unencrypted private key then the sysadmin or anyone |
246 | who cracks the machine can steal the keys and pretend to be you for |
247 | as long as they want. |
248 | |
249 | However, the sysadmin of the server machine can always pretend to be |
250 | you \e{on that machine}. So if you forward your agent to a server |
251 | machine, then the sysadmin of that machine can access the forwarded |
78d426c3 |
252 | agent connection and request signatures from your private keys, and |
8f1529bc |
253 | can therefore log in to other machines as you. They can only do this |
254 | to a limited extent - when the agent forwarding disappears they lose |
255 | the ability - but using Pageant doesn't actually \e{prevent} the |
256 | sysadmin (or hackers) on the server from doing this. |
257 | |
258 | Therefore, if you don't trust the sysadmin of a server machine, you |
259 | should \e{never} use agent forwarding to that machine. (Of course |
260 | you also shouldn't store private keys on that machine, type |
261 | passphrases into it, or log into other machines from it in any way |
262 | at all; Pageant is hardly unique in this respect.) |