crypto: support loading private keys through STORE loaders

[panva]

Allow crypto.createPrivateKey() and APIs that consume private keys, such as crypto.sign(), crypto.privateDecrypt(), crypto.diffieHellman(), and crypto.decapsulate(), to load private keys through configured OpenSSL STORE loaders using WHATWG URL objects.

This supports direct URL input:

import { createPrivateKey } from 'node:crypto';

const key = createPrivateKey(
  new URL('file:///path/to/private-key.pem'),
);

It also supports object input with an optional passphrase or PIN and OpenSSL property query:

import { createPrivateKey, sign } from 'node:crypto';

const key = createPrivateKey({
  key: new URL('pkcs11:token=node;object=signing-key;type=private'),
  passphrase: process.env.PKCS11_PIN,
  properties: 'provider=pkcs11',
});

const signature = sign('sha256', Buffer.from('payload'), key);

The provider implementing the STORE loader must already be loaded in Node.js' default OpenSSL library context, for example through OpenSSL configuration. This API does not load providers.

passphrase is forwarded to the loader as its passphrase or PIN. properties is an OpenSSL property query used to select the STORE loader; it is not appended to the URL and is distinct from provider-specific URI parameters.

Why URL?

A URL distinguishes an external key reference from existing key material. Strings, buffers, typed arrays, and formatted objects retain their existing PEM, DER, JWK, and raw-key semantics. This avoids adding STORE loading to the key import/export format namespace.

URL input is accepted only in private-key contexts. A public key can be derived by first loading the private key and passing the resulting KeyObject to crypto.createPublicKey().

The resulting provider-backed key is an ordinary KeyObject and interoperates with existing private-key operations, key metadata, public-key derivation, and toCryptoKey() where supported by the key algorithm and provider. Provider policy continues to control permitted operations and private-key exportability.

The native STORE-loading path is available with OpenSSL >= 3.

Permission model

STORE loading adds the global openssl.store permission, enabled with --allow-openssl-store and exposed through the runtime permission APIs:

process.permission.has('openssl.store'); // true
process.permission.drop('openssl.store');
process.permission.has('openssl.store'); // false

This permission grants broad authority to configured STORE loaders. Loaders may access files, devices, tokens, or the network, and that access is not constrained by the fs.read, fs.write, or net permission scopes.

This broad capability matches OpenSSL's behavior: STORE loaders perform their own I/O, and OpenSSL may try its file loader before another loader for opaque URIs.

When STORE access is denied, Node.js redacts the URI from the permission error resource and permission diagnostics.

Passphrases and errors

Credentials should be supplied through passphrase rather than embedded in the URI.

If OpenSSL requests a passphrase and none was provided, Node.js throws ERR_MISSING_PASSPHRASE, matching existing encrypted private-key import behavior. Incorrect passphrases and provider failures continue to surface as OpenSSL errors.

Node.js redacts URIs from its own permission-denial errors. Errors reported by OpenSSL or a provider after loading begins may still include the URI.

[nodejs-github-bot]

Review requested:

• @nodejs/actions
• @nodejs/config
• @nodejs/crypto
• @nodejs/gyp
• @nodejs/security-wg

I changed the feature shape quite a bit. Dismissing a stale review.

[codecov]

Codecov Report

❌ Patch coverage is 75.32468% with 76 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.26%. Comparing base (a6e7e6a) to head (266e8f3).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
src/crypto/crypto_keys.cc	56.97%	21 Missing and 16 partials ⚠️
src/crypto/crypto_sig.cc	58.44%	12 Missing and 20 partials ⚠️
lib/internal/crypto/keys.js	95.78%	4 Missing ⚠️
src/crypto/crypto_ec.cc	33.33%	0 Missing and 2 partials ⚠️
src/permission/openssl_store_permission.cc	87.50%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63949      +/-   ##
==========================================
- Coverage   90.30%   90.26%   -0.04%     
==========================================
  Files         760      762       +2     
  Lines      247154   247425     +271     
  Branches    46613    46674      +61     
==========================================
+ Hits       223181   223347     +166     
- Misses      15443    15526      +83     
- Partials     8530     8552      +22     

Files with missing lines	Coverage Δ
lib/internal/process/permission.js	81.70% <100.00%> (+0.22%)	⬆️
lib/internal/process/pre_execution.js	97.72% <100.00%> (+<0.01%)	⬆️
lib/internal/url.js	93.27% <100.00%> (+0.09%)	⬆️
src/crypto/crypto_cipher.cc	76.92% <100.00%> (+0.04%)	⬆️
src/crypto/crypto_keys.h	62.22% <ø> (ø)
src/env.cc	85.50% <100.00%> (+0.19%)	⬆️
src/node_options.cc	76.74% <100.00%> (+0.12%)	⬆️
src/node_options.h	98.02% <100.00%> (+<0.01%)	⬆️
src/permission/openssl_store_permission.h	100.00% <100.00%> (ø)
src/permission/permission.cc	82.56% <100.00%> (+0.24%)	⬆️
... and 6 more

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

[panva]

@mcollina

1. addressed with a documentation update in 90a0903, blocking openssl's file: loader entirely was in my original version of this, also had it tied in the existing fs permission, but ultimately there's no blocking opaque uris from reaching them anyway. I tried, didn't work and i always found ways to bypass.
2. addressed in 90a0903
3. addressed in 7725852

[mcollina]

lgtm

[panva]

Resolving conflict with d1f3d0a

[github-actions]

Platform	Number of requisites	Proportion of new derivations
x86_64-linux	451 -> 455 => +4	4 / 455 = 0.8%
aarch64-linux	452 -> 456 => +4	4 / 456 = 0.8%
x86_64-darwin	387 -> 393 => +6	6 / 393 = 1.5%
aarch64-darwin	392 -> 398 => +6	6 / 398 = 1.5%
Total	1682 -> 1702 => +20	20 / 1702 = 1.1%

Changelog

@@ -694,0 +695 @@
+/nix/store/i8jyv4awyfkg1b065gcqcqpp27x7iyfm-libtasn1-4.21.0 (aarch64-darwin)
@@ -695,0 +697 @@
+/nix/store/rx1vh845iyrzg8s011jn3gx5m79ls7vq-libtasn1-4.21.0 (x86_64-darwin)
@@ -1000,0 +1003,4 @@
+/nix/store/wzl026xydz70snlvqalhyxi6ykvwqg75-node-pkcs11-softhsm (aarch64-darwin)
+/nix/store/7y5rw6fh5k7v29w80a200538b1m0416d-node-pkcs11-softhsm (aarch64-linux)
+/nix/store/ry1b8p26d8956b07fnyhdy1km1798fq2-node-pkcs11-softhsm (x86_64-darwin)
+/nix/store/4al1pqpw5l1wgd7vwjn0sfywj993gij9-node-pkcs11-softhsm (x86_64-linux)
@@ -1156,0 +1163,5 @@
+/nix/store/47x3k6bg2vawsrgynf65kxdlq1pr0kh7-openssl-pkcs11.cnf (aarch64-darwin)
+/nix/store/w3y21hx5dg2hnkch5lna79cz265fiphq-openssl-pkcs11.cnf (aarch64-linux)
+/nix/store/7sz3idgaqq1dpa1sc756c25lvh9hb9g1-openssl-pkcs11.cnf (x86_64-darwin)
+/nix/store/g6vlpipryrns8b11fmnn2mf4h3f63ahf-openssl-pkcs11.cnf (x86_64-linux)
+/nix/store/y8s864yb4binyfhzg198hnk38lshm3az-p11-kit-0.26.2 (aarch64-darwin)
@@ -1157,0 +1169 @@
+/nix/store/3m6nv9jvs114k0xpqnsqjmjyzv9643qf-p11-kit-0.26.2 (x86_64-darwin)
@@ -1345,0 +1358,4 @@
+/nix/store/ai6m8bm8w216jwicdym4ndlzbdc149nw-pkcs11-provider-1.2.0 (aarch64-darwin)
+/nix/store/77kxyyzmvkgm75g2dzxaccirn2pi148k-pkcs11-provider-1.2.0 (aarch64-linux)
+/nix/store/jb4w25b7dxwfy8fci52zgf8r9swb5mmb-pkcs11-provider-1.2.0 (x86_64-darwin)
+/nix/store/9w72flqh3gj158chgp9s8w65q587s69s-pkcs11-provider-1.2.0 (x86_64-linux)
@@ -1519,0 +1536,4 @@
+/nix/store/f39kdfrc185dij9nvvaqxzlx3vgzs181-softhsm-2.7.0 (aarch64-darwin)
+/nix/store/4w902rmqzd91j44kq8ql0r9m8fpmgfcs-softhsm-2.7.0 (aarch64-linux)
+/nix/store/8n7flys8x90kpz21lzjk76av2ipkngcp-softhsm-2.7.0 (x86_64-darwin)
+/nix/store/fiw0d9ikli4iy0vjsfpp3nd6qsxk01ay-softhsm-2.7.0 (x86_64-linux)

[mcollina]

lgtm

[nodejs-github-bot]

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

[nodejs-github-bot]

Landed in 565c3da