ML-DSA-44.

ML-DSA-65.

ML-DSA-87.

The three parameter sets of FIPS 204.

Named for the algorithm rather than "DSA", which is a different one that crypton also has, in Crypto.PubKey.DSA. It is the three sets FIPS 204 defines, closed, carrying their sizes and the calls into the implementation; only the sizes are exported.

A public verification key.

A private signing key.

A signature.

Try to read a verification key. Only the length is checked: a verification key is a packed encoding with no redundancy to test, and one that is not a real key simply verifies nothing.

Try to read a signing key.

Beyond the length this runs the validity checks of the implementation: the secret polynomials must have coefficients in range, and the commitment and the public-key hash the key carries must match what is recomputed from the rest of it. A key that fails has been damaged or was never a key, and signing with it would produce signatures nothing verifies.

Try to read a signature. Only the length is checked; whether it is a signature of anything is what verify answers.

Generate a key pair.

The seed it is derived from is drawn here and thrown away. Use generateKeyPairAndSeed where it has to be kept.

Generate a key pair and hand back the seed it was derived from, xi in FIPS 204.

A SigningKey is the expanded key and nothing else, so the seed cannot be recovered from a pair afterwards. An application that has to write the key out in a form that keeps the seed -- RFC 9881 lets an ML-DSA private key be the seed, the expanded key, or both -- has to generate it here:

(vk, sk, seed) <- generateKeyPairAndSeed MLDSA65

The seed is as secret as the signing key: keyPairFromSeed turns it back into the same pair.

Derive a key pair from a seed, xi in FIPS 204, which must be seedSize bytes.

Recover the verification key a signing key was made with.

The context string a signature is bound to, at most maxContextLength bytes.

FIPS 204 mixes it into what is signed, so a signature made under one context does not verify under another. Two uses of one key that don't agree on a context string cannot be made to accept each other's signatures. Use emptyContext where there is nothing to separate -- TLS, for one, signs with an empty context.

Try to build a context string.

The context string of length zero, which is what to sign under when there is nothing to separate.

It is a context and not the absence of one: sign always takes one, and what this separates from is every non-empty context there is.

The message representative, mu in FIPS 204: a 64-byte commitment to the verification key, the context string and the message, and the only part of them that signing and verification actually read.

Signing it directly is the "external mu" interface. It is for a caller that has the representative without having the message in one piece: a message arriving as a stream, or hashed on another machine, or by a device that holds the key and is handed only this. TLS does not need it.

Try to read a message representative.

Compute the message representative, for a caller that wants to make it here and sign it later, or sign it elsewhere.

signExternalMuDeterministic sk (messageRepresentative (toPublic sk) ctx msg) and signDeterministic sk ctx msg are the same signature.

A Mu being computed, with the message going in a piece at a time.

The name is not Context: that is ML-DSA's context string, which this is built from and is not.

Begin a message representative. The key and the context string are what it is bound to, and they are all that is needed before the message.

muFinalize (muUpdates (muInit vk ctx) chunks)

is messageRepresentative of the chunks joined, so a message too large to hold at once never has to be.

Absorb a piece of the message.

Absorb several pieces, which is muUpdate one after the other.

The message representative of everything absorbed so far.

Sign a message.

This is the hedged signing FIPS 204 recommends: fresh randomness goes in alongside the key and the message, so two signatures of one message differ and a fault in one reveals less. Verification does not care which of the three entry points made the signature.

Sign with the randomness supplied, which must be signingRandomnessSize bytes.

For test vectors, and for callers who draw their own randomness. Ordinary use wants sign.

Sign deterministically, as FIPS 204 section 3.4 allows: the randomness is replaced by zeroes, so one key and one message always give one signature.

This is what test vectors are written against, and what to use where the signature must be reproducible. It gives up what hedging buys, so where there is a usable random source sign is the better default.

Verify a signature.

The context must be the one it was signed under; anything else is a rejection, which is what the context is for.

Sign a message representative, drawing the randomness.

The context string is already inside the representative, which is why this does not take one.

Sign a message representative with the randomness supplied.

Sign a message representative deterministically.

Verify a signature of a message representative.

Size in bytes of the seed keyPairFromSeed takes, xi in FIPS 204.

Size in bytes of the randomness signWith takes.

The longest context string FIPS 204 allows, which is 255 bytes because its length is encoded in one byte.

Size in bytes of a Mu.