1 \define{versionidpubkey} \versionid $Id$
3 \C{pubkey} Using public keys for SSH authentication
5 \H{pubkey-intro} \ii{Public key authentication} - an introduction
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.
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
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.
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
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.
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.
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}.
64 \H{pubkey-puttygen} Using \i{PuTTYgen}, the PuTTY key generator
66 \cfg{winhelp-topic}{puttygen.general}
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.
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.
77 \S{puttygen-generating} Generating a new key
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.
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}.
87 \b Then press the \q{Generate} button, to actually generate the key.
88 \K{puttygen-generate} describes this step.
90 \b Once you have generated the key, select a comment field
91 (\k{puttygen-comment}) and a passphrase (\k{puttygen-passphrase}).
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}).
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.
105 \K{pubkey-gettingready} describes the typical process of configuring
106 PuTTY to attempt public-key authentication, and configuring your SSH
109 \S{puttygen-keytype} Selecting the type of key
111 \cfg{winhelp-topic}{puttygen.keytype}
113 Before generating a key pair using PuTTYgen, you need to select
114 which type of key you need. PuTTYgen currently supports three types
117 \b An \i{RSA} key for use with the SSH-1 protocol.
119 \b An RSA key for use with the SSH-2 protocol.
121 \b A \i{DSA} key for use with the SSH-2 protocol.
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.
127 The SSH-2 protocol supports more than one key type. The two types
128 supported by PuTTY are RSA and DSA.
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.
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.
145 \S{puttygen-strength} Selecting the size (strength) of the key
147 \cfg{winhelp-topic}{puttygen.bits}
149 The \q{Number of bits} input box allows you to choose the strength
150 of the key PuTTYgen will generate.
152 Currently 1024 bits should be sufficient for most purposes.
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.
163 DSA keys are not created by multiplying primes together, so they
164 should always be exactly the length you asked for.
166 \S{puttygen-generate} The \q{Generate} button
168 \cfg{winhelp-topic}{puttygen.generate}
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.
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.
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
191 When the key generation is complete, a new set of controls will
192 appear in the window to indicate this.
194 \S{puttygen-fingerprint} The \q{\ii{Key fingerprint}} box
196 \cfg{winhelp-topic}{puttygen.fingerprint}
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.
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.
209 \S{puttygen-comment} Setting a comment for your key
211 \cfg{winhelp-topic}{puttygen.comment}
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
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}.
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.
229 \S{puttygen-passphrase} Setting a \i{passphrase} for your key
231 \cfg{winhelp-topic}{puttygen.passphrase}
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.
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.
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
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).
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
272 \e{Do not forget your passphrase}. There is no way to recover it.
274 \S{puttygen-savepriv} Saving your private key to a disk file
276 \cfg{winhelp-topic}{puttygen.savepriv}
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.
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}.
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}).
290 \S{puttygen-savepub} Saving your public key to a disk file
292 \cfg{winhelp-topic}{puttygen.savepub}
294 The SSH-2 protocol drafts specify a \I{SSH-2 public key format}standard
295 format for storing 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}.)
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}.
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
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
315 \S{puttygen-pastekey} \q{Public key for pasting into \i{authorized_keys
318 \cfg{winhelp-topic}{puttygen.pastekey}
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.
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.
330 See \k{pubkey-gettingready} for general instructions on configuring
331 public-key authentication once you have generated a key.
333 \S{puttygen-load} Reloading a private key
335 \cfg{winhelp-topic}{puttygen.load}
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
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.
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.
353 \S{puttygen-conversions} Dealing with private keys in other formats
355 \cfg{winhelp-topic}{puttygen.conversions}
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.
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
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.
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.
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.
388 \H{pubkey-gettingready} Getting ready for public key authentication
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:
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.
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.)
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.
419 \b For other SSH server software, you should refer to the manual for
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
428 \c chmod go-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys
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
435 \b Select the private key in PuTTY's configuration. See
436 \k{config-ssh-privkey} for details.
438 \b Specify the key file on the command line with the \c{-i} option.
439 See \k{using-cmdline-identity} for details.
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.