39a938f7 |
1 | \define{versionidpubkey} \versionid $Id$ |
024f5783 |
2 | |
e5b0d077 |
3 | \C{pubkey} Using public keys for SSH authentication |
4 | |
421406a4 |
5 | \H{pubkey-intro} \ii{Public key authentication} - an introduction |
024f5783 |
6 | |
388f343b |
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 |
421406a4 |
15 | hacked, or \i\e{spoofed} (see \k{gs-hostkey}), an attacker can learn |
388f343b |
16 | your password. |
17 | |
421406a4 |
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}. |
2f8d6d43 |
22 | A signature created using your private key cannot be forged by |
388f343b |
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 |
2f8d6d43 |
28 | who you are, PuTTY can generate a signature using your private key. |
388f343b |
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 |
421406a4 |
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 |
388f343b |
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 |
421406a4 |
47 | passphrase. One solution to this is to use an \i\e{authentication |
388f343b |
48 | agent}, a separate program which holds decrypted private keys and |
49 | generates signatures on request. PuTTY's authentication agent is |
421406a4 |
50 | called \i{Pageant}. When you begin a Windows session, you start Pageant |
114a2518 |
51 | and load your private key into it (typing your passphrase once). For |
2f8d6d43 |
52 | the rest of your session, you can start PuTTY any number of times |
388f343b |
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. |
e5b0d077 |
58 | |
421406a4 |
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 |
0906628e |
61 | DSS), the USA's federal Digital Signature Standard. The key types |
62 | supported by PuTTY are described in \k{puttygen-keytype}. |
63 | |
421406a4 |
64 | \H{pubkey-puttygen} Using \i{PuTTYgen}, the PuTTY key generator |
0906628e |
65 | |
9dda6459 |
66 | \cfg{winhelp-topic}{puttygen.general} |
67 | |
421406a4 |
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. |
0906628e |
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. |
5c72ca61 |
104 | |
12100b9c |
105 | \K{pubkey-gettingready} describes the typical process of configuring |
0906628e |
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 | |
114a2518 |
113 | Before generating a key pair using PuTTYgen, you need to select |
0906628e |
114 | which type of key you need. PuTTYgen currently supports three types |
115 | of key: |
5c72ca61 |
116 | |
421406a4 |
117 | \b An \i{RSA} key for use with the SSH-1 protocol. |
9e55cd45 |
118 | |
2e85c969 |
119 | \b An RSA key for use with the SSH-2 protocol. |
9e55cd45 |
120 | |
421406a4 |
121 | \b A \i{DSA} key for use with the SSH-2 protocol. |
5c72ca61 |
122 | |
2e85c969 |
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 |
5c72ca61 |
125 | key will be completely useless. |
126 | |
2e85c969 |
127 | The SSH-2 protocol supports more than one key type. The two types |
0906628e |
128 | supported by PuTTY are RSA and DSA. |
5c72ca61 |
129 | |
421406a4 |
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! |
5c72ca61 |
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 | |
0906628e |
145 | \S{puttygen-strength} Selecting the size (strength) of the key |
024f5783 |
146 | |
0906628e |
147 | \cfg{winhelp-topic}{puttygen.bits} |
024f5783 |
148 | |
0906628e |
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 | |
63a890aa |
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 | |
0906628e |
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 | |
421406a4 |
194 | \S{puttygen-fingerprint} The \q{\ii{Key fingerprint}} box |
024f5783 |
195 | |
0906628e |
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 |
b41cfbb5 |
215 | them apart. PuTTYgen allows you to enter a \e{comment} for your key, |
0906628e |
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 | |
421406a4 |
229 | \S{puttygen-passphrase} Setting a \i{passphrase} for your key |
0906628e |
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 |
421406a4 |
235 | \i{encrypt} the key on disk, so you will not be able to use the key |
0906628e |
236 | without first entering the passphrase. |
237 | |
b41cfbb5 |
238 | When you save the key, PuTTYgen will check that the \q{Key passphrase} |
0906628e |
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 |
421406a4 |
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. |
0906628e |
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 |
8f1529bc |
263 | run through a whole dictionary, you should not use a song lyric, |
421406a4 |
264 | quotation or other well-known sentence as a passphrase. \i{DiceWare} |
eb92e68f |
265 | (\W{http://www.diceware.com/}\cw{www.diceware.com}) recommends using |
266 | at least five words each generated randomly by rolling five dice, |
65befd9c |
267 | which gives over 2^64 possible passphrases and is probably not a bad |
eb92e68f |
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 |
0906628e |
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}. |
024f5783 |
284 | |
421406a4 |
285 | This file is in PuTTY's native format (\c{*.\i{PPK}}); it is the one you |
8cee3b72 |
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}). |
024f5783 |
289 | |
0906628e |
290 | \S{puttygen-savepub} Saving your public key to a disk file |
024f5783 |
291 | |
0906628e |
292 | \cfg{winhelp-topic}{puttygen.savepub} |
024f5783 |
293 | |
4b33f610 |
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 |
421406a4 |
296 | \i\cw{ssh.com}'s) require a public key in this format in order to accept |
0906628e |
297 | authentication with the corresponding private key. (Others, such as |
298 | OpenSSH, use a different format; see \k{puttygen-pastekey}.) |
299 | |
2e85c969 |
300 | To save your public key in the SSH-2 standard format, press the |
0906628e |
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 | |
2e85c969 |
310 | If you use this option with an SSH-1 key, the file PuTTYgen saves |
0906628e |
311 | will contain exactly the same text that appears in the \q{Public key |
2e85c969 |
312 | for pasting} box. This is the only existing standard for SSH-1 |
0906628e |
313 | public keys. |
314 | |
421406a4 |
315 | \S{puttygen-pastekey} \q{Public key for pasting into \i{authorized_keys |
316 | file}} |
0906628e |
317 | |
318 | \cfg{winhelp-topic}{puttygen.pastekey} |
319 | |
2e85c969 |
320 | All SSH-1 servers require your public key to be given to it in a |
0906628e |
321 | one-line format before it will accept authentication with your |
421406a4 |
322 | private key. The \i{OpenSSH} server also requires this for SSH-2. |
0906628e |
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 | |
b723338c |
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. |
9d07b2db |
352 | |
b723338c |
353 | \S{puttygen-conversions} Dealing with private keys in other formats |
9d07b2db |
354 | |
b723338c |
355 | \cfg{winhelp-topic}{puttygen.conversions} |
9d07b2db |
356 | |
2e85c969 |
357 | Most SSH-1 clients use a standard format for storing private keys on |
9d07b2db |
358 | disk. PuTTY uses this format as well; so if you have generated an |
2e85c969 |
359 | SSH-1 private key using OpenSSH or \cw{ssh.com}'s client, you can use |
9d07b2db |
360 | it with PuTTY, and vice versa. |
361 | |
421406a4 |
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. |
9d07b2db |
365 | So a key generated with one client cannot immediately be used with |
366 | another. |
367 | |
421406a4 |
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 |
8cee3b72 |
373 | process (unless you deliberately change it). You may want to change |
2e85c969 |
374 | the key comment before you save the key, since OpenSSH's SSH-2 key |
8cee3b72 |
375 | format contains no space for a comment and \cw{ssh.com}'s default |
376 | comment format is long and verbose. |
b723338c |
377 | |
421406a4 |
378 | PuTTYgen can also \i{export private keys} in OpenSSH format and in |
b723338c |
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 | |
2e85c969 |
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. |
9d07b2db |
387 | |
0906628e |
388 | \H{pubkey-gettingready} Getting ready for public key authentication |
024f5783 |
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 |
5c72ca61 |
392 | password to login. Once logged in, you must configure the server to |
393 | accept your public key for authentication: |
394 | |
2e85c969 |
395 | \b If your server is using the SSH-1 protocol, you should change |
421406a4 |
396 | into the \i\c{.ssh} directory and open the file \i\c{authorized_keys} |
f21d1674 |
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. |
5c72ca61 |
404 | |
421406a4 |
405 | \b If your server is \i{OpenSSH} and is using the SSH-2 protocol, you |
0906628e |
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 |
2e85c969 |
409 | SSH-1 and SSH-2 keys.) |
5c72ca61 |
410 | |
421406a4 |
411 | \b If your server is \i\cw{ssh.com}'s product and is using SSH-2, you |
6a5316a5 |
412 | need to save a \e{public} key file from PuTTYgen (see |
421406a4 |
413 | \k{puttygen-savepub}), and copy that into the \i\c{.ssh2} directory on |
6a5316a5 |
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. |
5c72ca61 |
418 | |
419 | \b For other SSH server software, you should refer to the manual for |
420 | that server. |
421 | |
0906628e |
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 |
ae0d43f1 |
425 | not group-writable or world-writable. You can typically do this by |
426 | using a command such as |
0906628e |
427 | |
ae0d43f1 |
428 | \c chmod go-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys |
0906628e |
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} |
e2a197cf |
432 | authentication using your private key. You can do this in any of |
433 | three ways: |
0906628e |
434 | |
435 | \b Select the private key in PuTTY's configuration. See |
436 | \k{config-ssh-privkey} for details. |
437 | |
e2a197cf |
438 | \b Specify the key file on the command line with the \c{-i} option. |
439 | See \k{using-cmdline-identity} for details. |
440 | |
0906628e |
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. |