tls: Add certificate compression algorithm configuration (RFC 8879)

This change adds TLS certificate compression support with brotli, zstd, and zlib
algorithms per RFC 8879. Certificate compression reduces TLS handshake size,
especially beneficial for QUIC where the ServerHello needs to fit in the initial
response.

Features:
- Support for brotli (ID 2), zstd (ID 3), and zlib (ID 1) compression algorithms
- Individual registration functions for each algorithm
- Compression stats: certificate_compression.<algo>.{compressed,total_uncompressed_bytes,total_compressed_bytes}
- Runtime feature flag: envoy.reloadable_features.tls_support_certificate_compression (default: false)

Testing:
- Unit tests for compression/decompression round-trips
- Registration tests with real SSL_CTX
- Integration tests for TLS handshake with compression enabled/disabled

Documentation:
- Changelog entry for the new feature
- Stats documentation in ssl_stats.rst

Part of certificate compression implementation (RFC 8879).

Author: bellatoris

changelogs/current.yaml

@@ -440,6 +440,16 @@ new_features:
     ``verify cert failed: cert hash and spki``, or the OpenSSL verification error string (e.g., certificate
     has expired, unable to get local issuer certificate). This provides better visibility into TLS handshake
     failures without requiring debug-level logging.
+- area: tls
+  change: |
+    Added TLS certificate compression support (RFC 8879) with brotli, zstd, and zlib algorithms.
+    Compression reduces TLS handshake size, especially beneficial for QUIC where the ServerHello
+    needs to fit in the initial response. Controlled by runtime flag
+    ``envoy.reloadable_features.tls_support_certificate_compression`` (defaults to ``false``).
+    New stats: ``ssl.certificate_compression.<algo>.compressed``,
+    ``ssl.certificate_compression.<algo>.total_uncompressed_bytes``,
+    ``ssl.certificate_compression.<algo>.total_compressed_bytes`` where ``<algo>`` is one of
+    brotli, zstd, or zlib.
 - area: ext_proc
   change: |
     Added support for forwarding cluster metadata to ext_proc server.

docs/root/_include/ssl_stats.rst

@@ -19,3 +19,6 @@
    sigalgs.<sigalg>, Counter, Total successful TLS connections that used signature algorithm <sigalg>
    versions.<version>, Counter, Total successful TLS connections that used protocol version <version>
    was_key_usage_invalid, Counter, Total successful TLS connections that used an `invalid keyUsage extension <https://github.com/google/boringssl/blob/6f13380d27835e70ec7caf807da7a1f239b10da6/ssl/internal.h#L3117>`_. (This is not available in BoringSSL FIPS yet due to `issue #28246 <https://github.com/envoyproxy/envoy/issues/28246>`_)
+   certificate_compression.<algo>.compressed, Counter, Total certificates compressed using algorithm <algo> (brotli/zstd/zlib). Requires runtime flag ``envoy.reloadable_features.tls_support_certificate_compression``.
+   certificate_compression.<algo>.total_uncompressed_bytes, Counter, Total bytes of certificates before compression using algorithm <algo>
+   certificate_compression.<algo>.total_compressed_bytes, Counter, Total bytes of certificates after compression using algorithm <algo>

source/common/quic/cert_compression.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include "source/common/runtime/runtime_features.h"
 #include "source/common/tls/cert_compression.h"
 
 namespace Envoy {
@@ -12,11 +13,20 @@ namespace Quic {
  */
 class CertCompression : protected Logger::Loggable<Logger::Id::quic> {
 public:
-  // Registers all compression and decompression functions on `ssl_ctx`.
-  // This is a wrapper that calls the TLS implementation.
-  // Registers brotli, zstd, and zlib in priority order (RFC 8879).
+  // Registers compression and decompression functions on `ssl_ctx`.
+  // When runtime feature is enabled: registers all algorithms (brotli, zstd, zlib)
+  // When runtime feature is disabled: registers zlib only (backward compat)
   static void registerSslContext(SSL_CTX* ssl_ctx) {
-    Extensions::TransportSockets::Tls::CertCompression::registerAll(ssl_ctx);
+    if (Runtime::runtimeFeatureEnabled(
+            "envoy.reloadable_features.tls_support_certificate_compression")) {
+      // Priority: brotli > zstd > zlib (brotli generally provides best compression for certs)
+      Extensions::TransportSockets::Tls::CertCompression::registerBrotli(ssl_ctx);
+      Extensions::TransportSockets::Tls::CertCompression::registerZstd(ssl_ctx);
+      Extensions::TransportSockets::Tls::CertCompression::registerZlib(ssl_ctx);
+    } else {
+      // Backward compatibility: register zlib only
+      Extensions::TransportSockets::Tls::CertCompression::registerZlib(ssl_ctx);
+    }
   }
 
   // Callbacks for `SSL_CTX_add_cert_compression_alg`.

source/common/runtime/runtime_features.cc

@@ -117,6 +117,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: flip to true after sufficient testing of TLS certificate compression.
+FALSE_RUNTIME_GUARD(envoy_reloadable_features_tls_support_certificate_compression);
 // 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/BUILD

@@ -183,6 +183,7 @@ envoy_cc_library(
     visibility = ["//visibility:public"],
     deps = [
         ":cert_compression_lib",
+        ":ssl_ctx_stats_provider_lib",
         ":stats_lib",
         ":utility_lib",
         "//envoy/ssl:context_config_interface",
@@ -261,12 +262,22 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "ssl_ctx_stats_provider_lib",
+    hdrs = ["ssl_ctx_stats_provider.h"],
+    deps = [
+        ":stats_lib",
+    ],
+)
+
 envoy_cc_library(
     name = "cert_compression_lib",
     srcs = ["cert_compression.cc"],
     hdrs = ["cert_compression.h"],
     external_deps = ["ssl"],
     deps = [
+        ":ssl_ctx_stats_provider_lib",
+        "//envoy/ssl:context_config_interface",
         "//source/common/common:assert_lib",
         "//source/common/common:logger_lib",
         "@org_brotli//:brotlidec",

source/common/tls/cert_compression.cc

@@ -1,6 +1,8 @@
 #include "source/common/tls/cert_compression.h"
 
 #include "source/common/common/assert.h"
+#include "source/common/tls/ssl_ctx_stats_provider.h"
+#include "source/common/tls/stats.h"
 
 #include "brotli/decode.h"
 #include "brotli/encode.h"
@@ -29,17 +31,25 @@ class ScopedZStream {
   CleanupFunc cleanup_;
 };
 
-} // namespace
-
-void CertCompression::registerAll(SSL_CTX* ssl_ctx) {
-  // Register all algorithms in priority order.
-  // The TLS handshake will negotiate the best mutually supported algorithm.
-  // Priority: brotli > zstd > zlib (brotli generally provides best compression for certs)
-  registerBrotli(ssl_ctx);
-  registerZstd(ssl_ctx);
-  registerZlib(ssl_ctx);
+// Record certificate compression stats per algorithm for monitoring compression effectiveness.
+void recordCompressedCertSize(SSL* ssl, size_t uncompressed_size, size_t compressed_size,
+                              const std::string& algo) {
+  SSL_CTX* ssl_ctx = SSL_get_SSL_CTX(ssl);
+  if (ssl_ctx == nullptr) {
+    return;
+  }
+  auto* provider = static_cast<SslCtxStatsProvider*>(SSL_CTX_get_app_data(ssl_ctx));
+  if (provider != nullptr) {
+    const std::string prefix = "ssl.certificate_compression." + algo + ".";
+    CertCompressionStats stats = generateCertCompressionStats(provider->statsScope(), prefix);
+    stats.compressed_.inc();
+    stats.total_uncompressed_bytes_.add(uncompressed_size);
+    stats.total_compressed_bytes_.add(compressed_size);
+  }
 }
 
+} // namespace
+
 void CertCompression::registerBrotli(SSL_CTX* ssl_ctx) {
   auto ret = SSL_CTX_add_cert_compression_alg(ssl_ctx, TLSEXT_cert_compression_brotli,
                                               compressBrotli, decompressBrotli);
@@ -59,7 +69,7 @@ void CertCompression::registerZlib(SSL_CTX* ssl_ctx) {
 }
 
 // Brotli compression implementation
-int CertCompression::compressBrotli(SSL*, CBB* out, const uint8_t* in, size_t in_len) {
+int CertCompression::compressBrotli(SSL* ssl, CBB* out, const uint8_t* in, size_t in_len) {
   size_t encoded_size = BrotliEncoderMaxCompressedSize(in_len);
   if (encoded_size == 0) {
     IS_ENVOY_BUG("BrotliEncoderMaxCompressedSize returned 0");
@@ -84,6 +94,7 @@ int CertCompression::compressBrotli(SSL*, CBB* out, const uint8_t* in, size_t in
     return FAILURE;
   }
 
+  recordCompressedCertSize(ssl, in_len, encoded_size, "brotli");
   ENVOY_LOG(trace, "Cert brotli compression successful");
   return SUCCESS;
 }
@@ -124,7 +135,7 @@ int CertCompression::decompressBrotli(SSL*, CRYPTO_BUFFER** out, size_t uncompre
 }
 
 // Zstd compression implementation
-int CertCompression::compressZstd(SSL*, CBB* out, const uint8_t* in, size_t in_len) {
+int CertCompression::compressZstd(SSL* ssl, CBB* out, const uint8_t* in, size_t in_len) {
   size_t const max_size = ZSTD_compressBound(in_len);
   if (max_size == 0) {
     IS_ENVOY_BUG("ZSTD_compressBound returned 0");
@@ -149,6 +160,7 @@ int CertCompression::compressZstd(SSL*, CBB* out, const uint8_t* in, size_t in_l
     return FAILURE;
   }
 
+  recordCompressedCertSize(ssl, in_len, compressed_size, "zstd");
   ENVOY_LOG(trace, "Cert zstd compression successful");
   return SUCCESS;
 }
@@ -186,7 +198,7 @@ int CertCompression::decompressZstd(SSL*, CRYPTO_BUFFER** out, size_t uncompress
 }
 
 // Zlib compression implementation
-int CertCompression::compressZlib(SSL*, CBB* out, const uint8_t* in, size_t in_len) {
+int CertCompression::compressZlib(SSL* ssl, CBB* out, const uint8_t* in, size_t in_len) {
   z_stream z = {};
   // The deflateInit macro from zlib.h contains an old-style cast, so we need to suppress the
   // warning for this call.
@@ -228,6 +240,7 @@ int CertCompression::compressZlib(SSL*, CBB* out, const uint8_t* in, size_t in_l
     return FAILURE;
   }
 
+  recordCompressedCertSize(ssl, in_len, z.total_out, "zlib");
   ENVOY_LOG(trace, "Cert zlib compression successful");
   return SUCCESS;
 }

source/common/tls/cert_compression.h

@@ -32,10 +32,6 @@ namespace Tls {
  */
 class CertCompression : protected Logger::Loggable<Logger::Id::connection> {
 public:
-  // Register all supported compression algorithms in priority order.
-  // Priority: brotli > zstd > zlib (brotli generally provides best compression for certs)
-  static void registerAll(SSL_CTX* ssl_ctx);
-
   // Individual registration functions for each algorithm.
   static void registerBrotli(SSL_CTX* ssl_ctx);
   static void registerZstd(SSL_CTX* ssl_ctx);

source/common/tls/context_impl.cc

@@ -164,9 +164,15 @@ ContextImpl::ContextImpl(Stats::Scope& scope, const Envoy::Ssl::ContextConfig& c
       }
     }
 
-    // Register certificate compression algorithms to reduce TLS handshake size.
-    // This registers brotli, zstd, and zlib in priority order (RFC 8879).
-    CertCompression::registerAll(ctx.ssl_ctx_.get());
+    // Register certificate compression algorithms to reduce TLS handshake size (RFC 8879).
+    // Only register if the runtime feature flag is enabled (default: disabled).
+    if (Runtime::runtimeFeatureEnabled(
+            "envoy.reloadable_features.tls_support_certificate_compression")) {
+      // Priority: brotli > zstd > zlib (brotli generally provides best compression for certs)
+      CertCompression::registerBrotli(ctx.ssl_ctx_.get());
+      CertCompression::registerZstd(ctx.ssl_ctx_.get());
+      CertCompression::registerZlib(ctx.ssl_ctx_.get());
+    }
   }
 
   auto verify_mode_or_error = cert_validator_->initializeSslContexts(
@@ -574,16 +580,6 @@ void ContextImpl::logHandshake(SSL* ssl) const {
     stats_.was_key_usage_invalid_.inc();
   }
 
-  // Record certificate chain sizes (DER-encoded bytes) for TLS overhead visibility.
-  const size_t peer_cert_size = Utility::getPeerCertificateChainDerSize(ssl);
-  if (peer_cert_size > 0) {
-    stats_.peer_certificate_chain_bytes_.recordValue(peer_cert_size);
-  }
-
-  const size_t local_cert_size = Utility::getLocalCertificateChainDerSize(ssl);
-  if (local_cert_size > 0) {
-    stats_.local_certificate_chain_bytes_.recordValue(local_cert_size);
-  }
 }
 
 std::vector<Ssl::PrivateKeyMethodProviderSharedPtr> ContextImpl::getPrivateKeyMethodProviders() {

source/common/tls/context_impl.h

@@ -21,6 +21,7 @@
 #include "source/common/stats/symbol_table.h"
 #include "source/common/tls/cert_validator/cert_validator.h"
 #include "source/common/tls/context_manager_impl.h"
+#include "source/common/tls/ssl_ctx_stats_provider.h"
 #include "source/common/tls/stats.h"
 
 #include "absl/synchronization/mutex.h"
@@ -80,6 +81,7 @@ namespace TransportSockets {
 namespace Tls {
 
 class ContextImpl : public virtual Envoy::Ssl::Context,
+                    public SslCtxStatsProvider,
                     protected Logger::Loggable<Logger::Id::config> {
 public:
   virtual absl::StatusOr<bssl::UniquePtr<SSL>>
@@ -92,7 +94,8 @@ class ContextImpl : public virtual Envoy::Ssl::Context,
    */
   void logHandshake(SSL* ssl) const;
 
-  SslStats& stats() { return stats_; }
+  SslStats& stats() override { return stats_; }
+  Stats::Scope& statsScope() override { return scope_; }
 
   /**
    * The global SSL-library index used for storing a pointer to the SslExtendedSocketInfo

source/common/tls/ssl_ctx_stats_provider.h

@@ -0,0 +1,24 @@
+#pragma once
+
+#include "envoy/stats/scope.h"
+
+#include "source/common/tls/stats.h"
+
+namespace Envoy {
+namespace Extensions {
+namespace TransportSockets {
+namespace Tls {
+
+// Interface for providing SSL stats from SSL_CTX app_data.
+// This avoids circular dependency between cert_compression_lib and context_lib.
+class SslCtxStatsProvider {
+public:
+  virtual ~SslCtxStatsProvider() = default;
+  virtual SslStats& stats() = 0;
+  virtual Stats::Scope& statsScope() = 0;
+};
+
+} // namespace Tls
+} // namespace TransportSockets
+} // namespace Extensions
+} // namespace Envoy