| 1 | \define{versionidpubkey} \versionid $Id$ |
| 2 | |
| 3 | \C{pubkey} Using public keys for SSH authentication |
| 4 | |
| 5 | \H{pubkey-intro} \ii{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 \i\e{spoofed} (see \k{gs-hostkey}), an attacker can learn |
| 16 | your password. |
| 17 | |
| 18 | Public key authentication solves this problem. You generate a \i\e{key |
| 19 | pair}, consisting of a \i{public key} (which everybody is allowed to |
| 20 | know) and a \i{private key} (which you keep secret and do not give to |
| 21 | anybody). The private key is able to generate \i\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 \i\e{encrypted} when it is |
| 40 | stored on your local machine, using a \i{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 \i\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 \i{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 \i{public-key algorithm} available. The most |
| 60 | common is \i{RSA}, but others exist, notably \i{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 \i{PuTTYgen}, the PuTTY key generator |
| 65 | |
| 66 | \cfg{winhelp-topic}{puttygen.general} |
| 67 | |
| 68 | PuTTYgen is a key generator. It \I{generating keys}generates pairs of |
| 69 | public and private keys to be used with PuTTY, PSCP, and Plink, as well |
| 70 | as the PuTTY authentication agent, Pageant (see \k{pageant}). PuTTYgen |
| 71 | generates 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 \i{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 \i{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. |
| 131 | \I{security risk}\i{DSA} has an intrinsic weakness which makes it very |
| 132 | easy to create a signature which contains enough information to give |
| 133 | away the \e{private} key! |
| 134 | This would allow an attacker to pretend to be you for any number of |
| 135 | future sessions. PuTTY's implementation has taken very careful |
| 136 | precautions to avoid this weakness, but we cannot be 100% certain we |
| 137 | have managed it, and if you have the choice we strongly recommend |
| 138 | using RSA keys instead. |
| 139 | |
| 140 | If you really need to connect to an SSH server which only supports |
| 141 | DSA, then you probably have no choice but to use DSA. If you do use |
| 142 | DSA, we recommend you do not use the same key to authenticate with |
| 143 | more than one server. |
| 144 | |
| 145 | \S{puttygen-strength} Selecting the size (strength) of the key |
| 146 | |
| 147 | \cfg{winhelp-topic}{puttygen.bits} |
| 148 | |
| 149 | The \q{Number of bits} input box allows you to choose the strength |
| 150 | of the key PuTTYgen will generate. |
| 151 | |
| 152 | Currently 1024 bits should be sufficient for most purposes. |
| 153 | |
| 154 | Note that an RSA key is generated by finding two primes of half the |
| 155 | length requested, and then multiplying them together. For example, |
| 156 | if you ask PuTTYgen for a 1024-bit RSA key, it will create two |
| 157 | 512-bit primes and multiply them. The result of this multiplication |
| 158 | might be 1024 bits long, or it might be only 1023; so you may not |
| 159 | get the exact length of key you asked for. This is perfectly normal, |
| 160 | and you do not need to worry. The lengths should only ever differ by |
| 161 | one, and there is no perceptible drop in security as a result. |
| 162 | |
| 163 | DSA keys are not created by multiplying primes together, so they |
| 164 | should always be exactly the length you asked for. |
| 165 | |
| 166 | \S{puttygen-generate} The \q{Generate} button |
| 167 | |
| 168 | \cfg{winhelp-topic}{puttygen.generate} |
| 169 | |
| 170 | Once you have chosen the type of key you want, and the strength of |
| 171 | the key, press the \q{Generate} button and PuTTYgen will begin the |
| 172 | process of actually generating the key. |
| 173 | |
| 174 | First, a progress bar will appear and PuTTYgen will ask you to move |
| 175 | the mouse around to generate randomness. Wave the mouse in circles |
| 176 | over the blank area in the PuTTYgen window, and the progress bar |
| 177 | will gradually fill up as PuTTYgen collects enough randomness. You |
| 178 | don't need to wave the mouse in particularly imaginative patterns |
| 179 | (although it can't hurt); PuTTYgen will collect enough randomness |
| 180 | just from the fine detail of \e{exactly} how far the mouse has moved |
| 181 | each time Windows samples its position. |
| 182 | |
| 183 | When the progress bar reaches the end, PuTTYgen will begin creating |
| 184 | the key. The progress bar will reset to the start, and gradually |
| 185 | move up again to track the progress of the key generation. It will |
| 186 | not move evenly, and may occasionally slow down to a stop; this is |
| 187 | unfortunately unavoidable, because key generation is a random |
| 188 | process and it is impossible to reliably predict how long it will |
| 189 | take. |
| 190 | |
| 191 | When the key generation is complete, a new set of controls will |
| 192 | appear in the window to indicate this. |
| 193 | |
| 194 | \S{puttygen-fingerprint} The \q{\ii{Key fingerprint}} box |
| 195 | |
| 196 | \cfg{winhelp-topic}{puttygen.fingerprint} |
| 197 | |
| 198 | The \q{Key fingerprint} box shows you a fingerprint value for the |
| 199 | generated key. This is derived cryptographically from the \e{public} |
| 200 | key value, so it doesn't need to be kept secret. |
| 201 | |
| 202 | The fingerprint value is intended to be cryptographically secure, in |
| 203 | the sense that it is computationally infeasible for someone to |
| 204 | invent a second key with the same fingerprint, or to find a key with |
| 205 | a particular fingerprint. So some utilities, such as the Pageant key |
| 206 | list box (see \k{pageant-mainwin-keylist}) and the Unix \c{ssh-add} |
| 207 | utility, will list key fingerprints rather than the whole public key. |
| 208 | |
| 209 | \S{puttygen-comment} Setting a comment for your key |
| 210 | |
| 211 | \cfg{winhelp-topic}{puttygen.comment} |
| 212 | |
| 213 | If you have more than one key and use them for different purposes, |
| 214 | you don't need to memorise the key fingerprints in order to tell |
| 215 | them apart. PuTTYgen allows you to enter a \e{comment} for your key, |
| 216 | which will be displayed whenever PuTTY or Pageant asks you for the |
| 217 | passphrase. |
| 218 | |
| 219 | The default comment format, if you don't specify one, contains the |
| 220 | key type and the date of generation, such as \c{rsa-key-20011212}. |
| 221 | Another commonly used approach is to use your name and the name of |
| 222 | the computer the key will be used on, such as \c{simon@simons-pc}. |
| 223 | |
| 224 | To alter the key comment, just type your comment text into the |
| 225 | \q{Key comment} box before saving the private key. If you want to |
| 226 | change the comment later, you can load the private key back into |
| 227 | PuTTYgen, change the comment, and save it again. |
| 228 | |
| 229 | \S{puttygen-passphrase} Setting a \i{passphrase} for your key |
| 230 | |
| 231 | \cfg{winhelp-topic}{puttygen.passphrase} |
| 232 | |
| 233 | The \q{Key passphrase} and \q{Confirm passphrase} boxes allow you to |
| 234 | choose a passphrase for your key. The passphrase will be used to |
| 235 | \i{encrypt} the key on disk, so you will not be able to use the key |
| 236 | without first entering the passphrase. |
| 237 | |
| 238 | When you save the key, PuTTYgen will check that the \q{Key passphrase} |
| 239 | and \q{Confirm passphrase} boxes both contain exactly the same |
| 240 | passphrase, and will refuse to save the key otherwise. |
| 241 | |
| 242 | If you leave the passphrase fields blank, the key will be saved |
| 243 | unencrypted. You should \e{not} do this without good reason; if you |
| 244 | do, your private key file on disk will be all an attacker needs to |
| 245 | gain access to any machine configured to accept that key. If you |
| 246 | want to be able to \i{passwordless login}log in without having to |
| 247 | type a passphrase every time, you should consider using Pageant |
| 248 | (\k{pageant}) so that your decrypted key is only held in memory |
| 249 | rather than on disk. |
| 250 | |
| 251 | Under special circumstances you may genuinely \e{need} to use a key |
| 252 | with no passphrase; for example, if you need to run an automated |
| 253 | batch script that needs to make an SSH connection, you can't be |
| 254 | there to type the passphrase. In this case we recommend you generate |
| 255 | a special key for each specific batch script (or whatever) that |
| 256 | needs one, and on the server side you should arrange that each key |
| 257 | is \e{restricted} so that it can only be used for that specific |
| 258 | purpose. The documentation for your SSH server should explain how to |
| 259 | do this (it will probably vary between servers). |
| 260 | |
| 261 | Choosing a good passphrase is difficult. Just as you shouldn't use a |
| 262 | dictionary word as a password because it's easy for an attacker to |
| 263 | run through a whole dictionary, you should not use a song lyric, |
| 264 | quotation or other well-known sentence as a passphrase. \i{DiceWare} |
| 265 | (\W{http://www.diceware.com/}\cw{www.diceware.com}) recommends using |
| 266 | at least five words each generated randomly by rolling five dice, |
| 267 | which gives over 2^64 possible passphrases and is probably not a bad |
| 268 | scheme. If you want your passphrase to make grammatical sense, this |
| 269 | cuts down the possibilities a lot and you should use a longer one as |
| 270 | a result. |
| 271 | |
| 272 | \e{Do not forget your passphrase}. There is no way to recover it. |
| 273 | |
| 274 | \S{puttygen-savepriv} Saving your private key to a disk file |
| 275 | |
| 276 | \cfg{winhelp-topic}{puttygen.savepriv} |
| 277 | |
| 278 | Once you have generated a key, set a comment field and set a |
| 279 | passphrase, you are ready to save your private key to disk. |
| 280 | |
| 281 | Press the \q{Save private key} button. PuTTYgen will put up a dialog |
| 282 | box asking you where to save the file. Select a directory, type in a |
| 283 | file name, and press \q{Save}. |
| 284 | |
| 285 | This file is in PuTTY's native format (\c{*.\i{PPK}}); it is the one you |
| 286 | will need to tell PuTTY to use for authentication (see |
| 287 | \k{config-ssh-privkey}) or tell Pageant to load (see |
| 288 | \k{pageant-mainwin-addkey}). |
| 289 | |
| 290 | \S{puttygen-savepub} Saving your public key to a disk file |
| 291 | |
| 292 | \cfg{winhelp-topic}{puttygen.savepub} |
| 293 | |
| 294 | RFC 4716 specifies a \I{SSH-2 public key format}standard format for |
| 295 | storing SSH-2 public keys on disk. Some SSH servers (such as |
| 296 | \i\cw{ssh.com}'s) require a public key in this format in order to accept |
| 297 | authentication with the corresponding private key. (Others, such as |
| 298 | OpenSSH, use a different format; see \k{puttygen-pastekey}.) |
| 299 | |
| 300 | To save your public key in the SSH-2 standard format, press the |
| 301 | \q{Save public key} button in PuTTYgen. PuTTYgen will put up a |
| 302 | dialog box asking you where to save the file. Select a directory, |
| 303 | type in a file name, and press \q{Save}. |
| 304 | |
| 305 | You will then probably want to copy the public key file to your SSH |
| 306 | server machine. See \k{pubkey-gettingready} for general instructions |
| 307 | on configuring public-key authentication once you have generated a |
| 308 | key. |
| 309 | |
| 310 | If you use this option with an SSH-1 key, the file PuTTYgen saves |
| 311 | will contain exactly the same text that appears in the \q{Public key |
| 312 | for pasting} box. This is the only existing standard for SSH-1 |
| 313 | public keys. |
| 314 | |
| 315 | \S{puttygen-pastekey} \q{Public key for pasting into \i{authorized_keys |
| 316 | file}} |
| 317 | |
| 318 | \cfg{winhelp-topic}{puttygen.pastekey} |
| 319 | |
| 320 | All SSH-1 servers require your public key to be given to it in a |
| 321 | one-line format before it will accept authentication with your |
| 322 | private key. The \i{OpenSSH} server also requires this for SSH-2. |
| 323 | |
| 324 | The \q{Public key for pasting into authorized_keys file} gives the |
| 325 | public-key data in the correct one-line format. Typically you will |
| 326 | want to select the entire contents of the box using the mouse, press |
| 327 | Ctrl+C to copy it to the clipboard, and then paste the data into a |
| 328 | PuTTY session which is already connected to the server. |
| 329 | |
| 330 | See \k{pubkey-gettingready} for general instructions on configuring |
| 331 | public-key authentication once you have generated a key. |
| 332 | |
| 333 | \S{puttygen-load} Reloading a private key |
| 334 | |
| 335 | \cfg{winhelp-topic}{puttygen.load} |
| 336 | |
| 337 | PuTTYgen allows you to load an existing private key file into |
| 338 | memory. If you do this, you can then change the passphrase and |
| 339 | comment before saving it again; you can also make extra copies of |
| 340 | the public key. |
| 341 | |
| 342 | To load an existing key, press the \q{Load} button. PuTTYgen will |
| 343 | put up a dialog box where you can browse around the file system and |
| 344 | find your key file. Once you select the file, PuTTYgen will ask you |
| 345 | for a passphrase (if necessary) and will then display the key |
| 346 | details in the same way as if it had just generated the key. |
| 347 | |
| 348 | If you use the Load command to load a foreign key format, it will |
| 349 | work, but you will see a message box warning you that the key you |
| 350 | have loaded is not a PuTTY native key. See \k{puttygen-conversions} |
| 351 | for information about importing foreign key formats. |
| 352 | |
| 353 | \S{puttygen-conversions} Dealing with private keys in other formats |
| 354 | |
| 355 | \cfg{winhelp-topic}{puttygen.conversions} |
| 356 | |
| 357 | Most SSH-1 clients use a standard format for storing private keys on |
| 358 | disk. PuTTY uses this format as well; so if you have generated an |
| 359 | SSH-1 private key using OpenSSH or \cw{ssh.com}'s client, you can use |
| 360 | it with PuTTY, and vice versa. |
| 361 | |
| 362 | However, SSH-2 private keys have no standard format. \I{OpenSSH private |
| 363 | key format}OpenSSH and \I{ssh.com private key format}\cw{ssh.com} have |
| 364 | different formats, and PuTTY's is different again. |
| 365 | So a key generated with one client cannot immediately be used with |
| 366 | another. |
| 367 | |
| 368 | Using the \I{importing keys}\q{Import} command from the \q{Conversions} |
| 369 | menu, PuTTYgen can load SSH-2 private keys in OpenSSH's format and |
| 370 | \cw{ssh.com}'s format. Once you have loaded one of these key types, you |
| 371 | can then save it back out as a PuTTY-format key (\c{*.\i{PPK}}) so that |
| 372 | you can use it with the PuTTY suite. The passphrase will be unchanged by this |
| 373 | process (unless you deliberately change it). You may want to change |
| 374 | the key comment before you save the key, since OpenSSH's SSH-2 key |
| 375 | format contains no space for a comment and \cw{ssh.com}'s default |
| 376 | comment format is long and verbose. |
| 377 | |
| 378 | PuTTYgen can also \i{export private keys} in OpenSSH format and in |
| 379 | \cw{ssh.com} format. To do so, select one of the \q{Export} options |
| 380 | from the \q{Conversions} menu. Exporting a key works exactly like |
| 381 | saving it (see \k{puttygen-savepriv}) - you need to have typed your |
| 382 | passphrase in beforehand, and you will be warned if you are about to |
| 383 | save a key without a passphrase. |
| 384 | |
| 385 | Note that since only SSH-2 keys come in different formats, the export |
| 386 | options are not available if you have generated an SSH-1 key. |
| 387 | |
| 388 | \H{pubkey-gettingready} Getting ready for public key authentication |
| 389 | |
| 390 | Connect to your SSH server using PuTTY with the SSH protocol. When the |
| 391 | connection succeeds you will be prompted for your user name and |
| 392 | password to login. Once logged in, you must configure the server to |
| 393 | accept your public key for authentication: |
| 394 | |
| 395 | \b If your server is using the SSH-1 protocol, you should change |
| 396 | into the \i\c{.ssh} directory and open the file \i\c{authorized_keys} |
| 397 | with your favourite editor. (You may have to create this file if |
| 398 | this is the first key you have put in it). Then switch to the |
| 399 | PuTTYgen window, select all of the text in the \q{Public key for |
| 400 | pasting into authorized_keys file} box (see \k{puttygen-pastekey}), |
| 401 | and copy it to the clipboard (\c{Ctrl+C}). Then, switch back to the |
| 402 | PuTTY window and insert the data into the open file, making sure it |
| 403 | ends up all on one line. Save the file. |
| 404 | |
| 405 | \b If your server is \i{OpenSSH} and is using the SSH-2 protocol, you |
| 406 | should follow the same instructions, except that in earlier versions |
| 407 | of OpenSSH 2 the file might be called \c{authorized_keys2}. (In |
| 408 | modern versions the same \c{authorized_keys} file is used for both |
| 409 | SSH-1 and SSH-2 keys.) |
| 410 | |
| 411 | \b If your server is \i\cw{ssh.com}'s product and is using SSH-2, you |
| 412 | need to save a \e{public} key file from PuTTYgen (see |
| 413 | \k{puttygen-savepub}), and copy that into the \i\c{.ssh2} directory on |
| 414 | the server. Then you should go into that \c{.ssh2} directory, and edit |
| 415 | (or create) a file called \c{authorization}. In this file you should |
| 416 | put a line like \c{Key mykey.pub}, with \c{mykey.pub} replaced by the |
| 417 | name of your key file. |
| 418 | |
| 419 | \b For other SSH server software, you should refer to the manual for |
| 420 | that server. |
| 421 | |
| 422 | You may also need to ensure that your home directory, your \c{.ssh} |
| 423 | directory, and any other files involved (such as |
| 424 | \c{authorized_keys}, \c{authorized_keys2} or \c{authorization}) are |
| 425 | not group-writable or world-writable. You can typically do this by |
| 426 | using a command such as |
| 427 | |
| 428 | \c chmod go-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys |
| 429 | |
| 430 | Your server should now be configured to accept authentication using |
| 431 | your private key. Now you need to configure PuTTY to \e{attempt} |
| 432 | authentication using your private key. You can do this in any of |
| 433 | three ways: |
| 434 | |
| 435 | \b Select the private key in PuTTY's configuration. See |
| 436 | \k{config-ssh-privkey} for details. |
| 437 | |
| 438 | \b Specify the key file on the command line with the \c{-i} option. |
| 439 | See \k{using-cmdline-identity} for details. |
| 440 | |
| 441 | \b Load the private key into Pageant (see \k{pageant}). In this case |
| 442 | PuTTY will automatically try to use it for authentication if it can. |