-\define{versionidconfig} \versionid $Id$
-
\C{config} Configuring PuTTY
This chapter describes all the \i{configuration options} in PuTTY.
you to reconfirm its host key. Conversely, if you expect to use the
same local port number for port forwardings to lots of different
servers, you probably didn't want any particular server's host key
-cached under that local port number.
+cached under that local port number. (For this latter case, you
+could also explicitly configure host keys in the relevant sessions;
+see \k{config-ssh-kex-manual-hostkeys}.)
If you just enter a host name for this option, PuTTY will cache the
SSH host key under the default SSH port for that host, irrespective
\cfg{winhelp-topic}{ssh.protocol}
-This allows you to select whether you would like to use \i{SSH protocol
-version 1} or \I{SSH-2}version 2. \#{FIXME: say something about this elsewhere?}
+This allows you to select whether you would prefer to use \i{SSH protocol
+version 1} or \I{SSH-2}version 2, and whether to permit falling back
+to the other version.
-PuTTY will attempt to use protocol 1 if the server you connect to
-does not offer protocol 2, and vice versa.
+With the settings \q{1} and \q{2}, PuTTY will attempt to use protocol 1
+if the server you connect to does not offer protocol 2, and vice versa.
If you select \q{1 only} or \q{2 only} here, PuTTY will only connect
if the server you connect to offers the SSH protocol version you
have specified.
+You should normally leave this at the default, \q{2 only}. The older
+SSH-1 protocol is no longer developed, has many known cryptographic
+weaknesses, and is generally not considered to be secure. If you
+permit use of SSH-1 by selecting \q{2} instead of \q{2 only}, an
+active attacker can force downgrade to SSH-1 even if the server
+you're connecting to supports SSH-2.
+
+PuTTY's protocol 1 implementation is provided mainly for
+compatibility, and is no longer being enhanced.
+
\S{config-ssh-sharing} Sharing an SSH connection between PuTTY tools
\cfg{winhelp-topic}{ssh.sharing}
\H{config-ssh-kex} The Kex panel
-\# FIXME: This whole section is draft. Feel free to revise.
-
The Kex panel (short for \q{\i{key exchange}}) allows you to configure
options related to SSH-2 key exchange.
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}.
+
+For situations where PuTTY's automated host key management simply
+picks the wrong host name to store a key under, you may want to
+consider setting a \q{logical host name} instead; see
+\k{config-loghost}.
+
+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
+OpenSSH's one-line public key format. How you acquire a public key in
+this format is server-dependent; on an OpenSSH server it can typically
+be found in a location like \c{/etc/ssh/ssh_host_rsa_key.pub}.
+
+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}
private key in another format that you want to use with PuTTY, see
\k{puttygen-conversions}.
-If a key file is specified here, and \i{Pageant} is running (see
-\k{pageant}), PuTTY will first try asking Pageant to authenticate with
-that key, and ignore any other keys Pageant may have. If that fails,
-PuTTY will ask for a passphrase as normal.
+You can use the authentication agent \i{Pageant} so that you do not
+need to explicitly configure a key here; see \k{pageant}. If a file
+is specified here with Pageant running, PuTTY will first try asking
+Pageant to authenticate with that key, and ignore any other keys
+Pageant may have. If that fails, PuTTY will ask for a passphrase as
+normal.
\H{config-ssh-auth-gssapi} The \i{GSSAPI} panel
The X11 panel allows you to configure \i{forwarding of X11} over an
SSH connection.
-If your server lets you run X Window System applications, X11
-forwarding allows you to securely give those applications access to
+If your server lets you run X Window System \i{graphical applications},
+X11 forwarding allows you to securely give those applications access to
a local X display on your PC.
To enable X11 forwarding, check the \q{Enable X11 forwarding} box.
by a colon, in the \q{Destination} box. Connections received on the
source port will be directed to this destination. For example, to
connect to a POP-3 server, you might enter
-\c{popserver.example.com:110}.
+\c{popserver.example.com:110}. (If you need to enter a literal
+\i{IPv6 address}, enclose it in square brackets, for instance
+\cq{[::1]:2200}.)
\b Click the \q{Add} button. Your forwarding details should appear
in the list box.
server, the session will succeed, but keepalives will not work and
the session might be less cryptographically secure than it could be.
+\S{config-ssh-bug-winadj} \q{Chokes on PuTTY's SSH-2 \cq{winadj} requests}
+
+\cfg{winhelp-topic}{ssh.bugs.winadj}
+
+PuTTY sometimes sends a special request to SSH servers in the middle
+of channel data, with the name \cw{winadj@putty.projects.tartarus.org}
+(see \k{sshnames-channel}). The purpose of this request is to measure
+the round-trip time to the server, which PuTTY uses to tune its flow
+control. The server does not actually have to \e{understand} the
+message; it is expected to send back a \cw{SSH_MSG_CHANNEL_FAILURE}
+message indicating that it didn't understand it. (All PuTTY needs for
+its timing calculations is \e{some} kind of response.)
+
+It has been known for some SSH servers to get confused by this message
+in one way or another \dash because it has a long name, or because
+they can't cope with unrecognised request names even to the extent of
+sending back the correct failure response, or because they handle it
+sensibly but fill up the server's log file with pointless spam, or
+whatever. PuTTY therefore supports this bug-compatibility flag: if it
+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.
+
\S{config-ssh-bug-hmac2} \q{Miscomputes SSH-2 HMAC keys}
\cfg{winhelp-topic}{ssh.bugs.hmac2}
correct server, the session will work correctly, but download
performance will be less than it could be.
-\S{config-ssh-bug-winadj} \q{Chokes on PuTTY's SSH-2 \cq{winadj} requests}
+\S{config-ssh-bug-chanreq} \q{Replies to requests on closed channels}
-\cfg{winhelp-topic}{ssh.bugs.winadj}
+\cfg{winhelp-topic}{ssh.bugs.chanreq}
-PuTTY sometimes sends a special request to SSH servers in the middle
-of channel data, with the name \cw{winadj@putty.projects.tartarus.org}
-(see \k{sshnames-channel}). The purpose of this request is to measure
-the round-trip time to the server, which PuTTY uses to tune its flow
-control. The server does not actually have to \e{understand} the
-message; it is expected to send back a \cw{SSH_MSG_CHANNEL_FAILURE}
-message indicating that it didn't understand it. (All PuTTY needs for
-its timing calculations is \e{some} kind of response.)
+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.
-It has been known for some SSH servers to get confused by this message
-in one way or another \dash because it has a long name, or because
-they can't cope with unrecognised request names even to the extent of
-sending back the correct failure response, or because they handle it
-sensibly but fill up the server's log file with pointless spam, or
-whatever. PuTTY therefore supports this bug-compatibility flag: if it
-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.
+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
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.
projects / PuTTY.git / blobdiff