Commit 7e08ca1
doc: document how to use the tls.DEFAULT_CIPHERS
The DEFAULT_CIPHERS already exists, this change shows how to use it.
Fixes: #46462
PR-URL: #46482
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>1 parent 3dae6f2 commit 7e08ca1
1 file changed
Lines changed: 36 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -356,6 +356,30 @@ export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' | |||
| 356 | 356 | node server.js | |
| 357 | 357 | ``` | |
| 358 | 358 | ||
| 359 | + To verify, use the following command to show the set cipher list, note the | ||
| 360 | + difference between `defaultCoreCipherList` and `defaultCipherList`: | ||
| 361 | + | ||
| 362 | + ```bash | ||
| 363 | + node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' -p crypto.constants.defaultCipherList | tr ':' '\n' | ||
| 364 | + ECDHE-RSA-AES128-GCM-SHA256 | ||
| 365 | + !RC4 | ||
| 366 | + ``` | ||
| 367 | + | ||
| 368 | + i.e. the `defaultCoreCipherList` list is set at compilation time and the | ||
| 369 | + `defaultCipherList` is set at runtime. | ||
| 370 | + | ||
| 371 | + To modify the default cipher suites from within the runtime, modify the | ||
| 372 | + `tls.DEFAULT_CIPHERS` variable, this must be performed before listening on any | ||
| 373 | + sockets, it will not affect sockets already opened. For example: | ||
| 374 | + | ||
| 375 | + ```js | ||
| 376 | + // Remove Obsolete CBC Ciphers and RSA Key Exchange based Ciphers as they don't provide Forward Secrecy | ||
| 377 | + tls.DEFAULT_CIPHERS += | ||
| 378 | + ':!ECDHE-RSA-AES128-SHA:!ECDHE-RSA-AES128-SHA256:!ECDHE-RSA-AES256-SHA:!ECDHE-RSA-AES256-SHA384' + | ||
| 379 | + ':!ECDHE-ECDSA-AES128-SHA:!ECDHE-ECDSA-AES128-SHA256:!ECDHE-ECDSA-AES256-SHA:!ECDHE-ECDSA-AES256-SHA384' + | ||
| 380 | + ':!kRSA'; | ||
| 381 | + ``` | ||
| 382 | + | ||
| 359 | 383 | The default can also be replaced on a per client or server basis using the | |
| 360 | 384 | `ciphers` option from [`tls.createSecureContext()`][], which is also available | |
| 361 | 385 | in [`tls.createServer()`][], [`tls.connect()`][], and when creating new | |
@@ -2219,6 +2243,18 @@ added: v11.4.0 | |||
| 2219 | 2243 | `'TLSv1.3'`. If multiple of the options are provided, the lowest minimum is | |
| 2220 | 2244 | used. | |
| 2221 | 2245 | ||
| 2246 | + ## `tls.DEFAULT_CIPHERS` | ||
| 2247 | + | ||
| 2248 | + <!-- YAML | ||
| 2249 | + added: REPLACEME | ||
| 2250 | + --> | ||
| 2251 | + | ||
| 2252 | + * {string} The default value of the `ciphers` option of | ||
| 2253 | + [`tls.createSecureContext()`][]. It can be assigned any of the supported | ||
| 2254 | + OpenSSL ciphers. Defaults to the content of | ||
| 2255 | + `crypto.constants.defaultCoreCipherList`, unless changed using CLI options | ||
| 2256 | + using `--tls-default-ciphers`. | ||
| 2257 | + | ||
| 2222 | 2258 | [CVE-2021-44531]: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44531 | |
| 2223 | 2259 | [Chrome's 'modern cryptography' setting]: https://www.chromium.org/Home/chromium-security/education/tls#TOC-Cipher-Suites | |
| 2224 | 2260 | [DHE]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange | |
0 commit comments