doc: rework tls for accuracy and clarity

Document all TLSSocket options:

- All the secure context options are valid options
  to a secureContext
- isServer modifies the default value of requestCert

Describe all tls.connect() variants:

- tls.connect(path) was undocumented
- tls.connect(port) was underdocumented, and its relationship to
  tls.connect(options) was obscure

Socket passed to tls.connect is user managed:

- Replace #8996

Add documentation to:

- describe and add tests for the pfx and key variants, and describe how
  and when passphrase is used.
- describe tls cert and ca options
- describe buffer forms of tls crl option
- describe tls cipher option and defaults
- fix link to Crypto Constants
- describe that honorCipherOrder sets SSL_OP_CIPHER_SERVER_PREFERENCE.
- describe tls ecdhCurve/dhparam options
- describe tls secureProtocol option
- describe tls secureOptions
- describe tls sessionIdContext

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.

PR-URL: #9800
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>

Author: sam-github

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
@@ -1653,8 +1642,8 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
   </tr>
   <tr>
     <td><code>SSL_OP_CIPHER_SERVER_PREFERENCE</code></td>
-    <td>Uses the server's preferences instead of the clients when selecting a
-    cipher. See
+    <td>Attempts to use the server's preferences instead of the client's when
+    selecting a cipher. Behaviour depends on protocol version. See
     https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html.</td>
   </tr>
   <tr>
@@ -1682,7 +1671,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
   </tr>
   <tr>
     <td><code>SSL_OP_LEGACY_SERVER_CONNECT</code></td>
-    <td>Allow initial connection to servers that do not support RI.</td>
+    <td>Allows initial connection to servers that do not support RI.</td>
   </tr>
   <tr>
     <td><code>SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER</code></td>
@@ -1980,4 +1969,4 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
 [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
 [stream]: stream.html
 [stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback
-[Crypto Constants]: #crypto_crypto_constants
+[Crypto Constants]: #crypto_crypto_constants_1