feat: implement kem trait for sntrup

.github/workflows/sntrup-kem.yml

@@ -53,6 +53,7 @@ jobs:
       - run: cargo test --no-default-features
       - run: cargo test
       - run: cargo test --all-features
+      - run: cargo test --features kem
       - run: cargo test --features serde,force-scalar
 
   cross:

sntrup-kem/Cargo.toml

@@ -11,6 +11,9 @@ categories = ["algorithms", "cryptography"]
 readme = "README.md"
 edition = "2024"
 
+[package.metadata.docs.rs]
+features = ["kem", "serde"]
+
 [features]
 default = ["kgen", "ecap", "dcap"]
 kgen = []
@@ -19,6 +22,7 @@ dcap = []
 alloc = []
 force-scalar = []
 std = []
+kem = ["dep:hybrid-array", "dep:kem", "dep:rand_core", "kgen", "ecap", "dcap"]
 serde = ["dep:serdect", "dep:serde"]
 js = ["getrandom/wasm_js"]
 
@@ -28,6 +32,9 @@ rand = "0.10.0"
 rand_chacha = "0.10.0"
 subtle = "2"
 getrandom = { version = "0.4", optional = true }
+hybrid-array = { version = "0.4.14", features = ["extra-sizes"], optional = true }
+kem = { version = "0.3", optional = true }
+rand_core = { version = "0.10", optional = true }
 serde = { version = "1", optional = true, default-features = false }
 serdect = { version = "0.4", optional = true }
 # sha2 0.11 dropped the `asm` feature; hardware SHA acceleration is now selected
@@ -40,6 +47,10 @@ zeroize = { version = "1", features = ["derive"] }
 criterion = "0.7"
 serde_json = "1"
 
+[[example]]
+name = "kem_traits"
+required-features = ["kem"]
+
 [[bench]]
 name = "mod"
 harness = false

sntrup-kem/README.md

@@ -48,6 +48,7 @@ The KEM API is split into three default features so downstream crates can pull i
 | `kgen`  | **yes** | Key generation: `SntrupKem::generate_key`, `SntrupKem::generate_key_deterministic` |
 | `ecap`  | **yes** | Encapsulation: `EncapsulationKey::encapsulate` |
 | `dcap`  | **yes** | Decapsulation: `DecapsulationKey::decapsulate` |
+| `kem`   | no | Implements the [`kem`](https://docs.rs/kem) crate traits for every parameter set |
 | `force-scalar` | no | Disable SIMD (AVX2/NEON) and use pure-Rust scalar code |
 | `serde` | no | Enables `Serialize`/`Deserialize` for all key and ciphertext types (via `serdect` for constant-time hex encoding) |
 | `js`    | no | Enables WebAssembly support for `wasm32-unknown-unknown` by configuring `getrandom` to use JavaScript's `crypto.getRandomValues()` |
@@ -175,6 +176,29 @@ let ek2 = EncapsulationKey::<Sntrup761Params>::try_from(ek_bytes).unwrap();
 assert_eq!(ek, ek2);
 ```
 
+### `kem` crate integration
+
+Enable the `kem` feature to use any parameter set through the generic
+[`kem`](https://docs.rs/kem) traits:
+
+```rust
+# #[cfg(feature = "kem")] {
+use rand::SeedableRng;
+use rand::rngs::{StdRng, SysRng};
+use sntrup_kem::kem::{Decapsulate, Encapsulate, Kem, Sntrup761Params};
+
+let Ok(mut rng) = StdRng::try_from_rng(&mut SysRng) else {
+    return;
+};
+let (dk, ek) = Sntrup761Params::generate_keypair_from_rng(&mut rng);
+let (ct, sent) = ek.encapsulate_with_rng(&mut rng);
+assert_eq!(dk.decapsulate(&ct), sent);
+# }
+```
+
+The module re-exports the traits and parameter-set marker types. See
+`examples/kem_traits.rs` for generic use and key import/export.
+
 ## WebAssembly
 
 To compile for `wasm32-unknown-unknown`, enable the `js` feature so that `getrandom` uses JavaScript's `crypto.getRandomValues()` for randomness:

sntrup-kem/examples/kem_traits.rs

@@ -0,0 +1,43 @@
+//! Streamlined NTRU Prime through the [`kem`](https://docs.rs/kem) crate traits.
+
+use rand::SeedableRng;
+use rand::rngs::{StdRng, SysRng};
+use rand_core::CryptoRng;
+use sntrup_kem::kem::{
+    Decapsulate, DecapsulationKey, Decapsulator, Encapsulate, EncapsulationKey, Generate, Kem,
+    KemSizes, KeyExport, Sntrup653Params, Sntrup761Params, Sntrup1277Params, TryKeyInit,
+};
+
+fn round_trip<K>(mut rng: impl CryptoRng) -> (usize, usize)
+where
+    K: KemSizes
+        + Kem<EncapsulationKey = EncapsulationKey<K>, DecapsulationKey = DecapsulationKey<K>>,
+{
+    let (dk, ek) = K::generate_keypair_from_rng(&mut rng);
+    let (ct, sent) = ek.encapsulate_with_rng(&mut rng);
+    let received = dk.decapsulate(&ct);
+    assert_eq!(sent, received);
+    (ct.len(), received.len())
+}
+
+fn main() {
+    let Ok(mut rng) = StdRng::try_from_rng(&mut SysRng) else {
+        return;
+    };
+
+    for (ct, ss) in [
+        round_trip::<Sntrup653Params>(&mut rng),
+        round_trip::<Sntrup761Params>(&mut rng),
+        round_trip::<Sntrup1277Params>(&mut rng),
+    ] {
+        assert!(ct > 0);
+        assert_eq!(ss, 32);
+    }
+
+    let dk = DecapsulationKey::<Sntrup761Params>::generate_from_rng(&mut rng);
+    let exported = dk.encapsulation_key().to_bytes();
+    let Ok(imported) = EncapsulationKey::<Sntrup761Params>::new(&exported) else {
+        return;
+    };
+    assert_eq!(&imported, dk.encapsulation_key());
+}