From 5aacd0d98e310688a8e1143e3b4377a849027419 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Fri, 19 Apr 2019 15:44:36 +0100 Subject: [PATCH] Docs: talk about SSH-2 before SSH-1. Because SSH-1 is a very niche interest these days. Mostly this affects the public key documentation. Also, a couple of unrelated concessions to modernity. --- doc/errors.but | 16 +++++----- doc/pageant.but | 19 ++++++------ doc/pubkey.but | 78 ++++++++++++++++++++++++------------------------- 3 files changed, 56 insertions(+), 57 deletions(-) diff --git a/doc/errors.but b/doc/errors.but index f57ac3a0..a9c15c1a 100644 --- a/doc/errors.but +++ b/doc/errors.but @@ -153,16 +153,16 @@ If you see one of these messages, it often indicates that you've tried to load a key of an inappropriate type into PuTTY, Plink, PSCP, PSFTP, or Pageant. -You may have specified a key that's inappropriate for the connection -you're making. The SSH-1 and SSH-2 protocols require different private -key formats, and a SSH-1 key can't be used for a SSH-2 connection (or -vice versa). - -Alternatively, you may have tried to load an SSH-2 key in a \q{foreign} +You may have tried to load an SSH-2 key in a \q{foreign} format (OpenSSH or \cw{ssh.com}) directly into one of the PuTTY tools, in which case you need to import it into PuTTY's native format (\c{*.PPK}) using PuTTYgen \dash see \k{puttygen-conversions}. +Alternatively, you may have specified a key that's inappropriate for +the connection you're making. The SSH-2 and the old SSH-1 protocols +require different private key formats, and a SSH-1 key can't be used +for a SSH-2 connection (or vice versa). + \H{errors-refused} \q{Server refused our key}, \q{Server refused our public key}, \q{Key refused} @@ -212,8 +212,8 @@ you to an SSH server. This may be because PuTTY has TIS or keyboard-interactive authentication disabled, in which case see \k{config-ssh-tis} and \k{config-ssh-ki}. -\H{errors-crc} \q{Incorrect \i{CRC} received on packet} or \q{Incorrect -\i{MAC} received on packet} +\H{errors-crc} \q{Incorrect \i{MAC} received on packet} or +\q{Incorrect \i{CRC} received on packet} This error occurs when PuTTY decrypts an SSH packet and its checksum is not correct. This probably means something has gone wrong in the diff --git a/doc/pageant.but b/doc/pageant.but index aaa57aa8..df8a1513 100644 --- a/doc/pageant.but +++ b/doc/pageant.but @@ -65,12 +65,12 @@ something like this: 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), \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 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), +or \c{ssh1} (an RSA key for use with the old SSH-1 protocol). \b The size (in bits) of the key. @@ -167,9 +167,10 @@ Use \c{-restrict-putty-acl} to change this. (Again, see Agent forwarding is a mechanism that allows applications on your SSH server machine to talk to the agent on your client machine. -Note that at present, agent forwarding in SSH-2 is only available -when your SSH server is \i{OpenSSH}. The \i\cw{ssh.com} server uses a -different agent protocol, which PuTTY does not yet support. +Note that at present, whether agent forwarding in SSH-2 is available +depends on your server. Pageant's protocol is compatible with the +\i{OpenSSH} server, but the \i\cw{ssh.com} server uses a different +agent protocol, which PuTTY does not yet support. To enable agent forwarding, first start Pageant. Then set up a PuTTY SSH session in which \q{Allow agent forwarding} is enabled (see diff --git a/doc/pubkey.but b/doc/pubkey.but index 309f3f5e..f2da0981 100644 --- a/doc/pubkey.but +++ b/doc/pubkey.but @@ -66,7 +66,7 @@ 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 Ed25519 keys. -When you run PuTTYgen you will see a window where you have two +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 \q{Load} to load in an existing private key. @@ -105,12 +105,12 @@ server to accept it. \S{puttygen-keytype} Selecting the type of key Before generating a key pair using PuTTYgen, you need to select -which type of key you need. PuTTYgen currently supports these types -of key: +which type of key you need. -\b An \i{RSA} key for use with the SSH-1 protocol. +The current version of the SSH protocol, SSH-2, supports several +different key types. PuTTYgen can generate: -\b An RSA key for use with the SSH-2 protocol. +\b An \i{RSA} key for use with the SSH-2 protocol. \b A \i{DSA} key for use with the SSH-2 protocol. @@ -120,12 +120,10 @@ 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, ECDSA, and Ed25519. +PuTTYgen can also generate an RSA key suitable for use with the old +SSH-1 protocol (which only supports RSA); for this, you need to select +the \q{SSH-1 (RSA)} option. Since the SSH-1 protocol is no longer +considered secure, it's rare to need this option. \S{puttygen-strength} Selecting the size (strength) of the key @@ -282,9 +280,9 @@ public keys. \S{puttygen-pastekey} \q{Public key for pasting into \i{authorized_keys file}} -All SSH-1 servers require your public key to be given to it in a -one-line format before it will accept authentication with your -private key. The \i{OpenSSH} server also requires this for SSH-2. +The \i{OpenSSH} server, among others, requires your public key to be +given to it in a one-line format before it will accept authentication +with your private key. (SSH-1 servers also used this method.) The \q{Public key for pasting into authorized_keys file} gives the public-key data in the correct one-line format. Typically you will @@ -315,12 +313,7 @@ for information about importing foreign key formats. \S{puttygen-conversions} Dealing with private keys in other formats -Most SSH-1 clients use a standard format for storing private keys on -disk. PuTTY uses this format as well; so if you have generated an -SSH-1 private key using OpenSSH or \cw{ssh.com}'s client, you can use -it with PuTTY, and vice versa. - -However, SSH-2 private keys have no standard format. \I{OpenSSH private +SSH-2 private keys have no standard format. \I{OpenSSH private key format}OpenSSH and \I{ssh.com private key format}\cw{ssh.com} have different formats, and PuTTY's is different again. So a key generated with one client cannot immediately be used with @@ -332,8 +325,8 @@ menu, PuTTYgen can load SSH-2 private keys in OpenSSH's format and can then save it back out as a PuTTY-format key (\c{*.\i{PPK}}) so that you can use it with the PuTTY suite. The passphrase will be unchanged by this process (unless you deliberately change it). You may want to change -the key comment before you save the key, since OpenSSH's SSH-2 key -format contains no space for a comment and \cw{ssh.com}'s default +the key comment before you save the key, since some OpenSSH key +formats contained no space for a comment, and \cw{ssh.com}'s default comment format is long and verbose. PuTTYgen can also \i{export private keys} in OpenSSH format and in @@ -353,8 +346,12 @@ 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. +Most clients for the older SSH-1 protocol use a standard format for +storing private keys on disk. PuTTY uses this format as well; so if +you have generated an SSH-1 private key using OpenSSH or +\cw{ssh.com}'s client, you can use it with PuTTY, and vice versa. +Hence, the export options are not available if you have generated an +SSH-1 key. \H{pubkey-gettingready} Getting ready for public key authentication @@ -363,21 +360,21 @@ connection succeeds you will be prompted for your user name and password to login. Once logged in, you must configure the server to accept your public key for authentication: -\b If your server is using the SSH-1 protocol, you should change -into the \i\c{.ssh} directory and open the file \i\c{authorized_keys} -with your favourite editor. (You may have to create this file if -this is the first key you have put in it). Then switch to the -PuTTYgen window, select all of the text in the \q{Public key for -pasting into authorized_keys file} box (see \k{puttygen-pastekey}), -and copy it to the clipboard (\c{Ctrl+C}). Then, switch back to the -PuTTY window and insert the data into the open file, making sure it -ends up all on one line. Save the file. +\b If your server is \i{OpenSSH}, you should change into the +\i\c{.ssh} directory under your home directory, and open the file +\i\c{authorized_keys} with your favourite editor. (You may have to +create this file, if this is the first key you have put in it.) Then +switch to the PuTTYgen window, select all of the text in the \q{Public +key for pasting into authorized_keys file} box (see +\k{puttygen-pastekey}), and copy it to the clipboard (\c{Ctrl+C}). +Then, switch back to the PuTTY window and insert the data into the +open file, making sure it ends up all on one line. Save the file. -\b If your server is \i{OpenSSH} and is using the SSH-2 protocol, you -should follow the same instructions, except that in earlier versions -of OpenSSH 2 the file might be called \c{authorized_keys2}. (In -modern versions the same \c{authorized_keys} file is used for both -SSH-1 and SSH-2 keys.) +\lcont{ +(In very old versions of OpenSSH, SSH-2 keys had to be put in a +separate file called \c{authorized_keys2}. In all current versions, +the same \c{authorized_keys} file is used for both SSH-1 and SSH-2 keys.) +} \b If your server is \i\cw{ssh.com}'s product and is using SSH-2, you need to save a \e{public} key file from PuTTYgen (see @@ -393,8 +390,9 @@ that server. You may also need to ensure that your home directory, your \c{.ssh} directory, and any other files involved (such as \c{authorized_keys}, \c{authorized_keys2} or \c{authorization}) are -not group-writable or world-writable. You can typically do this by -using a command such as +not group-writable or world-writable; servers will typically ignore +the keys unless this is done. You can typically do this by using a +command such as \c chmod go-w $HOME $HOME/.ssh $HOME/.ssh/authorized_keys