Consistently use a single notation to refer to SSH protocol versions, as
[u/mdw/putty] / doc / pubkey.but
CommitLineData
39a938f7 1\define{versionidpubkey} \versionid $Id$
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 7Public key authentication is an alternative means of identifying
8yourself to a login server, instead of typing a password. It is more
9secure and more flexible, but more difficult to set up.
10
11In conventional password authentication, you prove you are who you
12claim to be by proving that you know the correct password. The only
13way to prove you know the password is to tell the server what you
14think the password is. This means that if the server has been
15hacked, or \e{spoofed} (see \k{gs-hostkey}), an attacker can learn
16your password.
17
18Public key authentication solves this problem. You generate a \e{key
19pair}, consisting of a public key (which everybody is allowed to
20know) and a private key (which you keep secret and do not give to
21anybody). The private key is able to generate \e{signatures}.
2f8d6d43 22A signature created using your private key cannot be forged by
388f343b 23anybody who does not have that key; but anybody who has your public
24key can verify that a particular signature is genuine.
25
26So you generate a key pair on your own computer, and you copy the
27public key to the server. Then, when the server asks you to prove
2f8d6d43 28who you are, PuTTY can generate a signature using your private key.
388f343b 29The server can verify that signature (since it has your public key)
30and allow you to log in. Now if the server is hacked or spoofed, the
31attacker does not gain your private key or password; they only gain
32one signature. And signatures cannot be re-used, so they have gained
33nothing.
34
35There is a problem with this: if your private key is stored
36unprotected 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
38they will be able to log in to your server under your account. For
39this reason, your private key is usually \e{encrypted} when it is
40stored on your local machine, using a passphrase of your choice. In
41order to generate a signature, PuTTY must decrypt the key, so you
42have to type your passphrase.
43
44This can make public-key authentication less convenient than
45password authentication: every time you log in to the server,
46instead of typing a short password, you have to type a longer
47passphrase. One solution to this is to use an \e{authentication
48agent}, a separate program which holds decrypted private keys and
49generates signatures on request. PuTTY's authentication agent is
50called Pageant. When you begin a Windows session, you start Pageant
114a2518 51and load your private key into it (typing your passphrase once). For
2f8d6d43 52the rest of your session, you can start PuTTY any number of times
388f343b 53and Pageant will automatically generate signatures without you
54having to do anything. When you close your Windows session, Pageant
55shuts down, without ever having stored your decrypted private key on
56disk. Many people feel this is a good compromise between security
57and convenience. See \k{pageant} for further details.
e5b0d077 58
0906628e 59There is more than one public-key algorithm available. The most
60common is RSA, but others exist, notably DSA (otherwise known as
61DSS), the USA's federal Digital Signature Standard. The key types
62supported 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 68PuTTYgen is a key generator. It generates pairs of public and private
69keys to be used with PuTTY, PSCP, and Plink, as well as the PuTTY
70authentication agent, Pageant (see \k{pageant}). PuTTYgen generates
8dcbc8dd 71RSA and DSA keys.
0906628e 72
73When you run PuTTYgen you will see a window where you have two
74choices: \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
79This is a general outline of the procedure for generating a new key
80pair. 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,
83and also select the strength of the key. This is described in more
84detail 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
96Your key pair is now ready for use. You may also want to copy the
97public key to your server, either by copying it out of the \q{Public
98key 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
101immediately; if you want, you can load the private key back into
102PuTTYgen later (see \k{puttygen-load}) and the public key will be
103available for copying and pasting again.
5c72ca61 104
12100b9c 105\K{pubkey-gettingready} describes the typical process of configuring
0906628e 106PuTTY to attempt public-key authentication, and configuring your SSH
107server to accept it.
108
109\S{puttygen-keytype} Selecting the type of key
110
111\cfg{winhelp-topic}{puttygen.keytype}
112
114a2518 113Before generating a key pair using PuTTYgen, you need to select
0906628e 114which type of key you need. PuTTYgen currently supports three types
115of key:
5c72ca61 116
2e85c969 117\b An 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
2e85c969 121\b A DSA key for use with the SSH-2 protocol.
5c72ca61 122
2e85c969 123The SSH-1 protocol only supports RSA keys; if you will be connecting
124using the SSH-1 protocol, you must select the first key type or your
5c72ca61 125key will be completely useless.
126
2e85c969 127The SSH-2 protocol supports more than one key type. The two types
0906628e 128supported by PuTTY are RSA and DSA.
5c72ca61 129
130The PuTTY developers \e{strongly} recommend you use RSA. DSA has an
131intrinsic weakness which makes it very easy to create a signature
132which contains enough information to give away the \e{private} key!
133This would allow an attacker to pretend to be you for any number of
134future sessions. PuTTY's implementation has taken very careful
135precautions to avoid this weakness, but we cannot be 100% certain we
136have managed it, and if you have the choice we strongly recommend
137using RSA keys instead.
138
139If you really need to connect to an SSH server which only supports
140DSA, then you probably have no choice but to use DSA. If you do use
141DSA, we recommend you do not use the same key to authenticate with
142more 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 148The \q{Number of bits} input box allows you to choose the strength
149of the key PuTTYgen will generate.
150
151Currently 1024 bits should be sufficient for most purposes.
152
63a890aa 153Note that an RSA key is generated by finding two primes of half the
154length requested, and then multiplying them together. For example,
155if you ask PuTTYgen for a 1024-bit RSA key, it will create two
156512-bit primes and multiply them. The result of this multiplication
157might be 1024 bits long, or it might be only 1023; so you may not
158get the exact length of key you asked for. This is perfectly normal,
159and you do not need to worry. The lengths should only ever differ by
160one, and there is no perceptible drop in security as a result.
161
162DSA keys are not created by multiplying primes together, so they
163should 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
169Once you have chosen the type of key you want, and the strength of
170the key, press the \q{Generate} button and PuTTYgen will begin the
171process of actually generating the key.
172
173First, a progress bar will appear and PuTTYgen will ask you to move
174the mouse around to generate randomness. Wave the mouse in circles
175over the blank area in the PuTTYgen window, and the progress bar
176will gradually fill up as PuTTYgen collects enough randomness. You
177don't need to wave the mouse in particularly imaginative patterns
178(although it can't hurt); PuTTYgen will collect enough randomness
179just from the fine detail of \e{exactly} how far the mouse has moved
180each time Windows samples its position.
181
182When the progress bar reaches the end, PuTTYgen will begin creating
183the key. The progress bar will reset to the start, and gradually
184move up again to track the progress of the key generation. It will
185not move evenly, and may occasionally slow down to a stop; this is
186unfortunately unavoidable, because key generation is a random
187process and it is impossible to reliably predict how long it will
188take.
189
190When the key generation is complete, a new set of controls will
191appear 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
197The \q{Key fingerprint} box shows you a fingerprint value for the
198generated key. This is derived cryptographically from the \e{public}
199key value, so it doesn't need to be kept secret.
200
201The fingerprint value is intended to be cryptographically secure, in
202the sense that it is computationally infeasible for someone to
203invent a second key with the same fingerprint, or to find a key with
204a particular fingerprint. So some utilities, such as the Pageant key
205list box (see \k{pageant-mainwin-keylist}) and the Unix \c{ssh-add}
206utility, 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
212If you have more than one key and use them for different purposes,
213you don't need to memorise the key fingerprints in order to tell
214them apart. PuTTY allows you to enter a \e{comment} for your key,
215which will be displayed whenever PuTTY or Pageant asks you for the
216passphrase.
217
218The default comment format, if you don't specify one, contains the
219key type and the date of generation, such as \c{rsa-key-20011212}.
220Another commonly used approach is to use your name and the name of
221the computer the key will be used on, such as \c{simon@simons-pc}.
222
223To 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
225change the comment later, you can load the private key back into
226PuTTYgen, 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
232The \q{Key passphrase} and \q{Confirm passphrase} boxes allow you to
233choose a passphrase for your key. The passphrase will be used to
234encrypt the key on disk, so you will not be able to use the key
235without first entering the passphrase.
236
237When you save the key, PuTTY will check that the \q{Key passphrase}
238and \q{Confirm passphrase} boxes both contain exactly the same
239passphrase, and will refuse to save the key otherwise.
240
241If you leave the passphrase fields blank, the key will be saved
242unencrypted. You should \e{not} do this without good reason; if you
243do, your private key file on disk will be all an attacker needs to
244gain access to any machine configured to accept that key. If you
245want to be able to log in without having to type a passphrase every
246time, you should consider using Pageant (\k{pageant}) so that your
247decrypted key is only held in memory rather than on disk.
248
249Under special circumstances you may genuinely \e{need} to use a key
250with no passphrase; for example, if you need to run an automated
251batch script that needs to make an SSH connection, you can't be
252there to type the passphrase. In this case we recommend you generate
253a special key for each specific batch script (or whatever) that
254needs one, and on the server side you should arrange that each key
255is \e{restricted} so that it can only be used for that specific
256purpose. The documentation for your SSH server should explain how to
257do this (it will probably vary between servers).
258
259Choosing a good passphrase is difficult. Just as you shouldn't use a
260dictionary word as a password because it's easy for an attacker to
8f1529bc 261run through a whole dictionary, you should not use a song lyric,
262quotation or other well-known sentence as a passphrase. DiceWare
eb92e68f 263(\W{http://www.diceware.com/}\cw{www.diceware.com}) recommends using
264at least five words each generated randomly by rolling five dice,
65befd9c 265which gives over 2^64 possible passphrases and is probably not a bad
eb92e68f 266scheme. If you want your passphrase to make grammatical sense, this
267cuts down the possibilities a lot and you should use a longer one as
0906628e 268a 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
276Once you have generated a key, set a comment field and set a
277passphrase, you are ready to save your private key to disk.
278
279Press the \q{Save private key} button. PuTTYgen will put up a dialog
280box asking you where to save the file. Select a directory, type in a
281file name, and press \q{Save}.
024f5783 282
8cee3b72 283This file is in PuTTY's native format (\c{*.PPK}); it is the one you
284will 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
2e85c969 292The SSH-2 protocol drafts specify a standard format for storing
0906628e 293public keys on disk. Some SSH servers (such as \cw{ssh.com}'s)
294require a public key in this format in order to accept
295authentication with the corresponding private key. (Others, such as
296OpenSSH, use a different format; see \k{puttygen-pastekey}.)
297
2e85c969 298To save your public key in the SSH-2 standard format, press the
0906628e 299\q{Save public key} button in PuTTYgen. PuTTYgen will put up a
300dialog box asking you where to save the file. Select a directory,
301type in a file name, and press \q{Save}.
302
303You will then probably want to copy the public key file to your SSH
304server machine. See \k{pubkey-gettingready} for general instructions
305on configuring public-key authentication once you have generated a
306key.
307
2e85c969 308If you use this option with an SSH-1 key, the file PuTTYgen saves
0906628e 309will contain exactly the same text that appears in the \q{Public key
2e85c969 310for pasting} box. This is the only existing standard for SSH-1
0906628e 311public keys.
312
313\S{puttygen-pastekey} \q{Public key for pasting into authorized_keys
314file}
315
316\cfg{winhelp-topic}{puttygen.pastekey}
317
2e85c969 318All SSH-1 servers require your public key to be given to it in a
0906628e 319one-line format before it will accept authentication with your
2e85c969 320private key. The OpenSSH server also requires this for SSH-2.
0906628e 321
322The \q{Public key for pasting into authorized_keys file} gives the
323public-key data in the correct one-line format. Typically you will
324want to select the entire contents of the box using the mouse, press
325Ctrl+C to copy it to the clipboard, and then paste the data into a
326PuTTY session which is already connected to the server.
327
328See \k{pubkey-gettingready} for general instructions on configuring
329public-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
335PuTTYgen allows you to load an existing private key file into
336memory. If you do this, you can then change the passphrase and
337comment before saving it again; you can also make extra copies of
338the public key.
339
340To load an existing key, press the \q{Load} button. PuTTYgen will
341put up a dialog box where you can browse around the file system and
342find your key file. Once you select the file, PuTTYgen will ask you
343for a passphrase (if necessary) and will then display the key
344details in the same way as if it had just generated the key.
345
b723338c 346If you use the Load command to load a foreign key format, it will
347work, but you will see a message box warning you that the key you
348have loaded is not a PuTTY native key. See \k{puttygen-conversions}
349for 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
2e85c969 355Most SSH-1 clients use a standard format for storing private keys on
9d07b2db 356disk. PuTTY uses this format as well; so if you have generated an
2e85c969 357SSH-1 private key using OpenSSH or \cw{ssh.com}'s client, you can use
9d07b2db 358it with PuTTY, and vice versa.
359
2e85c969 360However, SSH-2 private keys have no standard format. OpenSSH and
9d07b2db 361\cw{ssh.com} have different formats, and PuTTY's is different again.
362So a key generated with one client cannot immediately be used with
363another.
364
b723338c 365Using the \q{Import} command from the \q{Conversions} menu, PuTTYgen
2e85c969 366can load SSH-2 private keys in OpenSSH's format and \cw{ssh.com}'s
b723338c 367format. Once you have loaded one of these key types, you can then
8cee3b72 368save it back out as a PuTTY-format key (\c{*.PPK}) so that you can use
369it with the PuTTY suite. The passphrase will be unchanged by this
370process (unless you deliberately change it). You may want to change
2e85c969 371the key comment before you save the key, since OpenSSH's SSH-2 key
8cee3b72 372format contains no space for a comment and \cw{ssh.com}'s default
373comment format is long and verbose.
b723338c 374
375PuTTYgen 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
377from the \q{Conversions} menu. Exporting a key works exactly like
378saving it (see \k{puttygen-savepriv}) - you need to have typed your
379passphrase in beforehand, and you will be warned if you are about to
380save a key without a passphrase.
381
2e85c969 382Note that since only SSH-2 keys come in different formats, the export
383options are not available if you have generated an SSH-1 key.
9d07b2db 384
0906628e 385\H{pubkey-gettingready} Getting ready for public key authentication
024f5783 386
387Connect to your SSH server using PuTTY with the SSH protocol. When the
388connection succeeds you will be prompted for your user name and
5c72ca61 389password to login. Once logged in, you must configure the server to
390accept your public key for authentication:
391
2e85c969 392\b If your server is using the SSH-1 protocol, you should change
5c72ca61 393into the \c{.ssh} directory and open the file \c{authorized_keys}
f21d1674 394with your favourite editor. (You may have to create this file if
395this is the first key you have put in it). Then switch to the
396PuTTYgen window, select all of the text in the \q{Public key for
397pasting into authorized_keys file} box (see \k{puttygen-pastekey}),
398and copy it to the clipboard (\c{Ctrl+C}). Then, switch back to the
399PuTTY window and insert the data into the open file, making sure it
400ends up all on one line. Save the file.
5c72ca61 401
2e85c969 402\b If your server is OpenSSH and is using the SSH-2 protocol, you
0906628e 403should follow the same instructions, except that in earlier versions
404of OpenSSH 2 the file might be called \c{authorized_keys2}. (In
405modern versions the same \c{authorized_keys} file is used for both
2e85c969 406SSH-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 409a \e{public} key file from PuTTYgen (see \k{puttygen-savepub}), and
410copy that into the \c{.ssh2} directory on the server. Then you
411should go into that \c{.ssh2} directory, and edit (or create) a file
412called \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
414key file.
5c72ca61 415
416\b For other SSH server software, you should refer to the manual for
417that server.
418
0906628e 419You may also need to ensure that your home directory, your \c{.ssh}
420directory, and any other files involved (such as
421\c{authorized_keys}, \c{authorized_keys2} or \c{authorization}) are
ae0d43f1 422not group-writable or world-writable. You can typically do this by
423using a command such as
0906628e 424
ae0d43f1 425\c chmod go-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys
0906628e 426
427Your server should now be configured to accept authentication using
428your private key. Now you need to configure PuTTY to \e{attempt}
e2a197cf 429authentication using your private key. You can do this in any of
430three 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.
436See \k{using-cmdline-identity} for details.
437
0906628e 438\b Load the private key into Pageant (see \k{pageant}). In this case
439PuTTY will automatically try to use it for authentication if it can.