Skip to content

Clarify the documentation for TLS cipher configuration & defaults #41061

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Clarify the documentation for TLS cipher configuration & defaults #41061

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4b74f70
doc: clarify the 'ciphers' list string format
pimterry Dec 2, 2021
0b583f8
doc: document the tls.DEFAULT_CIPHERS property
pimterry Dec 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 30 additions & 12 deletions doc/api/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -361,14 +361,14 @@ The default can also be replaced on a per client or server basis using the
in [`tls.createServer()`][], [`tls.connect()`][], and when creating new
[`tls.TLSSocket`][]s.

The ciphers list can contain a mixture of TLSv1.3 cipher suite names, the ones
that start with `'TLS_'`, and specifications for TLSv1.2 and below cipher
suites. The TLSv1.2 ciphers support a legacy specification format, consult
the OpenSSL [cipher list format][] documentation for details, but those
specifications do _not_ apply to TLSv1.3 ciphers. The TLSv1.3 suites can only
be enabled by including their full name in the cipher list. They cannot, for
example, be enabled or disabled by using the legacy TLSv1.2 `'EECDH'` or
`'!EECDH'` specification.
The ciphers list is colon-separated and can contain a mixture of TLSv1.3
cipher suite names, the ones that start with `'TLS_'`, and specifications for
TLSv1.2 and below cipher suites. The TLSv1.2 ciphers support a legacy
specification format, consult the OpenSSL [cipher list format][] documentation
for details, but those specifications do _not_ apply to TLSv1.3 ciphers. The
TLSv1.3 suites can only be enabled by including their full name in the cipher
list. They cannot, for example, be enabled or disabled by using the legacy
TLSv1.2 `'EECDH'` or `'!EECDH'` specification.

Despite the relative order of TLSv1.3 and TLSv1.2 cipher suites, the TLSv1.3
protocol is significantly more secure than TLSv1.2, and will always be chosen
Expand Down Expand Up @@ -1844,10 +1844,12 @@ changes:
'RSA+SHA384') or TLS v1.3 scheme names (e.g. `rsa_pss_pss_sha512`).
See [OpenSSL man pages](https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_sigalgs_list.html)
for more info.
* `ciphers` {string} Cipher suite specification, replacing the default. For
more information, see [Modifying the default TLS cipher suite][]. Permitted
ciphers can be obtained via [`tls.getCiphers()`][]. Cipher names must be
uppercased in order for OpenSSL to accept them.
* `ciphers` {string} Colon-separated cipher suite specification, replacing
the default. For more information, see
[modifying the default TLS cipher suite][]. Permitted ciphers can be
obtained via [`tls.getCiphers()`][]. Cipher names must be uppercased in
order for OpenSSL to accept them.
**Default:** [`tls.DEFAULT_CIPHERS`][].
* `clientCertEngine` {string} Name of an OpenSSL engine which can provide the
client certificate.
* `crl` {string|string\[]|Buffer|Buffer\[]} PEM formatted CRLs (Certificate
Expand Down Expand Up @@ -2176,6 +2178,21 @@ from the bundled Mozilla CA store as supplied by the current Node.js version.
The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store
that is fixed at release time. It is identical on all supported platforms.

## `tls.DEFAULT_CIPHERS`

<!-- YAML
added: v0.11.3
changes:
- version: v4.0.0
pr-url: https://github.com/nodejs/node/pull/2412
description: Made configurable using the --tls-cipher-list command line
switch.
-->

* {string} The default TLS cipher suites supported by this Node.js process,
as a colon-separated string. See [modifying the default TLS cipher suite][]
for further information.

## `tls.DEFAULT_ECDH_CURVE`

<!-- YAML
Expand Down Expand Up @@ -2257,6 +2274,7 @@ added: v11.4.0
[`server.listen()`]: net.md#serverlisten
[`server.setTicketKeys()`]: #serversetticketkeyskeys
[`socket.connect()`]: net.md#socketconnectoptions-connectlistener
[`tls.DEFAULT_CIPHERS`]: #tlsdefault_ciphers
[`tls.DEFAULT_ECDH_CURVE`]: #tlsdefault_ecdh_curve
[`tls.DEFAULT_MAX_VERSION`]: #tlsdefault_max_version
[`tls.DEFAULT_MIN_VERSION`]: #tlsdefault_min_version
Expand Down