From 495acac227f65e54b9c5d75eebd83a2e050236eb Mon Sep 17 00:00:00 2001
From: Damien Miller <djm@cvs.openbsd.org>
Date: Fri, 14 Jun 2024 05:01:23 +0000
Subject: clarify KEXAlgorithms supported vs available. Inspired by bz3701 from
 Colin Watson.

---
 usr.bin/ssh/ssh_config.5  | 13 +++++++++----
 usr.bin/ssh/sshd_config.5 | 15 ++++++++++-----
 2 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/usr.bin/ssh/ssh_config.5 b/usr.bin/ssh/ssh_config.5
index 165ba75f90a..9cd1ccdfd4f 100644
--- a/usr.bin/ssh/ssh_config.5
+++ b/usr.bin/ssh/ssh_config.5
@@ -33,8 +33,8 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $OpenBSD: ssh_config.5,v 1.394 2024/02/21 06:01:13 djm Exp $
-.Dd $Mdocdate: February 21 2024 $
+.\" $OpenBSD: ssh_config.5,v 1.395 2024/06/14 05:01:22 djm Exp $
+.Dd $Mdocdate: June 14 2024 $
 .Dt SSH_CONFIG 5
 .Os
 .Sh NAME
@@ -1262,8 +1262,12 @@ it may be zero or more of:
 and
 .Cm skey .
 .It Cm KexAlgorithms
-Specifies the available KEX (Key Exchange) algorithms.
+Specifies the permitted KEX (Key Exchange) algorithms that will be used and
+their preference order.
+The selected algorithm will the the first algorithm in this list that
+the server also supports.
 Multiple algorithms must be comma-separated.
+.Pp
 If the specified list begins with a
 .Sq +
 character, then the specified algorithms will be appended to the default set
@@ -1276,6 +1280,7 @@ If the specified list begins with a
 .Sq ^
 character, then the specified algorithms will be placed at the head of the
 default set.
+.Pp
 The default is:
 .Bd -literal -offset indent
 sntrup761x25519-sha512@openssh.com,
@@ -1287,7 +1292,7 @@ diffie-hellman-group18-sha512,
 diffie-hellman-group14-sha256
 .Ed
 .Pp
-The list of available key exchange algorithms may also be obtained using
+The list of supported key exchange algorithms may also be obtained using
 .Qq ssh -Q kex .
 .It Cm KnownHostsCommand
 Specifies a command to use to obtain a list of host keys, in addition to
diff --git a/usr.bin/ssh/sshd_config.5 b/usr.bin/ssh/sshd_config.5
index 7047434e893..0a4d5d8ad16 100644
--- a/usr.bin/ssh/sshd_config.5
+++ b/usr.bin/ssh/sshd_config.5
@@ -33,8 +33,8 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $OpenBSD: sshd_config.5,v 1.362 2024/06/13 15:06:33 naddy Exp $
-.Dd $Mdocdate: June 13 2024 $
+.\" $OpenBSD: sshd_config.5,v 1.363 2024/06/14 05:01:22 djm Exp $
+.Dd $Mdocdate: June 14 2024 $
 .Dt SSHD_CONFIG 5
 .Os
 .Sh NAME
@@ -1004,9 +1004,13 @@ file on logout.
 The default is
 .Cm yes .
 .It Cm KexAlgorithms
-Specifies the available KEX (Key Exchange) algorithms.
+Specifies the permitted KEX (Key Exchange) algorithms that the server will
+offer to clients.
+The ordering of this list is not important, as the client specifies the
+preference order.
 Multiple algorithms must be comma-separated.
-Alternately if the specified list begins with a
+.Pp
+If the specified list begins with a
 .Sq +
 character, then the specified algorithms will be appended to the default set
 instead of replacing them.
@@ -1018,6 +1022,7 @@ If the specified list begins with a
 .Sq ^
 character, then the specified algorithms will be placed at the head of the
 default set.
+.Pp
 The supported algorithms are:
 .Pp
 .Bl -item -compact -offset indent
@@ -1059,7 +1064,7 @@ diffie-hellman-group16-sha512,diffie-hellman-group18-sha512,
 diffie-hellman-group14-sha256
 .Ed
 .Pp
-The list of available key exchange algorithms may also be obtained using
+The list of supported key exchange algorithms may also be obtained using
 .Qq ssh -Q KexAlgorithms .
 .It Cm ListenAddress
 Specifies the local addresses
-- 
cgit v1.2.3