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

@@ -17267,8 +17267,33 @@ crt-list <file>
 
         <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...]
 
-  sslbindconf supports the following keywords from the bind line
+  Empty lines as well as lines beginning with a hash ('#') will be ignored.
-  (see Section 5.1. Bind options):
+
+  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).
+
+  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.
+
+  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 <crtfile> 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 <crtfile>. HAProxy
+    will duplicate the crt-list line internally, adding an algorithm extension
+    (.rsa, .ecdsa, .dsa) when loading the file.
+
+  sslbindconf:
+
+     <sslbindconf> supports the following keywords from the bind line (see
+     Section 5.1. Bind options):
 
      - allow-0rtt
      - alpn
@@ -17288,7 +17313,7 @@ crt-list <file>
      - ssl-max-ver
      - verify
 
-  sslbindconf also supports the following keywords from the crt-store load
+     <sslbindconf> also supports the following keywords from the crt-store load
      keyword (see Section 3.12.1. Load options):
 
      - crt
@@ -17298,50 +17323,58 @@ crt-list <file>
      - sctl
      - ocsp-update
 
-  It overrides the configuration set in bind line for the certificate.
+    Parameters from the bind line are inherited in <sslbindconf>, if none were
+    specified, the default options are inherited, the parameters specified in
+    <sslbindconf> overwrite those inherited settings.
 
-  Wildcards are supported in the SNI filter. Negative filter are also supported,
+  snifilter:
-  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,
+    When the <snifilter> parameter is used on a crt-list line, the CN and SAN
-  as long as only the base name is given in the crt-list. SNI filter will do
+    are not used anymore to select the certificate on this line during the
-  the same work on all bundled certificates.
+    handshake but the <snifilter> is used instead.
 
-  Empty lines as well as lines beginning with a hash ('#') will be ignored.
+    <snifilter> 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 first declared certificate of a bind line is used as the default
+    The certificates will be presented to clients who provide a valid TLS
-  certificate, either from crt or crt-list option, which HAProxy should use in
+    Server Name Indication field matching one of the SNI filters, or the CN and
-  the TLS handshake if no other certificate matches. This certificate will also
+    SAN of a <crtfile>. The matching algorithm first looks for a positive domain
-  be used if the provided SNI matches its CN or SAN, even if a matching SNI
+    entry in the list, if not found it will try to look for a wildcard in the
-  filter is found on any crt-list. The SNI filter !* can be used after the first
+    list. If a wilcard match, haproxy checks for a negative filter from the
-  declared certificate to not include its CN and SAN in the SNI tree, so it will
+    same line and unmatch if necessary. In case of multiple key algorithms
-  never match except if no other certificate matches. This way the first
+    (RSA,ECDSA,DSA), HAProxy will try to match one certificate per type and
-  declared certificate act as a fallback. It is also possible to declare a '*'
+    chose the right one depending on what is supported by the client.
-  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.
 
-  When no ALPN is set, the "bind" line's default one is used. If a "bind" line
+    If no SNI is presented by the client or if no certificate matched, this
-  has no "no-alpn", "alpn" nor "npn" set, a default value will be used
+    will fallback to one of the default certificate. To disable the default
-  depending on the protocol (see "alpn" above). However if the "bind" line has
+    certificate fallback, the 'strict-sni' option may be used.
-  a different default, or explicitly disables ALPN using "no-alpn", it is
+    When multiple default certificates are defined, HAProxy is able to chose
-  possible to force a specific value for a certificate.
+    the right ECDSA or RSA one depending on what the client supports.
 
-  crt-list file example:
+    The first declared certificate of a bind line is used as a default
-        cert1.pem !*
+    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
+        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
-        default.pem.rsa *
-        default.pem.ecdsa *
         foo.crt [key bar.pem ocsp foo.ocsp ocsp-update on] foo.bar.com
 
 default-crt <cert>