From 11950739256d323dc6daa932edd27fccd6370880 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Fri, 21 Oct 2022 11:52:49 +0100 Subject: [PATCH 1/6] Docs: add index alias for "ECDSA". --- doc/index.but | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/index.but b/doc/index.but index 28303ee2..bb760338 100644 --- a/doc/index.but +++ b/doc/index.but @@ -819,6 +819,9 @@ saved sessions from \IM{DSA} DSA \IM{DSA} Digital Signature Standard +\IM{ECDSA} ECDSA +\IM{ECDSA} elliptic-curve DSA + \IM{EdDSA} EdDSA \IM{EdDSA} Edwards-curve DSA From 617bf732bd3db05f2f72a3b29f5aea2127fd3c86 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Fri, 21 Oct 2022 12:51:50 +0100 Subject: [PATCH 2/6] Docs: PuTTYgen: fix gratuitous exclusion of PSFTP. --- doc/pubkey.but | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/pubkey.but b/doc/pubkey.but index 27c0ba60..750cc738 100644 --- a/doc/pubkey.but +++ b/doc/pubkey.but @@ -62,9 +62,9 @@ The key types supported by PuTTY are described in \k{puttygen-keytype}. \H{pubkey-puttygen} Using \i{PuTTYgen}, the PuTTY key generator PuTTYgen is a key generator. It \I{generating keys}generates pairs of -public and private keys to be used with PuTTY, PSCP, and Plink, as well -as the PuTTY authentication agent, Pageant (see \k{pageant}). PuTTYgen -generates RSA, DSA, ECDSA, and EdDSA keys. +public and private keys to be used with PuTTY, PSCP, PSFTP, and Plink, +as well as the PuTTY authentication agent, Pageant (see \k{pageant}). +PuTTYgen generates RSA, DSA, ECDSA, and EdDSA keys. When you run PuTTYgen you will see a window where you have two main choices: \q{Generate}, to generate a new public/private key pair, or From 2b5b7b5c45c5b3bbca36cee4d2c21281646eb79a Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Fri, 21 Oct 2022 11:51:34 +0100 Subject: [PATCH 3/6] Docs: note warning about <2048-bit RSA/DSA keys. --- doc/pubkey.but | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/pubkey.but b/doc/pubkey.but index 750cc738..c51f87bb 100644 --- a/doc/pubkey.but +++ b/doc/pubkey.but @@ -132,7 +132,8 @@ The \q{Number of bits} input box allows you to choose the strength of the key PuTTYgen will generate. \b For RSA and DSA, 2048 bits should currently be sufficient for most -purposes. +purposes. (Smaller keys of these types are no longer considered +secure, and PuTTYgen will warn if you try to generate them.) \b For ECDSA, only 256, 384, and 521 bits are supported. (ECDSA offers equivalent security to RSA with smaller key sizes.) From d42983088ae44534c5e6f51bc024f74fc0759a27 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Fri, 21 Oct 2022 13:01:05 +0100 Subject: [PATCH 4/6] Docs: prime generation defaults are usually fine. --- doc/pubkey.but | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/pubkey.but b/doc/pubkey.but index c51f87bb..b97f43de 100644 --- a/doc/pubkey.but +++ b/doc/pubkey.but @@ -146,6 +146,9 @@ the same as 255.) \S{puttygen-primes} Selecting the \i{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 \q{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 @@ -155,9 +158,6 @@ 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: \b Use \i{probable primes} (fast) From 5d5a6a8fd3900cd078d030a15ea96c4969def524 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Fri, 21 Oct 2022 11:53:27 +0100 Subject: [PATCH 5/6] Docs: MD5 is forced for SSH-1 key fingerprints. --- doc/pageant.but | 9 +++++---- doc/pubkey.but | 6 +++--- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/pageant.but b/doc/pageant.but index 206811f5..99a8145a 100644 --- a/doc/pageant.but +++ b/doc/pageant.but @@ -86,10 +86,11 @@ fingerprint shown by remote utilities such as \i\c{ssh-keygen} when applied to your \c{authorized_keys} file. \lcont{ -By default this is shown in the \q{SHA256} format. You can change to the -older \q{MD5} format (which looks like \c{aa:bb:cc:...}) with the -\q{Fingerprint type} drop-down, but bear in mind that this format is -less secure and should be avoided for comparison purposes where possible. +For SSH-2 keys, by default this is shown in the \q{SHA256} format. You +can change to the older \q{MD5} format (which looks like \c{aa:bb:cc:...}) +with the \q{Fingerprint type} drop-down, but bear in mind that this +format is less secure and should be avoided for comparison purposes +where possible. If some of the keys loaded into Pageant have certificates attached, then Pageant will default to showing the fingerprint of the underlying diff --git a/doc/pubkey.but b/doc/pubkey.but index b97f43de..f696c0db 100644 --- a/doc/pubkey.but +++ b/doc/pubkey.but @@ -240,9 +240,9 @@ a particular fingerprint. So some utilities, such as the Pageant key list box (see \k{pageant-mainwin-keylist}) and the Unix \c{ssh-add} utility, will list key fingerprints rather than the whole public key. -By default, PuTTYgen will display fingerprints in the \q{SHA256} -format. If you need to see the fingerprint in the older \q{MD5} format -(which looks like \c{aa:bb:cc:...}), you can choose +By default, PuTTYgen will display SSH-2 key fingerprints in the +\q{SHA256} format. If you need to see the fingerprint in the older +\q{MD5} format (which looks like \c{aa:bb:cc:...}), you can choose \q{Show fingerprint as MD5} from the \q{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. From 6472f7fc774e1c9255c1ed83f70ef7909858811d Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Fri, 21 Oct 2022 11:55:32 +0100 Subject: [PATCH 6/6] Docs: update Pageant key list description. GUI Pageant stopped using SSH identifiers for key types in fea08bb244, but the docs were still referring to them. As part of this, ensure that the term "NIST" is thoroughly cross-referenced and indexed, since it now appears so prominently in Pageant. (While I'm there, reword the "it's OK that elliptic-curve keys are smaller than RSA ones" note, as I kept tripping over the old wording.) --- doc/config.but | 2 +- doc/index.but | 3 +++ doc/pageant.but | 21 ++++++++++++--------- doc/pubkey.but | 6 ++++-- doc/pubkeyfmt.but | 2 +- 5 files changed, 21 insertions(+), 13 deletions(-) diff --git a/doc/config.but b/doc/config.but index 540d6a93..32973ed7 100644 --- a/doc/config.but +++ b/doc/config.but @@ -2546,7 +2546,7 @@ 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. +\i{NIST}-standardised elliptic curves. \b \q{DSA}: straightforward \i{DSA} using modular exponentiation. diff --git a/doc/index.but b/doc/index.but index bb760338..ac1a317d 100644 --- a/doc/index.but +++ b/doc/index.but @@ -822,6 +822,9 @@ saved sessions from \IM{ECDSA} ECDSA \IM{ECDSA} elliptic-curve DSA +\IM{NIST} NIST-standardised elliptic curves +\IM{NIST} elliptic curves, NIST-standardised + \IM{EdDSA} EdDSA \IM{EdDSA} Edwards-curve DSA diff --git a/doc/pageant.but b/doc/pageant.but index 99a8145a..33d910b6 100644 --- a/doc/pageant.but +++ b/doc/pageant.but @@ -64,21 +64,24 @@ The large list box in the Pageant main window lists the private keys that are currently loaded into Pageant. The list might look something like this: -\c ssh-ed25519 SHA256:TddlQk20DVs4LRcAsIfDN9pInKpY06D+h4kSHwWAj4w -\c ssh-rsa 2048 SHA256:8DFtyHm3kQihgy52nzX96qMcEVOq7/yJmmwQQhBWYFg +\c Ed25519 SHA256:TddlQk20DVs4LRcAsIfDN9pInKpY06D+h4kSHwWAj4w +\c RSA 2028 SHA256:8DFtyHm3kQihgy52nzX96qMcEVOq7/yJmmwQQhBWYFg For each key, the list box will tell you: \b The type of the key. Currently, this can be -\c{ssh-rsa} (an RSA key for use with the SSH-2 protocol), -\c{ssh-dss} (a DSA key for use with the SSH-2 protocol), -\c{ecdsa-sha2-*} (an ECDSA key for use with the SSH-2 protocol), -\c{ssh-ed25519} (an Ed25519 key for use with the SSH-2 protocol), -\c{ssh-ed448} (an Ed448 key for use with the SSH-2 protocol), -or \c{ssh1} (an RSA key for use with the old SSH-1 protocol). +\q{RSA} (an RSA key for use with the SSH-2 protocol), +\q{DSA} (a DSA key for use with the SSH-2 protocol), +\q{\i{NIST}} (an ECDSA key for use with the SSH-2 protocol), +\q{Ed25519} (an Ed25519 key for use with the SSH-2 protocol), +\q{Ed448} (an Ed448 key for use with the SSH-2 protocol), +or \q{SSH-1} (an RSA key for use with the old SSH-1 protocol). +(If the key has an associated certificate, this is shown here with a +\q{cert} suffix.) \b The size (in bits) of the key, for key types that come in different -sizes. +sizes. (For ECDSA \q{NIST} keys, this is indicated as \q{p256} or +\q{p384} or \q{p521}.) \b The \I{key fingerprint}fingerprint for the public key. This should be the same fingerprint given by PuTTYgen, and (hopefully) also the same diff --git a/doc/pubkey.but b/doc/pubkey.but index f696c0db..5ac59390 100644 --- a/doc/pubkey.but +++ b/doc/pubkey.but @@ -135,8 +135,10 @@ of the key PuTTYgen will generate. purposes. (Smaller keys of these types are no longer considered secure, and PuTTYgen will warn if you try to generate them.) -\b For ECDSA, only 256, 384, and 521 bits are supported. (ECDSA offers -equivalent security to RSA with smaller key sizes.) +\b For ECDSA, only 256, 384, and 521 bits are supported, corresponding +to \i{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.) \b For EdDSA, the only valid sizes are 255 bits (these keys are also known as \q{\i{Ed25519}} and are commonly used) and 448 bits diff --git a/doc/pubkeyfmt.but b/doc/pubkeyfmt.but index 51954c53..836ed527 100644 --- a/doc/pubkeyfmt.but +++ b/doc/pubkeyfmt.but @@ -241,7 +241,7 @@ of \e{y} in the group generated by \e{g} mod \e{p}. \S{ppk-privkey-ecdsa} NIST elliptic-curve keys -NIST elliptic-curve keys are stored using one of the following +\i{NIST} elliptic-curve keys are stored using one of the following \s{algorithm-name} values, each corresponding to a different elliptic curve and key size: