@blamejs/pki 0.6.14 → 0.6.16

package/lib/pbes2.js

@@ -1,14 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- the RFC 8018 PBES2 / PBKDF2 primitives, the single home shared by pki.cms EncryptedData / PWRI
-// password encryption and pki.key EncryptedPrivateKeyInfo (RFC 5958). Error-factory-parameterized like the
-// guard family: every reject goes through the caller's `E(code, msg, cause)` full-code factory plus a domain
-// `prefix`, so pki.cms keeps cms/* codes and pki.key keeps key/* codes off one implementation. Extracted
-// behavior-preservingly from cms-encrypt.js and cms-decrypt.js; the shipped CMS PBES2 tests are the guard.
-// A shape here that cannot route through a guard stays with its caller; the reusable PBES2 shape lives here
-// so a fourth copy (the drift a reviewer flags) cannot re-accrete.
+// @internal
 
 var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der");
@@ -20,15 +13,9 @@ var C = require("./constants");
 var b = asn1.build;
 function O(n) { return oid.byName(n); }
 
-// PBKDF2 prf tables: the OID name -> node digest (encrypt names the prf) and the OID -> node digest (decrypt
-// reads the OID). One source, both directions.
 var PRF_NODE_BY_NAME = { hmacWithSHA1: "sha1", hmacWithSHA256: "sha256", hmacWithSHA384: "sha384", hmacWithSHA512: "sha512" };
 var PRF_NODE_BY_OID = {}; Object.keys(PRF_NODE_BY_NAME).forEach(function (n) { PRF_NODE_BY_OID[O(n)] = PRF_NODE_BY_NAME[n]; });
 
-// content-encryption OID -> AES key bits (CBC + GCM). The PBES2 encryptionScheme + CMS content cipher table.
-// CONTENT_MODE rides the same rows so a cipher can never be present for its key length but absent for its
-// mode: key length alone does not distinguish an AEAD cipher from a plain one, and a consumer that resolves
-// only the length would open content in the wrong mode whenever the two happen to share a key size.
 var CONTENT_KEYBITS = {}, CONTENT_MODE = {};
 [["aes128-CBC", 128, "cbc"], ["aes192-CBC", 192, "cbc"], ["aes256-CBC", 256, "cbc"],
   ["aes128-GCM", 128, "gcm"], ["aes192-GCM", 192, "gcm"], ["aes256-GCM", 256, "gcm"]].forEach(function (r) {
@@ -36,15 +23,8 @@ var CONTENT_KEYBITS = {}, CONTENT_MODE = {};
   CONTENT_MODE[O(r[0])] = r[2];
 });
 
-// A password is an octet string (RFC 8018 sec. 2): a string is UTF-8-encoded deterministically (correct for
-// non-ASCII, and byte-identical to OpenSSL), a Buffer/Uint8Array used verbatim.
 function passwordBytes(p, E, prefix) { return passwordBytesOwned(p, E, prefix).bytes; }
 
-// The same conversion, reporting OWNERSHIP. A string or Uint8Array password is encoded into a fresh
-// Buffer this toolkit allocated -- a credential copy that must be cleared once the derivation has
-// consumed it -- while a caller-supplied Buffer is BORROWED and must be left intact. Without this
-// distinction a call site can only be safe by leaving every password encoding readable, which is
-// the common case, since a password arrives as a string far more often than as a Buffer.
 function passwordBytesOwned(p, E, prefix) {
   if (Buffer.isBuffer(p)) return { bytes: p, owned: false };
   if (p instanceof Uint8Array) return { bytes: Buffer.from(p), owned: true };
@@ -52,15 +32,12 @@ function passwordBytesOwned(p, E, prefix) {
   throw E(prefix + "/bad-input", "a password must be a string, Buffer, or Uint8Array");
 }
 
-// iterationCount for a PRODUCED PBES2/PWRI structure: a positive integer at or below the cap the decryptor
-// enforces, so a structure we emit is always one we can read back (config-time throw on a bad value).
 function assertIterations(n, E, prefix) {
   if (typeof n !== "number" || !isFinite(n) || n < 1 || Math.floor(n) !== n) throw E(prefix + "/bad-input", "iterations must be a positive integer");
   if (n > C.LIMITS.PBKDF2_MAX_ITERATIONS) throw E(prefix + "/bad-input", "iterations exceeds the " + C.LIMITS.PBKDF2_MAX_ITERATIONS + " cap");
   return n;
 }
 
-// Bound a PRODUCED salt to the same cap the decryptor enforces.
 function assertSalt(salt, E, prefix) {
   guard.limits.byteCap(salt, C.LIMITS.PBKDF2_MAX_SALT, E, prefix + "/bad-input", "salt");
   return salt;
@@ -69,28 +46,18 @@ function assertSalt(salt, E, prefix) {
 function prfNodeByName(prf, E, prefix) { if (!PRF_NODE_BY_NAME[prf]) throw E(prefix + "/bad-input", "unsupported prf " + JSON.stringify(prf)); return PRF_NODE_BY_NAME[prf]; }
 function prfNodeByOid(oidStr, E, prefix) { if (!PRF_NODE_BY_OID[oidStr]) throw E(prefix + "/unsupported-algorithm", "unsupported PBKDF2 prf " + oidStr); return PRF_NODE_BY_OID[oidStr]; }
 
-// PBKDF2-params { salt OCTET STRING, iterationCount INTEGER, prf DEFAULT hmacWithSHA1 }. prf equal to the
-// DEFAULT (hmacWithSHA1) MUST be omitted on encode (X.690 sec. 11.5 / RFC 8018 App. A.2); every other prf is
-// an hmacWithSHA_n AlgorithmIdentifier carrying NULL parameters.
 function pbkdf2ParamsSeq(salt, iterations, prf) {
   var kids = [b.octetString(salt), b.integer(BigInt(iterations))];
   if (prf !== "hmacWithSHA1") kids.push(b.sequence([b.oid(O(prf)), b.nullValue()]));
   return b.sequence(kids);
 }
 
-// The PBES2 AlgorithmIdentifier: SEQUENCE { id-PBES2, SEQUENCE { keyDerivationFunc PBKDF2, encryptionScheme } }.
-// The single home for the CMS EncryptedData contentEncryptionAlgorithm and the RFC 5958 EncryptedPrivateKeyInfo
-// encryptionAlgorithm: both wrap the same PBES2 structure around a PBKDF2 KDF plus an AES-CBC scheme whose
-// IV rides in the encryptionScheme parameter. `cipherName` is a registry NAME (an AES-CBC OID name).
 function pbes2AlgId(salt, iterations, prf, cipherName, iv) {
   var kdf = b.sequence([b.oid(O("pbkdf2")), pbkdf2ParamsSeq(salt, iterations, prf)]);
   var encScheme = b.sequence([b.oid(O(cipherName)), b.octetString(iv)]);
   return b.sequence([b.oid(O("pbes2")), b.sequence([kdf, encScheme])]);
 }
 
-// SEQUENCE structural guards -- a malformed (primitive / too-short) attacker-controlled parameter SEQUENCE is
-// a typed E(prefix + "/bad-input"), never a raw `.children` dereference fault (a PBES2 structure is public,
-// not a decrypt oracle).
 function requireChildren(node, minLen, what, E, prefix) {
   if (!node || !node.children || node.children.length < minLen) throw E(prefix + "/bad-input", "malformed " + what);
   return node.children;
@@ -100,9 +67,6 @@ function seqChildren(paramsDer, minLen, what, E, prefix) {
   return requireChildren(asn1.decode(paramsDer), minLen, what, E, prefix);
 }
 
-// Strict PBKDF2-params decode: salt (capped before derivation), iterationCount (positiveInt31 + cap, downward-
-// overridable via a validated-positive-int opts.maxIterations so Math.min(NaN, cap) cannot silently disable
-// the DoS cap), prf. Returns { salt, iterations, prfNode }.
 function parsePbkdf2Params(paramsDer, opts, E, prefix, strictPrf) {
   var node = Buffer.isBuffer(paramsDer) ? asn1.decode(paramsDer) : paramsDer;
   var kids = requireChildren(node, 2, "PBKDF2 parameters", E, prefix);
@@ -120,8 +84,6 @@ function parsePbkdf2Params(paramsDer, opts, E, prefix, strictPrf) {
     var ch = node.children[i];
     if (ch.tagClass === "universal" && ch.tagNumber === asn1.TAGS.SEQUENCE) {
       var prfOid = asn1.read.oid(ch.children[0]);
-      // X.690 sec. 11.5 / RFC 8018 App. A.2: a prf equal to the DEFAULT (hmacWithSHA1 with NULL parameters)
-      // MUST be omitted -- an explicit encoding of it is non-canonical. A strictPrf caller rejects it.
       if (strictPrf && prfOid === O("hmacWithSHA1") && ch.children.length > 1 && ch.children[1].tagClass === "universal" && ch.children[1].tagNumber === asn1.TAGS.NULL) {
         throw E(prefix + "/bad-input", "a PBKDF2 prf equal to the default hmacWithSHA1 must be omitted (X.690 sec. 11.5)");
       }
@@ -131,28 +93,15 @@ function parsePbkdf2Params(paramsDer, opts, E, prefix, strictPrf) {
   return { salt: salt, iterations: iterations, prfNode: prfNode };
 }
 
-// AES-CBC content encryption / decryption (PKCS#7 pad). decrypt's final() throws on bad pad, and the caller
-// collapses that into its uniform decrypt-failed verdict.
-// cbcEncrypt(key, iv, plaintext, keyBits, E, code) -> the ciphertext.
-// Takes the caller's typed error for the same reason cbcDecrypt does: the cipher runs through the
-// shared guard, whose one throw has to keep the calling domain's own code.
 function cbcEncrypt(key, iv, plaintext, keyBits, E, code) {
   var c = nodeCrypto.createCipheriv("aes-" + keyBits + "-cbc", key, iv);
   return guard.secret.cipherFinish(c, plaintext, E, code, "a content-encryption intermediate");
 }
-// cbcDecrypt(key, iv, ct, keyBits, E, code) -> the recovered plaintext.
-// Takes the caller's typed error the way rc2.cbcDecrypt does, so a refusal keeps its own domain.
 function cbcDecrypt(key, iv, ct, keyBits, E, code) {
   var d = nodeCrypto.createDecipheriv("aes-" + keyBits + "-cbc", key, iv);
-  // A wrong key fails inside final(), on the padding check, and update() has by then produced every
-  // block but the last. Through the guard so that partial plaintext is cleared on both exits rather
-  // than abandoned readable on exactly the path an attacker induces.
   return guard.secret.cipherFinish(d, ct, E, code, "the partially recovered plaintext");
 }
 
-// Higher-level PBES2 AES-CBC encrypt: derive an AES key from PRE-FORMATTED password bytes (the caller owns
-// the encoding -- CMS UTF-8 vs PKCS#12 App. B.1) and encrypt the plaintext, returning the PBES2
-// AlgorithmIdentifier + ciphertext. `cipherName` is an AES-CBC registry name (aes128/192/256-CBC).
 function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
   opts = opts || {};
   var cipherName = opts.cipher || "aes256-CBC";
@@ -163,33 +112,14 @@ function pbes2Encrypt(pwBytes, plaintext, opts, E, prefix) {
   var iterations = assertIterations(opts.iterations == null ? 2048 : opts.iterations, E, prefix);
   var salt = opts.salt != null ? assertSalt(opts.salt, E, prefix) : nodeCrypto.randomBytes(16);
   var iv = opts.iv != null ? opts.iv : nodeCrypto.randomBytes(16);
-  // The derived key is this module's allocation and protects the caller's plaintext (a private key
-  // in the pkcs8 and pkcs12 callers), so it is cleared once the encryption has consumed it. pwBytes
-  // is not cleared: the caller formatted it and may still own the buffer.
   var key = nodeCrypto.pbkdf2Sync(pwBytes, salt, iterations, keyBits / 8, prfNode);
   try {
     return { algId: pbes2AlgId(salt, iterations, prf, cipherName, iv), ct: cbcEncrypt(key, iv, plaintext, keyBits, E, prefix + "/bad-input") };
   } finally {
-    // E is the caller's error FACTORY, not a class; guard-secret delegates its only throw to
-    // guard-bytes, which constructs. `new` on a factory yields the object the factory returns, so
-    // the currency is compatible -- and the throw is unreachable here regardless, because a freshly
-    // allocated pbkdf2 buffer cannot be detached.
     guard.secret.zeroize(key, E, prefix + "/bad-input", "the password-derived encryption key");
   }
 }
 
-// PBES2 AES-CBC DECRYPT: parse the PBES2 params (PBKDF2 kdf + AES-CBC scheme), derive the key from
-// PRE-FORMATTED password bytes (the caller owns UTF-8 vs BMPString), and AES-CBC-decrypt. Structural faults
-// (a non-PBKDF2 KDF, a non-AES-CBC scheme, an over-cap salt/iteration, a wrong-length IV, a malformed param
-// SEQUENCE) are typed pre-derivation and password-independent, so they leak no oracle; the generic
-// <prefix>/bad-input a param guard raises is normalized to the structural <prefix>/bad-algorithm-parameters.
-// A wrong key / bad PKCS#7 pad collapses to the UNIFORM <prefix>/decrypt-failed (RFC 8018 sec. 8). The
-// plaintext integrity re-check (re-parse as a PrivateKeyInfo / SafeContents) is the CALLER's step.
-// `budget` (optional) is a shared { rounds } tally a caller decrypting MANY structures under one
-// call charges against, so the per-structure iteration cap cannot simply reset each time: PBKDF2
-// runs on the event loop, and a store that repeats a costly bag up to the parser's element limit
-// otherwise multiplies the cap by that limit. A caller decrypting exactly one structure passes
-// nothing and is bounded by the cap alone.
 function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
   var keyBits, iv, pb;
   try {
@@ -197,7 +127,7 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
     var kdf = requireChildren(p[0], 2, "PBES2 keyDerivationFunc", E, prefix);
     var encScheme = requireChildren(p[1], 2, "PBES2 encryptionScheme", E, prefix);
     if (asn1.read.oid(kdf[0]) !== O("pbkdf2")) throw E(prefix + "/unsupported-algorithm", "the PBES2 keyDerivationFunc must be PBKDF2 (RFC 8018 sec. 6.2)");
-    pb = parsePbkdf2Params(kdf[1].bytes, opts, E, prefix, true);   // strictPrf: reject a non-canonical explicit default prf
+    pb = parsePbkdf2Params(kdf[1].bytes, opts, E, prefix, true);
     var encOid = asn1.read.oid(encScheme[0]);
     keyBits = CONTENT_KEYBITS[encOid];
     if (!keyBits || (oid.name(encOid) || "").indexOf("CBC") === -1) throw E(prefix + "/unsupported-algorithm", "unsupported PBES2 encryptionScheme " + (oid.name(encOid) || encOid) + " (AES-CBC only)");
@@ -210,7 +140,6 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
     }
     throw E(prefix + "/bad-algorithm-parameters", "malformed PBES2 parameters", e);
   }
-  // Charge the shared budget before deriving, so the work is refused instead of performed.
   if (budget) {
     budget.rounds -= pb.iterations;
     if (budget.rounds < 0) throw E(prefix + "/iteration-limit", "the aggregate PBKDF2 key-derivation work exceeds the budget (a hostile many-element input)");
@@ -221,13 +150,8 @@ function pbes2Decrypt(pwBytes, params, ciphertext, opts, E, prefix, budget) {
   finally { guard.secret.zeroize(dk, E, prefix + "/bad-input", "the password-derived decryption key"); }
 }
 
-// ---- PBMAC1 (RFC 9579 / RFC 8018 App. A.5) : PBKDF2 -> HMAC over a message --
-// An hmacWithSHA_n AlgorithmIdentifier carries NULL parameters (RFC 8018 B.1.1).
 function _hmacAlgId(name) { return b.sequence([b.oid(O(name)), b.nullValue()]); }
 
-// The id-PBMAC1 AlgorithmIdentifier: id-PBMAC1 + PBMAC1-params { keyDerivationFunc PBKDF2, messageAuthScheme
-// HMAC }, the byte-exact inverse of schema-pkcs12 / schema-cmp's PBMAC1_PARAMS. `desc` = { salt,
-// iterationCount, keyLength, prfName, macName }. The prf is omitted iff it equals the default hmacWithSHA1.
 function pbmac1AlgId(desc) {
   var pbkdf2Params = [b.octetString(desc.salt), b.integer(BigInt(desc.iterationCount)), b.integer(BigInt(desc.keyLength))];
   if (desc.prfName !== "hmacWithSHA1") pbkdf2Params.push(_hmacAlgId(desc.prfName));
@@ -235,26 +159,15 @@ function pbmac1AlgId(desc) {
   return b.sequence([b.oid(O("pbmac1")), b.sequence([pbkdf2AlgId, _hmacAlgId(desc.macName)])]);
 }
 
-// Compute PBMAC1 = HMAC_macHash(PBKDF2(pwBytes, salt, iter, keyLength, prfHash), message). The PBKDF2 prf
-// and the HMAC messageAuthScheme are INDEPENDENT (RFC 9579 sec. 4 / RFC 8018 App. A.5) -- e.g. a SHA-512 PRF
-// with a SHA-256 HMAC -- so both are passed explicitly. `prfHash` / `macHash` are WebCrypto hash names
-// ("SHA-256"); pwBytes is pre-formatted (the caller owns the encoding).
 function pbmac1(pwBytes, salt, iterationCount, keyLength, prfHash, macHash, message) {
   var subtle = webcrypto.webcrypto.subtle;
   return subtle.importKey("raw", pwBytes, { name: "PBKDF2" }, false, ["deriveBits"]).then(function (baseKey) {
     return subtle.deriveBits({ name: "PBKDF2", salt: salt, iterations: iterationCount, hash: prfHash }, baseKey, keyLength * 8);
   }).then(function (bits) {
-    // The derived MAC key is this function's allocation, in two forms: the ArrayBuffer deriveBits
-    // returned and the Buffer view over it that is imported. Clearing the view clears both, and it
-    // runs whether the signing succeeds or throws. The sibling PBES2 encrypt/decrypt above clear
-    // their derived keys, and every PBMAC1 consumer (PKCS#12 build and verification) inherits this.
     var mk = Buffer.from(bits);
     return subtle.importKey("raw", mk, { name: "HMAC", hash: macHash }, false, ["sign"]).then(function (hmacKey) {
       return subtle.sign({ name: "HMAC" }, hmacKey, message);
     }).finally(function () {
-      // pbmac1 takes no caller error factory, and this key is engine-adjacent, so the engine's
-      // typed class is the right currency -- a raw TypeError must never escape a lib boundary.
-      // Unreachable in practice: a freshly allocated Buffer cannot be detached.
       guard.secret.zeroize(mk, webcrypto.WebCryptoError, "webcrypto/operation", "the PBMAC1 key");
     });
   }).then(function (sig) { return Buffer.from(sig); });