Skip to content

Commit a31378a

Browse files
pimterryaduh95
pimterry
authored and
aduh95
committed
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. Signed-off-by: Tim Perry <[email protected]> PR-URL: #62217 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 89ceffa commit a31378a

10 files changed

Lines changed: 513 additions & 6 deletions

File tree

‎deps/openssl/openssl.gyp‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,6 @@
1919
{
2020
'target_name': 'openssl',
2121
'type': '<(library)',
22-
'dependencies': [
23-
'../zlib/zlib.gyp:zlib',
24-
'../brotli/brotli.gyp:brotli',
25-
'../zstd/zstd.gyp:zstd',
26-
],
2722
'includes': ['./openssl_common.gypi'],
2823
'defines': [
2924
# Compile out hardware engines. Most are stubs that dynamically load
@@ -54,6 +49,15 @@
5449
'MODULESDIR="<(modules_dir)"',
5550
]
5651
}],
52+
['node_shared_zlib=="false"', {
53+
'dependencies': [ '../zlib/zlib.gyp:zlib' ],
54+
}],
55+
['node_shared_brotli=="false"', {
56+
'dependencies': [ '../brotli/brotli.gyp:brotli' ],
57+
}],
58+
['node_shared_zstd=="false"', {
59+
'dependencies': [ '../zstd/zstd.gyp:zstd' ],
60+
}],
5761
],
5862
'direct_dependent_settings': {
5963
'include_dirs': [ 'openssl/include', 'openssl/crypto/include']

‎doc/api/tls.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1895,6 +1895,9 @@ argument.
18951895
<!-- YAML
18961896
added: v0.11.13
18971897
changes:
1898+
- version: REPLACEME
1899+
pr-url: https://github.com/nodejs/node/pull/62217
1900+
description: The `certificateCompression` option has been added.
18981901
- version:
18991902
- v22.9.0
19001903
- v20.18.0
@@ -1988,6 +1991,12 @@ changes:
19881991
the same order as their private keys in `key`. If the intermediate
19891992
certificates are not provided, the peer will not be able to validate the
19901993
certificate, and the handshake will fail.
1994+
* `certificateCompression` {string\[]} An array of supported certificate
1995+
compression algorithm names, in preference order. Supported values are
1996+
`'zlib'`, `'brotli'`, and `'zstd'`. When set, enables TLS certificate
1997+
compression ([RFC 8879][]) which compresses certificates during the TLS
1998+
handshake, reducing handshake size. Only effective with TLSv1.3.
1999+
**Default:** `[]` (disabled).
19912000
* `sigalgs` {string} Colon-separated list of supported signature algorithms.
19922001
The list can contain digest algorithms (`SHA256`, `MD5` etc.), public key
19932002
algorithms (`RSA-PSS`, `ECDSA` etc.), combination of both (e.g
@@ -2376,6 +2385,25 @@ TLSv1.2 and below.
23762385
console.log(tls.getCiphers()); // ['aes128-gcm-sha256', 'aes128-sha', ...]
23772386
```
23782387

2388+
## `tls.getCertificateCompressionAlgorithms()`
2389+
2390+
<!-- YAML
2391+
added: REPLACEME
2392+
-->
2393+
2394+
* Returns: {string\[]}
2395+
2396+
Returns an array with the names of the RFC 8879 certificate compression
2397+
algorithms supported by the current OpenSSL build, suitable for use in the
2398+
`certificateCompression` option of [`tls.createSecureContext()`][]. Possible
2399+
values include `'zlib'`, `'brotli'`, and `'zstd'`.
2400+
2401+
The array is empty when certificate compression is unavailable.
2402+
2403+
```js
2404+
console.log(tls.getCertificateCompressionAlgorithms()); // ['zlib', 'brotli', 'zstd']
2405+
```
2406+
23792407
## `tls.rootCertificates`
23802408

23812409
<!-- YAML
@@ -2467,6 +2495,7 @@ added: v0.11.3
24672495
[RFC 4279]: https://tools.ietf.org/html/rfc4279
24682496
[RFC 5077]: https://tools.ietf.org/html/rfc5077
24692497
[RFC 5929]: https://tools.ietf.org/html/rfc5929
2498+
[RFC 8879]: https://tools.ietf.org/html/rfc8879
24702499
[SSL_METHODS]: https://www.openssl.org/docs/man1.1.1/man7/ssl.html#Dealing-with-Protocol-Methods
24712500
[Session Resumption]: #session-resumption
24722501
[Stream]: stream.md#stream

‎lib/internal/tls/secure-context.js‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,7 @@ function configSecureContext(context, options = kEmptyObject, name = 'options')
133133
allowPartialTrustChain,
134134
ca,
135135
cert,
136+
certificateCompression,
136137
ciphers = getDefaultCiphers(),
137138
clientCertEngine,
138139
crl,
@@ -210,6 +211,43 @@ function configSecureContext(context, options = kEmptyObject, name = 'options')
210211
}
211212
}
212213

214+
if (certificateCompression != null) {
215+
if (!ArrayIsArray(certificateCompression)) {
216+
throw new ERR_INVALID_ARG_TYPE(
217+
`${name}.certificateCompression`, 'Array', certificateCompression);
218+
}
219+
220+
if (certificateCompression.length > 0) {
221+
// Pack length + algorithm IDs into a single Uint32 for a cheap
222+
// JS->C++ crossing. Layout:
223+
// bits 0-7 : length (1..3)
224+
// bits 8-15: alg id at position 0
225+
// bits 16-23: alg id at position 1
226+
// bits 24-31: alg id at position 2
227+
// IDs match OpenSSL's TLSEXT_comp_cert_zlib (1), _brotli (2), _zstd (3)
228+
if (certificateCompression.length > 3) {
229+
throw new ERR_INVALID_ARG_VALUE(
230+
`${name}.certificateCompression`, certificateCompression,
231+
'can specify at most 3 algorithms');
232+
}
233+
let packed = certificateCompression.length;
234+
for (let i = 0; i < certificateCompression.length; i++) {
235+
const algoName = certificateCompression[i];
236+
let id;
237+
if (algoName === 'zlib') id = 1;
238+
else if (algoName === 'brotli') id = 2;
239+
else if (algoName === 'zstd') id = 3;
240+
else {
241+
throw new ERR_INVALID_ARG_VALUE(
242+
`${name}.certificateCompression[${i}]`, algoName,
243+
"must be 'zlib', 'brotli', or 'zstd'");
244+
}
245+
packed |= id << (8 * (i + 1));
246+
}
247+
context.setCertificateCompression(packed);
248+
}
249+
}
250+
213251
if (sigalgs !== undefined && sigalgs !== null) {
214252
validateString(sigalgs, `${name}.sigalgs`);
215253

‎lib/internal/tls/wrap.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1621,6 +1621,7 @@ Server.prototype.setSecureContext = function(options) {
16211621

16221622
this.privateKeyIdentifier = options.privateKeyIdentifier;
16231623
this.privateKeyEngine = options.privateKeyEngine;
1624+
this.certificateCompression = options.certificateCompression;
16241625

16251626
this._sharedCreds = tls.createSecureContext({
16261627
pfx: this.pfx,
@@ -1644,6 +1645,7 @@ Server.prototype.setSecureContext = function(options) {
16441645
sessionTimeout: this.sessionTimeout,
16451646
privateKeyIdentifier: this.privateKeyIdentifier,
16461647
privateKeyEngine: this.privateKeyEngine,
1648+
certificateCompression: this.certificateCompression,
16471649
});
16481650
};
16491651

‎lib/tls.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ const {
4747
resetRootCertStore,
4848
getUserRootCertificates,
4949
getSSLCiphers,
50+
getCertificateCompressionAlgorithms,
5051
startLoadingCertificatesOffThread,
5152
} = internalBinding('crypto');
5253

@@ -113,6 +114,10 @@ exports.getCiphers = internalUtil.cachedResult(
113114
() => internalUtil.filterDuplicateStrings(getSSLCiphers(), true),
114115
);
115116

117+
exports.getCertificateCompressionAlgorithms = internalUtil.cachedResult(
118+
() => getCertificateCompressionAlgorithms(),
119+
);
120+
116121
let bundledRootCertificates;
117122
function cacheBundledRootCertificates() {
118123
bundledRootCertificates ||= ObjectFreeze(getBundledRootCertificates());

‎src/crypto/crypto_context.cc‎

Lines changed: 112 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,10 @@
1212
#include "util.h"
1313
#include "v8.h"
1414

15-
#include <openssl/x509.h>
15+
#include <openssl/comp.h>
1616
#include <openssl/pkcs12.h>
1717
#include <openssl/rand.h>
18+
#include <openssl/x509.h>
1819
#ifndef OPENSSL_NO_ENGINE
1920
#include <openssl/engine.h>
2021
#endif // !OPENSSL_NO_ENGINE
@@ -1308,6 +1309,8 @@ Local<FunctionTemplate> SecureContext::GetConstructorTemplate(
13081309
SetProtoMethod(isolate, tmpl, "setOptions", SetOptions);
13091310
SetProtoMethod(isolate, tmpl, "setSessionIdContext", SetSessionIdContext);
13101311
SetProtoMethod(isolate, tmpl, "setSessionTimeout", SetSessionTimeout);
1312+
SetProtoMethod(
1313+
isolate, tmpl, "setCertificateCompression", SetCertificateCompression);
13111314
SetProtoMethod(isolate, tmpl, "close", Close);
13121315
SetProtoMethod(isolate, tmpl, "loadPKCS12", LoadPKCS12);
13131316
SetProtoMethod(isolate, tmpl, "setTicketKeys", SetTicketKeys);
@@ -1372,6 +1375,10 @@ void SecureContext::Initialize(Environment* env, Local<Object> target) {
13721375
target,
13731376
"startLoadingCertificatesOffThread",
13741377
StartLoadingCertificatesOffThread);
1378+
SetMethodNoSideEffect(context,
1379+
target,
1380+
"getCertificateCompressionAlgorithms",
1381+
GetCertificateCompressionAlgorithms);
13751382
}
13761383

13771384
void SecureContext::RegisterExternalReferences(
@@ -1396,6 +1403,7 @@ void SecureContext::RegisterExternalReferences(
13961403
registry->Register(SetOptions);
13971404
registry->Register(SetSessionIdContext);
13981405
registry->Register(SetSessionTimeout);
1406+
registry->Register(SetCertificateCompression);
13991407
registry->Register(Close);
14001408
registry->Register(LoadPKCS12);
14011409
registry->Register(SetTicketKeys);
@@ -1417,6 +1425,7 @@ void SecureContext::RegisterExternalReferences(
14171425
registry->Register(ResetRootCertStore);
14181426
registry->Register(GetUserRootCertificates);
14191427
registry->Register(StartLoadingCertificatesOffThread);
1428+
registry->Register(GetCertificateCompressionAlgorithms);
14201429
}
14211430

14221431
SecureContext* SecureContext::Create(Environment* env) {
@@ -1554,6 +1563,14 @@ void SecureContext::Init(const FunctionCallbackInfo<Value>& args) {
15541563
env->external_memory_accounter()->Increase(env->isolate(), kExternalSize);
15551564
SSL_CTX_set_app_data(sc->ctx_.get(), sc);
15561565

1566+
// OpenSSL populates cert_comp_prefs with all available algorithms by
1567+
// default when compression libraries are linked. Clear them so that
1568+
// certificate compression (RFC 8879) is always opt-in for now, via
1569+
// the certificateCompression option.
1570+
#ifdef NODE_OPENSSL_HAS_CERT_COMP
1571+
SSL_CTX_set1_cert_comp_preference(sc->ctx_.get(), nullptr, 0);
1572+
#endif
1573+
15571574
// Disable SSLv2 in the case when method == TLS_method() and the
15581575
// cipher list contains SSLv2 ciphers (not the default, should be rare.)
15591576
// The bundled OpenSSL doesn't have SSLv2 support but the system OpenSSL may.
@@ -2059,6 +2076,100 @@ void SecureContext::SetSessionTimeout(const FunctionCallbackInfo<Value>& args) {
20592076
SSL_CTX_set_timeout(sc->ctx_.get(), sessionTimeout);
20602077
}
20612078

2079+
void SecureContext::SetCertificateCompression(
2080+
const FunctionCallbackInfo<Value>& args) {
2081+
SecureContext* sc;
2082+
ASSIGN_OR_RETURN_UNWRAP(&sc, args.This());
2083+
Environment* env = sc->env();
2084+
2085+
CHECK_GE(args.Length(), 1);
2086+
CHECK(args[0]->IsUint32());
2087+
2088+
// Cert compression requires TLS 1.3:
2089+
long max_proto = // NOLINT(runtime/int)
2090+
SSL_CTX_get_max_proto_version(sc->ctx_.get());
2091+
if (max_proto != 0 && max_proto < TLS1_3_VERSION) {
2092+
return THROW_ERR_INVALID_ARG_VALUE(
2093+
env,
2094+
"certificateCompression requires a TLS protocol range that includes "
2095+
"TLSv1.3");
2096+
}
2097+
2098+
#ifdef NODE_OPENSSL_HAS_CERT_COMP
2099+
// JS packs (length | alg0<<8 | alg1<<16 | alg2<<24) into a single Uint32.
2100+
// IDs match TLSEXT_comp_cert_zlib (1), _brotli (2), _zstd (3).
2101+
uint32_t packed = args[0].As<v8::Uint32>()->Value();
2102+
size_t len = packed & 0xff;
2103+
2104+
// TLSEXT_comp_cert_limit is the limit for a zero-terminated algs array,
2105+
// total number of available algs is one fewer.
2106+
constexpr size_t kMaxCompAlgs = TLSEXT_comp_cert_limit - 1;
2107+
if (len == 0 || len > kMaxCompAlgs) {
2108+
return THROW_ERR_INVALID_ARG_VALUE(
2109+
env,
2110+
"certificateCompression must specify fewer than %d algorithms",
2111+
static_cast<int>(kMaxCompAlgs));
2112+
}
2113+
2114+
int algs[kMaxCompAlgs];
2115+
for (size_t i = 0; i < len; i++) {
2116+
algs[i] = (packed >> (8 * (i + 1))) & 0xff;
2117+
}
2118+
if (!SSL_CTX_set1_cert_comp_preference(
2119+
sc->ctx_.get(), algs, static_cast<size_t>(len))) {
2120+
return THROW_ERR_CRYPTO_OPERATION_FAILED(
2121+
env, "Failed to set certificate compression preference");
2122+
}
2123+
2124+
// Pre-compress the loaded certificate(s) for all supported algorithms.
2125+
// Returns 0 when no certificate is loaded (e.g. client-only context) or
2126+
// when compression did not reduce size - both are non-fatal.
2127+
constexpr int kCompressAllAlgs = 0;
2128+
SSL_CTX_compress_certs(sc->ctx_.get(), kCompressAllAlgs);
2129+
2130+
// Store preferences for propagation during SNI context switches.
2131+
memcpy(sc->cert_comp_prefs_, algs, sizeof(int) * len);
2132+
sc->cert_comp_prefs_len_ = len;
2133+
2134+
// Cache pre-compressed cert data for SNI context switches.
2135+
// setSniContext uses SSL_use_certificate which doesn't carry comp_cert data,
2136+
// so we extract it here and re-apply via SSL_set1_compressed_cert later.
2137+
sc->compressed_certs_.clear();
2138+
for (size_t i = 0; i < len; i++) {
2139+
unsigned char* data = nullptr;
2140+
size_t orig_len = 0;
2141+
size_t comp_len =
2142+
SSL_CTX_get1_compressed_cert(sc->ctx_.get(), algs[i], &data, &orig_len);
2143+
ncrypto::DataPointer comp(data, comp_len);
2144+
if (comp_len > 0 && data != nullptr) {
2145+
sc->compressed_certs_.push_back(
2146+
{algs[i],
2147+
std::vector<unsigned char>(data, data + comp_len),
2148+
orig_len});
2149+
}
2150+
}
2151+
#else
2152+
return THROW_ERR_CRYPTO_UNSUPPORTED_OPERATION(
2153+
env, "Certificate compression is not supported by this OpenSSL build");
2154+
#endif
2155+
}
2156+
2157+
void SecureContext::GetCertificateCompressionAlgorithms(
2158+
const FunctionCallbackInfo<Value>& args) {
2159+
Environment* env = Environment::GetCurrent(args);
2160+
LocalVector<Value> algs(env->isolate());
2161+
#ifdef NODE_OPENSSL_HAS_CERT_COMP
2162+
if (BIO_f_zlib() != nullptr)
2163+
algs.push_back(FIXED_ONE_BYTE_STRING(env->isolate(), "zlib"));
2164+
if (BIO_f_brotli() != nullptr)
2165+
algs.push_back(FIXED_ONE_BYTE_STRING(env->isolate(), "brotli"));
2166+
if (BIO_f_zstd() != nullptr)
2167+
algs.push_back(FIXED_ONE_BYTE_STRING(env->isolate(), "zstd"));
2168+
#endif
2169+
args.GetReturnValue().Set(
2170+
Array::New(env->isolate(), algs.data(), algs.size()));
2171+
}
2172+
20622173
void SecureContext::Close(const FunctionCallbackInfo<Value>& args) {
20632174
SecureContext* sc;
20642175
ASSIGN_OR_RETURN_UNWRAP(&sc, args.This());

‎src/crypto/crypto_context.h‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@
1010
#include "memory_tracker.h"
1111
#include "v8.h"
1212

13+
#ifdef NODE_OPENSSL_HAS_CERT_COMP
14+
#include <vector>
15+
#endif
16+
1317
namespace node {
1418
namespace crypto {
1519
// A maxVersion of 0 means "any", but OpenSSL may support TLS versions that
@@ -47,6 +51,27 @@ class SecureContext final : public BaseObject {
4751
// the SecureContext.
4852
ncrypto::SSLCtxPointer& ctx() { return ctx_; }
4953

54+
#ifdef NODE_OPENSSL_HAS_CERT_COMP
55+
bool HasCertCompression() const {
56+
return cert_comp_prefs_len_ > 0;
57+
}
58+
int* CertCompPrefs() {
59+
return cert_comp_prefs_;
60+
}
61+
size_t CertCompPrefsLen() const {
62+
return cert_comp_prefs_len_;
63+
}
64+
65+
struct CompressedCertData {
66+
int algorithm;
67+
std::vector<unsigned char> data;
68+
size_t orig_length;
69+
};
70+
const std::vector<CompressedCertData>& CompressedCerts() const {
71+
return compressed_certs_;
72+
}
73+
#endif
74+
5075
ncrypto::SSLPointer CreateSSL();
5176

5277
void SetGetSessionCallback(GetSessionCb cb);
@@ -106,6 +131,10 @@ class SecureContext final : public BaseObject {
106131
const v8::FunctionCallbackInfo<v8::Value>& args);
107132
static void SetSessionTimeout(
108133
const v8::FunctionCallbackInfo<v8::Value>& args);
134+
static void SetCertificateCompression(
135+
const v8::FunctionCallbackInfo<v8::Value>& args);
136+
static void GetCertificateCompressionAlgorithms(
137+
const v8::FunctionCallbackInfo<v8::Value>& args);
109138
static void SetMinProto(const v8::FunctionCallbackInfo<v8::Value>& args);
110139
static void SetMaxProto(const v8::FunctionCallbackInfo<v8::Value>& args);
111140
static void GetMinProto(const v8::FunctionCallbackInfo<v8::Value>& args);
@@ -156,6 +185,12 @@ class SecureContext final : public BaseObject {
156185
unsigned char ticket_key_name_[16];
157186
unsigned char ticket_key_aes_[16];
158187
unsigned char ticket_key_hmac_[16];
188+
189+
#ifdef NODE_OPENSSL_HAS_CERT_COMP
190+
int cert_comp_prefs_[TLSEXT_comp_cert_limit] = {};
191+
size_t cert_comp_prefs_len_ = 0;
192+
std::vector<CompressedCertData> compressed_certs_;
193+
#endif
159194
};
160195

161196
int SSL_CTX_use_certificate_chain(SSL_CTX* ctx,

0 commit comments

Comments
 (0)