From a21056acd2e2263ca67f6dcd2105874b4d3117a8 Mon Sep 17 00:00:00 2001 From: Simon Tatham Date: Sun, 11 Apr 2021 15:06:44 +0100 Subject: [PATCH] Fill in holes in the documentation. I've filled in some text about prime generation methods and Ed448, which were all the things marked as 'review before release'. While I'm at it, also filled in a reasonable enough DSA key length recommendation, because the FIXME comment in that section was within sight of one of the places I was editing. FIPS 186-4 seemed to think that RSA and DSA had comparable relationships between the key length and practical security level, so I see no reason not to use the same recommendation for both key types. --- doc/config.but | 5 +++-- doc/man-puttygen.but | 32 ++++++++++++++++++++++++++++-- doc/pubkey.but | 47 +++++++++++++++++++++++++++++++++++--------- 3 files changed, 71 insertions(+), 13 deletions(-) diff --git a/doc/config.but b/doc/config.but index 9b6e43d0..4222b784 100644 --- a/doc/config.but +++ b/doc/config.but @@ -2422,8 +2422,9 @@ PuTTY currently supports the following host key types: \b \q{\i{Ed25519}}: \I{EdDSA}Edwards-curve DSA using a twisted Edwards curve with modulus \cw{2^255-19}. -\b \q{\i{Ed448}}: another \I{EdDSA}Edwards-curve DSA type. -\#{XXX-REVIEW-BEFORE-RELEASE: better description} +\b \q{\i{Ed448}}: another \I{EdDSA}Edwards-curve DSA type, using a +larger elliptic curve with a 448-bit instead of 255-bit modulus (so it +has a higher security level than Ed25519). \b \q{ECDSA}: \i{elliptic curve} \i{DSA} using one of the NIST-standardised elliptic curves. diff --git a/doc/man-puttygen.but b/doc/man-puttygen.but index 7593bc34..e4421ce2 100644 --- a/doc/man-puttygen.but +++ b/doc/man-puttygen.but @@ -78,8 +78,36 @@ OpenSSH format, or the standard SSH-1 format. are \c{probable} (the default), \c{proven}, and \c{proven-even}; the the later methods are slower. (Various synonyms for these method names are also accepted.) -\#{XXX-REVIEW-BEFORE-RELEASE: explain in more detail why you would -want to fiddle with this} + +\lcont{ + +The \q{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 \e{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. + +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. + +} + +\dd \cw{\-\-strong-rsa} + +\dd When generating an RSA key, make sure the prime factors of the key +modulus are \q{strong primes}. 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 \e{unless} you have a +local standard that recommends it. \dt \cw{\-q} diff --git a/doc/pubkey.but b/doc/pubkey.but index 8fda7f15..79bd8bed 100644 --- a/doc/pubkey.but +++ b/doc/pubkey.but @@ -130,9 +130,8 @@ considered secure, it's rare to need this option. The \q{Number of bits} input box allows you to choose the strength of the key PuTTYgen will generate. -\b For RSA, 2048 bits should currently be sufficient for most purposes. - -\#{FIXME: advice for DSA?} +\b For RSA and DSA, 2048 bits should currently be sufficient for most +purposes. \b For ECDSA, only 256, 384, and 521 bits are supported. (ECDSA offers equivalent security to RSA with smaller key sizes.) @@ -146,9 +145,18 @@ the same as 255.) \S{puttygen-primes} Selecting the \i{prime generation method} On the \q{Key} menu, you can also optionally change the method for -generating the prime numbers used in the generated key. This affects -the quality of the key, but not its compatibility. The default method -is usually fine. The available methods are: +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. + +If you don't care abut this, it's entirely sensible to leave it on the +default setting. + +The available methods are: \b Use \i{probable primes} (fast) @@ -156,9 +164,30 @@ is usually fine. The available methods are: \b Use proven primes with even distribution (slowest) -\#{XXX-REVIEW-BEFORE-RELEASE: really need more words here, about why -you'd fiddle with this, and particularly around why 'probable' is ever -considered fine} +The \q{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 \e{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. + +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 \q{Key} menu to use +\q{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 \e{unless} you have a local standard that recommends +it. \S{puttygen-generate} The \q{Generate} button