From 1030afcf8e9f8747da6ae8bd7af9d42658ec8252 Mon Sep 17 00:00:00 2001
From: "wacky6.AriesMBP" <416707889@qq.com>
Date: Thu, 9 Jun 2016 02:47:14 +0800
Subject: [PATCH] doc: clarify tls.createServer's {cert, ca}

1. clarity cert to match bottom-half
in src/node_crypto.cc setCert() calls SSL_CTX_use_certificate_chain()

2. clarity ca is to be used with requestCert

Previously, nothing is mentioned about certificate chain, this may be
confusing to beginners. They may pass intermediate certificates to
ca option.

If requestCert is false, this won't cause any problem. As bottom-half
will try to find and insert intermediate certificates from ca store.
---
 doc/api/tls.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/doc/api/tls.md b/doc/api/tls.md
index caec8a7b123c57..222bf5de1d2b79 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -851,12 +851,12 @@ publicly trusted list of CAs as given in
   * `passphrase` {string} A string containing the passphrase for the private
     key or pfx.
   * `cert` {string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of
-    strings, or array of `Buffer`s containing the certificate key of the server
-    in PEM format. (Required)
+    strings, or array of `Buffer`s containing the server's certificate chain
+    (server's certificate and intermediates) in PEM format. (Required)
   * `ca` {string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of strings,
     or array of `Buffer`s of trusted certificates in PEM format. If this is
     omitted several well known "root" CAs (like VeriSign) will be used. These
-    are used to authorize connections.
+    are used to authorize connections. Useful for `requestCert` option.
   * `crl` {string|string[]} Either a string or array of strings of PEM encoded
     CRLs (Certificate Revocation List).
   * `ciphers` {string} A string describing the ciphers to use or exclude,
@@ -880,8 +880,8 @@ publicly trusted list of CAs as given in
   * `honorCipherOrder` {boolean} When choosing a cipher, use the server's
     preferences instead of the client preferences. Defaults to `true`.
   * `requestCert` {boolean} If `true` the server will request a certificate from
-    clients that connect and attempt to verify that certificate. Defaults to
-    `false`.
+    clients that connect and attempt to verify that certificate against
+    certificates provided in `ca` option. Defaults to `false`.
   * `rejectUnauthorized` {boolean} If `true` the server will reject any
     connection which is not authorized with the list of supplied CAs. This
     option only has an effect if `requestCert` is `true`. Defaults to `false`.
@@ -965,7 +965,7 @@ const fs = require('fs');
 
 const options = {
   key: fs.readFileSync('server-key.pem'),
-  cert: fs.readFileSync('server-cert.pem'),
+  cert: fs.readFileSync('server-cert-chain.pem'),
 
   // This is necessary only if using the client certificate authentication.
   requestCert: true,