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** — enable the `js` feature for browser environments
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//! - **SIMD acceleration** — AVX2 (x86_64) and NEON (AArch64) NTT behind `simd`
15//!
16//! # Feature Flags
17//!
18//! | Feature | Default | Description |
19//! |---------|---------|-------------|
20//! | `std`   | ✅      | Enables `getrandom` for OS entropy (`generate`, `sign`, `sign_prehash`) |
21//! | `serde` | ❌      | Enables `Serialize`/`Deserialize` for key pairs, signatures, and modes |
22//! | `simd`  | ❌      | Enables AVX2 (x86_64) and NEON (AArch64) NTT acceleration |
23//! | `js`    | ❌      | Enables `getrandom/js` for WASM browser targets |
24//!
25//! # Platform Support
26//!
27//! | Target | Build | Notes |
28//! |--------|-------|-------|
29//! | x86_64 Linux/macOS | ✅ | Full support, AVX2 SIMD optional |
30//! | AArch64 (Apple Silicon, ARM) | ✅ | Full support, NEON SIMD optional |
31//! | `wasm32-unknown-unknown` | ✅ | Requires `--no-default-features`, add `js` for entropy |
32//! | `thumbv7em-none-eabihf` | ✅ | Requires `--no-default-features`, deterministic APIs only |
33//!
34//! # Quick Start
35//!
36//! ```rust
37//! use dilithium::{MlDsaKeyPair, ML_DSA_44};
38//!
39//! let kp = MlDsaKeyPair::generate(ML_DSA_44).unwrap();
40//! let sig = kp.sign(b"Hello, post-quantum world!", b"").unwrap();
41//! assert!(MlDsaKeyPair::verify(
42//!     kp.public_key(), &sig, b"Hello, post-quantum world!", b"",
43//!     ML_DSA_44
44//! ));
45//! ```
46
47#![cfg_attr(not(feature = "std"), no_std)]
48// Crypto-specific clippy allows:
49// - unreadable_literal: NTT zetas table ported verbatim from C reference
50// - cast_possible_truncation/sign_loss/wrap: intentional in bit-packing (poly.rs, packing.rs)
51// - cast_lossless: i32→i64 / u8→i32 casts are clearer as `as` in arithmetic
52// - many_single_char_names: math variable names (e, r, t, w, z) from the FIPS spec
53// - wildcard_imports: used for re-exporting poly/polyvec helpers
54// - identity_op: shifts by 0 are from the C reference for clarity
55// - too_many_arguments: pack_sk/unpack_sk mirror the C API
56// - module_name_repetitions: DilithiumMode etc. are the standard naming
57#![allow(
58    clippy::unreadable_literal,
59    clippy::cast_possible_truncation,
60    clippy::cast_sign_loss,
61    clippy::cast_possible_wrap,
62    clippy::cast_lossless,
63    clippy::many_single_char_names,
64    clippy::wildcard_imports,
65    clippy::identity_op,
66    clippy::too_many_arguments,
67    clippy::module_name_repetitions,
68    clippy::similar_names,
69    clippy::items_after_statements,
70    clippy::match_same_arms,
71    clippy::needless_range_loop,
72    clippy::missing_errors_doc,
73    clippy::missing_panics_doc
74)]
75
76extern crate alloc;
77
78// ── Internal modules (accessible but not in public docs) ────────
79#[doc(hidden)]
80pub mod ntt;
81#[doc(hidden)]
82pub mod packing;
83pub mod params;
84#[doc(hidden)]
85pub mod poly;
86#[doc(hidden)]
87pub mod polyvec;
88#[doc(hidden)]
89pub mod reduce;
90#[doc(hidden)]
91pub mod rounding;
92pub mod safe_api;
93#[doc(hidden)]
94pub mod sign;
95#[doc(hidden)]
96pub mod symmetric;
97#[cfg(feature = "simd")]
98pub mod ntt_avx2;
99#[cfg(feature = "simd")]
100pub mod ntt_neon;
101
102// ── Public re-exports (the SDK surface) ─────────────────────────
103pub use params::DilithiumMode;
104pub use params::{ML_DSA_44, ML_DSA_65, ML_DSA_87};
105pub use safe_api::{DilithiumError, DilithiumKeyPair, DilithiumSignature};
106
107/// FIPS 204 type alias for `DilithiumKeyPair`.
108pub use safe_api::MlDsaKeyPair;
109/// FIPS 204 type alias for `DilithiumSignature`.
110pub use safe_api::MlDsaSignature;
111
dilithium/lib.rs

dilithium/
lib.rs
