From 03e250886fe68ca947a7f9be14545f5b248e5a75 Mon Sep 17 00:00:00 2001 From: yanbzhu Date: Mon, 14 Dec 2015 15:10:25 -0500 Subject: [PATCH 6/6] DOC: ssl: Adding docs for Multi-Cert bundling Added entries in crt and crt-list to document multi-cert bundling. --- doc/configuration.txt | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/doc/configuration.txt b/doc/configuration.txt index e06e01d..b4d603a 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -9649,6 +9649,56 @@ crt Transparency (RFC6962) TLS extension is enabled. The file must contain a valid Signed Certificate Timestamp List, as described in RFC. File is parsed to check basic syntax, but no signatures are verified. + + There are cases where it is desirable support multiple key types (RSA/ECDSA) + in the cipher suites offered to the clients. This allows clients that support + EC certificates to be able to use EC ciphers, while simultaneously supporting + older, RSA only clients. + + In order to provide this functionality, multiple PEM files, each with a + different key type, are required. To associate these PEM files into a + "cert bundle" that is recognized by haproxy, they must be named in the + following way: All PEM files that are to be bundled must have the same base + name, with a suffix indicating the key type. Currently, three suffixes are + supported: rsa, dsa and ecdsa. For example, if www.example.com has two PEM + files, an RSA file and an ECDSA file, they must be named: "example.pem.rsa" + and "example.pem.ecdsa". The first part of the filename is arbitrary; only the + suffix matters. To load this bundle into haproxy, specify the base name only: + + Example : bind :8443 ssl crt example.pem + + Note that the suffix is not given to haproxy, this tells haproxy to look for + a cert bundle. + + Haproxy will load all PEM files in the bundle at the same time to try to + support multiple key types. PEM files are combined based on Common Name + (CN) and Subject Alternative Name (SAN) to support SNI lookups. This means + that even if you give haproxy a cert bundle, if there are no shared CN/SAN + entries in the certificates in that bundle, haproxy will not be able to + provide multi-cert support. + + Assuming bundle in the example above contained the following: + + Filename | CN | SAN + -------------------+-----------------+------------------- + example.pem.rsa | www.example.com | rsa.example.com + -------------------+-----------------+--+---------------- + example.pem.ecdsa | www.example.com | ecdsa.example.com + -------------------+-----------------+------------------- + + + Users connecting with an SNI of "www.example.com" will be able + to use both RSA and ECDSA cipher suites. Users connecting with an SNI of + "rsa.example.com" will only be able to use RSA cipher suites, and users + connecting with "ecdsa.example.com" will only be able to use ECDSA cipher + suites. + + If a directory name is given as the argument, haproxy will + automatically search and load bundled files in that directory. + + OSCP files (.ocsp) and issuer files (.issuer) are supported with multi-cert + bundling. Each certificate can have its own .ocsp and .issuer file. At this + time, sctl is not supported in multi-certificate bundling. crt-ignore-err This setting is only available when support for OpenSSL was built in. Sets a @@ -9671,6 +9721,10 @@ crt-list 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 "crt") is support with crt-list, as long as only the + base name is given in the crt-list. Due to the nature of bundling, all SNI + filters given to a multi-cert bundle entry are ignored. defer-accept Is an optional keyword which is supported only on certain Linux kernels. It -- 2.5.3