From 9dd9860cc84f82309de64c33e2813c6e9dc60749 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Thu, 22 Oct 2015 01:48:02 +0100 Subject: [PATCH] Update docs for Ed25519 and ChaCha20-Poly1305. --- doc/config.but | 2 ++ doc/man-pg.but | 12 +++++++++--- doc/pageant.but | 3 ++- doc/pubkey.but | 35 +++++++++++++++++++++++++++-------- 4 files changed, 40 insertions(+), 12 deletions(-) diff --git a/doc/config.but b/doc/config.but index 8ee0d445..82656cd2 100644 --- a/doc/config.but +++ b/doc/config.but @@ -2548,6 +2548,8 @@ use that. PuTTY currently supports the following algorithms: +\b \i{ChaCha20-Poly1305}, a combined cipher and \i{MAC} (SSH-2 only) + \b \i{AES} (Rijndael) - 256, 192, or 128-bit SDCTR or CBC (SSH-2 only) \b \i{Arcfour} (RC4) - 256 or 128-bit stream cipher (SSH-2 only) diff --git a/doc/man-pg.but b/doc/man-pg.but index 51173e22..6ee37c99 100644 --- a/doc/man-pg.but +++ b/doc/man-pg.but @@ -53,8 +53,8 @@ OpenSSH and ssh.com's implementation. \dt \cw{\-t} \e{keytype} \dd Specify a type of key to generate. The acceptable values here are -\c{rsa} and \c{dsa} (to generate SSH-2 keys), and \c{rsa1} (to -generate SSH-1 keys). +\c{rsa}, \c{dsa}, \c{ecdsa}, and \c{ed25519} (to generate SSH-2 keys), +and \c{rsa1} (to generate SSH-1 keys). \dt \cw{\-b} \e{bits} @@ -117,9 +117,15 @@ algorithms are believed compatible with OpenSSH. \dt \cw{private-openssh} -\dd Save an SSH-2 private key in OpenSSH's format. This option is not +\dd Save an SSH-2 private key in OpenSSH's format, using the oldest +format available to maximise backward compatibility. This option is not permitted for SSH-1 keys. +\dt \cw{private-openssh-new} + +\dd As \c{private-openssh}, except that it forces the use of OpenSSH's +newer format even for RSA, DSA, and ECDSA keys. + \dt \cw{private-sshcom} \dd Save an SSH-2 private key in ssh.com's format. This option is not diff --git a/doc/pageant.but b/doc/pageant.but index 7aecbc69..8e7c5a7a 100644 --- a/doc/pageant.but +++ b/doc/pageant.but @@ -72,7 +72,8 @@ For each key, the list box will tell you: \b The type of the key. Currently, this can be \c{ssh1} (an RSA key for use with the SSH-1 protocol), \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), or \c{ecdsa-sha2-*} (an ECDSA key for use with +the SSH-2 protocol), \c{ecdsa-sha2-*} (an ECDSA key for use with +the SSH-2 protocol), or \c{ssh-ed25519} (an Ed25519 key for use with the SSH-2 protocol). \b The size (in bits) of the key. diff --git a/doc/pubkey.but b/doc/pubkey.but index dc8beae2..e2620bb5 100644 --- 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 -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 @@ -109,7 +109,7 @@ server to accept it. \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. @@ -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{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 -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! @@ -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. -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.) +\b For Ed25519, the only valid size is 256 bits. + \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} -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 @@ -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. +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.