\b \c{&H} will be replaced by the host name you are connecting to.
+\b \c{&P} will be replaced by the port number you are connecting to on
+the target host.
+
For example, if you enter the host name
\c{c:\\puttylogs\\log-&h-&y&m&d-&t.dat}, you will end up with files looking
like
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}
existing SSH connection set up by an instance of GUI PuTTY. The one
special case is that PSCP and PSFTP will \e{never} act as upstreams.
-\H{config-ssh-kex} The Kex panel
+It is possible to test programmatically for the existence of a live
+upstream using Plink. See \k{plink-option-shareexists}.
-\# FIXME: This whole section is draft. Feel free to revise.
+\H{config-ssh-kex} The Kex panel
The Kex panel (short for \q{\i{key exchange}}) allows you to configure
options related to SSH-2 key exchange.
to choose which one you prefer to use; configuration is similar to
cipher selection (see \k{config-ssh-encryption}).
-PuTTY currently supports the following varieties of \i{Diffie-Hellman key
-exchange}:
+PuTTY currently supports the following key exchange methods:
+
+\b \q{ECDH}: \i{elliptic curve} \i{Diffie-Hellman key exchange}.
-\b \q{Group 14}: a well-known 2048-bit group.
+\b \q{Group 14}: Diffie-Hellman key exchange with a well-known
+2048-bit group.
-\b \q{Group 1}: a well-known 1024-bit group. This is less secure
-\#{FIXME better words} than group 14, but may be faster with slow
-client or server machines, and may be the only method supported by
-older server software.
+\b \q{Group 1}: Diffie-Hellman key exchange with a well-known
+1024-bit group. This is less secure \#{FIXME better words} than
+group 14, but may be faster with slow client or server machines,
+and may be the only method supported by older server software.
\b \q{\ii{Group exchange}}: with this method, instead of using a fixed
group, PuTTY requests that the server suggest a group to use for key
invent new ones over time, without any changes required to PuTTY's
configuration. We recommend use of this method, if possible.
-In addition, PuTTY supports \i{RSA key exchange}, which requires much less
-computational effort on the part of the client, and somewhat less on
-the part of the server, than Diffie-Hellman key exchange.
+\b \q{\i{RSA key exchange}}: this requires much less computational
+effort on the part of the client, and somewhat less on the part of
+the server, than Diffie-Hellman key exchange.
If the first algorithm PuTTY finds is below the \q{warn below here}
line, you will see a warning box when you make the connection, similar
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
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.
+\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
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)
The Auth panel allows you to configure \i{authentication} options for
SSH sessions.
-\S{config-ssh-noauth} \q{Bypass authentication entirely}
-
-\cfg{winhelp-topic}{ssh.auth.bypass}
-
-In SSH-2, it is possible to establish a connection without using SSH's
-mechanisms to identify or authenticate oneself to the server. Some
-servers may prefer to handle authentication in the data channel, for
-instance, or may simply require no authentication whatsoever.
-
-By default, PuTTY assumes the server requires authentication (most
-do), and thus must provide a username. If you find you are getting
-unwanted username prompts, you could try checking this option.
-
-This option only affects SSH-2 connections. SSH-1 connections always
-require an authentication step.
-
\S{config-ssh-banner} \q{Display pre-authentication banner}
\cfg{winhelp-topic}{ssh.auth.banner}
By unchecking this option, display of the banner can be suppressed
entirely.
+\S{config-ssh-noauth} \q{Bypass authentication entirely}
+
+\cfg{winhelp-topic}{ssh.auth.bypass}
+
+In SSH-2, it is in principle possible to establish a connection
+without using SSH's mechanisms to identify or prove who you are
+to the server. An SSH server could prefer to handle authentication
+in the data channel, for instance, or simply require no user
+authentication whatsoever.
+
+By default, PuTTY assumes the server requires authentication (we've
+never heard of one that doesn't), and thus must start this process
+with a username. If you find you are getting username prompts that
+you cannot answer, you could try enabling this option. However,
+most SSH servers will reject this.
+
+This is not the option you want if you have a username and just want
+PuTTY to remember it; for that see \k{config-username}.
+It's also probably not what if you're trying to set up passwordless
+login to a mainstream SSH server; depending on the server, you
+probably wanted public-key authentication (\k{pubkey})
+or perhaps GSSAPI authentication (\k{config-ssh-auth-gssapi}).
+(These are still forms of authentication, even if you don't have to
+interact with them.)
+
+This option only affects SSH-2 connections. SSH-1 connections always
+require an authentication step.
+
\S{config-ssh-tryagent} \q{Attempt authentication using Pageant}
\cfg{winhelp-topic}{ssh.auth.pageant}
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 private key 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. You can also specify a \e{public} key file
+in this case (in RFC 4716 or OpenSSH format), as that's sufficient to
+identify the key to Pageant, but of course if Pageant isn't present
+PuTTY can't fall back to using this file itself.
\H{config-ssh-auth-gssapi} The \i{GSSAPI} panel
authentication exchange to a library elsewhere on the client
machine, which in principle can authenticate in many different ways
but in practice is usually used with the \i{Kerberos} \i{single sign-on}
-protocol.
+protocol to implement \i{passwordless login}.
GSSAPI is only available in the SSH-2 protocol.
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.
ticking \q{Auto} should always give you a port which you can connect
to using either protocol.
-\H{config-ssh-bugs} \I{SSH server bugs}The Bugs panel
+\H{config-ssh-bugs} \I{SSH server bugs}The Bugs and More Bugs panels
Not all SSH servers work properly. Various existing servers have
bugs in them, which can make it impossible for a client to talk to
if the server is a version which PuTTY's bug database does not know
about, then PuTTY will not know what bugs to expect.
-The Bugs panel allows you to manually configure the bugs PuTTY
-expects to see in the server. Each bug can be configured in three
-states:
+The Bugs and More Bugs panels (there are two because we have so many
+bug compatibility modes) allow you to manually configure the bugs
+PuTTY expects to see in the server. Each bug can be configured in
+three states:
\b \q{Off}: PuTTY will assume the server does not have the bug.
and terminate with an error along the lines of \q{Received
\cw{SSH2_MSG_CHANNEL_FAILURE} for nonexistent channel 256}.
+\S{config-ssh-bug-oldgex2} \q{Only supports pre-RFC4419 SSH-2 DH GEX}
+
+\cfg{winhelp-topic}{ssh.bugs.oldgex2}
+
+The SSH key exchange method that uses Diffie-Hellman group exchange
+was redesigned after its original release, to use a slightly more
+sophisticated setup message. Almost all SSH implementations switched
+over to the new version. (PuTTY was one of the last.) A few old
+servers still only support the old one.
+
+If this bug is detected, and the client and server negotiate
+Diffie-Hellman group exchange, then PuTTY will send the old message
+now known as \cw{SSH2_MSG_KEX_DH_GEX_REQUEST_OLD} in place of the new
+\cw{SSH2_MSG_KEX_DH_GEX_REQUEST}.
+
+This is an SSH-2-specific bug.
+
\H{config-serial} The Serial panel
The \i{Serial} panel allows you to configure options that only apply
projects / PuTTY.git / blobdiff