d60c975d |
1 | \versionid $Id: pageant.but,v 1.5 2001/11/25 17:32:39 simon Exp $ |
8f1529bc |
2 | |
e5b0d077 |
3 | \C{pageant} Using Pageant for authentication |
4 | |
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. |
8 | |
e5b0d077 |
9 | \H{pageant-start} Getting started with Pageant |
10 | |
55ba634a |
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. |
e5b0d077 |
13 | |
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. |
16 | |
17 | If you click the Pageant icon with the right mouse button, you will |
d60c975d |
18 | see a menu. Select \q{View Keys} from this menu. The Pageant main |
e5b0d077 |
19 | window will appear. (You can also bring this window up by |
20 | double-clicking on the Pageant icon.) |
21 | |
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. |
25 | |
d60c975d |
26 | To add a key to Pageant, press the \q{Add Key} button. Pageant will |
e5b0d077 |
27 | bring up a file dialog, labelled \q{Select Private Key File}. Find |
d60c975d |
28 | your private key file in this dialog, and press \q{Open}. |
e5b0d077 |
29 | |
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 |
33 | window. |
34 | |
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 |
39 | passphrase again. |
40 | |
41 | When you want to shut down Pageant, click the right button on the |
d60c975d |
42 | Pageant icon in the System tray, and select \q{Exit} from the menu. |
e5b0d077 |
43 | Closing the Pageant main window does \e{not} shut down Pageant. |
44 | |
45 | \H{pageant-forward} Using agent forwarding |
46 | |
8f1529bc |
47 | Agent forwarding is a mechanism that allows applications on your SSH |
48 | server machine to talk to the agent on your client machine. |
49 | |
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 |
56 | secret. |
57 | |
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. |
61 | |
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 |
66 | machines: |
67 | |
68 | \c unixbox:~$ echo $SSH_AUTH_SOCK |
69 | \c /tmp/ssh-XXNP18Jz/agent.28794 |
70 | \c unixbox:~$ |
71 | |
72 | If the result line comes up blank, agent forwarding has not been |
73 | enabled at all. |
74 | |
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: |
78 | |
79 | \c unixbox:~$ ssh -v otherunixbox |
80 | \c [...] |
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 |
84 | \c [...] |
85 | |
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. |
91 | |
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 |
94 | \c{ssh-add} command: |
95 | |
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) |
100 | \c unixbox:~$ |
101 | |
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). |
e5b0d077 |
104 | |
105 | \H{pageant-security} Security considerations |
106 | |
8f1529bc |
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 |
112 | convenience. |
113 | |
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 |
117 | for two reasons: |
118 | |
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.) |
126 | |
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. |
135 | |
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. |
144 | |
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. |
153 | |
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.) |