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 74.06143% with 76 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.14%. Comparing base (0618e9f) to head (cd2dd6d).
⚠️ Report is 19 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.60%	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.14%   90.14%   -0.01%     
==========================================
  Files         743      746       +3     
  Lines      242408   242774     +366     
  Branches    45656    45749      +93     
==========================================
+ Hits       218520   218838     +318     
- Misses      15387    15395       +8     
- Partials     8501     8541      +40     

Files with missing lines	Coverage Δ
lib/internal/process/permission.js	81.70% <100.00%> (+0.22%)	⬆️
lib/internal/process/pre_execution.js	97.84% <100.00%> (-0.12%)	⬇️
lib/internal/url.js	93.23% <100.00%> (+0.05%)	⬆️
src/crypto/crypto_cipher.cc	76.92% <100.00%> (+0.04%)	⬆️
src/crypto/crypto_keys.h	65.11% <ø> (ø)
src/env.cc	85.35% <100.00%> (-0.04%)	⬇️
src/node_options.cc	76.72% <100.00%> (+0.12%)	⬆️
src/node_options.h	98.01% <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 31 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]

With db7cc5b and cecfdce...0938489 in place I have to cleanup workarounds on the wrong layer which are now absorbed by ncrypto

[nodejs-github-bot]

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

[aduh95]

It might get confusing when the user provides --arg pkcs11 '<some value>' --arg withPkcs11 false. We could rename it to withDefaultPkcs11, or merge the two arguments

[aduh95]

I’m not sure we want to do that, it forces to rebuild the derivation even if it’s cached by the Nix project – for softhms there’s no upside given that upstream doesn’t define a doCheck. Maybe we should override only if openssl != pkgs.openssl?

[aduh95]

Why do we use a variable here that we only use once?

[aduh95]

Do we need a hook and temp files, or could we have a derivation that outputs a fixed conf file?