tls: add certificateCompression option

This changes enables compression within OpenSSL *without* enabling
record compression, so this only affects compression of certificates
delivered within the TLS handshake. This certificate compression remains
disabled by default for now, but becomes available via the new
certificateCompression option in TLS context APIs.

Enabling this shrinks handshakes significantly, and also reduces
fingerprintability of Node.js client handshakes, as these are enabled in
all modern browsers by default.

Author: pimterry

doc/api/tls.md

@@ -1895,6 +1895,9 @@ argument.
 <!-- YAML
 added: v0.11.13
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62217
+    description: The `certificateCompression` option has been added.
   - version:
     - v22.9.0
     - v20.18.0
@@ -1988,6 +1991,12 @@ changes:
     the same order as their private keys in `key`. If the intermediate
     certificates are not provided, the peer will not be able to validate the
     certificate, and the handshake will fail.
+  * `certificateCompression` {string\[]} An array of supported certificate
+    compression algorithm names, in preference order. Supported values are
+    `'zlib'`, `'brotli'`, and `'zstd'`. When set, enables TLS certificate
+    compression ([RFC 8879][]) which compresses certificates during the TLS
+    handshake, reducing handshake size. Only effective with TLSv1.3.
+    **Default:** `[]` (disabled).
   * `sigalgs` {string} Colon-separated list of supported signature algorithms.
     The list can contain digest algorithms (`SHA256`, `MD5` etc.), public key
     algorithms (`RSA-PSS`, `ECDSA` etc.), combination of both (e.g
@@ -2469,6 +2478,7 @@ added: v0.11.3
 [RFC 4279]: https://tools.ietf.org/html/rfc4279
 [RFC 5077]: https://tools.ietf.org/html/rfc5077
 [RFC 5929]: https://tools.ietf.org/html/rfc5929
+[RFC 8879]: https://tools.ietf.org/html/rfc8879
 [SSL_METHODS]: https://www.openssl.org/docs/man1.1.1/man7/ssl.html#Dealing-with-Protocol-Methods
 [Session Resumption]: #session-resumption
 [Stream]: stream.md#stream

lib/internal/tls/secure-context.js

@@ -133,6 +133,7 @@ function configSecureContext(context, options = kEmptyObject, name = 'options')
     allowPartialTrustChain,
     ca,
     cert,
+    certificateCompression,
     ciphers = getDefaultCiphers(),
     clientCertEngine,
     crl,
@@ -210,6 +211,17 @@ function configSecureContext(context, options = kEmptyObject, name = 'options')
     }
   }
 
+  if (certificateCompression != null) {
+    if (!ArrayIsArray(certificateCompression)) {
+      throw new ERR_INVALID_ARG_TYPE(
+        `${name}.certificateCompression`, 'Array', certificateCompression);
+    }
+
+    if (certificateCompression.length > 0) {
+      context.setCertificateCompression(certificateCompression);
+    }
+  }
+
   if (sigalgs !== undefined && sigalgs !== null) {
     validateString(sigalgs, `${name}.sigalgs`);
 

lib/internal/tls/wrap.js

@@ -1506,6 +1506,7 @@ Server.prototype.setSecureContext = function(options) {
 
   this.privateKeyIdentifier = options.privateKeyIdentifier;
   this.privateKeyEngine = options.privateKeyEngine;
+  this.certificateCompression = options.certificateCompression;
 
   this._sharedCreds = tls.createSecureContext({
     pfx: this.pfx,
@@ -1529,6 +1530,7 @@ Server.prototype.setSecureContext = function(options) {
     sessionTimeout: this.sessionTimeout,
     privateKeyIdentifier: this.privateKeyIdentifier,
     privateKeyEngine: this.privateKeyEngine,
+    certificateCompression: this.certificateCompression,
   });
 };
 

src/crypto/crypto_context.cc

@@ -1319,6 +1319,8 @@ Local<FunctionTemplate> SecureContext::GetConstructorTemplate(
     SetProtoMethod(isolate, tmpl, "setOptions", SetOptions);
     SetProtoMethod(isolate, tmpl, "setSessionIdContext", SetSessionIdContext);
     SetProtoMethod(isolate, tmpl, "setSessionTimeout", SetSessionTimeout);
+    SetProtoMethod(
+        isolate, tmpl, "setCertificateCompression", SetCertificateCompression);
     SetProtoMethod(isolate, tmpl, "close", Close);
     SetProtoMethod(isolate, tmpl, "loadPKCS12", LoadPKCS12);
     SetProtoMethod(isolate, tmpl, "setTicketKeys", SetTicketKeys);
@@ -1407,6 +1409,7 @@ void SecureContext::RegisterExternalReferences(
   registry->Register(SetOptions);
   registry->Register(SetSessionIdContext);
   registry->Register(SetSessionTimeout);
+  registry->Register(SetCertificateCompression);
   registry->Register(Close);
   registry->Register(LoadPKCS12);
   registry->Register(SetTicketKeys);
@@ -1565,6 +1568,14 @@ void SecureContext::Init(const FunctionCallbackInfo<Value>& args) {
   env->external_memory_accounter()->Increase(env->isolate(), kExternalSize);
   SSL_CTX_set_app_data(sc->ctx_.get(), sc);
 
+  // OpenSSL populates cert_comp_prefs with all available algorithms by
+  // default when compression libraries are linked. Clear them so that
+  // certificate compression (RFC 8879) is always opt-in for now, via
+  // the certificateCompression option.
+#ifndef OPENSSL_NO_COMP_ALG
+  SSL_CTX_set1_cert_comp_preference(sc->ctx_.get(), nullptr, 0);
+#endif
+
   // Disable SSLv2 in the case when method == TLS_method() and the
   // cipher list contains SSLv2 ciphers (not the default, should be rare.)
   // The bundled OpenSSL doesn't have SSLv2 support but the system OpenSSL may.
@@ -2067,6 +2078,84 @@ void SecureContext::SetSessionTimeout(const FunctionCallbackInfo<Value>& args) {
   SSL_CTX_set_timeout(sc->ctx_.get(), sessionTimeout);
 }
 
+void SecureContext::SetCertificateCompression(
+    const FunctionCallbackInfo<Value>& args) {
+  SecureContext* sc;
+  ASSIGN_OR_RETURN_UNWRAP(&sc, args.This());
+  Environment* env = sc->env();
+
+  CHECK_GE(args.Length(), 1);
+  CHECK(args[0]->IsArray());
+
+  Local<Array> arr = args[0].As<Array>();
+  uint32_t len = arr->Length();
+
+  if (len == 0 || len > TLSEXT_comp_cert_limit) {
+    return THROW_ERR_INVALID_ARG_VALUE(
+        env, "certificateCompression must contain 1 to 3 algorithm names");
+  }
+
+#ifndef OPENSSL_NO_COMP_ALG
+  int algs[TLSEXT_comp_cert_limit];
+  for (uint32_t i = 0; i < len; i++) {
+    Local<Value> val;
+    if (!arr->Get(env->context(), i).ToLocal(&val) || !val->IsString()) {
+      return THROW_ERR_INVALID_ARG_VALUE(
+          env, "certificateCompression entries must be strings");
+    }
+    Utf8Value name(env->isolate(), val);
+    if (strcmp(*name, "zlib") == 0) {
+      algs[i] = TLSEXT_comp_cert_zlib;
+    } else if (strcmp(*name, "brotli") == 0) {
+      algs[i] = TLSEXT_comp_cert_brotli;
+    } else if (strcmp(*name, "zstd") == 0) {
+      algs[i] = TLSEXT_comp_cert_zstd;
+    } else {
+      return THROW_ERR_INVALID_ARG_VALUE(
+          env,
+          "certificateCompression algorithm must be 'zlib', 'brotli', or "
+          "'zstd'");
+    }
+  }
+  if (!SSL_CTX_set1_cert_comp_preference(
+          sc->ctx_.get(), algs, static_cast<size_t>(len))) {
+    return THROW_ERR_CRYPTO_OPERATION_FAILED(
+        env, "Failed to set certificate compression preference");
+  }
+
+  // Pre-compress the loaded certificate(s) for all supported algorithms, where
+  // 0 arg means 'compress with all algorithms in the preference list'.
+  // Returns 0 when no certificate is loaded (e.g. client-only context) or
+  // when compression did not reduce size — both are non-fatal.
+  SSL_CTX_compress_certs(sc->ctx_.get(), 0);
+
+  // Store preferences for propagation during SNI context switches.
+  memcpy(sc->cert_comp_prefs_, algs, sizeof(int) * len);
+  sc->cert_comp_prefs_len_ = len;
+
+  // Cache pre-compressed cert data for SNI context switches.
+  // setSniContext uses SSL_use_certificate which doesn't carry comp_cert data,
+  // so we extract it here and re-apply via SSL_set1_compressed_cert later.
+  sc->compressed_certs_.clear();
+  for (uint32_t i = 0; i < len; i++) {
+    unsigned char* data = nullptr;
+    size_t orig_len = 0;
+    size_t comp_len =
+        SSL_CTX_get1_compressed_cert(sc->ctx_.get(), algs[i], &data, &orig_len);
+    if (comp_len > 0 && data != nullptr) {
+      sc->compressed_certs_.push_back(
+          {algs[i],
+           std::vector<unsigned char>(data, data + comp_len),
+           orig_len});
+      OPENSSL_free(data);
+    }
+  }
+#else
+  return THROW_ERR_CRYPTO_UNSUPPORTED_OPERATION(
+      env, "Certificate compression is not supported by this OpenSSL build");
+#endif
+}
+
 void SecureContext::Close(const FunctionCallbackInfo<Value>& args) {
   SecureContext* sc;
   ASSIGN_OR_RETURN_UNWRAP(&sc, args.This());

src/crypto/crypto_context.h

@@ -10,6 +10,8 @@
 #include "memory_tracker.h"
 #include "v8.h"
 
+#include <vector>
+
 namespace node {
 namespace crypto {
 // A maxVersion of 0 means "any", but OpenSSL may support TLS versions that
@@ -47,6 +49,27 @@ class SecureContext final : public BaseObject {
   // the SecureContext.
   ncrypto::SSLCtxPointer& ctx() { return ctx_; }
 
+#ifndef OPENSSL_NO_COMP_ALG
+  bool HasCertCompression() const {
+    return cert_comp_prefs_len_ > 0;
+  }
+  int* CertCompPrefs() {
+    return cert_comp_prefs_;
+  }
+  size_t CertCompPrefsLen() const {
+    return cert_comp_prefs_len_;
+  }
+
+  struct CompressedCertData {
+    int algorithm;
+    std::vector<unsigned char> data;
+    size_t orig_length;
+  };
+  const std::vector<CompressedCertData>& CompressedCerts() const {
+    return compressed_certs_;
+  }
+#endif
+
   ncrypto::SSLPointer CreateSSL();
 
   void SetGetSessionCallback(GetSessionCb cb);
@@ -107,6 +130,8 @@ class SecureContext final : public BaseObject {
       const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetSessionTimeout(
       const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void SetCertificateCompression(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetMinProto(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetMaxProto(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void GetMinProto(const v8::FunctionCallbackInfo<v8::Value>& args);
@@ -157,6 +182,12 @@ class SecureContext final : public BaseObject {
   unsigned char ticket_key_name_[16];
   unsigned char ticket_key_aes_[16];
   unsigned char ticket_key_hmac_[16];
+
+#ifndef OPENSSL_NO_COMP_ALG
+  int cert_comp_prefs_[TLSEXT_comp_cert_limit] = {};
+  size_t cert_comp_prefs_len_ = 0;
+  std::vector<CompressedCertData> compressed_certs_;
+#endif
 };
 
 int SSL_CTX_use_certificate_chain(SSL_CTX* ctx,

src/crypto/crypto_tls.cc

@@ -1614,6 +1614,24 @@ void TLSWrap::CertCbDone(const FunctionCallbackInfo<Value>& args) {
       unsigned long err = ERR_get_error();  // NOLINT(runtime/int)
       return ThrowCryptoError(env, err, "CertCbDone");
     }
+    // setSniContext copies the cert via SSL_use_certificate which does not
+    // carry over pre-compressed certificate data (comp_cert). If the new
+    // context has certificate compression configured, set the compression
+    // preferences on this connection and apply the cached compressed cert
+    // data so the server can send CompressedCertificate messages.
+#ifndef OPENSSL_NO_COMP_ALG
+    if (sc->HasCertCompression()) {
+      SSL_set1_cert_comp_preference(
+          w->ssl_.get(), sc->CertCompPrefs(), sc->CertCompPrefsLen());
+      for (const auto& cc : sc->CompressedCerts()) {
+        SSL_set1_compressed_cert(w->ssl_.get(),
+                                 cc.algorithm,
+                                 const_cast<unsigned char*>(cc.data.data()),
+                                 cc.data.size(),
+                                 cc.orig_length);
+      }
+    }
+#endif
   } else if (ctx->IsObject()) {
     // Failure: incorrect SNI context object
     Local<Value> err = Exception::TypeError(env->sni_context_err_string());