diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index b2e6032af6e5..50c7a7e357ff 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -4885,18 +4885,21 @@ Use global `TextDecoder` and `TextEncoder` instead. -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. @@ -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. diff --git a/doc/api/tls.md b/doc/api/tls.md index 08c5e66ef629..d82ea70e2c80 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -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 @@ -906,6 +906,9 @@ connection is open.