@webbuf/mldsa

WebBuf 4 byte access

Public APIs keep WebBuf and FixedBuf wrappers. For native APIs use value.bytes or fixed.buf.bytes. This package unwraps selected native views at its WASM boundary; key/signature/secret formats and cryptographic behavior are unchanged. Inputs are not mutated and outputs retain their existing independent storage. Nonzero-offset selections are supported.

ML-DSA (FIPS 204) post-quantum digital signatures for WebBuf.

Preferred API

Use the message-level APIs for application code. They apply the FIPS 204 domain and context separation rules and default to hedged signing by generating randomness with the platform CSPRNG through FixedBuf.fromRandom.

import { mlDsa65KeyPair, mlDsa65Sign, mlDsa65Verify } from "@webbuf/mldsa";
import { WebBuf } from "@webbuf/webbuf";

const message = WebBuf.fromUtf8("Signed message");
const context = WebBuf.fromUtf8("example");
const { verifyingKey, signingKey } = mlDsa65KeyPair();
const signature = mlDsa65Sign(signingKey, message, context);
const ok = mlDsa65Verify(verifyingKey, message, signature, context);

The preferred APIs are available for ML-DSA-44, ML-DSA-65, and ML-DSA-87. Two calls to mlDsa*Sign(sk, msg) with identical inputs produce different signatures because each call samples fresh randomness — this matches FIPS 204 §3.6 best practice and @webbuf/slhdsa's default.

Deterministic And Internal APIs

Seeded key generation and deterministic signing aliases are available for reproducible tests and advanced protocol work:

mlDsa65KeyPairDeterministic(seed);
mlDsa65SignDeterministic(signingKey, message, context);

mlDsa*SignDeterministic(...) produces identical bytes for identical inputs (rnd = 0^32 per FIPS 204 §5.4 deterministic variant).

The mlDsa*SignInternal(...) and mlDsa*VerifyInternal(...) functions remain public for ACVP vectors and low-level conformance work. They expose FIPS 204 internal primitives (Sign_internal / Verify_internal) and should not be the default application-facing API.

Testing

The package keeps NIST ACVP vector tests for the internal interface and adds round-trip and context-separation tests for the preferred message-level API.