Skip to content
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

Jump to bottom

doc: document how to use the tls.DEFAULT_CIPHERS #46482

Merged
merged 4 commits into from
Feb 23, 2023
Merged

doc: document how to use the tls.DEFAULT_CIPHERS #46482

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c951d3d
doc: document how to use the tls.DEFAULT_CIPHERS
andreas-ibm Feb 3, 2023
e2c0b05
doc: fix lint errors and warnings
andreas-ibm Feb 3, 2023
8167f89
doc: remove copy-paste typo
andreas-ibm Feb 3, 2023
0c6719e
Update doc/api/tls.md
andreas-ibm Feb 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
36 changes: 36 additions & 0 deletions doc/api/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,6 +356,30 @@ export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4'
node server.js
```

To verify, use the following command to show the set cipher list, note the
difference between `defaultCoreCipherList` and `defaultCipherList`:

```bash
node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n'
ECDHE-RSA-AES128-GCM-SHA256
!RC4
```

i.e. the `defaultCoreCipherList` list is set at compilation time and the
`defaultCipherList` is set at runtime.

To modify the default cipher suites from within the runtime, modify the
`tls.DEFAULT_CIPHERS` variable, this must be performed before listening on any
sockets, it will not affect sockets already opened. For example:

```js
// Remove Obsolete CBC Ciphers and RSA Key Exchange based Ciphers as they don't provide Forward Secrecy
tls.DEFAULT_CIPHERS +=
':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' +
':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' +
':!kRSA';
```

The default can also be replaced on a per client or server basis using the
`ciphers` option from [`tls.createSecureContext()`][], which is also available
in [`tls.createServer()`][], [`tls.connect()`][], and when creating new
Expand Down Expand Up @@ -2226,6 +2250,18 @@ added: v11.4.0
`'TLSv1.3'`. If multiple of the options are provided, the lowest minimum is
used.

## `tls.DEFAULT_CIPHERS`

<!-- YAML
added: REPLACEME
-->

* {string} The default value of the `ciphers` option of
[`tls.createSecureContext()`][]. It can be assigned any of the supported
OpenSSL ciphers. Defaults to the content of
`crypto.constants.defaultCoreCipherList`, unless changed using CLI options
using `--tls-default-ciphers`.

[CVE-2021-44531]: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44531
[Chrome's 'modern cryptography' setting]: https://www.chromium.org/Home/chromium-security/education/tls#TOC-Cipher-Suites
[DHE]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange
Expand Down