DOC: ssl: new "cert bundle" behavior
Update the documentation with the new bundle behavior which does not use
the same OpenSSL certificate store anymore but loads the PEM separately
as multiple "crt" were specified.
It should fix issue #872.
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 3ecca85..b01129f 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -1391,14 +1391,40 @@
bundles, sctl, ocsp, issuer, key.
"bundle": When a file specified in the configuration does not exist, HAProxy
- will try to load a certificate bundle. This is done by looking for
- <basename>.rsa, .ecdsa and .dsa.
- The multi-certificates bundles were introduced with OpenSSL 1.0.2 and were
- the only way back then to serve an ECDSA certificate and a RSA one with the
- same SNI. Since HAProxy 2.3 it does not use the OpenSSL bundle but it
- loads every certificates separately to emulate this behavior. At least
- OpenSSL 1.1.1 is required. It is recommended to specify all the certificates
- in the configuration instead of using the bundle feature.
+ will try to load a "cert bundle".
+
+ Starting from HAProxy 2.3, the bundles are not loaded in the same OpenSSL
+ certificate store, instead it will loads each certificate in a separate
+ store which is equivalent to declaring multiple "crt". OpenSSL 1.1.1 is
+ required to achieve this. Which means that bundles are now used only for
+ backward compatibility and are not mandatory anymore to do an hybrid RSA/ECC
+ bind configuration..
+
+ 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 as if they were configured
+ separately in several "crt".
+
+ The bundle loading does not have an impact anymore on the directory loading
+ since files are loading separately.
+
+ On the CLI, bundles are seen as separate files, and the bundle extension is
+ required to commit them.
+
+ OSCP files (.ocsp), issuer files (.issuer), Certificate Transparency (.sctl)
+ as well as private keys (.key) are supported with multi-cert bundling.
"sctl": Try to load "<basename>.sctl" for each crt keyword.
@@ -12531,61 +12557,9 @@
that support EC certificates to be able to use EC ciphers, while
simultaneously supporting older, RSA only clients.
- In order to provide this feature, multiple PEM files, each with a different
- key type, are required. Since HAProxy 2.3, at least OpenSSL 1.1.1 is
- required to use this feature. It can be configured by adding each file in
- the configuration, which is the recommended way, or by using a "cert
- bundle".
-
- 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. With BoringSSL and Openssl >= 1.1.1 multi-cert is natively supported,
- no need to bundle certificates. ECDSA certificate will be preferred if client
- supports it.
-
- If a directory name is given as the <cert> argument, haproxy will
- automatically search and load bundled files in that directory.
- It is however recommended to move away from bundle loading, especially if you
- want to use the runtime API to load new certificate which does not support
- bundle. A recommended way to migrate is to set `ssl-load-extra-file`
- parameter to `none` in global config so that each certificate is loaded as a
- single one.
-
- 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.
+ To achieve this, OpenSSL 1.1.1 is required, you can configure this behavior
+ by providing one crt entry per certificate type, or by configuring a "cert
+ bundle" like it was required before HAProxy 1.8. See "ssl-load-extra-files".
crt-ignore-err <errors>
This setting is only available when support for OpenSSL was built in. Sets a
@@ -12615,11 +12589,9 @@
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 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. With BoringSSL and Openssl >= 1.1.1 multi-cert is
- natively supported, avoid multi-cert bundling. RSA and ECDSA certificates can
- be declared in a row, and set different ssl and filter parameter.
+ 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.
diff --git a/doc/management.txt b/doc/management.txt
index 42e8ddb..adbad95 100644
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -1725,10 +1725,6 @@
Create a new empty SSL certificate store to be filled with a certificate and
added to a directory or a crt-list. This command should be used in
combination with "set ssl cert" and "add ssl crt-list".
- Note that bundle certificates are not supported; it is recommended to use
- `ssl-load-extra-file none` in global config to avoid loading certificates as
- bundle and then mixing with single certificates in the runtime API. This will
- avoid confusion, especailly when it comes to the `commit` command.
prompt
Toggle the prompt at the beginning of the line and enter or leave interactive