DOC: configuration: clarify ciphersuites usage (V2)

The previous attempt removed the TLSv1.3 version for the
"ciphersuites" keywords. However it looks like the TLSv1.2 support for
SSL_CTX_set_ciphersuites() is a bug, and can have inconsistent behavior.

This patch revert the previous attempt and add explaining about this
problem and clear examples on how to configure TLSv1.2 ciphers + TLSv1.3
ciphersuites.

Revert "DOC: configuration: clarify ciphersuites usage"
This reverts commit e2a44d6c94.

This must be backported to all stable branches.

Fixes issue #2459.

doc/configuration.txt

@@ -2298,13 +2298,31 @@ ssl-default-bind-ciphers <ciphers>
 ssl-default-bind-ciphersuites <ciphersuites>
   This setting is only available when support for OpenSSL was built in and
   OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default string
-  describing the list of cipher algorithms in "cipher suite" format that are
+  describing the list of cipher algorithms ("cipher suite") that are negotiated
-  negotiated during the TLS handshake for all "bind" lines which do not
+  during the TLSv1.3 handshake for all "bind" lines which do not explicitly define
-  explicitly define theirs. The format of the string is defined in "man 1
+  theirs. The format of the string is defined in
-  ciphers" from OpenSSL man pages under the section "ciphersuites". For cipher
+  "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
-  configuration for TLSv1.2 and earlier using the "OpenSSL" ciphers format,
+  cipher configuration for TLSv1.2 and earlier, please check the
-  please check the "ssl-default-bind-ciphers" keyword. Please check the "bind"
+  "ssl-default-bind-ciphers" keyword. This setting might accept TLSv1.2
-  keyword for more information.
+  ciphersuites however this is an undocumented behavior and not recommended as
+  it could be inconsistent or buggy.
+  The default TLSv1.3 ciphersuites of OpenSSL are:
+  "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
+
+  TLSv1.3 only supports 5 ciphersuites:
+
+  - TLS_AES_128_GCM_SHA256
+  - TLS_AES_256_GCM_SHA384
+  - TLS_CHACHA20_POLY1305_SHA256
+  - TLS_AES_128_CCM_SHA256
+  - TLS_AES_128_CCM_8_SHA256
+
+  Please check the "bind" keyword for more information.
+
+  Example:
+      global
+          ssl-default-bind-ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256
+          ssl-default-bind-ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
 
 ssl-default-bind-client-sigalgs <sigalgs>
   This setting is only available when support for OpenSSL was built in. It sets
@@ -2368,14 +2386,14 @@ ssl-default-server-ciphers <ciphers>
 
 ssl-default-server-ciphersuites <ciphersuites>
   This setting is only available when support for OpenSSL was built in and
-  OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default string
+  OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default
-  describing the list of cipher algorithms in "cipher suite" format that are
+  string describing the list of cipher algorithms that are negotiated during
-  negotiated during the TLS handshake with the server, for all "server" lines
+  the TLSv1.3 handshake with the server, for all "server" lines which do not
-  which do not explicitly define theirs. The format of the string is defined in
+  explicitly define theirs. The format of the string is defined in
   "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
-  cipher configuration for TLSv1.2 and earlier using the "OpenSSL" cipher
+  cipher configuration for TLSv1.2 and earlier, please check the
-  format, please check the "ssl-default-server-ciphers" keyword. Please check the
+  "ssl-default-server-ciphers" keyword. Please check the "server" keyword for
-  "server" keyword for more information.
+  more information.
 
 ssl-default-server-client-sigalgs <sigalgs>
   This setting is only available when support for OpenSSL was built in. It sets
@@ -15533,11 +15551,26 @@ ciphers <ciphers>
 ciphersuites <ciphersuites>
   This setting is only available when support for OpenSSL was built in and
   OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing
-  the list of cipher algorithms in "cipher suite" format that are negotiated
+  the list of cipher algorithms ("cipher suite") that are negotiated during the
-  during the TLS handshake. The format of the string is defined in "man 1
+  TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from
-  ciphers" from OpenSSL man pages under the "ciphersuites" section. For cipher
+  OpenSSL man pages under the "ciphersuites" section. For cipher configuration
-  configuration for TLSv1.2 and earlier using the "OpenSSL" ciphers format,
+  for TLSv1.2 and earlier, please check the "ciphers" keyword.
-  please check the "ciphers" keyword.
+  This setting might accept TLSv1.2 ciphersuites however this is an
+  undocumented behavior and not recommended as it could be inconsistent or buggy.
+  The default TLSv1.3 ciphersuites of OpenSSL are:
+  "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
+
+  TLSv1.3 only supports 5 ciphersuites:
+
+  - TLS_AES_128_GCM_SHA256
+  - TLS_AES_256_GCM_SHA384
+  - TLS_CHACHA20_POLY1305_SHA256
+  - TLS_AES_128_CCM_SHA256
+  - TLS_AES_128_CCM_8_SHA256
+
+  Example:
+          ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256
+          ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
 
 client-sigalgs <sigalgs>
   This setting is only available when support for OpenSSL was built in. It sets
@@ -16676,11 +16709,11 @@ ciphersuites <ciphersuites>
 
   This setting is only available when support for OpenSSL was built in and
   OpenSSL 1.1.1 or later was used to build HAProxy. This option sets the string
-  describing the list of cipher algorithms in "cipher suite" format that is
+  describing the list of cipher algorithms that is negotiated during the TLS
-  negotiated during the TLS handshake with the server. The format of the string
+  1.3 handshake with the server. The format of the string is defined in
-  is defined in "man 1 ciphers" from OpenSSL man pages under the "ciphersuites"
+  "man 1 ciphers" from OpenSSL man pages under the "ciphersuites" section.
-  section. For cipher configuration for TLSv1.2 and earlier using the "OpenSSL"
+  For cipher configuration for TLSv1.2 and earlier, please check the "ciphers"
-  cipher format, please check the "ciphers" keyword.
+  keyword.
 
 client-sigalgs <sigalgs>
   May be used in the following contexts: tcp, http, log, peers, ring