DOC: config: clarify the fact that SNI should not be used in HTTP scenarios
As reported by Tim in issue #1373 some warnings are deserved to explain
why using the frontend SNI for routing or connecting to a server is
usually not correct, especially since it can be tempting and used to
make sense in pure TCP scenarios.
(cherry picked from commit d26fb57e817da6cb587c0b61baf60a011e756c49)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
(cherry picked from commit 0b41d6be9bf7d8a091ddcb8a6630ff747f63ee87)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
(cherry picked from commit 2dc31601680f934f18dd6b3575ae33612299f39a)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 45b2e66..d514033 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -15011,8 +15011,10 @@
The "sni" parameter evaluates the sample fetch expression, converts it to a
string and uses the result as the host name sent in the SNI TLS extension to
the server. A typical use case is to send the SNI received from the client in
- a bridged HTTPS scenario, using the "ssl_fc_sni" sample fetch for the
- expression, though alternatives such as req.hdr(host) can also make sense. If
+ a bridged TCP/SSL scenario, using the "ssl_fc_sni" sample fetch for the
+ expression. THIS MUST NOT BE USED FOR HTTPS, where req.hdr(host) should be
+ used instead, since SNI in HTTPS must always match the Host field and clients
+ are allowed to use different host names over the same connection). If
"verify required" is set (which is the recommended setting), the resulting
name will also be matched against the server certificate's names. See the
"verify" directive for more details. If you want to set a SNI for health
@@ -18885,6 +18887,16 @@
requires that the SSL library is built with support for TLS extensions
enabled (check haproxy -vv).
+ CAUTION! Except under very specific conditions, it is normally not correct to
+ use this field as a substitute for the HTTP "Host" header field. For example,
+ when forwarding an HTTPS connection to a server, the SNI field must be set
+ from the HTTP Host header field using "req.hdr(host)" and not from the front
+ SNI value. The reason is that SNI is solely used to select the certificate
+ the server side will present, and that clients are then allowed to send
+ requests with different Host values as long as they match the names in the
+ certificate. As such, "ssl_fc_sni" should normally not be used as an argument
+ to the "sni" server keyword, unless the backend works in TCP mode.
+
ACL derivatives :
ssl_fc_sni_end : suffix match
ssl_fc_sni_reg : regex match