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