crypto: add tls.setDefaultCACertificates()

This API allows dynamically configuring CA certificates that
will be used by the Node.js TLS clients by default.

Once called, the provided certificates will become the default CA
certificate list returned by `tls.getCACertificates('default')` and
used by TLS connections that don't specify their own CA certificates.

This function only affects the current Node.js thread.

Author: joyeecheung

doc/api/tls.md

@@ -2260,6 +2260,54 @@ openssl pkcs12 -certpbe AES-256-CBC -export -out client-cert.pem \
 The server can be tested by connecting to it using the example client from
 [`tls.connect()`][].
 
+## `tls.setDefaultCACertificates(certs)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `certs` {string\[]|ArrayBufferView\[]} An array of CA certificates in PEM format.
+
+Sets the default CA certificates used by Node.js TLS clients. If the provided
+certificates are parsed successfully, they will become the default CA
+certificate list returned by [`tls.getCACertificates()`][] and used
+by subsequent TLS connections that don't specify their own CA certificates.
+The certificates will be deduplicated before being set as the default.
+
+This function only affects the current Node.js thread. Previous
+sessions cached by the HTTPS agent won't be affected by this change, so
+this method should be called before any unwanted cachable TLS connections are
+made.
+
+To use system CA certificates as the default:
+
+```cjs
+const tls = require('node:tls');
+tls.setDefaultCACertificates(tls.getCACertificates('system'));
+```
+
+```mjs
+import tls from 'node:tls';
+tls.setDefaultCACertificates(tls.getCACertificates('system'));
+```
+
+This function completely replaces the default CA certificate list. To add additional
+certificates to the existing defaults, get the current certificates and append to them:
+
+```cjs
+const tls = require('node:tls');
+const currentCerts = tls.getCACertificates('default');
+const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
+tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);
+```
+
+```mjs
+import tls from 'node:tls';
+const currentCerts = tls.getCACertificates('default');
+const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
+tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);
+```
+
 ## `tls.getCACertificates([type])`
 
 <!-- YAML

lib/tls.js

@@ -37,6 +37,7 @@ const {
   ERR_TLS_CERT_ALTNAME_INVALID,
   ERR_OUT_OF_RANGE,
   ERR_INVALID_ARG_VALUE,
+  ERR_INVALID_ARG_TYPE,
 } = require('internal/errors').codes;
 const internalUtil = require('internal/util');
 internalUtil.assertCrypto();
@@ -51,6 +52,8 @@ const {
   getBundledRootCertificates,
   getExtraCACertificates,
   getSystemCACertificates,
+  resetRootCertStore,
+  getUserRootCertificates,
   getSSLCiphers,
 } = internalBinding('crypto');
 const { Buffer } = require('buffer');
@@ -122,8 +125,17 @@ function cacheSystemCACertificates() {
 }
 
 let defaultCACertificates;
+let hasResetDefaultCACertificates = false;
+
 function cacheDefaultCACertificates() {
   if (defaultCACertificates) { return defaultCACertificates; }
+
+  if (hasResetDefaultCACertificates) {
+    defaultCACertificates = getUserRootCertificates();
+    ObjectFreeze(defaultCACertificates);
+    return defaultCACertificates;
+  }
+
   defaultCACertificates = [];
 
   if (!getOptionValue('--use-openssl-ca')) {
@@ -171,6 +183,26 @@ function getCACertificates(type = 'default') {
 }
 exports.getCACertificates = getCACertificates;
 
+function setDefaultCACertificates(certs) {
+  if (!ArrayIsArray(certs)) {
+    throw new ERR_INVALID_ARG_TYPE('certs', 'Array', certs);
+  }
+
+  // Verify that all elements in the array are strings
+  for (let i = 0; i < certs.length; i++) {
+    if (typeof certs[i] !== 'string' && !isArrayBufferView(certs[i])) {
+      throw new ERR_INVALID_ARG_TYPE(
+        `certs[${i}]`, ['string', 'ArrayBufferView'], certs[i]);
+    }
+  }
+
+  resetRootCertStore(certs);
+  defaultCACertificates = undefined; // Reset the cached default certificates
+  hasResetDefaultCACertificates = true;
+}
+
+exports.setDefaultCACertificates = setDefaultCACertificates;
+
 // Convert protocols array into valid OpenSSL protocols list
 // ("\x06spdy/2\x08http/1.1\x08http/1.0")
 function convertProtocols(protocols) {

src/crypto/crypto_context.cc

@@ -27,6 +27,8 @@
 #include <wincrypt.h>
 #endif
 
+#include <set>
+
 namespace node {
 
 using ncrypto::BignumPointer;
@@ -83,10 +85,28 @@ static std::atomic<bool> has_cached_bundled_root_certs{false};
 static std::atomic<bool> has_cached_system_root_certs{false};
 static std::atomic<bool> has_cached_extra_root_certs{false};
 
+// Used for sets of X509.
+struct X509Less {
+  bool operator()(const X509* lhs, const X509* rhs) const noexcept {
+    return X509_cmp(const_cast<X509*>(lhs), const_cast<X509*>(rhs)) < 0;
+  }
+};
+using X509Set = std::set<X509*, X509Less>;
+
+// Per-thread root cert store. See NewRootCertStore() on what it contains.
+static thread_local X509_STORE* root_cert_store = nullptr;
+// If the user calls tls.setDefaultCACertificates() this will be used
+// to hold the user-provided certificates, the root_cert_store and any new
+// copy generated by NewRootCertStore() will then contain the certificates
+// from this set.
+static thread_local std::unique_ptr<X509Set> root_certs_from_users;
+
 X509_STORE* GetOrCreateRootCertStore() {
-  // Guaranteed thread-safe by standard, just don't use -fno-threadsafe-statics.
-  static X509_STORE* store = NewRootCertStore();
-  return store;
+  if (root_cert_store != nullptr) {
+    return root_cert_store;
+  }
+  root_cert_store = NewRootCertStore();
+  return root_cert_store;
 }
 
 // Takes a string or buffer and loads it into a BIO.
@@ -227,14 +247,11 @@ int SSL_CTX_use_certificate_chain(SSL_CTX* ctx,
                                        issuer);
 }
 
-static unsigned long LoadCertsFromFile(  // NOLINT(runtime/int)
+static unsigned long LoadCertsFromBIO(  // NOLINT(runtime/int)
     std::vector<X509*>* certs,
-    const char* file) {
+    BIOPointer bio) {
   MarkPopErrorOnReturn mark_pop_error_on_return;
 
-  auto bio = BIOPointer::NewFile(file, "r");
-  if (!bio) return ERR_get_error();
-
   while (X509* x509 = PEM_read_bio_X509(
              bio.get(), nullptr, NoPasswordCallback, nullptr)) {
     certs->push_back(x509);
@@ -250,6 +267,17 @@ static unsigned long LoadCertsFromFile(  // NOLINT(runtime/int)
   }
 }
 
+static unsigned long LoadCertsFromFile(  // NOLINT(runtime/int)
+    std::vector<X509*>* certs,
+    const char* file) {
+  MarkPopErrorOnReturn mark_pop_error_on_return;
+
+  auto bio = BIOPointer::NewFile(file, "r");
+  if (!bio) return ERR_get_error();
+
+  return LoadCertsFromBIO(certs, std::move(bio));
+}
+
 // Indicates the trust status of a certificate.
 enum class TrustStatus {
   // Trust status is unknown / uninitialized.
@@ -831,11 +859,24 @@ static std::vector<X509*>& GetExtraCACertificates() {
 //    NODE_EXTRA_CA_CERTS are cached after first load. Certificates
 //    from --use-system-ca are not cached and always reloaded from
 //    disk.
+// 8. If users have reset the root cert store by calling
+//    tls.setDefaultCACertificates(), the store will be populated with
+//    the certificates provided by users.
 // TODO(joyeecheung): maybe these rules need a bit of consolidation?
 X509_STORE* NewRootCertStore() {
   X509_STORE* store = X509_STORE_new();
   CHECK_NOT_NULL(store);
 
+  // If the root cert store is already reset by users through
+  // tls.setDefaultCACertificates(), just create a copy from the
+  // user-provided certificates.
+  if (root_certs_from_users != nullptr) {
+    for (X509* cert : *root_certs_from_users) {
+      CHECK_EQ(1, X509_STORE_add_cert(store, cert));
+    }
+    return store;
+  }
+
 #ifdef NODE_OPENSSL_SYSTEM_CERT_PATH
   if constexpr (sizeof(NODE_OPENSSL_SYSTEM_CERT_PATH) > 1) {
     ERR_set_mark();
@@ -903,14 +944,57 @@ void GetBundledRootCertificates(const FunctionCallbackInfo<Value>& args) {
       Array::New(env->isolate(), result, arraysize(root_certs)));
 }
 
+bool ArrayOfStringsToX509s(Local<Context> context,
+                           Local<Array> cert_array,
+                           std::vector<X509*>* certs) {
+  ClearErrorOnReturn clear_error_on_return;
+  Isolate* isolate = context->GetIsolate();
+  Environment* env = Environment::GetCurrent(context);
+  uint32_t array_length = cert_array->Length();
+
+  std::vector<v8::Global<Value>> cert_items;
+  if (FromV8Array(context, cert_array, &cert_items).IsNothing()) {
+    return false;
+  }
+
+  for (uint32_t i = 0; i < array_length; i++) {
+    Local<Value> cert_val = cert_items[i].Get(isolate);
+    // Parse the PEM certificate.
+    BIOPointer bio(LoadBIO(env, cert_val));
+    if (!bio) {
+      ThrowCryptoError(env, ERR_get_error(), "Failed to load certificate data");
+      return false;
+    }
+
+    // Read all certificates from this PEM string
+    size_t start = certs->size();
+    auto err = LoadCertsFromBIO(certs, std::move(bio));
+    if (err != 0) {
+      size_t end = certs->size();
+      // Clean up any certificates we've already parsed upon failure.
+      for (size_t j = start; j < end; ++j) {
+        X509_free((*certs)[j]);
+      }
+      ThrowCryptoError(env, err, "Failed to parse certificate");
+      return false;
+    }
+  }
+
+  return true;
+}
+
+template <typename It>
 MaybeLocal<Array> X509sToArrayOfStrings(Environment* env,
-                                        const std::vector<X509*>& certs) {
+                                        It first,
+                                        It last,
+                                        size_t size) {
   ClearErrorOnReturn clear_error_on_return;
   EscapableHandleScope scope(env->isolate());
 
-  LocalVector<Value> result(env->isolate(), certs.size());
-  for (size_t i = 0; i < certs.size(); ++i) {
-    X509View view(certs[i]);
+  LocalVector<Value> result(env->isolate(), size);
+  size_t i = 0;
+  for (It cur = first; cur != last; ++cur, ++i) {
+    X509View view(*cur);
     auto pem_bio = view.toPEM();
     if (!pem_bio) {
       ThrowCryptoError(env, ERR_get_error(), "X509 to PEM conversion");
@@ -935,10 +1019,87 @@ MaybeLocal<Array> X509sToArrayOfStrings(Environment* env,
   return scope.Escape(Array::New(env->isolate(), result.data(), result.size()));
 }
 
+void GetUserRootCertificates(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  CHECK_NOT_NULL(root_certs_from_users);
+  Local<Array> results;
+  if (X509sToArrayOfStrings(env,
+                            root_certs_from_users->begin(),
+                            root_certs_from_users->end(),
+                            root_certs_from_users->size())
+          .ToLocal(&results)) {
+    args.GetReturnValue().Set(results);
+  }
+}
+
+void ResetRootCertStore(const FunctionCallbackInfo<Value>& args) {
+  Local<Context> context = args.GetIsolate()->GetCurrentContext();
+  CHECK(args[0]->IsArray());
+  Local<Array> cert_array = args[0].As<Array>();
+
+  if (cert_array->Length() == 0) {
+    // If the array is empty, just clear the user certs and reset the store.
+    if (root_cert_store != nullptr) {
+      X509_STORE_free(root_cert_store);
+      root_cert_store = nullptr;
+    }
+
+    // Free any existing certificates in the old set.
+    if (root_certs_from_users != nullptr) {
+      for (X509* cert : *root_certs_from_users) {
+        X509_free(cert);
+      }
+    }
+    root_certs_from_users = std::make_unique<X509Set>();
+    return;
+  }
+
+  // Parse certificates from the array
+  std::unique_ptr<std::vector<X509*>> certs =
+      std::make_unique<std::vector<X509*>>();
+  if (!ArrayOfStringsToX509s(context, cert_array, certs.get())) {
+    // Error already thrown by ArrayOfStringsToX509s
+    return;
+  }
+
+  if (certs->empty()) {
+    Environment* env = Environment::GetCurrent(context);
+    return THROW_ERR_CRYPTO_OPERATION_FAILED(
+        env, "No valid certificates found in the provided array");
+  }
+
+  auto new_set = std::make_unique<X509Set>();
+  for (X509* cert : *certs) {
+    auto [it, inserted] = new_set->insert(cert);
+    if (!inserted) {  // Free duplicate certificates from the vector.
+      X509_free(cert);
+    }
+  }
+
+  // Free any existing certificates in the old set.
+  if (root_certs_from_users != nullptr) {
+    for (X509* cert : *root_certs_from_users) {
+      X509_free(cert);
+    }
+  }
+  std::swap(root_certs_from_users, new_set);
+
+  // Reset the global root cert store and create a new one with the
+  // certificates.
+  if (root_cert_store != nullptr) {
+    X509_STORE_free(root_cert_store);
+  }
+
+  // TODO(joyeecheung): we can probably just reset it to nullptr
+  // and let the next call to NewRootCertStore() create a new one.
+  root_cert_store = NewRootCertStore();
+}
+
 void GetSystemCACertificates(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   Local<Array> results;
-  if (X509sToArrayOfStrings(env, GetSystemStoreCACertificates())
+  std::vector<X509*>& certs = GetSystemStoreCACertificates();
+  if (X509sToArrayOfStrings(env, certs.begin(), certs.end(), certs.size())
           .ToLocal(&results)) {
     args.GetReturnValue().Set(results);
   }
@@ -950,7 +1111,9 @@ void GetExtraCACertificates(const FunctionCallbackInfo<Value>& args) {
     return args.GetReturnValue().Set(Array::New(env->isolate()));
   }
   Local<Array> results;
-  if (X509sToArrayOfStrings(env, GetExtraCACertificates()).ToLocal(&results)) {
+  std::vector<X509*>& certs = GetExtraCACertificates();
+  if (X509sToArrayOfStrings(env, certs.begin(), certs.end(), certs.size())
+          .ToLocal(&results)) {
     args.GetReturnValue().Set(results);
   }
 }
@@ -1046,6 +1209,9 @@ void SecureContext::Initialize(Environment* env, Local<Object> target) {
       context, target, "getSystemCACertificates", GetSystemCACertificates);
   SetMethodNoSideEffect(
       context, target, "getExtraCACertificates", GetExtraCACertificates);
+  SetMethod(context, target, "resetRootCertStore", ResetRootCertStore);
+  SetMethodNoSideEffect(
+      context, target, "getUserRootCertificates", GetUserRootCertificates);
 }
 
 void SecureContext::RegisterExternalReferences(
@@ -1088,6 +1254,8 @@ void SecureContext::RegisterExternalReferences(
   registry->Register(GetBundledRootCertificates);
   registry->Register(GetSystemCACertificates);
   registry->Register(GetExtraCACertificates);
+  registry->Register(ResetRootCertStore);
+  registry->Register(GetUserRootCertificates);
 }
 
 SecureContext* SecureContext::Create(Environment* env) {