@theqrl/mldsa87 2.0.1 → 2.1.0

package/src/index.d.ts

@@ -89,6 +89,35 @@ export function cryptoSign(
   ctx: Uint8Array
 ): Uint8Array;
 
+/**
+ * Create a deterministic ML-DSA-87 detached signature
+ * (FIPS 204 §3.5 — `randomizedSigning = false` wrapper).
+ *
+ * **Use only when the deterministic property is itself a requirement**
+ * — RANDAO-style verifiable beacon contributions, ACVP / KAT vector
+ * reproduction. For general-purpose signing prefer `cryptoSignSignature`
+ * with `randomizedSigning = true` (hedged, FIPS 204 §3.4 recommended).
+ * (TOB-QRLLIB-6.)
+ */
+export function cryptoSignSignatureDeterministic(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  sk: Uint8Array,
+  ctx: Uint8Array
+): number;
+
+/**
+ * Attached-form deterministic ML-DSA-87 signing
+ * (FIPS 204 §3.5 — `randomizedSigning = false` wrapper for `cryptoSign`).
+ * Same recommendation as `cryptoSignSignatureDeterministic`.
+ * (TOB-QRLLIB-6.)
+ */
+export function cryptoSignDeterministic(
+  msg: Uint8Array | string,
+  sk: Uint8Array,
+  ctx: Uint8Array
+): Uint8Array;
+
 /**
  * Verify a signature
  * @param sig - Signature to verify
@@ -109,7 +138,10 @@ export function cryptoSignVerify(
  * @param sm - Signed message (signature || message)
  * @param pk - Public key
  * @param ctx - Context string (max 255 bytes)
- * @returns Message if valid, undefined if verification fails
+ * @returns Message if valid, undefined if verification fails (or if
+ *   sm is null / undefined / non-Uint8Array / shorter than
+ *   CryptoBytes — see `cryptoSignOpenWithReason` for distinct
+ *   failure-mode reporting)
  */
 export function cryptoSignOpen(
   sm: Uint8Array,
@@ -117,6 +149,40 @@ export function cryptoSignOpen(
   ctx: Uint8Array
 ): Uint8Array | undefined;
 
+/**
+ * Failure-mode discriminator returned by `cryptoSignOpenWithReason`.
+ * (TOB-QRLLIB-14: distinct failure modes for Open.)
+ */
+export type CryptoSignOpenReason =
+  | 'invalid-ctx-type'
+  | 'invalid-ctx-length'
+  | 'invalid-sm-type'
+  | 'invalid-sm-length'
+  | 'invalid-pk'
+  | 'verification-failed';
+
+/**
+ * Open a signed message with a typed failure-mode report.
+ * (TOB-QRLLIB-14.) Behavioural twin of `cryptoSignOpen` that
+ * distinguishes API-shape problems (input wrong type / length /
+ * shape) from genuine verification failures.
+ *
+ * `cryptoSignOpen` is kept unchanged and continues to return
+ * `undefined` for any failure mode. Use this variant when you need
+ * to log or route on specific failure modes.
+ *
+ * @param sm - Signed message (signature || message)
+ * @param pk - Public key
+ * @param ctx - Context string (max 255 bytes)
+ */
+export function cryptoSignOpenWithReason(
+  sm: Uint8Array,
+  pk: Uint8Array,
+  ctx: Uint8Array
+):
+  | { ok: true; message: Uint8Array }
+  | { ok: false; reason: CryptoSignOpenReason };
+
 // Utility functions
 
 /**
@@ -202,3 +268,118 @@ export function unpackSig(
   h: PolyVecK,
   sig: Uint8Array
 ): number;
+
+// FIPS 202 SHAKE primitives (low-level XOF interface, primarily internal)
+export function shake128Init(state: KeccakState): void;
+export function shake128Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake128Finalize(state: KeccakState): void;
+export function shake128SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+export function shake256Init(state: KeccakState): void;
+export function shake256Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake256Finalize(state: KeccakState): void;
+export function shake256SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+
+// ML-DSA-specific stream initializers
+export function mldsaShake128StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+export function mldsaShake256StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+
+// Polynomial operations (internal)
+export function polyReduce(a: Poly): void;
+export function polyCAddQ(a: Poly): void;
+export function polyAdd(c: Poly, a: Poly, b: Poly): void;
+export function polySub(c: Poly, a: Poly, b: Poly): void;
+export function polyShiftL(a: Poly): void;
+export function polyPointWiseMontgomery(c: Poly, a: Poly, b: Poly): void;
+export function polyPower2round(a1: Poly, a0: Poly, a: Poly): void;
+export function polyDecompose(a1: Poly, a0: Poly, a: Poly): void;
+export function polyMakeHint(h: Poly, a0: Poly, a1: Poly): number;
+export function polyUseHint(b: Poly, a: Poly, h: Poly): void;
+export function polyChkNorm(a: Poly, b: number): number;
+export function rejUniform(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniform(a: Poly, seed: Uint8Array, nonce: number): void;
+export function rejEta(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniformEta(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyZUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyUniformGamma1(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyEtaPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyEtaUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT1Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT0Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT0Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyZPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyW1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+
+// Polynomial vector operations (internal)
+export function polyVecMatrixExpand(mat: PolyVecL[], rho: Uint8Array): void;
+export function polyVecMatrixPointWiseMontgomery(
+  t: PolyVecK,
+  mat: PolyVecL[],
+  v: PolyVecL
+): void;
+export function polyVecLUniformEta(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLUniformGamma1(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLReduce(v: PolyVecL): void;
+export function polyVecLAdd(w: PolyVecL, u: PolyVecL, v: PolyVecL): void;
+export function polyVecLNTT(v: PolyVecL): void;
+export function polyVecLInvNTTToMont(v: PolyVecL): void;
+export function polyVecLPointWisePolyMontgomery(
+  r: PolyVecL,
+  a: Poly,
+  v: PolyVecL
+): void;
+export function polyVecLPointWiseAccMontgomery(
+  w: Poly,
+  u: PolyVecL,
+  v: PolyVecL
+): void;
+export function polyVecLChkNorm(v: PolyVecL, bound: number): number;
+export function polyVecKUniformEta(v: PolyVecK, seed: Uint8Array, nonce: number): void;
+export function polyVecKReduce(v: PolyVecK): void;
+export function polyVecKCAddQ(v: PolyVecK): void;
+export function polyVecKAdd(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKSub(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKShiftL(v: PolyVecK): void;
+export function polyVecKNTT(v: PolyVecK): void;
+export function polyVecKInvNTTToMont(v: PolyVecK): void;
+export function polyVecKPointWisePolyMontgomery(
+  r: PolyVecK,
+  a: Poly,
+  v: PolyVecK
+): void;
+export function polyVecKChkNorm(v: PolyVecK, bound: number): number;
+export function polyVecKPower2round(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKDecompose(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKMakeHint(h: PolyVecK, v0: PolyVecK, v1: PolyVecK): number;
+export function polyVecKUseHint(w: PolyVecK, u: PolyVecK, h: PolyVecK): void;
+export function polyVecKPackW1(r: Uint8Array, w1: PolyVecK): void;