Previous | Contents | Index | Next
Public key authentication is an alternative means of identifying yourself to a login server, instead of typing a password. It is more secure and more flexible, but more difficult to set up.
In conventional password authentication, you prove you are who you claim to be by proving that you know the correct password. The only way to prove you know the password is to tell the server what you think the password is. This means that if the server has been hacked, or spoofed (see section 2.2), an attacker can learn your password.
Public key authentication solves this problem. You generate a key pair, consisting of a public key (which everybody is allowed to know) and a private key (which you keep secret and do not give to anybody). The private key is able to generate signatures. A signature created using your private key cannot be forged by anybody who does not have that key; but anybody who has your public key can verify that a particular signature is genuine.
So you generate a key pair on your own computer, and you copy the public key to the server. Then, when the server asks you to prove who you are, PuTTY can generate a signature using your private key. The server can verify that signature (since it has your public key) and allow you to log in. Now if the server is hacked or spoofed, the attacker does not gain your private key or password; they only gain one signature. And signatures cannot be re-used, so they have gained nothing.
There is a problem with this: if your private key is stored unprotected on your own computer, then anybody who gains access to that will be able to generate signatures as if they were you. So they will be able to log in to your server under your account. For this reason, your private key is usually encrypted when it is stored on your local machine, using a passphrase of your choice. In order to generate a signature, PuTTY must decrypt the key, so you have to type your passphrase.
This can make public-key authentication less convenient than password authentication: every time you log in to the server, instead of typing a short password, you have to type a longer passphrase. One solution to this is to use an authentication agent, a separate program which holds decrypted private keys and generates signatures on request. PuTTY's authentication agent is called Pageant. When you begin a Windows session, you start Pageant and load your private key into it (typing your passphrase once). For the rest of your session, you can start PuTTY any number of times and Pageant will automatically generate signatures without you having to do anything. When you close your Windows session, Pageant shuts down, without ever having stored your decrypted private key on disk. Many people feel this is a good compromise between security and convenience. See chapter 9 for further details.
There is more than one public-key algorithm available. The most common are RSA and ECDSA, but others exist, notably DSA (otherwise known as DSS), the USA's federal Digital Signature Standard. The key types supported by PuTTY are described in section 8.2.2.
PuTTYgen is a key generator. It generates pairs of public and private keys to be used with PuTTY, PSCP, PSFTP, and Plink, as well as the PuTTY authentication agent, Pageant (see chapter 9). PuTTYgen generates RSA, DSA, ECDSA, and EdDSA keys.
When you run PuTTYgen you will see a window where you have two main choices: ‘Generate’, to generate a new public/private key pair, or ‘Load’ to load in an existing private key.
This is a general outline of the procedure for generating a new key pair. The following sections describe the process in more detail.
Your key pair is now ready for use. You may also want to copy the public key to your server, either by copying it out of the ‘Public key for pasting into OpenSSH authorized_keys file’ box (see section 8.2.12), or by using the ‘Save public key’ button (section 8.2.11). However, you don't need to do this immediately; if you want, you can load the private key back into PuTTYgen later (see section 8.2.14) and the public key will be available for copying and pasting again.
Section 8.3 describes the typical process of configuring PuTTY to attempt public-key authentication, and configuring your SSH server to accept it.
Before generating a key pair using PuTTYgen, you need to select which type of key you need.
The current version of the SSH protocol, SSH-2, supports several different key types, although specific servers may not support all of them. PuTTYgen can generate:
PuTTYgen can also generate an RSA key suitable for use with the old SSH-1 protocol (which only supports RSA); for this, you need to select the ‘SSH-1 (RSA)’ option. Since the SSH-1 protocol is no longer considered secure, it's rare to need this option.
The ‘Number of bits’ input box allows you to choose the strength of the key PuTTYgen will generate.
(This is entirely optional. Unless you know better, it's entirely sensible to skip this and use the default settings.)
On the ‘Key’ menu, you can also optionally change the method for generating the prime numbers used in the generated key. This is used for RSA and DSA keys only. (The other key types don't require generating prime numbers at all.)
The prime-generation method does not affect compatibility: a key generated with any of these methods will still work with all the same SSH servers.
The available methods are:
The ‘probable primes’ method sounds unsafe, but it's the most commonly used prime-generation strategy. There is in theory a possibility that it might accidentally generate a number that isn't prime, but the software does enough checking to make that probability vanishingly small (less than 1 in 2^80, or 1 in 10^24). So, in practice, nobody worries about it very much.
The other methods cause PuTTYgen to use numbers that it is sure are prime, because it generates the output number together with a proof of its primality. This takes more effort, but it eliminates that theoretical risk in the probabilistic method.
There in one way in which PuTTYgen's ‘proven primes’ method is not strictly better than its ‘probable primes’ method. If you use PuTTYgen to generate an RSA key on a computer that is potentially susceptible to timing- or cache-based side-channel attacks, such as a shared computer, the ‘probable primes’ method is designed to resist such attacks, whereas the ‘proven primes’ methods are not. (This is only a concern for RSA keys; for other key types, primes are either not secret or not involved.)
You might choose to switch from probable to proven primes if you have a local security standard that demands it, or if you don't trust the probabilistic argument for the safety of the usual method.
For RSA keys, there's also an option on the ‘Key’ menu to use ‘strong’ primes as the prime factors of the public key. A ‘strong’ prime is a prime number chosen to have a particular structure that makes certain factoring algorithms more difficult to apply, so some security standards recommend their use. However, the most modern factoring algorithms are unaffected, so this option is probably not worth turning on unless you have a local standard that recommends it.
Once you have chosen the type of key you want, and the strength of the key, press the ‘Generate’ button and PuTTYgen will begin the process of actually generating the key.
First, a progress bar will appear and PuTTYgen will ask you to move the mouse around to generate randomness. Wave the mouse in circles over the blank area in the PuTTYgen window, and the progress bar will gradually fill up as PuTTYgen collects enough randomness. You don't need to wave the mouse in particularly imaginative patterns (although it can't hurt); PuTTYgen will collect enough randomness just from the fine detail of exactly how far the mouse has moved each time Windows samples its position.
When the progress bar reaches the end, PuTTYgen will begin creating the key. The progress bar will reset to the start, and gradually move up again to track the progress of the key generation. It will not move evenly, and may occasionally slow down to a stop; this is unfortunately unavoidable, because key generation is a random process and it is impossible to reliably predict how long it will take.
When the key generation is complete, a new set of controls will appear in the window to indicate this.
The ‘Key fingerprint’ box shows you a fingerprint value for the generated key. This is derived cryptographically from the public key value, so it doesn't need to be kept secret; it is supposed to be more manageable for human beings than the public key itself.
The fingerprint value is intended to be cryptographically secure, in the sense that it is computationally infeasible for someone to invent a second key with the same fingerprint, or to find a key with a particular fingerprint. So some utilities, such as the Pageant key list box (see section 9.2.1) and the Unix ssh-add utility, will list key fingerprints rather than the whole public key.
By default, PuTTYgen will display SSH-2 key fingerprints in the ‘SHA256’ format. If you need to see the fingerprint in the older ‘MD5’ format (which looks like aa:bb:cc:...), you can choose ‘Show fingerprint as MD5’ from the ‘Key’ menu, but bear in mind that this is less cryptographically secure; it may be feasible for an attacker to create a key with the same fingerprint as yours.
If you have more than one key and use them for different purposes, you don't need to memorise the key fingerprints in order to tell them apart. PuTTYgen allows you to enter a comment for your key, which will be displayed whenever PuTTY or Pageant asks you for the passphrase.
The default comment format, if you don't specify one, contains the key type and the date of generation, such as rsa-key-20011212. Another commonly used approach is to use your name and the name of the computer the key will be used on, such as simon@simons-pc.
To alter the key comment, just type your comment text into the ‘Key comment’ box before saving the private key. If you want to change the comment later, you can load the private key back into PuTTYgen, change the comment, and save it again.
The ‘Key passphrase’ and ‘Confirm passphrase’ boxes allow you to choose a passphrase for your key. The passphrase will be used to encrypt the key on disk, so you will not be able to use the key without first entering the passphrase.
When you save the key, PuTTYgen will check that the ‘Key passphrase’ and ‘Confirm passphrase’ boxes both contain exactly the same passphrase, and will refuse to save the key otherwise.
If you leave the passphrase fields blank, the key will be saved unencrypted. You should not do this without good reason; if you do, your private key file on disk will be all an attacker needs to gain access to any machine configured to accept that key. If you want to be able to log in without having to type a passphrase every time, you should consider using Pageant (chapter 9) so that your decrypted key is only held in memory rather than on disk.
Under special circumstances you may genuinely need to use a key with no passphrase; for example, if you need to run an automated batch script that needs to make an SSH connection, you can't be there to type the passphrase. In this case we recommend you generate a special key for each specific batch script (or whatever) that needs one, and on the server side you should arrange that each key is restricted so that it can only be used for that specific purpose. The documentation for your SSH server should explain how to do this (it will probably vary between servers).
Choosing a good passphrase is difficult. Just as you shouldn't use a dictionary word as a password because it's easy for an attacker to run through a whole dictionary, you should not use a song lyric, quotation or other well-known sentence as a passphrase. DiceWare (www.diceware.com) recommends using at least five words each generated randomly by rolling five dice, which gives over 2^64 possible passphrases and is probably not a bad scheme. If you want your passphrase to make grammatical sense, this cuts down the possibilities a lot and you should use a longer one as a result.
Do not forget your passphrase. There is no way to recover it.
In some environments, user authentication keys can be signed in turn by a ‘certifying authority’ (‘CA’ for short), and user accounts on an SSH server can be configured to automatically trust any key that's certified by the right signature.
This can be a convenient setup if you have a very large number of servers. When you change your key pair, you might otherwise have to edit the authorized_keys file on every server individually, to make them all accept the new key. But if instead you configure all those servers once to accept keys signed as yours by a CA, then when you change your public key, all you have to do is to get the new key certified by the same CA as before, and then all your servers will automatically accept it without needing individual reconfiguration.
To get your key signed by a CA, you'll probably send the CA the new public key (not the private half), and get back a modified version of the public key with the certificate included.
If you want to incorporate the certificate into your PPK file for convenience, you can use the ‘Add certificate to key’ menu option in PuTTYgen's ‘Key’ menu. This will give you a single file containing your private key and the certificate, which is everything you need to authenticate to a server prepared to accept that certificate.
To remove the certificate again and restore the uncertified PPK file, there's also a ‘Remove certificate from key’ option.
(However, you don't have to incorporate the certificate into your PPK file. You can equally well use it separately, via the ‘Certificate to use with the private key’ option in PuTTY itself. See section 4.22.2. It's up to you which you find more convenient.)
When the currently loaded key in PuTTYgen contains a certificate, the large ‘Public key for pasting’ edit box (see section 8.2.12) is replaced by a button that brings up an information box telling you about the certificate, such as who it certifies your key as belonging to, when it expires (if ever), and the fingerprint of the CA key that signed it in turn.
Once you have generated a key, set a comment field and set a passphrase, you are ready to save your private key to disk.
Press the ‘Save private key’ button. PuTTYgen will put up a dialog box asking you where to save the file. Select a directory, type in a file name, and press ‘Save’.
This file is in PuTTY's native format (*.PPK); it is the one you will need to tell PuTTY to use for authentication (see section 4.22.1) or tell Pageant to load (see section 9.2.2).
(You can optionally change some details of the PPK format for your saved key files; see section 8.2.13. But the defaults should be fine for most purposes.)
RFC 4716 specifies a standard format for storing SSH-2 public keys on disk. Some SSH servers (such as ssh.com's) require a public key in this format in order to accept authentication with the corresponding private key. (Others, such as OpenSSH, use a different format; see section 8.2.12.)
To save your public key in the SSH-2 standard format, press the ‘Save public key’ button in PuTTYgen. PuTTYgen will put up a dialog box asking you where to save the file. Select a directory, type in a file name, and press ‘Save’.
You will then probably want to copy the public key file to your SSH server machine. See section 8.3 for general instructions on configuring public-key authentication once you have generated a key.
If you use this option with an SSH-1 key, the file PuTTYgen saves will contain exactly the same text that appears in the ‘Public key for pasting’ box. This is the only existing standard for SSH-1 public keys.
The OpenSSH server, among others, requires your public key to be given to it in a one-line format before it will accept authentication with your private key. (SSH-1 servers also used this method.)
The ‘Public key for pasting into OpenSSH authorized_keys file’ gives the public-key data in the correct one-line format. Typically you will want to select the entire contents of the box using the mouse, press Ctrl+C to copy it to the clipboard, and then paste the data into a PuTTY session which is already connected to the server.
See section 8.3 for general instructions on configuring public-key authentication once you have generated a key.
Selecting ‘Parameters for saving key files...’ from the ‘Key’ menu lets you adjust some aspects of PPK-format private key files stored on disk. None of these options affect compatibility with SSH servers.
In most cases, it's entirely sensible to leave all of these at their default settings.
This defaults to version 3, which is fine for most uses.
You might need to select PPK version 2 if you need your private key file to be loadable in older versions of PuTTY (0.74 and older), or in other tools which do not yet support the version 3 format (which was introduced in 2021).
The version 2 format is less resistant to brute-force decryption, and doesn't support any of the following options to control that.
All of the following options only affect keys saved with passphrases. They control how much work is required to decrypt the key (which happens every time you type its passphrase). This allows you to trade off the cost of legitimate use of the key against the resistance of the encrypted key to password-guessing attacks.
These options only affect PPK version 3.
PuTTYgen allows you to load an existing private key file into memory. If you do this, you can then change the passphrase and comment before saving it again; you can also make extra copies of the public key.
To load an existing key, press the ‘Load’ button. PuTTYgen will put up a dialog box where you can browse around the file system and find your key file. Once you select the file, PuTTYgen will ask you for a passphrase (if necessary) and will then display the key details in the same way as if it had just generated the key.
If you use the Load command to load a foreign key format, it will work, but you will see a message box warning you that the key you have loaded is not a PuTTY native key. See section 8.2.15 for information about importing foreign key formats.
SSH-2 private keys have no standard format. OpenSSH and ssh.com have different formats, and PuTTY's is different again. So a key generated with one client cannot immediately be used with another.
Using the ‘Import’ command from the ‘Conversions’ menu, PuTTYgen can load SSH-2 private keys in OpenSSH's format and ssh.com's format. Once you have loaded one of these key types, you can then save it back out as a PuTTY-format key (*.PPK) so that you can use it with the PuTTY suite. The passphrase will be unchanged by this process (unless you deliberately change it). You may want to change the key comment before you save the key, since some OpenSSH key formats contained no space for a comment, and ssh.com's default comment format is long and verbose.
PuTTYgen can also export private keys in OpenSSH format and in ssh.com format. To do so, select one of the ‘Export’ options from the ‘Conversions’ menu. Exporting a key works exactly like saving it (see section 8.2.10) - you need to have typed your passphrase in beforehand, and you will be warned if you are about to save a key without a passphrase.
For OpenSSH there are two options. Modern OpenSSH actually has two formats it uses for storing private keys: an older (‘PEM-style’) format, and a newer ‘native’ format with better resistance to passphrase guessing and support for comments. ‘Export OpenSSH key’ will automatically choose the oldest format supported for the key type, for maximum backward compatibility with older versions of OpenSSH; for newer key types like Ed25519, it will use the newer format as that is the only legal option. If you have some specific reason for wanting to use OpenSSH's newer format even for RSA, DSA, or ECDSA keys – for instance, you know your file will only be used by OpenSSH 6.5 or newer (released in 2014), and want the extra security – you can choose ‘Export OpenSSH key (force new file format)’.
Most clients for the older SSH-1 protocol use a standard format for storing private keys on disk. PuTTY uses this format as well; so if you have generated an SSH-1 private key using OpenSSH or ssh.com's client, you can use it with PuTTY, and vice versa. Hence, the export options are not available if you have generated an SSH-1 key.
PuTTYgen supports a set of command-line options to configure many of the same settings you can select in the GUI. This allows you to start it up with your own preferences ready-selected, which might be useful if you generate a lot of keys. (For example, you could make a Windows shortcut that runs PuTTYgen with some command line options, or a batch file or Powershell script that you could distribute to a whole organisation containing your local standards.)
The options supported on the command line are:
-t keytype
rsa, dsa, ecdsa, eddsa, ed25519, ed448, or rsa1. See section 8.2.2.
-b bits
--primes method
probable, proven, and proven-even. See section 8.2.4.
--strong-rsa
--ppk-param key=value,...
Aspects to change are specified as a series of key=value pairs separated by commas. The keys are:
version
3 or 2.
kdf
argon2id, argon2i, and argon2d.
memory
time
passes
time: specifies the number of hash passes required to attempt decrypting the key.
parallelism
-E fptype
sha256 or md5. See section 8.2.6.
Connect to your SSH server using PuTTY with the SSH protocol. When the connection succeeds you will be prompted for your user name and password to login. Once logged in, you must configure the server to accept your public key for authentication:
.ssh directory under your home directory, and open the file authorized_keys with your favourite editor. (You may have to create this file, if this is the first key you have put in it.) Then switch to the PuTTYgen window, select all of the text in the ‘Public key for pasting into OpenSSH authorized_keys file’ box (see section 8.2.12), and copy it to the clipboard (Ctrl+C). Then, switch back to the PuTTY window and insert the data into the open file, making sure it ends up all on one line. Save the file.
(In very old versions of OpenSSH, SSH-2 keys had to be put in a separate file called authorized_keys2. In all current versions, the same authorized_keys file is used for both SSH-1 and SSH-2 keys.)
ssh.com's product and is using SSH-2, you need to save a public key file from PuTTYgen (see section 8.2.11), and copy that into the .ssh2 directory on the server. Then you should go into that .ssh2 directory, and edit (or create) a file called authorization. In this file you should put a line like Key mykey.pub, with mykey.pub replaced by the name of your key file.
You may also need to ensure that your home directory, your .ssh directory, and any other files involved (such as authorized_keys, authorized_keys2 or authorization) are not group-writable or world-writable; servers will typically ignore the keys unless this is done. You can typically do this by using a command such as
chmod go-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys
Your server should now be configured to accept authentication using your private key. Now you need to configure PuTTY to attempt authentication using your private key. You can do this in any of three ways:
-i option. See section 3.11.3.18 for details.
If you want to provide feedback on this manual or on the PuTTY tools themselves, see the Feedback page.
[PuTTY development snapshot 2024-11-19.01c404c]