ui_puttygen » Revisions »
Differences
This shows you the differences between the selected revisions of the page.
| ui_puttygen 2015-09-22 | ui_puttygen 2024-07-19 (current) | ||
| Line 1: | Line 1: | ||
| ====== Using PuTTYgen ====== | ====== Using PuTTYgen ====== | ||
| - | PuTTYgen is a key generator. It generates pairs of [[public_key|public and private keys]] to be used with WinSCP. PuTTYgen generates RSA and DSA keys. | + | PuTTYgen is a key generator. It generates pairs of [[public_key|public and private keys]] to be used with WinSCP. PuTTYgen generates RSA, DSA, ECDSA, and EdDSA keys.((&puttydoccite)) |
| ===== Obtaining and Starting PuTTYgen ===== | ===== Obtaining and Starting PuTTYgen ===== | ||
| - | PuTTYgen is included in the [[installation|WinSCP installation package]]. You can also download it separately from the [[&download|WinSCP download page]]. | + | PuTTYgen is included in the [[ui_installer_selectcomponents|WinSCP installation package]]. You can also download it separately from the [[&downloads#putty_additional|WinSCP download page]]. |
| PuTTYgen originates from PuTTY and is also part of the PuTTY installation package. It does not matter if you use PuTTYgen from WinSCP or the PuTTY installation package, they are identical. | PuTTYgen originates from PuTTY and is also part of the PuTTY installation package. It does not matter if you use PuTTYgen from WinSCP or the PuTTY installation package, they are identical. | ||
| Line 9: | Line 9: | ||
| To start PuTTYgen, go to //Tools > PuTTYgen// on [[ui_login|Login dialog]]. | To start PuTTYgen, go to //Tools > PuTTYgen// on [[ui_login|Login dialog]]. | ||
| - | ===== PuTTYgen Window ===== | + | ===== [[window]] PuTTYgen Window ===== |
| &screenshotpict(puttygen) | &screenshotpict(puttygen) | ||
| - | When you run PuTTYgen you will see a window where you have two choices: //Generate//, to generate a new public/private key pair, or //Load// to load in an existing private key. | + | 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. |
| - | ===== Generating a New Key ===== | + | ===== [[generating]] Generating a New Key ===== |
| This is a general outline of the procedure for generating a new key pair. The following sections describe the process in more detail. | This is a general outline of the procedure for generating a new key pair. The following sections describe the process in more detail. | ||
| Line 23: | Line 23: | ||
| * Now you're ready to [[#saving_private|save the private key to disk]]; press the //Save private key// button. | * Now you're ready to [[#saving_private|save the private key to disk]]; press the //Save private key// button. | ||
| - | 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 //[[#authorized_keys|Public key for pasting into authorized_keys file]]// box, or by using the //[[#saving_public|Save public key]]// button. However, you don't need to do this immediately; if you want, you can [[#reloading|load the private key]] back into PuTTYgen later and the public key will be available for copying and pasting again. | + | 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 //[[#authorized_keys|Public key for pasting into OpenSSH authorized_keys file]]// box, or by using the //[[#saving_public|Save public key]]// button. However, you don't need to do this immediately; if you want, you can [[#reloading|load the private key]] back into PuTTYgen later and the public key will be available for copying and pasting again. |
| For more details refer to guide to [[guide_public_key|setting up public key authentication]]. | For more details refer to guide to [[guide_public_key|setting up public key authentication]]. | ||
| Line 29: | Line 29: | ||
| ===== [[type]] Selecting the Type of Key ===== | ===== [[type]] Selecting the Type of Key ===== | ||
| - | Before generating a key pair using PuTTYgen, you need to select which type of key you need. PuTTYgen currently supports three types of key: | + | Before generating a key pair using PuTTYgen, you need to select which type of key you need. |
| - | * An RSA key for use with the SSH-1 protocol. | + | The SSH protocol supports several different key types, although specific servers may not support all of them. PuTTYgen can generate: |
| - | * An RSA key for use with the SSH-2 protocol. | + | |
| - | * A DSA key for use with the SSH-2 protocol. | + | |
| - | The SSH-1 protocol only supports RSA keys; if you will be connecting using the SSH-1 protocol, you must select the first key type or your key will be completely useless. | + | * An //RSA// key. |
| + | * A //DSA// key. | ||
| + | * An //ECDSA// (elliptic curve %%DSA%%) key. | ||
| + | * An //EdDSA// key (Edwards-curve DSA, another elliptic curve algorithm). | ||
| - | The SSH-2 protocol supports more than one key type. The two types supported by WinSCP are RSA and DSA. | + | PuTTYgen can also generate an %%RSA%% key suitable for use with the deprecated %%SSH-1%% protocol (which only supports %%RSA%%). But SSH-1 is no longer supported by WinSCP. |
| - | + | ||
| - | The WinSCP developers strongly recommend you use RSA. DSA has an intrinsic weakness which makes it very easy to create a signature which contains enough information to give away the private key! This would allow an attacker to pretend to be you for any number of future sessions. WinSCP's implementation has taken very careful precautions to avoid this weakness, but we cannot be 100% certain we have managed it, and if you have the choice we strongly recommend using RSA keys instead. | + | |
| - | + | ||
| - | If you really need to connect to an SSH server which only supports DSA, then you probably have no choice but to use DSA. If you do use DSA, we recommend you do not use the same key to authenticate with more than one server. | + | |
| ===== [[size]] Selecting the Size (Strength) of the Key ===== | ===== [[size]] Selecting the Size (Strength) of the Key ===== | ||
| Line 47: | Line 44: | ||
| The //Number of bits// input box allows you to choose the strength of the key PuTTYgen will generate. | The //Number of bits// input box allows you to choose the strength of the key PuTTYgen will generate. | ||
| - | Currently 2048 bits should be sufficient for most purposes. | + | * For RSA and DSA, 2048 bits should currently be sufficient for most purposes. (Smaller keys of these types are no longer considered secure, and PuTTYgen will warn if you try to generate them.) |
| + | |||
| + | * For ECDSA, only 256, 384, and 521 bits are supported, corresponding to NIST-standardised elliptic curves. (Elliptic-curve keys do not need as many bits as RSA keys for equivalent security, so these numbers are smaller than the %%RSA%% recommendations.) | ||
| + | |||
| + | * For EdDSA, the only valid sizes are 255 bits (these keys are also known as Ed25519 and are commonly used) and 448 bits (Ed448, which is much less common at the time of writing). (256 is also accepted for backward compatibility, but the effect is the same as 255.) | ||
| + | |||
| + | ===== [[method]] Selecting the Prime Generation Method ===== | ||
| + | |||
| + | (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: | ||
| + | |||
| + | * //Use probable primes (fast)// | ||
| + | |||
| + | * //Use proven primes (slower)// | ||
| + | |||
| + | * //Use proven primes with even distribution (slowest)// | ||
| + | |||
| + | 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. | ||
| ===== [[generate]] The Generate Button ===== | ===== [[generate]] The Generate Button ===== | ||
| Line 61: | Line 88: | ||
| ===== [[fingerprint]] The Key Fingerprint Box ===== | ===== [[fingerprint]] The Key Fingerprint Box ===== | ||
| - | 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. | + | 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. | + | 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 [[ui_pageant#list|Pageant key list box]] and the Unix ''ssh-add'' utility, will list key fingerprints rather than the whole public key. |
| + | |||
| + | By default, PuTTYgen will display fingerprints in the SHA-256 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. | ||
| ===== [[comment]] Setting a Comment for Your Key ===== | ===== [[comment]] Setting a Comment for Your Key ===== | ||
| Line 86: | Line 115: | ||
| Do not forget your passphrase. There is no way to recover it. | Do not forget your passphrase. There is no way to recover it. | ||
| + | |||
| + | ===== [[certificate]] Adding a Certificate to Your Key ===== | ||
| + | |||
| + | 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 [[guide_public_key#configure_openssh|edit the ''authorized_keys'' file]] (in case of OpenSSH) 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 [[ui_login_authentication#certificate|//Certificate to use with the private key// option]] in WinSCP itself. It's up to you which you find more convenient.) | ||
| + | |||
| + | When the currently loaded key in PuTTYgen contains a certificate, the large [[#authorized_keys|//Public key for pasting// edit box]] 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. | ||
| ===== [[saving_private]] Saving Your Private Key to a Disk File ===== | ===== [[saving_private]] Saving Your Private Key to a Disk File ===== | ||
| Line 94: | Line 139: | ||
| This file is in PuTTY's native format (''*.PPK''); it is the one you will need to tell WinSCP to use for [[ui_login_authentication|authentication]]. | This file is in PuTTY's native format (''*.PPK''); it is the one you will need to tell WinSCP to use for [[ui_login_authentication|authentication]]. | ||
| + | |||
| + | (You can optionally [[#save_params|change some details]] of the PPK format for your saved key files. But the defaults should be fine for most purposes.) | ||
| + | |||
| + | If you have started PuTTYgen from //[[ui_login_authentication#private_key_tools|SSH > Authentication page]]// of Advanced Site Settings dialog, WinSCP automatically detects the saved key and will insert its path it into //[[ui_login_authentication#private_key|Private key file]]// box. | ||
| ===== [[saving_public]] Saving Your Public Key to a Disk File ===== | ===== [[saving_public]] Saving Your Public Key to a Disk File ===== | ||
| - | 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) | + | RFC 4716 specifies a standard format for storing SSH 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) |
| - | 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//. | + | To save your public key in the SSH 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. | You will then probably want to copy the public key file to your SSH server machine. | ||
| - | 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. | + | ===== [[authorized_keys]] Public Key for Pasting into OpenSSH authorized_keys File ===== |
| - | ===== [[authorized_keys]] Public Key for Pasting into authorized_keys File ===== | + | 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. |
| - | All SSH-1 servers require your public key to be given to it in a one-line format before it will accept authentication with your private key. The OpenSSH server also requires this for SSH-2. | + | The //Public key for pasting into OpenSSH authorized_keys file// gives the public-key data in the correct one-line format. |
| - | + | ||
| - | The //Public key for pasting into authorized_keys file// gives the public-key data in the correct one-line format. | + | |
| For more details refer to guide to [[guide_public_key|setting up public key authentication]]. | For more details refer to guide to [[guide_public_key|setting up public key authentication]]. | ||
| + | |||
| + | WinSCP can [[ui_login_authentication#private_key_tools|show you the public key]] too. | ||
| + | |||
| + | ===== [[save_params]] Parameters for Saving Key Files ===== | ||
| + | |||
| + | 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. | ||
| + | |||
| + | ==== PPK File Version ==== | ||
| + | |||
| + | 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 WinSCP or PuTTY, 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. | ||
| + | |||
| + | ==== Options Affecting Passphrase Hashing ==== | ||
| + | |||
| + | 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. | ||
| + | |||
| + | * //Key derivation function//: The variant of the Argon2 key derivation function to use. You might change this if you consider your exposure to side-channel attacks to be different to the norm. | ||
| + | |||
| + | * //Memory to use for passphrase hash//: The amount of memory needed to decrypt the key, in Kbyte. | ||
| + | |||
| + | * //Time to use for passphrase hash//: Controls how much time is required to attempt decrypting the key. You can either specify an approximate time in milliseconds (on this machine), or explicitly specify a number of hash passes (which is what the time is turned into during encryption). | ||
| + | |||
| + | * //Parallelism for passphrase hash//: Number of parallelisable threads that can be used to decrypt the key. The default, 1, forces the process to run single-threaded, even on machines with multiple cores. | ||
| ===== [[reloading]] Reloading a Private Key ===== | ===== [[reloading]] Reloading a Private Key ===== | ||
| Line 123: | Line 200: | ||
| ===== [[other_formats]] Dealing with Private Keys in Other Formats ===== | ===== [[other_formats]] Dealing with Private Keys in Other Formats ===== | ||
| - | Most SSH-1 clients use a standard format for storing private keys on disk. WinSCP 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 WinSCP, and vice versa. | + | SSH private keys have no standard format. OpenSSH and ssh.com have different formats, and WinSCP'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 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 WinSCP. 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_private|saving it]] -- 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)//. | ||
| + | |||
| + | You can also use WinSCP ''[[commandline#keygen|/keygen]]'' command-line switch to convert the private key from other formats. | ||
| + | |||
| + | ===== PuTTYgen Command-line Configuration ===== | ||
| + | |||
| + | 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.) | ||
| - | However, SSH-2 private keys have no standard format. OpenSSH and ssh.com have different formats, and WinSCP's is different again. So a key generated with one client cannot immediately be used with another. | + | //Note that WinSCP has ''[[commandline#keygen|/keygen]]'' command-line switch that can be used to convert the private keys automatically.// |
| - | 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 WinSCP. 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 OpenSSH's SSH-2 key format contains no space for a comment and ssh.com's default comment format is long and verbose. | + | The options supported on the PuTTYgen command line are: |
| - | 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_private|saving it]] - 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. | + | | ''-t <keytype>'' | [[#type|Type of key]] to generate. You can select ''rsa'', ''dsa'', ''ecdsa'', ''eddsa'', ''ed25519'' or ''ed448'' | |
| + | | ''-b <bits>'' | [[#size|Size of the key]] to generate, in bits. | | ||
| + | | ''%%--primes <method>%%'' | [[#method|Method for generating prime numbers]]. You can select ''probable'', ''proven'', and ''proven-even''. | | ||
| + | | ''%%--strong-rsa%%'' | When generating an RSA key, make sure the prime factors of the key modulus are [[#strong|strong primes]]. | | ||
| + | | ''%%--ppk-param%% <key>=<value>'' | Allows setting [[#save_params|details of the PPK save file format]]. \\ Aspects to change are specified as a series of ''%%<key>=<value>%%'' pairs separated by commas. The keys are: \\ ''version'' – The PPK format version: either ''3'' or ''2''. \\ ''kdf'' – The variant of Argon2 to use: ''argon2id'', ''argon2i'', and ''argon2d''. \\ ''memory'' – The amount of memory needed to decrypt the key, in Kbyte. \\ ''time'' – Specifies how much time is required to attempt decrypting the key, in milliseconds. \\ ''passes'' – Alternative to ''time'': specifies the number of hash passes required to attempt decrypting the key. \\ ''parallelism'' – Number of parallelisable threads that can be used to decrypt the key. | | ||
| + | | ''-E <fptype>'' | Algorithm to use when [[#fingerprint|displaying key fingerprints]]. You can select ''sha256'' or ''md5''. | | ||
| - | Note that since only SSH-2 keys come in different formats, the export options are not available if you have generated an SSH-1 key. ((&puttydoccite)) | ||