Skip to main content

umbera_core/
callkey.rs

1// Second, post-quantum layer for calls.
2//
3// DTLS-SRTP in WebRTC agrees on a key via ECDHE, which is not post-quantum: a conversation recorded today
4// can be decrypted by a quantum computer tomorrow. Therefore frames (audio, camera, screen sharing)
5// are additionally encrypted with a key the parties agreed on via a hybrid X25519 + ML-KEM-1024 exchange
6// over the already protected messaging channel (call offer/answer travel inside the 1:1 E2E envelope). A frame opens
7// only if BOTH DTLS AND this exchange are broken — i.e. both X25519 and ML-KEM.
8//
9// Flow (per PeerConnection pair: 1:1 and every pair in a conference):
10//   initiator (sends the offer):      call_pq_keypair()          → public in the offer, secret kept locally;
11//   responder (if supported):         call_pq_respond(id, public) → answer back, keys ready;
12//   initiator:                         call_pq_finish(id, secret, public, answer) → the same keys.
13// An old peer neither sends nor reads these fields — the call proceeds as before, without the second layer.
14//
15//   public  = version(1) ‖ X25519 (32) ‖ ML-KEM-1024 key (1568)
16//   answer  = version(1) ‖ X25519 (32) ‖ ML-KEM-1024 ciphertext (1568)
17//   TH      = SHA-256( ∀ part: u32be len ‖ part ) over ["umbera-call-v1/transcript", call_id, public, answer]
18//   PRK     = HKDF-SHA256-Extract(salt = TH, IKM = X25519(eph., eph.) ‖ ss ML-KEM)
19//   key i→r, key r→i = HKDF-Expand(PRK, "umbera-call-v1/frames/initiator->responder" | "…/responder->initiator", 32)
20//   code    = 4 bytes HKDF-Expand(PRK, "umbera-call-v1/check", 4) — for comparison in the verification log, not in the UI.
21// Keys are fresh for every call (ephemeral X25519 and ML-KEM) — forward secrecy: a later leak of long-term
22// keys does not open a recorded conversation. An all-zero X25519 result (small-order point) is rejected.
23
24use sha2::{Digest, Sha256};
25use zeroize::Zeroizing;
26
27use crate::primitives as p;
28use crate::primitives::PrimitiveError;
29
30const VERSION: u8 = 1;
31const X_LEN: usize = 32;
32const EK_LEN: usize = 1568;
33const CT_LEN: usize = 1568;
34/// Length of `public` and `answer`.
35pub const CALL_PQ_BLOB_LEN: usize = 1 + X_LEN + EK_LEN;
36
37#[derive(uniffi::Record)]
38pub struct CallPqKeypair {
39    /// Goes into the call offer (base64 in the signal).
40    pub public: Vec<u8>,
41    /// Keep locally until the answer; X25519 (32) ‖ ML-KEM seed (64). Erase after call_pq_finish.
42    pub secret: Vec<u8>,
43}
44
45#[derive(uniffi::Record)]
46pub struct CallFrameKeys {
47    /// Key for frames this side SENDS.
48    pub send: Vec<u8>,
49    /// Key for frames this side RECEIVES.
50    pub recv: Vec<u8>,
51    /// 4 check bytes: identical on both sides.
52    pub check: Vec<u8>,
53}
54
55#[derive(uniffi::Record)]
56pub struct CallPqResponse {
57    pub answer: Vec<u8>,
58    pub keys: CallFrameKeys,
59}
60
61fn bad(m: &str) -> PrimitiveError {
62    PrimitiveError::Key(format!("call pq: {m}"))
63}
64
65fn transcript(call_id: &str, public: &[u8], answer: &[u8]) -> Vec<u8> {
66    let mut h = Sha256::new();
67    for part in [b"umbera-call-v1/transcript".as_slice(), call_id.as_bytes(), public, answer] {
68        h.update((part.len() as u32).to_be_bytes());
69        h.update(part);
70    }
71    h.finalize().to_vec()
72}
73
74fn derive(call_id: &str, public: &[u8], answer: &[u8], ss_x: &[u8], ss_k: &[u8], initiator: bool) -> Result<CallFrameKeys, PrimitiveError> {
75    if ss_x.iter().all(|b| *b == 0) {
76        return Err(bad("x25519 low-order point"));
77    }
78    let th = transcript(call_id, public, answer);
79    let ikm = Zeroizing::new([ss_x, ss_k].concat());
80    let prk = Zeroizing::new(hkdf::Hkdf::<Sha256>::extract(Some(&th), &ikm).0.to_vec());
81    let exp = |info: &str, n: u32| p::hkdf_sha256_expand(prk.to_vec(), info.as_bytes().to_vec(), n);
82    let i2r = exp("umbera-call-v1/frames/initiator->responder", 32)?;
83    let r2i = exp("umbera-call-v1/frames/responder->initiator", 32)?;
84    let check = exp("umbera-call-v1/check", 4)?;
85    Ok(if initiator { CallFrameKeys { send: i2r, recv: r2i, check } } else { CallFrameKeys { send: r2i, recv: i2r, check } })
86}
87
88fn check_id(call_id: &str) -> Result<(), PrimitiveError> {
89    if call_id.is_empty() || call_id.len() > 128 {
90        return Err(bad("call id length"));
91    }
92    Ok(())
93}
94
95/// Initiator: an ephemeral X25519 + ML-KEM-1024 pair for one call.
96#[uniffi::export]
97pub fn call_pq_keypair() -> CallPqKeypair {
98    let xs: Zeroizing<[u8; 32]> = Zeroizing::new(p::os_random());
99    let kem = p::mlkem1024_generate_keypair();
100    let xp = p::x25519_public_key(xs.to_vec()).expect("32-byte x25519 scalar");
101    let mut public = Vec::with_capacity(CALL_PQ_BLOB_LEN);
102    public.push(VERSION);
103    public.extend_from_slice(&xp);
104    public.extend_from_slice(&kem.public_key);
105    let mut secret = Vec::with_capacity(32 + 64);
106    secret.extend_from_slice(xs.as_ref());
107    secret.extend_from_slice(&kem.private_key);
108    let _wipe = Zeroizing::new(kem.private_key);
109    CallPqKeypair { public, secret }
110}
111
112/// Responder: verify the initiator's `public`, answer and immediately derive the frame keys.
113#[uniffi::export]
114pub fn call_pq_respond(call_id: String, initiator_public: Vec<u8>) -> Result<CallPqResponse, PrimitiveError> {
115    check_id(&call_id)?;
116    if initiator_public.len() != CALL_PQ_BLOB_LEN || initiator_public[0] != VERSION {
117        return Err(bad("initiator public: length/version"));
118    }
119    let peer_x = initiator_public[1..1 + X_LEN].to_vec();
120    let ek = initiator_public[1 + X_LEN..].to_vec();
121    let enc = p::mlkem1024_encapsulate(ek)?;
122    let xs: Zeroizing<[u8; 32]> = Zeroizing::new(p::os_random());
123    let xp = p::x25519_public_key(xs.to_vec())?;
124    let ss_x = Zeroizing::new(p::x25519_shared_secret(xs.to_vec(), peer_x)?);
125    let ss_k = Zeroizing::new(enc.shared_secret);
126    let mut answer = Vec::with_capacity(CALL_PQ_BLOB_LEN);
127    answer.push(VERSION);
128    answer.extend_from_slice(&xp);
129    answer.extend_from_slice(&enc.ciphertext);
130    let keys = derive(&call_id, &initiator_public, &answer, &ss_x, &ss_k, false)?;
131    Ok(CallPqResponse { answer, keys })
132}
133
134/// Initiator: from the responder's answer — the same frame keys.
135#[uniffi::export]
136pub fn call_pq_finish(call_id: String, secret: Vec<u8>, initiator_public: Vec<u8>, answer: Vec<u8>) -> Result<CallFrameKeys, PrimitiveError> {
137    check_id(&call_id)?;
138    let secret = Zeroizing::new(secret);
139    if secret.len() != 32 + 64 {
140        return Err(bad("secret length"));
141    }
142    if initiator_public.len() != CALL_PQ_BLOB_LEN || answer.len() != CALL_PQ_BLOB_LEN || answer[0] != VERSION {
143        return Err(bad("answer: length/version"));
144    }
145    // public must be ours: otherwise the keys would come from someone else's transcript.
146    let own_x = p::x25519_public_key(secret[..32].to_vec())?;
147    let own_ek = p::mlkem1024_public_key(secret[32..].to_vec())?;
148    if initiator_public[1..1 + X_LEN] != own_x[..] || initiator_public[1 + X_LEN..] != own_ek[..] {
149        return Err(bad("public does not belong to secret"));
150    }
151    let peer_x = answer[1..1 + X_LEN].to_vec();
152    let ct = answer[1 + X_LEN..1 + X_LEN + CT_LEN].to_vec();
153    let ss_x = Zeroizing::new(p::x25519_shared_secret(secret[..32].to_vec(), peer_x)?);
154    let ss_k = Zeroizing::new(p::mlkem1024_decapsulate(ct, secret[32..].to_vec())?);
155    derive(&call_id, &initiator_public, &answer, &ss_x, &ss_k, true)
156}
157
158#[cfg(test)]
159mod tests {
160    use super::*;
161
162    #[test]
163    fn both_sides_get_the_same_directional_keys() {
164        let kp = call_pq_keypair();
165        assert_eq!(kp.public.len(), CALL_PQ_BLOB_LEN);
166        let r = call_pq_respond("call-1".into(), kp.public.clone()).unwrap();
167        let i = call_pq_finish("call-1".into(), kp.secret.clone(), kp.public.clone(), r.answer.clone()).unwrap();
168        assert_eq!(i.send, r.keys.recv);
169        assert_eq!(i.recv, r.keys.send);
170        assert_ne!(i.send, i.recv);
171        assert_eq!(i.check, r.keys.check);
172        // A different call — different keys, even with the same exchange bytes.
173        let other = call_pq_finish("call-2".into(), kp.secret.clone(), kp.public.clone(), r.answer.clone()).unwrap();
174        assert_ne!(other.send, i.send);
175    }
176
177    #[test]
178    fn tampering_changes_keys_or_fails() {
179        let kp = call_pq_keypair();
180        let r = call_pq_respond("c".into(), kp.public.clone()).unwrap();
181        // Substituted ML-KEM ciphertext: FIPS 203 implicit rejection → different keys (the check fails, frames do not open).
182        let mut a = r.answer.clone();
183        a[100] ^= 1;
184        let k = call_pq_finish("c".into(), kp.secret.clone(), kp.public.clone(), a).unwrap();
185        assert_ne!(k.recv, r.keys.send);
186        // Substituted responder X25519.
187        let mut a = r.answer.clone();
188        a[5] ^= 1;
189        let k = call_pq_finish("c".into(), kp.secret.clone(), kp.public.clone(), a).unwrap();
190        assert_ne!(k.recv, r.keys.send);
191        // Someone else's public with our secret — rejected.
192        let other = call_pq_keypair();
193        assert!(call_pq_finish("c".into(), kp.secret.clone(), other.public, r.answer.clone()).is_err());
194        // Invalid lengths/version.
195        assert!(call_pq_respond("c".into(), kp.public[..100].to_vec()).is_err());
196        let mut v = kp.public.clone();
197        v[0] = 2;
198        assert!(call_pq_respond("c".into(), v).is_err());
199        assert!(call_pq_respond(String::new(), kp.public.clone()).is_err());
200        // Small-order point (all-zero X25519) — rejected.
201        let mut z = kp.public.clone();
202        z[1..33].fill(0);
203        assert!(call_pq_respond("c".into(), z).is_err());
204    }
205}