docs(tls): document multi-source cipher/SECLEVEL resolution per listener#598
docs(tls): document multi-source cipher/SECLEVEL resolution per listener#598heskew wants to merge 1 commit into
Conversation
Documents HarperFast/harper#1841 (5.2.0): every configured ciphers source is honored — composed as suites-from-highest-priority-source plus the minimum explicit @SECLEVEL — with CA entries scoped to mTLS-verifying listeners, operationsApi.tls precedence, composition warnings, and the restart-required caveat for post-boot changes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-598 This preview will update automatically when you push new commits. |
|
|
||
| <VersionBadge type="changed" version="v5.2.0" /> — every configured `ciphers` source is now honored; previously only `tls.ciphers` (or the first array entry's) took effect and all others were silently ignored. | ||
|
|
||
| A TLS listener has a single effective cipher string: OpenSSL applies the cipher list — and any `@SECLEVEL` command in it, which governs client-certificate chain verification — from the configuration the listener was created with. A per-certificate value cannot take effect on its own, so Harper resolves one effective string per listener from every configured source: |
There was a problem hiding this comment.
@SECLEVEL is broader than client-certificate chain verification: OpenSSL applies the level to cipher algorithms, curves, signature algorithms, DH sizes, and certificate key/signature strength for the whole listener. Could we say that here and explicitly warn that selecting the minimum level downgrades every connection on this listener? Otherwise the CA-scoped source rule reads like a CA-scoped relaxation.
| ciphers: DEFAULT@SECLEVEL=0 | ||
| ``` | ||
|
|
||
| resolves to `HIGH:!aNULL@SECLEVEL=0` — the configured suites are preserved while the relaxed security level lets the legacy chains (for example SHA-1-signed client CAs, which otherwise fail verification on modern OpenSSL) verify. |
There was a problem hiding this comment.
Could we replace "SHA-1-signed client CAs" with something like "client certificate chains containing SHA-1 signatures (for example, on a leaf or intermediate certificate)"? OpenSSL does not enforce a directly trusted root's own signature algorithm, and the core integration fixture also signs the leaf client certificate with SHA-1. As written, someone with only a SHA-1-self-signed root may unnecessarily set SECLEVEL=0.
|
|
||
| ## Cipher Suites and Security Level | ||
|
|
||
| <VersionBadge type="changed" version="v5.2.0" /> — every configured `ciphers` source is now honored; previously only `tls.ciphers` (or the first array entry's) took effect and all others were silently ignored. |
There was a problem hiding this comment.
The core change deliberately does not apply effective-cipher/@SECLEVEL resolution on the Bun/BoringSSL server path, and its integration test skips Bun. Could we scope "every configured source is now honored" to Node.js/OpenSSL and state the Bun exception? Also, repository convention asks for the <VersionBadge> on its own line with this explanation in a separate paragraph.
|
|
||
| A TLS listener has a single effective cipher string: OpenSSL applies the cipher list — and any `@SECLEVEL` command in it, which governs client-certificate chain verification — from the configuration the listener was created with. A per-certificate value cannot take effect on its own, so Harper resolves one effective string per listener from every configured source: | ||
|
|
||
| - The listener's own `tls` section, in priority order: `operationsApi.tls` for the Operations API listener, then the root `tls` section (an object's `ciphers` directly; an array's entries individually). |
There was a problem hiding this comment.
The implementation relevance-filters tls[] entries by uses (and includes CA entries only for mTLS); it does not consume every array entry for every listener. Could this say "relevant array entries" and state that the no-uses / legacy https / matching-listener rules apply here too? Otherwise an Operations-API-only entry can look like it should alter the application listener.
2 participants
Summary
Documents the composed per-listener cipher resolution shipped in HarperFast/harper#1841 (v5.2.0, closes harper#1840):
tls.ciphersfield description updated: the value may live at the top level, ontls[]entries, or on certificate records, and is composed per listener.reference/http/tls.md: source priority (operationsApi.tls> roottls> certificate records), relevance rules (CA entries only for mTLS-verifying listeners;usesmatching incl. legacyhttps/no-usesgenerics), suite-preserving@SECLEVELcomposition with a worked legacy-client-CA example, composition warnings, and the restart-required caveat for post-boot changes.<VersionBadge type="changed" version="v5.2.0" />.Where to look
HIGH:!aNULL+ CADEFAULT@SECLEVEL=0toHIGH:!aNULL@SECLEVEL=0— matches the resolver's unit tests in core.🤖 Generated with Claude Code (Claude Fable 5)