tls: rename 'as' to 'format' in getCACertificates, default 'string'

Author: haramj

doc/api/tls.md

@@ -2326,12 +2326,16 @@ changes:
   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. **Default**: `"buffer"`.
+  * `format` {string} The format of returned certificates. One of `"string"`, `"buffer"`, or `"x509"`.
+    **Default**: `"string"`.
+    * `"string"`: Returns PEM-encoded strings by default. See `encoding` for DER.
     * `"buffer"`: Returns an array of certificate data as `Buffer` objects.
-    * `"x509"`: Returns an array of \[`X509Certificate`]\[] instances.
+    * `"x509"`: Returns an array of [`X509Certificate`][x509certificate] instances.
+  * `encoding` {string} When `format` is `"string"`, the encoding of the returned strings.
+    One of `"pem"` (PEM-encoded) or `"der"` (base64 DER). **Default:** `"pem"`.
 
-* Returns: {Array.\<Buffer|X509Certificate>}
-  An array of certificates in the specified format.
+* Returns: {Array}
+  An array of certificate data in the specified format (Buffer or X509Certificate).
 
 * `"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,
@@ -2465,7 +2469,6 @@ added: v0.11.3
 [Session Resumption]: #session-resumption
 [Stream]: stream.md#stream
 [TLS recommendations]: https://wiki.mozilla.org/Security/Server_Side_TLS
-[X509Certificate]: https://nodejs.org/api/crypto.html#class-x509certificate
 [`'newSession'`]: #event-newsession
 [`'resumeSession'`]: #event-resumesession
 [`'secureConnect'`]: #event-secureconnect
@@ -2513,3 +2516,4 @@ added: v0.11.3
 [cipher list format]: https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-LIST-FORMAT
 [forward secrecy]: https://en.wikipedia.org/wiki/Perfect_forward_secrecy
 [perfect forward secrecy]: #perfect-forward-secrecy
+[x509certificate]: https://nodejs.org/api/crypto.html#class-x509certificate

lib/tls.js

@@ -175,9 +175,17 @@ function getCACertificates(options = {}) {
     throw new ERR_INVALID_ARG_TYPE('options', ['string', 'object'], options);
   }
 
-  const { type = 'default', as = 'buffer' } = options;
+  const {
+    type = 'default',
+    format = 'string',
+    encoding = 'pem',
+  } = options;
+
   validateString(type, 'type');
-  validateOneOf(as, 'as', ['buffer', 'x509']);
+  validateOneOf(format, 'format', ['string', 'buffer', 'x509']);
+  if (format === 'string') {
+    validateOneOf(encoding, 'encoding', ['pem', 'der']);
+  }
 
   let certs;
   switch (type) {
@@ -188,13 +196,38 @@ function getCACertificates(options = {}) {
     default: throw new ERR_INVALID_ARG_VALUE('type', type);
   }
 
-  if (as === 'x509') {
-    return certs.map((cert) => new X509Certificate(cert));
+  if (format === 'string' && encoding === 'pem') {
+    return certs;
+  }
+
+  if (format === 'buffer' || format === 'x509') {
+    const buffers = certs.map((cert) => {
+      if (Buffer.isBuffer(cert)) return cert;
+      if (typeof cert === 'string') {
+        const base64 = cert
+          .replace(/-----BEGIN CERTIFICATE-----/g, '')
+          .replace(/-----END CERTIFICATE-----/g, '')
+          .replace(/\s+/g, '');
+        return Buffer.from(base64, 'base64');
+      }
+      throw new ERR_INVALID_ARG_VALUE('cert', cert);
+    });
+    return (format === 'buffer') ? buffers : buffers.map((buf) => new X509Certificate(buf));
   }
 
-  return certs;
+  return certs.map((cert) => {
+    if (typeof cert === 'string') {
+      const base64 = cert
+        .replace(/-----BEGIN CERTIFICATE-----/g, '')
+        .replace(/-----END CERTIFICATE-----/g, '')
+        .replace(/\s+/g, '');
+      return Buffer.from(base64, 'base64').toString('base64');
+    }
+    return encoding === 'pem' ? cert.toString('utf8') : cert.toString('base64');
+  });
 }
 
+
 exports.getCACertificates = getCACertificates;
 
 function setDefaultCACertificates(certs) {

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

@@ -9,7 +9,7 @@ const tls = require('tls');
 const { X509Certificate } = require('crypto');
 
 {
-  const certs = tls.getCACertificates({ type: 'default', as: 'x509' });
+  const certs = tls.getCACertificates({ type: 'default', format: 'x509' });
 
   assert.ok(Array.isArray(certs), 'should return an array');
   assert.ok(certs.length > 0, 'should return non-empty array');
@@ -24,7 +24,7 @@ const { X509Certificate } = require('crypto');
 }
 
 {
-  const certs = tls.getCACertificates({ type: 'default', as: 'buffer' });
+  const certs = tls.getCACertificates({ type: 'default', format: 'buffer' });
   assert.ok(Array.isArray(certs));
   assert.ok(certs.length > 0);
 
@@ -38,16 +38,15 @@ const { X509Certificate } = require('crypto');
   const certs = tls.getCACertificates({ type: 'default' });
   assert.ok(Array.isArray(certs));
   assert.ok(certs.length > 0);
-
   for (let i = 0; i < certs.length; i++) {
-    assert.ok(Buffer.isBuffer(certs[i]),
-              `cert at index ${i} should be a Buffer`);
+    assert.strictEqual(typeof certs[i], 'string');
+    assert.ok(certs[i].includes('-----BEGIN CERTIFICATE-----'));
   }
 }
 
 {
   assert.throws(() => {
-    tls.getCACertificates({ type: 'default', as: 'invalid' });
+    tls.getCACertificates({ type: 'default', format: 'invalid' });
   }, {
     name: 'TypeError',
     code: 'ERR_INVALID_ARG_VALUE',
@@ -56,7 +55,7 @@ const { X509Certificate } = require('crypto');
 }
 
 {
-  const certs = tls.getCACertificates({ as: 'buffer' });
+  const certs = tls.getCACertificates({ format: 'buffer' });
   assert.ok(Array.isArray(certs));
   assert.ok(certs.length > 0);
 
@@ -68,10 +67,20 @@ const { X509Certificate } = require('crypto');
 
 {
   assert.throws(() => {
-    tls.getCACertificates({ type: 'invalid', as: 'buffer' });
+    tls.getCACertificates({ type: 'invalid', format: 'buffer' });
   }, {
     name: 'TypeError',
     code: 'ERR_INVALID_ARG_VALUE',
     message: "The argument 'type' is invalid. Received 'invalid'"
   });
 }
+
+{
+  const certs = tls.getCACertificates({ format: 'string', encoding: 'der' });
+  assert.ok(Array.isArray(certs));
+  assert.ok(certs.length > 0);
+  for (let i = 0; i < certs.length; i++) {
+    assert.strictEqual(typeof certs[i], 'string');
+    assert.ok(/^[A-Za-z0-9+/]+=*$/.test(certs[i]), 'should be base64 string');
+  }
+}