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