| 1 | \versionid $Id: pageant.but,v 1.6 2001/12/11 18:48:29 simon Exp $ |
| 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. See |
| 14 | \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 key1 |
| 66 | \c ssh-rsa 1023 74:63:08:82:95:75:e1:7c:33:31:bb:cb:00:c0:89:8b key2 |
| 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 v1 protocol), \c{ssh-rsa} (an RSA key for use |
| 72 | with the SSH v2 protocol), or \c{ssh-dss} (a DSA key for use with |
| 73 | the SSH v2 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-forward} Using agent forwarding |
| 119 | |
| 120 | Agent forwarding is a mechanism that allows applications on your SSH |
| 121 | server machine to talk to the agent on your client machine. |
| 122 | |
| 123 | Note that at present, agent forwarding in SSH2 is only available |
| 124 | when your SSH server is OpenSSH. The \cw{ssh.com} server uses a |
| 125 | different agent protocol which they have not published. If you would |
| 126 | like PuTTY to be able to support agent forwarding to an \cw{ssh.com} |
| 127 | server, please write to \cw{ssh.com} and explain to them that they |
| 128 | are hurting themselves and their users by keeping their protocol |
| 129 | secret. |
| 130 | |
| 131 | To enable agent forwarding, first start Pageant. Then set up a PuTTY |
| 132 | SSH session in which \q{Allow agent forwarding} is enabled (see |
| 133 | \k{config-ssh-agentfwd}). Open the session as normal. |
| 134 | |
| 135 | If this has worked, your applications on the server should now have |
| 136 | access to a Unix domain socket which the SSH server will forward |
| 137 | back to PuTTY, and PuTTY will forward on to the agent. To check that |
| 138 | this has actually happened, you can try this command on Unix server |
| 139 | machines: |
| 140 | |
| 141 | \c unixbox:~$ echo $SSH_AUTH_SOCK |
| 142 | \c /tmp/ssh-XXNP18Jz/agent.28794 |
| 143 | \c unixbox:~$ |
| 144 | |
| 145 | If the result line comes up blank, agent forwarding has not been |
| 146 | enabled at all. |
| 147 | |
| 148 | Now if you run \c{ssh} on the server and use it to connect through |
| 149 | to another server that accepts one of the keys in Pageant, you |
| 150 | should be able to log in without a password: |
| 151 | |
| 152 | \c unixbox:~$ ssh -v otherunixbox |
| 153 | \c [...] |
| 154 | \c debug: next auth method to try is publickey |
| 155 | \c debug: userauth_pubkey_agent: trying agent key my-putty-key |
| 156 | \c debug: ssh-userauth2 successful: method publickey |
| 157 | \c [...] |
| 158 | |
| 159 | If you enable agent forwarding on \e{that} SSH connection as well |
| 160 | (see the manual for your server-side SSH client to find out how to |
| 161 | do this), your authentication keys will still be available on the |
| 162 | next machine you connect to - two SSH connections away from where |
| 163 | they're actually stored. |
| 164 | |
| 165 | In addition, if you have a private key on one of the SSH servers, |
| 166 | you can send it all the way back to Pageant using the local |
| 167 | \c{ssh-add} command: |
| 168 | |
| 169 | \c unixbox:~$ ssh-add ~/.ssh/id_rsa |
| 170 | \c Need passphrase for /home/fred/.ssh/id_rsa |
| 171 | \c Enter passphrase for /home/fred/.ssh/id_rsa: |
| 172 | \c Identity added: /home/fred/.ssh/id_rsa (/home/simon/.ssh/id_rsa) |
| 173 | \c unixbox:~$ |
| 174 | |
| 175 | and then it's available to every machine that has agent forwarding |
| 176 | available (not just the ones downstream of the place you added it). |
| 177 | |
| 178 | \H{pageant-security} Security considerations |
| 179 | |
| 180 | Using Pageant for public-key authentication gives you the |
| 181 | convenience of being able to open multiple SSH sessions without |
| 182 | having to type a passphrase every time, but also gives you the |
| 183 | security benefit of never storing a decrypted private key on disk. |
| 184 | Many people feel this is a good compromise between security and |
| 185 | convenience. |
| 186 | |
| 187 | It \e{is} a compromise, however. Holding your decrypted private keys |
| 188 | in Pageant is better than storing them in easy-to-find disk files, |
| 189 | but still less secure than not storing them anywhere at all. This is |
| 190 | for two reasons: |
| 191 | |
| 192 | \b Windows unfortunately provides no way to protect pieces of memory |
| 193 | from being written to the system swap file. So if Pageant is holding |
| 194 | your private keys for a long period of time, it's possible that |
| 195 | decrypted private key data may be written to the system swap file, |
| 196 | and an attacker who gained access to your hard disk later on might |
| 197 | be able to recover that data. (However, if you stored an unencrypted |
| 198 | key in a disk file they would \e{certainly} be able to recover it.) |
| 199 | |
| 200 | \b Although, like most modern operating systems, Windows prevents |
| 201 | programs from accidentally accessing one another's memory space, it |
| 202 | does allow programs to access one another's memory space |
| 203 | deliberately, for special purposes such as debugging. This means |
| 204 | that if you allow a virus, trojan, or other malicious program on to |
| 205 | your Windows system while Pageant is running, it could access the |
| 206 | memory of the Pageant process, extract your decrypted authentication |
| 207 | keys, and send them back to its master. |
| 208 | |
| 209 | Similarly, use of agent \e{forwarding} is a security improvement on |
| 210 | other methods of one-touch authentication, but not perfect. Holding |
| 211 | your keys in Pageant on your Windows box has a security advantage |
| 212 | over holding them on the remote server machine itself (either in an |
| 213 | agent or just unencrypted on disk), because if the server machine |
| 214 | ever sees your unencrypted private key then the sysadmin or anyone |
| 215 | who cracks the machine can steal the keys and pretend to be you for |
| 216 | as long as they want. |
| 217 | |
| 218 | However, the sysadmin of the server machine can always pretend to be |
| 219 | you \e{on that machine}. So if you forward your agent to a server |
| 220 | machine, then the sysadmin of that machine can access the forwarded |
| 221 | agent connection and request signatures from your public keys, and |
| 222 | can therefore log in to other machines as you. They can only do this |
| 223 | to a limited extent - when the agent forwarding disappears they lose |
| 224 | the ability - but using Pageant doesn't actually \e{prevent} the |
| 225 | sysadmin (or hackers) on the server from doing this. |
| 226 | |
| 227 | Therefore, if you don't trust the sysadmin of a server machine, you |
| 228 | should \e{never} use agent forwarding to that machine. (Of course |
| 229 | you also shouldn't store private keys on that machine, type |
| 230 | passphrases into it, or log into other machines from it in any way |
| 231 | at all; Pageant is hardly unique in this respect.) |