From 9e8f05c6912b1fe1dd007e025c5301d3087fceee Mon Sep 17 00:00:00 2001
From: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com>
Date: Fri, 28 Aug 2026 06:10:13 -0500
Subject: [PATCH 1/5] crypto: add crypto.parsePKCS12()

Return the private key, end-entity certificate, and CA certificates from
a PKCS#12 (.p12/.pfx) bundle as a KeyObject and X509Certificate
instances.

Node.js already parses PKCS#12 in SecureContext::LoadPKCS12, which backs
tls's `pfx` option, but the results are consumed directly into an
SSL_CTX and never reach JavaScript. Callers who need the key or the
certificates for anything other than an immediate TLS connection have to
shell out to `openssl pkcs12` or take a userland dependency.

The binding wraps d2i_PKCS12_bio() and PKCS12_parse() and follows their
semantics, matching the existing TLS path: the first private key is
returned, the end-entity certificate is the one associated with that
key, and any remaining certificates are returned through `ca`. A bundle
containing no private key reports `cert` as null and returns its
certificates through `ca`.

Absent and empty passphrases are kept distinct, since OpenSSL treats
them differently. Bundles that require OpenSSL's legacy provider throw
ERR_CRYPTO_UNSUPPORTED_OPERATION, reusing the error added for the TLS
path.

Signed-off-by: bmuenzenmeyer <brian.muenzenmeyer@gmail.com>
---
 doc/api/crypto.md                   |  72 ++++++++++
 lib/crypto.js                       |   2 +
 lib/internal/crypto/keys.js         |  54 ++++++++
 node.gyp                            |   2 +
 src/crypto/crypto_pkcs12.cc         | 205 ++++++++++++++++++++++++++++
 src/crypto/crypto_pkcs12.h          |  23 ++++
 src/node_crypto.cc                  |   1 +
 src/node_crypto.h                   |   1 +
 test/parallel/test-crypto-pkcs12.js | 131 ++++++++++++++++++
 9 files changed, 491 insertions(+)
 create mode 100644 src/crypto/crypto_pkcs12.cc
 create mode 100644 src/crypto/crypto_pkcs12.h
 create mode 100644 test/parallel/test-crypto-pkcs12.js

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 8d80bdc299aa..bba0c2358f4b 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -5338,6 +5338,75 @@ const derivedKey = hkdfSync('sha512', 'key', 'salt', 'info', 64);
 console.log(Buffer.from(derivedKey).toString('hex'));  // '24156e2...5391653'
 ```
 
+### `crypto.parsePKCS12(bundle[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `bundle` {ArrayBuffer|Buffer|TypedArray|DataView} The DER-encoded PKCS#12
+  bundle.
+* `options` {Object}
+  * `passphrase` {string|ArrayBuffer|Buffer|TypedArray|DataView} The passphrase
+    protecting the bundle. Omit for bundles with no passphrase. Omitting this
+    option is **not** equivalent to passing an empty string; the two are
+    handled differently, and a bundle created with one will not open with the
+    other.
+* Returns: {Object}
+  * `key` {KeyObject|null} The private key, or `null` if the bundle contains
+    none.
+  * `cert` {X509Certificate|null} The end-entity certificate, or `null` if the
+    bundle contains none.
+  * `ca` {X509Certificate\[]} Any additional certificates in the bundle, such
+    as intermediates and roots. May be empty.
+
+Parses a PKCS#12 bundle — commonly seen with the `.p12` or `.pfx` extension —
+and returns its contents.
+
+```mjs
+import { parsePKCS12 } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+const { key, cert, ca } = parsePKCS12(
+  readFileSync('bundle.p12'),
+  { passphrase: 'secret' },
+);
+
+console.log(cert.subject);
+console.log(key.export({ type: 'pkcs8', format: 'pem' }));
+```
+
+```cjs
+const { parsePKCS12 } = require('node:crypto');
+const { readFileSync } = require('node:fs');
+
+const { key, cert, ca } = parsePKCS12(
+  readFileSync('bundle.p12'),
+  { passphrase: 'secret' },
+);
+
+console.log(cert.subject);
+console.log(key.export({ type: 'pkcs8', format: 'pem' }));
+```
+
+A PKCS#12 bundle may technically contain more than one private key. This API
+returns only the first, matching the behavior of OpenSSL's `PKCS12_parse()`.
+
+The end-entity certificate is identified by its association with the private
+key. A bundle containing no private key therefore reports `cert` as `null` and
+returns all of its certificates through `ca`.
+
+Bundles encrypted with older algorithms — notably RC2 and PBE-SHA1 variants
+produced by legacy Windows tooling and older versions of `keytool` — require
+OpenSSL's legacy provider. Reading these throws an error with the code
+[`ERR_CRYPTO_UNSUPPORTED_OPERATION`][]; starting Node.js with
+[`--openssl-legacy-provider`][] may allow them to be read, subject to the
+security implications of enabling that provider.
+
+To use a PKCS#12 bundle directly for a TLS connection, prefer the `pfx` option
+of [`tls.createSecureContext()`][] rather than parsing and re-supplying the
+parts.
+
 ### `crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)`
 
 <!-- YAML
@@ -7438,11 +7507,13 @@ See the [list of SSL OP Flags][] for details.
 [`--enable-fips`]: cli.md#--enable-fips
 [`--force-fips`]: cli.md#--force-fips
 [`--openssl-config`]: cli.md#--openssl-configfile
+[`--openssl-legacy-provider`]: cli.md#--openssl-legacy-provider
 [`--openssl-shared-config`]: cli.md#--openssl-shared-config
 [`BN_is_prime_ex`]: https://www.openssl.org/docs/man1.1.1/man3/BN_is_prime_ex.html
 [`Buffer`]: buffer.md
 [`DH_generate_key()`]: https://www.openssl.org/docs/man3.0/man3/DH_generate_key.html
 [`DiffieHellmanGroup`]: #class-diffiehellmangroup
+[`ERR_CRYPTO_UNSUPPORTED_OPERATION`]: errors.md#err_crypto_unsupported_operation
 [`KeyObject`]: #class-keyobject
 [`Sign`]: #class-sign
 [`String.prototype.normalize()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize
@@ -7499,6 +7570,7 @@ See the [list of SSL OP Flags][] for details.
 [`stream.Transform`]: stream.md#class-streamtransform
 [`stream.Writable` options]: stream.md#new-streamwritableoptions
 [`stream.transform` options]: stream.md#new-streamtransformoptions
+[`tls.createSecureContext()`]: tls.md#tlscreatesecurecontextoptions
 [`util.promisify()`]: util.md#utilpromisifyoriginal
 [`verify.update()`]: #verifyupdatedata-inputencoding
 [`verify.verify()`]: #verifyverifykey-signature-signatureencoding
diff --git a/lib/crypto.js b/lib/crypto.js
index ac4b0a33efb8..6965d30d62d4 100644
--- a/lib/crypto.js
+++ b/lib/crypto.js
@@ -84,6 +84,7 @@ const {
   createSecretKey,
   createPublicKey,
   createPrivateKey,
+  parsePKCS12,
   KeyObject,
 } = require('internal/crypto/keys');
 const {
@@ -206,6 +207,7 @@ module.exports = {
   getHashes,
   hkdf,
   hkdfSync,
+  parsePKCS12,
   pbkdf2,
   pbkdf2Sync,
   generateKeyPair,
diff --git a/lib/internal/crypto/keys.js b/lib/internal/crypto/keys.js
index 2bc63a2419fa..e140911294bb 100644
--- a/lib/internal/crypto/keys.js
+++ b/lib/internal/crypto/keys.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const {
+  ArrayPrototypeMap,
   ArrayPrototypeSlice,
   ObjectDefineProperties,
   ObjectPrototypeHasOwnProperty,
@@ -35,6 +36,7 @@ const {
   kKeyEncodingPKCS8,
   kKeyEncodingSPKI,
   kKeyEncodingSEC1,
+  parsePKCS12: _parsePKCS12,
 } = internalBinding('crypto');
 
 const {
@@ -77,6 +79,8 @@ const {
   isArrayBufferView,
 } = require('internal/util/types');
 
+const { Buffer } = require('buffer');
+
 const {
   fileURLToPath,
   getURLHref,
@@ -739,6 +743,55 @@ function createPublicKey(key) {
   return new PublicKeyObject(handle);
 }
 
+/**
+ * Parses a PKCS#12 (.p12 / .pfx) bundle. Returns an object holding the first
+ * private key as `key`, the certificate associated with it as `cert`, and any
+ * remaining certificates as an array in `ca`; `key` and `cert` are null when
+ * the bundle contains none.
+ * @param {ArrayBuffer|Buffer|TypedArray|DataView} bundle
+ * @param {object} [options]
+ * @returns {object}
+ */
+function parsePKCS12(bundle, options = kEmptyObject) {
+  if (!isArrayBufferView(bundle) && !isAnyArrayBuffer(bundle)) {
+    throw new ERR_INVALID_ARG_TYPE(
+      'bundle',
+      ['ArrayBuffer', 'TypedArray', 'DataView', 'Buffer'],
+      bundle);
+  }
+
+  validateObject(options, 'options');
+  const { passphrase } = options;
+
+  // Absent and empty passphrases are distinct at the OpenSSL level and are
+  // kept distinct here. `undefined` means no passphrase; '' means a
+  // zero-length one.
+  let passBuf;
+  if (passphrase !== undefined) {
+    passBuf = getArrayBufferOrView(passphrase, 'options.passphrase', 'utf8');
+    // The binding reads the passphrase as a view; wrap a bare ArrayBuffer.
+    if (isAnyArrayBuffer(passBuf)) passBuf = Buffer.from(passBuf);
+  }
+
+  // Likewise, the binding reads the bundle as a view.
+  const bundleBuf = isAnyArrayBuffer(bundle) ? Buffer.from(bundle) : bundle;
+
+  const {
+    0: keyHandle,
+    1: certHandle,
+    2: caHandles,
+  } = _parsePKCS12(bundleBuf, passBuf);
+
+  // Required lazily: internal/crypto/x509 depends on this module.
+  const { InternalX509Certificate } = require('internal/crypto/x509');
+
+  return {
+    key: keyHandle === null ? null : new PrivateKeyObject(keyHandle),
+    cert: certHandle === null ? null : new InternalX509Certificate(certHandle),
+    ca: ArrayPrototypeMap(caHandles, (h) => new InternalX509Certificate(h)),
+  };
+}
+
 /**
  * Converts a secret KeyObjectHandle to a CryptoKey by dispatching to the
  * algorithm-specific Web Crypto import path.
@@ -1333,6 +1386,7 @@ module.exports = {
   createSecretKey,
   createPublicKey,
   createPrivateKey,
+  parsePKCS12,
   KeyObject,
   CryptoKey,
   InternalCryptoKey,
diff --git a/node.gyp b/node.gyp
index b99755575020..3d0e0e3826bf 100644
--- a/node.gyp
+++ b/node.gyp
@@ -407,6 +407,7 @@
       'src/crypto/crypto_hash.cc',
       'src/crypto/crypto_keys.cc',
       'src/crypto/crypto_keygen.cc',
+      'src/crypto/crypto_pkcs12.cc',
       'src/crypto/crypto_scrypt.cc',
       'src/crypto/crypto_tls.cc',
       'src/crypto/crypto_x509.cc',
@@ -425,6 +426,7 @@
       'src/crypto/crypto_hash.h',
       'src/crypto/crypto_keys.h',
       'src/crypto/crypto_keygen.h',
+      'src/crypto/crypto_pkcs12.h',
       'src/crypto/crypto_scrypt.h',
       'src/crypto/crypto_tls.h',
       'src/crypto/crypto_context.h',
diff --git a/src/crypto/crypto_pkcs12.cc b/src/crypto/crypto_pkcs12.cc
new file mode 100644
index 000000000000..b149961b5589
--- /dev/null
+++ b/src/crypto/crypto_pkcs12.cc
@@ -0,0 +1,205 @@
+#include "crypto/crypto_pkcs12.h"
+#include "crypto/crypto_context.h"
+#include "crypto/crypto_keys.h"
+#include "crypto/crypto_util.h"
+#include "crypto/crypto_x509.h"
+#include "env-inl.h"
+#include "ncrypto.h"
+#include "node_errors.h"
+#include "util-inl.h"
+#include "v8.h"
+
+#include <openssl/pkcs12.h>
+
+#include <string>
+
+namespace node {
+
+using ncrypto::BIOPointer;
+using v8::Array;
+using v8::ArrayBufferView;
+using v8::FunctionCallbackInfo;
+using v8::Local;
+using v8::LocalVector;
+using v8::Object;
+using v8::Value;
+
+namespace crypto {
+
+namespace {
+
+using PKCS12Pointer = ncrypto::DeleteFnPtr<PKCS12, PKCS12_free>;
+
+// Parsed contents of a PKCS#12 bundle. Any field may be empty: a bundle can
+// legitimately contain only certificates, or only a key.
+struct PKCS12Contents {
+  ncrypto::EVPKeyPointer key;
+  ncrypto::X509Pointer cert;
+  ncrypto::StackOfX509 ca;
+};
+
+enum class PKCS12ParseError {
+  // Input is not a well-formed PKCS#12 structure.
+  NOT_RECOGNIZED,
+  // Structure is valid but uses an algorithm the active providers do not
+  // offer -- typically RC2 or PBE-SHA1 without the legacy provider.
+  UNSUPPORTED_ALGORITHM,
+  FAILED,
+};
+
+using PKCS12ParseResult = ncrypto::Result<PKCS12Contents, PKCS12ParseError>;
+
+// Parses a PKCS#12 bundle from `bio`.
+//
+// `pass` distinguishes three cases, and the distinction is load-bearing:
+//   - nullptr      -> NULL passphrase
+//   - ""           -> empty-string passphrase
+//   - non-empty    -> that passphrase
+// OpenSSL treats NULL and "" differently for both MAC verification and bag
+// decryption, so callers must not collapse them. PKCS12_parse() verifies the
+// MAC itself when one is present, and tolerates the NULL / "" ambiguity.
+PKCS12ParseResult ParseBundle(const BIOPointer& bio, const char* pass) {
+  ncrypto::ClearErrorOnReturn clear_error_on_return;
+
+  if (!bio) {
+    return PKCS12ParseResult(PKCS12ParseError::FAILED,
+                             static_cast<int>(ERR_get_error()));
+  }
+
+  PKCS12* p12_ptr = nullptr;
+  if (!d2i_PKCS12_bio(bio.get(), &p12_ptr) || p12_ptr == nullptr) {
+    return PKCS12ParseResult(PKCS12ParseError::NOT_RECOGNIZED,
+                             static_cast<int>(ERR_get_error()));
+  }
+  PKCS12Pointer p12(p12_ptr);
+
+  EVP_PKEY* pkey_ptr = nullptr;
+  X509* cert_ptr = nullptr;
+  STACK_OF(X509)* ca_ptr = nullptr;
+
+  if (!PKCS12_parse(p12.get(), pass, &pkey_ptr, &cert_ptr, &ca_ptr)) {
+    unsigned long err = ERR_get_error();  // NOLINT(runtime/int)
+#if OPENSSL_VERSION_MAJOR >= 3
+    // Same condition the TLS path checks: OpenSSL 3 reports algorithms that
+    // moved to the legacy provider as a bare "unsupported" error.
+    if (ERR_GET_REASON(err) == ERR_R_UNSUPPORTED) {
+      return PKCS12ParseResult(PKCS12ParseError::UNSUPPORTED_ALGORITHM,
+                               static_cast<int>(err));
+    }
+#endif
+    return PKCS12ParseResult(PKCS12ParseError::FAILED, static_cast<int>(err));
+  }
+
+  PKCS12Contents contents;
+  contents.key.reset(pkey_ptr);
+  contents.cert.reset(cert_ptr);
+  contents.ca.reset(ca_ptr);
+  return PKCS12ParseResult(std::move(contents));
+}
+
+// Returns [ keyHandle | null, certificate | null, [ ...caCertificates ] ].
+void ParsePKCS12(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+
+  CHECK_GE(args.Length(), 2);
+
+  BIOPointer bio(LoadBIO(env, args[0]));
+  if (!bio) {
+    return THROW_ERR_CRYPTO_OPERATION_FAILED(env,
+                                             "Unable to read PKCS#12 data");
+  }
+
+  // PKCS12_parse() takes a NUL-terminated C string. Build one explicitly so
+  // that the NULL / "" distinction survives.
+  std::string pass_storage;
+  const char* pass = nullptr;
+  if (!args[1]->IsUndefined()) {
+    THROW_AND_RETURN_IF_NOT_BUFFER(env, args[1], "passphrase");
+    Local<ArrayBufferView> abv = args[1].As<ArrayBufferView>();
+    size_t len = abv->ByteLength();
+    pass_storage.resize(len);
+    if (len > 0) abv->CopyContents(pass_storage.data(), len);
+    // An explicitly-supplied empty passphrase is NOT the same as no
+    // passphrase; both reach OpenSSL, and they behave differently.
+    pass = pass_storage.c_str();
+  }
+
+  auto parsed = ParseBundle(bio, pass);
+
+  if (!parsed) {
+    switch (*parsed.error) {
+      case PKCS12ParseError::NOT_RECOGNIZED:
+        return THROW_ERR_CRYPTO_OPERATION_FAILED(
+            env, "Input is not a valid PKCS#12 structure");
+      case PKCS12ParseError::UNSUPPORTED_ALGORITHM:
+        // Same condition PR #54485 addressed for the TLS path: OpenSSL 3
+        // moved RC2 and PBE-SHA1 into the legacy provider.
+        return THROW_ERR_CRYPTO_UNSUPPORTED_OPERATION(
+            env,
+            "PKCS#12 bundle uses an unsupported algorithm; it may require "
+            "the OpenSSL legacy provider");
+      case PKCS12ParseError::FAILED:
+        return ThrowCryptoError(env,
+                                parsed.openssl_error.value_or(0),
+                                "Unable to parse PKCS#12 data");
+    }
+  }
+
+  Local<Value> key_value = v8::Null(env->isolate());
+  if (parsed.value.key) {
+    auto data = KeyObjectData::CreateAsymmetric(KeyType::kKeyTypePrivate,
+                                                std::move(parsed.value.key));
+    Local<Object> handle;
+    if (!KeyObjectHandle::Create(env, data).ToLocal(&handle)) return;
+    key_value = handle;
+  }
+
+  Local<Value> cert_value = v8::Null(env->isolate());
+  if (parsed.value.cert) {
+    Local<Object> cert;
+    if (!X509Certificate::New(env, std::move(parsed.value.cert))
+             .ToLocal(&cert)) {
+      return;
+    }
+    cert_value = cert;
+  }
+
+  const int ca_count = parsed.value.ca ? sk_X509_num(parsed.value.ca.get()) : 0;
+  LocalVector<Value> ca_values(env->isolate());
+  ca_values.reserve(ca_count > 0 ? ca_count : 0);
+
+  for (int i = 0; i < ca_count; i++) {
+    X509* ca = sk_X509_value(parsed.value.ca.get(), i);
+    if (ca == nullptr) continue;
+    // New() takes ownership, so hand it a reference of its own rather than
+    // the stack's.
+    X509_up_ref(ca);
+    ncrypto::X509Pointer owned(ca);
+    Local<Object> obj;
+    if (!X509Certificate::New(env, std::move(owned)).ToLocal(&obj)) return;
+    ca_values.push_back(obj);
+  }
+
+  Local<Value> result[] = {
+      key_value,
+      cert_value,
+      Array::New(env->isolate(), ca_values.data(), ca_values.size()),
+  };
+
+  args.GetReturnValue().Set(
+      Array::New(env->isolate(), result, arraysize(result)));
+}
+
+}  // anonymous namespace
+
+void PKCS12Parser::Initialize(Environment* env, Local<Object> target) {
+  SetMethodNoSideEffect(env->context(), target, "parsePKCS12", ParsePKCS12);
+}
+
+void PKCS12Parser::RegisterExternalReferences(
+    ExternalReferenceRegistry* registry) {
+  registry->Register(ParsePKCS12);
+}
+
+}  // namespace crypto
+}  // namespace node
diff --git a/src/crypto/crypto_pkcs12.h b/src/crypto/crypto_pkcs12.h
new file mode 100644
index 000000000000..e715fcdae101
--- /dev/null
+++ b/src/crypto/crypto_pkcs12.h
@@ -0,0 +1,23 @@
+#ifndef SRC_CRYPTO_CRYPTO_PKCS12_H_
+#define SRC_CRYPTO_CRYPTO_PKCS12_H_
+
+#if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
+
+#include "env.h"
+#include "v8.h"
+
+namespace node {
+namespace crypto {
+
+class PKCS12Parser final {
+ public:
+  static void Initialize(Environment* env, v8::Local<v8::Object> target);
+  static void RegisterExternalReferences(ExternalReferenceRegistry* registry);
+};
+
+}  // namespace crypto
+}  // namespace node
+
+#endif  // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
+
+#endif  // SRC_CRYPTO_CRYPTO_PKCS12_H_
diff --git a/src/node_crypto.cc b/src/node_crypto.cc
index 7d52d835ca4c..7c7fce89e00d 100644
--- a/src/node_crypto.cc
+++ b/src/node_crypto.cc
@@ -51,6 +51,7 @@ namespace crypto {
   V(NativeCryptoKey)                                                           \
   V(NativeKeyObject)                                                           \
   V(PBKDF2Job)                                                                 \
+  V(PKCS12Parser)                                                              \
   V(Random)                                                                    \
   V(RSAAlg)                                                                    \
   V(SecureContext)                                                             \
diff --git a/src/node_crypto.h b/src/node_crypto.h
index 3bb95cb340d2..219157cb1039 100644
--- a/src/node_crypto.h
+++ b/src/node_crypto.h
@@ -49,6 +49,7 @@
 #include "crypto/crypto_keygen.h"
 #include "crypto/crypto_keys.h"
 #include "crypto/crypto_pbkdf2.h"
+#include "crypto/crypto_pkcs12.h"
 #include "crypto/crypto_pqc.h"
 #include "crypto/crypto_random.h"
 #include "crypto/crypto_rsa.h"
diff --git a/test/parallel/test-crypto-pkcs12.js b/test/parallel/test-crypto-pkcs12.js
new file mode 100644
index 000000000000..6fd979c870b8
--- /dev/null
+++ b/test/parallel/test-crypto-pkcs12.js
@@ -0,0 +1,131 @@
+'use strict';
+const common = require('../common');
+if (!common.hasCrypto) common.skip('missing crypto');
+
+const assert = require('assert');
+const crypto = require('crypto');
+const fixtures = require('../common/fixtures');
+const { hasOpenSSL3 } = require('../common/crypto');
+
+{
+  // Round-trip: a bundle containing one key and one leaf cert, no CA certs.
+  const bundle = fixtures.readKey('rsa_cert.pfx');
+  const { key, cert, ca } = crypto.parsePKCS12(bundle, { passphrase: 'sample' });
+
+  assert.strictEqual(key.type, 'private');
+  assert.strictEqual(key.asymmetricKeyType, 'rsa');
+  assert.ok(cert instanceof crypto.X509Certificate);
+  assert.ok(Array.isArray(ca));
+  assert.strictEqual(ca.length, 0);
+
+  // The parsed key and cert must actually correspond.
+  assert.strictEqual(cert.checkPrivateKey(key), true);
+
+  // PEM export -- the primary reason callers want this API at all.
+  const keyPem = key.export({ type: 'pkcs8', format: 'pem' });
+  assert.match(keyPem, /^-----BEGIN PRIVATE KEY-----/);
+  assert.match(cert.toString(), /^-----BEGIN CERTIFICATE-----/);
+
+  // Round-trips back through createPrivateKey.
+  const reimported = crypto.createPrivateKey(keyPem);
+  assert.strictEqual(reimported.asymmetricKeyType, 'rsa');
+
+  // Passphrase accepted as a buffer as well as a string.
+  const { key: key2 } =
+    crypto.parsePKCS12(bundle, { passphrase: Buffer.from('sample') });
+  assert.strictEqual(key2.type, 'private');
+}
+
+{
+  // A bundle with a CA certificate included.
+  const bundle = fixtures.readKey('agent1.pfx');
+  const { key, cert, ca } = crypto.parsePKCS12(bundle, { passphrase: 'sample' });
+  assert.strictEqual(key.type, 'private');
+  assert.ok(cert instanceof crypto.X509Certificate);
+  assert.strictEqual(ca.length, 1);
+  assert.ok(ca[0] instanceof crypto.X509Certificate);
+  assert.strictEqual(cert.checkPrivateKey(key), true);
+}
+
+{
+  // EC key, and an empty (but present) passphrase.
+  const bundle = fixtures.readKey('ec.pfx');
+  const { key, cert } = crypto.parsePKCS12(bundle, { passphrase: '' });
+  assert.strictEqual(key.asymmetricKeyType, 'ec');
+  assert.strictEqual(cert.checkPrivateKey(key), true);
+}
+
+{
+  // Wrong passphrase must be distinguishable from malformed input: OpenSSL
+  // reports it as a MAC verification failure of its own.
+  const bundle = fixtures.readKey('rsa_cert.pfx');
+  assert.throws(
+    () => crypto.parsePKCS12(bundle, { passphrase: 'wrong' }),
+    { code: 'ERR_OSSL_PKCS12_MAC_VERIFY_FAILURE' });
+}
+
+{
+  // A bundle whose MAC was computed over an absent passphrase opens without
+  // one, matching what tls's `pfx` option already accepts for the same file.
+  const { key } = crypto.parsePKCS12(fixtures.readKey('ec.pfx'));
+  assert.strictEqual(key.asymmetricKeyType, 'ec');
+}
+
+{
+  // Not a PKCS#12 structure at all.
+  assert.throws(
+    () => crypto.parsePKCS12(Buffer.from('not a bundle'), { passphrase: 'x' }),
+    { code: 'ERR_CRYPTO_OPERATION_FAILED', message: /not a valid PKCS#12/ });
+}
+
+{
+  // Certificate-only bundle: no key present, and that is not an error.
+  // With no private key to match a certificate against, PKCS12_parse() has no
+  // end-entity certificate to single out, so the contents arrive via `ca`.
+  const bundle = fixtures.readKey('cert-without-key.pfx');
+  const { key, cert, ca } = crypto.parsePKCS12(bundle, { passphrase: 'test' });
+  assert.strictEqual(key, null);
+  assert.strictEqual(cert, null);
+  assert.strictEqual(ca.length, 1);
+  assert.ok(ca[0] instanceof crypto.X509Certificate);
+}
+
+if (hasOpenSSL3) {
+  // Legacy algorithms (RC2-40-CBC) throw a recognizable, actionable error
+  // rather than a bare OpenSSL string. Mirrors the behavior added for the
+  // TLS path in https://github.com/nodejs/node/pull/54485.
+  const bundle = fixtures.readKey('legacy.pfx');
+  assert.throws(
+    () => crypto.parsePKCS12(bundle, { passphrase: 'legacy' }),
+    { code: 'ERR_CRYPTO_UNSUPPORTED_OPERATION' });
+}
+
+{
+  // ArrayBuffer is a documented input type for both the bundle and the
+  // passphrase, and must behave the same as a view over the same bytes.
+  const buf = fixtures.readKey('rsa_cert.pfx');
+  const bundleAb =
+    buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  const passBuf = Buffer.from('sample');
+  const passAb =
+    passBuf.buffer.slice(passBuf.byteOffset,
+                         passBuf.byteOffset + passBuf.byteLength);
+
+  const { key, cert } = crypto.parsePKCS12(bundleAb, { passphrase: passAb });
+  assert.strictEqual(key.type, 'private');
+  assert.ok(cert instanceof crypto.X509Certificate);
+  assert.strictEqual(cert.checkPrivateKey(key), true);
+
+  // DataView too.
+  const { key: key2 } = crypto.parsePKCS12(
+    new DataView(bundleAb), { passphrase: 'sample' });
+  assert.strictEqual(key2.type, 'private');
+}
+
+{
+  // Argument validation.
+  assert.throws(() => crypto.parsePKCS12('a string'),
+                { code: 'ERR_INVALID_ARG_TYPE' });
+  assert.throws(() => crypto.parsePKCS12(Buffer.alloc(0), 'nope'),
+                { code: 'ERR_INVALID_ARG_TYPE' });
+}

From 9e94a9a7baf07e49005b751da01da331c93dd599 Mon Sep 17 00:00:00 2001
From: bmuenzenmeyer <brian.muenzenmeyer@gmail.com>
Date: Sat, 29 Aug 2026 07:27:22 -0500
Subject: [PATCH 2/5] crypto: add PKCS12ParseResult type and parsePKCS12
 function

---
 typings/internalBinding/crypto.d.ts | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/typings/internalBinding/crypto.d.ts b/typings/internalBinding/crypto.d.ts
index 44cf62888e85..387ae620cb58 100644
--- a/typings/internalBinding/crypto.d.ts
+++ b/typings/internalBinding/crypto.d.ts
@@ -755,6 +755,12 @@ declare namespace InternalCryptoBinding {
     toLegacy(): object;
   }
 
+  type PKCS12ParseResult = [
+    key: KeyObjectHandle | null,
+    cert: X509CertificateHandle | null,
+    ca: X509CertificateHandle[],
+  ];
+
   interface CipherInfo {
     name: string;
     nid: number;
@@ -967,6 +973,10 @@ export interface CryptoBinding {
     functionName?: InternalCryptoBinding.OptionalBufferSource,
     customization?: InternalCryptoBinding.OptionalBufferSource,
   ): string | InternalCryptoBinding.Buffer;
+  parsePKCS12(
+    bundle: InternalCryptoBinding.ByteSource,
+    passphrase?: InternalCryptoBinding.ByteSource,
+  ): InternalCryptoBinding.PKCS12ParseResult;
   parseX509(data: InternalCryptoBinding.ByteSource): InternalCryptoBinding.X509CertificateHandle;
   privateDecrypt: InternalCryptoBinding.PublicKeyCipher;
   privateEncrypt: InternalCryptoBinding.PublicKeyCipher;

From 42bc331abf21a3db7b5aaee1eb3847f096c456c0 Mon Sep 17 00:00:00 2001
From: bmuenzenmeyer <brian.muenzenmeyer@gmail.com>
Date: Sat, 29 Aug 2026 07:34:59 -0500
Subject: [PATCH 3/5] doc: convert synxtax per review

---
 doc/api/crypto.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index bba0c2358f4b..7894ec8204cc 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -5364,8 +5364,8 @@ Parses a PKCS#12 bundle — commonly seen with the `.p12` or `.pfx` extension 
 and returns its contents.
 
 ```mjs
-import { parsePKCS12 } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+const { parsePKCS12 } = await import('node:crypto');
+const { readFileSync } = await import('node:fs');
 
 const { key, cert, ca } = parsePKCS12(
   readFileSync('bundle.p12'),

From e24d894f5b15a7050388c5889db5c6321e4c9645 Mon Sep 17 00:00:00 2001
From: bmuenzenmeyer <brian.muenzenmeyer@gmail.com>
Date: Sat, 29 Aug 2026 07:51:23 -0500
Subject: [PATCH 4/5] delete cjs example

---
 doc/api/crypto.md | 13 -------------
 1 file changed, 13 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 7894ec8204cc..9d5a8e49c4ec 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -5376,19 +5376,6 @@ console.log(cert.subject);
 console.log(key.export({ type: 'pkcs8', format: 'pem' }));
 ```
 
-```cjs
-const { parsePKCS12 } = require('node:crypto');
-const { readFileSync } = require('node:fs');
-
-const { key, cert, ca } = parsePKCS12(
-  readFileSync('bundle.p12'),
-  { passphrase: 'secret' },
-);
-
-console.log(cert.subject);
-console.log(key.export({ type: 'pkcs8', format: 'pem' }));
-```
-
 A PKCS#12 bundle may technically contain more than one private key. This API
 returns only the first, matching the behavior of OpenSSL's `PKCS12_parse()`.
 

From 44b14a4ea2b55fe89cf495f07c8fb5ec649f6a32 Mon Sep 17 00:00:00 2001
From: bmuenzenmeyer <brian.muenzenmeyer@gmail.com>
Date: Sat, 29 Aug 2026 08:10:28 -0500
Subject: [PATCH 5/5] Revert "doc: convert synxtax per review"

This reverts commit 42bc331abf21a3db7b5aaee1eb3847f096c456c0.
---
 doc/api/crypto.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 9d5a8e49c4ec..13d6de076b84 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -5364,8 +5364,8 @@ Parses a PKCS#12 bundle — commonly seen with the `.p12` or `.pfx` extension 
 and returns its contents.
 
 ```mjs
-const { parsePKCS12 } = await import('node:crypto');
-const { readFileSync } = await import('node:fs');
+import { parsePKCS12 } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 
 const { key, cert, ca } = parsePKCS12(
   readFileSync('bundle.p12'),