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 e2a44d6c94b08d1bdf6294706c3b64267a13c86f.
This must be backported to all stable branches.
Fixes issue #2459.
(cherry picked from commit 3262c2ddcdbc832d0a60b89257edcd598f20371d)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
(cherry picked from commit dc4198519eb6fc427589e31be58bf1130c61bdc8)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
(cherry picked from commit ee8a65ae3f4a2739f3f2f30eeaa7edfe9b2a43a3)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
(cherry picked from commit 84cbce0cb2973ff3ab1cbc591012e2d1709a10e4)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
(cherry picked from commit 9465167189d376d3d03b1d7219c0c9e384ac7093)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
diff --git a/doc/configuration.txt b/doc/configuration.txt
index e923736..35157f1 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -1882,13 +1882,31 @@
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
- negotiated during the TLS handshake for all "bind" lines which do not
- 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" ciphers format,
- please check the "ssl-default-bind-ciphers" keyword. Please check the "bind"
- keyword for more information.
+ describing the list of cipher algorithms ("cipher suite") that are negotiated
+ during the TLSv1.3 handshake for all "bind" lines which do not 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, please check the
+ "ssl-default-bind-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
+
+ 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-curves <curves>
This setting is only available when support for OpenSSL was built in. It sets
@@ -1921,14 +1939,14 @@
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
- describing the list of cipher algorithms in "cipher suite" format that are
- negotiated during the TLS handshake with the server, for all "server" lines
- which do not explicitly define theirs. The format of the string is defined in
+ OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default
+ string describing the list of cipher algorithms that are negotiated during
+ the TLSv1.3 handshake with the server, for all "server" lines which do not
+ 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
- format, please check the "ssl-default-server-ciphers" keyword. Please check the
- "server" keyword for more information.
+ cipher configuration for TLSv1.2 and earlier, please check the
+ "ssl-default-server-ciphers" keyword. Please check the "server" keyword for
+ more information.
ssl-default-server-options [<option>]...
This setting is only available when support for OpenSSL was built in. It sets
@@ -13544,11 +13562,26 @@
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
- during the TLS handshake. The format of the string is defined in "man 1
- ciphers" from OpenSSL man pages under the "ciphersuites" section. For cipher
- configuration for TLSv1.2 and earlier using the "OpenSSL" ciphers format,
- please check the "ciphers" keyword.
+ the list of cipher algorithms ("cipher suite") that are negotiated during the
+ TLSv1.3 handshake. The format of the string is defined in "man 1 ciphers" from
+ OpenSSL man pages under the "ciphersuites" section. For cipher configuration
+ for TLSv1.2 and earlier, 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
crl-file <crlfile>
This setting is only available when support for OpenSSL was built in. It
@@ -14381,11 +14414,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
- negotiated during the TLS handshake with the server. The format of the string
- is defined in "man 1 ciphers" from OpenSSL man pages under the "ciphersuites"
- section. For cipher configuration for TLSv1.2 and earlier using the "OpenSSL"
- cipher format, please check the "ciphers" keyword.
+ describing the list of cipher algorithms that is negotiated during the TLS
+ 1.3 handshake with the server. The format of the string is defined in
+ "man 1 ciphers" from OpenSSL man pages under the "ciphersuites" section.
+ For cipher configuration for TLSv1.2 and earlier, please check the "ciphers"
+ keyword.
cookie <value>
The "cookie" parameter sets the cookie value assigned to the server to