Skip to main content

arachne_security/
object.rs

1//! Signed, independently decryptable current-epoch objects. Delivery owns replay
2//! records and application handoff; successful authentication is not delivery.
3use super::{
4    ApplicationMessage, MAX_APPLICATION_CIPHERTEXT, MAX_APPLICATION_CONTEXT,
5    MAX_APPLICATION_PAYLOAD, SUITE, Workspace, bootstrap,
6};
7use openmls_traits::{OpenMlsProvider, crypto::OpenMlsCrypto, signatures::Signer};
8use sframe::{
9    CipherSuite,
10    frame::{EncryptedFrameView, MediaFrameView, MonotonicCounter},
11    key::{DecryptionKey, EncryptionKey},
12};
13use zeroize::Zeroizing;
14
15const MAGIC: &[u8] = b"DFSO\x01";
16const HEADER: usize = 5 + 32 + 8 + 4;
17const SIGNATURE: usize = 64;
18const DOMAIN: &[u8] = b"data-fabric/signed-object/v1\0";
19// A namespaced application record in the already persisted provider snapshot.
20// It is not an OpenMLS storage key or a second uncommitted state store.
21const COUNTER: &[u8] = b"data-fabric/object-sender-counter/v1\0";
22const CIPHER: CipherSuite = CipherSuite::AesGcm256Sha512;
23
24#[derive(Debug, PartialEq, Eq)]
25pub struct AuthenticatedObject {
26    pub message: ApplicationMessage,
27    /// Scoped to the authenticated author and current workspace epoch.
28    pub counter: u64,
29}
30
31#[test]
32fn objects_are_independent_authenticated_and_current_epoch_only() {
33    use super::{PendingJoin, StorageKey};
34    let admin = Workspace::create([1; 32], "Publisher").unwrap();
35    let (invite, checkpoint) = admin.issue_invitation().unwrap();
36    let pending = PendingJoin::from_invitation(&invite, &checkpoint, [2; 32], "Reader").unwrap();
37    let prepared = admin
38        .prepare_admission([2; 32], pending.admission_request().unwrap())
39        .unwrap();
40    let mut proof = pending.join_proof().unwrap();
41    proof
42        .apply_add(&prepared.authorization, &prepared.commit)
43        .unwrap();
44    let mut reader = pending
45        .prepare_workspace(&proof, &prepared.welcome)
46        .unwrap();
47    let mut sender = prepared.workspace;
48    let storage_key = StorageKey::derive(&[11; 32]).unwrap();
49    let old = sender
50        .protect_object(b"chat/first", b"retained chat")
51        .unwrap();
52    let size = sender.seal(&storage_key).unwrap().len();
53    for _ in 0..10_000 {
54        sender.protect_object(b"feed", b"opaque sample").unwrap();
55    }
56    let live = sender.protect_object(b"chat/latest", b"live chat").unwrap();
57    assert_eq!(
58        reader
59            .unprotect_object(b"chat/latest", &live)
60            .unwrap()
61            .counter,
62        10_002
63    );
64    let first = reader.unprotect_object(b"chat/first", &old).unwrap();
65    assert_eq!(first.counter, 1);
66    assert_eq!(first.message.payload, b"retained chat");
67    assert_eq!(first.message.endpoint, sender.endpoint());
68    assert_eq!(first.message.member, sender.member().unwrap().id());
69    assert_eq!(size, sender.seal(&storage_key).unwrap().len());
70    // No ratchet/replay side effects in crypto; delivery must suppress repeats.
71    assert_eq!(reader.unprotect_object(b"chat/first", &old).unwrap(), first);
72    assert!(reader.unprotect_object(b"feed", &old).is_err());
73    let outsider = Workspace::create([3; 32], "Other workspace").unwrap();
74    assert!(outsider.unprotect_object(b"chat/first", &old).is_err());
75    for offset in [0, 5, 37, 45, HEADER, old.len() - 1] {
76        let mut changed = old.clone();
77        changed[offset] ^= 1;
78        assert!(reader.unprotect_object(b"chat/first", &changed).is_err());
79    }
80    let mut forged = old.clone();
81    let end = forged.len() - SIGNATURE;
82    let signature = reader
83        ._signer
84        .sign(&signed(b"chat/first", &forged[..end]))
85        .unwrap();
86    forged[end..].copy_from_slice(&signature);
87    assert_eq!(
88        reader.unprotect_object(b"chat/first", &forged).unwrap_err(),
89        "object signature invalid"
90    );
91    for len in 0..old.len() {
92        assert!(reader.unprotect_object(b"chat/first", &old[..len]).is_err());
93    }
94    assert!(
95        sender
96            .protect_object(&vec![0; MAX_APPLICATION_CONTEXT + 1], b"")
97            .is_err()
98    );
99    assert!(
100        sender
101            .protect_object(b"", &vec![0; MAX_APPLICATION_PAYLOAD + 1])
102            .is_err()
103    );
104    let maximum = sender
105        .protect_object(b"max", &vec![7; MAX_APPLICATION_PAYLOAD])
106        .unwrap();
107    assert_eq!(
108        reader
109            .unprotect_object(b"max", &maximum)
110            .unwrap()
111            .message
112            .payload
113            .len(),
114        MAX_APPLICATION_PAYLOAD
115    );
116    let saved = sender.seal(&storage_key).unwrap();
117    sender = Workspace::restore(&storage_key, sender.endpoint(), sender.id(), &saved).unwrap();
118    let next = sender.protect_object(b"after-restore", b"chat").unwrap();
119    assert_eq!(
120        reader
121            .unprotect_object(b"after-restore", &next)
122            .unwrap()
123            .counter,
124        10_004
125    );
126
127    // Accepted removal closes the old epoch for both live and catch-up objects.
128    sender
129        .group
130        .remove_members(
131            &sender.provider,
132            &sender._signer,
133            &[reader.group.own_leaf_index()],
134        )
135        .unwrap();
136    sender.group.merge_pending_commit(&sender.provider).unwrap();
137    let backdated = reader
138        .protect_object(b"old-claim", b"manufactured after removal")
139        .unwrap();
140    assert_eq!(
141        sender
142            .unprotect_object(b"old-claim", &backdated)
143            .unwrap_err(),
144        "object epoch not current"
145    );
146    assert_eq!(
147        sender.unprotect_object(b"chat/first", &old).unwrap_err(),
148        "object epoch not current"
149    );
150    let fresh = sender
151        .protect_object(b"new-epoch", b"private to current members")
152        .unwrap();
153    assert_eq!(
154        sender
155            .unprotect_object(b"new-epoch", &fresh)
156            .unwrap()
157            .counter,
158        1
159    );
160    assert!(reader.unprotect_object(b"new-epoch", &fresh).is_err());
161
162    let epoch = sender.epoch();
163    sender.provider.storage().values.write().unwrap().insert(
164        COUNTER.to_vec(),
165        [epoch.to_be_bytes(), u64::MAX.to_be_bytes()].concat(),
166    );
167    assert_eq!(
168        sender.protect_object(b"", b"").unwrap_err(),
169        "object counter exhausted"
170    );
171    sender
172        .provider
173        .storage()
174        .values
175        .write()
176        .unwrap()
177        .insert(COUNTER.to_vec(), vec![0]);
178    let malformed = sender.seal(&storage_key).unwrap();
179    assert!(Workspace::restore(&storage_key, sender.endpoint(), sender.id(), &malformed).is_err());
180}
181
182fn signed(context: &[u8], object: &[u8]) -> Vec<u8> {
183    [
184        DOMAIN,
185        &(context.len() as u32).to_be_bytes(),
186        context,
187        object,
188    ]
189    .concat()
190}
191
192fn key_id(epoch: u64, leaf: u32) -> u64 {
193    // RFC9605 5.2, E=16 and context=0; no other context is accepted. Since
194    // context=0, S does not affect the encoding. Only one epoch is retained.
195    (u64::from(leaf) << 16) | (epoch & 0xffff)
196}
197
198impl Workspace {
199    fn object_secret(&self) -> Result<Zeroizing<Vec<u8>>, &'static str> {
200        self.group
201            .export_secret(self.provider.crypto(), "SFrame 1.0 Base Key", b"", 32)
202            .map(Zeroizing::new)
203            .map_err(|_| "object key unavailable")
204    }
205
206    pub(super) fn object_counter(&self) -> Result<u64, &'static str> {
207        let state = self
208            .provider
209            .storage()
210            .values
211            .read()
212            .map_err(|_| "storage unavailable")?;
213        let Some(value) = state.get(COUNTER) else {
214            return Ok(0);
215        };
216        if value.len() != 16 {
217            return Err("invalid object counter state");
218        }
219        let epoch = u64::from_be_bytes(value[..8].try_into().unwrap());
220        let counter = u64::from_be_bytes(value[8..].try_into().unwrap());
221        if epoch > self.epoch() || counter == 0 {
222            return Err("invalid object counter state");
223        }
224        Ok(if epoch == self.epoch() { counter } else { 0 })
225    }
226
227    /// Host MUST durably save the resulting owner before releasing this object.
228    /// Retries resend the exact object. Never restore an older committed sender
229    /// state to retry encryption. On error discard the candidate, as with MLS.
230    pub fn protect_object(
231        &mut self,
232        context: &[u8],
233        payload: &[u8],
234    ) -> Result<Vec<u8>, &'static str> {
235        if self.member.is_none()
236            || context.len() > MAX_APPLICATION_CONTEXT
237            || payload.len() > MAX_APPLICATION_PAYLOAD
238        {
239            return Err("object exceeds bounds or lacks member identity");
240        }
241        let counter = self
242            .object_counter()?
243            .checked_add(1)
244            .ok_or("object counter exhausted")?;
245        let epoch = self.epoch();
246        let leaf = self.group.own_leaf_index().u32();
247        let secret = self.object_secret()?;
248        let key = EncryptionKey::derive_from(CIPHER, key_id(epoch, leaf), secret.as_slice())
249            .map_err(|_| "object key unavailable")?;
250        let mut nonce = MonotonicCounter::with_start_value(counter, counter);
251        let frame = MediaFrameView::with_meta_data(&mut nonce, payload, context)
252            .encrypt(&key)
253            .map_err(|_| "object encryption failed")?;
254        let mut object = MAGIC.to_vec();
255        object.extend(self.id());
256        object.extend(epoch.to_be_bytes());
257        object.extend(leaf.to_be_bytes());
258        // Owning SFrame buffers include metadata; our caller reconstructs it.
259        object.extend(&frame.as_ref()[frame.meta_data().len()..]);
260        object.extend(
261            self._signer
262                .sign(&signed(context, &object))
263                .map_err(|_| "object signing failed")?,
264        );
265        if object.len() > MAX_APPLICATION_CIPHERTEXT {
266            return Err("object exceeds bounds");
267        }
268        self.provider
269            .storage()
270            .values
271            .write()
272            .map_err(|_| "storage unavailable")?
273            .insert(
274                COUNTER.to_vec(),
275                [epoch.to_be_bytes(), counter.to_be_bytes()].concat(),
276            );
277        Ok(object)
278    }
279
280    /// Authenticate using the CURRENT accepted epoch/roster only. Does not import
281    /// historical epochs, mutate a ratchet or suppress replay. The delivery layer
282    /// must atomically record acceptance and pending application work before use.
283    pub fn unprotect_object(
284        &self,
285        context: &[u8],
286        object: &[u8],
287    ) -> Result<AuthenticatedObject, &'static str> {
288        if context.len() > MAX_APPLICATION_CONTEXT
289            || !(HEADER + 2 + 16 + SIGNATURE..=MAX_APPLICATION_CIPHERTEXT).contains(&object.len())
290            || !object.starts_with(MAGIC)
291            || object[5..37] != self.id()
292        {
293            return Err("invalid object envelope");
294        }
295        let epoch = u64::from_be_bytes(object[37..45].try_into().unwrap());
296        if epoch != self.epoch() {
297            return Err("object epoch not current");
298        }
299        let leaf = u32::from_be_bytes(object[45..HEADER].try_into().unwrap());
300        let author = self
301            .group
302            .members()
303            .find(|member| member.index.u32() == leaf)
304            .ok_or("object author not current");
305        let author = author?;
306        let (member, endpoint) = bootstrap::binding(&author.credential)?;
307        let (body, signature) = object.split_at(object.len() - SIGNATURE);
308        self.provider
309            .crypto()
310            .verify_signature(
311                SUITE.signature_algorithm(),
312                &signed(context, body),
313                &author.signature_key,
314                signature,
315            )
316            .map_err(|_| "object signature invalid")?;
317        let frame = EncryptedFrameView::try_with_meta_data(&body[HEADER..], context)
318            .map_err(|_| "invalid encrypted object")?;
319        if frame.header().key_id() != key_id(epoch, leaf) || frame.header().counter() == 0 {
320            return Err("object key or counter mismatch");
321        }
322        let secret = self.object_secret()?;
323        let key = DecryptionKey::derive_from(CIPHER, key_id(epoch, leaf), secret.as_slice())
324            .map_err(|_| "object key unavailable")?;
325        let plain = frame
326            .decrypt(&key)
327            .map_err(|_| "object authentication failed")?;
328        if plain.payload().len() > MAX_APPLICATION_PAYLOAD {
329            return Err("object payload exceeds bounds");
330        }
331        Ok(AuthenticatedObject {
332            counter: frame.header().counter(),
333            message: ApplicationMessage {
334                member,
335                endpoint,
336                payload: plain.payload().to_vec(),
337            },
338        })
339    }
340}