ui_puttygen » Revisions »
Differences
This shows you the differences between the selected revisions of the page.
| ui_puttygen 2021-12-06 | ui_puttygen 2024-05-09 (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, DSA, ECDSA, and EdDSA 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 ===== | ||
| 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) | ||
| Line 33: | Line 33: | ||
| The SSH protocol supports several different key types, although specific servers may not support all of them. PuTTYgen can generate: | The SSH protocol supports several different key types, although specific servers may not support all of them. PuTTYgen can generate: | ||
| - | * An RSA key. | + | * An //RSA// key. |
| - | * A DSA key. | + | * A //DSA// key. |
| - | * An ECDSA (elliptic curve %%DSA%%) key. | + | * An //ECDSA// (elliptic curve %%DSA%%) key. |
| - | * An EdDSA key (Edwards-curve DSA, another elliptic curve algorithm). | + | * An //EdDSA// key (Edwards-curve DSA, another elliptic curve algorithm). |
| 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. | 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. | ||
| Line 44: | 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. | ||
| - | * For RSA and DSA, 2048 bits should currently 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. (%%ECDSA%% offers equivalent security to %%RSA%% with smaller key sizes.)· | + | * 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.) | * 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.) | ||
| - | ===== Selecting the Prime Generation Method ===== | + | ===== [[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.) | 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 prime-generation method does not affect compatibility: a key generated with any of these methods will still work with all the same SSH servers. | ||
| - | |||
| - | If you don't care about this, it's entirely sensible to leave it on the default setting. | ||
| The available methods are: | The available methods are: | ||
| Line 69: | Line 69: | ||
| 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. | 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. | 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. | + | 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 113: | 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 144: | Line 162: | ||
| WinSCP can [[ui_login_authentication#private_key_tools|show you the public key]] too. | WinSCP can [[ui_login_authentication#private_key_tools|show you the public key]] too. | ||
| - | ===== [[save_params]] Parameters for Saving Key Piles ===== | + | ===== [[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. | 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. | ||
| Line 188: | Line 206: | ||
| 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. | 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. //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, you can choose //Export OpenSSH key (force new file format)//. | + | 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. | 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.) | ||
| + | |||
| + | //Note that WinSCP has ''[[commandline#keygen|/keygen]]'' command-line switch that can be used to convert the private keys automatically.// | ||
| + | |||
| + | The options supported on the PuTTYgen command line are: | ||
| + | |||
| + | | ''-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''. | | ||
| + | |||