Document multiple fingerprint formats.

doc/config.but

@@ -2591,8 +2591,8 @@ NIST-standardised elliptic curves.
 \b \q{RSA}: the ordinary \i{RSA} algorithm.
 
 If PuTTY already has one or more host keys stored for the server,
-it will prefer to use one of those, even if the server has a key
+it will by default prefer to use one of those, even if the server has
-type that is higher in the preference order. You can add such a
+a key type that is higher in the preference order. You can add such a
 key to PuTTY's cache from within an existing session using the
 \q{Special Commands} menu; see \k{using-specials}.
 
@@ -2657,9 +2657,13 @@ You can remove keys again with the \q{Remove} button.
 
 The text describing a host key can be in one of the following formats:
 
-\b An MD5-based host key fingerprint of the form displayed in PuTTY's
+\b An \I{SHA256 fingerprint}SHA-256-based host key fingerprint of the
-Event Log and host key dialog boxes, i.e. sixteen 2-digit hex numbers
+form displayed in PuTTY's Event Log and host key dialog boxes,
-separated by colons.
+i.e. \cq{SHA256:} followed by 43 case-sensitive characters.
+
+\b An \I{MD5 fingerprint}MD5-based host key fingerprint, i.e. sixteen
+2-digit hex numbers separated by colons, optionally preceded by the
+prefix \cq{MD5:}. (The case of the characters does not matter.)
 
 \b A base64-encoded blob describing an SSH-2 public key in
 OpenSSH's one-line public key format. How you acquire a public key in

doc/gs.but

@@ -50,17 +50,15 @@ section.
 If you are using SSH to connect to a server for the first time, you
 will probably see a message looking something like this:
 
-\c The server's host key is not cached in the registry. You
+\c The server's host key is not cached in the registry. You have no
-\c have no guarantee that the server is the computer you
+\c guarantee that the server is the computer you think it is.
-\c think it is.
+\c The server's ssh-ed25519 key fingerprint is:
-\c The server's rsa2 key fingerprint is:
+\c  ssh-ed25519 255 SHA256:TddlQk20DVs4LRcAsIfDN9pInKpY06D+h4kSHwWAj4w
-\c ssh-rsa 1024 7b:e5:6f:a7:f4:f9:81:62:5c:e3:1f:bf:8b:57:6c:5a
+\c If you trust this host, press "Accept" to add the key to PuTTY's
-\c If you trust this host, hit Yes to add the key to
+\c cache and carry on connecting.
-\c PuTTY's cache and carry on connecting.
+\c If you want to carry on connecting just once, without adding the key
-\c If you want to carry on connecting just once, without
+\c to the cache, press "Connect Once".
-\c adding the key to the cache, hit No.
+\c If you do not trust this host, press "Cancel" to abandon the connection.
-\c If you do not trust this host, hit Cancel to abandon the
-\c connection.
 
 This is a feature of the SSH protocol. It is designed to protect you
 against a network attack known as \i\e{spoofing}: secretly
@@ -83,7 +81,8 @@ server, it checks that the host key presented by the server is the
 same host key as it was the last time you connected. If it is not,
 you will see a warning, and you will have the chance to abandon your
 connection before you type any private information (such as a
-password) into it.
+password) into it. (See \k{errors-hostkey-wrong} for what that looks
+like.)
 
 However, when you connect to a server you have not connected to
 before, PuTTY has no way of telling whether the host key is the
@@ -97,10 +96,26 @@ network users are on the same side and spoofing attacks are
 unlikely, so you might choose to trust the key without checking it.
 If you are connecting across a hostile network (such as the
 Internet), you should check with your system administrator, perhaps
-by telephone or in person. (Many servers have more than one
+by telephone or in person. (When verifying the fingerprint, be careful
-host key. If the system administrator sends you more than one
+with letters and numbers that can be confused with each other:
-\I{host key fingerprint}fingerprint, you should make sure the one
+\c{0}/\c{O}, \c{1}/\c{I}/\c{l}, and so on.)
-PuTTY shows you is on the list, but it doesn't matter which one it is.)
+
+Many servers have more than one host key. If the system administrator
+sends you more than one \I{host key fingerprint}fingerprint, you should
+make sure the one PuTTY shows you is on the list, but it doesn't matter
+which one it is.
+
+If you don't have any fingerprints that look like the example
+(\I{SHA256 fingerprint}\c{SHA256:} followed by a long string of
+characters), but instead have pairs of characters separated by colons
+like \c{a4:db:96:a7:...}, try pressing the \q{More info...} button and
+see if you have a fingerprint matching the \q{\i{MD5 fingerprint}}
+there. This is an older and less secure way to summarise the same
+underlying host key; it's possible for an attacker to create their
+own host key with the same fingerprint; so you should avoid relying on
+this fingerprint format unless you have no choice. The
+\q{More info...} dialog box also shows the full host public key, in
+case that is easier to compare than a fingerprint.
 
 See \k{config-ssh-hostkey} for advanced options for managing host keys.
 

doc/index.but

@@ -20,6 +20,12 @@
 \IM{host key fingerprint} host key fingerprint (SSH)
 \IM{host key fingerprint} SSH host key fingerprint
 
+\IM{MD5 fingerprint} MD5 fingerprint, of SSH host key
+\IM{MD5 fingerprint} fingerprint, MD5, of SSH host key
+
+\IM{SHA256 fingerprint} SHA-256 fingerprint, of SSH host key
+\IM{SHA256 fingerprint} fingerprint, SHA-256, of SSH host key
+
 \IM{manually configuring host keys} manually configuring host keys
 \IM{manually configuring host keys} overriding host keys
 \IM{manually configuring host keys} host keys, manually configuring

doc/man-pageant.but

@@ -18,8 +18,8 @@
 \e bbbbbbb   bb   bbbbbbbb   bbbbbbbbbbbbbbbb   iiiiiiiiiiiiii
 \c pageant -D
 \e bbbbbbb bb
-\c pageant -l
+\c pageant -l [ --fptype format ]
-\e bbbbbbb bb
+\e bbbbbbb bb   bbbbbbbb iiiiii
 \c pageant --askpass prompt
 \e bbbbbbb bbbbbbbbb iiiiii
 
@@ -188,7 +188,8 @@ The private key files must be in PuTTY's \cw{.ppk} file format.
 \dt \cw{-l}
 
 \dd List the keys currently in the running agent. Each key's
-fingerprint and comment string will be shown.
+fingerprint and comment string will be shown. (Use the
+\cw{--fptype} opton to change the fingerprint format.)
 
 \dt \cw{--public} \e{key-identifiers}
 
@@ -205,8 +206,8 @@ in \cw{.ppk} format) or just its public half.
 
 \b The key's comment string, as shown by \cw{pageant -l}.
 
-\b Enough hex digits of the key's fingerprint to be unique among keys
+\b Enough of one of the key's fingerprint formats to be unique among
-currently loaded into the agent.
+keys currently loaded into the agent.
 
 If Pageant can uniquely identify one key by interpreting the
 \e{key-identifier} in any of these ways, it will assume that key was
@@ -214,9 +215,24 @@ the one you meant. If it cannot, you will have to specify more detail.
 
 If you find that your desired \e{key-identifier} string can be validly
 interpreted as more than one of the above \e{kinds} of identification,
-you can disambiguate by prefixing it with \cq{file:}, \cq{comment:} or
+you can disambiguate by prefixing it as follows:
-\cq{fp:} to indicate that it is a filename, comment string or
+
-fingerprint prefix respectively.
+\dt \cq{file:}
+
+\dd to indicate that it is a filename
+
+\dt \cq{comment:}
+
+\dd to indicate that it is a comment string
+
+\dt \cq{fp:}
+
+\dd to indicate that it is a fingerprint; any fingerprint format will
+be matched
+
+\dt \cq{sha256:} or \cq{md5:}
+
+\dd to indicate that it is a fingerprint of a specific format
 
 }
 
@@ -292,6 +308,11 @@ respectively. If neither option is given, Pageant will guess based on
 whether the environment variable \cw{SHELL} has a value ending in
 \cq{csh}.
 
+\dt \cw{--fptype sha256}, \cw{--fptype md5}
+
+\dd Specify the fingerprint format to print. Only applicable when
+listing fingerprints with \cw{-l}.
+
 \dt \cw{--gui-prompt}, \cw{--tty-prompt}
 
 \dd Force Pageant to prompt for key passphrases with a particular

doc/man-plink.but

@@ -208,8 +208,9 @@ a new connection.
 \dt \cw{\-hostkey} \e{key}
 
 \dd Specify an acceptable host public key. This option may be specified
-multiple times; each key can be either a fingerprint (\cw{99:aa:bb:...}) or
+multiple times; each key can be either a fingerprint (\cw{SHA256:AbCdE...},
-a base64-encoded blob in OpenSSH's one-line format.
+\cw{99:aa:bb:...}, etc) or a base64-encoded blob in OpenSSH's one-line
+format.
 
 \lcont{ Specifying this option overrides automated host key
 management; \e{only} the key(s) specified on the command-line will be

doc/man-pscp.but

@@ -145,8 +145,9 @@ to override a setting in a saved session.)
 \dt \cw{\-hostkey} \e{key}
 
 \dd Specify an acceptable host public key. This option may be specified
-multiple times; each key can be either a fingerprint (\cw{99:aa:bb:...}) or
+multiple times; each key can be either a fingerprint (\cw{SHA256:AbCdE...},
-a base64-encoded blob in OpenSSH's one-line format.
+\cw{99:aa:bb:...}, etc) or a base64-encoded blob in OpenSSH's one-line
+format.
 
 \lcont{ Specifying this option overrides automated host key
 management; \e{only} the key(s) specified on the command-line will be

doc/man-psftp.but

@@ -133,8 +133,9 @@ to override a setting in a saved session.)
 \dt \cw{\-hostkey} \e{key}
 
 \dd Specify an acceptable host public key. This option may be specified
-multiple times; each key can be either a fingerprint (\cw{99:aa:bb:...}) or
+multiple times; each key can be either a fingerprint (\cw{SHA256:AbCdE...},
-a base64-encoded blob in OpenSSH's one-line format.
+\cw{99:aa:bb:...}, etc) or a base64-encoded blob in OpenSSH's one-line
+format.
 
 \lcont{ Specifying this option overrides automated host key
 management; \e{only} the key(s) specified on the command-line will be

doc/man-putty.but

@@ -290,8 +290,9 @@ to override a setting in a saved session.)
 \dt \cw{\-hostkey} \e{key}
 
 \dd Specify an acceptable host public key. This option may be specified
-multiple times; each key can be either a fingerprint (\cw{99:aa:bb:...}) or
+multiple times; each key can be either a fingerprint (\cw{SHA256:AbCdE...},
-a base64-encoded blob in OpenSSH's one-line format.
+\cw{99:aa:bb:...}, etc) or a base64-encoded blob in OpenSSH's one-line
+format.
 
 \lcont{ Specifying this option overrides automated host key
 management; \e{only} the key(s) specified on the command-line will be

doc/man-puttygen.but

@@ -12,8 +12,8 @@
 \e bbbbbbbb   iiiiiii   bb iiiiiii   bb iiii     bbbbbbbb iiiiii
 \c          [ -C new-comment ] [ -P ] [ -q ]
 \e            bb iiiiiiiiiii     bb     bb
-\c          [ -O output-type | -l | -L | -p ]
+\c          [ -O output-type | -l | -L | -p ] [ -E fptype ]
-\e            bb iiiiiiiiiii   bb   bb   bb
+\e            bb iiiiiiiiiii   bb   bb   bb     bb iiiiii
 \c          [ -o output-file ]
 \e            bb iiiiiiiiiii
 
@@ -144,8 +144,9 @@ which is a single line (\q{\cw{ssh-rsa AAAAB3NzaC1yc2}...}).
 
 \dt \cw{fingerprint}
 
-\dd Print the fingerprint of the public key. All fingerprinting
+\dd Print a fingerprint of the public key. The \cw{-E} option lets you
-algorithms are believed compatible with OpenSSH.
+specify which fingerprinting algorithm to use. All algorithms are
+believed compatible with OpenSSH.
 
 \dt \cw{private-openssh}
 
@@ -188,6 +189,11 @@ fingerprint. Otherwise, the \c{\-o} option is required.
 
 \dd Synonym for \q{\cw{-O public}}.
 
+\dt \cw{-E} \e{fptype}
+
+\dd Specify the algorithm to use if generating a fingerprint. The
+options are \cw{sha256} (the default) and \cw{md5}.
+
 \dt \cw{\-\-new\-passphrase} \e{file}
 
 \dd Specify a file name; the first line will be read from this file
@@ -241,7 +247,7 @@ automatically detect the input key type):
 
 \c puttygen my-ssh.com-key -o mykey.ppk
 
-To display the fingerprint of a key (some key types require a
+To display the SHA-256 fingerprint of a key (some key types require a
 passphrase to extract even this much information):
 
 \c puttygen -l mykey.ppk

doc/pageant.but

@@ -60,8 +60,8 @@ 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-rsa 2048 22:d6:69:c9:22:51:ac:cb:b9:15:67:47:f7:65:6d:d7 k1
+\c ssh-ed25519  SHA256:TddlQk20DVs4LRcAsIfDN9pInKpY06D+h4kSHwWAj4w
-\c ssh-dss 2048 e4:6c:69:f3:4f:fc:cf:fc:96:c0:88:34:a7:1e:59:d7 k2
+\c ssh-rsa 2048 SHA256:8DFtyHm3kQihgy52nzX96qMcEVOq7/yJmmwQQhBWYFg
 
 For each key, the list box will tell you:
 
@@ -73,13 +73,21 @@ For each key, the list box will tell you:
 \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).
 
-\b The size (in bits) of the key.
+\b The size (in bits) of the key, for key types that come in different
+sizes.
 
 \b The \I{key fingerprint}fingerprint for the public key. This should be
 the same fingerprint given by PuTTYgen, and (hopefully) also the same
 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.
+}
+
 \b The comment attached to the key.
 
 \S{pageant-mainwin-addkey} The \q{Add Key} button

doc/plink.but

@@ -168,12 +168,14 @@ key of the server you're connecting to, to enter a user name, or to
 enter a password.
 
 To avoid being prompted for the server host key when using Plink for
-an automated connection, you should first make a \e{manual}
+an automated connection, you can first make a \e{manual}
 connection (using either of PuTTY or Plink) to the same server,
 verify the host key (see \k{gs-hostkey} for more information), and
-select Yes to add the host key to the Registry. After that, Plink
+select \q{Accept} to add the host key to the Registry. After that,
-commands connecting to that server should not give a host key prompt
+Plink commands connecting to that server should not give a host key
-unless the host key changes.
+prompt unless the host key changes. Alternatively, you can specify
+the appropriate host key(s) on Plink's command line every time you
+use it; see \k{using-cmdline-hostkey}.
 
 To avoid being prompted for a user name, you can:
 

doc/pubkey.but

@@ -200,6 +200,13 @@ 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
+\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.
+
 \S{puttygen-comment} Setting a comment for your key
 
 If you have more than one key and use them for different purposes,