tls: add 'as' option to getCACertificates() for X509Certificate output

Author: haramj

doc/api/tls.md

@@ -2308,21 +2308,25 @@ const additionalCerts = ['-----BEGIN CERTIFICATE-----\n...'];
 tls.setDefaultCACertificates([...currentCerts, ...additionalCerts]);
 ```
 
-## `tls.getCACertificates([type])`
+## `tls.getCACertificates([options])`
 
 <!-- YAML
 added:
   - v23.10.0
   - v22.15.0
 -->
 
-* `type` {string|undefined} The type of CA certificates that will be returned. Valid values
-  are `"default"`, `"system"`, `"bundled"` and `"extra"`.
-  **Default:** `"default"`.
-* Returns: {string\[]} An array of PEM-encoded certificates. The array may contain duplicates
-  if the same certificate is repeatedly stored in multiple sources.
+* `options` {string|Object|undefined}\
+  Optional. If a string, it is treated as the `type` of certificates to return.\
+  If an object, it may contain:
+  * `type` {string} The type of CA certificates to return. One of `"default"`, `"system"`, `"bundled"`, or `"extra"`.\
+    **Default:** `"default"`.
+  * `as` {string} The format of returned certificates. One of:
+    * `"buffer"` (default): Returns an array of certificate data as `Buffer` objects.
+    * `"x509"`: Returns an array of \[`X509Certificate`]\[] instances.
 
-Returns an array containing the CA certificates from various sources, depending on `type`:
+* Returns: {Array.\<Buffer|X509Certificate>}\
+  An array of certificates in the specified format.
 
 * `"default"`: return the CA certificates that will be used by the Node.js TLS clients by default.
   * When [`--use-bundled-ca`][] is enabled (default), or [`--use-openssl-ca`][] is not enabled,
@@ -2331,11 +2335,14 @@ Returns an array containing the CA certificates from various sources, depending
     trusted store.
   * When [`NODE_EXTRA_CA_CERTS`][] is used, this would also include certificates loaded from the specified
     file.
+
 * `"system"`: return the CA certificates that are loaded from the system's trusted store, according
   to rules set by [`--use-system-ca`][]. This can be used to get the certificates from the system
   when [`--use-system-ca`][] is not enabled.
+
 * `"bundled"`: return the CA certificates from the bundled Mozilla CA store. This would be the same
   as [`tls.rootCertificates`][].
+
 * `"extra"`: return the CA certificates loaded from [`NODE_EXTRA_CA_CERTS`][]. It's an empty array if
   [`NODE_EXTRA_CA_CERTS`][] is not set.
 

lib/tls.js

@@ -61,6 +61,7 @@ const { canonicalizeIP } = internalBinding('cares_wrap');
 const tlsCommon = require('internal/tls/common');
 const tlsWrap = require('internal/tls/wrap');
 const { validateString } = require('internal/validators');
+const { X509Certificate } = require('crypto');
 
 // Allow {CLIENT_RENEG_LIMIT} client-initiated session renegotiations
 // every {CLIENT_RENEG_WINDOW} seconds. An error event is emitted if more
@@ -164,23 +165,32 @@ function cacheDefaultCACertificates() {
   return defaultCACertificates;
 }
 
-// TODO(joyeecheung): support X509Certificate output?
-function getCACertificates(type = 'default') {
+function getCACertificates(options = {}) {
+  if (typeof options === 'string') {
+    options = { type: options };
+  } else if (typeof options !== 'object' || options === null) {
+    throw new ERR_INVALID_ARG_TYPE('options', ['string', 'object'], options);
+  }
+
+  const { type = 'default', as = 'buffer' } = options;
   validateString(type, 'type');
 
+  let certs;
   switch (type) {
-    case 'default':
-      return cacheDefaultCACertificates();
-    case 'bundled':
-      return cacheBundledRootCertificates();
-    case 'system':
-      return cacheSystemCACertificates();
-    case 'extra':
-      return cacheExtraCACertificates();
-    default:
-      throw new ERR_INVALID_ARG_VALUE('type', type);
+    case 'default': certs = cacheDefaultCACertificates(); break;
+    case 'bundled': certs = cacheBundledRootCertificates(); break;
+    case 'system': certs = cacheSystemCACertificates(); break;
+    case 'extra': certs = cacheExtraCACertificates(); break;
+    default: throw new ERR_INVALID_ARG_VALUE('type', type);
+  }
+
+  if (as === 'x509') {
+    return certs.map((cert) => new X509Certificate(cert));
   }
+
+  return certs;
 }
+
 exports.getCACertificates = getCACertificates;
 
 function setDefaultCACertificates(certs) {

test/parallel/test-tls-get-ca-certificates-x509-option.js

@@ -0,0 +1,23 @@
+'use strict';
+const common = require('../common');
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+
+const assert = require('assert');
+const tls = require('tls');
+const { X509Certificate } = require('crypto');
+
+function testX509Option() {
+  const certs = tls.getCACertificates({ type: 'default', as: 'x509' });
+
+  assert.ok(Array.isArray(certs), 'should return an array');
+  assert.ok(certs.length > 0, 'should return non-empty array');
+  assert.ok(certs[0] instanceof X509Certificate,
+            'each cert should be instance of X509Certificate');
+
+  assert.match(certs[0].serialNumber, /^[0-9A-F]+$/i, 'serialNumber should be hex string');
+}
+
+testX509Option();
+
+console.log('Test passed: getCACertificates with as: "x509"');