dilithium/
lib.rs

1//! Pure Rust implementation of ML-DSA (FIPS 204) / CRYSTALS-Dilithium.
2//!
3//! A post-quantum digital signature scheme standardized as FIPS 204.
4//! Supports all three security levels: ML-DSA-44, ML-DSA-65, ML-DSA-87.
5//!
6//! # Features
7//!
8//! - **FIPS 204 compliant** — supports pure ML-DSA and HashML-DSA (pre-hash)
9//! - **`no_std` compatible** — works on embedded and WASM targets
10//! - **WASM ready** — all dependencies support `wasm32-unknown-unknown`
11//! - **Zeroize** — private key material is automatically zeroized on drop
12//! - **Constant-time** — verification uses constant-time comparison
13//! - **Optional serde** — enable the `serde` feature for serialization
14//!
15//! # Quick Start
16//!
17//! ```rust
18//! use dilithium::{MlDsaKeyPair, ML_DSA_44};
19//!
20//! let kp = MlDsaKeyPair::generate(ML_DSA_44).unwrap();
21//! let sig = kp.sign(b"Hello, post-quantum world!", b"").unwrap();
22//! assert!(MlDsaKeyPair::verify(
23//!     kp.public_key(), &sig, b"Hello, post-quantum world!", b"",
24//!     ML_DSA_44
25//! ));
26//! ```
27
28#![cfg_attr(not(feature = "std"), no_std)]
29// Crypto-specific clippy allows:
30// - unreadable_literal: NTT zetas table ported verbatim from C reference
31// - cast_possible_truncation/sign_loss/wrap: intentional in bit-packing (poly.rs, packing.rs)
32// - cast_lossless: i32→i64 / u8→i32 casts are clearer as `as` in arithmetic
33// - many_single_char_names: math variable names (e, r, t, w, z) from the FIPS spec
34// - wildcard_imports: used for re-exporting poly/polyvec helpers
35// - identity_op: shifts by 0 are from the C reference for clarity
36// - too_many_arguments: pack_sk/unpack_sk mirror the C API
37// - module_name_repetitions: DilithiumMode etc. are the standard naming
38#![allow(
39    clippy::unreadable_literal,
40    clippy::cast_possible_truncation,
41    clippy::cast_sign_loss,
42    clippy::cast_possible_wrap,
43    clippy::cast_lossless,
44    clippy::many_single_char_names,
45    clippy::wildcard_imports,
46    clippy::identity_op,
47    clippy::too_many_arguments,
48    clippy::module_name_repetitions,
49    clippy::similar_names,
50    clippy::items_after_statements,
51    clippy::match_same_arms,
52    clippy::needless_range_loop,
53    clippy::missing_errors_doc,
54    clippy::missing_panics_doc
55)]
56
57extern crate alloc;
58
59// ── Internal modules (accessible but not in public docs) ────────
60#[doc(hidden)]
61pub mod ntt;
62#[doc(hidden)]
63pub mod packing;
64pub mod params;
65#[doc(hidden)]
66pub mod poly;
67#[doc(hidden)]
68pub mod polyvec;
69#[doc(hidden)]
70pub mod reduce;
71#[doc(hidden)]
72pub mod rounding;
73pub mod safe_api;
74#[doc(hidden)]
75pub mod sign;
76#[doc(hidden)]
77pub mod symmetric;
78
79// ── Public re-exports (the SDK surface) ─────────────────────────
80pub use params::DilithiumMode;
81pub use params::{ML_DSA_44, ML_DSA_65, ML_DSA_87};
82pub use safe_api::{DilithiumError, DilithiumKeyPair, DilithiumSignature};
83
84/// FIPS 204 type alias for `DilithiumKeyPair`.
85pub use safe_api::MlDsaKeyPair;
86/// FIPS 204 type alias for `DilithiumSignature`.
87pub use safe_api::MlDsaSignature;
88
dilithium/lib.rs

dilithium/
lib.rs
