From: Bertrand Jacquin <bertrand@jacquin.bzh>
Date: Sun, 3 Feb 2019 18:48:49 +0000 (+0000)
Subject: DOC: ssl: Stop documenting ciphers example to use
X-Git-Tag: v2.0-dev1~58
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=4f03ab06a90df8e88ba2e347f52465b31392acc4;p=thirdparty%2Fhaproxy.git

DOC: ssl: Stop documenting ciphers example to use

Since TLS ciphers are not well understand, it is very common pratice to
copy and paste parameters from documentation and use them as-is. Since RC4
should not be used anymore, it is wiser to link users to up to date
documnetation from Mozilla to avoid unsafe configuration in the wild.

Clarify the location of man pages for OpenSSL when missing.
---

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 9d366b9c7e..d2a49cf11b 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -1029,10 +1029,12 @@ ssl-default-bind-ciphers <ciphers>
   the default string describing the list of cipher algorithms ("cipher suite")
   that are negotiated during the SSL/TLS handshake up to TLSv1.2 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, and can be for instance
-  a string such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes). For
-  TLSv1.3 cipher configuration, please check the "ssl-default-bind-ciphersuites"
-  keyword. Please check the "bind" keyword for more information.
+  is defined in "man 1 ciphers" from OpenSSL man pages. For background
+  information and recommendations see e.g.
+  (https://wiki.mozilla.org/Security/Server_Side_TLS) and
+  (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
+  cipher configuration, please check the "ssl-default-bind-ciphersuites" keyword.
+  Please check the "bind" keyword for more information.
 
 ssl-default-bind-ciphersuites <ciphersuites>
   This setting is only available when support for OpenSSL was built in and
@@ -1040,11 +1042,9 @@ ssl-default-bind-ciphersuites <ciphersuites>
   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", and can
-  be for instance a string such as
-  "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
-  (without quotes). For cipher configuration for TLSv1.2 and earlier, please check
-  the "ssl-default-bind-ciphers" keyword. Please check the "bind" keyword for more
+  "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. Please check the "bind" keyword for more
   information.
 
 ssl-default-bind-options [<option>]...
@@ -1061,9 +1061,13 @@ ssl-default-server-ciphers <ciphers>
   sets the default string describing the list of cipher algorithms that are
   negotiated during the SSL/TLS handshake up to TLSv1.2 with the server,
   for all "server" lines which do not explicitly define theirs. The format of
-  the string is defined in "man 1 ciphers". For TLSv1.3 cipher configuration,
-  please check the "ssl-default-server-ciphersuites" keyword. Please check the
-  "server" keyword for more information.
+  the string is defined in "man 1 ciphers" from OpenSSL man pages. For background
+  information and recommendations see e.g.
+  (https://wiki.mozilla.org/Security/Server_Side_TLS) and
+  (https://mozilla.github.io/server-side-tls/ssl-config-generator/).
+  For TLSv1.3 cipher configuration, please check the
+  "ssl-default-server-ciphersuites" keyword. Please check the "server" keyword
+  for more information.
 
 ssl-default-server-ciphersuites <ciphersuites>
   This setting is only available when support for OpenSSL was built in and
@@ -1071,9 +1075,10 @@ ssl-default-server-ciphersuites <ciphersuites>
   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" under the "ciphersuites" section. For cipher configuration for
-  TLSv1.2 and earlier, please check the "ssl-default-server-ciphers" keyword.
-  Please check the "server" keyword for more information.
+  "man 1 ciphers" from OpenSSL man pages under the section "ciphersuites". For
+  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
@@ -10894,10 +10899,7 @@ ciphers <ciphers>
   This setting is only available when support for OpenSSL was built in. It sets
   the string describing the list of cipher algorithms ("cipher suite") that are
   negotiated during the SSL/TLS handshake up to TLSv1.2. The format of the
-  string is defined in "man 1 ciphers" from OpenSSL man pages, and can be for
-  instance a string such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without
-  quotes). Depending on the compatibility and security requirements, the list
-  of suitable ciphers depends on a variety of variables. For background
+  string is defined in "man 1 ciphers" from OpenSSL man pages. For background
   information and recommendations see e.g.
   (https://wiki.mozilla.org/Security/Server_Side_TLS) and
   (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
@@ -10908,11 +10910,8 @@ ciphersuites <ciphersuites>
   OpenSSL 1.1.1 or later was used to build HAProxy. It sets the string describing
   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, and can be for instance a
-  string such as
-  "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"
-  (without quotes). For cipher configuration for TLSv1.2 and earlier, please check
-  the "ciphers" keyword.
+  OpenSSL man pages under the "ciphersuites" section. For cipher configuration
+  for TLSv1.2 and earlier, please check the "ciphers" keyword.
 
 crl-file <crlfile>
   This setting is only available when support for OpenSSL was built in. It
@@ -11661,19 +11660,20 @@ ciphers <ciphers>
   This setting is only available when support for OpenSSL was built in. This
   option sets the string describing the list of cipher algorithms that is
   negotiated during the SSL/TLS handshake with the server. The format of the
-  string is defined in "man 1 ciphers". When SSL is used to communicate with
-  servers on the local network, it is common to see a weaker set of algorithms
-  than what is used over the internet. Doing so reduces CPU usage on both the
-  server and haproxy while still keeping it compatible with deployed software.
-  Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
-  is needed and just connectivity, using DES can be appropriate.
+  string is defined in "man 1 ciphers" from OpenSSL man pages. For background
+  information and recommendations see e.g.
+  (https://wiki.mozilla.org/Security/Server_Side_TLS) and
+  (https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
+  cipher configuration, please check the "ciphersuites" keyword.
 
 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 that is negotiated during the TLS
   1.3 handshake with the server. The format of the string is defined in
-  "man 1 ciphers" under the "ciphersuites" section.
+  "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