Add some index terms for host key overrides.

[PuTTY.git] / doc / config.but

diff --git a/doc/config.but b/doc/config.but
index 7a7c451a0535158a247923662047f4e89aea411d..97d94b9986f00bcf70cb16454ce56bff290c13ef 100644 (file)
--- a/doc/config.but
+++ b/doc/config.but
@@ -1539,7 +1539,7 @@ If you do not see \cq{colors#256} in the output, you may need to
 change your terminal setting. On modern Linux machines, you could
 try \cq{xterm-256color}.
 
 change your terminal setting. On modern Linux machines, you could
 try \cq{xterm-256color}.
 

-\S{config-boldcolour} \q{Indicate bolded text by changing}
+\S{config-boldcolour} \q{Indicate bolded text by changing...}

 
 \cfg{winhelp-topic}{colours.bold}
 
 
 \cfg{winhelp-topic}{colours.bold}
 


@@ -1556,6 +1556,10 @@ box, bold and non-bold text will be displayed in the same colour, and
 instead the font will change to indicate the difference. If you select
 \q{Both}, the font and the colour will both change.
 
 instead the font will change to indicate the difference. If you select
 \q{Both}, the font and the colour will both change.
 

+Some applications rely on \q{\i{bold black}} being distinguishable
+from a black background; if you choose \q{The font}, their text may
+become invisible.
+

 \S{config-logpalette} \q{Attempt to use \i{logical palettes}}
 
 \cfg{winhelp-topic}{colours.logpal}
 \S{config-logpalette} \q{Attempt to use \i{logical palettes}}
 
 \cfg{winhelp-topic}{colours.logpal}


@@ -1600,10 +1604,10 @@ and \I{default background}background, and the precise shades of all the
 \I{ANSI colours}ANSI configurable colours (black, red, green, yellow, blue,
 magenta, cyan, and white). You can also modify the precise shades used for
 the \i{bold} versions of these colours; these are used to display bold text
 \I{ANSI colours}ANSI configurable colours (black, red, green, yellow, blue,
 magenta, cyan, and white). You can also modify the precise shades used for
 the \i{bold} versions of these colours; these are used to display bold text

-if you have selected \q{Bolded text is a different colour}, and can also be
-used if the server asks specifically to use them. (Note that \q{Default
-Bold Background} is \e{not} the background colour used for bold text;
-it is only used if the server specifically asks for a bold
+if you have chosen to indicate that by colour (see \k{config-boldcolour}),
+and can also be used if the server asks specifically to use them. (Note
+that \q{Default Bold Background} is \e{not} the background colour used for
+bold text; it is only used if the server specifically asks for a bold

 background.)
 
 \H{config-connection} The Connection panel
 background.)
 
 \H{config-connection} The Connection panel


@@ -2276,6 +2280,8 @@ have specified.
 
 \S{config-ssh-sharing} Sharing an SSH connection between PuTTY tools
 
 
 \S{config-ssh-sharing} Sharing an SSH connection between PuTTY tools
 

+\cfg{winhelp-topic}{ssh.sharing}
+

 The controls in this box allow you to configure PuTTY to reuse an
 existing SSH connection, where possible.
 
 The controls in this box allow you to configure PuTTY to reuse an
 existing SSH connection, where possible.
 


@@ -2460,6 +2466,57 @@ when the SSH connection is idle, so they shouldn't cause the same
 problems.  The SSH-1 protocol, incidentally, has even weaker integrity
 protection than SSH-2 without rekeys.
 
 problems.  The SSH-1 protocol, incidentally, has even weaker integrity
 protection than SSH-2 without rekeys.
 

+\S{config-ssh-kex-manual-hostkeys} \ii{Manually configuring host keys}
+
+\cfg{winhelp-topic}{ssh.kex.manualhostkeys}
+
+In some situations, if PuTTY's automated host key management is not
+doing what you need, you might need to manually configure PuTTY to
+accept a specific host key, or one of a specific set of host keys.
+
+One reason why you might want to do this is because the host name
+PuTTY is connecting to is using round-robin DNS to return one of
+multiple actual servers, and they all have different host keys. In
+that situation, you might need to configure PuTTY to accept any of a
+list of host keys for the possible servers, while still rejecting any
+key not in that list.
+
+Another reason is if PuTTY's automated host key management is
+completely unavailable, e.g. because PuTTY (or Plink or PSFTP, etc) is
+running in a Windows environment without access to the Registry. In
+that situation, you will probably want to use the \cw{-hostkey}
+command-line option to configure the expected host key(s); see
+\k{using-cmdline-hostkey}.
+
+To configure manual host keys via the GUI, enter some text describing
+the host key into the edit box in the \q{Manually configure host keys
+for this connection} container, and press the \q{Add} button. The text
+will appear in the \q{Host keys or fingerprints to accept} list box.
+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
+Event Log and host key dialog boxes, i.e. sixteen 2-digit hex numbers
+separated by colons.
+
+\b A base64-encoded blob describing an SSH-2 public key in the
+standard way. This can be found in OpenSSH's one-line public key
+format, or by concatenating all the lines of the public key section in
+one of PuTTY's \cw{.ppk} files. Alternatively, you can load a key into
+PuTTYgen, and paste out the OpenSSH-format public key line it
+displays.
+
+If this box contains at least one host key or fingerprint when PuTTY
+makes an SSH connection, then PuTTY's automated host key management is
+completely bypassed: the connection will be permitted if and only if
+the host key presented by the server is one of the keys listed in this
+box, and the host key store in the Registry will be neither read
+\e{nor written}.
+
+If the box is empty (as it usually is), then PuTTY's automated host
+key management will work as normal.
+

 \H{config-ssh-encryption} The Cipher panel
 
 \cfg{winhelp-topic}{ssh.ciphers}
 \H{config-ssh-encryption} The Cipher panel
 
 \cfg{winhelp-topic}{ssh.ciphers}


@@ -3288,6 +3345,31 @@ believes the server has this bug, it will never send its
 \cq{winadj@putty.projects.tartarus.org} request, and will make do
 without its timing data.
 
 \cq{winadj@putty.projects.tartarus.org} request, and will make do
 without its timing data.
 

+\S{config-ssh-bug-chanreq} \q{Replies to channel requests after channel close}
+
+\cfg{winhelp-topic}{ssh.bugs.chanreq}
+
+The SSH protocol as published in RFC 4254 has an ambiguity which
+arises if one side of a connection tries to close a channel, while the
+other side simultaneously sends a request within the channel and asks
+for a reply. RFC 4254 leaves it unclear whether the closing side
+should reply to the channel request after having announced its
+intention to close the channel.
+
+Discussion on the \cw{ietf-ssh} mailing list in April 2014 formed a
+clear consensus that the right answer is no. However, because of the
+ambiguity in the specification, some SSH servers have implemented the
+other policy; for example,
+\W{https://bugzilla.mindrot.org/show_bug.cgi?id=1818}{OpenSSH used to}
+until it was fixed.
+
+Because PuTTY sends channel requests with the \q{want reply} flag
+throughout channels' lifetime (see \k{config-ssh-bug-winadj}), it's
+possible that when connecting to such a server it might receive a
+reply to a request after it thinks the channel has entirely closed,
+and terminate with an error along the lines of \q{Received
+\cw{SSH2_MSG_CHANNEL_FAILURE} for nonexistent channel 256}.
+

 \H{config-serial} The Serial panel
 
 The \i{Serial} panel allows you to configure options that only apply
 \H{config-serial} The Serial panel
 
 The \i{Serial} panel allows you to configure options that only apply


@@ -3419,5 +3501,5 @@ Here is an example \c{PUTTYRND.REG} file:
 
 You should replace \c{a:\\putty.rnd} with the location where you
 want to store your random number data. If the aim is to carry around
 
 You should replace \c{a:\\putty.rnd} with the location where you
 want to store your random number data. If the aim is to carry around

-PuTTY and its settings on one floppy, you probably want to store it
-on the floppy.
+PuTTY and its settings on one USB stick, you probably want to store it
+on the USB stick.