Skip to content
Open
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
38 changes: 22 additions & 16 deletions doc/api/deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -4885,18 +4885,21 @@ Use global `TextDecoder` and `TextEncoder` instead.

<!-- YAML
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67618
description: Runtime deprecation. Renegotiation is disabled by default.
- 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`][])
Type: Runtime

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.
TLS renegotiation is deprecated and is disabled by default. 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.
Expand All @@ -4909,24 +4912,27 @@ 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()`][].
renegotiation requested by the server, must opt in by setting the
`allowRenegotiation` option of [`tls.connect()`][]. Accepting renegotiation
requested by the server does not emit a deprecation warning.
* 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()`][].
renegotiation requested by the client, must opt in by setting the
`allowRenegotiation` option of [`tls.createServer()`][], which emits a
deprecation warning.
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.
emits a deprecation warning, and should be avoided by using alternative
mechanisms. This method only works 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.
* Using [`tlsSocket.disableRenegotiation()`][] to disable renegotiation is
no longer necessary. It is a no-op unless the connection was created with
the `allowRenegotiation` option.
* The `tls.CLIENT_RENEG_LIMIT` and `tls.CLIENT_RENEG_WINDOW` properties which
limit renegotiation will become unused in default configurations.
limit renegotiation are unused unless a server sets the `allowRenegotiation`
option. Reading or writing either emits a deprecation warning.
If renegotiation by clients is removed in future these are likely to be
removed.

Expand Down
43 changes: 27 additions & 16 deletions doc/api/tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -231,14 +231,14 @@ threshold is exceeded. The limits are configurable:
in seconds. **Default:** `600` (10 minutes).

The default renegotiation limits should not be modified without a full
understanding of the implications and risks.
understanding of the implications and risks. Reading or writing either
property emits a deprecation warning (see [DEP0213][]).

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.
Renegotiation is deprecated (see [DEP0213][]) and is disabled by default, for
servers and clients. The `allowRenegotiation` option of [`tls.createServer()`][]
and [`tls.connect()`][] can be set to `true` to enable it.

### Session resumption

Expand Down Expand Up @@ -906,6 +906,9 @@ connection is open.
<!-- YAML
added: v0.11.4
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67618
description: The `allowRenegotiation` option now defaults to `false`.
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67532
description: The `allowRenegotiation` option is now supported.
Expand Down Expand Up @@ -1136,9 +1139,9 @@ deprecated: REPLACEME
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.
Renegotiation is disabled by default, and the peer's attempts to renegotiate
are then refused without an error. This method only has an effect on a
connection created with `allowRenegotiation: true`.

### `tlsSocket.enableTrace()`

Expand Down Expand Up @@ -1604,6 +1607,10 @@ Returns the numeric representation of the remote port. For example, `443`.
added: v0.11.8
deprecated: REPLACEME
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67618
description: Runtime deprecation. This method now fails unless the
connection was created with the `allowRenegotiation` option.
- version: v18.0.0
pr-url: https://github.com/nodejs/node/pull/41678
description: Passing an invalid callback to the `callback` argument
Expand Down Expand Up @@ -1641,11 +1648,9 @@ 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
Unless the connection was created with `allowRenegotiation: true`, 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`.
[`ERR_TLS_RENEGOTIATION_DISABLED`][] error.

### `tlsSocket.servername`

Expand Down Expand Up @@ -1765,6 +1770,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/67618
description: The `allowRenegotiation` option now defaults to `false`.
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67532
description: The `allowRenegotiation` option is now supported.
Expand Down Expand Up @@ -1866,8 +1874,8 @@ changes:
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`.
requested by the server. Renegotiation is deprecated (see [DEP0213][]).
**Default:** `false`.
* `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 @@ -2240,6 +2248,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/67618
description: The `allowRenegotiation` option now defaults to `false`.
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/67532
description: The `allowRenegotiation` option is now supported.
Expand Down Expand Up @@ -2283,10 +2294,10 @@ changes:
* `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`.
[DEP0213][]), and setting this to `true` emits a deprecation warning.
Setting this to `true` throws [`ERR_TLS_RENEGOTIATION_UNSUPPORTED`][]
where the TLS library does not support renegotiation on servers.
**Default:** `true`.
**Default:** `false`.
* `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
4 changes: 4 additions & 0 deletions lib/internal/tls/common.js
Original file line number Diff line number Diff line change
Expand Up @@ -158,8 +158,12 @@ function translatePeerCertificate(c) {
return c;
}

// Backs tls.CLIENT_RENEG_LIMIT and tls.CLIENT_RENEG_WINDOW.
const renegotiationLimits = { limit: 3, window: 600 };

module.exports = {
SecureContext,
renegotiationLimits,
createSecureContext,
translatePeerCertificate,
};
33 changes: 12 additions & 21 deletions lib/internal/tls/wrap.js
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,6 @@ const {
const {
assertCrypto,
getDeprecationWarningEmitter,
isPendingDeprecation,
kEmptyObject,
} = require('internal/util');

Expand Down Expand Up @@ -105,12 +104,8 @@ const {
} = 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,
'TLS renegotiation is deprecated. Only clients setting allowRenegotiation ' +
"to accept a server's request will remain supported.",
);
const traceTls = getOptionValue('--trace-tls');
const tlsKeylog = getOptionValue('--tls-keylog');
Expand Down Expand Up @@ -228,7 +223,7 @@ function onhandshakestart(now) {
if (lastHandshakeTime === 0)
return;

if ((now - lastHandshakeTime) >= tls.CLIENT_RENEG_WINDOW * 1000)
if ((now - lastHandshakeTime) >= common.renegotiationLimits.window * 1000)
this.handshakes = 1;
else
this.handshakes++;
Expand All @@ -237,7 +232,7 @@ function onhandshakestart(now) {

assert(owner._tlsOptions.isServer);

if (this.handshakes > tls.CLIENT_RENEG_LIMIT) {
if (this.handshakes > common.renegotiationLimits.limit) {
owner._emitTLSError(new ERR_TLS_SESSION_ATTACK());
return;
}
Expand All @@ -250,9 +245,12 @@ 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();
if (allowRenegotiation && isServer) {
// BoringSSL servers always refuse renegotiation.
if (isBoringSSL)
throw new ERR_TLS_RENEGOTIATION_UNSUPPORTED();
emitRenegotiationDeprecation();
}
}

function onhandshakedone() {
Expand Down Expand Up @@ -1003,7 +1001,7 @@ TLSSocket.prototype._init = function(socket, wrap) {
if (requestCert || rejectUnauthorized)
ssl.setVerifyMode(requestCert, rejectUnauthorized);

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

// Only call .onkeylog if there is a keylog listener.
Expand Down Expand Up @@ -1153,7 +1151,7 @@ TLSSocket.prototype.renegotiate = function(options, callback) {
if (this.destroyed)
return;

if (this._tlsOptions.allowRenegotiation === false) {
if (this._tlsOptions.allowRenegotiation !== true) {
if (callback) {
process.nextTick(callback, new ERR_TLS_RENEGOTIATION_DISABLED());
}
Expand Down Expand Up @@ -1266,13 +1264,6 @@ 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
27 changes: 25 additions & 2 deletions lib/tls.js
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,31 @@ const {
// every {CLIENT_RENEG_WINDOW} seconds. An error event is emitted if more
// renegotiations are seen. The settings are applied to all remote client
// connections.
exports.CLIENT_RENEG_LIMIT = 3;
exports.CLIENT_RENEG_WINDOW = 600;
const emitRenegotiationLimitDeprecation =
internalUtil.getDeprecationWarningEmitter(
'DEP0213',
'tls.CLIENT_RENEG_LIMIT and tls.CLIENT_RENEG_WINDOW are deprecated, as ' +
'TLS renegotiation is deprecated.',
);

function defineRenegotiationLimit(name, key) {
// Not enumerable, so that copying the exports does not emit the warning.
ObjectDefineProperty(exports, name, {
__proto__: null,
configurable: true,
enumerable: false,
get() {
emitRenegotiationLimitDeprecation();
return tlsCommon.renegotiationLimits[key];
},
set(value) {
emitRenegotiationLimitDeprecation();
tlsCommon.renegotiationLimits[key] = value;
},
});
}
defineRenegotiationLimit('CLIENT_RENEG_LIMIT', 'limit');
defineRenegotiationLimit('CLIENT_RENEG_WINDOW', 'window');

exports.DEFAULT_CIPHERS = getOptionValue('--tls-cipher-list');

Expand Down
1 change: 1 addition & 0 deletions test/common/boringssl.js
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@ function testRenegotiationUnsupported() {
port: server.address().port,
rejectUnauthorized: false,
maxVersion: 'TLSv1.2',
allowRenegotiation: true,
}, common.mustCall(() => {
const ok = client.renegotiate({}, common.mustCall((err) => {
assert.throws(() => { throw err; }, {
Expand Down
Loading
Loading