Skip to main content

qualia_core_db/crypto/network/
pq_handshake.rs

1//! CRY-02 PQ handshake transitions over the existing `HandshakeState` FSM.
2//!
3//! Draft until FND-03 freeze: initiator share wire bytes are exactly
4//! `ml_kem_pk || x25519_pk` with no version prefix. Responder share encoding,
5//! length-delimited transcripts, dual proofs, and CRY-02.12 independent
6//! vectors remain open. No security proof is claimed. Live KEM encapsulate
7//! is not exercised here (RNG/provider); encodings + FSM + 0-RTT only.
8//!
9//! Allowed successive states:
10//! `Idle → Reachability → SharesExchanged → HandshakeKeys → Proofs → Finished → Traffic`
11
12use crate::crypto::network::errors::CryptoError;
13use crate::crypto::network::types::{ML_KEM_768_PK_LEN, X25519_LEN};
14use crate::net::qdnf::crypto::handshake::{HandshakeState, InitiatorShare, FORBIDDEN_ZERO_RTT};
15
16/// Exact initiator-share slice length: `ML_KEM_768_PK_LEN || X25519_LEN`.
17pub const INITIATOR_SHARE_WIRE_LEN: usize = ML_KEM_768_PK_LEN + X25519_LEN;
18
19const _: () = assert!(FORBIDDEN_ZERO_RTT);
20
21/// QLink HKDF/domain label. Distinct from [`qsession_domain`].
22pub fn qlink_domain() -> &'static [u8] {
23    b"qpr-pq-1/qlink"
24}
25
26/// QSession HKDF/domain label. Distinct from [`qlink_domain`].
27pub fn qsession_domain() -> &'static [u8] {
28    b"qpr-pq-1/qsession"
29}
30
31/// CRY-02.06 partial: classical-only controller/delegation is never sufficient.
32pub fn classical_only_authority_is_enough() -> bool {
33    false
34}
35
36/// Application data is admitted only in `Traffic`. Initial-profile 0-RTT is false.
37pub fn application_data_allowed(state: HandshakeState) -> bool {
38    debug_assert!(FORBIDDEN_ZERO_RTT);
39    state == HandshakeState::Traffic
40}
41
42/// Advance `from` to `to` only when `to` is the immediate successor.
43///
44/// Forbidden: skip, reverse, stay, `Idle → Traffic`, or any `→ Traffic` before `Finished`.
45/// Skip-to-traffic / 0-RTT attempts map to [`CryptoError::Downgrade`]. Reverse maps to
46/// [`CryptoError::Unauthorized`]. Other illegal steps map to [`CryptoError::Malformed`].
47pub fn transition(from: HandshakeState, to: HandshakeState) -> Result<HandshakeState, CryptoError> {
48    if successor(from) == Some(to) {
49        return Ok(to);
50    }
51    if to == HandshakeState::Traffic {
52        return Err(CryptoError::Downgrade);
53    }
54    if (to as u8) < (from as u8) {
55        return Err(CryptoError::Unauthorized);
56    }
57    Err(CryptoError::Malformed)
58}
59
60#[inline]
61fn successor(from: HandshakeState) -> Option<HandshakeState> {
62    match from {
63        HandshakeState::Idle => Some(HandshakeState::Reachability),
64        HandshakeState::Reachability => Some(HandshakeState::SharesExchanged),
65        HandshakeState::SharesExchanged => Some(HandshakeState::HandshakeKeys),
66        HandshakeState::HandshakeKeys => Some(HandshakeState::Proofs),
67        HandshakeState::Proofs => Some(HandshakeState::Finished),
68        HandshakeState::Finished => Some(HandshakeState::Traffic),
69        HandshakeState::Traffic => None,
70    }
71}
72
73/// Encode initiator share as `ml_kem_pk || x25519_pk` (draft; no version byte).
74pub fn encode_initiator_share(
75    share: &InitiatorShare,
76    out: &mut [u8],
77) -> Result<usize, CryptoError> {
78    if out.len() < INITIATOR_SHARE_WIRE_LEN {
79        return Err(CryptoError::Capacity);
80    }
81    out[..ML_KEM_768_PK_LEN].copy_from_slice(&share.ml_kem_pk);
82    out[ML_KEM_768_PK_LEN..INITIATOR_SHARE_WIRE_LEN].copy_from_slice(&share.x25519_pk);
83    Ok(INITIATOR_SHARE_WIRE_LEN)
84}
85
86/// Decode initiator share from `ml_kem_pk || x25519_pk`. Truncated `src` fails.
87/// Extra bytes are [`CryptoError::Malformed`]. Does not call `initiator_share`.
88pub fn decode_initiator_share(src: &[u8]) -> Result<InitiatorShare, CryptoError> {
89    if src.len() < INITIATOR_SHARE_WIRE_LEN {
90        return Err(CryptoError::Truncated);
91    }
92    if src.len() != INITIATOR_SHARE_WIRE_LEN {
93        return Err(CryptoError::Malformed);
94    }
95    let mut share = InitiatorShare {
96        ml_kem_pk: [0u8; ML_KEM_768_PK_LEN],
97        x25519_pk: [0u8; X25519_LEN],
98    };
99    share.ml_kem_pk.copy_from_slice(&src[..ML_KEM_768_PK_LEN]);
100    share.x25519_pk.copy_from_slice(&src[ML_KEM_768_PK_LEN..]);
101    Ok(share)
102}
103
104/// Concatenate ML-KEM shared secret then X25519 shared secret. Order is frozen.
105pub fn ml_kem_then_x25519_secret_input(
106    ml_kem_ss: &[u8; 32],
107    x25519_ss: &[u8; 32],
108    out: &mut [u8; 64],
109) {
110    out[..32].copy_from_slice(ml_kem_ss);
111    out[32..].copy_from_slice(x25519_ss);
112}
113
114#[cfg(test)]
115mod tests {
116    use super::*;
117    use crate::crypto::network::x25519::X25519Secret;
118    use crate::net::qdnf::crypto::handshake::initiator_share;
119
120    /// Fixed test-only ML-KEM public bytes. Not a production key; not generated.
121    fn test_ml_kem_pk() -> [u8; ML_KEM_768_PK_LEN] {
122        let mut pk = [0u8; ML_KEM_768_PK_LEN];
123        let mut i = 0usize;
124        while i < ML_KEM_768_PK_LEN {
125            pk[i] = (i as u8).wrapping_add(0x5A);
126            i += 1;
127        }
128        pk[0] = 0x11;
129        pk[ML_KEM_768_PK_LEN - 1] = 0xEE;
130        pk
131    }
132
133    const TEST_X25519_SK: [u8; 32] = [
134        0x42, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E,
135        0x0F, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D,
136        0x1E, 0x1F,
137    ];
138
139    fn test_share_from_fixed_keys() -> InitiatorShare {
140        InitiatorShare {
141            ml_kem_pk: test_ml_kem_pk(),
142            x25519_pk: X25519Secret::from_bytes(TEST_X25519_SK).public(),
143        }
144    }
145
146    #[test]
147    fn successive_transitions_ok() {
148        let chain = [
149            (HandshakeState::Idle, HandshakeState::Reachability),
150            (
151                HandshakeState::Reachability,
152                HandshakeState::SharesExchanged,
153            ),
154            (
155                HandshakeState::SharesExchanged,
156                HandshakeState::HandshakeKeys,
157            ),
158            (HandshakeState::HandshakeKeys, HandshakeState::Proofs),
159            (HandshakeState::Proofs, HandshakeState::Finished),
160            (HandshakeState::Finished, HandshakeState::Traffic),
161        ];
162        let mut i = 0usize;
163        while i < chain.len() {
164            let (from, to) = chain[i];
165            assert_eq!(transition(from, to), Ok(to));
166            i += 1;
167        }
168    }
169
170    #[test]
171    fn skip_shares_to_proofs_forbidden() {
172        assert_eq!(
173            transition(HandshakeState::SharesExchanged, HandshakeState::Proofs),
174            Err(CryptoError::Malformed)
175        );
176    }
177
178    #[test]
179    fn reverse_and_skip_to_traffic_forbidden() {
180        assert_eq!(
181            transition(HandshakeState::Proofs, HandshakeState::HandshakeKeys),
182            Err(CryptoError::Unauthorized)
183        );
184        assert_eq!(
185            transition(HandshakeState::Idle, HandshakeState::Traffic),
186            Err(CryptoError::Downgrade)
187        );
188        assert_eq!(
189            transition(HandshakeState::SharesExchanged, HandshakeState::Traffic),
190            Err(CryptoError::Downgrade)
191        );
192        assert_eq!(
193            transition(HandshakeState::Proofs, HandshakeState::Traffic),
194            Err(CryptoError::Downgrade)
195        );
196        assert_eq!(
197            transition(HandshakeState::Idle, HandshakeState::Idle),
198            Err(CryptoError::Malformed)
199        );
200    }
201
202    #[test]
203    fn zero_rtt_application_data_forbidden() {
204        assert!(FORBIDDEN_ZERO_RTT);
205        assert!(!application_data_allowed(HandshakeState::Idle));
206        assert!(!application_data_allowed(HandshakeState::Reachability));
207        assert!(!application_data_allowed(HandshakeState::SharesExchanged));
208        assert!(!application_data_allowed(HandshakeState::HandshakeKeys));
209        assert!(!application_data_allowed(HandshakeState::Proofs));
210        assert!(!application_data_allowed(HandshakeState::Finished));
211        assert!(application_data_allowed(HandshakeState::Traffic));
212    }
213
214    #[test]
215    fn encode_decode_share_round_trip_independent_of_initiator_share() {
216        let share = test_share_from_fixed_keys();
217        let mut wire = [0u8; INITIATOR_SHARE_WIRE_LEN];
218        let n = encode_initiator_share(&share, &mut wire).unwrap();
219        assert_eq!(n, INITIATOR_SHARE_WIRE_LEN);
220        assert_eq!(&wire[..ML_KEM_768_PK_LEN], &share.ml_kem_pk);
221        assert_eq!(&wire[ML_KEM_768_PK_LEN..], &share.x25519_pk);
222
223        let decoded = decode_initiator_share(&wire).unwrap();
224        assert_eq!(decoded.ml_kem_pk, share.ml_kem_pk);
225        assert_eq!(decoded.x25519_pk, share.x25519_pk);
226
227        let from_helper = initiator_share(&TEST_X25519_SK, &share.ml_kem_pk).unwrap();
228        assert_eq!(from_helper.x25519_pk, share.x25519_pk);
229        assert_eq!(from_helper.ml_kem_pk, share.ml_kem_pk);
230    }
231
232    #[test]
233    fn encode_capacity_and_decode_truncated() {
234        let share = test_share_from_fixed_keys();
235        let mut short = [0u8; 8];
236        assert_eq!(
237            encode_initiator_share(&share, &mut short),
238            Err(CryptoError::Capacity)
239        );
240        let mut wire = [0u8; INITIATOR_SHARE_WIRE_LEN];
241        encode_initiator_share(&share, &mut wire).unwrap();
242        match decode_initiator_share(&wire[..INITIATOR_SHARE_WIRE_LEN - 1]) {
243            Err(e) => assert_eq!(e, CryptoError::Truncated),
244            Ok(_) => panic!("truncated share decoded"),
245        }
246        let mut extra = [0u8; INITIATOR_SHARE_WIRE_LEN + 1];
247        extra[..INITIATOR_SHARE_WIRE_LEN].copy_from_slice(&wire);
248        match decode_initiator_share(&extra) {
249            Err(e) => assert_eq!(e, CryptoError::Malformed),
250            Ok(_) => panic!("oversize share decoded"),
251        }
252    }
253
254    #[test]
255    fn ml_kem_then_x25519_order() {
256        let kem = [0xAAu8; 32];
257        let x = [0x55u8; 32];
258        let mut out = [0u8; 64];
259        ml_kem_then_x25519_secret_input(&kem, &x, &mut out);
260        assert_eq!(&out[..32], &kem);
261        assert_eq!(&out[32..], &x);
262        assert_ne!(&out[..32], &out[32..]);
263    }
264
265    #[test]
266    fn domains_are_distinct() {
267        assert_ne!(qlink_domain(), qsession_domain());
268        assert_eq!(qlink_domain(), b"qpr-pq-1/qlink");
269        assert_eq!(qsession_domain(), b"qpr-pq-1/qsession");
270    }
271
272    #[test]
273    fn classical_only_authority_rejected() {
274        assert!(!classical_only_authority_is_enough());
275    }
276}