@noble/post-quantum 0.6.0 → 0.7.0

package/ml-dsa.js

@@ -40,10 +40,16 @@ const GAMMA2_2 = Math.floor((Q - 1) / 32) | 0;
  * This is only the Table 1 subset used directly here: `BETA = TAU * ETA` is derived later,
  * while `C_TILDE_BYTES`, `TR_BYTES`, `CRH_BYTES`, and `securityLevel` live in the preset wrappers.
  */
-export const PARAMS = /* @__PURE__ */ (() => ({
-    2: { K: 4, L: 4, D, GAMMA1: 2 ** 17, GAMMA2: GAMMA2_1, TAU: 39, ETA: 2, OMEGA: 80 },
-    3: { K: 6, L: 5, D, GAMMA1: 2 ** 19, GAMMA2: GAMMA2_2, TAU: 49, ETA: 4, OMEGA: 55 },
-    5: { K: 8, L: 7, D, GAMMA1: 2 ** 19, GAMMA2: GAMMA2_2, TAU: 60, ETA: 2, OMEGA: 75 },
+export const PARAMS = /* @__PURE__ */ (() => Object.freeze({
+    2: Object.freeze({
+        K: 4, L: 4, D, GAMMA1: 2 ** 17, GAMMA2: GAMMA2_1, TAU: 39, ETA: 2, OMEGA: 80
+    }),
+    3: Object.freeze({
+        K: 6, L: 5, D, GAMMA1: 2 ** 19, GAMMA2: GAMMA2_2, TAU: 49, ETA: 4, OMEGA: 55
+    }),
+    5: Object.freeze({
+        K: 8, L: 7, D, GAMMA1: 2 ** 19, GAMMA2: GAMMA2_2, TAU: 60, ETA: 2, OMEGA: 75
+    }),
 }))();
 const newPoly = (n) => new Int32Array(n);
 // Shared CRYSTALS helper in the ML-DSA branch: non-Kyber mode, 8-bit bit-reversal,
@@ -66,24 +72,32 @@ 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.
-const polyAdd = (a, b) => {
+// 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_;
     for (let i = 0; i < a.length; i++)
         a[i] = crystals.mod(a[i] + b[i]);
     return a;
 };
 // Mutates `a` in place; callers must pass same-length polynomials.
-const polySub = (a, b) => {
+const polySub = (a_, b_) => {
+    const a = a_;
+    const b = b_;
     for (let i = 0; i < a.length; i++)
         a[i] = crystals.mod(a[i] - b[i]);
     return a;
 };
 // Mutates `p` in place and assumes it is a decoded `t1`-range polynomial.
-const polyShiftl = (p) => {
+const polyShiftl = (p_) => {
+    const p = p_;
     for (let i = 0; i < N; i++)
         p[i] <<= D;
     return p;
 };
-const polyChknorm = (p, B) => {
+const polyChknorm = (p_, B) => {
+    const p = p_;
     // FIPS 204 Algorithms 7 and 8 express the same centered-norm check with explicit inequalities.
     for (let i = 0; i < N; i++)
         if (Math.abs(crystals.smod(p[i])) >= B)
@@ -91,7 +105,9 @@ const polyChknorm = (p, B) => {
     return false;
 };
 // Both inputs must already be in NTT / `T_q` form.
-const MultiplyNTTs = (a, b) => {
+const MultiplyNTTs = (a_, b_) => {
+    const a = a_;
+    const b = b_;
     // NOTE: we don't use montgomery reduction in code, since it requires 64 bit ints,
     // which is not available in JS. mod(a[i] * b[i]) is ok, since Q is 23 bit,
     // which means a[i] * b[i] is 46 bit, which is safe to use in JS. (number is 53 bits).
@@ -102,7 +118,8 @@ const MultiplyNTTs = (a, b) => {
     return c;
 };
 // Return poly in NTT representation
-function RejNTTPoly(xof) {
+function RejNTTPoly(xof_) {
+    const xof = xof_;
     // 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 :(
@@ -121,7 +138,8 @@ function RejNTTPoly(xof) {
 }
 // Instantiate one ML-DSA parameter set from the Table 1 lattice constants plus the
 // Table 2 byte lengths / hash-width choices used by the public wrappers below.
-function getDilithium(opts) {
+function getDilithium(opts_) {
+    const opts = opts_;
     const { K, L, GAMMA1, GAMMA2, TAU, ETA, OMEGA } = opts;
     const { CRH_BYTES, TR_BYTES, C_TILDE_BYTES, XOF128, XOF256, securityLevel } = opts;
     if (![2, 4].includes(ETA))
@@ -163,14 +181,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) => {
@@ -181,7 +201,8 @@ function getDilithium(opts) {
     };
     const hintCoder = {
         bytesLen: OMEGA + K,
-        encode: (h) => {
+        encode: (h_) => {
+            const h = h_;
             if (h === false)
                 throw new Error('hint.encode: hint is false'); // should never happen
             const res = new Uint8Array(OMEGA + K);
@@ -235,7 +256,8 @@ function getDilithium(opts) {
     // Return poly in ordinary representation.
     // This helper returns ordinary-form `[-ETA, ETA]` coefficients for ExpandS; callers apply
     // `NTT.encode()` later when needed.
-    function RejBoundedPoly(xof) {
+    function RejBoundedPoly(xof_) {
+        const xof = xof_;
         // Samples an element a ∈ Rq with coeffcients in [−η, η] computed via rejection sampling from ρ.
         const r = newPoly(N);
         for (let j = 0; j < N;) {
@@ -279,7 +301,8 @@ function getDilithium(opts) {
         }
         return pre;
     };
-    const polyPowerRound = (p) => {
+    const polyPowerRound = (p_) => {
+        const p = p_;
         const res0 = newPoly(N);
         const res1 = newPoly(N);
         for (let i = 0; i < p.length; i++) {
@@ -289,14 +312,18 @@ function getDilithium(opts) {
         }
         return { r0: res0, r1: res1 };
     };
-    const polyUseHint = (u, h) => {
+    const polyUseHint = (u_, h_) => {
+        const u = u_;
+        const h = h_;
         // In-place on `u`: verification only needs the recovered high bits, so reuse the
         // temporary `wApprox` buffer instead of allocating another polynomial.
         for (let i = 0; i < N; i++)
             u[i] = UseHint(h[i], u[i]);
         return u;
     };
-    const polyMakeHint = (a, b) => {
+    const polyMakeHint = (a_, b_) => {
+        const a = a_;
+        const b = b_;
         const v = newPoly(N);
         let cnt = 0;
         for (let i = 0; i < N; i++) {
@@ -309,15 +336,15 @@ function getDilithium(opts) {
     const signRandBytes = 32;
     const seedCoder = splitCoder('seed', 32, 64, 32);
     // API & argument positions are exactly as in FIPS204.
-    const internal = {
-        info: { type: 'internal-ml-dsa' },
-        lengths: {
+    const internal = Object.freeze({
+        info: Object.freeze({ type: 'internal-ml-dsa' }),
+        lengths: Object.freeze({
             secretKey: secretCoder.bytesLen,
             publicKey: publicCoder.bytesLen,
             seed: 32,
             signature: sigCoder.bytesLen,
             signRand: signRandBytes,
-        },
+        }),
         keygen: (seed) => {
             // H(𝜉||IntegerToBytes(𝑘, 1)||IntegerToBytes(ℓ, 1), 128) 2: ▷ expand seed
             const seedDst = new Uint8Array(32 + 2);
@@ -367,7 +394,10 @@ function getDilithium(opts) {
             // DSA44: { calls: 24, xofs: 24 }, DSA65: { calls: 41, xofs: 41 },
             // DSA87: { calls: 71, xofs: 71 }
             cleanBytes(rho, rhoPrime, K_, s1, s2, s1Hat, t, t0, t1, tr, seedDst);
-            return { publicKey, secretKey };
+            return {
+                publicKey: publicKey,
+                secretKey: secretKey,
+            };
         },
         getPublicKey: (secretKey) => {
             // (ρ, K,tr, s1, s2, t0) ← skDecode(sk)
@@ -395,11 +425,34 @@ function getDilithium(opts) {
         sign: (msg, secretKey, opts = {}) => {
             validateSigOpts(opts);
             validateInternalOpts(opts);
-            let { extraEntropy: random, externalMu = false } = opts;
+            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);
@@ -422,19 +475,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
@@ -506,6 +555,9 @@ function getDilithium(opts) {
         verify: (sig, msg, publicKey, opts = {}) => {
             validateInternalOpts(opts);
             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)
@@ -561,9 +613,9 @@ function getDilithium(opts) {
                     return false;
             return equalBytes(cTilde, c2);
         },
-    };
-    return {
-        info: { type: 'ml-dsa' },
+    });
+    return Object.freeze({
+        info: Object.freeze({ type: 'ml-dsa' }),
         internal,
         securityLevel: securityLevel,
         keygen: internal.keygen,
@@ -578,32 +630,54 @@ function getDilithium(opts) {
         },
         verify: (sig, msg, publicKey, opts = {}) => {
             validateVerOpts(opts);
+            abytes(sig, undefined, 'signature');
             return internal.verify(sig, getMessage(msg, opts.context), publicKey);
         },
         prehash: (hash) => {
             checkHash(hash, securityLevel);
-            return {
-                info: { type: 'hashml-dsa' },
+            const rawHash = hash;
+            return Object.freeze({
+                info: Object.freeze({ type: 'hashml-dsa' }),
                 securityLevel: securityLevel,
                 lengths: internal.lengths,
                 keygen: internal.keygen,
                 getPublicKey: internal.getPublicKey,
                 sign: (msg, secretKey, opts = {}) => {
                     validateSigOpts(opts);
-                    const M = getMessagePrehash(hash, msg, opts.context);
+                    const M = getMessagePrehash(rawHash, msg, opts.context);
                     const res = internal.sign(M, secretKey, opts);
                     cleanBytes(M);
                     return res;
                 },
                 verify: (sig, msg, publicKey, opts = {}) => {
                     validateVerOpts(opts);
-                    return internal.verify(sig, getMessagePrehash(hash, msg, opts.context), publicKey);
+                    abytes(sig, undefined, 'signature');
+                    return internal.verify(sig, getMessagePrehash(rawHash, msg, opts.context), publicKey);
                 },
-            };
+            });
         },
-    };
+    });
 }
-/** 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,
@@ -633,4 +707,3 @@ export const ml_dsa87 = /* @__PURE__ */ (() => getDilithium({
     XOF256,
     securityLevel: 256,
 }))();
-//# sourceMappingURL=ml-dsa.js.map

package/ml-kem.d.ts

@@ -1,4 +1,4 @@
-import { type KEM } from './utils.ts';
+import { type KEM, type TRet } from './utils.ts';
 /** FIPS 203: 7. Parameter Sets */
 /** Public ML-KEM parameter-set description. */
 export type KEMParam = {
@@ -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: 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: 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: KEM;
+export declare const ml_kem1024: TRet<MLKEM>;
 export declare const __tests: any;
-//# sourceMappingURL=ml-kem.d.ts.map