Skip to main content

hyprstream_crypto/
pq.rs

1//! Post-quantum hybrid cryptographic primitives (ML-DSA-65 + ML-KEM-768).
2//!
3//! Always compiled (M3 #152). Whether these are USED is a runtime decision via
4//! `hyprstream_rpc::crypto::CryptoPolicy`, not a compile-time cargo feature. Provides:
5//! - ML-DSA-65 (FIPS 204) digital signatures
6//! - ML-KEM-768 (FIPS 203) key encapsulation
7
8use anyhow::Result;
9use ml_dsa::{
10    EncodedVerifyingKey, Generate, KeyExport, Keypair, MlDsa65, SignatureEncoding, Signer, Verifier,
11};
12use ml_kem::{
13    kem::{Decapsulate, Encapsulate, Kem, TryKeyInit},
14    MlKem768,
15};
16
17// ── ML-DSA-65 type aliases ──────────────────────────────────────────────────
18
19pub type MlDsaSigningKey = ml_dsa::SigningKey<MlDsa65>;
20pub type MlDsaVerifyingKey = ml_dsa::VerifyingKey<MlDsa65>;
21pub type MlDsaSignature = ml_dsa::Signature<MlDsa65>;
22
23// ── ML-KEM-768 type aliases ─────────────────────────────────────────────────
24
25pub type MlKemDecapsKey = ml_kem::DecapsulationKey<MlKem768>;
26pub type MlKemEncapsKey = ml_kem::EncapsulationKey<MlKem768>;
27
28// ── ML-DSA-65 operations ────────────────────────────────────────────────────
29
30pub fn ml_dsa_generate_keypair() -> (MlDsaSigningKey, MlDsaVerifyingKey) {
31    let sk = MlDsaSigningKey::generate();
32    let vk = sk.verifying_key().clone();
33    (sk, vk)
34}
35
36pub fn ml_dsa_sign(key: &MlDsaSigningKey, message: &[u8]) -> Vec<u8> {
37    let sig = key.sign(message);
38    sig.to_vec()
39}
40
41pub fn ml_dsa_verify(key: &MlDsaVerifyingKey, message: &[u8], sig: &[u8]) -> Result<()> {
42    let signature = MlDsaSignature::try_from(sig)
43        .map_err(|_| anyhow::anyhow!("invalid ML-DSA-65 signature encoding"))?;
44    key.verify(message, &signature)
45        .map_err(|_| anyhow::anyhow!("ML-DSA-65 signature verification failed"))
46}
47
48pub fn ml_dsa_vk_bytes(key: &MlDsaVerifyingKey) -> Vec<u8> {
49    key.to_bytes().to_vec()
50}
51
52/// Derive the raw ML-DSA-65 verifying-key bytes (1952 bytes) from a signing key.
53///
54/// Convenience for callers outside this crate that hold a signing key but do not
55/// depend on the `ml_dsa` crate's `Keypair` trait directly.
56pub fn ml_dsa_sk_to_vk_bytes(key: &MlDsaSigningKey) -> Vec<u8> {
57    ml_dsa_vk_bytes(&key.verifying_key())
58}
59
60/// Derive the ML-DSA-65 verifying key from a signing key.
61///
62/// Convenience for callers outside this crate that hold a signing key but do
63/// not depend on the `ml_dsa` crate's `Keypair` trait directly.
64pub fn ml_dsa_sk_to_vk(key: &MlDsaSigningKey) -> MlDsaVerifyingKey {
65    key.verifying_key().clone()
66}
67
68pub fn ml_dsa_vk_from_bytes(bytes: &[u8]) -> Result<MlDsaVerifyingKey> {
69    let encoded = EncodedVerifyingKey::<MlDsa65>::try_from(bytes).map_err(|_| {
70        anyhow::anyhow!("invalid ML-DSA-65 verifying key length (expected 1952 bytes)")
71    })?;
72    Ok(MlDsaVerifyingKey::decode(&encoded))
73}
74
75/// Serialize an ML-DSA-65 signing key to its 32-byte seed.
76pub fn ml_dsa_sk_to_seed(key: &MlDsaSigningKey) -> [u8; 32] {
77    let seed = key.to_seed();
78    let mut out = [0u8; 32];
79    out.copy_from_slice(seed.as_slice());
80    out
81}
82
83/// Reconstruct an ML-DSA-65 signing key from its 32-byte seed.
84pub fn ml_dsa_sk_from_seed(seed: &[u8; 32]) -> MlDsaSigningKey {
85    let arr = ml_dsa::B32::from(*seed);
86    MlDsaSigningKey::from_seed(&arr)
87}
88
89// ── ML-KEM-768 operations ───────────────────────────────────────────────────
90
91pub fn ml_kem_generate_keypair() -> (MlKemDecapsKey, MlKemEncapsKey) {
92    MlKem768::generate_keypair()
93}
94
95/// Encapsulate a shared secret. Returns `(ciphertext, shared_secret)`.
96pub fn ml_kem_encapsulate(ek: &MlKemEncapsKey) -> (Vec<u8>, [u8; 32]) {
97    let (ct, ss): (
98        ml_kem::Ciphertext<MlKem768>,
99        ml_kem::kem::SharedKey<MlKem768>,
100    ) = ek.encapsulate();
101    let mut shared = [0u8; 32];
102    shared.copy_from_slice(ss.as_slice());
103    (ct.as_slice().to_vec(), shared)
104}
105
106pub fn ml_kem_decapsulate(dk: &MlKemDecapsKey, ct: &[u8]) -> Result<[u8; 32]> {
107    let ss = dk.decapsulate_slice(ct).map_err(|_| {
108        anyhow::anyhow!("invalid ML-KEM-768 ciphertext length (expected 1088 bytes)")
109    })?;
110    let mut shared = [0u8; 32];
111    shared.copy_from_slice(ss.as_slice());
112    Ok(shared)
113}
114
115pub fn ml_kem_ek_bytes(key: &MlKemEncapsKey) -> Vec<u8> {
116    ml_kem::kem::KeyExport::to_bytes(key).to_vec()
117}
118
119/// Reconstruct an ML-KEM-768 decapsulation key from its 64-byte FIPS 203 seed
120/// (`d ‖ z`). Deterministic — the matching encapsulation key is recovered via
121/// [`MlKemDecapsKey::encapsulation_key`]. This 64-byte seed is the canonical byte
122/// form used by the hybrid-KEM component (#551) and by `#mesh-kem` key derivation
123/// (#552), mirroring [`ml_dsa_sk_from_seed`].
124pub fn ml_kem_decaps_from_seed(seed: &[u8; 64]) -> MlKemDecapsKey {
125    let s = ml_kem::Seed::from(*seed);
126    MlKemDecapsKey::from_seed(s)
127}
128
129/// Serialize an ML-KEM-768 decapsulation key to its 64-byte seed.
130///
131/// Returns `None` only if the key was built from the (deprecated) expanded form
132/// rather than a seed; keys from [`ml_kem_generate_keypair`] or
133/// [`ml_kem_decaps_from_seed`] are always seed-backed.
134pub fn ml_kem_dk_to_seed(dk: &MlKemDecapsKey) -> Option<[u8; 64]> {
135    dk.to_seed().map(|s| {
136        let mut out = [0u8; 64];
137        out.copy_from_slice(s.as_ref());
138        out
139    })
140}
141
142/// The encapsulation-key bytes (1184 B) corresponding to a decapsulation key.
143pub fn ml_kem_ek_of_dk(dk: &MlKemDecapsKey) -> Vec<u8> {
144    ml_kem_ek_bytes(dk.encapsulation_key())
145}
146
147pub fn ml_kem_ek_from_bytes(bytes: &[u8]) -> Result<MlKemEncapsKey> {
148    let key_array = ml_kem::kem::Key::<MlKemEncapsKey>::try_from(bytes).map_err(|_| {
149        anyhow::anyhow!("invalid ML-KEM-768 encapsulation key length (expected 1184 bytes)")
150    })?;
151    <MlKemEncapsKey as TryKeyInit>::new(&key_array)
152        .map_err(|_| anyhow::anyhow!("invalid ML-KEM-768 encapsulation key"))
153}
154
155#[cfg(test)]
156#[allow(clippy::unwrap_used, clippy::expect_used)]
157mod tests {
158    use super::*;
159
160    #[test]
161    fn ml_dsa_sign_verify_roundtrip() {
162        let (sk, vk) = ml_dsa_generate_keypair();
163        let msg = b"hyprstream post-quantum test";
164        let sig = ml_dsa_sign(&sk, msg);
165        assert_eq!(sig.len(), 3309);
166        ml_dsa_verify(&vk, msg, &sig).unwrap();
167    }
168
169    #[test]
170    fn ml_dsa_wrong_key_rejects() {
171        let (sk, _vk) = ml_dsa_generate_keypair();
172        let (_sk2, vk2) = ml_dsa_generate_keypair();
173        let msg = b"signed by key 1";
174        let sig = ml_dsa_sign(&sk, msg);
175        assert!(ml_dsa_verify(&vk2, msg, &sig).is_err());
176    }
177
178    #[test]
179    fn ml_dsa_tampered_sig_rejects() {
180        let (sk, vk) = ml_dsa_generate_keypair();
181        let msg = b"original message";
182        let sig = ml_dsa_sign(&sk, msg);
183        assert!(ml_dsa_verify(&vk, b"tampered message", &sig).is_err());
184    }
185
186    #[test]
187    fn ml_dsa_vk_serialization_roundtrip() {
188        let (_sk, vk) = ml_dsa_generate_keypair();
189        let bytes = ml_dsa_vk_bytes(&vk);
190        assert_eq!(bytes.len(), 1952);
191        let vk2 = ml_dsa_vk_from_bytes(&bytes).unwrap();
192        assert_eq!(ml_dsa_vk_bytes(&vk2), bytes);
193    }
194
195    #[test]
196    fn ml_dsa_seed_roundtrip() {
197        let (sk, vk) = ml_dsa_generate_keypair();
198        let seed = ml_dsa_sk_to_seed(&sk);
199        assert_eq!(seed.len(), 32);
200        let sk2 = ml_dsa_sk_from_seed(&seed);
201        let vk2 = sk2.verifying_key().clone();
202        assert_eq!(ml_dsa_vk_bytes(&vk), ml_dsa_vk_bytes(&vk2));
203        // Sign with restored key, verify with original vk
204        let msg = b"seed roundtrip test";
205        let sig = ml_dsa_sign(&sk2, msg);
206        ml_dsa_verify(&vk, msg, &sig).unwrap();
207    }
208
209    #[test]
210    fn ml_kem_encapsulate_decapsulate_roundtrip() {
211        let (dk, ek) = ml_kem_generate_keypair();
212        let (ct, k_send) = ml_kem_encapsulate(&ek);
213        assert_eq!(ct.len(), 1088);
214        let k_recv = ml_kem_decapsulate(&dk, &ct).unwrap();
215        assert_eq!(k_send, k_recv);
216    }
217
218    #[test]
219    fn ml_kem_wrong_key_rejects() {
220        let (_dk, ek) = ml_kem_generate_keypair();
221        let (dk2, _ek2) = ml_kem_generate_keypair();
222        let (ct, k_send) = ml_kem_encapsulate(&ek);
223        // ML-KEM decapsulate always succeeds but produces a different shared secret
224        let k_recv = ml_kem_decapsulate(&dk2, &ct).unwrap();
225        assert_ne!(k_send, k_recv);
226    }
227
228    #[test]
229    fn ml_kem_ek_serialization_roundtrip() {
230        let (_dk, ek) = ml_kem_generate_keypair();
231        let bytes = ml_kem_ek_bytes(&ek);
232        assert_eq!(bytes.len(), 1184);
233        let ek2 = ml_kem_ek_from_bytes(&bytes).unwrap();
234        assert_eq!(ml_kem_ek_bytes(&ek2), bytes);
235    }
236}