crypto: add crypto.parsePKCS12()

Return the private key, end-entity certificate, and any other
non-matching 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
`additionalCertificates`. A bundle containing no private key reports
`certificate` as null and returns its certificates through
`additionalCertificates`.

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>

Author: bmuenzenmeyer

doc/api/crypto.md

@@ -5516,6 +5516,64 @@ 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}
+  * `privateKey` {KeyObject|null} The private key, or `null` if the bundle
+    contains none.
+  * `certificate` {X509Certificate|null} The certificate associated with
+    `privateKey`, or `null` if the bundle contains none.
+  * `additionalCertificates` {X509Certificate\[]} Every other certificate in
+    the bundle. These are not necessarily certificate authorities; this is
+    whatever remains once `certificate` has been taken out. 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 { privateKey, certificate } = parsePKCS12(
+  readFileSync('bundle.p12'),
+  { passphrase: 'secret' },
+);
+
+console.log(certificate.subject);
+console.log(privateKey.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()`.
+
+`certificate` is identified by its association with the private key. A bundle
+containing no private key therefore reports `certificate` as `null` and returns
+all of its certificates through `additionalCertificates`, including any
+end-entity certificate the bundle holds.
+
+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
@@ -7624,11 +7682,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
@@ -7690,6 +7750,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

lib/crypto.js

@@ -84,6 +84,7 @@ const {
   createSecretKey,
   createPublicKey,
   createPrivateKey,
+  parsePKCS12,
   KeyObject,
 } = require('internal/crypto/keys');
 const {
@@ -216,6 +217,7 @@ module.exports = {
   getMacs,
   hkdf,
   hkdfSync,
+  parsePKCS12,
   pbkdf2,
   pbkdf2Sync,
   generateKeyPair,

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,
@@ -757,6 +761,58 @@ function createPublicKey(key) {
   return new PublicKeyObject(handle);
 }
 
+/**
+ * Parses a PKCS#12 (.p12 / .pfx) bundle. Returns an object holding the first
+ * private key as `privateKey`, the certificate associated with it as
+ * `certificate`, and every other certificate in the bundle as an array in
+ * `additionalCertificates`. `privateKey` and `certificate` 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: otherHandles,
+  } = _parsePKCS12(bundleBuf, passBuf);
+
+  // Required lazily: internal/crypto/x509 depends on this module.
+  const { InternalX509Certificate } = require('internal/crypto/x509');
+
+  return {
+    privateKey: keyHandle === null ? null : new PrivateKeyObject(keyHandle),
+    certificate:
+      certHandle === null ? null : new InternalX509Certificate(certHandle),
+    additionalCertificates:
+      ArrayPrototypeMap(otherHandles, (h) => new InternalX509Certificate(h)),
+  };
+}
+
 /**
  * Converts a secret KeyObjectHandle to a CryptoKey by dispatching to the
  * algorithm-specific Web Crypto import path.
@@ -1358,6 +1414,7 @@ module.exports = {
   createSecretKey,
   createPublicKey,
   createPrivateKey,
+  parsePKCS12,
   KeyObject,
   CryptoKey,
   InternalCryptoKey,

node.gyp

@@ -409,6 +409,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',
@@ -429,6 +430,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',