DOC: clarify how to create a fallback crt
HAProxy uses CN and SAN of the certificates to match incoming SNI, and
use the matching certificate in the TLS handshake. `crt-list` goes
further and allows to configure SNI filters to explicitly define the
FQDNs that should match a certificate.
The first declared certificate of the `crt-list` option follows the same
rules, and it's also used as a fallback - the certificate that should be
used if SNI isn't provided or the provided one cannot match any
certificate or SNI filter. If a provided SNI matches the CN or SAN of
the first certificate, the first certificate would be used even if a
matching SNI filter is declared later.
This change clarifies this scenario and documents a filter that can be
used to convert the first declared certificate as a proper fallback.
Should be merged as far as the first SNI filter implementation.
diff --git a/doc/configuration.txt b/doc/configuration.txt
index d979314..9dbe432 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -12596,10 +12596,11 @@
configuration set in bind line for the certificate.
Wildcards are supported in the SNI filter. Negative filter are also supported,
- only useful in combination with a wildcard filter to exclude a particular SNI.
- The certificates will be presented to clients who provide a valid TLS Server
- Name Indication field matching one of the SNI filters. If no SNI filter is
- specified, the CN and alt subjects are used. This directive may be specified
+ useful in combination with a wildcard filter to exclude a particular SNI, or
+ after the first certificate to exclude a pattern from its CN or Subject Alt
+ Name (SAN). The certificates will be presented to clients who provide a valid
+ TLS Server Name Indication field matching one of the SNI filters. If no SNI
+ filter is specified, the CN and SAN are used. This directive may be specified
multiple times. See the "crt" option for more information. The default
certificate is still needed to meet OpenSSL expectations. If it is not used,
the 'strict-sni' option may be used.
@@ -12610,8 +12611,16 @@
Empty lines as well as lines beginning with a hash ('#') will be ignored.
+ The first valid line declares the default certificate, which haproxy should
+ use in the TLS handshake if no other certificate matches, just like the crt
+ bind option. This certificate will also be used if the provided SNI matches
+ its CN or SAN, even if a matching SNI filter is declared later. The SNI filter
+ !* can be used after the first certificate to not include its CN and SAN in
+ the SNI tree, so it will never match except if no other certificate matches.
+ This way the first declared certificate act as a fallback.
+
crt-list file example:
- cert1.pem
+ cert1.pem !*
# comment
cert2.pem [alpn h2,http/1.1]
certW.pem *.domain.tld !secure.domain.tld