Skip to content

Verify client certificates (mTLS) with :client-auth and :client-ca-file - #70

Merged
yogthos merged 2 commits into
mainfrom
feat/tls-client-auth
Nov 11, 2026
Merged

yogthos merged 2 commits into
mainfrom
feat/tls-client-auth

Conversation

@burinc

@burinc burinc commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

:tls can now verify client certificates (mTLS). Until now the README listed client certificates under "Not included", so a server that needed them couldn't use ring-chez.

(run-server handler {:port 8443
                     :tls {:cert-file "server.pem" :key-file "server-key.pem"
                           :client-ca-file "clients-ca.pem"
                           :client-auth :need}})
  • :client-ca-file is a PEM file of the CAs a client certificate must chain to. It goes to SSL_CTX_load_verify_locations, and its names go out in the CertificateRequest through SSL_load_client_CA_file and SSL_CTX_set_client_CA_list.
  • :client-auth :need fails the handshake without a certificate that verifies. :want asks for one and verifies it if sent, but lets a client without one through. A certificate that is sent and doesn't verify fails under both, as on the JVM.
  • Without :client-auth (or with nil or false) nothing changes. A session id context is set once peers are verified, because OpenSSL won't resume a session without one. I checked that with openssl s_client -sess_out/-sess_in: TLS 1.2 and 1.3 both resume, and the cert is still on the request.
  • A verified certificate reaches the handler as Ring's :ssl-client-cert, a java.security.cert.X509Certificate from jolt-crypto (already a dependency, loaded only when :client-auth is set). It's on every request of the connection and on a websocket session's :request. Without one the key is absent.
  • :client-ca-file without :client-auth is refused rather than read as :need. A trust store alone asks no client for anything, so that config would look protective and let everyone in. The other misconfigurations are refused at run-server with a message naming the problem.
  • :client-auth needs OpenSSL 3 (SSL_get1_peer_certificate) and is refused on 1.1. It doesn't fall back to SSL_get_peer_certificate, because on macOS that name also resolves to the process's LibreSSL.
  • A certificate that verified but can't be turned into an X509Certificate closes the connection and is recorded as a :tls-peer-cert fault in server-stats, so it doesn't vanish silently.

Revocation (CRLs, OCSP) isn't checked, and the README says so.

Tests make a small PKI with the openssl CLI: a trusted CA and client, plus a second CA and client the server doesn't know. They drive both strategies through http-client's TLS stream with a PKCS#12 key store:

  • :need and :want with a trusted cert, no cert, and an untrusted cert, with the server still serving afterwards;
  • an offered cert when :client-auth is off;
  • keep-alive;
  • websocket upgrade;
  • the :tls-peer-cert fault;
  • every refusal.

Suite on jolt v0.8.26 (macOS, OpenSSL 3.5.9): all new checks pass. The one failure, test-serves-only-own-conns-threads, fails the same way on main on this machine, because another program holds its fixed port 8631.

Closes #71.

:tls takes two more keys. :client-ca-file is a PEM file of the CAs a client
certificate must chain to, loaded with SSL_CTX_load_verify_locations, and its names
go out in the CertificateRequest through SSL_load_client_CA_file and
SSL_CTX_set_client_CA_list. :client-auth :need sets SSL_VERIFY_PEER |
SSL_VERIFY_FAIL_IF_NO_PEER_CERT, so a handshake without a good certificate fails;
:want sets SSL_VERIFY_PEER alone, so one is asked for and verified if sent. A
session id context is set too, since OpenSSL won't resume a session without one
once peers are verified. Without :client-auth nothing changes.

:client-ca-file without :client-auth is refused rather than read as :need. A trust
store on its own asks no client for anything, which is what Jetty and http-kit do
with one too, so a config that looks like it protects the server would quietly let
everyone in. Implying :need would be safer but surprising, and the error says which
key is missing either way. The other refusals name what is wrong in the existing
style: a :client-auth other than :need or :want, :client-auth without a CA file,
and a CA file that isn't a string, is missing, or that OpenSSL can't use.

After the handshake, a server that asked (SSL_CTX_get_verify_mode is non-zero)
reads the peer with SSL_get1_peer_certificate, checks SSL_get_verify_result, and
turns the i2d_X509 DER into a java.security.cert.X509Certificate through
jolt-crypto's CertificateFactory. tls/serve hands it to serve-conn alongside the io
as {:ssl-client-cert cert}, connection-loop merges that into conn-info, and the
request gets :ssl-client-cert only when there is one. Threads, fibers and websocket
sessions (whose :request is the same map) all go through that one path. jolt.crypto
is required only by make-context with :client-auth, so a plain or plain-TLS server
still doesn't load it, and only those servers touch the OpenSSL 3-only
SSL_get1_peer_certificate; on OpenSSL 1.1 :client-auth is refused instead.

Tests build a small PKI with the openssl CLI (a trusted CA and client, a second CA
and client the server doesn't know) and drive the server through http-client's TLS
stream with a PKCS#12 key store, on both strategies and over a websocket upgrade.
…-auth false as off

A certificate that verified but couldn't be read (SSL_get_verify_result, i2d_X509
or jolt-crypto's CertificateFactory failing) escaped tls/serve to a catch that drops
everything, so the client got a bare close and the operator nothing. serve now hands
the throwable to serve-conn, and the connection loop records it as a :tls-peer-cert
fault, printed and counted in server-stats like the server's other faults.

:client-auth false was refused as not :need or :want; a config layer may well write
false for off, so nil and false now both mean off.

Also: a failing (require 'jolt.crypto) is a :tls refusal rather than a bare require
error, the OpenSSL error queue is cleared before the CA file is read so last-error
names its trouble, and a test pins the certificate on every request of a kept-alive
connection, on both strategies.
@yogthos
yogthos merged commit 387cf67 into main Nov 11, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

:tls can't verify client certificates (no mTLS)

2 participants

⌂