f21d1674 |
1 | \versionid $Id: pubkey.but,v 1.13 2001/12/14 09:58:07 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 | |
66 | PuTTYgen is a key generator. It generates pairs of public and private |
67 | keys to be used with PuTTY, PSCP, and Plink, as well as the PuTTY |
68 | authentication agent, Pageant (see \k{pageant}). PuTTYgen generates |
69 | RSA keys. |
70 | |
71 | When you run PuTTYgen you will see a window where you have two |
72 | choices: \q{Generate}, to generate a new public/private key pair, or |
73 | \q{Load} to load in an existing private key. |
74 | |
75 | \S{puttygen-generating} Generating a new key |
76 | |
77 | This is a general outline of the procedure for generating a new key |
78 | pair. The following sections describe the process in more detail. |
79 | |
80 | \b First, you need to select which type of key you want to generate, |
81 | and also select the strength of the key. This is described in more |
82 | detail in \k{puttygen-keytype} and |
83 | \k{puttygen-strength}. |
84 | |
85 | \b Then press the \q{Generate} button, to actually generate the key. |
86 | \K{puttygen-generate} describes this step. |
87 | |
88 | \b Once you have generated the key, select a comment field |
89 | (\k{puttygen-comment}) and a passphrase (\k{puttygen-passphrase}). |
90 | |
91 | \b Now you're ready to save the private key to disk; press the |
92 | \q{Save private key} button. (See \k{puttygen-savepriv}). |
93 | |
94 | Your key pair is now ready for use. You may also want to copy the |
95 | public key to your server, either by copying it out of the \q{Public |
96 | key for pasting into authorized_keys file} box (see |
97 | \k{puttygen-pastekey}), or by using the \q{Save public key} button |
98 | (\k{puttygen-savepub}). However, you don't need to do this |
99 | immediately; if you want, you can load the private key back into |
100 | PuTTYgen later (see \k{puttygen-load}) and the public key will be |
101 | available for copying and pasting again. |
5c72ca61 |
102 | |
0906628e |
103 | \k{pubkey-gettingready} describes the typical process of configuring |
104 | PuTTY to attempt public-key authentication, and configuring your SSH |
105 | server to accept it. |
106 | |
107 | \S{puttygen-keytype} Selecting the type of key |
108 | |
109 | \cfg{winhelp-topic}{puttygen.keytype} |
110 | |
111 | Before generating a public key using PuTTYgen, you need to select |
112 | which type of key you need. PuTTYgen currently supports three types |
113 | of key: |
5c72ca61 |
114 | |
115 | \b An RSA key for use with the SSH 1 protocol. |
9e55cd45 |
116 | |
5c72ca61 |
117 | \b An RSA key for use with the SSH 2 protocol. |
9e55cd45 |
118 | |
5c72ca61 |
119 | \b A DSA key for use with the SSH 2 protocol. |
120 | |
121 | The SSH 1 protocol only supports RSA keys; if you will be connecting |
122 | using the SSH 1 protocol, you must select the first key type or your |
123 | key will be completely useless. |
124 | |
0906628e |
125 | The SSH 2 protocol supports more than one key type. The two types |
126 | supported by PuTTY are RSA and DSA. |
5c72ca61 |
127 | |
128 | The PuTTY developers \e{strongly} recommend you use RSA. DSA has an |
129 | intrinsic weakness which makes it very easy to create a signature |
130 | which contains enough information to give away the \e{private} key! |
131 | This would allow an attacker to pretend to be you for any number of |
132 | future sessions. PuTTY's implementation has taken very careful |
133 | precautions to avoid this weakness, but we cannot be 100% certain we |
134 | have managed it, and if you have the choice we strongly recommend |
135 | using RSA keys instead. |
136 | |
137 | If you really need to connect to an SSH server which only supports |
138 | DSA, then you probably have no choice but to use DSA. If you do use |
139 | DSA, we recommend you do not use the same key to authenticate with |
140 | more than one server. |
141 | |
0906628e |
142 | \S{puttygen-strength} Selecting the size (strength) of the key |
024f5783 |
143 | |
0906628e |
144 | \cfg{winhelp-topic}{puttygen.bits} |
024f5783 |
145 | |
0906628e |
146 | The \q{Number of bits} input box allows you to choose the strength |
147 | of the key PuTTYgen will generate. |
148 | |
149 | Currently 1024 bits should be sufficient for most purposes. |
150 | |
151 | \S{puttygen-generate} The \q{Generate} button |
152 | |
153 | \cfg{winhelp-topic}{puttygen.generate} |
154 | |
155 | Once you have chosen the type of key you want, and the strength of |
156 | the key, press the \q{Generate} button and PuTTYgen will begin the |
157 | process of actually generating the key. |
158 | |
159 | First, a progress bar will appear and PuTTYgen will ask you to move |
160 | the mouse around to generate randomness. Wave the mouse in circles |
161 | over the blank area in the PuTTYgen window, and the progress bar |
162 | will gradually fill up as PuTTYgen collects enough randomness. You |
163 | don't need to wave the mouse in particularly imaginative patterns |
164 | (although it can't hurt); PuTTYgen will collect enough randomness |
165 | just from the fine detail of \e{exactly} how far the mouse has moved |
166 | each time Windows samples its position. |
167 | |
168 | When the progress bar reaches the end, PuTTYgen will begin creating |
169 | the key. The progress bar will reset to the start, and gradually |
170 | move up again to track the progress of the key generation. It will |
171 | not move evenly, and may occasionally slow down to a stop; this is |
172 | unfortunately unavoidable, because key generation is a random |
173 | process and it is impossible to reliably predict how long it will |
174 | take. |
175 | |
176 | When the key generation is complete, a new set of controls will |
177 | appear in the window to indicate this. |
178 | |
179 | \S{puttygen-fingerprint} The \q{Key fingerprint} box |
024f5783 |
180 | |
0906628e |
181 | \cfg{winhelp-topic}{puttygen.fingerprint} |
182 | |
183 | The \q{Key fingerprint} box shows you a fingerprint value for the |
184 | generated key. This is derived cryptographically from the \e{public} |
185 | key value, so it doesn't need to be kept secret. |
186 | |
187 | The fingerprint value is intended to be cryptographically secure, in |
188 | the sense that it is computationally infeasible for someone to |
189 | invent a second key with the same fingerprint, or to find a key with |
190 | a particular fingerprint. So some utilities, such as the Pageant key |
191 | list box (see \k{pageant-mainwin-keylist}) and the Unix \c{ssh-add} |
192 | utility, will list key fingerprints rather than the whole public key. |
193 | |
194 | \S{puttygen-comment} Setting a comment for your key |
195 | |
196 | \cfg{winhelp-topic}{puttygen.comment} |
197 | |
198 | If you have more than one key and use them for different purposes, |
199 | you don't need to memorise the key fingerprints in order to tell |
200 | them apart. PuTTY allows you to enter a \e{comment} for your key, |
201 | which will be displayed whenever PuTTY or Pageant asks you for the |
202 | passphrase. |
203 | |
204 | The default comment format, if you don't specify one, contains the |
205 | key type and the date of generation, such as \c{rsa-key-20011212}. |
206 | Another commonly used approach is to use your name and the name of |
207 | the computer the key will be used on, such as \c{simon@simons-pc}. |
208 | |
209 | To alter the key comment, just type your comment text into the |
210 | \q{Key comment} box before saving the private key. If you want to |
211 | change the comment later, you can load the private key back into |
212 | PuTTYgen, change the comment, and save it again. |
213 | |
214 | \S{puttygen-passphrase} Setting a passphrase for your key |
215 | |
216 | \cfg{winhelp-topic}{puttygen.passphrase} |
217 | |
218 | The \q{Key passphrase} and \q{Confirm passphrase} boxes allow you to |
219 | choose a passphrase for your key. The passphrase will be used to |
220 | encrypt the key on disk, so you will not be able to use the key |
221 | without first entering the passphrase. |
222 | |
223 | When you save the key, PuTTY will check that the \q{Key passphrase} |
224 | and \q{Confirm passphrase} boxes both contain exactly the same |
225 | passphrase, and will refuse to save the key otherwise. |
226 | |
227 | If you leave the passphrase fields blank, the key will be saved |
228 | unencrypted. You should \e{not} do this without good reason; if you |
229 | do, your private key file on disk will be all an attacker needs to |
230 | gain access to any machine configured to accept that key. If you |
231 | want to be able to log in without having to type a passphrase every |
232 | time, you should consider using Pageant (\k{pageant}) so that your |
233 | decrypted key is only held in memory rather than on disk. |
234 | |
235 | Under special circumstances you may genuinely \e{need} to use a key |
236 | with no passphrase; for example, if you need to run an automated |
237 | batch script that needs to make an SSH connection, you can't be |
238 | there to type the passphrase. In this case we recommend you generate |
239 | a special key for each specific batch script (or whatever) that |
240 | needs one, and on the server side you should arrange that each key |
241 | is \e{restricted} so that it can only be used for that specific |
242 | purpose. The documentation for your SSH server should explain how to |
243 | do this (it will probably vary between servers). |
244 | |
245 | Choosing a good passphrase is difficult. Just as you shouldn't use a |
246 | dictionary word as a password because it's easy for an attacker to |
8f1529bc |
247 | run through a whole dictionary, you should not use a song lyric, |
248 | quotation or other well-known sentence as a passphrase. DiceWare |
eb92e68f |
249 | (\W{http://www.diceware.com/}\cw{www.diceware.com}) recommends using |
250 | at least five words each generated randomly by rolling five dice, |
65befd9c |
251 | which gives over 2^64 possible passphrases and is probably not a bad |
eb92e68f |
252 | scheme. If you want your passphrase to make grammatical sense, this |
253 | cuts down the possibilities a lot and you should use a longer one as |
0906628e |
254 | a result. |
255 | |
256 | \e{Do not forget your passphrase}. There is no way to recover it. |
257 | |
258 | \S{puttygen-savepriv} Saving your private key to a disk file |
259 | |
260 | \cfg{winhelp-topic}{puttygen.savepriv} |
261 | |
262 | Once you have generated a key, set a comment field and set a |
263 | passphrase, you are ready to save your private key to disk. |
264 | |
265 | Press the \q{Save private key} button. PuTTYgen will put up a dialog |
266 | box asking you where to save the file. Select a directory, type in a |
267 | file name, and press \q{Save}. |
024f5783 |
268 | |
0906628e |
269 | This file is the one you will need to tell PuTTY to use for |
270 | authentication (see \k{config-ssh-privkey}) or tell Pageant to load |
271 | (see \k{pageant-mainwin-addkey}). |
024f5783 |
272 | |
0906628e |
273 | \S{puttygen-savepub} Saving your public key to a disk file |
024f5783 |
274 | |
0906628e |
275 | \cfg{winhelp-topic}{puttygen.savepub} |
024f5783 |
276 | |
0906628e |
277 | The SSH 2 protocol drafts specify a standard format for storing |
278 | public keys on disk. Some SSH servers (such as \cw{ssh.com}'s) |
279 | require a public key in this format in order to accept |
280 | authentication with the corresponding private key. (Others, such as |
281 | OpenSSH, use a different format; see \k{puttygen-pastekey}.) |
282 | |
283 | To save your public key in the SSH 2 standard format, press the |
284 | \q{Save public key} button in PuTTYgen. PuTTYgen will put up a |
285 | dialog box asking you where to save the file. Select a directory, |
286 | type in a file name, and press \q{Save}. |
287 | |
288 | You will then probably want to copy the public key file to your SSH |
289 | server machine. See \k{pubkey-gettingready} for general instructions |
290 | on configuring public-key authentication once you have generated a |
291 | key. |
292 | |
293 | If you use this option with an SSH 1 key, the file PuTTYgen saves |
294 | will contain exactly the same text that appears in the \q{Public key |
295 | for pasting} box. This is the only existing standard for SSH 1 |
296 | public keys. |
297 | |
298 | \S{puttygen-pastekey} \q{Public key for pasting into authorized_keys |
299 | file} |
300 | |
301 | \cfg{winhelp-topic}{puttygen.pastekey} |
302 | |
303 | All SSH 1 servers require your public key to be given to it in a |
304 | one-line format before it will accept authentication with your |
305 | private key. The OpenSSH server also requires this for SSH 2. |
306 | |
307 | The \q{Public key for pasting into authorized_keys file} gives the |
308 | public-key data in the correct one-line format. Typically you will |
309 | want to select the entire contents of the box using the mouse, press |
310 | Ctrl+C to copy it to the clipboard, and then paste the data into a |
311 | PuTTY session which is already connected to the server. |
312 | |
313 | See \k{pubkey-gettingready} for general instructions on configuring |
314 | public-key authentication once you have generated a key. |
315 | |
316 | \S{puttygen-load} Reloading a private key |
317 | |
318 | \cfg{winhelp-topic}{puttygen.load} |
319 | |
320 | PuTTYgen allows you to load an existing private key file into |
321 | memory. If you do this, you can then change the passphrase and |
322 | comment before saving it again; you can also make extra copies of |
323 | the public key. |
324 | |
325 | To load an existing key, press the \q{Load} button. PuTTYgen will |
326 | put up a dialog box where you can browse around the file system and |
327 | find your key file. Once you select the file, PuTTYgen will ask you |
328 | for a passphrase (if necessary) and will then display the key |
329 | details in the same way as if it had just generated the key. |
330 | |
331 | \H{pubkey-gettingready} Getting ready for public key authentication |
024f5783 |
332 | |
333 | Connect to your SSH server using PuTTY with the SSH protocol. When the |
334 | connection succeeds you will be prompted for your user name and |
5c72ca61 |
335 | password to login. Once logged in, you must configure the server to |
336 | accept your public key for authentication: |
337 | |
338 | \b If your server is using the SSH 1 protocol, you should change |
339 | into the \c{.ssh} directory and open the file \c{authorized_keys} |
f21d1674 |
340 | with your favourite editor. (You may have to create this file if |
341 | this is the first key you have put in it). Then switch to the |
342 | PuTTYgen window, select all of the text in the \q{Public key for |
343 | pasting into authorized_keys file} box (see \k{puttygen-pastekey}), |
344 | and copy it to the clipboard (\c{Ctrl+C}). Then, switch back to the |
345 | PuTTY window and insert the data into the open file, making sure it |
346 | ends up all on one line. Save the file. |
5c72ca61 |
347 | |
348 | \b If your server is OpenSSH and is using the SSH 2 protocol, you |
0906628e |
349 | should follow the same instructions, except that in earlier versions |
350 | of OpenSSH 2 the file might be called \c{authorized_keys2}. (In |
351 | modern versions the same \c{authorized_keys} file is used for both |
352 | SSH 1 and SSH 2 keys.) |
5c72ca61 |
353 | |
354 | \b If your server is \cw{ssh.com}'s SSH 2 product, you need to save |
0906628e |
355 | a \e{public} key file from PuTTYgen (see \k{puttygen-savepub}), and |
356 | copy that into the \c{.ssh2} directory on the server. Then you |
357 | should go into that \c{.ssh2} directory, and edit (or create) a file |
358 | called \c{authorization}. In this file you should put a line like |
359 | \c{Key mykey.pub}, with \c{mykey.pub} replaced by the name of your |
360 | key file. |
5c72ca61 |
361 | |
362 | \b For other SSH server software, you should refer to the manual for |
363 | that server. |
364 | |
0906628e |
365 | You may also need to ensure that your home directory, your \c{.ssh} |
366 | directory, and any other files involved (such as |
367 | \c{authorized_keys}, \c{authorized_keys2} or \c{authorization}) are |
368 | not group-writable. You can typically do this by using a command |
369 | such as |
370 | |
371 | \c chmod g-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys |
372 | |
373 | Your server should now be configured to accept authentication using |
374 | your private key. Now you need to configure PuTTY to \e{attempt} |
375 | authentication using your private key. You can do this in either of |
376 | two ways: |
377 | |
378 | \b Select the private key in PuTTY's configuration. See |
379 | \k{config-ssh-privkey} for details. |
380 | |
381 | \b Load the private key into Pageant (see \k{pageant}). In this case |
382 | PuTTY will automatically try to use it for authentication if it can. |