Repository navigation
Verify client certificates (mTLS) with :client-auth and :client-ca-file - #70
Merged
Merged
Conversation
: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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
:tlscan 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.:client-ca-fileis a PEM file of the CAs a client certificate must chain to. It goes toSSL_CTX_load_verify_locations, and its names go out in the CertificateRequest throughSSL_load_client_CA_fileandSSL_CTX_set_client_CA_list.:client-auth :needfails the handshake without a certificate that verifies.:wantasks 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.:client-auth(or withnilorfalse) nothing changes. A session id context is set once peers are verified, because OpenSSL won't resume a session without one. I checked that withopenssl s_client -sess_out/-sess_in: TLS 1.2 and 1.3 both resume, and the cert is still on the request.:ssl-client-cert, ajava.security.cert.X509Certificatefrom jolt-crypto (already a dependency, loaded only when:client-authis set). It's on every request of the connection and on a websocket session's:request. Without one the key is absent.:client-ca-filewithout:client-authis 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 atrun-serverwith a message naming the problem.:client-authneeds OpenSSL 3 (SSL_get1_peer_certificate) and is refused on 1.1. It doesn't fall back toSSL_get_peer_certificate, because on macOS that name also resolves to the process's LibreSSL.X509Certificatecloses the connection and is recorded as a:tls-peer-certfault inserver-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:
:needand:wantwith a trusted cert, no cert, and an untrusted cert, with the server still serving afterwards;:client-authis off;:tls-peer-certfault;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 onmainon this machine, because another program holds its fixed port 8631.Closes #71.