doc: de-deduplicate secure context docs

The secure context options were documented 4 times, making it difficult to understand where the options come from, where they are supported, and under what conditions they are used. The multiple copies were inconsistent and contradictory in their descriptions of the options, and also inconsistent in whether the options would be documented at all. Cut through this gordian knot by linking all APIs that use the secureContext options to the single source of truth about the options.
nodejs · sam-github · Nov 18, 2016 · Nov 21, 2016 · Nov 22, 2016 · Nov 22, 2016
commit bb89227d029d3af3bbf76b08cd4f7a4d90cf8c98
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
@@ -1082,26 +1082,15 @@ deprecated: v0.11.13
 
 > Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead.
 
-The `crypto.createCredentials()` method is a deprecated alias for creating
-and returning a `tls.SecureContext` object. The `crypto.createCredentials()`
-method should not be used.
+- `details` {Object} Identical to [`tls.createSecureContext()`][].
 
-The optional `details` argument is a hash object with keys:
+The `crypto.createCredentials()` method is a deprecated function for creating
+and returning a `tls.SecureContext`. It should not be used. Replace it with
+[`tls.createSecureContext()`][] which has the exact same arguments and return
+value.
 
-* `pfx` : {String|Buffer} - PFX or PKCS12 encoded private
-  key, certificate and CA certificates
-* `key` : {String} - PEM encoded private key
-* `passphrase` : {String} - passphrase for the private key or PFX
-* `cert` : {String} - PEM encoded certificate
-* `ca` : {String|Array} - Either a string or array of strings of PEM encoded CA
-  certificates to trust.
-* `crl` : {String|Array} - Either a string or array of strings of PEM encoded CRLs
-  (Certificate Revocation List)
-* `ciphers`: {String} using the [OpenSSL cipher list format][] describing the
-  cipher algorithms to use or exclude.
-
-If no 'ca' details are given, Node.js will use Mozilla's default
-[publicly trusted list of CAs][].
+Returns a `tls.SecureContext`, as-if [`tls.createSecureContext()`][] had been
+called.
 
 ### crypto.createDecipher(algorithm, password)
 <!-- YAML

diff --git a/doc/api/tls.md b/doc/api/tls.md
@@ -193,6 +193,19 @@ Changing the default cipher suite can have a significant impact on the security
 of an application. The `--tls-cipher-list` switch and `ciphers` option should by
 used only if absolutely necessary.
 
+The default cipher suite prefers GCM ciphers for [Chrome's 'modern
+cryptography' setting] and also prefers ECDHE and DHE ciphers for Perfect
+Forward Secrecy, while offering *some* backward compatibility.
+
+128 bit AES is preferred over 192 and 256 bit AES in light of [specific
+attacks affecting larger AES key sizes].
+
+Old clients that rely on insecure and deprecated RC4 or DES-based ciphers
+(like Internet Explorer 6) cannot complete the handshaking process with
+the default configuration. If these clients _must_ be supported, the
+[TLS recommendations] may offer a compatible cipher suite. For more details
+on the format, see the [OpenSSL cipher list format documentation].
+
 ## Class: tls.Server
 <!-- YAML
 added: v0.3.2
@@ -773,23 +786,6 @@ added: v0.11.3
     connection/disconnection/destruction of `socket` is the user's
     responsibility, calling `tls.connect()` will not cause `net.connect()` to be
     called.
-  * `pfx` {string|Buffer} A string or `Buffer` containing the private key,
-    certificate, and CA certs of the client in PFX or PKCS12 format.
-  * `key` {string|string[]|Buffer|Buffer[]} A string, `Buffer`, array of
-    strings, or array of `Buffer`s containing the private key of the client in
-    PEM format.
-  * `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 client
-    in PEM format.
-  * `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.
-  * `ciphers` {string} A string describing the ciphers to use or exclude,
-    separated by `:`. Uses the same default cipher suite as
-    [`tls.createServer()`][].
   * `rejectUnauthorized` {boolean} If `true`, the server certificate is verified
     against the list of supplied CAs. An `'error'` event is emitted if
     verification fails; `err.code` contains the OpenSSL error code. Defaults to
@@ -810,18 +806,19 @@ added: v0.11.3
     to be used when checking the server's hostname against the certificate.
     This should throw an error if verification fails. The method should return
     `undefined` if the `servername` and `cert` are verified.
-  * `secureProtocol` {string} The SSL method to use, e.g. `SSLv3_method` to
-    force SSL version 3. The possible values depend on the version of OpenSSL
-    installed in the environment and are defined in the constant
-    [SSL_METHODS][].
-  * `secureContext` {tls.SecureContext} An optional TLS context object as returned by
-    `tls.createSecureContext()`. It can be used for caching client
-    certificates, keys, and CA certificates.
   * `session` {Buffer} A `Buffer` instance, containing TLS session.
   * `minDHSize` {number} Minimum size of the DH parameter in bits to accept a
     TLS connection. When a server offers a DH parameter with a size less
     than `minDHSize`, the TLS connection is destroyed and an error is thrown.
     Defaults to `1024`.
+  * `secureContext`: Optional TLS context object created with
+    [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one
+    will be created by passing the entire `options` object to
+    `tls.createSecureContext()`. *Note*: In effect, all
+    [`tls.createSecureContext()`][] options can be provided, but they will be
+    _completely ignored_ unless the `secureContext` option is missing.
+  * ...: Optional [`tls.createSecureContext()`][] options can be provided, see
+    the `secureContext` option for more information.
 * `callback` {Function}
 
 The `callback` function, if specified, will be added as a listener for the
@@ -968,45 +965,10 @@ added: v0.3.2
 -->
 
 * `options` {Object}
-  * `pfx` {string|Buffer} A string or `Buffer` containing the private key,
-    certificate and CA certs of the server in PFX or PKCS12 format. (Mutually
-    exclusive with the `key`, `cert`, and `ca` options.)
-  * `key` {string|string[]|Buffer|Object[]} The private key of the server in
-    PEM format. To support multiple keys using different algorithms an array can
-    be provided either as a plain array of key strings or an array of objects
-    in the format `{pem: key, passphrase: passphrase}`. This option is
-    *required* for ciphers that make use of private keys.
-  * `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)
-  * `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.
-  * `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,
-    separated by `:`.
-  * `ecdhCurve` {string} A string describing a named curve to use for ECDH key
-    agreement or `false` to disable ECDH. Defaults to `prime256v1` (NIST P-256).
-    Use [`crypto.getCurves()`][] to obtain a list of available curve names. On
-    recent releases, `openssl ecparam -list_curves` will also display the name
-    and description of each available elliptic curve.
-  * `dhparam` {string|Buffer} A string or `Buffer` containing Diffie Hellman
-    parameters, required for [Perfect Forward Secrecy][]. Use
-    `openssl dhparam` to create the parameters. The key length must be greater
-    than or equal to 1024 bits, otherwise an error will be thrown. It is
-    strongly recommended to use 2048 bits or larger for stronger security. If
-    omitted or invalid, the parameters are silently discarded and DHE ciphers
-    will not be available.
   * `handshakeTimeout` {number} Abort the connection if the SSL/TLS handshake
     does not finish in the specified number of milliseconds. Defaults to `120`
     seconds. A `'clientError'` is emitted on the `tls.Server` object whenever a
     handshake times out.
-  * `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`.
@@ -1033,57 +995,13 @@ added: v0.3.2
     a 16-byte HMAC key, and a 16-byte AES key. This can be used to accept TLS
     session tickets on multiple instances of the TLS server. *Note* that this is
     automatically shared between `cluster` module workers.
-  * `sessionIdContext` {string} A string containing an opaque identifier for
-    session resumption. The default is a 128 bit truncated SHA1 hash value
-    generated from `process.argv`.
-  * `secureProtocol` {string} Optional SSL method to use, default is
-    `"SSLv23_method"`. The possible values are listed as [SSL_METHODS][], use
-    the function names as strings. For example, `"SSLv3_method"` to force SSL
-    version 3.
+  * ...: Any [`tls.createSecureContext()`][] options can be provided. For
+    servers, the identity options (`pfx` or `key`/`cert`) are usually required.
 * `secureConnectionListener` {Function}
 
 Creates a new [tls.Server][].  The `secureConnectionListener`, if provided, is
 automatically set as a listener for the [`'secureConnection'`][] event.
 
-For the `ciphers` option, the default cipher suite is:
-
-```text
-ECDHE-RSA-AES128-GCM-SHA256:
-ECDHE-ECDSA-AES128-GCM-SHA256:
-ECDHE-RSA-AES256-GCM-SHA384:
-ECDHE-ECDSA-AES256-GCM-SHA384:
-DHE-RSA-AES128-GCM-SHA256:
-ECDHE-RSA-AES128-SHA256:
-DHE-RSA-AES128-SHA256:
-ECDHE-RSA-AES256-SHA384:
-DHE-RSA-AES256-SHA384:
-ECDHE-RSA-AES256-SHA256:
-DHE-RSA-AES256-SHA256:
-HIGH:
-!aNULL:
-!eNULL:
-!EXPORT:
-!DES:
-!RC4:
-!MD5:
-!PSK:
-!SRP:
-!CAMELLIA
-```
-
-The default cipher suite prefers GCM ciphers for [Chrome's 'modern
-cryptography' setting] and also prefers ECDHE and DHE ciphers for Perfect
-Forward Secrecy, while offering *some* backward compatibility.
-
-128 bit AES is preferred over 192 and 256 bit AES in light of [specific
-attacks affecting larger AES key sizes].
-
-Old clients that rely on insecure and deprecated RC4 or DES-based ciphers
-(like Internet Explorer 6) cannot complete the handshaking process with
-the default configuration. If these clients _must_ be supported, the
-[TLS recommendations] may offer a compatible cipher suite. For more details
-on the format, see the [OpenSSL cipher list format documentation].
-
 The following illustrates a simple echo server:
 
 ```js