quic: add TLS key log support (NSS Key Log Format)

[bellatoris]

Commit Message: quic: add TLS key log support so QUIC TLS secrets can be exported in NSS Key Log Format

Additional Description:

Summary

When debugging QUIC TLS behavior — session ticket resumption, certificate compression, or other handshake-level questions — the typical workflow is to open a packet capture in Wireshark and supply per-connection TLS secrets via a NSS Key Log file. Today this only works when the client can emit the key log itself via SSLKEYLOGFILE. Some client stacks — for example Apple's Network framework on macOS and iOS, and SDKs built on top of it — don't expose that hook, so operators are left without an easy way to inspect those handshakes.

For TCP TLS this is already covered: Envoy's DownstreamTlsContext has a key_log field that hooks BoringSSL's key log callback and writes NSS-format lines to a file, with optional local/remote address filters. The same proto field exists for QUIC but is not yet plumbed (see #25418, under CommonTlsContext: key_log).

This PR bridges that gap so the same key_log configuration that already works for TCP TLS produces NSS Key Log lines for QUIC connections too, giving operators a server-side way to decrypt QUIC captures when the client can't help.

Implementation

We piggy-back on the per-connection EnvoyTlsServerHandshaker introduced by #42734 and add a sibling static callback EnvoyTlsServerHandshaker::keylogCallback next to the existing ticketKeyCallback. The callback retrieves the handshaker from SSL ex_data, downcasts the QUIC session to its Network::Connection facet (static_cast<EnvoyQuicServerSession*>(handshaker->session())), reads cached local/peer addresses from its connection info provider, and forwards the line to the pinned ServerContextImpl's maybeWriteKeyLog(...).

To keep the address-filter + file-write logic from being duplicated, the existing inline body of ContextImpl::keylogCallback is factored into a new void ContextImpl::maybeWriteKeyLog(line, local_addr, remote_addr) that both the TCP and QUIC paths call. The TCP callback is now a thin shim: fetch the per-connection Network::TransportSocketCallbacks from ex_data, pull addresses off the connection, and call maybeWriteKeyLog. No behavior change for TCP.

The SSL_CTX_set_keylog_callback install lives in EnvoyQuicProofSource::OnNewSslCtx, alongside SSL_CTX_set_tlsext_ticket_key_cb. Both callbacks install unconditionally on the QUICHE-owned SSL_CTX, since OnNewSslCtx is the single mutation hook Envoy has on it and runs before any filter chain is known. Per-connection gating happens later.

EnvoyTlsServerHandshaker is selected for every QUIC connection that has a transport socket factory (vanilla quic::TlsServerHandshaker remains the fallback only when transport_socket_factory.has_value() is false — the no-filter-chain edge path). The session-ticket runtime flag (envoy.reloadable_features.quic_session_ticket_support) is folded into the per-connection disable_resumption ctor argument computed by the crypto stream factory:

const bool disable_resumption =
    !Runtime::runtimeFeatureEnabled("envoy.reloadable_features.quic_session_ticket_support") ||
    !ticket_config.has_keys || ticket_config.disable_stateless_resumption ||
    ticket_config.handles_session_resumption;

The handshaker constructor calls DisableResumption() (which sets SSL_OP_NO_TICKET on the SSL) whenever the caller wants resumption off or the pinned context is null / has no ticket keys. BoringSSL gates every QUIC/TLS 1.3 ticket path on SSL_OP_NO_TICKET, so ticketKeyCallback doesn't need a per-handshaker policy bit — the callback only verifies an Envoy handshaker is in ex_data and a pinned context is available, and trusts BoringSSL not to dispatch on disabled connections. An integration regression test (NoSessionTicketResumptionWhenRuntimeDisabledWithStaticKeys) pins that contract.

A small preparatory cleanup is included: source/common/quic/envoy_quic_server_session.cc was including envoy_quic_proof_source.h without referencing any proof-source symbol, and the matching BUILD dep on envoy_quic_proof_source_lib existed only to satisfy strict-headers for that vestigial include. Removing the include + dep (and adding the direct quic_server_transport_socket_factory.h include the proof-source header was transitively providing) breaks a cycle that would otherwise prevent envoy_tls_server_handshaker from depending on envoy_quic_server_session_lib to do the cast.

Key design decisions:

1. EnvoyTlsServerHandshaker is always used for QUIC. Restricting it to a runtime flag would couple unrelated features (key log, session tickets, future per-handshake hooks) to the same gate. vs. vanilla quic::TlsServerHandshaker, the subclass adds only SSL_set_ex_data (a pointer store) and a DisableResumption() call when resumption is disabled — the latter sets SSL_OP_NO_TICKET per-SSL, redundant with QUICHE's existing behavior of not setting SSL_CTX_set_ticket_aead_method when proof_source->GetTicketCrypter() returns null (Envoy's case).

2. Per-connection ticket gating lives in DisableResumption(), not in ticketKeyCallback. Setting SSL_OP_NO_TICKET in the ctor makes BoringSSL refuse to invoke ticket_key_cb on the TLS 1.2 decrypt/encrypt and TLS 1.3 encrypt paths. The callback only needs to verify ex_data is populated; the regression test pins the BoringSSL contract.

3. Reuse the pinned ServerContextImpl from quic: add TLS session ticket resumption support #42734. The handshaker already pins a ServerContextSharedPtr for session-ticket purposes. The key log callback uses the same pin, so an SDS rotation that swaps the factory's active context does not affect in-flight connections — every line a connection emits goes to the key log file the connection was created with, matching TCP TLS behavior.

4. maybeWriteKeyLog lives on ContextImpl, shared by TCP and QUIC. The key log file and IP-list filter members already live on ContextImpl, so factoring the filter+write step into a member of that class is the natural home. Refactoring ContextImpl::keylogCallback to delegate makes the new method genuinely shared rather than parallel-copied logic.

5. Addresses come from EnvoyQuicServerSession's Network::Connection facet. Inside keylogCallback, static_cast<EnvoyQuicServerSession*>(handshaker->session())->connectionInfoProvider() returns the same cached envoy address objects the connection was created with — no per-line allocation.

6. handshakerExDataIndex() is private to EnvoyTlsServerHandshaker. The ex_data slot is written only by the constructor (SSL_set_ex_data(..., this), wrapped in RELEASE_ASSERT for symmetry with the existing RELEASE_ASSERT(index >= 0, ...) on SSL_get_ex_new_index). Retrieval goes through a private helper handshakerFromSsl(ssl) that does a plain static_cast. The type contract — "the slot is either nullptr or a real EnvoyTlsServerHandshaker*" — is enforced structurally by who owns the index, not by runtime RTTI.

Flow

Server startup (once per listener SSL_CTX):
  EnvoyQuicProofSource::OnNewSslCtx()
    ├─ SSL_CTX_set_keylog_callback     (ssl_ctx, EnvoyTlsServerHandshaker::keylogCallback)
    └─ SSL_CTX_set_tlsext_ticket_key_cb(ssl_ctx, EnvoyTlsServerHandshaker::ticketKeyCallback)

Per QUIC connection:
  EnvoyQuicCryptoServerStreamFactoryImpl::createEnvoyQuicCryptoServerStream()
    ├─ if !transport_socket_factory.has_value(): return quic::CreateCryptoServerStream(...)
    ├─ disable_resumption =
    │     !runtimeFeatureEnabled(...quic_session_ticket_support) ||
    │     !ticket_config.has_keys || ticket_config.disable_stateless_resumption ||
    │     ticket_config.handles_session_resumption
    └─ EnvoyTlsServerHandshaker(session, crypto_config, factory.sslCtx(), disable_resumption)
         ├─ pins ServerContextSharedPtr
         ├─ RELEASE_ASSERT(SSL_set_ex_data(ssl, handshakerExDataIndex(), this) == 1, ...)
         └─ if disable_resumption || pinnedServerContext() == nullptr || no ticket keys:
              ASSERT(DisableResumption())   // sets SSL_OP_NO_TICKET on this SSL

During handshake (BoringSSL-driven):
  keylogCallback(ssl, line)
    ├─ handshaker = handshakerFromSsl(ssl)   // private helper, plain static_cast
    ├─ if null or no pinned context: return  // vanilla-handshaker edge path
    ├─ info = static_cast<EnvoyQuicServerSession*>(handshaker->session())->connectionInfoProvider()
    └─ handshaker->pinnedServerContext()->maybeWriteKeyLog(
                                              line,
                                              info.localAddress().get(),
                                              info.remoteAddress().get())
         ├─ if no key log file is configured: return  // shared with TCP TLS
         └─ apply tls_keylog_local_/remote_ filters; write the line

  ticketKeyCallback(ssl, ...)
    ├─ BoringSSL itself short-circuits when SSL_OP_NO_TICKET is set on the SSL
    │  (TLS 1.2: extensions.cc:4847; TLS 1.3: tls13_server.cc:159) → callback never fires
    ├─ handshaker = handshakerFromSsl(ssl)
    ├─ if null or no pinned context: return 0
    └─ return handshaker->pinnedServerContext()->sessionTicketProcess(ssl, ...)

TCP TLS key log (refactored, behavior unchanged):
  ContextImpl::keylogCallback(ssl, line)
    ├─ callbacks = SSL_get_ex_data(ssl, sslSocketIndex())
    ├─ ctx       = SSL_CTX_get_app_data(SSL_get_SSL_CTX(ssl))
    └─ ctx->maybeWriteKeyLog(line,
                             callbacks->connection().connectionInfoProvider().localAddress().get(),
                             callbacks->connection().connectionInfoProvider().remoteAddress().get())

Risk Level: Low. The key log feature is a no-op unless key_log is configured. The TCP TLS path is refactored but observably unchanged. Always-installing EnvoyTlsServerHandshaker is audited above: the only added per-connection work vs. vanilla is a pointer store and a redundant SSL_OP_NO_TICKET flag.

Testing:

• Unit: EnvoyTlsServerHandshakerTest.TicketKeyCallbackNullHandshaker and KeylogCallbackNullHandshaker (helper's null-tolerance on the vanilla edge path). EnvoyQuicProofSourceTest.OnNewSslCtxInstallsKeylogCallback (exact-equality assertion that EnvoyTlsServerHandshaker::keylogCallback is installed on the SSL_CTX).
• E2E key log: 7 tests in quic_http_integration_test (KeylogNoFilter, KeylogLocalFilterMatches, KeylogRemoteFilterMatches, KeylogLocalAndRemoteFilterMatch, KeylogLocalFilterNoMatch, KeylogRemoteFilterNoMatch, KeylogNotConfigured), each parameterized on IPv4/IPv6. The fixture does not toggle the session-ticket runtime flag, so the whole suite proves key log works with the flag at its default (off). Positive cases assert the file contains all five TLS 1.3 secrets (CLIENT_HANDSHAKE_TRAFFIC_SECRET, SERVER_HANDSHAKE_TRAFFIC_SECRET, CLIENT_TRAFFIC_SECRET, SERVER_TRAFFIC_SECRET, EXPORTER_SECRET); address-filter-no-match cases assert the file is created but empty; KeylogNotConfigured asserts no file is created when key_log is absent.
• E2E session-ticket: QuicHttpIntegrationTest.NoSessionTicketResumptionWhenRuntimeDisabledWithStaticKeys configures static ticket keys with envoy.reloadable_features.quic_session_ticket_support off and asserts the second connection does not resume — pins the BoringSSL SSL_OP_NO_TICKET contract the design relies on. SessionTicketResumptionWithStaticKeys and NoSessionTicketResumptionWithoutKeys continue to cover the flag-on resumption behavior.
• Existing TCP TLS key log tests in test/common/tls/integration/ssl_integration_test continue to pass after the keylogCallback → maybeWriteKeyLog refactor.

Docs Changes: N/A — uses the existing key_log proto already documented for TCP TLS.

Release Notes: N/A.

Platform Specific Features: N/A

[Optional Fixes #Issue] Fixes #35339. Also addresses the CommonTlsContext: key_log bullet of #25418.

[bellatoris]

Hi @danzh2010 and @RyanTheOptimist — when you have a moment, would you mind taking a look? This is a small follow-up to #42734 that addresses the CommonTlsContext: key_log bullet of #25418, and it reuses the EnvoyTlsServerHandshaker infrastructure you helped shape. Thanks in advance for your time!

[bellatoris]

/retest

[bellatoris]

@danzh2010 addressed all three review comments in the latest commit:

• ContextImpl::writeKeyLog is renamed to maybeWriteKeyLog.
• The QUIC key log callback now does static_cast<EnvoyQuicServerSession*>(handshaker->session())->connectionInfoProvider() inline as you suggested.
• The kQuicSessionTicketRuntimeFlag constant is inlined.

PR description updated to match. PTAL when you have a moment, thanks!

[bellatoris]

/retest

[danzh2010]

Thanks for your contribution!

[danzh2010]

Hand it to @RyanTheOptimist for final pass!

[kyessenov]

@RyanTheOptimist gentle ping!
/wait

[ggreenway]

/wait

[ggreenway]

This shouldn't be tied to envoy.reloadable_features.quic_session_ticket_support

[ggreenway]

Can this callback only be registered when keylogging is configured?

[bellatoris]

I don’t think we can gate the SSL_CTX callback registration directly on keylog config at OnNewSslCtx() time. That hook only has the shared QUICHE SSL_CTX; it does not know which filter chain / ServerContextImpl will be selected for a connection.

Instead, the updated patch installs the shared callback unconditionally, then gates the actual write at callback time through the per-connection pinned ServerContextImpl. If keylogging is not configured, maybeWriteKeyLog() short-circuits and no file is created/written.

To make that work for keylog-only configs, EnvoyTlsServerHandshaker is now selected whenever a QUIC transport socket factory is available, while the runtime flag only controls session resumption.

[ggreenway]

Add on line above: ASSERT(dynamic_cast<EnvoyTlsServerHandshaker*>(SSL_get_ex_data(ssl, handshakerExDataIndex())) != nullptr;

[bellatoris]

Because the SSL_CTX callbacks are now installed unconditionally, they can be invoked for SSL objects that did not come from EnvoyTlsServerHandshaker — specifically the vanilla QUICHE fallback path when no QUIC transport socket factory/filter chain is available. In that case the ex_data slot is legitimately unset, so nullptr is valid and a pre-null-check assert would be incorrect.

[bellatoris]

@danzh could you please review the updated design where Envoy installs EnvoyTlsServerHandshaker for all QUIC connections with a transport socket factory, and uses the runtime flag only to disable session resumption?

[bellatoris]

/gemini review

[gemini-code-assist]

Code Review

This pull request implements TLS key logging for QUIC by bridging shared QUICHE SSL_CTX callbacks to per-connection Envoy state and refactoring ContextImpl to share key logging logic. The reviewer identified several critical issues, including circular dependencies introduced in the build and source files by depending on the full session library instead of the connection interface. Additionally, a compilation error was noted where the void return value of DisableResumption() was incorrectly assigned to a boolean variable.