Update docs for Ed25519 and ChaCha20-Poly1305.

[PuTTY.git] / doc / pubkey.but

diff --git a/doc/pubkey.but b/doc/pubkey.but
index dc8beae2bf8609d2364cb2a228eb4690cc1be2a1..e2620bb515a6edb592ffe1b7097a38649e3b9d6c 100644 (file)
--- a/doc/pubkey.but
+++ b/doc/pubkey.but
@@ -66,7 +66,7 @@ The key types supported by PuTTY are described in \k{puttygen-keytype}.
 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
 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, and ECDSA keys.
+generates RSA, DSA, ECDSA, and Ed25519 keys.

 
 When you run PuTTYgen you will see a window where you have two
 choices: \q{Generate}, to generate a new public/private key pair, or
 
 When you run PuTTYgen you will see a window where you have two
 choices: \q{Generate}, to generate a new public/private key pair, or


@@ -109,7 +109,7 @@ server to accept it.
 \cfg{winhelp-topic}{puttygen.keytype}
 
 Before generating a key pair using PuTTYgen, you need to select
 \cfg{winhelp-topic}{puttygen.keytype}
 
 Before generating a key pair using PuTTYgen, you need to select

-which type of key you need. PuTTYgen currently supports three types
+which type of key you need. PuTTYgen currently supports these types

 of key:
 
 \b An \i{RSA} key for use with the SSH-1 protocol.
 of key:
 
 \b An \i{RSA} key for use with the SSH-1 protocol.


@@ -121,14 +121,18 @@ of key:
 \b An \i{ECDSA} (\i{elliptic curve} DSA) key for use with the
 SSH-2 protocol.
 
 \b An \i{ECDSA} (\i{elliptic curve} DSA) key for use with the
 SSH-2 protocol.
 

+\b An \i{Ed25519} key (another elliptic curve algorithm) for use
+with the SSH-2 protocol.
+

 The SSH-1 protocol only supports RSA keys; if you will be connecting
 using the SSH-1 protocol, you must select the first key type or your
 key will be completely useless.
 
 The SSH-2 protocol supports more than one key type. The types
 The SSH-1 protocol only supports RSA keys; if you will be connecting
 using the SSH-1 protocol, you must select the first key type or your
 key will be completely useless.
 
 The SSH-2 protocol supports more than one key type. The types

-supported by PuTTY are RSA, DSA, and ECDSA.
+supported by PuTTY are RSA, DSA, ECDSA, and Ed25519.

 
 

-The PuTTY developers \e{strongly} recommend you use RSA. \#{FIXME: ECDSA!}
+The PuTTY developers \e{strongly} recommend you use RSA.
+\#{FIXME: ECDSA, Ed25519!}

 \I{security risk}\i{DSA} has an intrinsic weakness which makes it very
 easy to create a signature which contains enough information to give
 away the \e{private} key!
 \I{security risk}\i{DSA} has an intrinsic weakness which makes it very
 easy to create a signature which contains enough information to give
 away the \e{private} key!


@@ -150,11 +154,15 @@ more than one server.
 The \q{Number of bits} input box allows you to choose the strength
 of the key PuTTYgen will generate.
 
 The \q{Number of bits} input box allows you to choose the strength
 of the key PuTTYgen will generate.
 

-For RSA, 2048 bits should currently be sufficient for most purposes.
-\#{FIXME: DSA}
-For ECDSA, only 256, 384, and 521 bits are supported. (ECDSA offers
+\b For RSA, 2048 bits should currently be sufficient for most purposes.
+
+\#{FIXME: advice for DSA?}
+
+\b For ECDSA, only 256, 384, and 521 bits are supported. (ECDSA offers

 equivalent security to RSA with smaller key sizes.)
 
 equivalent security to RSA with smaller key sizes.)
 

+\b For Ed25519, the only valid size is 256 bits.
+

 \S{puttygen-generate} The \q{Generate} button
 
 \cfg{winhelp-topic}{puttygen.generate}
 \S{puttygen-generate} The \q{Generate} button
 
 \cfg{winhelp-topic}{puttygen.generate}


@@ -189,7 +197,8 @@ appear in the window to indicate this.
 
 The \q{Key fingerprint} box shows you a fingerprint value for the
 generated key. This is derived cryptographically from the \e{public}
 
 The \q{Key fingerprint} box shows you a fingerprint value for the
 generated key. This is derived cryptographically from the \e{public}

-key value, so it doesn't need to be kept secret.
+key value, so it doesn't need to be kept secret; it is supposed to
+be more manageable for human beings than the public key itself.

 
 The fingerprint value is intended to be cryptographically secure, in
 the sense that it is computationally infeasible for someone to
 
 The fingerprint value is intended to be cryptographically secure, in
 the sense that it is computationally infeasible for someone to


@@ -374,6 +383,16 @@ saving it (see \k{puttygen-savepriv}) - 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.
 
 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. \q{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 \q{Export OpenSSH key (force new file
+format}.
+

 Note that since only SSH-2 keys come in different formats, the export
 options are not available if you have generated an SSH-1 key.
 
 Note that since only SSH-2 keys come in different formats, the export
 options are not available if you have generated an SSH-1 key.