Skip to content

Commit

Permalink
doc: document how to use the tls.DEFAULT_CIPHERS
Browse files Browse the repository at this point in the history
The DEFAULT_CIPHERS already exists, this change shows how to use it.

Fixes: nodejs#46462
  • Loading branch information
andreas-ibm committed Feb 3, 2023
1 parent 279839d commit c951d3d
Showing 1 changed file with 32 additions and 0 deletions.
32 changes: 32 additions & 0 deletions doc/api/tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -356,6 +356,26 @@ 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
tls.DEFAULT_CIPHERS=tls.DEFAULT_CIPHERS +
':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' + // Obsolete CBC Ciphers
':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' + // Obsolete CBC Ciphers using elliptic keys
':!kRSA'; // RSA Key Exchange Algorithm considered weak, doesn't provide forward secrecy
```

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 +2246,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

0 comments on commit c951d3d

Please sign in to comment.