Crate ml_dsa 

RustCrypto: ML-DSA

Pure Rust implementation of the Module-Lattice-Based Digital Signature Standard (ML-DSA) as described in the FIPS 204 (final).

About

ML-DSA was formerly known as CRYSTALS-Dilithium.

⚠️ Security Warning

The implementation contained in this crate has never been independently audited!

USE AT YOUR OWN RISK!

License

All crates licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Usage

The following types provide the core functionality of this crate, and are all generic around the MlDsaParams trait which defines the security level and is one of MlDsa44, MlDsa65, or MlDsa87 (with MlDsa65 recommended as providing the best balance of security and performance):

• SigningKey: secret key capable of generating signatures. Implements the KeyInit, KeyExport, Keypair, and Signer traits, as well as Generate when the rand_core feature of this crate is enabled.
• VerifyingKey: public key associated with a given SigningKey. Implements the KeyInit, KeyExport, and Verifier traits.
• Signature: ML-DSA signature generated by a SigningKey, and verifiable by a VerifyingKey. Implements the SignatureEncoding trait.

// NOTE: requires the `getrandom` feature is enabled
use ml_dsa::{MlDsa65, Generate, Keypair, SigningKey, Signer, Verifier};

let sk = SigningKey::<MlDsa65>::generate();

let msg = b"Hello world";
let sig = sk.sign(msg);

sk.verifying_key().verify(msg, &sig)?;

Re-exports

pub use common;

pub use signature;

Modules

pkcs8pkcs8

PKCS#8 private key encoding support.

Structs

Error

Signature errors.

ExpandedSigningKey

An ML-DSA signing key

MlDsa44

MlDsa44 is the parameter set for security category 2, providing the equivalent of 128-bit symmetric security.

MlDsa65

MlDsa65 is the parameter set for security category 3, providing the equivalent of 192-bit symmetric security, and is the recommended parameter set.

MlDsa87

MlDsa87 is the parameter set for security category 5, providing the equivalent of 256-bit symmetric security.

Signature

An ML-DSA signature

SigningKey

ML-DSA signing key (i.e. private/secret key).

VerifyingKey

An ML-DSA verification key.

Traits

Generaterand_core

Secure random generation.

KeyExport

Serialize a key to a byte array.

KeyInit

Types which can be initialized from a key.

KeySizeUser

Types which use key for initialization.

Keypair

Signing keypair with an associated verifying key.

MlDsaParams

An instance of MlDsaParams defines all of the parameters necessary for ML-DSA operations. Typically this is done by implementing ParameterSet with values that will fit into the blanket implementations of SigningKeyParams, VerifyingKeyParams, and SignatureParams.

SignatureEncoding

Support for decoding/encoding signatures as bytes.

Signer

Sign the provided message bytestring using Self (e.g. a cryptographic key or connection to an HSM), returning a digital signature.

Verifier

Verify the provided message bytestring using Self (e.g. a public key).

Type Aliases

B32

A 32-byte array, defined here for brevity because it is used several times

EncodedSignature

A signature encoded as a byte array

EncodedVerifyingKey

A verifying key encoded as a byte array

ExpandedSigningKeyBytes

A signing key encoded as a byte array

Seed

ML-DSA seeds are signing (private) keys, which are consistently 32-bytes across all security levels, and are the preferred serialization for representing such keys.