Skip to main content

umbera_core/devlink/
mlsjoin.rs

1// MLS on a linked device: every device is ITS OWN group leaf, not a copy of the phone's
2// keys. MLS state must not be copied: two devices sharing one leaf would diverge
3// in the ratchet (same generation, nonce reuse) and break the group and its secrecy.
4//
5// How a desktop joins the phone's groups:
6//  1. Phone → desktop (KIND_MLS_JOIN_REQUESTS): a list of {gid, the phone's memberId in the group}.
7//  2. For each group the desktop creates a separate MlsClient with a FRESH random memberId
8//     (as MlsManager.beginJoin: groups are not linkable to each other), makes a KeyPackage and
9//     signs the "sibling" link sibling(gid, phone memberId, desktop memberId) with its
10//     leaf key → desktop → phone (KIND_MLS_JOIN_OFFERS).
11//  3. The phone verifies the link against the leaf key from the KeyPackage (mls_sibling_verify_key_package),
12//     co-signs it with its own leaf (sibling_sign), adds the KeyPackage to the group
13//     (add_members → Commit to members) and puts the Welcome into the bundle (SECTION_MLS_WELCOME,
14//     id = desktop memberId). To the group it sends a control message "leaf X is my
15//     device" with both signatures; any member checks it with sibling_verify against the
16//     leaf keys in the current tree and shows both leaves as one person.
17// The link is signed with leaf keys of this group only and only for this group, so
18// it does not reveal that the same people are in another group (group anonymity is preserved).
19
20use openmls::prelude::*;
21use crate::provider::UmberaProvider;
22use openmls_traits::signatures::Signer as _;
23use tls_codec::Deserialize as _;
24
25use super::codec::{Rd, W};
26use super::{LinkError, DOMAIN, LR};
27use crate::{MlsClient, MlsError};
28
29const ID_MAX: usize = 64;
30const GID_MAX: usize = 255;
31const KP_MAX: usize = 64 * 1024;
32const LIST_MAX: usize = 1024;
33
34#[derive(uniffi::Record, Clone, Debug, PartialEq, Eq)]
35pub struct MlsJoinRequest {
36    pub gid: Vec<u8>,
37    pub primary_member_id: Vec<u8>,
38}
39
40#[derive(uniffi::Record, Clone, Debug, PartialEq, Eq)]
41pub struct MlsJoinOffer {
42    pub gid: Vec<u8>,
43    pub device_member_id: Vec<u8>,
44    pub key_package: Vec<u8>,
45    /// Link signature with the desktop leaf key (Ed25519 MLS, 64 B).
46    pub device_sibling_sig: Vec<u8>,
47}
48
49fn check_ids(gid: &[u8], a: &[u8], b: &[u8]) -> LR<()> {
50    if gid.is_empty() || gid.len() > GID_MAX || a.is_empty() || a.len() > ID_MAX || b.is_empty() || b.len() > ID_MAX {
51        return Err(LinkError::Malformed("mls sibling: id lengths".into()));
52    }
53    if a == b {
54        return Err(LinkError::Malformed("mls sibling: device and primary are the same leaf".into()));
55    }
56    Ok(())
57}
58
59pub(crate) fn sibling_message(gid: &[u8], primary: &[u8], device: &[u8]) -> LR<Vec<u8>> {
60    check_ids(gid, primary, device)?;
61    let mut w = W::new();
62    w.raw(DOMAIN).raw(b"/mls-sibling").b8(gid).b8(primary).b8(device);
63    Ok(w.done())
64}
65
66fn ed25519_ok(crypto: &impl openmls_traits::crypto::OpenMlsCrypto, msg: &[u8], pk: &[u8], sig: &[u8]) -> bool {
67    crypto.verify_signature(SignatureScheme::ED25519, msg, pk, sig).is_ok()
68}
69
70#[uniffi::export]
71pub fn mls_join_requests_encode(requests: Vec<MlsJoinRequest>) -> LR<Vec<u8>> {
72    if requests.len() > LIST_MAX {
73        return Err(LinkError::Malformed("too many groups".into()));
74    }
75    let mut w = W::new();
76    w.u16(requests.len() as u16);
77    for r in &requests {
78        if r.gid.is_empty() || r.gid.len() > GID_MAX || r.primary_member_id.is_empty() || r.primary_member_id.len() > ID_MAX {
79            return Err(LinkError::Malformed("join request: id lengths".into()));
80        }
81        w.b8(&r.gid).b8(&r.primary_member_id);
82    }
83    Ok(w.done())
84}
85
86#[uniffi::export]
87pub fn mls_join_requests_decode(bytes: Vec<u8>) -> LR<Vec<MlsJoinRequest>> {
88    let mut r = Rd::new(&bytes, "join requests");
89    let n = r.u16()? as usize;
90    if n > LIST_MAX {
91        return Err(LinkError::Malformed("too many groups".into()));
92    }
93    let mut out = Vec::with_capacity(n);
94    for _ in 0..n {
95        let gid = r.b8(GID_MAX)?.to_vec();
96        let primary_member_id = r.b8(ID_MAX)?.to_vec();
97        if gid.is_empty() || primary_member_id.is_empty() {
98            return Err(LinkError::Malformed("join request: empty id".into()));
99        }
100        out.push(MlsJoinRequest { gid, primary_member_id });
101    }
102    r.end()?;
103    Ok(out)
104}
105
106#[uniffi::export]
107pub fn mls_join_offers_encode(offers: Vec<MlsJoinOffer>) -> LR<Vec<u8>> {
108    if offers.len() > LIST_MAX {
109        return Err(LinkError::Malformed("too many groups".into()));
110    }
111    let mut w = W::new();
112    w.u16(offers.len() as u16);
113    for o in &offers {
114        if o.gid.is_empty() || o.gid.len() > GID_MAX || o.device_member_id.is_empty() || o.device_member_id.len() > ID_MAX
115            || o.key_package.is_empty() || o.key_package.len() > KP_MAX || o.device_sibling_sig.len() != 64
116        {
117            return Err(LinkError::Malformed("join offer: field lengths".into()));
118        }
119        w.b8(&o.gid).b8(&o.device_member_id).b32(&o.key_package).b8(&o.device_sibling_sig);
120    }
121    Ok(w.done())
122}
123
124#[uniffi::export]
125pub fn mls_join_offers_decode(bytes: Vec<u8>) -> LR<Vec<MlsJoinOffer>> {
126    let mut r = Rd::new(&bytes, "join offers");
127    let n = r.u16()? as usize;
128    if n > LIST_MAX {
129        return Err(LinkError::Malformed("too many groups".into()));
130    }
131    let mut out = Vec::with_capacity(n);
132    for _ in 0..n {
133        let gid = r.b8(GID_MAX)?.to_vec();
134        let device_member_id = r.b8(ID_MAX)?.to_vec();
135        let key_package = r.b32(KP_MAX)?.to_vec();
136        let device_sibling_sig = r.b8(64)?.to_vec();
137        if gid.is_empty() || device_member_id.is_empty() || key_package.is_empty() || device_sibling_sig.len() != 64 {
138            return Err(LinkError::Malformed("join offer: field lengths".into()));
139        }
140        out.push(MlsJoinOffer { gid, device_member_id, key_package, device_sibling_sig });
141    }
142    r.end()?;
143    Ok(out)
144}
145
146/// Phone, before add_members: the KeyPackage is valid (signature, ciphersuite), its leaf carries
147/// the claimed desktop memberId, and the link is signed with the key of exactly this leaf.
148#[uniffi::export]
149pub fn mls_sibling_verify_key_package(primary_member_id: Vec<u8>, offer: MlsJoinOffer) -> bool {
150    let Ok(msg) = sibling_message(&offer.gid, &primary_member_id, &offer.device_member_id) else { return false };
151    let provider = UmberaProvider::default();
152    let Ok(kp_in) = KeyPackageIn::tls_deserialize_exact(&offer.key_package) else { return false };
153    let Ok(kp) = kp_in.validate(provider.crypto(), ProtocolVersion::Mls10) else { return false };
154    let leaf = kp.leaf_node();
155    if leaf.credential().serialized_content() != offer.device_member_id.as_slice() {
156        return false;
157    }
158    ed25519_ok(provider.crypto(), &msg, leaf.signature_key().as_slice(), &offer.device_sibling_sig)
159}
160
161#[uniffi::export]
162impl MlsClient {
163    /// Sign the "sibling" link with our own leaf key. Our memberId must be one of the
164    /// two (the phone signs as primary, the desktop as device). Group membership is not required:
165    /// the desktop signs before joining; an MlsClient has one leaf key for its whole lifetime.
166    pub fn sibling_sign(&self, gid: Vec<u8>, primary_member_id: Vec<u8>, device_member_id: Vec<u8>) -> Result<Vec<u8>, MlsError> {
167        let g = self.inner.lock().unwrap();
168        if g.identity != primary_member_id && g.identity != device_member_id {
169            return Err(MlsError::Generic("sibling: our memberId is neither primary nor device".into()));
170        }
171        let msg = sibling_message(&gid, &primary_member_id, &device_member_id).map_err(|e| MlsError::Generic(e.to_string()))?;
172        g.signer.sign(&msg).map_err(|e| MlsError::Generic(format!("sibling sign: {e:?}")))
173    }
174
175    /// Verify the link against leaf keys in the CURRENT group tree: both leaves exist,
176    /// carry these memberIds, and both signatures are valid.
177    pub fn sibling_verify(
178        &self,
179        gid: Vec<u8>,
180        primary_member_id: Vec<u8>,
181        device_member_id: Vec<u8>,
182        primary_sig: Vec<u8>,
183        device_sig: Vec<u8>,
184    ) -> Result<bool, MlsError> {
185        let Ok(msg) = sibling_message(&gid, &primary_member_id, &device_member_id) else { return Ok(false) };
186        let g = self.inner.lock().unwrap();
187        let group = MlsClient::load_group(&g, &gid)?;
188        let key_of = |id: &[u8]| {
189            group
190                .members()
191                .find(|m| m.credential.serialized_content() == id)
192                .map(|m| m.signature_key)
193        };
194        let (Some(pk_p), Some(pk_d)) = (key_of(&primary_member_id), key_of(&device_member_id)) else { return Ok(false) };
195        let a = ed25519_ok(g.provider.crypto(), &msg, &pk_p, &primary_sig);
196        let b = ed25519_ok(g.provider.crypto(), &msg, &pk_d, &device_sig);
197        Ok(a & b)
198    }
199}