Skip to main content

arachne_security/
message.rs

1//! MLS application protection, independent of transport and payload format.
2use super::*;
3use openmls::prelude::tls_codec::Deserialize;
4
5pub const MAX_APPLICATION_PAYLOAD: usize = 12 * 1024;
6pub const MAX_APPLICATION_CONTEXT: usize = 1024;
7pub const MAX_APPLICATION_CIPHERTEXT: usize = 16 * 1024;
8
9/// Authenticated origin, not necessarily the immediate transport peer.
10#[derive(Debug, PartialEq, Eq)]
11pub struct ApplicationMessage {
12    pub member: [u8; 32],
13    pub endpoint: [u8; 32],
14    pub payload: Vec<u8>,
15}
16
17impl Workspace {
18    /// Advances the sender ratchet. The host must persist the updated workspace
19    /// before sending the returned ciphertext or preparing another publication.
20    /// On any error, close this owner and restore its last committed snapshot.
21    /// Retrying delivery uses the SAME ciphertext, never re-encryption from old state.
22    pub fn protect_application(
23        &mut self,
24        context: &[u8],
25        payload: &[u8],
26    ) -> Result<Vec<u8>, &'static str> {
27        if self.member.is_none()
28            || payload.len() > MAX_APPLICATION_PAYLOAD
29            || context.len() > MAX_APPLICATION_CONTEXT
30        {
31            return Err("application publication exceeds bounds or lacks member identity");
32        }
33        self.group.set_aad(context.to_vec());
34        let encrypted = self
35            .group
36            .create_message(&self.provider, &self._signer, payload)
37            .map_err(|_| "application encryption failed")?
38            .to_bytes()
39            .map_err(|_| "application encoding failed")?;
40        if encrypted.len() > MAX_APPLICATION_CIPHERTEXT {
41            return Err("application ciphertext exceeds bounds");
42        }
43        Ok(encrypted)
44    }
45
46    /// Authenticates an application message and advances replay/receive state.
47    /// The host must persist before delivering the returned plaintext. On any
48    /// error discard this owner and restore committed state: rejection can occur
49    /// after the library has consumed a receive-ratchet generation.
50    /// Context must be the canonical expected routing envelope, not an unchecked
51    /// copy of the incoming message's AAD. This does not grant topic permissions.
52    pub fn unprotect_application(
53        &mut self,
54        context: &[u8],
55        ciphertext: &[u8],
56    ) -> Result<ApplicationMessage, &'static str> {
57        if context.len() > MAX_APPLICATION_CONTEXT || ciphertext.len() > MAX_APPLICATION_CIPHERTEXT
58        {
59            return Err("application message exceeds bounds");
60        }
61        let message = MlsMessageIn::tls_deserialize_exact(ciphertext)
62            .map_err(|_| "invalid application encoding")?;
63        // Membership handshakes have their own authorization path. Never process
64        // public proposals/commits as application traffic.
65        let MlsMessageBodyIn::PrivateMessage(message) = message.extract() else {
66            return Err("application message must be private");
67        };
68        let processed = self
69            .group
70            .process_message(&self.provider, message)
71            .map_err(|_| "application authentication or replay check failed")?;
72        if processed.aad() != context {
73            return Err("application routing context mismatch");
74        }
75        let credential = BasicCredential::try_from(processed.credential().clone())
76            .map_err(|_| "unsupported application author")?;
77        let identity = credential
78            .identity()
79            .strip_prefix(b"data-fabric/candidate-member/v2/")
80            .filter(|identity| identity.len() == 64)
81            .ok_or("application author lacks member identity")?;
82        let member = identity[..32].try_into().unwrap();
83        let endpoint = identity[32..].try_into().unwrap();
84        let ProcessedMessageContent::ApplicationMessage(message) = processed.into_content() else {
85            return Err("membership operation on application channel");
86        };
87        let payload = message.into_bytes();
88        if payload.len() > MAX_APPLICATION_PAYLOAD {
89            return Err("application payload exceeds bounds");
90        }
91        Ok(ApplicationMessage {
92            member,
93            endpoint,
94            payload,
95        })
96    }
97}
98
99#[test]
100fn application_authentication_replay_and_restart() {
101    let admin = Workspace::create([1; 32], "Alex").unwrap();
102    let (invite, checkpoint) = admin.issue_invitation().unwrap();
103    let pending = PendingJoin::from_invitation(&invite, &checkpoint, [2; 32], "Jordan").unwrap();
104    let prepared = admin
105        .prepare_admission([2; 32], pending.admission_request().unwrap())
106        .unwrap();
107    let mut proof = pending.join_proof().unwrap();
108    proof
109        .apply_add(&prepared.authorization, &prepared.commit)
110        .unwrap();
111    let mut receiver = pending
112        .prepare_workspace(&proof, &prepared.welcome)
113        .unwrap();
114    let mut sender = prepared.workspace;
115    let sender_key = StorageKey::derive(&[11; 32]).unwrap();
116    let receiver_key = StorageKey::derive(&[22; 32]).unwrap();
117    let id = sender.id();
118    let context = b"workspace-scoped topic and publication id";
119    let payload = b"arbitrary binary payload\x00\xff";
120    let ciphertext = sender.protect_application(context, payload).unwrap();
121    assert!(
122        !ciphertext
123            .windows(payload.len())
124            .any(|part| part == payload)
125    );
126    // Persist/reopen the advanced sender before releasing ciphertext.
127    sender =
128        Workspace::restore(&sender_key, [1; 32], id, &sender.seal(&sender_key).unwrap()).unwrap();
129    let before = receiver.seal(&receiver_key).unwrap();
130    let mut wrong_context = Workspace::restore(&receiver_key, [2; 32], id, &before).unwrap();
131    assert!(
132        wrong_context
133            .unprotect_application(b"other topic", &ciphertext)
134            .is_err()
135    );
136    let mut damaged = ciphertext.clone();
137    *damaged.last_mut().unwrap() ^= 1;
138    let mut tampered = Workspace::restore(&receiver_key, [2; 32], id, &before).unwrap();
139    assert!(tampered.unprotect_application(context, &damaged).is_err());
140    let mut outsider = Workspace::create([3; 32], "Other workspace").unwrap();
141    assert!(
142        outsider
143            .unprotect_application(context, &ciphertext)
144            .is_err()
145    );
146    let mut trailing = ciphertext.clone();
147    trailing.push(0);
148    assert!(receiver.unprotect_application(context, &trailing).is_err());
149    receiver = Workspace::restore(&receiver_key, [2; 32], id, &before).unwrap();
150    assert!(
151        receiver
152            .unprotect_application(context, &prepared.commit)
153            .is_err()
154    );
155    receiver = Workspace::restore(&receiver_key, [2; 32], id, &before).unwrap();
156    let received = receiver
157        .unprotect_application(context, &ciphertext)
158        .unwrap();
159    assert_eq!(received.member, sender.member().unwrap().id());
160    assert_eq!(received.endpoint, [1; 32]);
161    assert_eq!(received.payload, payload);
162    let received_snapshot = receiver.seal(&receiver_key).unwrap();
163    receiver = Workspace::restore(&receiver_key, [2; 32], id, &received_snapshot).unwrap();
164    assert!(
165        receiver
166            .unprotect_application(context, &ciphertext)
167            .is_err()
168    );
169    receiver = Workspace::restore(&receiver_key, [2; 32], id, &received_snapshot).unwrap();
170    let next = sender
171        .protect_application(context, b"next generation")
172        .unwrap();
173    sender =
174        Workspace::restore(&sender_key, [1; 32], id, &sender.seal(&sender_key).unwrap()).unwrap();
175    assert_eq!(
176        receiver
177            .unprotect_application(context, &next)
178            .unwrap()
179            .payload,
180        b"next generation"
181    );
182    let large_context = vec![7; MAX_APPLICATION_CONTEXT];
183    let large_payload = vec![8; MAX_APPLICATION_PAYLOAD];
184    let large = sender
185        .protect_application(&large_context, &large_payload)
186        .unwrap();
187    assert!(large.len() <= MAX_APPLICATION_CIPHERTEXT);
188    sender =
189        Workspace::restore(&sender_key, [1; 32], id, &sender.seal(&sender_key).unwrap()).unwrap();
190    assert_eq!(
191        receiver
192            .unprotect_application(&large_context, &large)
193            .unwrap()
194            .payload,
195        large_payload
196    );
197    receiver = Workspace::restore(
198        &receiver_key,
199        [2; 32],
200        id,
201        &receiver.seal(&receiver_key).unwrap(),
202    )
203    .unwrap();
204    let reverse = receiver
205        .protect_application(context, b"reply from member")
206        .unwrap();
207    let _persisted = receiver.seal(&receiver_key).unwrap();
208    let reply = sender.unprotect_application(context, &reverse).unwrap();
209    assert_eq!(reply.member, receiver.member().unwrap().id());
210    assert_eq!(reply.endpoint, [2; 32]);
211    assert_eq!(reply.payload, b"reply from member");
212    let _persisted = sender.seal(&sender_key).unwrap();
213    assert!(
214        receiver
215            .unprotect_application(context, &vec![0; MAX_APPLICATION_CIPHERTEXT + 1])
216            .is_err()
217    );
218    assert!(
219        sender
220            .protect_application(context, &vec![0; MAX_APPLICATION_PAYLOAD + 1])
221            .is_err()
222    );
223}
224
225#[test]
226fn selective_subscription_requires_bounded_ratchet_recovery() {
227    let admin = Workspace::create([1; 32], "Publisher").unwrap();
228    let (invite, checkpoint) = admin.issue_invitation().unwrap();
229    let pending =
230        PendingJoin::from_invitation(&invite, &checkpoint, [2; 32], "Subscriber").unwrap();
231    let prepared = admin
232        .prepare_admission([2; 32], pending.admission_request().unwrap())
233        .unwrap();
234    let mut proof = pending.join_proof().unwrap();
235    proof
236        .apply_add(&prepared.authorization, &prepared.commit)
237        .unwrap();
238    let receiver = pending
239        .prepare_workspace(&proof, &prepared.welcome)
240        .unwrap();
241    let mut sender = prepared.workspace;
242    let key = StorageKey::derive(&[22; 32]).unwrap();
243    let before = receiver.seal(&key).unwrap();
244    // One sender ratchet covers its applications across topics in this MLS group.
245    // Keep only the last two packets to exercise the pinned default's exact edge.
246    let mut edge = Vec::new();
247    let mut beyond = Vec::new();
248    for generation in 0..=1001u32 {
249        let packet = sender
250            .protect_application(b"busy/topic", &generation.to_be_bytes())
251            .unwrap();
252        if generation == 1000 {
253            edge = packet;
254        } else if generation == 1001 {
255            beyond = packet;
256        }
257    }
258    let mut candidate = Workspace::restore(&key, [2; 32], sender.id(), &before).unwrap();
259    assert!(
260        candidate
261            .unprotect_application(b"busy/topic", &beyond)
262            .is_err()
263    );
264    // Rejected candidates are discarded. An available intermediate ciphertext
265    // permits bounded advancement, but the runtime does not retrieve it yet.
266    let mut candidate = Workspace::restore(&key, [2; 32], sender.id(), &before).unwrap();
267    assert_eq!(
268        candidate
269            .unprotect_application(b"busy/topic", &edge)
270            .unwrap()
271            .payload,
272        1000u32.to_be_bytes()
273    );
274    let saved = candidate.seal(&key).unwrap();
275    let mut recovered = Workspace::restore(&key, [2; 32], sender.id(), &saved).unwrap();
276    assert_eq!(
277        recovered
278            .unprotect_application(b"busy/topic", &beyond)
279            .unwrap()
280            .payload,
281        1001u32.to_be_bytes()
282    );
283}
284
285#[test]
286fn sparse_empty_control_messages_recover_skipped_topics() {
287    // Candidate experiment only: ordinary MLS applications, no new crypto or
288    // runtime repair protocol. The receiver never receives busy payload packets.
289    let admin = Workspace::create([1; 32], "Publisher").unwrap();
290    let (invite, checkpoint) = admin.issue_invitation().unwrap();
291    let pending =
292        PendingJoin::from_invitation(&invite, &checkpoint, [2; 32], "Subscriber").unwrap();
293    let prepared = admin
294        .prepare_admission([2; 32], pending.admission_request().unwrap())
295        .unwrap();
296    let mut proof = pending.join_proof().unwrap();
297    proof
298        .apply_add(&prepared.authorization, &prepared.commit)
299        .unwrap();
300    let receiver = pending
301        .prepare_workspace(&proof, &prepared.welcome)
302        .unwrap();
303    let mut sender = prepared.workspace;
304    let sender_key = StorageKey::derive(&[11; 32]).unwrap();
305    let receiver_key = StorageKey::derive(&[22; 32]).unwrap();
306    let initial = receiver.seal(&receiver_key).unwrap();
307    let workspace = sender.id();
308    let epoch = sender.epoch();
309    let restore =
310        |snapshot: &[u8]| Workspace::restore(&receiver_key, [2; 32], workspace, snapshot).unwrap();
311    let repair_context = b"candidate/empty-ratchet-control/v1";
312    let quiet_context = b"quiet/subscribed-topic";
313    let mut controls = Vec::new();
314    let mut delayed_quiet = Vec::new();
315    let started = std::time::Instant::now();
316    for batch in 0..3 {
317        for _ in 0..512 {
318            let _discarded = sender
319                .protect_application(b"busy/unsubscribed-topic", b"not transferred")
320                .unwrap();
321            // Model the existing durable sender contract before another message.
322            let _committed_sender = sender.seal(&sender_key).unwrap();
323        }
324        if batch == 0 {
325            delayed_quiet = sender
326                .protect_application(quiet_context, b"older subscribed message")
327                .unwrap();
328            let _committed_sender = sender.seal(&sender_key).unwrap();
329        }
330        let control = sender.protect_application(repair_context, b"").unwrap();
331        let _committed_sender = sender.seal(&sender_key).unwrap();
332        controls.push(control);
333    }
334    let target = sender
335        .protect_application(quiet_context, b"current subscribed message")
336        .unwrap();
337    let sender_snapshot = sender.seal(&sender_key).unwrap();
338    let sender = Workspace::restore(&sender_key, [1; 32], workspace, &sender_snapshot).unwrap();
339    assert_eq!(sender.epoch(), epoch); // No membership commit or epoch reset.
340    assert!(
341        restore(&initial)
342            .unprotect_application(quiet_context, &target)
343            .is_err()
344    );
345    assert!(
346        restore(&initial)
347            .unprotect_application(repair_context, &controls[1])
348            .is_err()
349    );
350    assert!(
351        restore(&initial)
352            .unprotect_application(b"wrong context", &controls[0])
353            .is_err()
354    );
355    let mut damaged = controls[0].clone();
356    *damaged.last_mut().unwrap() ^= 1;
357    assert!(
358        restore(&initial)
359            .unprotect_application(repair_context, &damaged)
360            .is_err()
361    );
362    let mut outsider = Workspace::create([3; 32], "Other workspace").unwrap();
363    assert!(
364        outsider
365            .unprotect_application(repair_context, &controls[0])
366            .is_err()
367    );
368
369    let receiver_started = std::time::Instant::now();
370    let mut recovered = restore(&initial);
371    for (index, control) in controls.iter().enumerate() {
372        let before = recovered.seal(&receiver_key).unwrap();
373        // Apply to a disposable owner; persist/adopt only authenticated state.
374        let mut candidate = restore(&before);
375        let decoded = candidate
376            .unprotect_application(repair_context, control)
377            .unwrap();
378        assert!(decoded.payload.is_empty());
379        assert_eq!(decoded.endpoint, [1; 32]);
380        assert_eq!(decoded.member, sender.member().unwrap().id());
381        let saved = candidate.seal(&receiver_key).unwrap();
382        recovered = restore(&saved);
383        assert!(
384            restore(&saved)
385                .unprotect_application(repair_context, control)
386                .is_err()
387        );
388        if index == 0 {
389            // Dropping the middle retained control leaves a gap beyond the limit.
390            assert!(
391                restore(&saved)
392                    .unprotect_application(repair_context, &controls[2])
393                    .is_err()
394            );
395            // An older subscribed message is still recoverable here, before
396            // later controls cause its unused key to leave the reorder window.
397            assert_eq!(
398                restore(&saved)
399                    .unprotect_application(quiet_context, &delayed_quiet)
400                    .unwrap()
401                    .payload,
402                b"older subscribed message"
403            );
404        }
405    }
406    let advanced = recovered.seal(&receiver_key).unwrap();
407    assert!(
408        restore(&advanced)
409            .unprotect_application(quiet_context, &delayed_quiet)
410            .is_err()
411    );
412    let decoded = recovered
413        .unprotect_application(quiet_context, &target)
414        .unwrap();
415    assert_eq!(decoded.payload, b"current subscribed message");
416    assert_eq!(decoded.member, sender.member().unwrap().id());
417    assert_eq!(decoded.endpoint, [1; 32]);
418    let saved = recovered.seal(&receiver_key).unwrap();
419    assert!(
420        restore(&saved)
421            .unprotect_application(quiet_context, &target)
422            .is_err()
423    );
424    // An explicitly complete, ordered batch can preserve both wanted messages.
425    // This is a test oracle, not an authenticated network ordering protocol.
426    // No candidate state or plaintext escapes if any later batch element fails.
427    let apply_batch = |steps: &[(bool, &[u8], &[u8])]| {
428        let mut candidate = restore(&initial);
429        let mut wanted = Vec::new();
430        for (deliver, context, ciphertext) in steps {
431            let message = candidate.unprotect_application(context, ciphertext)?;
432            if message.endpoint != [1; 32] || message.member != sender.member().unwrap().id() {
433                return Err("batch author mismatch");
434            }
435            if *deliver {
436                wanted.push(message.payload);
437            } else if !message.payload.is_empty() {
438                return Err("nonempty recovery control");
439            }
440        }
441        Ok((candidate.seal(&receiver_key)?, wanted))
442    };
443    let ordered: [(bool, &[u8], &[u8]); 5] = [
444        (false, repair_context, &controls[0]),
445        (true, quiet_context, &delayed_quiet),
446        (false, repair_context, &controls[1]),
447        (false, repair_context, &controls[2]),
448        (true, quiet_context, &target),
449    ];
450    let request = RecoveryRequest {
451        workspace,
452        author: sender.member().unwrap().id(),
453        epoch,
454        selection: [8; 32],
455        after: 0,
456        through: 1540,
457    };
458    let response: Vec<_> = ordered
459        .iter()
460        .map(|(_, context, packet)| (*context, *packet))
461        .collect();
462    let signed_offer = sender.sign_recovery_offer(&request, &response).unwrap();
463    let verifier = restore(&initial);
464    let offer = verifier
465        .verify_recovery_offer(&request, &signed_offer)
466        .unwrap();
467    offer.verify_packets(&response).unwrap();
468    let mut omitted_response = response.clone();
469    omitted_response.remove(1);
470    assert!(offer.verify_packets(&omitted_response).is_err());
471    let (batch_snapshot, wanted) = apply_batch(&ordered).unwrap();
472    assert_eq!(
473        wanted,
474        [
475            b"older subscribed message".to_vec(),
476            b"current subscribed message".to_vec()
477        ]
478    );
479    let adopted = restore(&batch_snapshot);
480    let adopted_snapshot = adopted.seal(&receiver_key).unwrap();
481    for packet in [&delayed_quiet, &target] {
482        assert!(
483            restore(&adopted_snapshot)
484                .unprotect_application(quiet_context, packet)
485                .is_err()
486        );
487    }
488    // Authentication of supplied packets does not prove response completeness:
489    // removing an entire wanted packet can still produce an apparently valid batch.
490    let omitted = apply_batch(&[ordered[0], ordered[2], ordered[3], ordered[4]]).unwrap();
491    assert_eq!(omitted.1, [b"current subscribed message".to_vec()]);
492    assert!(
493        restore(&omitted.0)
494            .unprotect_application(quiet_context, &delayed_quiet)
495            .is_err()
496    );
497    let mut reversed = ordered;
498    reversed.reverse();
499    assert!(apply_batch(&reversed).is_err());
500    assert!(apply_batch(&[ordered[0], ordered[1], ordered[3], ordered[4]]).is_err());
501    let mut duplicate = ordered.to_vec();
502    duplicate.insert(2, ordered[1]);
503    assert!(apply_batch(&duplicate).is_err());
504    let mut corrupt_tail = target.clone();
505    *corrupt_tail.last_mut().unwrap() ^= 1;
506    let mut corrupt = ordered;
507    corrupt[4].2 = &corrupt_tail;
508    assert!(apply_batch(&corrupt).is_err());
509    // Failed candidate attempts leave the last committed owner usable. There is
510    // no rollback of a live adopted state and no partial application callback.
511    assert_eq!(apply_batch(&ordered).unwrap().1, wanted);
512    println!(
513        "ordered_control_probe wanted_messages=2 steps=5 reversed_rejected=true missing_middle_rejected=true duplicate_rejected=true corrupt_tail_rejected=true batch_atomicity=memory_only complete_order=fixture_oracle omitted_wanted_undetectable_without_coverage=true signed_offer_rejects_holder_omission=true"
514    );
515    println!(
516        "sparse_control_probe busy_packets_omitted=1536 controls={} control_bytes={} target_bytes={} elapsed_ms={} recovery_ms={} epoch_unchanged=true delayed_quiet_lost_if_controls_advanced_first=true",
517        controls.len(),
518        controls.iter().map(Vec::len).sum::<usize>(),
519        target.len(),
520        started.elapsed().as_millis(),
521        receiver_started.elapsed().as_millis()
522    );
523}