@noble/post-quantum 0.6.1 → 0.7.1

package/src/ml-dsa.ts

@@ -27,9 +27,9 @@ import {
   splitCoder,
   type TArg,
   type TRet,
-  validateOpts,
   validateSigOpts,
   validateVerOpts,
+  checkOptKeys,
   vecCoder,
   type VerOpts,
 } from './utils.ts';
@@ -43,9 +43,28 @@ export type DSAInternalOpts = {
    */
   externalMu?: boolean;
 };
-function validateInternalOpts(opts: TArg<DSAInternalOpts>) {
-  validateOpts(opts);
-  if (opts.externalMu !== undefined) abool(opts.externalMu, 'opts.externalMu');
+/**
+ * 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',
+] as const);
+const INTERNAL_VER_OPT_KEYS = /* @__PURE__ */ Object.freeze(['externalMu'] as const);
+
+function validateInternalOpts<T extends TArg<DSAInternalOpts>>(
+  opts: T,
+  allowed: readonly string[]
+): T {
+  const normalized = checkOptKeys(opts, allowed);
+  if (normalized.externalMu !== undefined) abool(normalized.externalMu, 'opts.externalMu');
+  return normalized;
 }
 
 /** ML-DSA signer surface with access to the internal message formatting mode. */
@@ -54,17 +73,26 @@ export type DSAInternal = CryptoKeys & {
   sign: (
     msg: TArg<Uint8Array>,
     secretKey: TArg<Uint8Array>,
-    opts?: TArg<SigOpts & DSAInternalOpts>
+    opts?: TArg<Omit<SigOpts, 'context'> & DSAInternalOpts>
   ) => TRet<Uint8Array>;
   verify: (
     sig: TArg<Uint8Array>,
     msg: TArg<Uint8Array>,
     pubKey: TArg<Uint8Array>,
-    opts?: TArg<VerOpts & DSAInternalOpts>
+    opts?: TArg<DSAInternalOpts>
   ) => boolean;
 };
 /** Public ML-DSA signer surface. */
-export type DSA = Signer & { internal: TRet<DSAInternal> };
+export type DSA = Signer & {
+  internal: TRet<DSAInternal>;
+  securityLevel: number;
+  /**
+   * HashML-DSA (FIPS 204 §5.4) variant which signs a pre-hashed message.
+   * @param hash - Approved hash, checked against the parameter set security level.
+   * @returns Signer which pre-hashes `msg` before formatting `M'`.
+   */
+  prehash: (hash: TArg<CHash>) => TRet<Signer>;
+};
 
 // Constants
 // FIPS 204 fixes ML-DSA over R = Z[X]/(X^256 + 1), so every polynomial has 256 coefficients.
@@ -154,6 +182,8 @@ const polyCoder = (d: number, compress: IdNum = id, verify: IdNum = id) =>
   });
 
 // 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_: TArg<Poly>, b_: TArg<Poly>): TRet<Poly> => {
   const a = a_ as Poly;
   const b = b_ as Poly;
@@ -201,7 +231,7 @@ function RejNTTPoly(xof_: TArg<XofGet>): TRet<Poly> {
   // Samples a polynomial ∈ Tq. xof() must return byte lengths divisible by 3.
   const r = newPoly(N);
   // NOTE: we can represent 3xu24 as 4xu32, but it doesn't improve perf :(
-  for (let j = 0; j < N; ) {
+  for (let j = 0; j < N;) {
     const b = xof();
     if (b.length % 3) throw new Error('RejNTTPoly: unaligned block');
     for (let i = 0; j < N && i <= b.length - 3; i += 3) {
@@ -275,13 +305,16 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
     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: number, r: number) => {
     // 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;
+    if (h === 1)
+      return r0 > 0 ? crystals.mod(r1 + 1, HINT_M) | 0 : crystals.mod(r1 - 1, HINT_M) | 0;
     return r1 | 0;
   };
   const Power2Round = (r: number) => {
@@ -360,7 +393,7 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
     const xof = xof_ as XofGet;
     // Samples an element a ∈ Rq with coeffcients in [−η, η] computed via rejection sampling from ρ.
     const r: Poly = newPoly(N);
-    for (let j = 0; j < N; ) {
+    for (let j = 0; j < N;) {
       const b = xof();
       for (let i = 0; j < N && i < b.length; i += 1) {
         // half byte. Should be superfast with vector instructions. But very slow with js :(
@@ -384,7 +417,7 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
     const masks = buf.slice(0, 8);
     for (let i = N - TAU, pos = 8, maskPos = 0, maskBit = 0; i < N; i++) {
       let b = i + 1;
-      for (; b > i; ) {
+      for (; b > i;) {
         b = buf[pos++];
         if (pos < shake256.blockLen) continue;
         s.xofInto(buf);
@@ -525,13 +558,34 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
       secretKey: TArg<Uint8Array>,
       opts: TArg<SigOpts & DSAInternalOpts> = {}
     ): TRet<Uint8Array> => {
-      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 as Uint8Array);
+      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: Poly[][] = []; // A ← ExpandA(ρ)
       const xof = XOF128(rho);
@@ -553,25 +607,18 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
           //    ▷ 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
-      main_loop: for (let kappa = 0; ; ) {
+      main_loop: for (let kappa = 0; ;) {
         const y = [];
         // y ← ExpandMask(ρ , κ)
         for (let i = 0; i < L; i++, kappa++)
@@ -599,7 +646,13 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
         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)) continue main_loop; // ||z||∞ ≥ γ1 − β
+          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;
@@ -607,16 +660,25 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
         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)) continue main_loop; // ||r0||∞ ≥ γ2 − β
+          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)) continue main_loop;
+          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) continue; // the number of 1’s in h is greater than ω
+        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.
@@ -636,8 +698,10 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
       publicKey: TArg<Uint8Array>,
       opts: TArg<DSAInternalOpts> = {}
     ) => {
-      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)
@@ -699,9 +763,14 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
       secretKey: TArg<Uint8Array>,
       opts: TArg<SigOpts> = {}
     ): TRet<Uint8Array> => {
-      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 as TRet<Uint8Array>;
     },
@@ -711,11 +780,13 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
       publicKey: TArg<Uint8Array>,
       opts: TArg<VerOpts> = {}
     ) => {
-      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: CHash) => {
-      checkHash(hash, securityLevel);
+    prehash: (hash: TArg<CHash>): TRet<Signer> => {
+      checkHash(hash as CHash, securityLevel);
+      const rawHash = hash as CHash;
       return Object.freeze({
         info: Object.freeze({ type: 'hashml-dsa' }),
         securityLevel: securityLevel,
@@ -727,9 +798,13 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
           secretKey: TArg<Uint8Array>,
           opts: TArg<SigOpts> = {}
         ): TRet<Uint8Array> => {
-          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 as TRet<Uint8Array>;
         },
@@ -739,15 +814,37 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
           publicKey: TArg<Uint8Array>,
           opts: TArg<VerOpts> = {}
         ) => {
-          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: TRet<DSA> = /* @__PURE__ */ (() =>
   getDilithium({
     ...PARAMS[2],