crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts

[pimterry]

Once upon a time (#20237) we attempted to remove the secureContext.context._external field which exposes OpenSSL contexts. This was later reverted (#21711) because it turns out there are external native addons which do want to integrate with Node's OpenSSL, and were using this JS API as it's currently the only way to do so.

At the time, @sam-github said:

maybe there is some way to have a pure C++ API, perhaps node::crypto::GetSecureContextFromHandle(), that would allow C++ addons to get the SecureContext? This would make more sense to me, given that the SecureContext can only be used with the SSL_ APIs by C++ code, only C++ needs to get it. This would still have the positive effect of removing the context from the js API.

I think this makes a lot of sense. I'm in the process of building a native addon myself that needs access to OpenSSL contexts (user-space solution for #41112). I'd like to do this properly, without having to awkwardly hook onto internals like this.

This PR does that: creating a new node::crypto::GetSSLCtx native API, so C++ addons can access the OpenSSL context directly. With this in place, we could potentially drop _external entirely from the JS API (and maybe even .context) in some future major bump. Naming is intended to match the SSL_CTX type and OpenSSL SSL_CTX_... APIs etc, but open to bikeshedding that further.

This API itself should be easy to keep stable as OpenSSL changes, but obviously SSL_CTX won't be stable as it has APIs that will change as we upgrade OpenSSL versions etc. I think that's fine, there's clearly no real avoiding that and addons using this will have to be able to deal with OpenSSL changes like this appropriately. Reasonable given that it's a native-only API imo.

[nodejs-github-bot]

Review requested:

• @nodejs/crypto
• @nodejs/gyp

[codecov]

Codecov Report

❌ Patch coverage is 88.23529% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.66%. Comparing base (65b521f) to head (e378906).
⚠️ Report is 49 commits behind head on main.

Files with missing lines	Patch %	Lines
src/crypto/crypto_context.cc	88.23%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62254      +/-   ##
==========================================
- Coverage   89.66%   89.66%   -0.01%     
==========================================
  Files         676      676              
  Lines      206500   206572      +72     
  Branches    39539    39555      +16     
==========================================
+ Hits       185168   185231      +63     
+ Misses      13463    13459       -4     
- Partials     7869     7882      +13     

Files with missing lines	Coverage Δ
src/node.h	92.30% <ø> (ø)
src/crypto/crypto_context.cc	71.98% <88.23%> (+0.47%)	⬆️

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

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/71780/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/71795/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/71838/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/71859/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/71864/

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/62254
✔  Done loading data for nodejs/node/pull/62254
----------------------------------- PR info ------------------------------------
Title      crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts (#62254)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     pimterry:getsslctx-api -> nodejs:main
Labels     crypto, c++, needs-ci, commit-queue-squash
Commits    2
 - crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts
 - Handle JS getter exceptions in GetSSLCtx
Committers 1
 - Tim Perry <pimterry@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/62254
Reviewed-By: Anna Henningsen <anna@addaleax.net>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/62254
Reviewed-By: Anna Henningsen <anna@addaleax.net>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Sat, 14 Mar 2026 16:27:50 GMT
   ✔  Approvals: 1
   ✔  - Anna Henningsen (@addaleax): https://github.com/nodejs/node/pull/62254#pullrequestreview-3950716542
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2026-03-18T17:02:27Z: https://ci.nodejs.org/job/node-test-pull-request/71864/
- Querying data for job/node-test-pull-request/71864/
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 62254
From https://github.com/nodejs/node
 * branch                  refs/pull/62254/merge -> FETCH_HEAD
✔  Fetched commits as 22fc52bda16b..e37890620fa3
--------------------------------------------------------------------------------
[main ea4524b511] crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts
 Author: Tim Perry <pimterry@gmail.com>
 Date: Sat Mar 14 16:09:37 2026 +0100
 6 files changed, 159 insertions(+)
 create mode 100644 test/addons/openssl-get-ssl-ctx/binding.cc
 create mode 100644 test/addons/openssl-get-ssl-ctx/binding.gyp
 create mode 100644 test/addons/openssl-get-ssl-ctx/test.js
[main a8907b2aca] Handle JS getter exceptions in GetSSLCtx
 Author: Tim Perry <pimterry@gmail.com>
 Date: Sun Mar 15 18:15:20 2026 +0100
 2 files changed, 12 insertions(+)
   ✔  Patches applied
There are 2 commits in the PR. Attempting to fixup everything into first commit.
[main 55124ce18f] crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts
 Author: Tim Perry <pimterry@gmail.com>
 Date: Sat Mar 14 16:09:37 2026 +0100
 6 files changed, 171 insertions(+)
 create mode 100644 test/addons/openssl-get-ssl-ctx/binding.cc
 create mode 100644 test/addons/openssl-get-ssl-ctx/binding.gyp
 create mode 100644 test/addons/openssl-get-ssl-ctx/test.js
--------------------------------- New Message ----------------------------------
crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts
This intended to replace usage of the unsupported _external field,

offering an official API for native addons to access OpenSSL directly

while reducing the JS API and internal field exposure.
PR-URL: #62254

Reviewed-By: Anna Henningsen <anna@addaleax.net>
[main 7ab7c5e2b4] crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts

Author: Tim Perry <pimterry@gmail.com>

Date: Sat Mar 14 16:09:37 2026 +0100

6 files changed, 171 insertions(+)

create mode 100644 test/addons/openssl-get-ssl-ctx/binding.cc

create mode 100644 test/addons/openssl-get-ssl-ctx/binding.gyp

create mode 100644 test/addons/openssl-get-ssl-ctx/test.js

✔  7ab7c5e2b40bb36397d894ff8f9d09044637a6a0

✔  0:0      no Co-authored-by metadata                co-authored-by-is-trailer

✔  0:0      skipping fixes-url                        fixes-url

✔  0:0      blank line after title                    line-after-title

✔  0:0      line-lengths are valid                    line-length

✔  0:0      metadata is at end of message             metadata-end

✔  5:8      PR-URL is valid.                          pr-url

✔  0:0      reviewers are valid                       reviewers

✔  0:0      valid subsystems                          subsystem

✔  0:0      Title is formatted correctly.             title-format

⚠  0:50     Title should be <= 50 columns.            title-length
The following commits are ready to be pushed to origin/main

7ab7c5e2b4 crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts


Temporary files removed.

To finish landing:

Run:

git push origin main
Post "Landed in 7ab7c5e2b40b" in crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts #62254

gh pr comment crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts #62254 --body "Landed in 7ab7c5e2b40b"

gh pr close crypto: add crypto::GetSSLCtx API for addon access to OpenSSL contexts #62254

https://github.com/nodejs/node/actions/runs/23432104950

[nodejs-github-bot]

Landed in 2263b4d