From 6472f7fc774e1c9255c1ed83f70ef7909858811d Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Fri, 21 Oct 2022 11:55:32 +0100 Subject: [PATCH] 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: