| 1 | \versionid $Id: pubkey.but,v 1.19 2002/11/01 21:50:35 jacob Exp $ |
| 2 | |
| 3 | \C{pubkey} Using public keys for SSH authentication |
| 4 | |
| 5 | \H{pubkey-intro} Public key authentication - an introduction |
| 6 | |
| 7 | Public key authentication is an alternative means of identifying |
| 8 | yourself to a login server, instead of typing a password. It is more |
| 9 | secure and more flexible, but more difficult to set up. |
| 10 | |
| 11 | In conventional password authentication, you prove you are who you |
| 12 | claim to be by proving that you know the correct password. The only |
| 13 | way to prove you know the password is to tell the server what you |
| 14 | think the password is. This means that if the server has been |
| 15 | hacked, or \e{spoofed} (see \k{gs-hostkey}), an attacker can learn |
| 16 | your password. |
| 17 | |
| 18 | Public key authentication solves this problem. You generate a \e{key |
| 19 | pair}, consisting of a public key (which everybody is allowed to |
| 20 | know) and a private key (which you keep secret and do not give to |
| 21 | anybody). The private key is able to generate \e{signatures}. |
| 22 | A signature created using your private key cannot be forged by |
| 23 | anybody who does not have that key; but anybody who has your public |
| 24 | key can verify that a particular signature is genuine. |
| 25 | |
| 26 | So you generate a key pair on your own computer, and you copy the |
| 27 | public key to the server. Then, when the server asks you to prove |
| 28 | who you are, PuTTY can generate a signature using your private key. |
| 29 | The server can verify that signature (since it has your public key) |
| 30 | and allow you to log in. Now if the server is hacked or spoofed, the |
| 31 | attacker does not gain your private key or password; they only gain |
| 32 | one signature. And signatures cannot be re-used, so they have gained |
| 33 | nothing. |
| 34 | |
| 35 | There is a problem with this: if your private key is stored |
| 36 | unprotected on your own computer, then anybody who gains access to |
| 37 | \e{that} will be able to generate signatures as if they were you. So |
| 38 | they will be able to log in to your server under your account. For |
| 39 | this reason, your private key is usually \e{encrypted} when it is |
| 40 | stored on your local machine, using a passphrase of your choice. In |
| 41 | order to generate a signature, PuTTY must decrypt the key, so you |
| 42 | have to type your passphrase. |
| 43 | |
| 44 | This can make public-key authentication less convenient than |
| 45 | password authentication: every time you log in to the server, |
| 46 | instead of typing a short password, you have to type a longer |
| 47 | passphrase. One solution to this is to use an \e{authentication |
| 48 | agent}, a separate program which holds decrypted private keys and |
| 49 | generates signatures on request. PuTTY's authentication agent is |
| 50 | called Pageant. When you begin a Windows session, you start Pageant |
| 51 | and load your private key into it (typing your passphrase once). For |
| 52 | the rest of your session, you can start PuTTY any number of times |
| 53 | and Pageant will automatically generate signatures without you |
| 54 | having to do anything. When you close your Windows session, Pageant |
| 55 | shuts down, without ever having stored your decrypted private key on |
| 56 | disk. Many people feel this is a good compromise between security |
| 57 | and convenience. See \k{pageant} for further details. |
| 58 | |
| 59 | There is more than one public-key algorithm available. The most |
| 60 | common is RSA, but others exist, notably DSA (otherwise known as |
| 61 | DSS), the USA's federal Digital Signature Standard. The key types |
| 62 | supported by PuTTY are described in \k{puttygen-keytype}. |
| 63 | |
| 64 | \H{pubkey-puttygen} Using PuTTYgen, the PuTTY key generator |
| 65 | |
| 66 | \cfg{winhelp-topic}{puttygen.general} |
| 67 | |
| 68 | PuTTYgen is a key generator. It generates pairs of public and private |
| 69 | keys to be used with PuTTY, PSCP, and Plink, as well as the PuTTY |
| 70 | authentication agent, Pageant (see \k{pageant}). PuTTYgen generates |
| 71 | RSA and DSA keys. |
| 72 | |
| 73 | When you run PuTTYgen you will see a window where you have two |
| 74 | choices: \q{Generate}, to generate a new public/private key pair, or |
| 75 | \q{Load} to load in an existing private key. |
| 76 | |
| 77 | \S{puttygen-generating} Generating a new key |
| 78 | |
| 79 | This is a general outline of the procedure for generating a new key |
| 80 | pair. The following sections describe the process in more detail. |
| 81 | |
| 82 | \b First, you need to select which type of key you want to generate, |
| 83 | and also select the strength of the key. This is described in more |
| 84 | detail in \k{puttygen-keytype} and |
| 85 | \k{puttygen-strength}. |
| 86 | |
| 87 | \b Then press the \q{Generate} button, to actually generate the key. |
| 88 | \K{puttygen-generate} describes this step. |
| 89 | |
| 90 | \b Once you have generated the key, select a comment field |
| 91 | (\k{puttygen-comment}) and a passphrase (\k{puttygen-passphrase}). |
| 92 | |
| 93 | \b Now you're ready to save the private key to disk; press the |
| 94 | \q{Save private key} button. (See \k{puttygen-savepriv}). |
| 95 | |
| 96 | Your key pair is now ready for use. You may also want to copy the |
| 97 | public key to your server, either by copying it out of the \q{Public |
| 98 | key for pasting into authorized_keys file} box (see |
| 99 | \k{puttygen-pastekey}), or by using the \q{Save public key} button |
| 100 | (\k{puttygen-savepub}). However, you don't need to do this |
| 101 | immediately; if you want, you can load the private key back into |
| 102 | PuTTYgen later (see \k{puttygen-load}) and the public key will be |
| 103 | available for copying and pasting again. |
| 104 | |
| 105 | \k{pubkey-gettingready} describes the typical process of configuring |
| 106 | PuTTY to attempt public-key authentication, and configuring your SSH |
| 107 | server to accept it. |
| 108 | |
| 109 | \S{puttygen-keytype} Selecting the type of key |
| 110 | |
| 111 | \cfg{winhelp-topic}{puttygen.keytype} |
| 112 | |
| 113 | Before generating a key pair using PuTTYgen, you need to select |
| 114 | which type of key you need. PuTTYgen currently supports three types |
| 115 | of key: |
| 116 | |
| 117 | \b An RSA key for use with the SSH 1 protocol. |
| 118 | |
| 119 | \b An RSA key for use with the SSH 2 protocol. |
| 120 | |
| 121 | \b A DSA key for use with the SSH 2 protocol. |
| 122 | |
| 123 | The SSH 1 protocol only supports RSA keys; if you will be connecting |
| 124 | using the SSH 1 protocol, you must select the first key type or your |
| 125 | key will be completely useless. |
| 126 | |
| 127 | The SSH 2 protocol supports more than one key type. The two types |
| 128 | supported by PuTTY are RSA and DSA. |
| 129 | |
| 130 | The PuTTY developers \e{strongly} recommend you use RSA. DSA has an |
| 131 | intrinsic weakness which makes it very easy to create a signature |
| 132 | which contains enough information to give away the \e{private} key! |
| 133 | This would allow an attacker to pretend to be you for any number of |
| 134 | future sessions. PuTTY's implementation has taken very careful |
| 135 | precautions to avoid this weakness, but we cannot be 100% certain we |
| 136 | have managed it, and if you have the choice we strongly recommend |
| 137 | using RSA keys instead. |
| 138 | |
| 139 | If you really need to connect to an SSH server which only supports |
| 140 | DSA, then you probably have no choice but to use DSA. If you do use |
| 141 | DSA, we recommend you do not use the same key to authenticate with |
| 142 | more than one server. |
| 143 | |
| 144 | \S{puttygen-strength} Selecting the size (strength) of the key |
| 145 | |
| 146 | \cfg{winhelp-topic}{puttygen.bits} |
| 147 | |
| 148 | The \q{Number of bits} input box allows you to choose the strength |
| 149 | of the key PuTTYgen will generate. |
| 150 | |
| 151 | Currently 1024 bits should be sufficient for most purposes. |
| 152 | |
| 153 | \S{puttygen-generate} The \q{Generate} button |
| 154 | |
| 155 | \cfg{winhelp-topic}{puttygen.generate} |
| 156 | |
| 157 | Once you have chosen the type of key you want, and the strength of |
| 158 | the key, press the \q{Generate} button and PuTTYgen will begin the |
| 159 | process of actually generating the key. |
| 160 | |
| 161 | First, a progress bar will appear and PuTTYgen will ask you to move |
| 162 | the mouse around to generate randomness. Wave the mouse in circles |
| 163 | over the blank area in the PuTTYgen window, and the progress bar |
| 164 | will gradually fill up as PuTTYgen collects enough randomness. You |
| 165 | don't need to wave the mouse in particularly imaginative patterns |
| 166 | (although it can't hurt); PuTTYgen will collect enough randomness |
| 167 | just from the fine detail of \e{exactly} how far the mouse has moved |
| 168 | each time Windows samples its position. |
| 169 | |
| 170 | When the progress bar reaches the end, PuTTYgen will begin creating |
| 171 | the key. The progress bar will reset to the start, and gradually |
| 172 | move up again to track the progress of the key generation. It will |
| 173 | not move evenly, and may occasionally slow down to a stop; this is |
| 174 | unfortunately unavoidable, because key generation is a random |
| 175 | process and it is impossible to reliably predict how long it will |
| 176 | take. |
| 177 | |
| 178 | When the key generation is complete, a new set of controls will |
| 179 | appear in the window to indicate this. |
| 180 | |
| 181 | \S{puttygen-fingerprint} The \q{Key fingerprint} box |
| 182 | |
| 183 | \cfg{winhelp-topic}{puttygen.fingerprint} |
| 184 | |
| 185 | The \q{Key fingerprint} box shows you a fingerprint value for the |
| 186 | generated key. This is derived cryptographically from the \e{public} |
| 187 | key value, so it doesn't need to be kept secret. |
| 188 | |
| 189 | The fingerprint value is intended to be cryptographically secure, in |
| 190 | the sense that it is computationally infeasible for someone to |
| 191 | invent a second key with the same fingerprint, or to find a key with |
| 192 | a particular fingerprint. So some utilities, such as the Pageant key |
| 193 | list box (see \k{pageant-mainwin-keylist}) and the Unix \c{ssh-add} |
| 194 | utility, will list key fingerprints rather than the whole public key. |
| 195 | |
| 196 | \S{puttygen-comment} Setting a comment for your key |
| 197 | |
| 198 | \cfg{winhelp-topic}{puttygen.comment} |
| 199 | |
| 200 | If you have more than one key and use them for different purposes, |
| 201 | you don't need to memorise the key fingerprints in order to tell |
| 202 | them apart. PuTTY allows you to enter a \e{comment} for your key, |
| 203 | which will be displayed whenever PuTTY or Pageant asks you for the |
| 204 | passphrase. |
| 205 | |
| 206 | The default comment format, if you don't specify one, contains the |
| 207 | key type and the date of generation, such as \c{rsa-key-20011212}. |
| 208 | Another commonly used approach is to use your name and the name of |
| 209 | the computer the key will be used on, such as \c{simon@simons-pc}. |
| 210 | |
| 211 | To alter the key comment, just type your comment text into the |
| 212 | \q{Key comment} box before saving the private key. If you want to |
| 213 | change the comment later, you can load the private key back into |
| 214 | PuTTYgen, change the comment, and save it again. |
| 215 | |
| 216 | \S{puttygen-passphrase} Setting a passphrase for your key |
| 217 | |
| 218 | \cfg{winhelp-topic}{puttygen.passphrase} |
| 219 | |
| 220 | The \q{Key passphrase} and \q{Confirm passphrase} boxes allow you to |
| 221 | choose a passphrase for your key. The passphrase will be used to |
| 222 | encrypt the key on disk, so you will not be able to use the key |
| 223 | without first entering the passphrase. |
| 224 | |
| 225 | When you save the key, PuTTY will check that the \q{Key passphrase} |
| 226 | and \q{Confirm passphrase} boxes both contain exactly the same |
| 227 | passphrase, and will refuse to save the key otherwise. |
| 228 | |
| 229 | If you leave the passphrase fields blank, the key will be saved |
| 230 | unencrypted. You should \e{not} do this without good reason; if you |
| 231 | do, your private key file on disk will be all an attacker needs to |
| 232 | gain access to any machine configured to accept that key. If you |
| 233 | want to be able to log in without having to type a passphrase every |
| 234 | time, you should consider using Pageant (\k{pageant}) so that your |
| 235 | decrypted key is only held in memory rather than on disk. |
| 236 | |
| 237 | Under special circumstances you may genuinely \e{need} to use a key |
| 238 | with no passphrase; for example, if you need to run an automated |
| 239 | batch script that needs to make an SSH connection, you can't be |
| 240 | there to type the passphrase. In this case we recommend you generate |
| 241 | a special key for each specific batch script (or whatever) that |
| 242 | needs one, and on the server side you should arrange that each key |
| 243 | is \e{restricted} so that it can only be used for that specific |
| 244 | purpose. The documentation for your SSH server should explain how to |
| 245 | do this (it will probably vary between servers). |
| 246 | |
| 247 | Choosing a good passphrase is difficult. Just as you shouldn't use a |
| 248 | dictionary word as a password because it's easy for an attacker to |
| 249 | run through a whole dictionary, you should not use a song lyric, |
| 250 | quotation or other well-known sentence as a passphrase. DiceWare |
| 251 | (\W{http://www.diceware.com/}\cw{www.diceware.com}) recommends using |
| 252 | at least five words each generated randomly by rolling five dice, |
| 253 | which gives over 2^64 possible passphrases and is probably not a bad |
| 254 | scheme. If you want your passphrase to make grammatical sense, this |
| 255 | cuts down the possibilities a lot and you should use a longer one as |
| 256 | a result. |
| 257 | |
| 258 | \e{Do not forget your passphrase}. There is no way to recover it. |
| 259 | |
| 260 | \S{puttygen-savepriv} Saving your private key to a disk file |
| 261 | |
| 262 | \cfg{winhelp-topic}{puttygen.savepriv} |
| 263 | |
| 264 | Once you have generated a key, set a comment field and set a |
| 265 | passphrase, you are ready to save your private key to disk. |
| 266 | |
| 267 | Press the \q{Save private key} button. PuTTYgen will put up a dialog |
| 268 | box asking you where to save the file. Select a directory, type in a |
| 269 | file name, and press \q{Save}. |
| 270 | |
| 271 | This file is the one you will need to tell PuTTY to use for |
| 272 | authentication (see \k{config-ssh-privkey}) or tell Pageant to load |
| 273 | (see \k{pageant-mainwin-addkey}). |
| 274 | |
| 275 | \S{puttygen-savepub} Saving your public key to a disk file |
| 276 | |
| 277 | \cfg{winhelp-topic}{puttygen.savepub} |
| 278 | |
| 279 | The SSH 2 protocol drafts specify a standard format for storing |
| 280 | public keys on disk. Some SSH servers (such as \cw{ssh.com}'s) |
| 281 | require a public key in this format in order to accept |
| 282 | authentication with the corresponding private key. (Others, such as |
| 283 | OpenSSH, use a different format; see \k{puttygen-pastekey}.) |
| 284 | |
| 285 | To save your public key in the SSH 2 standard format, press the |
| 286 | \q{Save public key} button in PuTTYgen. PuTTYgen will put up a |
| 287 | dialog box asking you where to save the file. Select a directory, |
| 288 | type in a file name, and press \q{Save}. |
| 289 | |
| 290 | You will then probably want to copy the public key file to your SSH |
| 291 | server machine. See \k{pubkey-gettingready} for general instructions |
| 292 | on configuring public-key authentication once you have generated a |
| 293 | key. |
| 294 | |
| 295 | If you use this option with an SSH 1 key, the file PuTTYgen saves |
| 296 | will contain exactly the same text that appears in the \q{Public key |
| 297 | for pasting} box. This is the only existing standard for SSH 1 |
| 298 | public keys. |
| 299 | |
| 300 | \S{puttygen-pastekey} \q{Public key for pasting into authorized_keys |
| 301 | file} |
| 302 | |
| 303 | \cfg{winhelp-topic}{puttygen.pastekey} |
| 304 | |
| 305 | All SSH 1 servers require your public key to be given to it in a |
| 306 | one-line format before it will accept authentication with your |
| 307 | private key. The OpenSSH server also requires this for SSH 2. |
| 308 | |
| 309 | The \q{Public key for pasting into authorized_keys file} gives the |
| 310 | public-key data in the correct one-line format. Typically you will |
| 311 | want to select the entire contents of the box using the mouse, press |
| 312 | Ctrl+C to copy it to the clipboard, and then paste the data into a |
| 313 | PuTTY session which is already connected to the server. |
| 314 | |
| 315 | See \k{pubkey-gettingready} for general instructions on configuring |
| 316 | public-key authentication once you have generated a key. |
| 317 | |
| 318 | \S{puttygen-load} Reloading a private key |
| 319 | |
| 320 | \cfg{winhelp-topic}{puttygen.load} |
| 321 | |
| 322 | PuTTYgen allows you to load an existing private key file into |
| 323 | memory. If you do this, you can then change the passphrase and |
| 324 | comment before saving it again; you can also make extra copies of |
| 325 | the public key. |
| 326 | |
| 327 | To load an existing key, press the \q{Load} button. PuTTYgen will |
| 328 | put up a dialog box where you can browse around the file system and |
| 329 | find your key file. Once you select the file, PuTTYgen will ask you |
| 330 | for a passphrase (if necessary) and will then display the key |
| 331 | details in the same way as if it had just generated the key. |
| 332 | |
| 333 | If you use the Load command to load a foreign key format, it will |
| 334 | work, but you will see a message box warning you that the key you |
| 335 | have loaded is not a PuTTY native key. See \k{puttygen-conversions} |
| 336 | for information about importing foreign key formats. |
| 337 | |
| 338 | \S{puttygen-conversions} Dealing with private keys in other formats |
| 339 | |
| 340 | \cfg{winhelp-topic}{puttygen.conversions} |
| 341 | |
| 342 | Most SSH1 clients use a standard format for storing private keys on |
| 343 | disk. PuTTY uses this format as well; so if you have generated an |
| 344 | SSH1 private key using OpenSSH or \cw{ssh.com}'s client, you can use |
| 345 | it with PuTTY, and vice versa. |
| 346 | |
| 347 | However, SSH2 private keys have no standard format. OpenSSH and |
| 348 | \cw{ssh.com} have different formats, and PuTTY's is different again. |
| 349 | So a key generated with one client cannot immediately be used with |
| 350 | another. |
| 351 | |
| 352 | Using the \q{Import} command from the \q{Conversions} menu, PuTTYgen |
| 353 | can load SSH2 private keys in OpenSSH's format and \cw{ssh.com}'s |
| 354 | format. Once you have loaded one of these key types, you can then |
| 355 | save it back out as a PuTTY-format key so that you can use it with |
| 356 | PuTTY. The passphrase will be unchanged by this process (unless you |
| 357 | deliberately change it). You may want to change the key comment |
| 358 | before you save the key, since OpenSSH's SSH2 key format contains no |
| 359 | space for a comment and \cw{ssh.com}'s default comment format is |
| 360 | long and verbose. |
| 361 | |
| 362 | PuTTYgen can also export private keys in OpenSSH format and in |
| 363 | \cw{ssh.com} format. To do so, select one of the \q{Export} options |
| 364 | from the \q{Conversions} menu. Exporting a key works exactly like |
| 365 | saving it (see \k{puttygen-savepriv}) - you need to have typed your |
| 366 | passphrase in beforehand, and you will be warned if you are about to |
| 367 | save a key without a passphrase. |
| 368 | |
| 369 | Note that since only SSH2 keys come in different formats, the export |
| 370 | options are not available if you have generated an SSH1 key. |
| 371 | |
| 372 | \H{pubkey-gettingready} Getting ready for public key authentication |
| 373 | |
| 374 | Connect to your SSH server using PuTTY with the SSH protocol. When the |
| 375 | connection succeeds you will be prompted for your user name and |
| 376 | password to login. Once logged in, you must configure the server to |
| 377 | accept your public key for authentication: |
| 378 | |
| 379 | \b If your server is using the SSH 1 protocol, you should change |
| 380 | into the \c{.ssh} directory and open the file \c{authorized_keys} |
| 381 | with your favourite editor. (You may have to create this file if |
| 382 | this is the first key you have put in it). Then switch to the |
| 383 | PuTTYgen window, select all of the text in the \q{Public key for |
| 384 | pasting into authorized_keys file} box (see \k{puttygen-pastekey}), |
| 385 | and copy it to the clipboard (\c{Ctrl+C}). Then, switch back to the |
| 386 | PuTTY window and insert the data into the open file, making sure it |
| 387 | ends up all on one line. Save the file. |
| 388 | |
| 389 | \b If your server is OpenSSH and is using the SSH 2 protocol, you |
| 390 | should follow the same instructions, except that in earlier versions |
| 391 | of OpenSSH 2 the file might be called \c{authorized_keys2}. (In |
| 392 | modern versions the same \c{authorized_keys} file is used for both |
| 393 | SSH 1 and SSH 2 keys.) |
| 394 | |
| 395 | \b If your server is \cw{ssh.com}'s SSH 2 product, you need to save |
| 396 | a \e{public} key file from PuTTYgen (see \k{puttygen-savepub}), and |
| 397 | copy that into the \c{.ssh2} directory on the server. Then you |
| 398 | should go into that \c{.ssh2} directory, and edit (or create) a file |
| 399 | called \c{authorization}. In this file you should put a line like |
| 400 | \c{Key mykey.pub}, with \c{mykey.pub} replaced by the name of your |
| 401 | key file. |
| 402 | |
| 403 | \b For other SSH server software, you should refer to the manual for |
| 404 | that server. |
| 405 | |
| 406 | You may also need to ensure that your home directory, your \c{.ssh} |
| 407 | directory, and any other files involved (such as |
| 408 | \c{authorized_keys}, \c{authorized_keys2} or \c{authorization}) are |
| 409 | not group-writable. You can typically do this by using a command |
| 410 | such as |
| 411 | |
| 412 | \c chmod g-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys |
| 413 | |
| 414 | Your server should now be configured to accept authentication using |
| 415 | your private key. Now you need to configure PuTTY to \e{attempt} |
| 416 | authentication using your private key. You can do this in any of |
| 417 | three ways: |
| 418 | |
| 419 | \b Select the private key in PuTTY's configuration. See |
| 420 | \k{config-ssh-privkey} for details. |
| 421 | |
| 422 | \b Specify the key file on the command line with the \c{-i} option. |
| 423 | See \k{using-cmdline-identity} for details. |
| 424 | |
| 425 | \b Load the private key into Pageant (see \k{pageant}). In this case |
| 426 | PuTTY will automatically try to use it for authentication if it can. |