From 25407965fdf607f98dd7d134aad0d3d79e16cde0 Mon Sep 17 00:00:00 2001 From: William Dauchy Date: Sat, 26 Sep 2020 13:35:52 +0200 Subject: [PATCH] DOC: crt: advise to move away from cert bundle especially when starting to use `new ssl cert` runtime API, it might become a bit confusing for users to mix bundle and single cert, especially when it comes to use the commit command: e.g.: - start the process with `crt` loading a bundle - use `set ssl cert my_cert.pem.ecdsa`: API detects it as a replacement of a bundle. - `commit` has to be done on the bundle: `commit ssl cert my_cert.pem` however: - add a new cert: `new ssl cert my_cert.pem.rsa`: added as a single certificate - `commit` has to be done on the certificate: `commit ssl cert my_cert.pem.rsa` this should resolve github issue #872 this should probably be backported in >= v2.2 in order to encourage people to move away from bundle certificates loading. Signed-off-by: William Dauchy --- doc/configuration.txt | 7 ++++++- doc/management.txt | 4 ++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/doc/configuration.txt b/doc/configuration.txt index 97ff2e499..87f35e984 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -12560,10 +12560,15 @@ crt 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 - support it. + supports it. If a directory name is given as the 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 diff --git a/doc/management.txt b/doc/management.txt index adbad95d3..42e8ddbca 100644 --- a/doc/management.txt +++ b/doc/management.txt @@ -1725,6 +1725,10 @@ new ssl cert 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