9dda6459 |
1 | \versionid $Id: pubkey.but,v 1.14 2002/05/11 16:45:29 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 |
51 | and load your public 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 |
71 | RSA 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. |
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 | |
113 | Before generating a public key using PuTTYgen, you need to select |
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 | |
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 |
024f5783 |
182 | |
0906628e |
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 |
8f1529bc |
249 | run through a whole dictionary, you should not use a song lyric, |
250 | quotation or other well-known sentence as a passphrase. DiceWare |
eb92e68f |
251 | (\W{http://www.diceware.com/}\cw{www.diceware.com}) recommends using |
252 | at least five words each generated randomly by rolling five dice, |
65befd9c |
253 | which gives over 2^64 possible passphrases and is probably not a bad |
eb92e68f |
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 |
0906628e |
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}. |
024f5783 |
270 | |
0906628e |
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}). |
024f5783 |
274 | |
0906628e |
275 | \S{puttygen-savepub} Saving your public key to a disk file |
024f5783 |
276 | |
0906628e |
277 | \cfg{winhelp-topic}{puttygen.savepub} |
024f5783 |
278 | |
0906628e |
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 | \H{pubkey-gettingready} Getting ready for public key authentication |
024f5783 |
334 | |
335 | Connect to your SSH server using PuTTY with the SSH protocol. When the |
336 | connection succeeds you will be prompted for your user name and |
5c72ca61 |
337 | password to login. Once logged in, you must configure the server to |
338 | accept your public key for authentication: |
339 | |
340 | \b If your server is using the SSH 1 protocol, you should change |
341 | into the \c{.ssh} directory and open the file \c{authorized_keys} |
f21d1674 |
342 | with your favourite editor. (You may have to create this file if |
343 | this is the first key you have put in it). Then switch to the |
344 | PuTTYgen window, select all of the text in the \q{Public key for |
345 | pasting into authorized_keys file} box (see \k{puttygen-pastekey}), |
346 | and copy it to the clipboard (\c{Ctrl+C}). Then, switch back to the |
347 | PuTTY window and insert the data into the open file, making sure it |
348 | ends up all on one line. Save the file. |
5c72ca61 |
349 | |
350 | \b If your server is OpenSSH and is using the SSH 2 protocol, you |
0906628e |
351 | should follow the same instructions, except that in earlier versions |
352 | of OpenSSH 2 the file might be called \c{authorized_keys2}. (In |
353 | modern versions the same \c{authorized_keys} file is used for both |
354 | SSH 1 and SSH 2 keys.) |
5c72ca61 |
355 | |
356 | \b If your server is \cw{ssh.com}'s SSH 2 product, you need to save |
0906628e |
357 | a \e{public} key file from PuTTYgen (see \k{puttygen-savepub}), and |
358 | copy that into the \c{.ssh2} directory on the server. Then you |
359 | should go into that \c{.ssh2} directory, and edit (or create) a file |
360 | called \c{authorization}. In this file you should put a line like |
361 | \c{Key mykey.pub}, with \c{mykey.pub} replaced by the name of your |
362 | key file. |
5c72ca61 |
363 | |
364 | \b For other SSH server software, you should refer to the manual for |
365 | that server. |
366 | |
0906628e |
367 | You may also need to ensure that your home directory, your \c{.ssh} |
368 | directory, and any other files involved (such as |
369 | \c{authorized_keys}, \c{authorized_keys2} or \c{authorization}) are |
370 | not group-writable. You can typically do this by using a command |
371 | such as |
372 | |
373 | \c chmod g-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys |
374 | |
375 | Your server should now be configured to accept authentication using |
376 | your private key. Now you need to configure PuTTY to \e{attempt} |
377 | authentication using your private key. You can do this in either of |
378 | two ways: |
379 | |
380 | \b Select the private key in PuTTY's configuration. See |
381 | \k{config-ssh-privkey} for details. |
382 | |
383 | \b Load the private key into Pageant (see \k{pageant}). In this case |
384 | PuTTY will automatically try to use it for authentication if it can. |