@noble/post-quantum 0.6.1 → 0.7.1

package/ml-dsa.js

@@ -11,11 +11,26 @@
 import { abool } from '@noble/curves/utils.js';
 import { shake256 } from '@noble/hashes/sha3.js';
 import { genCrystals, XOF128, XOF256 } from "./_crystals.js";
-import { abytes, checkHash, cleanBytes, equalBytes, getMessage, getMessagePrehash, randomBytes, splitCoder, validateOpts, validateSigOpts, validateVerOpts, vecCoder, } from "./utils.js";
-function validateInternalOpts(opts) {
-    validateOpts(opts);
-    if (opts.externalMu !== undefined)
-        abool(opts.externalMu, 'opts.externalMu');
+import { abytes, checkHash, cleanBytes, equalBytes, getMessage, getMessagePrehash, randomBytes, splitCoder, validateSigOpts, validateVerOpts, checkOptKeys, vecCoder, } from "./utils.js";
+/**
+ * Keys each internal surface accepts.
+ *
+ * `context` is deliberately absent from both. The internal functions never read it: the
+ * public wrappers consume it when they format `M'` and must not pass it down, because a
+ * key that is accepted and then not acted on is the same silent downgrade this validation
+ * exists to prevent. `externalMu` is the mirror case, existing here and rejected above.
+ * `extraEntropy` is signing-only, so verification does not take it either.
+ */
+const INTERNAL_SIG_OPT_KEYS = /* @__PURE__ */ Object.freeze([
+    'extraEntropy',
+    'externalMu',
+]);
+const INTERNAL_VER_OPT_KEYS = /* @__PURE__ */ Object.freeze(['externalMu']);
+function validateInternalOpts(opts, allowed) {
+    const normalized = checkOptKeys(opts, allowed);
+    if (normalized.externalMu !== undefined)
+        abool(normalized.externalMu, 'opts.externalMu');
+    return normalized;
 }
 // Constants
 // FIPS 204 fixes ML-DSA over R = Z[X]/(X^256 + 1), so every polynomial has 256 coefficients.
@@ -72,6 +87,8 @@ const polyCoder = (d, compress = id, verify = id) => crystals.bitsCoder(d, {
     decode: (i) => verify(compress(i)),
 });
 // Mutates `a` in place; callers must pass same-length polynomials.
+// NOTE: conditional-reduction variants (as in ml-kem) were measured performance-neutral here —
+// int32 `%` with 23-bit Q is already cheap — so the simpler mod() form is kept for audit.
 const polyAdd = (a_, b_) => {
     const a = a_;
     const b = b_;
@@ -179,14 +196,16 @@ function getDilithium(opts_) {
         // See dilithium-py README section "Optimising decomposition and making hints".
         return res0;
     };
+    // m = (q-1)/(2γ2): 44 for ML-DSA-44, 16 for 65/87. Hoisted out of UseHint, which runs
+    // per coefficient during verification.
+    const HINT_M = Math.floor((Q - 1) / (2 * GAMMA2));
     const UseHint = (h, r) => {
         // Returns the high bits of r adjusted according to hint h
-        const m = Math.floor((Q - 1) / (2 * GAMMA2));
         const { r1, r0 } = decompose(r);
         // 3: if h = 1 and r0 > 0 return (r1 + 1) mod m
         // 4: if h = 1 and r0 ≤ 0 return (r1 − 1) mod m
         if (h === 1)
-            return r0 > 0 ? crystals.mod(r1 + 1, m) | 0 : crystals.mod(r1 - 1, m) | 0;
+            return r0 > 0 ? crystals.mod(r1 + 1, HINT_M) | 0 : crystals.mod(r1 - 1, HINT_M) | 0;
         return r1 | 0;
     };
     const Power2Round = (r) => {
@@ -419,13 +438,36 @@ function getDilithium(opts_) {
         },
         // NOTE: random is optional.
         sign: (msg, secretKey, opts = {}) => {
-            validateSigOpts(opts);
-            validateInternalOpts(opts);
-            let { extraEntropy: random, externalMu = false } = opts;
+            opts = validateSigOpts(opts, INTERNAL_SIG_OPT_KEYS);
+            opts = validateInternalOpts(opts, INTERNAL_SIG_OPT_KEYS);
+            const { extraEntropy: random, externalMu = false } = opts;
+            // FIPS 204 external-mu mode expects the 64-byte message representative µ = H(tr || M).
+            if (externalMu)
+                abytes(msg, CRH_BYTES, 'mu');
+            // Prepare entropy before touching decoded secrets: randomBytes() may throw, and an RNG
+            // failure must not leave expanded secret-polynomial copies behind.
+            const ownRnd = random === false || random === undefined;
+            const rnd = random === false
+                ? new Uint8Array(32)
+                : random === undefined
+                    ? randomBytes(signRandBytes)
+                    : random;
+            abytes(rnd, 32, 'extraEntropy');
             // This part can be pre-cached per secretKey, but there is only minor performance improvement,
             // since we re-use a lot of variables to computation.
             // (ρ, K,tr, s1, s2, t0) ← skDecode(sk)
-            const [rho, _K, tr, s1, s2, t0] = secretCoder.decode(secretKey);
+            const decoded = (() => {
+                try {
+                    return secretCoder.decode(secretKey);
+                }
+                catch (error) {
+                    // A malformed key must not strand entropy owned by the library.
+                    if (ownRnd)
+                        cleanBytes(rnd);
+                    throw error;
+                }
+            })();
+            const [rho, _K, tr, s1, s2, t0] = decoded;
             // Cache matrix to avoid re-compute later
             const A = []; // A ← ExpandA(ρ)
             const xof = XOF128(rho);
@@ -448,19 +490,15 @@ function getDilithium(opts_) {
                 : // 6: µ ← H(tr||M, 512)
                     //    ▷ Compute message representative µ
                     shake256.create({ dkLen: CRH_BYTES }).update(tr).update(msg).digest();
-            // Compute private random seed
-            const rnd = random === false
-                ? new Uint8Array(32)
-                : random === undefined
-                    ? randomBytes(signRandBytes)
-                    : random;
-            abytes(rnd, 32, 'extraEntropy');
             const rhoprime = shake256
                 .create({ dkLen: CRH_BYTES })
                 .update(_K)
                 .update(rnd)
                 .update(mu)
                 .digest(); // ρ′← H(K||rnd||µ, 512)
+            // Only wipe entropy we generated; caller-provided extraEntropy stays caller-owned.
+            if (ownRnd)
+                cleanBytes(rnd);
             abytes(rhoprime, CRH_BYTES);
             const x256 = XOF256(rhoprime, ZCoder.bytesLen);
             //  Rejection sampling loop
@@ -493,8 +531,13 @@ function getDilithium(opts_) {
                 const cs1 = s1.map((i) => MultiplyNTTs(i, cHat));
                 for (let i = 0; i < L; i++) {
                     polyAdd(crystals.NTT.decode(cs1[i]), y[i]); // z ← y + ⟨⟨cs1⟩⟩
-                    if (polyChknorm(cs1[i], GAMMA1 - BETA))
+                    if (polyChknorm(cs1[i], GAMMA1 - BETA)) {
+                        // Rejected. Wipe this iteration's secret-derived buffers before retrying; the
+                        // accepted path wipes the same set, and only the persistent key material (s1, s2,
+                        // t0, A, rhoprime) is kept for the next iteration and cleaned at the very end.
+                        cleanBytes(cTilde, cs1, cHat, w1, w, z, y);
                         continue main_loop; // ||z||∞ ≥ γ1 − β
+                    }
                 }
                 // cs1 is now z (▷ Signer’s response)
                 let cnt = 0;
@@ -502,19 +545,25 @@ function getDilithium(opts_) {
                 for (let i = 0; i < K; i++) {
                     const cs2 = crystals.NTT.decode(MultiplyNTTs(s2[i], cHat)); // ⟨⟨cs2⟩⟩ ← NTT−1(cˆ◦ sˆ2)
                     const r0 = polySub(w[i], cs2).map(LowBits); // r0 ← LowBits(w − ⟨⟨cs2⟩⟩)
-                    if (polyChknorm(r0, GAMMA2 - BETA))
+                    if (polyChknorm(r0, GAMMA2 - BETA)) {
+                        cleanBytes(cTilde, cs1, cHat, w1, w, z, y, h, cs2, r0);
                         continue main_loop; // ||r0||∞ ≥ γ2 − β
+                    }
                     const ct0 = crystals.NTT.decode(MultiplyNTTs(t0[i], cHat)); // ⟨⟨ct0⟩⟩ ← NTT−1(cˆ◦ tˆ0)
-                    if (polyChknorm(ct0, GAMMA2))
+                    if (polyChknorm(ct0, GAMMA2)) {
+                        cleanBytes(cTilde, cs1, cHat, w1, w, z, y, h, cs2, r0, ct0);
                         continue main_loop;
+                    }
                     polyAdd(r0, ct0);
                     // ▷ Signer’s hint
                     const hint = polyMakeHint(r0, w1[i]); // h ← MakeHint(−⟨⟨ct0⟩⟩, w− ⟨⟨cs2⟩⟩ + ⟨⟨ct0⟩⟩)
                     h.push(hint.v);
                     cnt += hint.cnt;
                 }
-                if (cnt > OMEGA)
+                if (cnt > OMEGA) {
+                    cleanBytes(cTilde, cs1, cHat, w1, w, z, y, h);
                     continue; // the number of 1’s in h is greater than ω
+                }
                 x256.clean();
                 const res = sigCoder.encode([cTilde, cs1, h]); // σ ← sigEncode(c˜, z mod±q, h)
                 // rho, _K, tr is subarray of secretKey, cannot clean.
@@ -530,8 +579,11 @@ function getDilithium(opts_) {
             throw new Error('Unreachable code path reached, report this error');
         },
         verify: (sig, msg, publicKey, opts = {}) => {
-            validateInternalOpts(opts);
+            opts = validateInternalOpts(opts, INTERNAL_VER_OPT_KEYS);
             const { externalMu = false } = opts;
+            // FIPS 204 external-mu mode expects the 64-byte message representative µ = H(tr || M).
+            if (externalMu)
+                abytes(msg, CRH_BYTES, 'mu');
             // ML-DSA.Verify(pk, M, σ): Verifes a signature σ for a message M.
             const [rho, t1] = publicCoder.decode(publicKey); // (ρ, t1) ← pkDecode(pk)
             const tr = shake256(publicKey, { dkLen: TR_BYTES }); // 6: tr ← H(BytesToBits(pk), 512)
@@ -596,18 +648,25 @@ function getDilithium(opts_) {
         lengths: internal.lengths,
         getPublicKey: internal.getPublicKey,
         sign: (msg, secretKey, opts = {}) => {
-            validateSigOpts(opts);
+            opts = validateSigOpts(opts);
             const M = getMessage(msg, opts.context);
-            const res = internal.sign(M, secretKey, opts);
+            // `context` is consumed by getMessage() above; forwarding it would make the internal
+            // surface accept a key it never reads.
+            const res = internal.sign(M, secretKey, {
+                extraEntropy: opts.extraEntropy,
+                externalMu: false,
+            });
             cleanBytes(M);
             return res;
         },
         verify: (sig, msg, publicKey, opts = {}) => {
-            validateVerOpts(opts);
-            return internal.verify(sig, getMessage(msg, opts.context), publicKey);
+            opts = validateVerOpts(opts);
+            abytes(sig, undefined, 'signature');
+            return internal.verify(sig, getMessage(msg, opts.context), publicKey, { externalMu: false });
         },
         prehash: (hash) => {
             checkHash(hash, securityLevel);
+            const rawHash = hash;
             return Object.freeze({
                 info: Object.freeze({ type: 'hashml-dsa' }),
                 securityLevel: securityLevel,
@@ -615,21 +674,47 @@ function getDilithium(opts_) {
                 keygen: internal.keygen,
                 getPublicKey: internal.getPublicKey,
                 sign: (msg, secretKey, opts = {}) => {
-                    validateSigOpts(opts);
-                    const M = getMessagePrehash(hash, msg, opts.context);
-                    const res = internal.sign(M, secretKey, opts);
+                    opts = validateSigOpts(opts);
+                    const M = getMessagePrehash(rawHash, msg, opts.context);
+                    // As above: getMessagePrehash() consumes `context`, so it must not travel further.
+                    const res = internal.sign(M, secretKey, {
+                        extraEntropy: opts.extraEntropy,
+                        externalMu: false,
+                    });
                     cleanBytes(M);
                     return res;
                 },
                 verify: (sig, msg, publicKey, opts = {}) => {
-                    validateVerOpts(opts);
-                    return internal.verify(sig, getMessagePrehash(hash, msg, opts.context), publicKey);
+                    opts = validateVerOpts(opts);
+                    abytes(sig, undefined, 'signature');
+                    return internal.verify(sig, getMessagePrehash(rawHash, msg, opts.context), publicKey, {
+                        externalMu: false,
+                    });
                 },
             });
         },
     });
 }
-/** ML-DSA-44 for 128-bit security level. Not recommended after 2030, as per ASD. */
+/**
+ * ML-DSA-44 for 128-bit security level. Not recommended after 2030, as per ASD.
+ * @example
+ * Generate deterministic ML-DSA-44 keys, sign one message, and verify the signature.
+ * ```ts
+ * import { sha256 } from '@noble/hashes/sha2.js';
+ * import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js';
+ * const seed = new Uint8Array(ml_dsa44.lengths.seed!);
+ * const { secretKey, publicKey } = ml_dsa44.keygen(seed);
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = ml_dsa44.sign(msg, secretKey);
+ * const isValid = ml_dsa44.verify(sig, msg, publicKey);
+ * const recovered = ml_dsa44.getPublicKey(secretKey);
+ * const context = new Uint8Array([1, 2, 3]);
+ * const prehash = ml_dsa44.prehash(sha256);
+ * const preSig = prehash.sign(msg, secretKey, { context });
+ * const preValid = prehash.verify(preSig, msg, publicKey, { context });
+ * const internalSig = ml_dsa44.internal.sign(msg, secretKey);
+ * ```
+ */
 export const ml_dsa44 = /* @__PURE__ */ (() => getDilithium({
     ...PARAMS[2],
     CRH_BYTES: 64,
@@ -659,4 +744,3 @@ export const ml_dsa87 = /* @__PURE__ */ (() => getDilithium({
     XOF256,
     securityLevel: 256,
 }))();
-//# sourceMappingURL=ml-dsa.js.map

package/ml-kem.d.ts

@@ -26,20 +26,61 @@ export type KEMParam = {
  * not a generic security label.
  */
 export declare const PARAMS: Record<string, KEMParam>;
+/**
+ * Prepared (pre-expanded) ML-KEM public key. Experimental prototype.
+ * Caches only public data: packed ek, the expanded matrix Â, decoded t̂ and H(ek). No secret
+ * material is retained between calls; secret keys passed to `decapsulate` are decoded and wiped
+ * per call, exactly like the one-shot API. `clean()` wipes the expanded Â/t̂ cache; the packed
+ * public key and H(ek) are public and are not wiped. The object must not be used afterwards.
+ */
+export type KEMPrepared = {
+    /**
+     * Detached copy of the source public key. Treat as read-only while the prepared object is in use.
+     * Callers may wipe it after final use; any mutation invalidates subsequent operations.
+     */
+    publicKey: Uint8Array;
+    /** Same as `KEM.encapsulate`, minus per-call ek re-validation and  re-expansion. */
+    encapsulate: (msg?: Uint8Array) => {
+        cipherText: Uint8Array;
+        sharedSecret: Uint8Array;
+    };
+    /**
+     * Same as `KEM.decapsulate`; throws if `secretKey` does not embed this public key.
+     * The embedded-ek byte comparison plus stored-hash comparison is equivalent to the
+     * FIPS 203 §7.3 hash input check.
+     */
+    decapsulate: (cipherText: Uint8Array, secretKey: Uint8Array) => Uint8Array;
+    /** Wipe cached (public) data. */
+    clean: () => void;
+};
+/** KEM with prepared-key support. */
+export type MLKEM = KEM & {
+    prepare: (publicKey: Uint8Array) => KEMPrepared;
+};
 /**
  * ML-KEM-512: Table 2 row `k=2, η1=3, η2=2, du=10, dv=4`; Table 3 sizes `800/1632/768/32`.
  * The ASD lifecycle note here is external policy guidance, not a FIPS 203 requirement.
+ * @example
+ * Generate deterministic ML-KEM-512 keys, encapsulate a shared secret, and decapsulate it.
+ * ```ts
+ * import { ml_kem512 } from '@noble/post-quantum/ml-kem.js';
+ * const seed = new Uint8Array(ml_kem512.lengths.seed!);
+ * const { secretKey, publicKey } = ml_kem512.keygen(seed);
+ * const msg = new Uint8Array(ml_kem512.lengths.msgRand!);
+ * const { cipherText, sharedSecret } = ml_kem512.encapsulate(publicKey, msg);
+ * const recovered = ml_kem512.decapsulate(cipherText, secretKey);
+ * const publicKey2 = ml_kem512.getPublicKey(secretKey);
+ * ```
  */
-export declare const ml_kem512: TRet<KEM>;
+export declare const ml_kem512: TRet<MLKEM>;
 /**
  * ML-KEM-768: Table 2 row `k=3, η1=2, η2=2, du=10, dv=4`; Table 3 sizes `1184/2400/1088/32`.
  * The ASD lifecycle note here is external policy guidance, not a FIPS 203 requirement.
  */
-export declare const ml_kem768: TRet<KEM>;
+export declare const ml_kem768: TRet<MLKEM>;
 /**
  * ML-KEM-1024: Table 2 row `k=4, η1=2, η2=2, du=11, dv=5`; Table 3 sizes `1568/3168/1568/32`.
  * The ASD lifecycle note here is external policy guidance, not a FIPS 203 requirement.
  */
-export declare const ml_kem1024: TRet<KEM>;
+export declare const ml_kem1024: TRet<MLKEM>;
 export declare const __tests: any;
-//# sourceMappingURL=ml-kem.d.ts.map