Skip to content

Commit

Permalink
doc: rework tls for accuracy and clarity
Browse files Browse the repository at this point in the history
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 nodejs#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: nodejs#9800
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
  • Loading branch information
sam-github committed Dec 12, 2016
1 parent a28e949 commit caa7fa9
Show file tree
Hide file tree
Showing 4 changed files with 346 additions and 253 deletions.
33 changes: 11 additions & 22 deletions doc/api/crypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
Loading

0 comments on commit caa7fa9

Please sign in to comment.