Commit 1648f88
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 <me@silverwind.io>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>1 parent 971505c commit 1648f88
4 files changed
Lines changed: 346 additions & 253 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1072,26 +1072,15 @@ deprecated: v0.11.13 | |||
| 1072 | 1072 | ||
| 1073 | 1073 | > Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead. | |
| 1074 | 1074 | ||
| 1075 | - The `crypto.createCredentials()` method is a deprecated alias for creating | ||
| 1076 | - and returning a `tls.SecureContext` object. The `crypto.createCredentials()` | ||
| 1077 | - method should not be used. | ||
| 1075 | + - `details` {Object} Identical to [`tls.createSecureContext()`][]. | ||
| 1078 | 1076 | ||
| 1079 | - The optional `details` argument is a hash object with keys: | ||
| 1077 | + The `crypto.createCredentials()` method is a deprecated function for creating | ||
| 1078 | + and returning a `tls.SecureContext`. It should not be used. Replace it with | ||
| 1079 | + [`tls.createSecureContext()`][] which has the exact same arguments and return | ||
| 1080 | + value. | ||
| 1080 | 1081 | ||
| 1081 | - * `pfx` : {String|Buffer} - PFX or PKCS12 encoded private | ||
| 1082 | - key, certificate and CA certificates | ||
| 1083 | - * `key` : {String} - PEM encoded private key | ||
| 1084 | - * `passphrase` : {String} - passphrase for the private key or PFX | ||
| 1085 | - * `cert` : {String} - PEM encoded certificate | ||
| 1086 | - * `ca` : {String|Array} - Either a string or array of strings of PEM encoded CA | ||
| 1087 | - certificates to trust. | ||
| 1088 | - * `crl` : {String|Array} - Either a string or array of strings of PEM encoded CRLs | ||
| 1089 | - (Certificate Revocation List) | ||
| 1090 | - * `ciphers`: {String} using the [OpenSSL cipher list format][] describing the | ||
| 1091 | - cipher algorithms to use or exclude. | ||
| 1092 | - | ||
| 1093 | - If no 'ca' details are given, Node.js will use Mozilla's default | ||
| 1094 | - [publicly trusted list of CAs][]. | ||
| 1082 | + Returns a `tls.SecureContext`, as-if [`tls.createSecureContext()`][] had been | ||
| 1083 | + called. | ||
| 1095 | 1084 | ||
| 1096 | 1085 | ### crypto.createDecipher(algorithm, password) | |
| 1097 | 1086 | <!-- YAML | |
@@ -1643,8 +1632,8 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. | |||
| 1643 | 1632 | </tr> | |
| 1644 | 1633 | <tr> | |
| 1645 | 1634 | <td><code>SSL_OP_CIPHER_SERVER_PREFERENCE</code></td> | |
| 1646 | - <td>Uses the server's preferences instead of the clients when selecting a | ||
| 1647 | - cipher. See | ||
| 1635 | + <td>Attempts to use the server's preferences instead of the client's when | ||
| 1636 | + selecting a cipher. Behaviour depends on protocol version. See | ||
| 1648 | 1637 | https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html.</td> | |
| 1649 | 1638 | </tr> | |
| 1650 | 1639 | <tr> | |
@@ -1672,7 +1661,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. | |||
| 1672 | 1661 | </tr> | |
| 1673 | 1662 | <tr> | |
| 1674 | 1663 | <td><code>SSL_OP_LEGACY_SERVER_CONNECT</code></td> | |
| 1675 | - <td>Allow initial connection to servers that do not support RI.</td> | ||
| 1664 | + <td>Allows initial connection to servers that do not support RI.</td> | ||
| 1676 | 1665 | </tr> | |
| 1677 | 1666 | <tr> | |
| 1678 | 1667 | <td><code>SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER</code></td> | |
@@ -1970,4 +1959,4 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. | |||
| 1970 | 1959 | [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt | |
| 1971 | 1960 | [stream]: stream.html | |
| 1972 | 1961 | [stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback | |
| 1973 | - [Crypto Constants]: #crypto_crypto_constants | ||
| 1962 | + [Crypto Constants]: #crypto_crypto_constants_1 | ||
0 commit comments