Struct MLDSA 

pub struct MLDSA<const PK_LEN: usize, const SK_LEN: usize, const SIG_LEN: usize, PK: MLDSAPublicKeyTrait<k, l, PK_LEN> + MLDSAPublicKeyInternalTrait<k, PK_LEN>, SK: MLDSAPrivateKeyTrait<k, l, ETA, SK_LEN, PK_LEN> + MLDSAPrivateKeyInternalTrait<k, l, ETA, SK_LEN, PK_LEN>, const TAU: i32, const LAMBDA: i32, const GAMMA1: i32, const GAMMA2: i32, const k: usize, const l: usize, const ETA: usize, const BETA: i32, const OMEGA: i32, const C_TILDE: usize, const POLY_VEC_H_PACKED_LEN: usize, const POLY_W1_PACKED_LEN: usize, const LAMBDA_over_4: usize, const GAMMA1_MASK_LEN: usize, const GAMMA1_MINUS_BETA: i32, const GAMMA2_MINUS_BETA: i32> { /* private fields */ }

The core internal implementation of the ML-DSA algorithm. This needs to be public for the compiler to be able to find it, but you shouldn’t ever need to use this directly. Please use the named public types.

Implementations

impl<const PK_LEN: usize, const SK_LEN: usize, const SIG_LEN: usize, PK: MLDSAPublicKeyTrait<k, l, PK_LEN> + MLDSAPublicKeyInternalTrait<k, PK_LEN>, SK: MLDSAPrivateKeyTrait<k, l, ETA, SK_LEN, PK_LEN> + MLDSAPrivateKeyInternalTrait<k, l, ETA, SK_LEN, PK_LEN>, const TAU: i32, const LAMBDA: i32, const GAMMA1: i32, const GAMMA2: i32, const k: usize, const l: usize, const ETA: usize, const BETA: i32, const OMEGA: i32, const C_TILDE: usize, const POLY_Z_PACKED_LEN: usize, const POLY_W1_PACKED_LEN: usize, const LAMBDA_over_4: usize, const GAMMA1_MASK_LEN: usize, const GAMMA1_MINUS_BETA: i32, const GAMMA2_MINUS_BETA: i32> MLDSA<PK_LEN, SK_LEN, SIG_LEN, PK, SK, TAU, LAMBDA, GAMMA1, GAMMA2, k, l, ETA, BETA, OMEGA, C_TILDE, POLY_Z_PACKED_LEN, POLY_W1_PACKED_LEN, LAMBDA_over_4, GAMMA1_MASK_LEN, GAMMA1_MINUS_BETA, GAMMA2_MINUS_BETA>

pub fn keygen_from_os_rng() -> Result<(PK, SK), SignatureError>

Should still be ok in FIPS mode

Trait Implementations

impl<const PK_LEN: usize, const SK_LEN: usize, const SIG_LEN: usize, PK: MLDSAPublicKeyTrait<k, l, PK_LEN> + MLDSAPublicKeyInternalTrait<k, PK_LEN>, SK: MLDSAPrivateKeyTrait<k, l, ETA, SK_LEN, PK_LEN> + MLDSAPrivateKeyInternalTrait<k, l, ETA, SK_LEN, PK_LEN>, const TAU: i32, const LAMBDA: i32, const GAMMA1: i32, const GAMMA2: i32, const k: usize, const l: usize, const ETA: usize, const BETA: i32, const OMEGA: i32, const C_TILDE: usize, const POLY_Z_PACKED_LEN: usize, const POLY_W1_PACKED_LEN: usize, const LAMBDA_over_4: usize, const GAMMA1_MASK_LEN: usize, const GAMMA1_MINUS_BETA: i32, const GAMMA2_MINUS_BETA: i32> MLDSATrait<PK_LEN, SK_LEN, SIG_LEN, PK, SK, k, l, ETA> for MLDSA<PK_LEN, SK_LEN, SIG_LEN, PK, SK, TAU, LAMBDA, GAMMA1, GAMMA2, k, l, ETA, BETA, OMEGA, C_TILDE, POLY_Z_PACKED_LEN, POLY_W1_PACKED_LEN, LAMBDA_over_4, GAMMA1_MASK_LEN, GAMMA1_MINUS_BETA, GAMMA2_MINUS_BETA>

fn sign_mu_deterministic_from_seed_out( seed: &KeyMaterial<32>, mu: &[u8; 64], rnd: [u8; 32], output: &mut [u8; SIG_LEN], ) -> Result<usize, SignatureError>

This function is a mash-up of keyGen (Algorithm 6) and sign (Algorithm 7) Although, while this algorithm is a precursor to the lowmemory implementation, I’m not sure that it actually gains you anything over a keygen_from_seed() followed by a sign(), and maybe I should change its implementation to that.

fn verify_mu_internal( pk: &PK, A_hat: &Matrix<k, l>, mu: &[u8; 64], sig: &[u8; SIG_LEN], ) -> bool

Algorithm 8 ML-DSA.Verify_internal(𝑝𝑘, 𝑀′, 𝜎) Internal function to verify a signature 𝜎 for a formatted message 𝑀′ . Input: Public key 𝑝𝑘 ∈ 𝔹32+32𝑘(bitlen (𝑞−1)−𝑑) and message 𝑀′ ∈ {0, 1}∗ . Input: Signature 𝜎 ∈ 𝔹𝜆/4+ℓ⋅32⋅(1+bitlen (𝛾1−1))+𝜔+𝑘.

fn keygen_from_seed(seed: &KeyMaterial<32>) -> Result<(PK, SK), SignatureError>

Imports a secret key from a seed.

fn keygen_from_seed_and_encoded( seed: &KeyMaterial<32>, encoded_sk: &[u8; SK_LEN], ) -> Result<(PK, SK), SignatureError>

Imports a secret key from both a seed and an encoded_sk.

fn keypair_consistency_check(pk: &PK, sk: &SK) -> Result<(), SignatureError>

Given a public key and a secret key, check that the public key matches the secret key. This is a sanity check that the public key was generated correctly from the secret key.

fn compute_mu_from_tr( tr: &[u8; 64], msg: &[u8], ctx: Option<&[u8]>, ) -> Result<[u8; 64], SignatureError>

This provides the first half of the “External Mu” interface to ML-DSA which is described in, and allowed under, NIST’s FAQ that accompanies FIPS 204.

fn compute_mu_from_pk( pk: &impl MLDSAPublicKeyTrait<k, l, PK_LEN>, msg: &[u8], ctx: Option<&[u8]>, ) -> Result<[u8; 64], SignatureError>

Same as MLDSATrait::compute_mu_from_tr, but extracts tr from the public key.

fn compute_mu_from_sk( sk: &impl MLDSAPrivateKeyTrait<k, l, ETA, SK_LEN, PK_LEN>, msg: &[u8], ctx: Option<&[u8]>, ) -> Result<[u8; 64], SignatureError>

Same as MLDSATrait::compute_mu_from_tr, but extracts tr from the private key.

fn sign_with_expanded_key( sk: &MLDSAPrivateKeyExpanded<k, l, ETA, PK, SK, SK_LEN, PK_LEN>, msg: &[u8], ctx: Option<&[u8]>, ) -> Result<[u8; SIG_LEN], SignatureError>

Same as Signature::sign, but signs from an MLDSAPrivateKeyExpanded.

fn sign_with_expanded_key_out( sk: &MLDSAPrivateKeyExpanded<k, l, ETA, PK, SK, SK_LEN, PK_LEN>, msg: &[u8], ctx: Option<&[u8]>, out: &mut [u8; SIG_LEN], ) -> Result<usize, SignatureError>

Same as MLDSATrait::sign_with_expanded_key, but takes an output array.

fn sign_mu( sk: &SK, A_hat: Option<&Matrix<k, l>>, mu: &[u8; 64], ) -> Result<[u8; SIG_LEN], SignatureError>

Performs an ML-DSA signature using the provided external message representative mu. This implements FIPS 204 Algorithm 7 with line 6 removed; a modification that is allowed by both FIPS 204 itself, as well as subsequent FAQ documents. This mode uses randomized signing (called “hedged mode” in FIPS 204) using an internal RNG.

fn sign_mu_out( sk: &SK, A_hat: Option<&Matrix<k, l>>, mu: &[u8; 64], output: &mut [u8; SIG_LEN], ) -> Result<usize, SignatureError>

Performs an ML-DSA signature using the provided external message representative mu. This implements FIPS 204 Algorithm 7 with line 6 removed; a modification that is allowed by both FIPS 204 itself, as well as subsequent FAQ documents. This mode uses randomized signing (called “hedged mode” in FIPS 204) using an internal RNG.

fn sign_mu_with_expanded_key( sk: &MLDSAPrivateKeyExpanded<k, l, ETA, PK, SK, SK_LEN, PK_LEN>, A_hat: Option<&Matrix<k, l>>, mu: &[u8; 64], ) -> Result<[u8; SIG_LEN], SignatureError>

Same as [Signature::sign_mu], but signs from an MLDSAPrivateKeyExpanded.

fn sign_mu_with_expanded_key_out( sk: &MLDSAPrivateKeyExpanded<k, l, ETA, PK, SK, SK_LEN, PK_LEN>, A_hat: Option<&Matrix<k, l>>, mu: &[u8; 64], out: &mut [u8; SIG_LEN], ) -> Result<usize, SignatureError>

Same as [Signature::sign_mu_out], but signs from an MLDSAPrivateKeyExpanded.

fn sign_mu_deterministic( sk: &SK, A_hat: Option<&Matrix<k, l>>, mu: &[u8; 64], rnd: [u8; 32], ) -> Result<[u8; SIG_LEN], SignatureError>

Algorithm 7 ML-DSA.Sign_internal(𝑠𝑘, 𝑀′, 𝑟𝑛𝑑) (modified to take an externally-computed mu instead of M’)

fn sign_mu_deterministic_out( sk: &SK, A_hat: Option<&Matrix<k, l>>, mu: &[u8; 64], rnd: [u8; 32], output: &mut [u8; SIG_LEN], ) -> Result<usize, SignatureError>

Algorithm 7 ML-DSA.Sign_internal(𝑠𝑘, 𝑀′, 𝑟𝑛𝑑) (modified to take an externally-computed mu instead of M’)

fn sign_mu_deterministic_from_seed( seed: &KeyMaterial<32>, mu: &[u8; 64], rnd: [u8; 32], ) -> Result<[u8; SIG_LEN], SignatureError>

This contains a heavily-optimized combined keygen() and sign() which greatly reduces peak memory usage by never having the full secret key in memory at the same time, and by deriving intermediate values piece-wise as needed.

fn set_signer_rnd(&mut self, rnd: [u8; 32])

To be used for deterministic signing in conjunction with the MLDSA44::sign_init, MLDSA44::sign_update, and MLDSA44::sign_final flow. Can be set anywhere after MLDSA44::sign_init and before MLDSA44::sign_final.

fn sign_init_from_seed( seed: &KeyMaterial<32>, ctx: Option<&[u8]>, ) -> Result<Self, SignatureError>

Alternative initialization of the streaming signer where you have your private key as a seed and you want to delay its expansion as late as possible for memory-usage reasons.

fn verify_with_expanded_key( pk: &MLDSAPublicKeyExpanded<k, l, PK, PK_LEN>, msg: &[u8], ctx: Option<&[u8]>, sig: &[u8], ) -> Result<(), SignatureError>

Same as Signature::verify, but signs from an expanded key object.

impl<const PK_LEN: usize, const SK_LEN: usize, const SIG_LEN: usize, PK: MLDSAPublicKeyTrait<k, l, PK_LEN> + MLDSAPublicKeyInternalTrait<k, PK_LEN>, SK: MLDSAPrivateKeyTrait<k, l, ETA, SK_LEN, PK_LEN> + MLDSAPrivateKeyInternalTrait<k, l, ETA, SK_LEN, PK_LEN>, const TAU: i32, const LAMBDA: i32, const GAMMA1: i32, const GAMMA2: i32, const k: usize, const l: usize, const ETA: usize, const BETA: i32, const OMEGA: i32, const C_TILDE: usize, const POLY_Z_PACKED_LEN: usize, const POLY_W1_PACKED_LEN: usize, const LAMBDA_over_4: usize, const GAMMA1_MASK_LEN: usize, const GAMMA1_MINUS_BETA: i32, const GAMMA2_MINUS_BETA: i32> Signature<PK, SK, PK_LEN, SK_LEN, SIG_LEN> for MLDSA<PK_LEN, SK_LEN, SIG_LEN, PK, SK, TAU, LAMBDA, GAMMA1, GAMMA2, k, l, ETA, BETA, OMEGA, C_TILDE, POLY_Z_PACKED_LEN, POLY_W1_PACKED_LEN, LAMBDA_over_4, GAMMA1_MASK_LEN, GAMMA1_MINUS_BETA, GAMMA2_MINUS_BETA>

fn keygen() -> Result<(PK, SK), SignatureError>

Generate a keypair. Error condition: Basically only on RNG failures

fn sign( sk: &SK, msg: &[u8], ctx: Option<&[u8]>, ) -> Result<[u8; SIG_LEN], SignatureError>

Produce a signature for the provided message and context. Both the msg and ctx accept zero-length byte arrays.

fn sign_out( sk: &SK, msg: &[u8], ctx: Option<&[u8]>, output: &mut [u8; SIG_LEN], ) -> Result<usize, SignatureError>

Returns the number of bytes written to the output buffer. Can be called with an oversized buffer.

fn sign_init(sk: &SK, ctx: Option<&[u8]>) -> Result<Self, SignatureError>

Initialize a signer for streaming mode with the provided private key.

fn sign_update(&mut self, msg_chunk: &[u8])

Update the signer with the next chunk of data. This can be called multiple times.

fn sign_final(self) -> Result<[u8; SIG_LEN], SignatureError>

Complete the signing operation. Consumes self.

fn sign_final_out( self, output: &mut [u8; SIG_LEN], ) -> Result<usize, SignatureError>

Returns the number of bytes written to the output buffer. Can be called with an oversized buffer.

fn verify( pk: &PK, msg: &[u8], ctx: Option<&[u8]>, sig: &[u8], ) -> Result<(), SignatureError>

On success, returns Ok(()) On failure, returns Err(SignatureError::SignatureVerificationFailed); may also return other types of SignatureError as appropriate (such as for invalid-length inputs).

fn verify_init(pk: &PK, ctx: Option<&[u8]>) -> Result<Self, SignatureError>

fn verify_update(&mut self, msg_chunk: &[u8])

Update the verifier with the next chunk of data. This can be called multiple times.

fn verify_final(self, sig: &[u8]) -> Result<(), SignatureError>

On success, returns Ok(()) On failure, returns Err(SignatureError::SignatureVerificationFailed); may also return other types of SignatureError as appropriate (such as for invalid-length inputs).