From 038a372684e2230c0c4be3504a419562ab5743ed Mon Sep 17 00:00:00 2001 From: William Lallemand Date: Mon, 7 Apr 2025 19:11:11 +0200 Subject: [PATCH] DOC: configuration: rework the crt-list section The crt-list section was unclear, this patch reworks it, giving more details on the matching algorithms and how the things are loaded. --- doc/configuration.txt | 169 +++++++++++++++++++++++++----------------- 1 file changed, 101 insertions(+), 68 deletions(-) diff --git a/doc/configuration.txt b/doc/configuration.txt index f139f809c..e79f0f763 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -17267,81 +17267,114 @@ crt-list [\[ ...\]] [[!] ...] - sslbindconf supports the following keywords from the bind line - (see Section 5.1. Bind options): - - - allow-0rtt - - alpn - - ca-file - - ca-verify-file - - ciphers - - ciphersuites - - client-sigalgs - - crl-file - - curves - - ecdhe - - no-alpn - - no-ca-names - - npn - - sigalgs - - ssl-min-ver - - ssl-max-ver - - verify - - sslbindconf also supports the following keywords from the crt-store load - keyword (see Section 3.12.1. Load options): - - - crt - - key - - ocsp - - issuer - - sctl - - ocsp-update - - It overrides the configuration set in bind line for the certificate. - - Wildcards are supported in the SNI filter. Negative filter are also supported, - 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. - - Multi-cert bundling (see "ssl-load-extra-files") is supported with crt-list, - as long as only the base name is given in the crt-list. SNI filter will do - the same work on all bundled certificates. - Empty lines as well as lines beginning with a hash ('#') will be ignored. - The first declared certificate of a bind line is used as the default - certificate, either from crt or crt-list option, which HAProxy should use in - the TLS handshake if no other certificate matches. This certificate will also - be used if the provided SNI matches its CN or SAN, even if a matching SNI - filter is found on any crt-list. The SNI filter !* can be used after the first - declared 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. It is also possible to declare a '*' - filter, which will allow to chose this certificate as default. When multiple - default certificates are defined, HAProxy is able to chose the right ECDSA or - RSA one depending on what the client supports. + The crt-list can be manipulated dynamically over the stats socket. (See "add + ssl crt-list", "del ssl crt-list", "show ssl crt-list" in the management + guide). - When no ALPN is set, the "bind" line's default one is used. If a "bind" line - has no "no-alpn", "alpn" nor "npn" set, a default value will be used - depending on the protocol (see "alpn" above). However if the "bind" line has - a different default, or explicitly disables ALPN using "no-alpn", it is - possible to force a specific value for a certificate. + crt-list are usually dedicated files, however a directory loaded with the "crt" + directive is represented internally as a crt-list. The "ssl-f-use" directive + in a frontend also declares a crt-list linked to this frontend. - crt-list file example: - cert1.pem !* + crtfile: + + This is the filename of the certificate, or an identifier if it was declared + elsewhere (over the CLI or in a crt-store with an alias for example). + + It is possible to use the same on multiple lines with different + options and filters. + + Multi-cert bundling (see "ssl-load-extra-files") is supported in a + crt-list, as long as only the base name is given in . HAProxy + will duplicate the crt-list line internally, adding an algorithm extension + (.rsa, .ecdsa, .dsa) when loading the file. + + sslbindconf: + + supports the following keywords from the bind line (see + Section 5.1. Bind options): + + - allow-0rtt + - alpn + - ca-file + - ca-verify-file + - ciphers + - ciphersuites + - client-sigalgs + - crl-file + - curves + - ecdhe + - no-alpn + - no-ca-names + - npn + - sigalgs + - ssl-min-ver + - ssl-max-ver + - verify + + also supports the following keywords from the crt-store load + keyword (see Section 3.12.1. Load options): + + - crt + - key + - ocsp + - issuer + - sctl + - ocsp-update + + Parameters from the bind line are inherited in , if none were + specified, the default options are inherited, the parameters specified in + overwrite those inherited settings. + + snifilter: + + When the parameter is used on a crt-list line, the CN and SAN + are not used anymore to select the certificate on this line during the + handshake but the is used instead. + + is a list of entries separated by spaces. This list can contain + domains, or wildcards. The wildcards are in wildcard DNS format, using a + single asterisk as the first character of the entry. It is possible to + exclude a domain from a wildcard with a negative filter by specifying a '!' + in front of a single domain. Having a ! in front of a * is ignored. Having + negative filters without a wildcard on the same line is not supported as + well. The special entry '*' is used to specify default certificates, which + are used as fallback when no domain matched. + + The certificates will be presented to clients who provide a valid TLS + Server Name Indication field matching one of the SNI filters, or the CN and + SAN of a . The matching algorithm first looks for a positive domain + entry in the list, if not found it will try to look for a wildcard in the + list. If a wilcard match, haproxy checks for a negative filter from the + same line and unmatch if necessary. In case of multiple key algorithms + (RSA,ECDSA,DSA), HAProxy will try to match one certificate per type and + chose the right one depending on what is supported by the client. + + If no SNI is presented by the client or if no certificate matched, this + will fallback to one of the default certificate. To disable the default + certificate fallback, the 'strict-sni' option may be used. + When multiple default certificates are defined, HAProxy is able to chose + the right ECDSA or RSA one depending on what the client supports. + + The first declared certificate of a bind line is used as a default + certificate, either from crt or crt-list option. + It is also possible to declare a '*' filter, which will add this + certificate to the list of default certificates. To clarify the + configuration, the default certificates could be explicited (with a '*' + filter) at the beginning of the list, so an implicit default is not added + before. + + The "show ssl sni" command on the stats socket could be used to debug your + configuration. (See "show ssl sni" in the management guide) + + Example: # comment - cert2.pem [alpn h2,http/1.1] - certW.pem *.domain.tld !secure.domain.tld - certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld default.pem.rsa * default.pem.ecdsa * + cert2.pem [alpn h2,http/1.1] + certW.pem *.domain.tld !secure.domain.tld + certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld foo.crt [key bar.pem ocsp foo.ocsp ocsp-update on] foo.bar.com default-crt