From 0436062f487b45e009a2752b2eb83d6326b2fdbf Mon Sep 17 00:00:00 2001 From: William Lallemand Date: Wed, 29 Oct 2025 17:09:37 +0100 Subject: [PATCH] DOC: management: document ECH CLI commands Document "show ssl ech", "add ssl ech", "set ssl ech" and "del ssl ech" --- doc/management.txt | 113 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) diff --git a/doc/management.txt b/doc/management.txt index e98a4a961..a7485d657 100644 --- a/doc/management.txt +++ b/doc/management.txt @@ -1834,6 +1834,28 @@ add ssl crt-list $ echo -e 'add ssl crt-list certlist1 <<\nfoobar.pem [allow-0rtt] foo.bar.com !test1.com\n' | socat /tmp/sock1 - +add ssl ech + Add an ECH key to a line. The payload must be in the PEM for ECH format. + (https://datatracker.ietf.org/doc/html/draft-farrell-tls-pemesni) + + The bind line format is /@: (Example: + frontend1/@haproxy.conf:19) or / if the bind line was named + with the "name" keyword. + + Necessitates an OpenSSL version that supports ECH, and HAProxy must be + compiled with USE_ECH=1. This command is only supported on a CLI connection + running in experimental mode (see "experimental-mode on"). + + See also "show ssl ech" and "ech" in the Section 5.1 of the configuration + manual. + + Example: + + $ openssl ech -public_name foobar.com -out foobar3.com.ech + $ echo -e "experimental-mode on; add ssl ech frontend1/@haproxy.conf:19 <<%EOF%\n$(cat foobar3.com.ech)\n%EOF%\n" | \ + socat /tmp/haproxy.sock - + added a new ECH config to frontend1 + add ssl jwt Add an already loaded certificate to the list of certificates that can be used for JWT validation (see "jwt_verify_cert" converter). This command does @@ -2110,6 +2132,25 @@ del ssl crt-list you will need to provide which line you want to delete. To display the line numbers, use "show ssl crt-list -n ". +det ssl ech + Delete the ECH keys of a bind line. + + The bind line format is /@: (Example: + frontend1/@haproxy.conf:19) or / if the bind line was named + with the "name" keyword. + + Necessitates an OpenSSL version that supports ECH, and HAProxy must be + compiled with USE_ECH=1. This command is only supported on a CLI connection + running in experimental mode (see "experimental-mode on"). + + See also "show ssl ech", "add ssl ech" and "ech" in the Section 5.1 of the + configuration manual. + + Example: + + $ echo "experimental-mode on; del ssl ech frontend1/@haproxy.conf:19" | socat /tmp/haproxy.sock - + deleted all ECH configs from frontend1/@haproxy.conf:19 + del ssl jwt Remove an already loaded certificate to the list of certificates that can be used for JWT validation (see "jwt_verify_cert" converter). This command does @@ -2658,6 +2699,28 @@ set ssl crl-file socat /var/run/haproxy.stat - echo "commit ssl crl-file crlfile.pem" | socat /var/run/haproxy.stat - +set ssl ech + Replace the ECH keys of a bind line with this one. The payload must be in the + PEM for ECH format. + (https://datatracker.ietf.org/doc/html/draft-farrell-tls-pemesni) + + The bind line format is /@: (Example: + frontend1/@haproxy.conf:19) or / if the bind line was named + with the "name" keyword. + + Necessitates an OpenSSL version that supports ECH, and HAProxy must be + compiled with USE_ECH=1. This command is only supported on a CLI connection + running in experimental mode (see "experimental-mode on"). + + See also "show ssl ech", "add ssl ech" and "ech" in the Section 5.1 of the + configuration manual. + + $ openssl ech -public_name foobar.com -out foobar3.com.ech + $ echo -e "experimental-mode on; + set ssl ech frontend1/@haproxy.conf:19 <<%EOF%\n$(cat foobar3.com.ech)\n%EOF%\n" | \ + socat /tmp/haproxy.sock - + set new ECH configs for frontend1/@haproxy.conf:19 + set ssl ocsp-response This command is used to update an OCSP Response for a certificate (see "crt" on "bind" lines). Same controls are performed as during the initial loading of @@ -3793,6 +3856,56 @@ show ssl crt-list [-n] [] ecdsa.pem:3 [verify none allow-0rtt ssl-min-ver TLSv1.0 ssl-max-ver TLSv1.3] localhost !www.test1.com ecdsa.pem:4 [verify none allow-0rtt ssl-min-ver TLSv1.0 ssl-max-ver TLSv1.3] +show ssl ech [] + Display the list of ECH keys loaded in the HAProxy process. + + When is specified, displays the keys for a specific bind line. The + bind line format is /@: (Example: + frontend1/@haproxy.conf:19) or / if the bind line was named + with the "name" keyword. + + The 'age' entry represents the time, in seconds, since the key was loaded in + the bind line. This value is reset when HAProxy is started, reloaded, or + restarted. + + Necessitates an OpenSSL version that supports ECH, and HAProxy must be + compiled with USE_ECH=1. + This command is only supported on a CLI connection running in experimental + mode (see "experimental-mode on"). + + See also "ech" in the Section 5.1 of the configuration manual. + + Example: + + $ echo "experimental-mode on; show ssl ech" | socat /tmp/haproxy.sock - + *** + frontend: frontend1 + + bind: frontend1/@haproxy.conf:19 + + ECH entry: 0 public_name: example.com age: 557 (has private key) + [fe0d,94,example.com,[0020,0001,0001],c39285b774bf61c071864181c5292a012b30adaf767e39369a566af05573ef2b,00,00] + + ECH entry: 1 public_name: example.com age: 557 (has private key) + [fe0d,ee,example.com,[0020,0001,0001],6572191131b5cabba819f8cacf2d2e06fa0b87b30d9b793644daba7b8866d511,00,00] + + bind: frontend1/@haproxy.conf:20 + + ECH entry: 0 public_name: example.com age: 557 (has private key) + [fe0d,94,example.com,[0020,0001,0001],c39285b774bf61c071864181c5292a012b30adaf767e39369a566af05573ef2b,00,00] + + ECH entry: 1 public_name: example.com age: 557 (has private key) + [fe0d,ee,example.com,[0020,0001,0001],6572191131b5cabba819f8cacf2d2e06fa0b87b30d9b793644daba7b8866d511,00,00] + + $ echo "experimental-mode on; show ssl ech frontend1/@haproxy.conf:19" | socat /tmp/haproxy.sock - + *** + ECH for frontend1/@haproxy.conf:19 + ECH entry: 0 public_name: example.com age: 786 (has private key) + [fe0d,94,example.com,[0020,0001,0001],c39285b774bf61c071864181c5292a012b30adaf767e39369a566af05573ef2b,00,00] + + ECH entry: 1 public_name: example.com age: 786 (has private key) + [fe0d,ee,example.com,[0020,0001,0001],6572191131b5cabba819f8cacf2d2e06fa0b87b30d9b793644daba7b8866d511,00,00] + show ssl jwt Display the list of certificates that can be used for JWT validation. See also "add ssl jwt" and "del ssl jwt" commands.