Verify the server certificate chain in the application

[ydnar]

Motivation

Authenticating the server's certificate is part of the QUIC TLS 1.3 handshake (RFC 9001 § 4), which QUIC drives directly rather than over the record layer. Built-in verification — the chain checked against TLSConfiguration.certificateVerification, plus the serverHostname name check (#109) — covers the common case. Some clients need the trust decision themselves: certificate pinning, a custom trust store, or validation that consults an external service such as an OCSP responder.

Such validation is network-bound and may suspend, while the QUIC connection core is sans-I/O and synchronous. The decision therefore belongs at the connection's edge, on the event loop, with the core pausing the handshake until a verdict arrives. The fork's NIOSSLQUICHandshake gained that pause as a sans-I/O two-step (alta/swift-nio-ssl#16): it parks at .wantsCertificateVerify carrying the peer chain and resumes on resumeVerification. This PR builds the QUIC consumer on top of it, the design settled in alta/swift-nio-ssl#13.

Modifications

QUICConfiguration gains verifyTLS, an optional @Sendable (QUICHandshakeContext) async throws -> NIOSSLVerificationResult. When set, it replaces the built-in trust and hostname checks — the application owns both — and opts the client handshake into the fork's custom verification. The QUICHandshakeContext is an immutable snapshot of what the handshake has settled when the certificate is ruled on: the peer chain, the serverHostname dialed, the negotiated protocol and cipher suite, and the peer address — modeled on Go's VerifyConnection(ConnectionState), deliberately a value rather than the live QUICConnection.

The pause threads through three layers. TLSHandshake propagates the opt-in, maps the fork's .wantsCertificateVerify into its own State, and forwards the verdict; it also splits CRYPTO reassembly from advancing (provideCryptoFrame), so a flight re-sent while paused buffers without re-driving the handshake. ConnectionCore parks on the chain — surfaced once by takeCertificateVerificationRequest — and resumes on the verdict via resumeCertificateVerification, which on .failed fails the handshake with the certificate alert (CRYPTO_ERROR, § 4.8); while paused it buffers received CRYPTO and keeps ACKing, with no new timer, so a verdict that never comes lets the connection idle out. TransportHandler assembles the QUICHandshakeContext, runs the verifier in a detached Task off the loop, and hops the verdict back through a NIOLoopBound to resume and flush; the Task is cancelled on teardown.

A verifier that throws (a check that could not complete) currently fails the handshake the same as a .failed verdict — the connection closes and the dial surfaces handshakeFailed. Splitting that into an INTERNAL_ERROR close, distinct from the certificate alert a rejection raises, is a small follow-up left out here to keep the change focused; flag it if it should land in this PR.

The mTLS direction — a server custom-verifying the client's certificate — is a separate follow-up (it needs a fork change to install custom verify on the server arm); the decisions are recorded on alta/swift-nio-ssl#13.

Validation: sans-I/O ConnectionCore tests drive a paused handshake to completion on a .certificateVerified verdict (asserting the verifier saw the server's leaf certificate, against an untrusted, name-mismatched server) and to a CRYPTO_ERROR close on .failed; loopback tests over real sockets prove the async path end to end — a verifier approving an otherwise-untrusted chain completes the dial (asserting the handed-in context carried the dialed name, the chain, and the negotiated ALPN), and a verifier rejecting it over a built-in .none policy fails the dial.

Result

A QUIC client can verify the server's certificate chain in the application, given an immutable QUICHandshakeContext, replacing the built-in trust and name checks (RFC 9001 § 4). The post-ClientHello transport-parameter selection remains the last piece of the § 4 handshake-driver row.

Tasks

• QUICConfiguration.verifyTLS async hook taking a QUICHandshakeContext
• TLSHandshake state, opt-in, resume, and the provide/advance split
• ConnectionCore park/resume (takeCertificateVerificationRequest / resumeCertificateVerification)
• TransportHandler off-loop Task bridge with the verdict hop back
• Sans-I/O accept + reject tests; loopback accept + reject tests
• TRACEABILITY.md § 4 row updated
• swift-nio-ssl dependency repointed to main once Verify the peer certificate chain in the application swift-nio-ssl#16 landed
• Issue Roadmap & progress tracker #1 M3 item reconciled at merge

🤖 Generated with Claude Code

[ydnar]

How does the caller implementing certificate verification get visibility into the connection metadata?

[ydnar]

Addressed in 2a314e0. The verifier now receives a QUICHandshakeContext rather than the bare chain — an immutable snapshot of what the handshake has settled by the point the certificate is ruled on: the peer chain, the serverHostname dialed (the name it validates against, since under a custom verifier it owns the hostname check), the negotiated protocol and cipher suite, and the peer address. This follows Go, where VerifyConnection(ConnectionState) hands the verifier a state snapshot (ServerName, NegotiatedProtocol, PeerCertificates, …) rather than the live connection.

It's a value, deliberately not the live QUICConnection: that handle is mutable (close, migrate, open streams), its cached facts aren't populated until the handshake completes (so negotiatedProtocol would read stale mid-handshake, where the core reads live), and it doesn't exist on the accept path — so a snapshot generalizes to the deferred mTLS direction too. The struct is Sendable and easy to extend (a …WithMetadata-style addition later, if wanted).

---

Generated by Claude Code

[ydnar]

I think this should be called verifyTLS.