From c951d3d69d6a88f3161110aad3ddfce560f9a051 Mon Sep 17 00:00:00 2001 From: Andreas Martens Date: Fri, 3 Feb 2023 10:48:04 +0000 Subject: [PATCH 1/4] doc: document how to use the tls.DEFAULT_CIPHERS The DEFAULT_CIPHERS already exists, this change shows how to use it. Fixes: https://github.com/nodejs/node/issues/46462 --- doc/api/tls.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index 32e0d5b5371489..ce4e9b9760a5ce 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -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 @@ -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` + + + +* {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 From e2c0b05def54e91fe25ba68eac5199f2ddb6b343 Mon Sep 17 00:00:00 2001 From: Andreas Martens Date: Fri, 3 Feb 2023 13:20:18 +0000 Subject: [PATCH 2/4] doc: fix lint errors and warnings --- doc/api/tls.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index ce4e9b9760a5ce..79cafabe43b26f 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -356,24 +356,28 @@ 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 +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 + +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 +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 +// Remove Obsolete CBC Ciphers and RSA Key Exchange based Ciphers as they don't provide Forward Secrecy +tls_module.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 @@ -2253,9 +2257,9 @@ 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 + [`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 From 8167f895d081111f73a1073f515833236c7379e2 Mon Sep 17 00:00:00 2001 From: Andreas Martens Date: Fri, 3 Feb 2023 13:28:39 +0000 Subject: [PATCH 3/4] doc: remove copy-paste typo --- doc/api/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 79cafabe43b26f..641eb3a01aa4d6 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -374,7 +374,7 @@ 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_module.DEFAULT_CIPHERS += +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'; From 0c6719eafc2eb4e43d9a60c996b17187ab374d57 Mon Sep 17 00:00:00 2001 From: Andreas Martens Date: Mon, 6 Feb 2023 08:13:15 +0000 Subject: [PATCH 4/4] Update doc/api/tls.md Remove extraneous quotes Co-authored-by: Mohammed Keyvanzadeh --- doc/api/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/tls.md b/doc/api/tls.md index 641eb3a01aa4d6..a9763c73426673 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -2259,7 +2259,7 @@ 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 + `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