Struct HashMLDSA 

pub struct HashMLDSA<HASH: Hash + AlgorithmOID + Default, const HASH_LEN: usize, 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_MINUS_BETA: i32, const GAMMA2_MINUS_BETA: i32, const GAMMA1_MASK_LEN: usize> { /* private fields */ }

An instance of the HashML-DSA algorithm.

The code is exposing the HashMLDSA struct this way so that alternative hash functions can be used without requiring modification of this source code; the user can add their own hash function by specifying the hash function to use (in the verifier), and specifying the bytes of the OID to to use as its domain separator in constructing the message representative M’.

Implementations

impl<HASH: Hash + AlgorithmOID + Default, const PH_LEN: usize, 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> HashMLDSA<HASH, PH_LEN, 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_MINUS_BETA, GAMMA2_MINUS_BETA, GAMMA1_MASK_LEN>

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

Generate a keypair, sourcing randomness from bouncycastle’s default os-backed RNG.

Key generation is intentionally not part of the Signer / SignatureVerifier traits; it is provided as an inherent associated function directly on the algorithm struct. Keygen, and keys in general, are interchangeable between MLDSA and HashMLDSA. Error condition: basically only on RNG failures.

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

Imports a secret key from a seed.

pub 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 Signer::sign, but signs from an MLDSAPrivateKeyExpanded.

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

Same as Signer::sign_out, but signs from an MLDSAPrivateKeyExpanded.

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

Same as PHSigner::sign_ph, but signs from an MLDSAPrivateKeyExpanded.

pub fn sign_ph_with_expanded_key_out( sk: &MLDSAPrivateKeyExpanded<k, l, ETA, PK, SK, SK_LEN, PK_LEN>, ph: &[u8; PH_LEN], ctx: Option<&[u8]>, output: &mut [u8; SIG_LEN], ) -> Result<usize, SignatureError>

Same as PHSigner::sign_ph_out, but signs from an MLDSAPrivateKeyExpanded.

pub fn sign_ph_deterministic( sk: &SK, A_hat: Option<&Matrix<k, l>>, ctx: Option<&[u8]>, ph: &[u8; PH_LEN], rnd: [u8; 32], ) -> Result<[u8; SIG_LEN], SignatureError>

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

Security note: This mode exposes deterministic signing (called “hedged mode” and allowed by FIPS 204). The ML-DSA algorithm is considered safe to use in deterministic mode. However, the user must be aware that is their responsibility to ensure that their nonce rnd is unique per signature. If otherwise, some privacy properties may be lost; for example it becomes easy to tell if a signer has signed the same message twice or two different messages, or to tell if the same message has been signed by the same signer twice or two different signers.

Since rnd should be either a per-signature nonce, or a fixed value, therefore, to help prevent accidental nonce reuse, this function moves rnd.

pub fn sign_ph_deterministic_out( sk: &SK, A_hat: Option<&Matrix<k, l>>, ctx: Option<&[u8]>, ph: &[u8; PH_LEN], rnd: [u8; 32], output: &mut [u8; SIG_LEN], ) -> Result<usize, SignatureError>

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

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 exposes deterministic signing (called “hedged mode” in FIPS 204) using an internal RNG.

Since rnd should be either a per-signature nonce, or a fixed value, therefore, to help prevent accidental nonce reuse, this function moves rnd.

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

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

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

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

Alternative initialization of the streaming signer where the user provides their private key as a seed and they want to delay its expansion as late as possible to optimize memory-usage.

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

Same as SignatureVerifier::verify, but verifies from an MLDSAPublicKeyExpanded.

Trait Implementations

impl<HASH: Hash + AlgorithmOID + Default, const PH_LEN: usize, 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> PHSignatureVerifier<PK, PK_LEN, SIG_LEN, PH_LEN> for HashMLDSA<HASH, PH_LEN, 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_MINUS_BETA, GAMMA2_MINUS_BETA, GAMMA1_MASK_LEN>

fn verify_ph( pk: &PK, ph: &[u8; PH_LEN], 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).

impl<HASH: Hash + AlgorithmOID + Default, const PH_LEN: usize, 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> PHSigner<PK, SK, PK_LEN, SK_LEN, SIG_LEN, PH_LEN> for HashMLDSA<HASH, PH_LEN, 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_MINUS_BETA, GAMMA2_MINUS_BETA, GAMMA1_MASK_LEN>

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

Note that the PH expected here is not the same as the mu computed by MuBuilder. To make use of this function, the user needs to compute a straight hash of the message using the same hash function as the indicated in the HashML-DSA variant; for example: SHA256 for HashMDSA44_with_SHA256; SHA512 for HashMLDSA65_with_SHA512; etc.

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

Produce a signature for the provided pre-hashed message and context.

impl<HASH: Hash + AlgorithmOID + Default, 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 PH_LEN: usize, const PK_LEN: usize, const SK_LEN: usize, const SIG_LEN: usize, 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_MINUS_BETA: i32, const GAMMA2_MINUS_BETA: i32, const GAMMA1_MASK_LEN: usize> SignatureVerifier<PK, PK_LEN, SIG_LEN> for HashMLDSA<HASH, PH_LEN, 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_MINUS_BETA, GAMMA2_MINUS_BETA, GAMMA1_MASK_LEN>

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>

streaming verification API

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).

impl<HASH: Hash + AlgorithmOID + Default, 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 PH_LEN: usize, const PK_LEN: usize, const SK_LEN: usize, const SIG_LEN: usize, 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_MINUS_BETA: i32, const GAMMA2_MINUS_BETA: i32, const GAMMA1_MASK_LEN: usize> Signer<SK, SK_LEN, SIG_LEN> for HashMLDSA<HASH, PH_LEN, 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_MINUS_BETA, GAMMA2_MINUS_BETA, GAMMA1_MASK_LEN>

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

Algorithm 4 HashML-DSA.Sign(𝑠𝑘, 𝑀 , 𝑐𝑡𝑥, PH) Generate a “pre-hash” ML-DSA signature.

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. The entire output buffer is zeroized before the signature is written.

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. The entire output buffer is zeroized before the signature is written.