Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions doc/api/deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -4861,6 +4861,55 @@ Type: Documentation-only
`node:util`'s `util.TextDecoder` and `util.TextEncoder` are deprecated.
Use global `TextDecoder` and `TextEncoder` instead.

### DEP0213: TLS renegotiation

<!-- YAML
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67532
description: Documentation-only deprecation
with `--pending-deprecation` support.
-->

Type: Documentation-only (supports [`--pending-deprecation`][])

TLS renegotiation is deprecated and will be disabled by default in future.
This functionality will be largely removed in a subsequent release. Only a
client accepting server-initiated renegotiation requests is expected to
remain supported, and on an opt-in basis for legacy server compatibility.

This only affects TLS 1.2. TLS 1.3 removed renegotiation from the standard,
and so this has never been supported.

Avoid using TLS renegotiation. A server that needs a client certificate should
request it in the initial configuration, with the `requestCert` option of
[`tls.createServer()`][]. A client that needs to change the configuration of
an existing connection should create a new connection.

This affects multiple TLS APIs:

* Node.js TLS clients needing to initiate renegotiation locally, or accept
renegotiation requested by the server, should opt in by setting the
`allowRenegotiation` option of [`tls.connect()`][].
* Node.js TLS servers needing to initiate renegotiation locally, or accept
renegotiation requested by the client, should opt in by setting the
`allowRenegotiation` option of [`tls.createServer()`][].
If renegotiation by clients is removed in future, setting this option to
`true` on a server will throw an error.
* In either case, initiating renegotiation ([`tlsSocket.renegotiate()`][])
should be avoided by using alternative mechanisms. When renegotiation is
disabled by default this method will only work on connections created
with the `allowRenegotiation` option, and will throw an error if not.
If initiating renegotiation is removed in future, this method will throw
an error.
* Using [`tlsSocket.disableRenegotiation()`][] to disable renegotiation will
no longer be necessary when it is disabled by default. This will become a
no-op in most configurations.
* The `tls.CLIENT_RENEG_LIMIT` and `tls.CLIENT_RENEG_WINDOW` properties which
limit renegotiation will become unused in default configurations.
If renegotiation by clients is removed in future these are likely to be
removed.

[DEP0142]: #dep0142-repl_builtinlibs
[DEP0156]: #dep0156-aborted-property-and-abort-aborted-event-in-http
[NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
Expand Down Expand Up @@ -4985,8 +5034,11 @@ Use global `TextDecoder` and `TextEncoder` instead.
[`tls.SecureContext`]: tls.md#tlscreatesecurecontextoptions
[`tls.TLSSocket`]: tls.md#class-tlstlssocket
[`tls.checkServerIdentity()`]: tls.md#tlscheckserveridentityhostname-cert
[`tls.connect()`]: tls.md#tlsconnectoptions-callback
[`tls.createSecureContext()`]: tls.md#tlscreatesecurecontextoptions
[`tls.createServer()`]: tls.md#tlscreateserveroptions-secureconnectionlistener
[`tlsSocket.disableRenegotiation()`]: tls.md#tlssocketdisablerenegotiation
[`tlsSocket.renegotiate()`]: tls.md#tlssocketrenegotiateoptions-callback
[`url.format()`]: url.md#urlformaturlobject
[`url.format(urlString)`]: url.md#urlformaturlstring
[`url.parse()`]: url.md#urlparseurlstring-parsequerystring-slashesdenotehost
Expand Down
4 changes: 2 additions & 2 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -3358,8 +3358,8 @@ disabled.

### `ERR_TLS_RENEGOTIATION_UNSUPPORTED`

An attempt was made to renegotiate TLS, but the TLS implementation does not
support caller-initiated renegotiation.
An attempt was made to renegotiate TLS, or to allow renegotiation on a server,
but the TLS implementation does not support it.

<a id="ERR_TLS_REQUIRED_SERVER_NAME"></a>

Expand Down
3 changes: 2 additions & 1 deletion doc/api/https.md
Original file line number Diff line number Diff line change
Expand Up @@ -474,7 +474,8 @@ Makes a request to a secure web server.
The following additional `options` from [`tls.connect()`][] are also accepted:
`ca`, `cert`, `ciphers`, `crl`, `dhparam`, `ecdhCurve`, `honorCipherOrder`,
`key`, `passphrase`, `pfx`, `rejectUnauthorized`, `secureOptions`,
`secureProtocol`, `servername`, `sessionIdContext`, `highWaterMark`.
`secureProtocol`, `servername`, `sessionIdContext`, `highWaterMark`,
`allowRenegotiation`.

`options` can be an object, a string, or a [`URL`][] object. If `options` is a
string, it is automatically parsed with [`new URL()`][]. If it is a [`URL`][]
Expand Down
45 changes: 45 additions & 0 deletions doc/api/tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,11 @@ understanding of the implications and risks.

TLSv1.3 does not support renegotiation.

Renegotiation is deprecated (see [DEP0213][]). A future version of Node.js will
disable it by default, for servers and clients. The `allowRenegotiation` option
of [`tls.createServer()`][] and [`tls.connect()`][] can be set to `false` to
disable it now, or to `true` to keep it enabled when that default changes.

### Session resumption

Establishing a TLS session can be relatively slow. The process can be sped
Expand Down Expand Up @@ -901,6 +906,9 @@ connection is open.
<!-- YAML
added: v0.11.4
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67532
description: The `allowRenegotiation` option is now supported.
- version: v12.2.0
pr-url: https://github.com/nodejs/node/pull/27497
description: The `enableTrace` option is now supported.
Expand All @@ -927,6 +935,7 @@ changes:
* `ALPNProtocols`: See [`tls.createServer()`][]
* `SNICallback`: See [`tls.createServer()`][]
* `ALPNCallback`: See [`tls.createServer()`][]
* `allowRenegotiation`: See [`tls.createServer()`][]
* `session` {Buffer} A `Buffer` instance containing a TLS session.
* `requestOCSP` {boolean} If `true`, specifies that the OCSP status request
extension will be added to the client hello and an `'OCSPResponse'` event
Expand Down Expand Up @@ -1119,11 +1128,18 @@ certificate at all.

<!-- YAML
added: v8.4.0
deprecated: REPLACEME
-->

> Stability: 0 - Deprecated. See [DEP0213][].

Disables TLS renegotiation for this `TLSSocket` instance. Once called, attempts
to renegotiate will trigger an `'error'` event on the `TLSSocket`.

Set `allowRenegotiation: false` when creating the server or connection
instead. This method has no effect on a connection created that way, where the
peer's attempts to renegotiate are refused without an error.

### `tlsSocket.enableTrace()`

<!-- YAML
Expand Down Expand Up @@ -1586,6 +1602,7 @@ Returns the numeric representation of the remote port. For example, `443`.

<!-- YAML
added: v0.11.8
deprecated: REPLACEME
changes:
- version: v18.0.0
pr-url: https://github.com/nodejs/node/pull/41678
Expand All @@ -1594,6 +1611,8 @@ changes:
`ERR_INVALID_CALLBACK`.
-->

> Stability: 0 - Deprecated. See [DEP0213][].

* `options` {Object}
* `rejectUnauthorized` {boolean} If not `false`, the server certificate is
verified against the list of supplied CAs. An `'error'` event is emitted if
Expand Down Expand Up @@ -1622,6 +1641,12 @@ When running as the server, the socket will be destroyed with an error after
For TLSv1.3, renegotiation cannot be initiated, it is not supported by the
protocol.

If the connection was created with `allowRenegotiation: false`, this method
returns `false` and `callback` is called with an
[`ERR_TLS_RENEGOTIATION_DISABLED`][] error. A future version of Node.js will
disable renegotiation by default, and this method will then only work on
connections created with `allowRenegotiation: true`.

### `tlsSocket.servername`

<!-- YAML
Expand Down Expand Up @@ -1740,6 +1765,9 @@ was present (see [CVE-2021-44531][]). Applications that wish to accept
<!-- YAML
added: v0.11.3
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67532
description: The `allowRenegotiation` option is now supported.
- version:
- v15.1.0
- v14.18.0
Expand Down Expand Up @@ -1837,6 +1865,9 @@ changes:
TLS connection. When a server offers a DH parameter with a size less
than `minDHSize`, the TLS connection is destroyed and an error is thrown.
**Default:** `1024`.
* `allowRenegotiation` {boolean} If `true`, the client accepts renegotiation
requested by the server. A future version of Node.js will change this default
to `false` (see [DEP0213][]). **Default:** `true`.
* `highWaterMark` {number} Consistent with the readable stream `highWaterMark` parameter.
**Default:** `16 * 1024`.
* `timeout`: {number} If set and if a socket is created internally, will call
Expand Down Expand Up @@ -2209,6 +2240,9 @@ permissible, use 2048 bits or larger for stronger security.
<!-- YAML
added: v0.3.2
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67532
description: The `allowRenegotiation` option is now supported.
- version: v27.0.0-alpha.0.0.0
pr-url: https://github.com/nodejs/node/pull/64777
description: Using the `clientCertEngine` option now throws
Expand Down Expand Up @@ -2246,6 +2280,13 @@ changes:
-->

* `options` {Object}
* `allowRenegotiation` {boolean} If `true`, connections to the server may be
renegotiated, either when requested by the client or through local calls to
[`tlsSocket.renegotiate()`][]. Renegotiation is deprecated (see
[DEP0213][]) and future versions will set this default to `false`.
Setting this to `true` throws [`ERR_TLS_RENEGOTIATION_UNSUPPORTED`][]
where the TLS library does not support renegotiation on servers.
**Default:** `true`.
* `ALPNProtocols` {string\[]|Buffer|TypedArray|DataView} An array of strings,
or a single `Buffer`, `TypedArray`, or `DataView` containing the supported
ALPN protocols. Buffers should have the format `[len][name][len][name]...`
Expand Down Expand Up @@ -2585,6 +2626,7 @@ added: v0.11.3

[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
[DEP0213]: deprecations.md#dep0213-tls-renegotiation
[DHE]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange
[ECDHE]: https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman
[IANA TLS Supported Groups registry]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
Expand Down Expand Up @@ -2617,6 +2659,8 @@ added: v0.11.3
[`--use-openssl-ca`]: cli.md#--use-bundled-ca---use-openssl-ca
[`--use-system-ca`]: cli.md#--use-system-ca
[`Duplex`]: stream.md#class-streamduplex
[`ERR_TLS_RENEGOTIATION_DISABLED`]: errors.md#err_tls_renegotiation_disabled
[`ERR_TLS_RENEGOTIATION_UNSUPPORTED`]: errors.md#err_tls_renegotiation_unsupported
[`NODE_EXTRA_CA_CERTS`]: cli.md#node_extra_ca_certsfile
[`NODE_OPTIONS`]: cli.md#node_optionsoptions
[`SSL_export_keying_material`]: https://www.openssl.org/docs/man3.0/man3/SSL_export_keying_material.html
Expand Down Expand Up @@ -2652,6 +2696,7 @@ added: v0.11.3
[`tls.getCACertificates()`]: #tlsgetcacertificatestype
[`tls.getCiphers()`]: #tlsgetciphers
[`tls.rootCertificates`]: #tlsrootcertificates
[`tlsSocket.renegotiate()`]: #tlssocketrenegotiateoptions-callback
[`x509.checkHost()`]: crypto.md#x509checkhostname-options
[asn1.js]: https://www.npmjs.com/package/asn1.js
[certificate object]: #certificate-object
Expand Down
4 changes: 4 additions & 0 deletions lib/https.js
Original file line number Diff line number Diff line change
Expand Up @@ -700,6 +700,10 @@ Agent.prototype.getName = function getName(options = kEmptyObject) {
if (options.session)
name += getTlsOptionKey(options.session);

name += ':';
if (options.allowRenegotiation !== undefined)
name += getTlsOptionKey(options.allowRenegotiation);

if (options[kPerRequestCheckServerIdentity])
name += `:${options[kPerRequestCheckServerIdentity]}`;

Expand Down
48 changes: 48 additions & 0 deletions lib/internal/tls/wrap.js
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ const {

const {
assertCrypto,
getDeprecationWarningEmitter,
isPendingDeprecation,
kEmptyObject,
} = require('internal/util');

Expand Down Expand Up @@ -101,10 +103,20 @@ const {
const {
InternalX509Certificate,
} = require('internal/crypto/x509');
const emitRenegotiationDeprecation = getDeprecationWarningEmitter(
'DEP0213',
'TLS renegotiation is deprecated and will be disabled by default. Only ' +
"clients setting allowRenegotiation to accept a server's request will " +
'remain supported.',
undefined,
false,
isPendingDeprecation,
);
const traceTls = getOptionValue('--trace-tls');
const tlsKeylog = getOptionValue('--tls-keylog');
const { appendFile } = require('fs');
const kConnectOptions = Symbol('connect-options');
const kAllowRenegotiation = Symbol('allowRenegotiation');
const kDisableRenegotiation = Symbol('disable-renegotiation');
const kErrorEmitted = Symbol('error-emitted');
const kHandshakeTimeout = Symbol('handshake-timeout');
Expand Down Expand Up @@ -234,6 +246,15 @@ function onhandshakestart(now) {
owner._emitTLSError(new ERR_TLS_RENEGOTIATION_DISABLED());
}

function validateAllowRenegotiation(allowRenegotiation, isServer) {
if (allowRenegotiation === undefined)
return;
validateBoolean(allowRenegotiation, 'options.allowRenegotiation');
// BoringSSL servers always refuse renegotiation.
if (allowRenegotiation && isServer && isBoringSSL)
throw new ERR_TLS_RENEGOTIATION_UNSUPPORTED();
}

function onhandshakedone() {
debug('server onhandshakedone');

Expand Down Expand Up @@ -655,6 +676,9 @@ function TLSSocket(socket, opts) {
if (tlsOptions.ALPNProtocols)
tls.convertALPNProtocols(tlsOptions.ALPNProtocols, tlsOptions);

validateAllowRenegotiation(tlsOptions.allowRenegotiation,
tlsOptions.isServer);

this._tlsOptions = tlsOptions;
this._secureEstablished = false;
this._securePending = false;
Expand Down Expand Up @@ -977,6 +1001,9 @@ TLSSocket.prototype._init = function(socket, wrap) {
if (requestCert || rejectUnauthorized)
ssl.setVerifyMode(requestCert, rejectUnauthorized);

if (options.allowRenegotiation === false)
ssl.disableRenegotiation();

// Only call .onkeylog if there is a keylog listener.
ssl.onkeylog = onkeylog;

Expand Down Expand Up @@ -1114,6 +1141,8 @@ TLSSocket.prototype.renegotiate = function(options, callback) {
validateFunction(callback, 'callback');
}

emitRenegotiationDeprecation();

debug('%s renegotiate()',
this._tlsOptions.isServer ? 'server' : 'client',
'destroyed?', this.destroyed,
Expand All @@ -1122,6 +1151,13 @@ TLSSocket.prototype.renegotiate = function(options, callback) {
if (this.destroyed)
return;

if (this._tlsOptions.allowRenegotiation === false) {
if (callback) {
process.nextTick(callback, new ERR_TLS_RENEGOTIATION_DISABLED());
}
return false;
}

let requestCert = !!this._requestCert;
let rejectUnauthorized = !!this._rejectUnauthorized;

Expand Down Expand Up @@ -1228,6 +1264,13 @@ TLSSocket.prototype._finishInit = function() {
'alpn', this.alpnProtocol,
'servername', this.servername);

// A second completed handshake is a renegotiation.
if (this._secureEstablished &&
(this._tlsOptions.isServer ||
this._tlsOptions.allowRenegotiation !== true)) {
emitRenegotiationDeprecation();
}

this._secureEstablished = true;
if (this._tlsOptions.handshakeTimeout > 0)
this.setTimeout(0, this._handleTimeout);
Expand Down Expand Up @@ -1412,6 +1455,7 @@ function tlsConnectionListener(rawSocket) {
ALPNCallback: this.ALPNCallback,
SNICallback: this[kSNICallback] || SNICallback,
enableTrace: this[kEnableTrace],
allowRenegotiation: this[kAllowRenegotiation],
pauseOnConnect: this.pauseOnConnect,
pskCallback: this[kPskCallback],
pskIdentityHint: this[kPskIdentityHint],
Expand Down Expand Up @@ -1532,6 +1576,9 @@ function Server(options, listener) {

validateNumber(this[kHandshakeTimeout], 'options.handshakeTimeout');

validateAllowRenegotiation(options.allowRenegotiation, true);
this[kAllowRenegotiation] = options.allowRenegotiation;

if (this[kSNICallback]) {
validateFunction(this[kSNICallback], 'options.SNICallback');
}
Expand Down Expand Up @@ -1901,6 +1948,7 @@ exports.connect = function connect(...args) {
ALPNProtocols: options.ALPNProtocols,
requestOCSP: options.requestOCSP,
enableTrace: options.enableTrace,
allowRenegotiation: options.allowRenegotiation,
pskCallback: options.pskCallback,
highWaterMark: options.highWaterMark,
onread: options.onread,
Expand Down
Loading
Loading