@noble/post-quantum 0.4.1 → 0.5.1

package/src/hybrid.ts

@@ -0,0 +1,373 @@
+/**
+ * Post-Quantum Hybrid Cryptography
+ *
+ * The current implementation is flawed and likely redundant. We should offer
+ * a small, generic API to compose hybrid schemes instead of reimplementing
+ * protocol-specific logic (SSH, GPG, etc.) with ad hoc encodings.
+ *
+ * 1. Core Issues
+ *    - sign/verify: implemented as two separate operations with different keys.
+ *    - EC getSharedSecret: could be refactored into a proper KEM.
+ *    - Multiple calls: keys, signatures, and shared secrets could be
+ *      concatenated to reduce the number of API invocations.
+ *    - Reinvention: most libraries add strange domain separations and
+ *      encodings instead of simple byte concatenation.
+ *
+ * 2. API Goals
+ *    - Provide primitives to build hybrids generically.
+ *    - Avoid embedding SSH- or GPG-specific formats in the core API.
+ *
+ * 3. Edge Cases
+ *    • Variable-length signatures:
+ *      - DER-encoded (Weierstrass curves).
+ *      - Falcon (unpadded).
+ *      - Concatenation works only if length is fixed; otherwise a length
+ *        prefix is required (but that breaks compatibility).
+ *
+ *    • getSharedSecret:
+ *      - Default: non-KEM (authenticated ECDH).
+ *      - KEM conversion: generate a random SK to remove implicit auth.
+ *
+ * 4. Common Pitfalls
+ *    - Seed expansion:
+ *      • Expanding a small seed into multiple keys reduces entropy.
+ *      • API should allow identity mapping (no expansion).
+ *
+ *    - Skipping full point encoding:
+ *      • Some omit the compression byte (parity) for WebCrypto compatibility.
+ *      • Better: hash the raw secret; coordinate output is already non-uniform.
+ *      • Some curves (e.g., X448) produce secrets that must be re-hashed to match
+ *        symmetric-key lengths.
+ *
+ *    - Combiner inconsistencies:
+ *      • Different domain separations and encodings across libraries.
+ *      • Should live at the application layer, since key lengths vary.
+ *
+ * 5. Protocol Examples
+ *    - SSH:
+ *      • Concatenate keys.
+ *      • Combiner: SHA-512.
+ *
+ *    - GPG:
+ *      • Concatenate keys.
+ *      • Combiner: SHA3-256(kemShare || ecdhShare || ciphertext || pubKey || algId || domSep || len(domSep))
+ *
+ *    - TLS:
+ *      • Transcript-based derivation (HKDF).
+ *
+ * 6. Relevant Specs & Implementations
+ *    - IETF Hybrid KEM drafts:
+ *      • draft-irtf-cfrg-hybrid-kems
+ *      • draft-connolly-cfrg-xwing-kem
+ *      • draft-westerbaan-tls-xyber768d00
+ *
+ *    - PQC Libraries:
+ *      • superdilithium (cyph/pqcrypto.js) – low adoption.
+ *      • hybrid-pqc (DogeProtocol, quantumcoinproject) – complex encodings.
+ *
+ * 7. Signatures
+ *    - Ed25519: fixed-size, easy to support.
+ *    - Variable-size: introduces custom format requirements; best left to
+ *      higher-level code.
+ *
+ * @module
+ */
+/*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
+import { type EdDSA } from '@noble/curves/abstract/edwards.js';
+import { type MontgomeryECDH } from '@noble/curves/abstract/montgomery.js';
+import { type ECDSA } from '@noble/curves/abstract/weierstrass.js';
+import { x25519 } from '@noble/curves/ed25519.js';
+import { p256, p384 } from '@noble/curves/nist.js';
+import {
+  asciiToBytes,
+  bytesToNumberBE,
+  bytesToNumberLE,
+  concatBytes,
+  numberToBytesBE,
+} from '@noble/curves/utils.js';
+import { expand, extract } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { sha3_256, shake256 } from '@noble/hashes/sha3.js';
+import { abytes, ahash, anumber, type CHash, type CHashXOF } from '@noble/hashes/utils.js';
+import { ml_kem1024, ml_kem768 } from './ml-kem.ts';
+import {
+  cleanBytes,
+  randomBytes,
+  splitCoder,
+  type CryptoKeys,
+  type KEM,
+  type Signer,
+} from './utils.ts';
+
+type CurveAll = ECDSA | EdDSA | MontgomeryECDH;
+type CurveECDH = ECDSA | MontgomeryECDH;
+type CurveSign = ECDSA | EdDSA;
+
+// Can re-use if decide to signatures support, on other hand getSecretKey is specific and ugly
+function ecKeygen(curve: CurveAll, allowZeroKey: boolean = false) {
+  const lengths = curve.lengths;
+  let keygen = curve.keygen;
+  if (allowZeroKey) {
+    // This is ugly, but we need to return exact results here.
+    const wCurve = curve as typeof p256;
+    const Fn = wCurve.Point.Fn;
+    if (!Fn) throw new Error('No Point.Fn');
+    keygen = (seed: Uint8Array = randomBytes(lengths.seed)) => {
+      abytes(seed, lengths.seed!, 'seed');
+      const seedScalar = Fn.isLE ? bytesToNumberLE(seed) : bytesToNumberBE(seed);
+      const secretKey = Fn.toBytes(Fn.create(seedScalar)); // Fixes modulo bias, but not zero
+      return { secretKey, publicKey: curve.getPublicKey(secretKey) };
+    };
+  }
+  return {
+    lengths: { secretKey: lengths.secretKey, publicKey: lengths.publicKey, seed: lengths.seed },
+    keygen,
+    getPublicKey: (secretKey: Uint8Array) => curve.getPublicKey(secretKey),
+  };
+}
+
+export const ecdhKem = (curve: CurveECDH, allowZeroKey: boolean = false): KEM => {
+  const kg = ecKeygen(curve, allowZeroKey);
+  if (!curve.getSharedSecret) throw new Error('wrong curve'); // ed25519 doesn't have one!
+  return {
+    lengths: { ...kg.lengths, msg: kg.lengths.seed, cipherText: kg.lengths.publicKey },
+    keygen: kg.keygen,
+    getPublicKey: kg.getPublicKey,
+    encapsulate(publicKey: Uint8Array, rand: Uint8Array = randomBytes(curve.lengths.secretKey)) {
+      const ek = this.keygen(rand).secretKey;
+      const sharedSecret = this.decapsulate(publicKey, ek);
+      const cipherText = curve.getPublicKey(ek);
+      cleanBytes(ek);
+      return { sharedSecret, cipherText };
+    },
+    decapsulate(cipherText: Uint8Array, secretKey: Uint8Array) {
+      const res = curve.getSharedSecret(secretKey, cipherText);
+      return curve.lengths.publicKeyHasPrefix ? res.subarray(1) : res;
+    },
+  };
+};
+
+export const ecSigner = (curve: CurveSign, allowZeroKey: boolean = false): Signer => {
+  const kg = ecKeygen(curve, allowZeroKey);
+  if (!curve.sign || !curve.verify) throw new Error('wrong curve'); // ed25519 doesn't have one!
+  return {
+    lengths: { ...kg.lengths, signature: curve.lengths.signature, signRand: 0 },
+    keygen: kg.keygen,
+    getPublicKey: kg.getPublicKey,
+    sign: (message, secretKey) => curve.sign(message, secretKey),
+    verify: (signature, message, publicKey) => curve.verify(signature, message, publicKey),
+  };
+};
+
+function splitLengths<K extends string, T extends { lengths: Partial<Record<K, number>> }>(
+  lst: T[],
+  name: K
+) {
+  return splitCoder(
+    name,
+    ...lst.map((i) => {
+      if (typeof i.lengths[name] !== 'number') throw new Error('wrong length: ' + name);
+      return i.lengths[name];
+    })
+  );
+}
+
+export type ExpandSeed = (seed: Uint8Array, len: number) => Uint8Array;
+type XOF = CHashXOF<any, { dkLen: number }>;
+
+// It is XOF for most cases, but can be more complex!
+export function expandSeedXof(xof: XOF): ExpandSeed {
+  return (seed: Uint8Array, seedLen: number) => xof(seed, { dkLen: seedLen });
+}
+
+export type Combiner = (
+  publicKeys: Uint8Array[],
+  cipherTexts: Uint8Array[],
+  sharedSecrets: Uint8Array[]
+) => Uint8Array;
+
+function combineKeys(
+  realSeedLen: number | undefined, // how much bytes expandSeed expects
+  expandSeed: ExpandSeed,
+  ...ck: CryptoKeys[]
+) {
+  const seedCoder = splitLengths(ck, 'seed');
+  const pkCoder = splitLengths(ck, 'publicKey');
+  // Allows to use identity functions for combiner/expandSeed
+  if (realSeedLen === undefined) realSeedLen = seedCoder.bytesLen;
+  anumber(realSeedLen);
+  function expandDecapsulationKey(seed: Uint8Array) {
+    abytes(seed, realSeedLen!);
+    const expanded = seedCoder.decode(expandSeed(seed, seedCoder.bytesLen));
+    const keys = ck.map((i, j) => i.keygen(expanded[j]));
+    const secretKey = keys.map((i) => i.secretKey);
+    const publicKey = keys.map((i) => i.publicKey);
+    return { secretKey, publicKey };
+  }
+  return {
+    info: { lengths: { seed: realSeedLen, publicKey: pkCoder.bytesLen, secretKey: realSeedLen } },
+    getPublicKey(secretKey: Uint8Array) {
+      return this.keygen(secretKey).publicKey;
+    },
+    keygen(seed: Uint8Array = randomBytes(realSeedLen)) {
+      const { publicKey: pk, secretKey } = expandDecapsulationKey(seed);
+      const publicKey = pkCoder.encode(pk);
+      cleanBytes(pk);
+      cleanBytes(secretKey);
+      return { secretKey: seed, publicKey };
+    },
+    expandDecapsulationKey,
+    realSeedLen,
+  };
+}
+
+// This generic function that combines multiple KEMs into single one
+export function combineKEMS(
+  realSeedLen: number | undefined, // how much bytes expandSeed expects
+  realMsgLen: number | undefined, // how much bytes combiner returns
+  expandSeed: ExpandSeed,
+  combiner: Combiner,
+  ...kems: KEM[]
+): KEM {
+  const keys = combineKeys(realSeedLen, expandSeed, ...kems);
+  const ctCoder = splitLengths(kems, 'cipherText');
+  const pkCoder = splitLengths(kems, 'publicKey');
+  const msgCoder = splitLengths(kems, 'msg');
+  if (realMsgLen === undefined) realMsgLen = msgCoder.bytesLen;
+  anumber(realMsgLen);
+  return {
+    lengths: {
+      ...keys.info.lengths,
+      msg: realMsgLen,
+      msgRand: msgCoder.bytesLen,
+      cipherText: ctCoder.bytesLen,
+    },
+    getPublicKey: keys.getPublicKey,
+    keygen: keys.keygen,
+    encapsulate(pk: Uint8Array, randomness: Uint8Array = randomBytes(msgCoder.bytesLen)) {
+      const pks = pkCoder.decode(pk);
+      const rand = msgCoder.decode(randomness);
+      const enc = kems.map((i, j) => i.encapsulate(pks[j], rand[j]));
+      const sharedSecret = enc.map((i) => i.sharedSecret);
+      const cipherText = enc.map((i) => i.cipherText);
+      const res = {
+        sharedSecret: combiner(pks, cipherText, sharedSecret),
+        cipherText: ctCoder.encode(cipherText),
+      };
+      cleanBytes(sharedSecret, cipherText, pks);
+      return res;
+    },
+    decapsulate(ct: Uint8Array, seed: Uint8Array) {
+      const cts = ctCoder.decode(ct);
+      const { publicKey, secretKey } = keys.expandDecapsulationKey(seed);
+      const sharedSecret = kems.map((i, j) => i.decapsulate(cts[j], secretKey[j]));
+      return combiner(publicKey, cts, sharedSecret);
+    },
+  };
+}
+// There is no specs for this, but can be useful
+// realSeedLen: how much bytes expandSeed expects.
+export function combineSigners(
+  realSeedLen: number | undefined,
+  expandSeed: ExpandSeed,
+  ...signers: Signer[]
+): Signer {
+  const keys = combineKeys(realSeedLen, expandSeed, ...signers);
+  const sigCoder = splitLengths(signers, 'signature');
+  const pkCoder = splitLengths(signers, 'publicKey');
+  return {
+    lengths: { ...keys.info.lengths, signature: sigCoder.bytesLen, signRand: 0 },
+    getPublicKey: keys.getPublicKey,
+    keygen: keys.keygen,
+    sign(message, seed) {
+      const { secretKey } = keys.expandDecapsulationKey(seed);
+      // NOTE: we probably can make different hashes for different algorithms
+      // same way as we do for kem, but not sure if this a good idea.
+      const sigs = signers.map((i, j) => i.sign(message, secretKey[j]));
+      return sigCoder.encode(sigs);
+    },
+    verify: (signature, message, publicKey) => {
+      const pks = pkCoder.decode(publicKey);
+      const sigs = sigCoder.decode(signature);
+      for (let i = 0; i < signers.length; i++) {
+        if (!signers[i].verify(sigs[i], message, pks[i])) return false;
+      }
+      return true;
+    },
+  };
+}
+
+export function QSF(label: string, pqc: KEM, curveKEM: KEM, xof: XOF, kdf: CHash): KEM {
+  ahash(xof);
+  ahash(kdf);
+  return combineKEMS(
+    32,
+    32,
+    expandSeedXof(xof),
+    (pk, ct, ss) => kdf(concatBytes(ss[0], ss[1], ct[1], pk[1], asciiToBytes(label))),
+    pqc,
+    curveKEM
+  );
+}
+
+export const QSFMLKEM768P256: KEM = QSF(
+  'QSF-KEM(ML-KEM-768,P-256)-XOF(SHAKE256)-KDF(SHA3-256)',
+  ml_kem768,
+  ecdhKem(p256, true),
+  shake256,
+  sha3_256
+);
+
+export const QSFMLKEM1024P384: KEM = QSF(
+  'QSF-KEM(ML-KEM-1024,P-384)-XOF(SHAKE256)-KDF(SHA3-256)',
+  ml_kem1024,
+  ecdhKem(p384, true),
+  shake256,
+  sha3_256
+);
+
+export function KitchenSink(label: string, pqc: KEM, curveKEM: KEM, xof: XOF, hash: CHash): KEM {
+  ahash(xof);
+  ahash(hash);
+  return combineKEMS(
+    32,
+    32,
+    expandSeedXof(xof),
+    (pk, ct, ss) => {
+      const preimage = concatBytes(ss[0], ss[1], ct[0], pk[0], ct[1], pk[1], asciiToBytes(label));
+      const len = 32;
+      const ikm = concatBytes(asciiToBytes('hybrid_prk'), preimage);
+      const prk = extract(hash, ikm);
+      const info = concatBytes(
+        numberToBytesBE(len, 2),
+        asciiToBytes('shared_secret'),
+        asciiToBytes('')
+      );
+      const res = expand(hash, prk, info, len);
+      cleanBytes(prk, info, ikm, preimage);
+      return res;
+    },
+    pqc,
+    curveKEM
+  );
+}
+
+const x25519kem = ecdhKem(x25519);
+export const KitchenSinkMLKEM768X25519: KEM = KitchenSink(
+  'KitchenSink-KEM(ML-KEM-768,X25519)-XOF(SHAKE256)-KDF(HKDF-SHA-256)',
+  ml_kem768,
+  x25519kem,
+  shake256,
+  sha256
+);
+
+// Always X25519 and ML-KEM - 768, no point to export
+export const XWing: KEM = combineKEMS(
+  32,
+  32,
+  expandSeedXof(shake256),
+  // Awesome label, so much escaping hell in a single line.
+  (pk, ct, ss) => sha3_256(concatBytes(ss[0], ss[1], ct[1], pk[1], asciiToBytes('\\.//^\\'))),
+  ml_kem768,
+  x25519kem
+);

package/src/index.ts

@@ -4,8 +4,8 @@
  * @module
  * @example
 ```js
-import { ml_kem512, ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem';
-import { ml_dsa44, ml_dsa65, ml_dsa87 } from '@noble/post-quantum/ml-dsa';
+import { ml_kem512, ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem.js';
+import { ml_dsa44, ml_dsa65, ml_dsa87 } from '@noble/post-quantum/ml-dsa.js';
 import {
   slh_dsa_sha2_128f, slh_dsa_sha2_128s,
   slh_dsa_sha2_192f, slh_dsa_sha2_192s,
@@ -13,7 +13,7 @@ import {
   slh_dsa_shake_128f, slh_dsa_shake_128s,
   slh_dsa_shake_192f, slh_dsa_shake_192s,
   slh_dsa_shake_256f, slh_dsa_shake_256s,
-} from '@noble/post-quantum/slh-dsa';
+} from '@noble/post-quantum/slh-dsa.js';
 ```
  */
 throw new Error('root module cannot be imported: import submodules instead. Check out README');

package/src/ml-dsa.ts

@@ -8,22 +8,49 @@
  * @module
  */
 /*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
-import { shake256 } from '@noble/hashes/sha3';
+import { abool } from '@noble/curves/utils.js';
+import { shake256 } from '@noble/hashes/sha3.js';
+import type { CHash } from '@noble/hashes/utils.js';
 import { genCrystals, type XOF, XOF128, XOF256 } from './_crystals.ts';
 import {
+  abytes,
   type BytesCoderLen,
+  checkHash,
   cleanBytes,
-  EMPTY,
-  ensureBytes,
+  type CryptoKeys,
   equalBytes,
   getMessage,
   getMessagePrehash,
   randomBytes,
   type Signer,
+  type SigOpts,
   splitCoder,
+  validateOpts,
+  validateSigOpts,
+  validateVerOpts,
   vecCoder,
+  type VerOpts,
 } from './utils.ts';
 
+export type DSAInternalOpts = { externalMu?: boolean };
+function validateInternalOpts(opts: DSAInternalOpts) {
+  validateOpts(opts);
+  if (opts.externalMu !== undefined) abool(opts.externalMu, 'opts.externalMu');
+}
+
+/** Signer API, containing internal methods */
+export type DSAInternal = CryptoKeys & {
+  lengths: Signer['lengths'];
+  sign: (msg: Uint8Array, secretKey: Uint8Array, opts?: SigOpts & DSAInternalOpts) => Uint8Array;
+  verify: (
+    sig: Uint8Array,
+    msg: Uint8Array,
+    pubKey: Uint8Array,
+    opts?: VerOpts & DSAInternalOpts
+  ) => boolean;
+};
+export type DSA = Signer & { internal: DSAInternal };
+
 // Constants
 const N = 256;
 // 2**23 − 2**13 + 1, 23 bits: multiply will be 46. We have enough precision in JS to avoid bigints
@@ -59,7 +86,7 @@ export const PARAMS: Record<string, DSAParam> = {
 
 // NOTE: there is a lot cases where negative numbers used (with smod instead of mod).
 type Poly = Int32Array;
-const newPoly = (n: number) => new Int32Array(n);
+const newPoly = (n: number): Int32Array => new Int32Array(n);
 
 const { mod, smod, NTT, bitsCoder } = genCrystals({
   N,
@@ -139,11 +166,12 @@ type DilithiumOpts = {
   TR_BYTES: number;
   XOF128: XOF;
   XOF256: XOF;
+  securityLevel: number;
 };
 
 function getDilithium(opts: DilithiumOpts) {
   const { K, L, GAMMA1, GAMMA2, TAU, ETA, OMEGA } = opts;
-  const { CRH_BYTES, TR_BYTES, C_TILDE_BYTES, XOF128, XOF256 } = opts;
+  const { CRH_BYTES, TR_BYTES, C_TILDE_BYTES, XOF128, XOF256, securityLevel } = opts;
 
   if (![2, 4].includes(ETA)) throw new Error('Wrong ETA');
   if (![1 << 17, 1 << 19].includes(GAMMA1)) throw new Error('Wrong GAMMA1');
@@ -239,8 +267,9 @@ function getDilithium(opts: DilithiumOpts) {
   const W1Coder = polyCoder(GAMMA2 === GAMMA2_1 ? 6 : 4);
   const W1Vec = vecCoder(W1Coder, K);
   // Main structures
-  const publicCoder = splitCoder(32, vecCoder(T1Coder, K));
+  const publicCoder = splitCoder('publicKey', 32, vecCoder(T1Coder, K));
   const secretCoder = splitCoder(
+    'secretKey',
     32,
     32,
     TR_BYTES,
@@ -248,7 +277,7 @@ function getDilithium(opts: DilithiumOpts) {
     vecCoder(ETACoder, K),
     vecCoder(T0Coder, K)
   );
-  const sigCoder = splitCoder(C_TILDE_BYTES, vecCoder(ZCoder, L), hintCoder);
+  const sigCoder = splitCoder('signature', C_TILDE_BYTES, vecCoder(ZCoder, L), hintCoder);
   const CoefFromHalfByte =
     ETA === 2
       ? (n: number) => (n < 15 ? 2 - (n % 5) : false)
@@ -322,18 +351,25 @@ function getDilithium(opts: DilithiumOpts) {
   };
 
   const signRandBytes = 32;
-  const seedCoder = splitCoder(32, 64, 32);
+  const seedCoder = splitCoder('seed', 32, 64, 32);
   // API & argument positions are exactly as in FIPS204.
-  const internal: Signer = {
-    signRandBytes,
+  const internal: DSAInternal = {
+    info: { type: 'internal-ml-dsa' },
+    lengths: {
+      secretKey: secretCoder.bytesLen,
+      publicKey: publicCoder.bytesLen,
+      seed: 32,
+      signature: sigCoder.bytesLen,
+      signRand: signRandBytes,
+    },
     keygen: (seed?: Uint8Array) => {
       // H(𝜉||IntegerToBytes(𝑘, 1)||IntegerToBytes(ℓ, 1), 128) 2: ▷ expand seed
       const seedDst = new Uint8Array(32 + 2);
       const randSeed = seed === undefined;
       if (randSeed) seed = randomBytes(32);
-      ensureBytes(seed, 32);
+      abytes(seed!, 32, 'seed');
       seedDst.set(seed!);
-      if (randSeed) seed!.fill(0);
+      if (randSeed) cleanBytes(seed!);
       seedDst[32] = K;
       seedDst[33] = L;
       const [rho, rhoPrime, K_] = seedCoder.decode(
@@ -352,7 +388,7 @@ function getDilithium(opts: DilithiumOpts) {
       const t = newPoly(N);
       for (let i = 0; i < K; i++) {
         // t ← NTT−1(A*NTT(s1)) + s2
-        t.fill(0); // don't-reallocate
+        cleanBytes(t); // don't-reallocate
         for (let j = 0; j < L; j++) {
           const aij = RejNTTPoly(xof.get(j, i)); // super slow!
           polyAdd(t, MultiplyNTTs(aij, s1Hat[j]));
@@ -373,8 +409,32 @@ function getDilithium(opts: DilithiumOpts) {
       cleanBytes(rho, rhoPrime, K_, s1, s2, s1Hat, t, t0, t1, tr, seedDst);
       return { publicKey, secretKey };
     },
+    getPublicKey: (secretKey: Uint8Array) => {
+      const [rho, _K, _tr, s1, s2, _t0] = secretCoder.decode(secretKey); // (ρ, K,tr, s1, s2, t0) ← skDecode(sk)
+      const xof = XOF128(rho);
+      const s1Hat = s1.map((p) => NTT.encode(p.slice()));
+      const t1: Poly[] = [];
+      const tmp = newPoly(N);
+      for (let i = 0; i < K; i++) {
+        tmp.fill(0);
+        for (let j = 0; j < L; j++) {
+          const aij = RejNTTPoly(xof.get(j, i)); // A_ij in NTT
+          polyAdd(tmp, MultiplyNTTs(aij, s1Hat[j])); // += A_ij * s1_j
+        }
+        NTT.decode(tmp); // NTT⁻¹
+        polyAdd(tmp, s2[i]); // t_i = A·s1 + s2
+        const { r1 } = polyPowerRound(tmp); // r1 = t1, r0 ≈ t0
+        t1.push(r1);
+      }
+      xof.clean();
+      cleanBytes(tmp, s1Hat, _t0, s1, s2);
+      return publicCoder.encode([rho, t1]);
+    },
     // NOTE: random is optional.
-    sign: (secretKey: Uint8Array, msg: Uint8Array, random?: Uint8Array, externalMu = false) => {
+    sign: (msg: Uint8Array, secretKey: Uint8Array, opts: SigOpts & DSAInternalOpts = {}) => {
+      validateSigOpts(opts);
+      validateInternalOpts(opts);
+      let { extraEntropy: random, externalMu = false } = opts;
       // 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.
       const [rho, _K, tr, s1, s2, t0] = secretCoder.decode(secretKey); // (ρ, K,tr, s1, s2, t0) ← skDecode(sk)
@@ -398,8 +458,13 @@ function getDilithium(opts: DilithiumOpts) {
         : shake256.create({ dkLen: CRH_BYTES }).update(tr).update(msg).digest(); // 6: µ ← H(tr||M, 512) ▷ Compute message representative µ
 
       // Compute private random seed
-      const rnd = random ? random : new Uint8Array(32);
-      ensureBytes(rnd);
+      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)
@@ -407,7 +472,7 @@ function getDilithium(opts: DilithiumOpts) {
         .update(mu)
         .digest(); // ρ′← H(K||rnd||µ, 512)
 
-      ensureBytes(rhoprime, CRH_BYTES);
+      abytes(rhoprime, CRH_BYTES);
       const x256 = XOF256(rhoprime, ZCoder.bytesLen);
       //  Rejection sampling loop
       main_loop: for (let kappa = 0; ; ) {
@@ -464,7 +529,14 @@ function getDilithium(opts: DilithiumOpts) {
       // @ts-ignore
       throw new Error('Unreachable code path reached, report this error');
     },
-    verify: (publicKey: Uint8Array, msg: Uint8Array, sig: Uint8Array, externalMu = false) => {
+    verify: (
+      sig: Uint8Array,
+      msg: Uint8Array,
+      publicKey: Uint8Array,
+      opts: DSAInternalOpts = {}
+    ) => {
+      validateInternalOpts(opts);
+      const { externalMu = false } = opts;
       // 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)
@@ -512,61 +584,76 @@ function getDilithium(opts: DilithiumOpts) {
     },
   };
   return {
+    info: { type: 'ml-dsa' },
     internal,
+    securityLevel: securityLevel,
     keygen: internal.keygen,
-    signRandBytes: internal.signRandBytes,
-    sign: (secretKey: Uint8Array, msg: Uint8Array, ctx = EMPTY, random?: Uint8Array) => {
-      const M = getMessage(msg, ctx);
-      const res = internal.sign(secretKey, M, random);
-      M.fill(0);
+    lengths: internal.lengths,
+    getPublicKey: internal.getPublicKey,
+    sign: (msg: Uint8Array, secretKey: Uint8Array, opts: SigOpts = {}) => {
+      validateSigOpts(opts);
+      const M = getMessage(msg, opts.context);
+      const res = internal.sign(M, secretKey, opts);
+      cleanBytes(M);
       return res;
     },
-    verify: (publicKey: Uint8Array, msg: Uint8Array, sig: Uint8Array, ctx = EMPTY) => {
-      return internal.verify(publicKey, getMessage(msg, ctx), sig);
+    verify: (sig: Uint8Array, msg: Uint8Array, publicKey: Uint8Array, opts: VerOpts = {}) => {
+      validateVerOpts(opts);
+      return internal.verify(sig, getMessage(msg, opts.context), publicKey);
+    },
+    prehash: (hash: CHash) => {
+      checkHash(hash, securityLevel);
+      return {
+        info: { type: 'hashml-dsa' },
+        securityLevel: securityLevel,
+        lengths: internal.lengths,
+        keygen: internal.keygen,
+        getPublicKey: internal.getPublicKey,
+        sign: (msg: Uint8Array, secretKey: Uint8Array, opts: SigOpts = {}) => {
+          validateSigOpts(opts);
+          const M = getMessagePrehash(hash, msg, opts.context);
+          const res = internal.sign(M, secretKey, opts);
+          cleanBytes(M);
+          return res;
+        },
+        verify: (sig: Uint8Array, msg: Uint8Array, publicKey: Uint8Array, opts: VerOpts = {}) => {
+          validateVerOpts(opts);
+          return internal.verify(sig, getMessagePrehash(hash, msg, opts.context), publicKey);
+        },
+      };
     },
-    prehash: (hashName: string) => ({
-      sign: (secretKey: Uint8Array, msg: Uint8Array, ctx = EMPTY, random?: Uint8Array) => {
-        const M = getMessagePrehash(hashName, msg, ctx);
-        const res = internal.sign(secretKey, M, random);
-        M.fill(0);
-        return res;
-      },
-      verify: (publicKey: Uint8Array, msg: Uint8Array, sig: Uint8Array, ctx = EMPTY) => {
-        return internal.verify(publicKey, getMessagePrehash(hashName, msg, ctx), sig);
-      },
-    }),
   };
 }
 
-/** Signer API, containing internal methods */
-export type SignerWithInternal = Signer & { internal: Signer };
-
 /** ML-DSA-44 for 128-bit security level. Not recommended after 2030, as per ASD. */
-export const ml_dsa44: SignerWithInternal = /* @__PURE__ */ getDilithium({
+export const ml_dsa44: DSA = /* @__PURE__ */ getDilithium({
   ...PARAMS[2],
   CRH_BYTES: 64,
   TR_BYTES: 64,
   C_TILDE_BYTES: 32,
   XOF128,
   XOF256,
+  securityLevel: 128,
 });
 
 /** ML-DSA-65 for 192-bit security level. Not recommended after 2030, as per ASD. */
-export const ml_dsa65: SignerWithInternal = /* @__PURE__ */ getDilithium({
+export const ml_dsa65: DSA = /* @__PURE__ */ getDilithium({
   ...PARAMS[3],
   CRH_BYTES: 64,
   TR_BYTES: 64,
   C_TILDE_BYTES: 48,
   XOF128,
   XOF256,
+  securityLevel: 192,
 });
 
 /** ML-DSA-87 for 256-bit security level. OK after 2030, as per ASD. */
-export const ml_dsa87: SignerWithInternal = /* @__PURE__ */ getDilithium({
+export const ml_dsa87: DSA = /* @__PURE__ */ getDilithium({
   ...PARAMS[5],
   CRH_BYTES: 64,
   TR_BYTES: 64,
   C_TILDE_BYTES: 64,
   XOF128,
   XOF256,
+  securityLevel: 256,
 });