From 1fca69c263ec10abc03281b13628b9ec541956ba Mon Sep 17 00:00:00 2001
From: Sam Roberts <vieuxtech@gmail.com>
Date: Wed, 21 Dec 2016 09:33:13 -0800
Subject: [PATCH] doc,test: tls .ca option supports multi-PEM files

PR-URL: https://github.com/nodejs/node/pull/10389
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
---
 doc/api/tls.md                      | 19 +++++++++++++++----
 test/parallel/test-tls-ca-concat.js | 24 ++++++++++++++++++++++++
 2 files changed, 39 insertions(+), 4 deletions(-)
 create mode 100644 test/parallel/test-tls-ca-concat.js

diff --git a/doc/api/tls.md b/doc/api/tls.md
index 64fd343c0449d5..f6bc19da78d264 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -909,10 +909,21 @@ added: v0.11.13
     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.
-  * `ca`{string|string[]|Buffer|Buffer[]} Optional CA certificates to trust.
-    Default is the well-known CAs from Mozilla. When connecting to peers that
-    use certificates issued privately, or self-signed, the private root CA or
-    self-signed certificate must be provided to verify the peer.
+  * `ca` {string|string[]|Buffer|Buffer[]} Optionally override the trusted CA
+    certificates. Default is to trust the well-known CAs curated by Mozilla.
+    Mozilla's CAs are completely replaced when CAs are explicitly specified
+    using this option. The value can be a string or Buffer, or an Array of
+    strings and/or Buffers. Any string or Buffer can contain multiple PEM CAs
+    concatenated together. The peer's certificate must be chainable to a CA
+    trusted by the server for the connection to be authenticated.  When using
+    certificates that are not chainable to a well-known CA, the certificate's CA
+    must be explicitly specified as a trusted or the connection will fail to
+    authenticate.
+    If the peer uses a certificate that doesn't match or chain to one of the
+    default CAs, use the `ca` option to provide a CA certificate that the peer's
+    certificate can match or chain to.
+    For self-signed certificates, the certificate is its own CA, and must be
+    provided.
   * `crl` {string|string[]|Buffer|Buffer[]} Optional PEM formatted
     CRLs (Certificate Revocation Lists).
   * `ciphers` {string} Optional cipher suite specification, replacing the
diff --git a/test/parallel/test-tls-ca-concat.js b/test/parallel/test-tls-ca-concat.js
new file mode 100644
index 00000000000000..65c837bed9dc37
--- /dev/null
+++ b/test/parallel/test-tls-ca-concat.js
@@ -0,0 +1,24 @@
+'use strict';
+const common = require('../common');
+
+// Check ca option can contain concatenated certs by prepending an unrelated
+// non-CA cert and showing that agent6's CA root is still found.
+
+const join = require('path').join;
+const {
+  assert, connect, keys
+} = require(join(common.fixturesDir, 'tls-connect'))();
+
+connect({
+  client: {
+    checkServerIdentity: (servername, cert) => { },
+    ca: keys.agent1.cert + '\n' + keys.agent6.ca,
+  },
+  server: {
+    cert: keys.agent6.cert,
+    key: keys.agent6.key,
+  },
+}, function(err, pair, cleanup) {
+  assert.ifError(err);
+  return cleanup();
+});