Skip to content

tls: docs-deprecate TLS renegotiation, add allowRenegotiation opt-in - #67532

Merged
nodejs-github-bot merged 1 commit into
nodejs:mainfrom
pimterry:tls-drop-client-reneg
Nov 18, 2026
Merged

nodejs-github-bot merged 1 commit into
nodejs:mainfrom
pimterry:tls-drop-client-reneg

Conversation

@pimterry

@pimterry pimterry commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

I think we should deprecate TLS renegotiation support, disable it by default soon, and aim to eventually mostly remove it.

Quick refresher: renegotiation is a TLS 1.2 feature (not in 1.3) where the client or server can ask the other peer to change the configuration of an existing connection, redo the handshake, and then continue with that new configuration on the old TLS connection. Today we support this in all 4 directions by default: initiating renegotiation for both clients & servers, and accepting remote requests for renegotiation from clients or servers.

Steps would be:

  • Docs deprecate default support for all 4 cases in current versions (this PR).
  • Flip the default to disabled for all 4 cases, in v27.
    • When the default is overridden to enable it, show a deprecation warning in 3/4 of the cases - this will be removed completely in future.
    • Keep the 4th case with no warning, but opt-in only: clients accepting server-initiated renegotiations (this is useful for legacy server support).
  • Later on (v28 at the earliest) remove the other 3 cases entirely leaving only opt-in client support for accepting server requests.

I think we should drop this because:

  • It's hard to secure, both for us (see recent CVEs) and for end users using these APIs. Renegotiation means an existing TLS connection's authorization state & configuration can change silently any time, e.g. in the middle of HTTP request processing. I strongly suspect very little code in the wild is aware of this or handling it correctly.
  • There's nearly no good reasons to do it nowadays. Changing security params during a connection is quite unusual & suspicious imo. The only somewhat reasonable case is to add client authentication to an active connection. Some servers apparently do use that (when you send an HTTP request that needs auth, renegotiate to require mTLS auth) but I think we can support that one case in isolation (opt-in) and drop the rest. Modern clients & protocols just reconnect with the new configuration instead.
  • It's already being removed (or has never been implemented at all, in new stacks) in most modern stacks elsewhere:
    • TLS 1.3 dropped it, replacing it with post-handshake authentication (PHA) which implements certificate auth and nothing else. We don't support PHA, and we shouldn't start now - similarly to renegotiation, active connections dynamically changing auth status is risky.
    • HTTP/2 forbids renegotiation and PHA. HTTP/3 doesn't support TLS 1.2 at all, and forbids PHA in TLS 1.3.
    • Browsers support this only for HTTP/1.1 on TLS 1.2, only for accepting the server-initiated legacy case. None support PHA by default.
    • BoringSSL disables all renegotiation by default, only supports accepting the server-initiated case with opt-in.
    • OpenSSL disabled client-initiated renegotiation by default in 3.0.0 - we currently override that default to actively enable it in every case.
    • Go crypto/tls has never supported initiating renegotiation, and only supports clients accepting server-initiated request to renegotiate (same legacy server case). Also doesn't support PHA.
    • Rustls doesn't support rengotiation or PHA.
  • Because of this, it's already very rarely used. You can't use it with modern TLS, modern HTTP, or modern clients, so the existing scope is fairly limited.
    • One counter-example I did find is Kibana, who do use it, but not for its real purpose: AFAICT they renegotiate connections just to force the client to resend the same client certificate, so they can get the full chain for authentication, because when resuming a TLS connection they don't have the old chain available (just the leaf). I've outlined some better alternatives to this here. This is already non-functional for them today with TLS 1.3 and/or HTTP/2+.

We did previously discuss this 10 years ago: #6983. At the time it was challenging, but in the meantime I think the ecosystem consensus has changed, and most of the remaining use cases have become unsupported everywhere else. Only the one use case remains, exclusively for accessing specific legacy server configurations.

This PR does nothing breaking for now, it's just laying the groundwork, which we'll want to backport to v26 too:

  • Docs deprecation for the relevant APIs.
  • Add a new allowRenegotiation option for clients & servers to explicitly enable/disable renegotiation from options. Defaults to true for now, will flip to false for v27 imminently.
  • A new --pending-deprecation warning if you use renegotiation, except for clients that set allowRenegotiation: true and just accept server-initiated requests.

Notable change:

TLS 1.2 renegotiation, which allows either peer to redo the handshake and change the configuration of an existing connection, is now deprecated (DEP0213). It is hard to use securely, is forbidden by HTTP/2, and was removed entirely in TLS 1.3.

A new allowRenegotiation option for tls.connect() and tls.createServer() controls whether renegotiation is enabled on connections. It defaults to true for now, but renegotiation will be disabled by default in a future major release such that enabling this explicitly will be required. In a subsequent major release, it is likely to be removed entirely, except for opt-in support for clients to accept received renegotiation requests from legacy servers. Run with --pending-deprecation to find affected code.

@pimterry pimterry added semver-minor PRs that contain new features and should be released in the next minor version. notable-change PRs with changes that should be highlighted in changelogs. labels Nov 16, 2026
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/crypto
  • @nodejs/http
  • @nodejs/net
  • @nodejs/userland-migrations

@github-actions

Copy link
Copy Markdown
Contributor

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @pimterry.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. crypto Issues and PRs related to the crypto subsystem. https Issues and PRs related to the https subsystem. needs-ci PRs that need a full CI run. tls Issues and PRs related to the tls subsystem. labels Nov 16, 2026
For now this changes very little, but offers an option to directly
control whether this is supported. In future, this will default to
'false' (disabling by default) and eventually be mostly removed,
except opt-in client support for accepting renegotiation requests
from servers.

Signed-off-by: Tim Perry <pimterry@gmail.com>
@pimterry
pimterry force-pushed the tls-drop-client-reneg branch from 56d9f29 to 118c40f Compare November 16, 2026 22:38
@codecov

codecov Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.45455% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.68%. Comparing base (d3c4048) to head (118c40f).
⚠️ Report is 58 commits behind head on main.

Files with missing lines Patch % Lines
src/crypto/crypto_tls.cc 85.71% 0 Missing and 2 partials ⚠️
lib/internal/tls/wrap.js 97.91% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #67532      +/-   ##
==========================================
+ Coverage   90.66%   90.68%   +0.01%     
==========================================
  Files         799      800       +1     
  Lines      280252   280555     +303     
  Branches    54121    54191      +70     
==========================================
+ Hits       254088   254416     +328     
+ Misses      16285    16233      -52     
- Partials     9879     9906      +27     
Files with missing lines Coverage Δ
lib/https.js 96.91% <100.00%> (+0.01%) ⬆️
src/crypto/crypto_tls.h 90.62% <ø> (ø)
lib/internal/tls/wrap.js 95.79% <97.91%> (+0.05%) ⬆️
src/crypto/crypto_tls.cc 79.36% <85.71%> (+0.05%) ⬆️

... and 57 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@pimterry pimterry added the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 17, 2026
@github-actions github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 17, 2026
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

@mcollina mcollina left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm actually ok in disabling it by default and/or removing it entirely even in previous releases (will require a tsc approval).

@pimterry pimterry added the resume-ci Add this label to resume the latest eligible Jenkins CI run on a PR with an approving review. label Nov 17, 2026
@github-actions github-actions Bot removed the resume-ci Add this label to resume the latest eligible Jenkins CI run on a PR with an approving review. label Nov 17, 2026
@nodejs-github-bot

nodejs-github-bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

@panva panva added the author ready PRs with CI started, the required approvals, and no outstanding review comments. label Nov 17, 2026
@pimterry

Copy link
Copy Markdown
Member Author

Looks like people are on board 😄

I'm actually ok in disabling it by default and/or removing it entirely even in previous releases (will require a tsc approval).

I would love to kill all this even sooner, but I'm not sure we can easily, since there are real apps using this for specific niche cases (like Kibana) so this would mean at least some production breakage for end users in a minor bump. There's a good security argument, but it would make a mess. If we really do want to, we could try to coordinate with existing users but we'll struggle to find them since I expect it's mostly legacy application code (not OSS libs).

There are other middle grounds though. We could backport just an update to the security model (exclude renegotiation from it) plus a runtime warning for anybody who uses it, like: "You are using TLS renegotiation, be aware that this has security risks, and usage is outside the scope of the Node.js security model". That'd simplify our vulnerability handling but limit breakage to just a warning.

(Might be worth considering more generally actually. Could we exclude issues in all runtime-deprecated features from being treated as vulnerabilities? We do the same for experimental features, you use them at your own risk)

@jasnell jasnell added the commit-queue PRs queued for automated landing through the Commit Queue. label Nov 18, 2026
@nodejs-github-bot
nodejs-github-bot merged commit b7df44b into nodejs:main Nov 18, 2026
72 checks passed
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Landed in b7df44b

@nodejs-github-bot nodejs-github-bot removed the commit-queue PRs queued for automated landing through the Commit Queue. label Nov 18, 2026
@pimterry
pimterry deleted the tls-drop-client-reneg branch November 19, 2026 14:18
aduh95 pushed a commit that referenced this pull request Nov 19, 2026
For now this changes very little, but offers an option to directly
control whether this is supported. In future, this will default to
'false' (disabling by default) and eventually be mostly removed,
except opt-in client support for accepting renegotiation requests
from servers.

Signed-off-by: Tim Perry <pimterry@gmail.com>
PR-URL: #67532
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author ready PRs with CI started, the required approvals, and no outstanding review comments. c++ Issues and PRs that require attention from people who are familiar with C++. crypto Issues and PRs related to the crypto subsystem. https Issues and PRs related to the https subsystem. needs-ci PRs that need a full CI run. notable-change PRs with changes that should be highlighted in changelogs. semver-minor PRs that contain new features and should be released in the next minor version. tls Issues and PRs related to the tls subsystem.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants