From e51fab0a4aba977b111c9d0926d6adbaf62204a1 Mon Sep 17 00:00:00 2001 From: Joao Morais Date: Sat, 21 Nov 2020 07:42:20 -0300 Subject: [PATCH] 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. --- doc/configuration.txt | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/configuration.txt b/doc/configuration.txt index d97931448..9dbe43208 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -12596,10 +12596,11 @@ crt-list 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 @@ crt-list 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