8000 tls: support TLSv1.3 · nodejs/node@42dbaed · GitHub
[go: up one dir, main page]
Skip to content

Commit 42dbaed

Browse files
sam-githubsam-github
committed
tls: support TLSv1.3
This introduces TLS1.3 support and makes it the default max protocol, but also supports CLI/NODE_OPTIONS switches to disable it if necessary. TLS1.3 is a major update to the TLS protocol, with many security enhancements. It should be preferred over TLS1.2 whenever possible. TLS1.3 is different enough that even though the OpenSSL APIs are technically API/ABI compatible, that when TLS1.3 is negotiated, the timing of protocol records and of callbacks broke assumptions hard-coded into the 'tls' module. This change introduces no API incompatibilities when TLS1.2 is negotiated. It is the intention that it be backported to current and LTS release lines with the default maximum TLS protocol reset to 'TLSv1.2'. This will allow users of those lines to explicitly enable TLS1.3 if they want. API incompatibilities between TLS1.2 and TLS1.3 are: - Renegotiation is not supported by TLS1.3 protocol, attempts to call `.renegotiate()` will always fail. - Compiling against a system OpenSSL lower than 1.1.1 is no longer supported (OpenSSL-1.1.0 used to be supported with configure flags). - Variations of `conn.write('data'); conn.destroy()` have undefined behaviour according to the streams API. They may or may not send the 'data', and may or may not cause a ERR_STREAM_DESTROYED error to be emitted. This has always been true, but conditions under which the write suceeds is slightly but observably different when TLS1.3 is negotiated vs when TLS1.2 or below is negotiated. - If TLS1.3 is negotiated, and a server calls `conn.end()` in its 'secureConnection' listener without any data being written, the client will not receive session tickets (no 'session' events will be emitted, and `conn.getSession()` will never return a resumable session). - The return value of `conn.getSession()` API may not return a resumable session if called right after the handshake. The effect will be that clients using the legacy `getSession()` API will resume sessions if TLS1.2 is negotiated, but will do full handshakes if TLS1.3 is negotiated. See #25831 for more information. PR-URL: #26209 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rod Vagg <rod@vagg.org>
1 parent 4306300 commit 42dbaed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+988
-220
lines changed

‎doc/api/cli.md‎

Lines changed: 30 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -443,21 +443,43 @@ added: v4.0.0
443443
Specify an alternative default TLS cipher list. Requires Node.js to be built
444444
with crypto support (default).
445445

446-
### `--tls-v1.0`
446+
### `--tls-max-v1.2`
447447
<!-- YAML
448448
added: REPLACEME
449449
-->
450450

451-
Enable TLSv1.0 and greater in default [secureProtocol][]. Use for compatibility
452-
with old TLS clients or servers.
451+
Set default [`maxVersion`][] to `'TLSv1.2'`. Use to disable support for TLSv1.3.
453452

454-
### `--tls-v1.1`
453+
### `--tls-max-v1.3`
455454
<!-- YAML
456455
added: REPLACEME
457456
-->
458457

459-
Enable TLSv1.1 and greater in default [secureProtocol][]. Use for compatibility
460-
with old TLS clients or servers.
458+
Set default [`maxVersion`][] to `'TLSv1.3'`. Use to enable support for TLSv1.3.
459+
460+
### `--tls-min-v1.0`
461+
<!-- YAML
462+
added: REPLACEME
463+
-->
464+
465+
Set default [`minVersion`][] to `'TLSv1'`. Use for compatibility with old TLS
466+
clients or servers.
467+
468+
### `--tls-min-v1.1`
469+
<!-- YAML
470+
added: REPLACEME
471+
-->
472+
473+
Set default [`minVersion`][] to `'TLSv1.1'`. Use for compatibility with old TLS
474+
clients or servers.
475+
476+
### `--tls-min-v1.3`
477+
<!-- YAML
478+
added: REPLACEME
479+
-->
480+
481+
Set default [`minVersion`][] to `'TLSv1.3'`. Use to disable support for TLSv1.2
482+
in favour of TLSv1.3, which is more secure.
461483

462484
### `--trace-deprecation`
463485
<!-- YAML
@@ -896,6 +918,8 @@ greater than `4` (its current default value). For more information, see the
896918
[`--openssl-config`]: #cli_openssl_config_file
897919
[`Buffer`]: buffer.html#buffer_class_buffer
898920
[`SlowBuffer`]: buffer.html#buffer_class_slowbuffer
921+
[`maxVersion`]: tls.html#tls_tls_createsecurecontext_options
922+
[`minVersion`]: tls.html#tls_tls_createsecurecontext_options
899923
[`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
900924
[Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
901925
[REPL]: repl.html
@@ -907,4 +931,3 @@ greater than `4` (its current default value). For more information, see the
907931
[experimental ECMAScript Module]: esm.html#esm_loader_hooks
908932
[libuv threadpool documentation]: http://docs.libuv.org/en/latest/threadpool.html
909933
[remote code execution]: https://www.owasp.org/index.php/Code_Injection
910-
[secureProtocol]: tls.html#tls_tls_createsecurecontext_options

‎doc/api/tls.md‎

Lines changed: 90 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,9 @@ not required and a default ECDHE curve will be used. The `ecdhCurve` property
104104
can be used when creating a TLS Server to specify the list of names of supported
105105
curves to use, see [`tls.createServer()`] for more info.
106106

107+
Perfect Forward Secrecy was optional up to TLSv1.2, but it is not optional for
108+
TLSv1.3, because all TLSv1.3 cipher suites use ECDHE.
109+
107110
### ALPN and SNI
108111

109112
<!-- type=misc -->
@@ -136,6 +139,8 @@ threshold is exceeded. The limits are configurable:
136139
The default renegotiation limits should not be modified without a full
137140
understanding of the implications and risks.
138141

142+
TLSv1.3 does not support renegotiation.
143+
139144
### Session Resumption
140145

141146
Establishing a TLS session can be relatively slow. The process can be sped
@@ -176,6 +181,10 @@ as for resumption with session tickets. For debugging, if
176181
[`tls.TLSSocket.getTLSTicket()`][] returns a value, the session data contains a
177182
ticket, otherwise it contains client-side session state.
178183

184+
With TLSv1.3, be aware that multiple tickets may be sent by the server,
185+
resulting in multiple `'session'` events, see [`'session'`][] for more
186+
information.
187+
179188
Single process servers need no specific implementation to use session tickets.
180189
To use session tickets across server restarts or load balancers, servers must
181190
all have the same ticket keys. There are three 16-byte keys internally, but the
@@ -230,6 +239,9 @@ Node.js is built with a default suite of enabled and disabled TLS ciphers.
230239
Currently, the default cipher suite is:
231240

232241
```txt
242+
TLS_AES_256_GCM_SHA384:
243+
TLS_CHACHA20_POLY1305_SHA256:
244+
TLS_AES_128_GCM_SHA256:
233245
ECDHE-RSA-AES128-GCM-SHA256:
234246
ECDHE-ECDSA-AES128-GCM-SHA256:
235247
ECDHE-RSA-AES256-GCM-SHA384:
@@ -270,7 +282,19 @@ The default can also be replaced on a per client or server basis using the
270282
in [`tls.createServer()`], [`tls.connect()`], and when creating new
271283
[`tls.TLSSocket`]s.
272284

273-
Consult [OpenSSL cipher list format documentation][] for details on the format.
285+
The ciphers list can contain a mixture of TLSv1.3 cipher suite names, the ones
286+
that start with `'TLS_'`, and specifications for TLSv1.2 and below cipher
287+
suites. The TLSv1.2 ciphers support a legacy specification format, consult
288+
the OpenSSL [cipher list format][] documentation for details, but those
289+
specifications do *not* apply to TLSv1.3 ciphers. The TLSv1.3 suites can only
290+
be enabled by including their full name in the cipher list. They cannot, for
291+
example, be enabled or disabled by using the legacy TLSv1.2 `'EECDH'` or
292+
`'!EECDH'` specification.
293+
294+
Despite the relative order of TLSv1.3 and TLSv1.2 cipher suites, the TLSv1.3
295+
protocol is significantly more secure than TLSv1.2, and will always be chosen
296+
over TLSv1.2 if the handshake indicates it is supported, and if any TLSv1.3
297+
cipher suites are enabled.
274298

275299
The default cipher suite included within Node.js has been carefully
276300
selected to reflect current security best practices and risk mitigation.
@@ -289,7 +313,18 @@ Old clients that rely on insecure and deprecated RC4 or DES-based ciphers
289313
(like Internet Explorer 6) cannot complete the handshaking process with
290314
the default configuration. If these clients _must_ be supported, the
291315
[TLS recommendations] may offer a compatible cipher suite. For more details
292-
on the format, see the [OpenSSL cipher list format documentation].
316+
on the format, see the OpenSSL [cipher list format][] documentation.
317+
318+
There are only 5 TLSv1.3 cipher suites:
319+
- `'TLS_AES_256_GCM_SHA384'`
320+
- `'TLS_CHACHA20_POLY1305_SHA256'`
321+
- `'TLS_AES_128_GCM_SHA256'`
322+
- `'TLS_AES_128_CCM_SHA256'`
323+
- `'TLS_AES_128_CCM_8_SHA256'`
324+
325+
The first 3 are enabled by default. The last 2 `CCM`-based suites are supported
326+
by TLSv1.3 because they may be more performant on constrained systems, but they
327+
are not enabled by default since they offer less security.
293328

294329
## Class: tls.Server
295330
<!-- YAML
@@ -634,11 +669,11 @@ On the client, the `session` can be provided to the `session` option of
634669

635670
See [Session Resumption][] for more information.
636671

637-
Note: For TLS1.2 and below, [`tls.TLSSocket.getSession()`][] can be called once
638-
the handshake is complete. For TLS1.3, only ticket based resumption is allowed
672+
Note: For TLSv1.2 and below, [`tls.TLSSocket.getSession()`][] can be called once
673+
the handshake is complete. For TLSv1.3, only ticket based resumption is allowed
639674
by the protocol, multiple tickets are sent, and the tickets aren't sent until
640675
later, after the handshake completes, so it is necessary to wait for the
641-
`'session'` event to get a resumable session. Future-proof applications are
676+
`'session'` event to get a resumable session. Applications are
642677
recommended to use the `'session'` 179F event instead of `getSession()` to ensure
643678
they will work for all TLS protocol versions. Applications that only expect to
644679
get or use 1 session should listen for this event only once:
@@ -731,7 +766,7 @@ changes:
731766

732767
Returns an object containing information on the negotiated cipher suite.
733768

734-
For example: `{ name: 'AES256-SHA', version: 'TLSv1/SSLv3' }`.
769+
For example: `{ name: 'AES256-SHA', version: 'TLSv1.2' }`.
735770

736771
See
737772
[OpenSSL](https://www.openssl.org/docs/man1.1.1/man3/SSL_CIPHER_get_name.html)
@@ -904,12 +939,13 @@ be returned for server sockets or disconnected client sockets.
904939

905940
Protocol versions are:
906941

942+
* `'SSLv3'`
907943
* `'TLSv1'`
908944
* `'TLSv1.1'`
909945
* `'TLSv1.2'`
910-
* `'SSLv3'`
946+
* `'TLSv1.3'`
911947

912-
See <https://www.openssl.org/docs/man1.1.0/ssl/SSL_get_version.html> for more
948+
See <https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html> for more
913949
information.
914950

915951
### tlsSocket.getSession()
@@ -926,8 +962,8 @@ for debugging.
926962

927963
See [Session Resumption][] for more information.
928964

929-
Note: `getSession()` works only for TLS1.2 and below. Future-proof applications
930-
should use the [`'session'`][] event.
965+
Note: `getSession()` works only for TLSv1.2 and below. For TLSv1.3, applications
966+
must use the [`'session'`][] event (it also works for TLSv1.2 and below).
931967

932968
### tlsSocket.getTLSTicket()
933969
<!-- YAML
@@ -1009,8 +1045,12 @@ added: v0.11.8
10091045
verification fails; `err.code` contains the OpenSSL error code. **Default:**
10101046
`true`.
10111047
* `requestCert`
1012-
* `callback` {Function} A function that will be called when the renegotiation
1013-
request has been completed.
1048+
* `callback` {Function} If `renegotiate()` returned `true`, callback is
1049+
attached once to the `'secure'` event. If it returned `false`, it will be
1050+
called in the next tick with `ERR_TLS_RENEGOTIATE`, unless the `tlsSocket`
1051+
has been destroyed, in which case it will not be called at all.
1052+
1053+
* Returns: {boolean} `true` if renegotiation was initiated, `false` otherwise.
10141054

10151055
The `tlsSocket.renegotiate()` method initiates a TLS renegotiation process.
10161056
Upon completion, the `callback` function will be passed a single argument
@@ -1022,6 +1062,9 @@ connection has been established.
10221062
When running as the server, the socket will be destroyed with an error after
10231063
`handshakeTimeout` timeout.
10241064

1065+
For TLSv1.3, renegotiation cannot be initiated, it is not supported by the
1066+
protocol.
1067+
10251068
### tlsSocket.setMaxSendFragment(size)
10261069
<!-- YAML
10271070
added: v0.11.11
@@ -1220,6 +1263,9 @@ argument.
12201263
<!-- YAML
12211264
added: v0.11.13
12221265
changes:
1266+
- version: REPLACEME
1267+
pr-url: https://github.com/nodejs/node/pull/26209
1268+
description: TLSv1.3 support added.
12231269
- version: v11.5.0
12241270
pr-url: https://github.com/nodejs/node/pull/24733
12251271
description: The `ca:` option now supports `BEGIN TRUSTED CERTIFICATE`.
@@ -1310,15 +1356,22 @@ changes:
13101356
`object.passphrase` is optional. Encrypted keys will be decrypted with
13111357
`object.passphrase` if provided, or `options.passphrase` if it is not.
13121358
* `maxVersion` {string} Optionally set the maximum TLS version to allow. One
1313-
of `TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified along with the
1314-
`secureProtocol` option, use one or the other. **Default:** `'TLSv1.2'`.
1359+
of `TLSv1.3`, `TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified
1360+
along with the `secureProtocol` option, use one or the other.
1361+
**Default:** `'TLSv1.3'`, unless changed using CLI options. Using
1362+
`--tls-max-v1.2` sets the default to `'TLSv1.2`'. Using `--tls-max-v1.3`
1363+
sets the default to `'TLSv1.3'`. If multiple of the options are provided,
1364+
the highest maximum is used.
13151365
* `minVersion` {string} Optionally set the minimum TLS version to allow. One
1316-
of `TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified along with the
1317-
`secureProtocol` option, use one or the other. It is not recommended to use
1318-
less than TLSv1.2, but it may be required for interoperability.
1366+
of `TLSv1.3`, `TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. Cannot be specified
1367+
along with the `secureProtocol` option, use one or the other. It is not
1368+
recommended to use less than TLSv1.2, but it may be required for
1369+
interoperability.
13191370
**Default:** `'TLSv1.2'`, unless changed using CLI options. Using
1320-
`--tls-v1.0` changes the default to `'TLSv1'`. Using `--tls-v1.1` changes
1321-
the default to `'TLSv1.1'`.
1371+
`--tls-min-v1.0` sets the default to `'TLSv1'`. Using `--tls-min-v1.1` sets
1372+
the default to `'TLSv1.1'`. Using `--tls-min-v1.3` sets the default to
1373+
`'TLSv1.3'`. If multiple of the options are provided, the lowest minimum is
1374+
used.
13221375
* `passphrase` {string} Shared passphrase used for a single private key and/or
13231376
a PFX.
13241377
* `pfx` {string|string[]|Buffer|Buffer[]|Object[]} PFX or PKCS12 encoded
@@ -1334,12 +1387,15 @@ changes:
13341387
which is not usually necessary. This should be used carefully if at all!
13351388
Value is a numeric bitmask of the `SSL_OP_*` options from
13361389
[OpenSSL Options][].
1337-
* `secureProtocol` {string} The TLS protocol version to use. The possible
1338-
values are listed as [SSL_METHODS][], use the function names as strings. For
1339-
example, use `'TLSv1_1_method'` to force TLS version 1.1, or `'TLS_method'`
1340-
to allow any TLS protocol version. It is not recommended to use TLS versions
1341-
less than 1.2, but it may be required for interoperability. **Default:**
1342-
none, see `minVersion`.
1390+
* `secureProtocol` {string} Legacy mechanism to select the TLS protocol
1391+
version to use, it does not support independent control of the minimum and
1392+
maximum version, and does not support limiting the protocol to TLSv1.3. Use
1393+
`minVersion` and `maxVersion` instead. The possible values are listed as
1394+
[SSL_METHODS][], use the function names as strings. For example, use
1395+
`'TLSv1_1_method'` to force TLS version 1.1, or `'TLS_method'` to allow any
1396+
TLS protocol version up to TLSv1.3. It is not recommended to use TLS
1397+
versions less than 1.2, but it may be required for interoperability.
1398+
**Default:** none, see `minVersion`.
13431399
* `sessionIdContext` {string} Opaque identifier used by servers to ensure
13441400
session state is not shared between applications. Unused by clients.
13451401

@@ -1457,10 +1513,15 @@ added: v0.10.2
14571513

14581514
* Returns: {string[]}
14591515

1460-
Returns an array with the names of the supported SSL ciphers.
1516+
Returns an array with the names of the supported TLS ciphers. The names are
1517+
lower-case for historical reasons, but must be uppercased to be used in
1518+
the `ciphers` option of [`tls.createSecureContext()`][].
1519+
1520+
Cipher names that start with `'tls_'` are for TLSv1.3, all the others are for
1521+
TLSv1.2 and below.
14611522

14621523
```js
1463-
console.log(tls.getCiphers()); // ['AES128-SHA', 'AES256-SHA', ...]
1524+
console.log(tls.getCiphers()); // ['aes128-gcm-sha256', 'aes128-sha', ...]
14641525
```
14651526

14661527
## tls.DEFAULT_ECDH_CURVE
@@ -1619,16 +1680,16 @@ where `secureSocket` has the same API as `pair.cleartext`.
16191680
[Forward secrecy]: https://en.wikipedia.org/wiki/Perfect_forward_secrecy
16201681
[OCSP request]: https://en.wikipedia.org/wiki/OCSP_stapling
16211682
[OpenSSL Options]: crypto.html#crypto_openssl_options
1622-
[OpenSSL cipher list format documentation]: https://www.openssl.org/docs/man1.1.0/apps/ciphers.html#CIPHER-LIST-FORMAT
16231683
[Perfect Forward Secrecy]: #tls_perfect_forward_secrecy
16241684
[RFC 2246]: https://www.ietf.org/rfc/rfc2246.txt
16251685
[RFC 5077]: https://tools.ietf.org/html/rfc5077
16261686
[RFC 5929]: https://tools.ietf.org/html/rfc5929
1627-
[SSL_METHODS]: https://www.openssl.org/docs/man1.1.0/ssl/ssl.html#Dealing-with-Protocol-Methods
1687+
[SSL_METHODS]: https://www.openssl.org/docs/man1.1.1/man7/ssl.html#Dealing-with-Protocol-Methods
16281688
[Session Resumption]: #tls_session_resumption
16291689
[Stream]: stream.html#stream_stream
16301690
[TLS recommendations]: https://wiki.mozilla.org/Security/Server_Side_TLS
16311691
[asn1.js]: https://www.npmjs.com/package/asn1.js
16321692
[certificate object]: #tls_certificate_object
1693+
[cipher list format]: https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-LIST-FORMAT
16331694
[modifying the default cipher suite]: #tls_modifying_the_default_tls_cipher_suite
16341695
[specific attacks affecting larger AES key sizes]: https://www.schneier.com/blog/archives/2009/07/another_new_aes.html

‎doc/node.1‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -236,13 +236,23 @@ Specify process.title on startup.
236236
Specify an alternative default TLS cipher list.
237237
Requires Node.js to be built with crypto support. (Default)
238238
.
239-
.It Fl -tls-v1.0
240-
Enable TLSv1.0 and greater in default secureProtocol. Use for compatibility
241-
with old TLS clients or servers.
239+
.It Fl -tls-max-v1.2
240+
Set default maxVersion to 'TLSv1.2'. Use to disable support for TLSv1.3.
242241
.
243-
.It Fl -tls-v1.1
244-
Enable TLSv1.1 and greater in default secureProtocol. Use for compatibility
245-
with old TLS clients or servers.
242+
.It Fl -tls-max-v1.3
243+
Set default maxVersion to 'TLSv1.3'. Use to enable support for TLSv1.3.
244+
.
245+
.It Fl -tls-min-v1.0
246+
Set default minVersion to 'TLSv1'. Use for compatibility with old TLS clients
247+
or servers.
248+
.
249+
.It Fl -tls-min-v1.1
250+
Set default minVersion to 'TLSv1.1'. Use for compatibility with old TLS clients
251+
or servers.
252+
.
253+
.It Fl -tls-min-v1.3
254+
Set default minVersion to 'TLSv1.3'. Use to disable support for TLSv1.2 in
255+
favour of TLSv1.3, which is more secure.
246256
.
247257
.It Fl -trace-deprecation
248258
Print stack traces for deprecations.

0 commit comments

Comments
 (0)
0