X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/putty/blobdiff_plain/6d60c7915f26898fb4468096ffbf9ddc843db73a..d57f70afa40c24426e5f936c86f7640801d43f7a:/doc/config.but?ds=sidebyside

diff --git a/doc/config.but b/doc/config.but
index 07c35289..f1258176 100644
--- a/doc/config.but
+++ b/doc/config.but
@@ -2098,6 +2098,111 @@ these servers if you enable the \q{Enable legacy use of single-DES in
 SSH 2} option; by default this is disabled and PuTTY will stick to
 recommended ciphers.
 
+\H{config-ssh-kex} The Kex panel
+
+\# FIXME: This whole section is draft. Feel free to revise.
+
+The Kex panel (short for \q{key exchange}) allows you to configure
+options related to SSH-2 key exchange.
+
+Key exchange occurs at the start of an SSH connection (and
+occasionally thereafter); it establishes a shared secret that is used
+as the basis for all of SSH's security features. It is therefore very
+important for the security of the connection that the key exchange is
+secure.
+
+Key exchange is a cryptographically intensive process; if either the
+client or the server is a relatively slow machine, the slower methods
+may take several tens of seconds to complete.
+
+If connection startup is too slow, or the connection hangs
+periodically, you may want to try changing these settings.
+
+If you don't understand what any of this means, it's safe to leave
+these settings alone.
+
+This entire panel is only relevant to SSH protocol version 2; none of
+these settings affect SSH-1 at all.
+
+\S{config-ssh-kex-order} Key exchange algorithm selection
+
+\cfg{winhelp-topic}{ssh.kex.order}
+
+PuTTY supports a variety of SSH-2 key exchange methods, and allows you
+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 Diffie-Hellman key
+exchange:
+
+\b \q{Group 14}: 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 exchange}: with this method, instead of using a fixed
+group, PuTTY requests that the server suggest a group to use for key
+exchange; the server can avoid groups known to be weak, and possibly
+invent new ones over time, without any changes required to PuTTY's
+configuration. We recommend use of this method, if possible.
+
+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
+to that for cipher selection (see \k{config-ssh-encryption}).
+
+\S{config-ssh-kex-rekey} Repeat key exchange
+
+\cfg{winhelp-topic}{ssh.kex.repeat}
+
+If the session key negotiated at connection startup is used too much
+or for too long, it may become feasible to mount attacks against the
+SSH connection. Therefore, the SSH-2 protocol specifies that a new key
+exchange should take place every so often; this can be initiated by
+either the client or the server.
+
+While this renegotiation is taking place, no data can pass through
+the SSH connection, so it may appear to \q{freeze}. (The occurrence of
+repeat key exchange is noted in the Event Log; see
+\k{using-eventlog}.) Usually the same algorithm is used as at the
+start of the connection, with a similar overhead.
+
+These options control how often PuTTY will initiate a repeat key
+exchange (\q{rekey}). You can also force a key exchange at any time
+from the Special Commands menu (see \k{using-specials}).
+
+\# FIXME: do we have any additions to the SSH-2 drafts' advice on
+these values? Do we want to enforce any limits?
+
+\b \q{Max minutes before rekey} specifies the amount of time that is
+allowed to elapse before a rekey is initiated. If this is set to zero,
+PuTTY will not rekey due to elapsed time. The SSH-2 protocol
+specification recommends a timeout of at most 60 minutes.
+
+\b \q{Max data before rekey} specifies the amount of data (in bytes)
+that is permitted to flow in either direction before a rekey is
+initiated. If this is set to zero, PuTTY will not rekey due to
+transferred data. The SSH-2 protocol specification recommends a limit
+of at most 1 gigabyte.
+
+\lcont{
+
+As well as specifying a value in bytes, the following shorthand can be
+used:
+
+\b \cq{1k} specifies 1 kilobyte (1024 bytes).
+
+\b \cq{1M} specifies 1 megabyte (1024 kilobytes).
+
+\b \cq{1G} specifies 1 gigabyte (1024 megabytes).
+
+}
+
+PuTTY can be prevented from initiating a rekey entirely by setting
+both of these values to zero. (Note, however, that the SSH server may
+still initiate rekeys.)
+
 \H{config-ssh-auth} The Auth panel
 
 The Auth panel allows you to configure authentication options for
@@ -2455,23 +2560,6 @@ to talking to OpenSSH.
 
 This is an SSH2-specific bug.
 
-\S{config-ssh-bug-dhgex} \q{Chokes on Diffie-Hellman group exchange}
-
-\cfg{winhelp-topic}{ssh.bugs.dhgex2}
-
-We have anecdotal evidence that some SSH servers claim to be able to
-perform Diffie-Hellman group exchange, but fail to actually do so
-when PuTTY tries to. If your SSH2 sessions spontaneously close
-immediately after opening the PuTTY window, it might be worth
-enabling the workaround for this bug to see if it helps.
-
-We have no hard evidence that any specific version of specific
-server software reliably demonstrates this bug. Therefore, PuTTY
-will never \e{assume} a server has this bug; if you want the
-workaround, you need to enable it manually.
-
-This is an SSH2-specific bug.
-
 \S{config-ssh-bug-pksessid2} \q{Misuses the session ID in PK auth}
 
 \cfg{winhelp-topic}{ssh.bugs.pksessid2}