ml-kem: define parameter set modules (#162)

Defines the following modules:

- `ml_kem_512`
- `ml_kem_768`
- `ml_kem_1024`

Each contains the `ParameterSet` definition for the given security level
(re-exported at the toplevel) along with type aliases for
`DecapsulationKey` and `EncapsulationKey`.

The documentation has been updated to use such a type alias for
`DecapsulationKey` as originally proposed in #161

Author: tarcieri

ml-kem/src/kem.rs

@@ -14,7 +14,7 @@ use crate::{Encoded, EncodedSizeUser, Seed};
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
 // Re-export traits from the `kem` crate
-pub use ::kem::{Decapsulate, Encapsulate};
+pub use ::kem::{Decapsulate, Encapsulate, KeyInit, KeySizeUser};
 
 /// A shared key resulting from an ML-KEM transaction
 pub(crate) type SharedKey = B32;

ml-kem/src/lib.rs

@@ -21,12 +21,16 @@
 //! computers.
 //!
 //! ```
-//! # use ml_kem::*;
-//! # use ::kem::{Decapsulate, Encapsulate};
-//! let mut rng = rand::rng();
+//! use ml_kem::{
+//!     ml_kem_768::DecapsulationKey,
+//!     kem::{Decapsulate, Encapsulate, KeyInit}
+//! };
 //!
-//! // Generate a (decapsulation key, encapsulation key) pair
-//! let (dk, ek) = MlKem768::generate(&mut rng);
+//! // Generate a decapsulation/encapsulation keypair
+//! let mut rng = rand::rng();
+//! let seed = DecapsulationKey::generate_key_with_rng(&mut rng);
+//! let dk = DecapsulationKey::new(&seed);
+//! let ek = dk.encapsulator();
 //!
 //! // Encapsulate a shared key to the holder of the decapsulation key, receive the shared
 //! // secret `k_send` and the encapsulated form `ct`.
@@ -81,50 +85,95 @@ pub use hybrid_array as array;
 #[cfg(feature = "deterministic")]
 pub use util::B32;
 
+pub use ml_kem_512::MlKem512Params;
+pub use ml_kem_768::MlKem768Params;
+pub use ml_kem_1024::MlKem1024Params;
 pub use param::{ArraySize, ParameterSet};
 pub use traits::*;
 
 /// ML-KEM seeds are decapsulation (private) keys, which are consistently 64-bytes across all
 /// security levels, and are the preferred serialization for representing such keys.
 pub type Seed = Array<u8, U64>;
 
-/// `MlKem512` is the parameter set for security category 1, corresponding to key search on a block
+/// ML-KEM-512 is the parameter set for security category 1, corresponding to key search on a block
 /// cipher with a 128-bit key.
-#[derive(Default, Clone, Debug, PartialEq)]
-pub struct MlKem512Params;
-
-impl ParameterSet for MlKem512Params {
-    type K = U2;
-    type Eta1 = U3;
-    type Eta2 = U2;
-    type Du = U10;
-    type Dv = U4;
+pub mod ml_kem_512 {
+    use super::{Debug, ParameterSet, U2, U3, U4, U10, kem};
+
+    /// `MlKem512` is the parameter set for security category 1, corresponding to key search on a
+    /// block cipher with a 128-bit key.
+    #[derive(Default, Clone, Debug, PartialEq)]
+    pub struct MlKem512Params;
+
+    impl ParameterSet for MlKem512Params {
+        type K = U2;
+        type Eta1 = U3;
+        type Eta2 = U2;
+        type Du = U10;
+        type Dv = U4;
+    }
+
+    /// An ML-KEM-512 `DecapsulationKey` which provides the ability to generate a new key pair, and
+    /// decapsulate an encapsulated shared key.
+    pub type DecapsulationKey = kem::DecapsulationKey<MlKem512Params>;
+
+    /// An ML-KEM-512 `EncapsulationKey` provides the ability to encapsulate a shared key so that it
+    /// can only be decapsulated by the holder of the corresponding decapsulation key.
+    pub type EncapsulationKey = kem::EncapsulationKey<MlKem512Params>;
 }
 
-/// `MlKem768` is the parameter set for security category 3, corresponding to key search on a block
+/// ML-KEM-768 is the parameter set for security category 3, corresponding to key search on a block
 /// cipher with a 192-bit key.
-#[derive(Default, Clone, Debug, PartialEq)]
-pub struct MlKem768Params;
-
-impl ParameterSet for MlKem768Params {
-    type K = U3;
-    type Eta1 = U2;
-    type Eta2 = U2;
-    type Du = U10;
-    type Dv = U4;
+pub mod ml_kem_768 {
+    use super::{Debug, ParameterSet, U2, U3, U4, U10, kem};
+
+    /// `MlKem768` is the parameter set for security category 3, corresponding to key search on a
+    /// block cipher with a 192-bit key.
+    #[derive(Default, Clone, Debug, PartialEq)]
+    pub struct MlKem768Params;
+
+    impl ParameterSet for MlKem768Params {
+        type K = U3;
+        type Eta1 = U2;
+        type Eta2 = U2;
+        type Du = U10;
+        type Dv = U4;
+    }
+
+    /// An ML-KEM-768 `DecapsulationKey` which provides the ability to generate a new key pair, and
+    /// decapsulate an encapsulated shared key.
+    pub type DecapsulationKey = kem::DecapsulationKey<MlKem768Params>;
+
+    /// An ML-KEM-768 `EncapsulationKey` provides the ability to encapsulate a shared key so that it
+    /// can only be decapsulated by the holder of the corresponding decapsulation key.
+    pub type EncapsulationKey = kem::EncapsulationKey<MlKem768Params>;
 }
 
-/// `MlKem1024` is the parameter set for security category 5, corresponding to key search on a block
+/// ML-KEM-1024 is the parameter set for security category 5, corresponding to key search on a block
 /// cipher with a 256-bit key.
-#[derive(Default, Clone, Debug, PartialEq)]
-pub struct MlKem1024Params;
-
-impl ParameterSet for MlKem1024Params {
-    type K = U4;
-    type Eta1 = U2;
-    type Eta2 = U2;
-    type Du = U11;
-    type Dv = U5;
+pub mod ml_kem_1024 {
+    use super::{Debug, ParameterSet, U2, U4, U5, U11, kem};
+
+    /// `MlKem1024` is the parameter set for security category 5, corresponding to key search on a
+    /// block cipher with a 256-bit key.
+    #[derive(Default, Clone, Debug, PartialEq)]
+    pub struct MlKem1024Params;
+
+    impl ParameterSet for MlKem1024Params {
+        type K = U4;
+        type Eta1 = U2;
+        type Eta2 = U2;
+        type Du = U11;
+        type Dv = U5;
+    }
+
+    /// An ML-KEM-1024 `DecapsulationKey` which provides the ability to generate a new key pair, and
+    /// decapsulate an encapsulated shared key.
+    pub type DecapsulationKey = kem::DecapsulationKey<MlKem1024Params>;
+
+    /// An ML-KEM-1024 `EncapsulationKey` provides the ability to encapsulate a shared key so that
+    /// it can only be decapsulated by the holder of the corresponding decapsulation key.
+    pub type EncapsulationKey = kem::EncapsulationKey<MlKem1024Params>;
 }
 
 /// A shared key produced by the KEM `K`