@noble/post-quantum 0.6.1 → 0.7.1

package/src/slh-dsa.ts

@@ -28,15 +28,10 @@
  */
 /*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
 import { hmac } from '@noble/hashes/hmac.js';
+import { bytesToNumberBE, numberToBytesBE } from '@noble/curves/utils.js';
 import { sha256, sha512 } from '@noble/hashes/sha2.js';
 import { shake256 } from '@noble/hashes/sha3.js';
-import {
-  bytesToHex,
-  concatBytes,
-  createView,
-  hexToBytes,
-  type CHash,
-} from '@noble/hashes/utils.js';
+import { concatBytes, createView, type CHash } from '@noble/hashes/utils.js';
 import {
   abytes,
   checkHash,
@@ -58,6 +53,13 @@ import {
   type VerOpts,
 } from './utils.ts';
 
+// Keys the internal SLH-DSA surface accepts. `context` is deliberately absent: the public
+// wrappers consume it when they format M' and must not forward it, because a key that is
+// accepted and then never read is the same silent downgrade this validation exists to prevent.
+// `extraEntropy` is signing-only, so verification (which takes no options of its own) has none.
+const INTERNAL_SIG_OPT_KEYS = /* @__PURE__ */ Object.freeze(['extraEntropy'] as const);
+const INTERNAL_VER_OPT_KEYS = /* @__PURE__ */ Object.freeze([] as const);
+
 /**
  * * N: Security parameter (in bytes). W: Winternitz parameter
  * * H: Hypertree height. D: Hypertree layers
@@ -88,6 +90,8 @@ export type SphincsHashOpts = {
   getContext: GetContext;
 };
 
+type InternalSphincsHashOpts = SphincsHashOpts & { isCompressed: boolean };
+
 /** Winternitz signature params. */
 /**
  * Built-in SLH-DSA Table 2 subset keyed by strength/profile.
@@ -123,12 +127,16 @@ const AddressType = {
 /** Address byte array of size `ADDR_BYTES`. */
 export type ADRS = Uint8Array;
 
-/** Hash and tweakable-hash callbacks bound to one SLH-DSA keypair context. */
+/** Hash and tweakable-hash callbacks bound to one SLH-DSA keypair context.
+ * Buffer-aliasing contract: `PRFaddr`, `thash1` and `thashN` return views into per-context
+ * scratch buffers (one per lane), so callers must consume or copy a result before the next
+ * call on the same lane. `clean()` wipes the scratch buffers along with the hash states.
+ */
 export type Context = {
   /**
    * Derive a PRF output for one address.
    * @param addr - Address bytes.
-   * @returns PRF output bytes.
+   * @returns PRF output bytes (scratch view; copy to retain).
    */
   PRFaddr: (addr: TArg<ADRS>) => TRet<Uint8Array>;
   /**
@@ -180,21 +188,6 @@ export type GetContext = (
   opts: SphincsOpts
 ) => (pub_seed: TArg<Uint8Array>, sk_seed?: TArg<Uint8Array>) => TRet<Context>;
 
-function hexToNumber(hex: string): bigint {
-  if (typeof hex !== 'string') throw new Error('hex string expected, got ' + typeof hex);
-  return BigInt(hex === '' ? '0' : '0x' + hex); // Big Endian
-}
-
-// BE: Big Endian, LE: Little Endian. This is the local FIPS 205 `toInt(...)` equivalent.
-function bytesToNumberBE(bytes: TArg<Uint8Array>): bigint {
-  return hexToNumber(bytesToHex(bytes));
-}
-
-// Local in-range FIPS 205 `toByte(x, n)` equivalent; callers must keep `n < 256^len`.
-function numberToBytesBE(n: number | bigint, len: number): TRet<Uint8Array> {
-  return hexToBytes(n.toString(16).padStart(len * 2, '0'));
-}
-
 // Local FIPS 205 Algorithm 4 `base_2^b(...)` implementation. Bits are consumed in big-endian
 // order within each input byte, and callers must provide at least `ceil(outLen * b / 8)` bytes;
 // short inputs are not rejected and would zero-extend implicitly.
@@ -214,8 +207,12 @@ const base2b = (outLen: number, b: number) => {
   };
 };
 
+const _1n = /* @__PURE__ */ BigInt(1);
+const _8n = /* @__PURE__ */ BigInt(8);
+const _0xffn = /* @__PURE__ */ BigInt(0xff);
+
 function getMaskBig(bits: number) {
-  return (1n << BigInt(bits)) - 1n; // 4 -> 0b1111
+  return (_1n << BigInt(bits)) - _1n; // 4 -> 0b1111
 }
 
 /** Public SLH-DSA signer with prehash customization. */
@@ -230,8 +227,8 @@ export type SphincsSigner = Signer & {
  * and `getPublicKey(secretKey)` only extracts the embedded public key
  * instead of recomputing `PK.root`.
  */
-function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsSigner> {
-  const hashOpts = hashOpts_ as SphincsHashOpts;
+function gen(opts: SphincsOpts, hashOpts_: TArg<InternalSphincsHashOpts>): TRet<SphincsSigner> {
+  const hashOpts = hashOpts_ as InternalSphincsHashOpts;
   const { N, W, H, D, K, A, securityLevel: securityLevel } = opts;
   const getContext = hashOpts.getContext(opts);
   if (W !== 16) throw new Error('Unsupported Winternitz parameter');
@@ -282,18 +279,37 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
     }>,
     addr: TArg<ADRS> = new Uint8Array(ADDR_BYTES)
   ) => {
-    const { type, height, tree, layer, index, chain, hash, keypair } = opts;
-    const { subtreeAddr, keypairAddr } = opts;
-    const v = createView(addr);
+    // These objects are created in hot internal loops, so avoid cloning them. Read only own fields:
+    // absent address words must stay absent even if Object.prototype was polluted.
+    const type = Object.hasOwn(opts, 'type') ? opts.type : undefined;
+    const height = Object.hasOwn(opts, 'height') ? opts.height : undefined;
+    const tree = Object.hasOwn(opts, 'tree') ? opts.tree : undefined;
+    const layer = Object.hasOwn(opts, 'layer') ? opts.layer : undefined;
+    const index = Object.hasOwn(opts, 'index') ? opts.index : undefined;
+    const chain = Object.hasOwn(opts, 'chain') ? opts.chain : undefined;
+    const hash = Object.hasOwn(opts, 'hash') ? opts.hash : undefined;
+    const keypair = Object.hasOwn(opts, 'keypair') ? opts.keypair : undefined;
+    const subtreeAddr = Object.hasOwn(opts, 'subtreeAddr') ? opts.subtreeAddr : undefined;
+    const keypairAddr = Object.hasOwn(opts, 'keypairAddr') ? opts.keypairAddr : undefined;
 
     if (height !== undefined) addr[OFFSET_CHAIN_ADDR] = height;
     if (layer !== undefined) addr[OFFSET_LAYER] = layer;
     if (type !== undefined) addr[OFFSET_TYPE] = type;
     if (chain !== undefined) addr[OFFSET_CHAIN_ADDR] = chain;
     if (hash !== undefined) addr[OFFSET_HASH_ADDR] = hash;
-    if (index !== undefined) v.setUint32(OFFSET_TREE_INDEX, index, false);
+    // Manual big-endian writes: setAddr runs in the innermost WOTS/tree loops, and creating a
+    // DataView per call was a measurable share of sign() time.
+    if (index !== undefined) {
+      addr[OFFSET_TREE_INDEX + 0] = index >>> 24;
+      addr[OFFSET_TREE_INDEX + 1] = index >>> 16;
+      addr[OFFSET_TREE_INDEX + 2] = index >>> 8;
+      addr[OFFSET_TREE_INDEX + 3] = index;
+    }
     if (subtreeAddr) addr.set(subtreeAddr.subarray(0, OFFSET_TREE + 8));
-    if (tree !== undefined) v.setBigUint64(OFFSET_TREE, tree, false);
+    if (tree !== undefined) {
+      let t = tree;
+      for (let i = 7; i >= 0; i--, t >>= _8n) addr[OFFSET_TREE + i] = Number(t & _0xffn);
+    }
     if (keypair !== undefined) {
       addr[OFFSET_KP_ADDR1] = keypair;
       if (TREE_HEIGHT > 8) addr[OFFSET_KP_ADDR2] = keypair >>> 8;
@@ -372,10 +388,12 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
       const maxIdx = (1 << height) - 1;
       const stack = new Uint8Array(height * N);
       const authPath = new Uint8Array(height * N);
+      // One node buffer per treehash call (not per leaf): both halves are fully overwritten at
+      // each use, and the returned root aliases cur1, which is never reused after return.
+      const current = new Uint8Array(2 * N);
+      const cur0 = current.subarray(0, N);
+      const cur1 = current.subarray(N);
       for (let idx = 0; ; idx++) {
-        const current = new Uint8Array(2 * N);
-        const cur0 = current.subarray(0, N);
-        const cur1 = current.subarray(N);
         const addrOffset = idx + idxOffset;
         cur1.set(leafFn(leafIdx, addrOffset, rawContext, info));
         let h = 0;
@@ -548,7 +566,7 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
       return Uint8Array.from(pk) as TRet<Uint8Array>;
     },
     sign: (msg: TArg<Uint8Array>, sk: TArg<Uint8Array>, opts: TArg<SigOpts> = {}) => {
-      validateSigOpts(opts);
+      opts = validateSigOpts(opts, INTERNAL_SIG_OPT_KEYS);
       let { extraEntropy: random } = opts;
       const [skSeed, skPRF, pk] = secretCoder.decode(sk); // todo: fix
       const [pkSeed, _] = publicCoder.decode(pk);
@@ -582,7 +600,9 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
           },
           forsTreeAddr
         );
-        const prf = context.PRFaddr(forsTreeAddr);
+        // Copy: PRFaddr returns a per-context scratch view, and this value is retained in
+        // `fors` across the many PRFaddr calls inside forsTreehash below.
+        const prf = copyBytes(context.PRFaddr(forsTreeAddr));
         setAddr({ type: AddressType.FORSTREE }, forsTreeAddr);
         const { root, authPath } = forsTreehash(
           context,
@@ -598,7 +618,9 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
         type: AddressType.FORSPK,
         keypairAddr: wotsAddr,
       });
-      const root = context.thashN(K, concatBytes(...roots), forsPkAddr);
+      // Copy: thashN returns a per-context scratch view, and `root` lives across every hash
+      // call in the hypertree loop below (it is also mutated via root.set).
+      const root = copyBytes(context.thashN(K, concatBytes(...roots), forsPkAddr));
       // WOTS signatures
       const treeAddr = setAddr({ type: AddressType.HASHTREE });
       const wots: [Uint8Array, Uint8Array][] = [];
@@ -620,11 +642,24 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
       cleanBytes(R, random, treeAddr, wotsAddr, forsLeaf, forsTreeAddr, indices, roots);
       return SIG as TRet<Uint8Array>;
     },
-    verify: (sig: TArg<Uint8Array>, msg: TArg<Uint8Array>, publicKey: TArg<Uint8Array>) => {
+    verify: (
+      sig: TArg<Uint8Array>,
+      msg: TArg<Uint8Array>,
+      publicKey: TArg<Uint8Array>,
+      opts: TArg<VerOpts> = {}
+    ) => {
+      // The internal verify reads no options; reject any so a stray key (e.g. a caller
+      // mistaking this for the public verify and passing `context`) is reported rather than
+      // silently swallowed by this function's arity.
+      validateVerOpts(opts, INTERNAL_VER_OPT_KEYS);
       const [pkSeed, pubRoot] = publicCoder.decode(publicKey);
-      const [random, forsVec, wotsVec] = sigCoder.decode(sig);
       const pk = publicKey;
+      // FIPS 205 Algorithm 20 step 1: wrong-length signatures return false instead of throwing
+      // (same as ml-dsa). Must run before sigCoder.decode, which throws on length mismatch.
+      // Preserve TypeError for non-byte API arguments before treating byte lengths as invalid.
+      abytes(sig, undefined, 'signature');
       if (sig.length !== sigCoder.bytesLen) return false;
+      const [random, forsVec, wotsVec] = sigCoder.decode(sig);
       const context = getContext(pkSeed);
       let { tree, leafIdx, md } = hashMessage(random, pk, msg, context);
       const wotsAddr = setAddr({
@@ -644,14 +679,18 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
         const idxOffset = i << A;
         setAddr({ height: 0, index: indices[i] + idxOffset }, forsTreeAddr);
         const leaf = context.thash1(prf, forsTreeAddr);
-        // Compute inplace, because we need all roots in same byte array
-        roots.push(computeRoot(leaf, indices[i], idxOffset, authPath, A, context, forsTreeAddr));
+        // Copy: computeRoot returns a thashN scratch view, and roots are retained across the
+        // remaining FORS iterations (computeRoot itself copies `leaf` before hashing).
+        roots.push(
+          copyBytes(computeRoot(leaf, indices[i], idxOffset, authPath, A, context, forsTreeAddr))
+        );
       }
       const forsPkAddr = setAddr({
         type: AddressType.FORSPK,
         keypairAddr: wotsAddr,
       });
-      let root = context.thashN(K, concatBytes(...roots), forsPkAddr); // root = thash()
+      // Copy: `root` must survive the thash1/thashN calls of the WOTS chain loop below.
+      let root = copyBytes(context.thashN(K, concatBytes(...roots), forsPkAddr)); // root = thash()
       // WOTS signature
       const treeAddr = setAddr({ type: AddressType.HASHTREE });
       const wotsPkAddr = setAddr({ type: AddressType.WOTSPK });
@@ -674,7 +713,8 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
           }
         }
         const leaf = context.thashN(WOTS_LEN, wotsPk, wotsPkAddr);
-        root = computeRoot(leaf, leafIdx, 0, sigAuth, TREE_HEIGHT, context, treeAddr);
+        // Copy: `root` is read by chainLengths / equalBytes after later hash calls.
+        root = copyBytes(computeRoot(leaf, leafIdx, 0, sigAuth, TREE_HEIGHT, context, treeAddr));
         leafIdx = Number(tree & getMaskBig(TREE_HEIGHT));
       }
       return equalBytes(root, pubRoot);
@@ -688,9 +728,11 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
     keygen: internal.keygen,
     getPublicKey: internal.getPublicKey,
     sign: (msg: TArg<Uint8Array>, secretKey: TArg<Uint8Array>, opts: TArg<SigOpts> = {}) => {
-      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 });
       cleanBytes(M);
       return res as TRet<Uint8Array>;
     },
@@ -700,7 +742,7 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
       publicKey: TArg<Uint8Array>,
       opts: TArg<VerOpts> = {}
     ) => {
-      validateVerOpts(opts);
+      opts = validateVerOpts(opts);
       return internal.verify(sig, getMessage(msg, opts.context), publicKey);
     },
     prehash: (hash: TArg<CHash>): TRet<Signer> => {
@@ -712,9 +754,10 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
         keygen: internal.keygen,
         getPublicKey: internal.getPublicKey,
         sign: (msg: TArg<Uint8Array>, secretKey: TArg<Uint8Array>, opts: TArg<SigOpts> = {}) => {
-          validateSigOpts(opts);
+          opts = validateSigOpts(opts);
           const M = getMessagePrehash(rawHash, msg, opts.context);
-          const res = internal.sign(M, secretKey, opts);
+          // As above: getMessagePrehash() consumes `context`, so it must not travel further.
+          const res = internal.sign(M, secretKey, { extraEntropy: opts.extraEntropy });
           cleanBytes(M);
           return res as TRet<Uint8Array>;
         },
@@ -724,7 +767,7 @@ function gen(opts: SphincsOpts, hashOpts_: TArg<SphincsHashOpts>): TRet<SphincsS
           publicKey: TArg<Uint8Array>,
           opts: TArg<VerOpts> = {}
         ) => {
-          validateVerOpts(opts);
+          opts = validateVerOpts(opts);
           return internal.verify(sig, getMessagePrehash(rawHash, msg, opts.context), publicKey);
         },
       });
@@ -744,20 +787,27 @@ const genShake =
     // for each address-bound call instead of reabsorbing the same seed every time.
     const h0 = shake256.create({}).update(pubSeed);
     const h0tmp = h0.clone();
+    // Per-context output scratch: thash1/thashN/PRFaddr return these buffers directly, so
+    // callers must consume or copy a result before the next call on the same lane.
+    const thashOut = new Uint8Array(N);
+    const prfOut = new Uint8Array(N);
     const thash = (blocks: number, input: TArg<Uint8Array>, addr: TArg<ADRS>): TRet<Uint8Array> => {
       stats.thash++;
-      return h0
-        ._cloneInto(h0tmp)
+      const len = blocks * N;
+      h0._cloneInto(h0tmp)
         .update(addr)
-        .update(input.subarray(0, blocks * N))
-        .xof(N) as TRet<Uint8Array>;
+        .update(
+          input.length === len ? (input as Uint8Array) : (input as Uint8Array).subarray(0, len)
+        )
+        .xofInto(thashOut);
+      return thashOut as TRet<Uint8Array>;
     };
     return {
       PRFaddr: (addr: TArg<ADRS>): TRet<Uint8Array> => {
         if (!skSeed) throw new Error('no sk seed');
         stats.prf++;
-        const res = h0._cloneInto(h0tmp).update(addr).update(skSeed).xof(N);
-        return res as TRet<Uint8Array>;
+        h0._cloneInto(h0tmp).update(addr).update(skSeed).xofInto(prfOut);
+        return prfOut as TRet<Uint8Array>;
       },
       PRFmsg: (
         skPRF: TArg<Uint8Array>,
@@ -787,12 +837,13 @@ const genShake =
       clean: () => {
         h0.destroy();
         h0tmp.destroy();
+        cleanBytes(thashOut, prfOut);
         //console.log(stats);
       },
     } as TRet<Context>;
   };
 
-const SHAKE_SIMPLE = /* @__PURE__ */ (() => ({ getContext: genShake() }))();
+const SHAKE_SIMPLE = /* @__PURE__ */ (() => ({ isCompressed: false, getContext: genShake() }))();
 
 /**
  * SLH-DSA-SHAKE-128f: Table 2 row `n=16, h=66, d=22, h'=3, a=6, k=33, lg w=4, m=34`;
@@ -869,6 +920,16 @@ const genSha =
 
     const h0tmp = h0ps.clone();
     const h1tmp = h1ps.clone();
+    // Per-context output scratch: thash1/thashN/PRFaddr return views into these buffers, so
+    // callers must consume or copy a result before the next call on the same lane (see Context
+    // docs). digestInto also skips digest()'s per-call destroy(): the tmp states are fully
+    // overwritten by the next _cloneInto and wiped in clean().
+    const h0out = new Uint8Array(h0.outputLen);
+    const h1out = new Uint8Array(h1.outputLen);
+    const prfOut = new Uint8Array(h0.outputLen);
+    const h0outN = h0out.subarray(0, N);
+    const h1outN = h1out.subarray(0, N);
+    const prfOutN = prfOut.subarray(0, N);
 
     // https://www.rfc-editor.org/rfc/rfc8017.html#appendix-B.2.1
     // This local helper is intentionally stricter than generic MGF1 reuse: current SLH-DSA callers
@@ -889,27 +950,28 @@ const genSha =
     }
 
     const thash =
-      (_: ShaType, h: typeof h0ps, hTmp: typeof h0ps) =>
+      (h: typeof h0ps, hTmp: typeof h0ps, out: TArg<Uint8Array>, outN: TArg<Uint8Array>) =>
       (blocks: number, input: TArg<Uint8Array>, addr: TArg<ADRS>): TRet<Uint8Array> => {
         stats.thash++;
-        const d = h
-          ._cloneInto(hTmp as any)
+        const len = blocks * N;
+        h._cloneInto(hTmp as any)
           .update(addr)
-          .update(input.subarray(0, blocks * N))
-          .digest();
-        return d.subarray(0, N) as TRet<Uint8Array>;
+          .update(
+            input.length === len ? (input as Uint8Array) : (input as Uint8Array).subarray(0, len)
+          )
+          .digestInto(out);
+        return outN as TRet<Uint8Array>;
       };
     return {
       PRFaddr: (addr: TArg<ADRS>): TRet<Uint8Array> => {
         if (!sk_seed) throw new Error('No sk seed');
         stats.prf++;
-        const res = h0ps
+        h0ps
           ._cloneInto(h0tmp as any)
           .update(addr)
           .update(sk_seed)
-          .digest()
-          .subarray(0, N);
-        return res as TRet<Uint8Array>;
+          .digestInto(prfOut);
+        return prfOutN as TRet<Uint8Array>;
       },
       PRFmsg: (
         skPRF: TArg<Uint8Array>,
@@ -938,13 +1000,14 @@ const genSha =
         );
         return mgf1(seed, outLen, h1);
       },
-      thash1: thash(h0, h0ps, h0tmp).bind(null, 1),
-      thashN: thash(h1, h1ps, h1tmp),
+      thash1: thash(h0ps, h0tmp, h0out, h0outN).bind(null, 1),
+      thashN: thash(h1ps, h1tmp, h1out, h1outN),
       clean: () => {
         h0ps.destroy();
         h1ps.destroy();
         h0tmp.destroy();
         h1tmp.destroy();
+        cleanBytes(h0out, h1out, prfOut);
         //console.log(stats);
       },
     } as TRet<Context>;
@@ -963,6 +1026,23 @@ const SHA512_SIMPLE = /* @__PURE__ */ (() => ({
  * SLH-DSA-SHA2-128f: Table 2 row `n=16, h=66, d=22, h'=3, a=6, k=33, lg w=4, m=34`;
  * lengths `publicKey=32`, `secretKey=64`, `signature=17088`, `seed=48`, `signRand=16`.
  * Also exposes `.prehash(...)`.
+ * @example
+ * Generate deterministic SLH-DSA keys, sign one message, and verify the signature.
+ * ```ts
+ * import { sha256 } from '@noble/hashes/sha2.js';
+ * import { slh_dsa_sha2_128f } from '@noble/post-quantum/slh-dsa.js';
+ * const seed = new Uint8Array(slh_dsa_sha2_128f.lengths.seed!);
+ * const { secretKey, publicKey } = slh_dsa_sha2_128f.keygen(seed);
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = slh_dsa_sha2_128f.sign(msg, secretKey);
+ * const isValid = slh_dsa_sha2_128f.verify(sig, msg, publicKey);
+ * const recovered = slh_dsa_sha2_128f.getPublicKey(secretKey);
+ * const context = new Uint8Array([1, 2, 3]);
+ * const prehash = slh_dsa_sha2_128f.prehash(sha256);
+ * const preSig = prehash.sign(msg, secretKey, { context });
+ * const preValid = prehash.verify(preSig, msg, publicKey, { context });
+ * const internalSig = slh_dsa_sha2_128f.internal.sign(msg, secretKey);
+ * ```
  */
 export const slh_dsa_sha2_128f: TRet<SphincsSigner> = /* @__PURE__ */ (() =>
   gen(PARAMS['128f'], SHA256_SIMPLE))();