quic: add TLS session ticket resumption support

changelogs/current.yaml

@@ -18,5 +18,12 @@ removed_config_or_runtime:
 # *Normally occurs at the end of the* :ref:`deprecation period <deprecated>`
 
 new_features:
+- area: quic
+  change: |
+    Added support for TLS session ticket resumption in QUIC using configured session ticket keys from
+    :ref:`session_ticket_keys <envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.session_ticket_keys>`.
+    This enables faster reconnection across server instances by allowing clients to resume TLS sessions
+    without full handshakes. The feature is disabled by default and can be enabled by setting runtime guard
+    ``envoy.reloadable_features.quic_session_ticket_support`` to ``true``.
 
 deprecated:

source/common/quic/BUILD

@@ -122,6 +122,19 @@ envoy_cc_library(
     ]),
 )
 
+envoy_cc_library(
+    name = "envoy_tls_server_handshaker",
+    srcs = envoy_select_enable_http3(["envoy_tls_server_handshaker.cc"]),
+    hdrs = envoy_select_enable_http3(["envoy_tls_server_handshaker.h"]),
+    external_deps = ["ssl"],
+    deps = envoy_select_enable_http3([
+        "//source/common/common:assert_lib",
+        "//source/common/common:macros",
+        "//source/common/tls:server_context_lib",
+        "@quiche//:quic_server_session_lib",
+    ]),
+)
+
 envoy_cc_library(
     name = "envoy_quic_proof_source_lib",
     srcs = envoy_select_enable_http3(["envoy_quic_proof_source.cc"]),
@@ -130,6 +143,7 @@ envoy_cc_library(
     deps = envoy_select_enable_http3([
         ":envoy_quic_proof_source_base_lib",
         ":envoy_quic_utils_lib",
+        ":envoy_tls_server_handshaker",
         ":quic_io_handle_wrapper_lib",
         ":quic_transport_socket_factory_lib",
         "//envoy/ssl:tls_certificate_config_interface",

source/common/quic/envoy_quic_proof_source.cc

@@ -4,7 +4,9 @@
 
 #include "envoy/ssl/tls_certificate_config.h"
 
+#include "source/common/common/assert.h"
 #include "source/common/quic/envoy_quic_utils.h"
+#include "source/common/quic/envoy_tls_server_handshaker.h"
 #include "source/common/quic/quic_io_handle_wrapper.h"
 #include "source/common/stream_info/stream_info_impl.h"
 
@@ -113,7 +115,12 @@ void EnvoyQuicProofSource::updateFilterChainManager(
   filter_chain_manager_ = &filter_chain_manager;
 }
 
-void EnvoyQuicProofSource::OnNewSslCtx(SSL_CTX* ssl_ctx) { registerCertCompression(ssl_ctx); }
+void EnvoyQuicProofSource::OnNewSslCtx(SSL_CTX* ssl_ctx) {
+  registerCertCompression(ssl_ctx);
+  if (Runtime::runtimeFeatureEnabled("envoy.reloadable_features.quic_session_ticket_support")) {
+    SSL_CTX_set_tlsext_ticket_key_cb(ssl_ctx, EnvoyTlsServerHandshaker::ticketKeyCallback);
+  }
+}
 
 } // namespace Quic
 } // namespace Envoy

source/common/quic/envoy_quic_server_crypto_stream_factory.h

@@ -7,7 +7,6 @@
 #include "quiche/quic/core/crypto/quic_crypto_server_config.h"
 #include "quiche/quic/core/quic_crypto_server_stream_base.h"
 #include "quiche/quic/core/quic_session.h"
-#include "quiche/quic/core/tls_server_handshaker.h"
 
 namespace Envoy {
 namespace Quic {

source/common/quic/envoy_tls_server_handshaker.cc

@@ -0,0 +1,45 @@
+#include "source/common/quic/envoy_tls_server_handshaker.h"
+
+#include "source/common/common/macros.h"
+
+namespace Envoy {
+namespace Quic {
+
+EnvoyTlsServerHandshaker::EnvoyTlsServerHandshaker(
+    quic::QuicSession* session, const quic::QuicCryptoServerConfig* crypto_config,
+    Ssl::ServerContextSharedPtr pinned_ssl_ctx, bool disable_resumption)
+    : TlsServerHandshaker(session, crypto_config), pinned_ssl_ctx_(std::move(pinned_ssl_ctx)) {
+  SSL_set_ex_data(ssl(), handshakerExDataIndex(), this);
+  // Also check the pinned context for keys: the factory is shared across workers and
+  // config_ may reflect an SDS update before ssl_ctx_ is swapped on the main thread.
+  if (disable_resumption || !pinnedServerContext()->hasSessionTicketKeys()) {
+    DisableResumption();
+  }
+}
+
+int EnvoyTlsServerHandshaker::handshakerExDataIndex() {
+  CONSTRUCT_ON_FIRST_USE(int, []() -> int {
+    int index = SSL_get_ex_new_index(0, nullptr, nullptr, nullptr, nullptr);
+    RELEASE_ASSERT(index >= 0, "Failed to allocate SSL ex_data index for handshaker");
+    return index;
+  }());
+}
+
+int EnvoyTlsServerHandshaker::ticketKeyCallback(SSL* ssl, uint8_t* key_name, uint8_t* iv,
+                                                EVP_CIPHER_CTX* ctx, HMAC_CTX* hmac_ctx,
+                                                int encrypt) {
+  auto* handshaker =
+      static_cast<EnvoyTlsServerHandshaker*>(SSL_get_ex_data(ssl, handshakerExDataIndex()));
+  if (handshaker == nullptr || handshaker->pinnedServerContext() == nullptr) {
+    // Null handshaker can occur if the runtime guard was toggled between
+    // OnNewSslCtx (which installed this callback on the SSL_CTX) and
+    // connection creation (which fell back to the vanilla TlsServerHandshaker).
+    // Return 0 to disable ticket for this connection — graceful fallback.
+    return 0;
+  }
+  return handshaker->pinnedServerContext()->sessionTicketProcess(ssl, key_name, iv, ctx, hmac_ctx,
+                                                                 encrypt);
+}
+
+} // namespace Quic
+} // namespace Envoy

source/common/quic/envoy_tls_server_handshaker.h

@@ -0,0 +1,50 @@
+#pragma once
+
+#include <openssl/ssl.h>
+
+#include "source/common/common/assert.h"
+#include "source/common/tls/server_context_impl.h"
+
+#include "quiche/quic/core/tls_server_handshaker.h"
+
+namespace Envoy {
+namespace Quic {
+
+// TlsServerHandshaker subclass for QUIC session ticket handling.
+//
+// The session ticket key callback is installed on the shared QUICHE ssl
+// context, so every connection reaches the same callback regardless of which
+// filter chain served it. To find the right session ticket keys at callback
+// time, each connection pins a shared pointer to its ServerContextImpl in
+// ssl ex data at creation time. The pinned pointer keeps the context alive
+// for the connection even after an SDS update rotates the factory's active
+// context, and it matches TCP TLS behavior where each connection is bound
+// to the ServerContextImpl that was current at connection creation.
+class EnvoyTlsServerHandshaker : public quic::TlsServerHandshaker {
+public:
+  EnvoyTlsServerHandshaker(quic::QuicSession* session,
+                           const quic::QuicCryptoServerConfig* crypto_config,
+                           Ssl::ServerContextSharedPtr pinned_ssl_ctx, bool disable_resumption);
+
+  // Session ticket key callback installed on the QUICHE ssl context.
+  // Retrieves the handshaker from ssl ex_data and delegates to the pinned
+  // ServerContextImpl::sessionTicketProcess().
+  static int ticketKeyCallback(SSL* ssl, uint8_t* key_name, uint8_t* iv, EVP_CIPHER_CTX* ctx,
+                               HMAC_CTX* hmac_ctx, int encrypt);
+
+  // SSL ex_data index for storing the handshaker pointer per-connection.
+  static int handshakerExDataIndex();
+
+private:
+  // QuicServerTransportSocketFactory always creates ServerContextImpl,
+  // so this downcast is safe for all QUIC connections.
+  Extensions::TransportSockets::Tls::ServerContextImpl* pinnedServerContext() const {
+    return static_cast<Extensions::TransportSockets::Tls::ServerContextImpl*>(
+        pinned_ssl_ctx_.get());
+  }
+
+  Ssl::ServerContextSharedPtr pinned_ssl_ctx_;
+};
+
+} // namespace Quic
+} // namespace Envoy

source/common/quic/quic_server_transport_socket_factory.h

@@ -38,6 +38,34 @@ class QuicServerTransportSocketFactory : public Network::DownstreamTransportSock
 
   bool earlyDataEnabled() const { return enable_early_data_; }
 
+  struct SessionTicketConfig {
+    // True when session ticket encryption keys are explicitly configured via
+    // session_ticket_keys or session_ticket_keys_sds_secret_config. Without
+    // keys, the server cannot encrypt or decrypt session tickets.
+    bool has_keys;
+    // True when disable_stateless_session_resumption is set in
+    // DownstreamTlsContext. When enabled, the server will not issue session
+    // tickets and clients must perform full handshakes on every connection.
+    bool disable_stateless_resumption;
+    // True when an external mechanism (e.g., SDS provider) manages session
+    // resumption including ticket encryption/decryption. When set, Envoy
+    // should not install its own session ticket key processing callback.
+    bool handles_session_resumption;
+  };
+
+  SessionTicketConfig getSessionTicketConfig() const {
+    return {!config_->sessionTicketKeys().empty(), config_->disableStatelessSessionResumption(),
+            config_->capabilities().handles_session_resumption};
+  }
+
+  // Returns the current ServerContextImpl, pinning a shared_ptr so it
+  // remains valid for the caller's lifetime. May return null before
+  // initialize() completes or if context creation failed.
+  Ssl::ServerContextSharedPtr sslCtx() const {
+    absl::ReaderMutexLock l(ssl_ctx_mu_);
+    return ssl_ctx_;
+  }
+
 protected:
   QuicServerTransportSocketFactory(bool enable_early_data, Stats::Scope& store,
                                    Ssl::ServerContextConfigPtr config,

source/common/runtime/runtime_features.cc

@@ -144,6 +144,8 @@ FALSE_RUNTIME_GUARD(envoy_reloadable_features_always_use_v6);
 FALSE_RUNTIME_GUARD(envoy_restart_features_upstream_http_filters_with_tcp_proxy);
 // TODO(danzh) false deprecate it once QUICHE has its own enable/disable flag.
 FALSE_RUNTIME_GUARD(envoy_reloadable_features_quic_reject_all);
+// TODO(doogie): Flip to true once QUIC session ticket support is stable.
+FALSE_RUNTIME_GUARD(envoy_reloadable_features_quic_session_ticket_support);
 // TODO(#10646) change to true when UHV is sufficiently tested
 // For more information about Universal Header Validation, please see
 // https://github.com/envoyproxy/envoy/issues/10646

source/common/tls/server_context_impl.h

@@ -70,6 +70,10 @@ class ServerContextImpl : public ContextImpl,
 
   Ssl::CurveNIDVector getClientEcdsaCapabilities(const SSL_CLIENT_HELLO& ssl_client_hello) const;
 
+  int sessionTicketProcess(SSL* ssl, uint8_t* key_name, uint8_t* iv, EVP_CIPHER_CTX* ctx,
+                           HMAC_CTX* hmac_ctx, int encrypt);
+  bool hasSessionTicketKeys() const { return !session_ticket_keys_.empty(); }
+
 protected:
   ServerContextImpl(
       Stats::Scope& scope, const Envoy::Ssl::ServerContextConfig& config,
@@ -82,8 +86,6 @@ class ServerContextImpl : public ContextImpl,
 
   int alpnSelectCallback(const unsigned char** out, unsigned char* outlen, const unsigned char* in,
                          unsigned int inlen);
-  int sessionTicketProcess(SSL* ssl, uint8_t* key_name, uint8_t* iv, EVP_CIPHER_CTX* ctx,
-                           HMAC_CTX* hmac_ctx, int encrypt);
 
   absl::StatusOr<SessionContextID>
   generateHashForSessionContextId(const std::vector<std::string>& server_names);

source/extensions/quic/crypto_stream/BUILD

@@ -27,7 +27,10 @@ envoy_cc_library(
     deps = envoy_select_enable_http3([
         "//envoy/registry",
         "//source/common/quic:envoy_quic_server_crypto_stream_factory_lib",
+        "//source/common/quic:envoy_tls_server_handshaker",
+        "//source/common/quic:quic_server_transport_socket_factory_lib",
         "@envoy_api//envoy/extensions/quic/crypto_stream/v3:pkg_cc_proto",
+        "@quiche//:quic_server_session_lib",
     ]),
     alwayslink = LEGACY_ALWAYSLINK,
 )

source/extensions/quic/crypto_stream/envoy_quic_crypto_server_stream.cc

@@ -1,5 +1,9 @@
 #include "source/extensions/quic/crypto_stream/envoy_quic_crypto_server_stream.h"
 
+#include "source/common/quic/envoy_tls_server_handshaker.h"
+#include "source/common/quic/quic_server_transport_socket_factory.h"
+#include "source/common/runtime/runtime_features.h"
+
 namespace Envoy {
 namespace Quic {
 
@@ -8,11 +12,26 @@ EnvoyQuicCryptoServerStreamFactoryImpl::createEnvoyQuicCryptoServerStream(
     const quic::QuicCryptoServerConfig* crypto_config,
     quic::QuicCompressedCertsCache* compressed_certs_cache, quic::QuicSession* session,
     quic::QuicCryptoServerStreamBase::Helper* helper,
-    // Though this extension doesn't use the two parameters below, they might be used by
-    // downstreams. Do not remove them.
-    OptRef<const Network::DownstreamTransportSocketFactory> /*transport_socket_factory*/,
+    OptRef<const Network::DownstreamTransportSocketFactory> transport_socket_factory,
+    // Though this extension doesn't use the dispatcher parameter, it might be used by
+    // downstreams. Do not remove it.
     Envoy::Event::Dispatcher& /*dispatcher*/) {
-  return quic::CreateCryptoServerStream(crypto_config, compressed_certs_cache, session, helper);
+
+  if (!Runtime::runtimeFeatureEnabled("envoy.reloadable_features.quic_session_ticket_support") ||
+      !transport_socket_factory.has_value()) {
+    return quic::CreateCryptoServerStream(crypto_config, compressed_certs_cache, session, helper);
+  }
+
+  // QUIC listeners always use QuicServerTransportSocketFactory. The factory's
+  // ssl_ctx_ is set in the constructor and swapped (never nulled) on SDS updates.
+  auto& factory = static_cast<const QuicServerTransportSocketFactory&>(*transport_socket_factory);
+
+  auto ticket_config = factory.getSessionTicketConfig();
+  bool disable_resumption = ticket_config.disable_stateless_resumption || !ticket_config.has_keys ||
+                            ticket_config.handles_session_resumption;
+
+  return std::make_unique<EnvoyTlsServerHandshaker>(session, crypto_config, factory.sslCtx(),
+                                                    disable_resumption);
 }
 
 REGISTER_FACTORY(EnvoyQuicCryptoServerStreamFactoryImpl,

test/common/quic/BUILD

@@ -53,6 +53,14 @@ envoy_cc_test(
     ]),
 )
 
+envoy_cc_test(
+    name = "envoy_tls_server_handshaker_test",
+    srcs = envoy_select_enable_http3(["envoy_tls_server_handshaker_test.cc"]),
+    deps = envoy_select_enable_http3([
+        "//source/common/quic:envoy_tls_server_handshaker",
+    ]),
+)
+
 envoy_cc_test(
     name = "envoy_quic_proof_source_test",
     srcs = envoy_select_enable_http3(["envoy_quic_proof_source_test.cc"]),

test/common/quic/envoy_quic_proof_source_test.cc

@@ -1,3 +1,5 @@
+#include <openssl/ssl.h>
+
 #include <memory>
 #include <string>
 #include <vector>
@@ -193,10 +195,16 @@ class EnvoyQuicProofSourceTest : public ::testing::Test {
     EXPECT_CALL(filter_chain_, transportSocketFactory())
         .WillRepeatedly(ReturnRef(*transport_socket_factory_));
 
+    loadCertsIntoFactory(cert, expect_private_key);
+  }
+
+  // Sets up mock config expectations and triggers cert loading into the transport
+  // socket factory. Does NOT set proof-source-level expectations (ioHandle,
+  // findFilterChain, transportSocketFactory) — callers add those as needed.
+  void loadCertsIntoFactory(const std::string& cert, bool with_private_key) {
     auto factory = Extensions::TransportSockets::Tls::TlsCertificateSelectorConfigFactoryImpl::
         getDefaultTlsCertificateSelectorConfigFactory();
     ASSERT_TRUE(factory);
-    ASSERT_EQ("envoy.tls.certificate_selectors.default", factory->name());
     const Protobuf::Any any;
 
     Server::Configuration::MockGenericFactoryContext ctx;
@@ -221,7 +229,7 @@ class EnvoyQuicProofSourceTest : public ::testing::Test {
     EXPECT_CALL(tls_cert_config_, certificateChain())
         .Times(testing::AtLeast(1))
         .WillRepeatedly(ReturnRef(cert));
-    if (expect_private_key) {
+    if (with_private_key) {
       EXPECT_CALL(tls_cert_config_, privateKey())
           .Times(testing::AtLeast(1))
           .WillRepeatedly(ReturnRef(pkey_));
@@ -348,5 +356,45 @@ TEST_F(EnvoyQuicProofSourceTest, ComputeSignatureFailNoFilterChain) {
       std::make_unique<TestSignatureCallback>(false, filter_chain_, signature));
 }
 
+TEST_F(EnvoyQuicProofSourceTest, ComputeSignatureFailAlgorithmMismatch) {
+  EXPECT_CALL(listen_socket_, ioHandle()).Times(testing::AnyNumber());
+  EXPECT_CALL(filter_chain_manager_, findFilterChain(_, _))
+      .WillRepeatedly(Invoke([&](const Network::ConnectionSocket&, const StreamInfo::StreamInfo&) {
+        return &filter_chain_;
+      }));
+  EXPECT_CALL(filter_chain_, transportSocketFactory())
+      .WillRepeatedly(ReturnRef(*transport_socket_factory_));
+
+  loadCertsIntoFactory(expected_certs_, true);
+
+  std::string signature;
+  // Use ECDSA algorithm with an RSA key — triggers algorithm mismatch error path.
+  proof_source_.ComputeTlsSignature(
+      server_address_, client_address_, hostname_, SSL_SIGN_ECDSA_SECP256R1_SHA256, "payload",
+      std::make_unique<TestSignatureCallback>(false, filter_chain_, signature));
+}
+
+// Smoke test: verify OnNewSslCtx installs the ticket key callback when the
+// runtime guard is enabled. We cannot directly inspect the callback, but we
+// verify the call completes without error.
+TEST_F(EnvoyQuicProofSourceTest, OnNewSslCtxWithSessionTicketSupport) {
+  TestScopedRuntime scoped_runtime;
+  scoped_runtime.mergeValues({{"envoy.reloadable_features.quic_session_ticket_support", "true"}});
+
+  bssl::UniquePtr<SSL_CTX> ssl_ctx(SSL_CTX_new(TLS_method()));
+  ASSERT_NE(ssl_ctx, nullptr);
+  proof_source_.OnNewSslCtx(ssl_ctx.get());
+}
+
+// Smoke test: verify OnNewSslCtx is a no-op when the runtime guard is disabled.
+TEST_F(EnvoyQuicProofSourceTest, OnNewSslCtxWithSessionTicketSupportDisabled) {
+  TestScopedRuntime scoped_runtime;
+  scoped_runtime.mergeValues({{"envoy.reloadable_features.quic_session_ticket_support", "false"}});
+
+  bssl::UniquePtr<SSL_CTX> ssl_ctx(SSL_CTX_new(TLS_method()));
+  ASSERT_NE(ssl_ctx, nullptr);
+  proof_source_.OnNewSslCtx(ssl_ctx.get());
+}
+
 } // namespace Quic
 } // namespace Envoy