Skip to main content

qualia_core_db/net/qdnf/crypto/handshake/
shares.rs

1//! Share-exchange: initiator ML-KEM public + X25519, responder ciphertext + X25519.
2
3#[cfg(not(target_arch = "wasm32"))]
4pub(crate) mod leased;
5
6use crate::crypto::network::errors::CryptoError;
7use crate::crypto::network::kem::{encapsulate, MlKem768Secret};
8use crate::crypto::network::malformed::{reject_all_zero_dh, reject_malformed_kem_ct};
9use crate::crypto::network::types::{ML_KEM_768_CT_LEN, ML_KEM_768_PK_LEN, X25519_LEN};
10use crate::crypto::network::x25519::X25519Secret;
11
12use super::identity::reject_reflected_share;
13
14#[repr(u8)]
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16pub enum HandshakeState {
17    Idle = 0,
18    Reachability = 1,
19    SharesExchanged = 2,
20    HandshakeKeys = 3,
21    Proofs = 4,
22    Finished = 5,
23    Traffic = 6,
24}
25
26pub const FORBIDDEN_ZERO_RTT: bool = true;
27
28#[repr(C)]
29#[derive(Clone, Copy)]
30pub struct InitiatorShare {
31    pub ml_kem_pk: [u8; ML_KEM_768_PK_LEN],
32    pub x25519_pk: [u8; X25519_LEN],
33}
34
35#[repr(C)]
36#[derive(Clone, Copy)]
37pub struct ResponderShare {
38    pub ml_kem_ct: [u8; ML_KEM_768_CT_LEN],
39    pub x25519_pk: [u8; X25519_LEN],
40}
41
42fn reject_zero(ss: &[u8; 32]) -> Result<(), CryptoError> {
43    if ss.iter().all(|b| *b == 0) {
44        Err(CryptoError::CryptoFailure)
45    } else {
46        Ok(())
47    }
48}
49
50/// Fail-closed checks on the complete path: all-zero peer DH public, KEM
51/// ciphertext length, and reflected X25519 publics.
52fn reject_complete_failures(
53    local_pk: &[u8; 32],
54    peer_pk: &[u8; 32],
55    kem_ct_len: usize,
56) -> Result<(), CryptoError> {
57    reject_all_zero_dh(peer_pk)?;
58    reject_malformed_kem_ct(kem_ct_len)?;
59    reject_reflected_share(local_pk, peer_pk)?;
60    Ok(())
61}
62
63/// Initiator sends its handshake share.
64pub fn initiator_share(
65    x25519_secret: &[u8; 32],
66    ml_kem_pk: &[u8; ML_KEM_768_PK_LEN],
67) -> Result<InitiatorShare, CryptoError> {
68    reject_zero(x25519_secret)?;
69    let x25519_pk = X25519Secret::from_bytes(*x25519_secret).public();
70    reject_all_zero_dh(&x25519_pk)?;
71    Ok(InitiatorShare {
72        ml_kem_pk: *ml_kem_pk,
73        x25519_pk,
74    })
75}
76
77/// Responder consumes the initiator share, producing its reply.
78pub fn responder_complete(
79    initiator: &InitiatorShare,
80    x25519_secret: &[u8; 32],
81) -> Result<(ResponderShare, [u8; 32], [u8; 32]), CryptoError> {
82    reject_zero(x25519_secret)?;
83    let local_pk = X25519Secret::from_bytes(*x25519_secret).public();
84    reject_complete_failures(&local_pk, &initiator.x25519_pk, ML_KEM_768_CT_LEN)?;
85    let (kem_ss, ct) = encapsulate(&initiator.ml_kem_pk)?;
86    reject_malformed_kem_ct(ct.len())?;
87    reject_zero(&kem_ss)?;
88    let x_ss = X25519Secret::from_bytes(*x25519_secret).diffie_hellman(&initiator.x25519_pk)?;
89    reject_zero(&x_ss)?;
90    let share = ResponderShare {
91        ml_kem_ct: ct,
92        x25519_pk: local_pk,
93    };
94    Ok((share, kem_ss, x_ss))
95}
96
97/// Initiator consumes the reply, completing the handshake.
98pub fn initiator_complete(
99    ml_kem_sk: &MlKem768Secret,
100    x25519_secret: &[u8; 32],
101    responder: &ResponderShare,
102) -> Result<([u8; 32], [u8; 32]), CryptoError> {
103    reject_zero(x25519_secret)?;
104    let local_pk = X25519Secret::from_bytes(*x25519_secret).public();
105    reject_complete_failures(&local_pk, &responder.x25519_pk, responder.ml_kem_ct.len())?;
106    let kem_ss = ml_kem_sk.decapsulate(&responder.ml_kem_ct)?;
107    reject_zero(&kem_ss)?;
108    let x_ss = X25519Secret::from_bytes(*x25519_secret).diffie_hellman(&responder.x25519_pk)?;
109    reject_zero(&x_ss)?;
110    Ok((kem_ss, x_ss))
111}
112
113#[cfg(test)]
114mod tests {
115    use super::*;
116    use crate::crypto::network::kem::MlKem768Secret;
117    use crate::crypto::network::transcript::Transcript;
118    use crate::net::qdnf::crypto::handshake::{derive_handshake_keys, HandshakeKeys};
119
120    #[test]
121    fn hybrid_handshake_agrees() {
122        let (sk, pk) = MlKem768Secret::generate().unwrap();
123        let i_x = [11u8; 32];
124        let r_x = [12u8; 32];
125        let ishare = initiator_share(&i_x, &pk).unwrap();
126        let (rshare, r_kem, r_dh) = responder_complete(&ishare, &r_x).unwrap();
127        let (i_kem, i_dh) = initiator_complete(&sk, &i_x, &rshare).unwrap();
128        assert_eq!(i_kem, r_kem);
129        assert_eq!(i_dh, r_dh);
130        let mut t = Transcript::new();
131        t.append(b"suite", b"qpr-pq-1").unwrap();
132        let k1 = derive_handshake_keys(&i_kem, &i_dh, &t).unwrap();
133        let k2 = derive_handshake_keys(&r_kem, &r_dh, &t).unwrap();
134        assert_eq!(k1.initiator_to_responder, k2.initiator_to_responder);
135        assert_ne!(k1.initiator_to_responder, k1.responder_to_initiator);
136        assert!(FORBIDDEN_ZERO_RTT);
137        assert_eq!(HandshakeState::Idle as u8, 0);
138        let _ = HandshakeKeys {
139            initiator_to_responder: k1.initiator_to_responder,
140            responder_to_initiator: k1.responder_to_initiator,
141            transcript_digest: k1.transcript_digest,
142        };
143    }
144
145    #[test]
146    fn zero_x25519_secret_is_rejected() {
147        let (_sk, pk) = MlKem768Secret::generate().unwrap();
148        assert!(initiator_share(&[0u8; 32], &pk).is_err());
149    }
150}