Skip to content

Drop the hand-rolled TLS client hello parser - #64827

Open
pimterry wants to merge 1 commit into
nodejs:mainfrom
pimterry:drop-client-parser
Open

Drop the hand-rolled TLS client hello parser#64827
pimterry wants to merge 1 commit into
nodejs:mainfrom
pimterry:drop-client-parser

Conversation

@pimterry

Copy link
Copy Markdown
Member

Our TLS code currently contains a custom parser for TLS client hellos hand-rolled in C++. This is complicated and a bit scary (which is why we have a separate fuzzer for it) and does extra work anytime it's used: OpenSSL already parses the hello, and this duplicates it, and adds checks throughout various other methods to support that. It's only required for a niche legacy feature (TLS session ids) that isn't even supported in TLS 1.3, but it makes up just under 10% of our TLS implementation (and ~15% of the TLS C++).

This parser exists because 'resumeSession' needs to support async lookups for session ids, on top of OpenSSL's SSL_CTX_sess_set_get_cb which is sync-only. We handled that by parsing out the session id ourselves, in advance, and passing through to OpenSSL when we were ready to answer synchronously.

Nowadays though (since OpenSSL 1.1.1) both OpenSSL & BoringSSL have an early ClientHello callback with suspend/resume support to handle this properly. This custom parser is redundant, and can be replaced by standard APIs in both backends.

We've previously talked about dropping this, over literally more than a decade, e.g. #1464 stopping using the parser to power SNI & OCSP, #1462 discussed dropping session ids completely to help us kill it, and #5774 trying to deprecate it away.

Nowadays it's much easier and we don't need any breaking changes at all. This PR deletes lots of code and switches to the modern mechanisms for this (separate impls for BoringSSL & OpenSSL). It drops the client hello parser & all related infrastructure, while preserving all the functionality. We could aim to drop session ids later anyway as a breaking change, but this makes them very cheap to keep in the meantime.

In addition, one of the new tests here covers a bug that this fixes en route: the hello parser silently dropped session events on fragmented hellos, which we now handle correctly instead for free. That fix should be the only externally visible change.

@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/crypto
  • @nodejs/gyp
  • @nodejs/net

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jul 29, 2026

@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.

lgtm

This existed for 'resumeSession', which needed to do an async lookup
though SSL_CTX_sess_set_get_cb is sync-only. Nowadays both OpenSSL &
BoringSSL have an early ClientHello callback for suspend/resume to
handle this properly, so it was redundant, in addition to being
complicated and generally a bit fragile & scary.

This PR switches to use the modern OpenSSL/BoringSSL mechanisms for this
and drops the client hello parser & related infrastructure completely.

In addition, there's a new test here, covering a fixed bug: the hello
parser silently dropped fragmented hellos, which we now do handle
correctly.

Signed-off-by: Tim Perry <pimterry@gmail.com>
@pimterry
pimterry force-pushed the drop-client-parser branch from 00c4a38 to 5875e8e Compare July 29, 2026 18:38
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

@codecov

codecov Bot commented Jul 29, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 87.30159% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.17%. Comparing base (41525ab) to head (5875e8e).
⚠️ Report is 18 commits behind head on main.

Files with missing lines Patch % Lines
src/crypto/crypto_tls.cc 87.03% 3 Missing and 4 partials ⚠️
src/crypto/crypto_tls.h 50.00% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #64827      +/-   ##
==========================================
+ Coverage   90.16%   90.17%   +0.01%     
==========================================
  Files         746      743       -3     
  Lines      242660   242604      -56     
  Branches    45720    45697      -23     
==========================================
- Hits       218793   218774      -19     
+ Misses      15360    15352       -8     
+ Partials     8507     8478      -29     
Files with missing lines Coverage Δ
lib/internal/tls/wrap.js 95.15% <100.00%> (+0.04%) ⬆️
src/crypto/crypto_context.cc 72.41% <100.00%> (+0.13%) ⬆️
src/crypto/crypto_context.h 100.00% <ø> (ø)
src/crypto/crypto_tls.h 82.35% <50.00%> (-4.32%) ⬇️
src/crypto/crypto_tls.cc 78.40% <87.03%> (+0.09%) ⬆️

... and 76 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants