1use super::{
3 ApplicationMessage, MAX_APPLICATION_CIPHERTEXT, MAX_APPLICATION_CONTEXT,
4 MAX_APPLICATION_PAYLOAD, SUITE, Workspace, bootstrap,
5};
6use openmls_traits::{
7 OpenMlsProvider, crypto::OpenMlsCrypto, random::OpenMlsRand, signatures::Signer,
8};
9use sha2::{Digest, Sha256};
10
11const DOMAIN: &[u8] = b"data-fabric/recovery-offer/v1\0";
12const CURRENT_VIEW_DOMAIN: &[u8] = b"data-fabric/current-view-statement/v1\0";
13const SIGNATURE_BYTES: usize = 64;
14pub const MAX_RECOVERY_PACKETS: usize = 32;
15
16#[derive(Clone, Debug)]
20pub struct RecoveryRequest {
21 pub workspace: [u8; 32],
22 pub author: [u8; 32],
23 pub epoch: u64,
24 pub selection: [u8; 32],
25 pub after: u64,
26 pub through: u64,
27}
28impl RecoveryRequest {
29 fn header(&self) -> Result<Vec<u8>, &'static str> {
30 if self.after >= self.through {
31 return Err("invalid recovery request");
32 }
33 let mut bytes = DOMAIN.to_vec();
34 bytes.extend(self.workspace);
35 bytes.extend(self.author);
36 bytes.extend(self.epoch.to_be_bytes());
37 bytes.extend(self.selection);
38 bytes.extend(self.after.to_be_bytes());
39 bytes.extend(self.through.to_be_bytes());
40 Ok(bytes)
41 }
42}
43
44#[derive(Clone, Debug)]
47pub struct RecoveryCutoffRequest {
48 pub workspace: [u8; 32],
49 pub author: [u8; 32],
50 pub epoch: u64,
51 pub selection: [u8; 32],
52 pub policy_revision: u64,
53 pub nonce: [u8; 32],
54}
55impl RecoveryCutoffRequest {
56 fn header(&self) -> Vec<u8> {
57 let mut bytes = b"data-fabric/recovery-cutoff/v2\0".to_vec();
58 bytes.extend(self.workspace);
59 bytes.extend(self.author);
60 bytes.extend(self.epoch.to_be_bytes());
61 bytes.extend(self.selection);
62 bytes.extend(self.policy_revision.to_be_bytes());
63 bytes.extend(self.nonce);
64 bytes
65 }
66}
67
68fn digest(context: &[u8], ciphertext: &[u8]) -> Result<[u8; 32], &'static str> {
69 if context.len() > MAX_APPLICATION_CONTEXT
70 || ciphertext.is_empty()
71 || ciphertext.len() > MAX_APPLICATION_CIPHERTEXT
72 {
73 return Err("recovery packet exceeds bounds");
74 }
75 let mut hash = Sha256::new();
76 hash.update(b"data-fabric/recovery-packet/v1\0");
77 hash.update((context.len() as u32).to_be_bytes());
78 hash.update(context);
79 hash.update((ciphertext.len() as u32).to_be_bytes());
80 hash.update(ciphertext);
81 Ok(hash.finalize().into())
82}
83
84pub struct VerifiedRecoveryOffer<'a> {
87 _membership: &'a Workspace,
88 author: [u8; 32],
89 endpoint: [u8; 32],
90 packets: Vec<[u8; 32]>,
91}
92impl VerifiedRecoveryOffer<'_> {
93 pub fn verify_packets(&self, packets: &[(&[u8], &[u8])]) -> Result<(), &'static str> {
96 if packets.len() != self.packets.len() {
97 return Err("incomplete recovery response");
98 }
99 for ((context, ciphertext), expected) in packets.iter().zip(&self.packets) {
100 if &digest(context, ciphertext)? != expected {
101 return Err("recovery packet or order mismatch");
102 }
103 }
104 Ok(())
105 }
106 pub fn verify_origin(&self, message: &ApplicationMessage) -> Result<(), &'static str> {
109 if message.member != self.author || message.endpoint != self.endpoint {
110 return Err("recovery author mismatch");
111 }
112 Ok(())
113 }
114}
115
116impl Workspace {
117 pub fn sign_current_view(&self, context: &[u8], body: &[u8]) -> Result<Vec<u8>, &'static str> {
120 if self.member.is_none()
121 || context.len() > MAX_APPLICATION_CONTEXT
122 || body.len() > MAX_APPLICATION_PAYLOAD
123 {
124 return Err("current-view statement exceeds bounds or lacks member identity");
125 }
126 let signature = self
127 ._signer
128 .sign(¤t_view_statement(context, body))
129 .map_err(|_| "current-view signing failed")?;
130 let mut signed = body.to_vec();
131 signed.extend(signature);
132 Ok(signed)
133 }
134
135 pub fn verify_current_view<'a>(
138 &self,
139 authority: [u8; 32],
140 context: &[u8],
141 signed: &'a [u8],
142 ) -> Result<&'a [u8], &'static str> {
143 if context.len() > MAX_APPLICATION_CONTEXT
144 || !(SIGNATURE_BYTES..=MAX_APPLICATION_PAYLOAD + SIGNATURE_BYTES)
145 .contains(&signed.len())
146 {
147 return Err("invalid current-view statement size");
148 }
149 let end = signed.len() - SIGNATURE_BYTES;
150 let (_, key) = self.recovery_signer(authority)?;
151 self.provider
152 .crypto()
153 .verify_signature(
154 SUITE.signature_algorithm(),
155 ¤t_view_statement(context, &signed[..end]),
156 &key,
157 &signed[end..],
158 )
159 .map_err(|_| "invalid current-view signature")?;
160 Ok(&signed[..end])
161 }
162
163 pub fn recovery_cutoff_request(
166 &self,
167 peer: [u8; 32],
168 selection: [u8; 32],
169 policy_revision: u64,
170 ) -> Result<RecoveryCutoffRequest, &'static str> {
171 Ok(RecoveryCutoffRequest {
172 workspace: self.id(),
173 author: self.member_id_for_endpoint(peer)?,
174 epoch: self.epoch(),
175 selection,
176 policy_revision,
177 nonce: self
178 .provider
179 .rand()
180 .random_array::<32>()
181 .map_err(|_| "recovery randomness failed")?,
182 })
183 }
184
185 pub fn member_id_for_endpoint(&self, peer: [u8; 32]) -> Result<[u8; 32], &'static str> {
187 let mut author = None;
188 for member in self.group.members() {
189 let (id, endpoint) = bootstrap::binding(&member.credential)?;
190 if endpoint == peer {
191 if author.is_some() {
192 return Err("ambiguous recovery endpoint");
193 }
194 author = Some(id);
195 }
196 }
197 author.ok_or("recovery peer is not a current member")
198 }
199
200 pub fn sign_recovery_cutoff(
203 &self,
204 request: &RecoveryCutoffRequest,
205 head: u64,
206 ) -> Result<Vec<u8>, &'static str> {
207 self.sign_recovery_window(request, 0, head)
208 }
209
210 pub fn sign_recovery_window(
212 &self,
213 request: &RecoveryCutoffRequest,
214 after: u64,
215 head: u64,
216 ) -> Result<Vec<u8>, &'static str> {
217 if after > head {
218 return Err("invalid recovery window");
219 }
220 if request.workspace != self.id()
221 || request.epoch != self.epoch()
222 || self.member().map(|m| m.id()) != Some(request.author)
223 {
224 return Err("invalid recovery cutoff scope");
225 }
226 let mut bytes = request.header();
227 bytes.extend(after.to_be_bytes());
228 bytes.extend(head.to_be_bytes());
229 let signature = self
230 ._signer
231 .sign(&bytes)
232 .map_err(|_| "recovery signing failed")?;
233 bytes.extend(signature);
234 Ok(bytes)
235 }
236
237 pub fn verify_recovery_cutoff(
241 &self,
242 expected: &RecoveryCutoffRequest,
243 bytes: &[u8],
244 ) -> Result<u64, &'static str> {
245 self.verify_recovery_window(expected, bytes)
246 .map(|(_, head)| head)
247 }
248
249 pub fn verify_recovery_window(
250 &self,
251 expected: &RecoveryCutoffRequest,
252 bytes: &[u8],
253 ) -> Result<(u64, u64), &'static str> {
254 if self.member().is_none()
255 || expected.workspace != self.id()
256 || expected.epoch != self.epoch()
257 {
258 return Err("wrong recovery workspace or epoch");
259 }
260 let header = expected.header();
261 if bytes.len() != header.len() + 16 + 64 || !bytes.starts_with(&header) {
262 return Err("invalid recovery cutoff request or size");
263 }
264 let (_, key) = self.recovery_signer(expected.author)?;
265 let end = bytes.len() - 64;
266 self.provider
267 .crypto()
268 .verify_signature(
269 SUITE.signature_algorithm(),
270 &bytes[..end],
271 &key,
272 &bytes[end..],
273 )
274 .map_err(|_| "invalid recovery cutoff signature")?;
275 let after = u64::from_be_bytes(bytes[header.len()..header.len() + 8].try_into().unwrap());
276 let head = u64::from_be_bytes(bytes[header.len() + 8..end].try_into().unwrap());
277 if after > head {
278 return Err("invalid recovery window");
279 }
280 Ok((after, head))
281 }
282
283 fn recovery_signer(&self, author: [u8; 32]) -> Result<([u8; 32], Vec<u8>), &'static str> {
284 let mut signer = None;
285 for member in self.group.members() {
286 let (id, endpoint) = bootstrap::binding(&member.credential)?;
287 if id == author {
288 if signer.is_some() {
289 return Err("ambiguous recovery author");
290 }
291 signer = Some((endpoint, member.signature_key));
292 }
293 }
294 signer.ok_or("recovery author is not a current member")
295 }
296
297 pub fn sign_recovery_offer(
302 &self,
303 request: &RecoveryRequest,
304 packets: &[(&[u8], &[u8])],
305 ) -> Result<Vec<u8>, &'static str> {
306 if request.workspace != self.id()
307 || request.epoch != self.epoch()
308 || self.member().map(|m| m.id()) != Some(request.author)
309 || packets.len() > MAX_RECOVERY_PACKETS
310 {
311 return Err("invalid recovery offer scope or size");
312 }
313 let mut bytes = request.header()?;
314 bytes.extend((packets.len() as u16).to_be_bytes());
315 let mut unique = std::collections::BTreeSet::new();
316 for (context, ciphertext) in packets {
317 let value = digest(context, ciphertext)?;
318 if !unique.insert(value) {
319 return Err("duplicate recovery packet");
320 }
321 bytes.extend(value);
322 }
323 let signature = self
324 ._signer
325 .sign(&bytes)
326 .map_err(|_| "recovery signing failed")?;
327 bytes.extend(signature);
328 Ok(bytes)
329 }
330
331 pub fn verify_recovery_offer<'a>(
334 &'a self,
335 expected: &RecoveryRequest,
336 bytes: &[u8],
337 ) -> Result<VerifiedRecoveryOffer<'a>, &'static str> {
338 if self.member().is_none()
339 || expected.workspace != self.id()
340 || expected.epoch != self.epoch()
341 {
342 return Err("wrong recovery workspace or epoch");
343 }
344 let header = expected.header()?;
345 if bytes.len() < header.len() + 2 + 64
346 || bytes.len() > header.len() + 2 + 32 * MAX_RECOVERY_PACKETS + 64
347 || !bytes.starts_with(&header)
348 {
349 return Err("invalid recovery offer request or size");
350 }
351 let count =
352 u16::from_be_bytes(bytes[header.len()..header.len() + 2].try_into().unwrap()) as usize;
353 let end = header.len() + 2 + 32 * count;
354 if count > MAX_RECOVERY_PACKETS || bytes.len() != end + 64 {
355 return Err("invalid recovery offer count");
356 }
357 let (endpoint, key) = self.recovery_signer(expected.author)?;
358 self.provider
359 .crypto()
360 .verify_signature(
361 SUITE.signature_algorithm(),
362 &bytes[..end],
363 &key,
364 &bytes[end..],
365 )
366 .map_err(|_| "invalid recovery offer signature")?;
367 let packets = bytes[header.len() + 2..end].as_chunks::<32>().0.to_vec();
368 if packets
369 .iter()
370 .collect::<std::collections::BTreeSet<_>>()
371 .len()
372 != packets.len()
373 {
374 return Err("duplicate recovery digest");
375 }
376 Ok(VerifiedRecoveryOffer {
377 _membership: self,
378 author: expected.author,
379 endpoint,
380 packets,
381 })
382 }
383}
384
385fn current_view_statement(context: &[u8], body: &[u8]) -> Vec<u8> {
386 let mut bytes = CURRENT_VIEW_DOMAIN.to_vec();
387 bytes.extend((context.len() as u32).to_be_bytes());
388 bytes.extend(context);
389 bytes.extend((body.len() as u32).to_be_bytes());
390 bytes.extend(body);
391 bytes
392}
393
394#[test]
395fn recovery_offer_authenticates_request_and_exact_packet_set() {
396 use crate::{PendingJoin, StorageKey};
397 let admin = Workspace::create([1; 32], "Publisher").unwrap();
398 let (invite, checkpoint) = admin.issue_invitation().unwrap();
399 let pending = PendingJoin::from_invitation(&invite, &checkpoint, [2; 32], "Reader").unwrap();
400 let prepared = admin
401 .prepare_admission([2; 32], pending.admission_request().unwrap())
402 .unwrap();
403 let mut proof = pending.join_proof().unwrap();
404 proof
405 .apply_add(&prepared.authorization, &prepared.commit)
406 .unwrap();
407 let receiver = pending
408 .prepare_workspace(&proof, &prepared.welcome)
409 .unwrap();
410 let mut sender = prepared.workspace;
411 let key = StorageKey::derive(&[9; 32]).unwrap();
412 let before = receiver.seal(&key).unwrap();
413 let first_request = receiver
414 .recovery_cutoff_request(sender.endpoint(), [4; 32], 7)
415 .unwrap();
416 let next_request = receiver
417 .recovery_cutoff_request(sender.endpoint(), [4; 32], 7)
418 .unwrap();
419 assert_eq!(first_request.author, sender.member().unwrap().id());
420 assert_ne!(first_request.nonce, next_request.nonce);
421 assert!(
422 receiver
423 .recovery_cutoff_request([99; 32], [4; 32], 7)
424 .is_err()
425 );
426 let reply = sender.sign_recovery_cutoff(&first_request, 52).unwrap();
427 assert!(
428 receiver
429 .verify_recovery_cutoff(&next_request, &reply)
430 .is_err()
431 );
432 let cutoff = RecoveryCutoffRequest {
433 workspace: sender.id(),
434 author: sender.member().unwrap().id(),
435 epoch: sender.epoch(),
436 selection: [4; 32],
437 policy_revision: 7,
438 nonce: [5; 32],
439 };
440 let window = sender.sign_recovery_window(&cutoff, 32, 52).unwrap();
441 assert_eq!(
442 receiver.verify_recovery_window(&cutoff, &window).unwrap(),
443 (32, 52)
444 );
445 assert!(sender.sign_recovery_window(&cutoff, 53, 52).is_err());
446 let mut changed_window = window.clone();
447 changed_window[cutoff.header().len()] ^= 1;
448 assert!(
449 receiver
450 .verify_recovery_window(&cutoff, &changed_window)
451 .is_err()
452 );
453 for head in [0, 1, 52, u64::MAX] {
454 let bytes = sender.sign_recovery_cutoff(&cutoff, head).unwrap();
455 assert_eq!(
456 receiver.verify_recovery_cutoff(&cutoff, &bytes).unwrap(),
457 head
458 );
459 for cut in 0..bytes.len() {
460 assert!(
461 receiver
462 .verify_recovery_cutoff(&cutoff, &bytes[..cut])
463 .is_err()
464 );
465 }
466 let mut trailing = bytes.clone();
467 trailing.push(0);
468 assert!(receiver.verify_recovery_cutoff(&cutoff, &trailing).is_err());
469 for offset in [cutoff.header().len(), bytes.len() - 1] {
470 let mut damaged = bytes.clone();
471 damaged[offset] ^= 1;
472 assert!(receiver.verify_recovery_cutoff(&cutoff, &damaged).is_err());
473 }
474 for field in 0..6 {
475 let mut changed = cutoff.clone();
476 match field {
477 0 => changed.workspace[0] ^= 1,
478 1 => changed.author[0] ^= 1,
479 2 => changed.epoch += 1,
480 3 => changed.selection[0] ^= 1,
481 4 => changed.policy_revision += 1,
482 _ => changed.nonce[0] ^= 1,
483 }
484 assert!(receiver.verify_recovery_cutoff(&changed, &bytes).is_err());
485 }
486 let mut forged = bytes[..bytes.len() - 64].to_vec();
488 let signature = receiver._signer.sign(&forged).unwrap();
489 forged.extend(signature);
490 assert!(receiver.verify_recovery_cutoff(&cutoff, &forged).is_err());
491 }
492 assert!(receiver.sign_recovery_cutoff(&cutoff, 52).is_err());
493 let mut ciphertexts = Vec::new();
494 for value in [b"first".as_slice(), b"second"] {
495 ciphertexts.push(
496 sender
497 .protect_application(b"opaque context", value)
498 .unwrap(),
499 );
500 let _saved_sender = sender.seal(&key).unwrap();
501 }
502 let packets: Vec<_> = ciphertexts
503 .iter()
504 .map(|p| (b"opaque context".as_slice(), p.as_slice()))
505 .collect();
506 let request = RecoveryRequest {
507 workspace: sender.id(),
508 author: sender.member().unwrap().id(),
509 epoch: sender.epoch(),
510 selection: [4; 32],
511 after: 1,
512 through: 3,
513 };
514 let encoded = sender.sign_recovery_offer(&request, &packets).unwrap();
515 assert!(receiver.verify_recovery_cutoff(&cutoff, &encoded).is_err());
516 assert!(
517 receiver
518 .verify_recovery_offer(&request, &sender.sign_recovery_cutoff(&cutoff, 52).unwrap())
519 .is_err()
520 );
521 let verified = receiver.verify_recovery_offer(&request, &encoded).unwrap();
522 verified.verify_packets(&packets).unwrap();
523 assert!(verified.verify_packets(&packets[..1]).is_err());
524 assert!(verified.verify_packets(&[packets[1], packets[0]]).is_err());
525 assert!(verified.verify_packets(&[packets[0], packets[0]]).is_err());
526 assert!(
527 verified
528 .verify_packets(&[(b"wrong context".as_slice(), packets[0].1), packets[1]])
529 .is_err()
530 );
531 let mut damaged_packet = ciphertexts[0].clone();
532 damaged_packet[0] ^= 1;
533 assert!(
534 verified
535 .verify_packets(&[(packets[0].0, damaged_packet.as_slice()), packets[1]])
536 .is_err()
537 );
538 for offset in [0, encoded.len() - 65, encoded.len() - 1] {
539 let mut damaged = encoded.clone();
540 damaged[offset] ^= 1;
541 assert!(receiver.verify_recovery_offer(&request, &damaged).is_err());
542 }
543 let mut forged = encoded[..encoded.len() - 64].to_vec();
544 let signature = receiver._signer.sign(&forged).unwrap();
545 forged.extend(signature);
546 assert!(receiver.verify_recovery_offer(&request, &forged).is_err());
547 let mut invalid_count = encoded.clone();
548 let offset = request.header().unwrap().len();
549 invalid_count[offset..offset + 2].copy_from_slice(&0u16.to_be_bytes());
550 assert!(
551 receiver
552 .verify_recovery_offer(&request, &invalid_count)
553 .is_err()
554 );
555 let mut trailing = encoded.clone();
556 trailing.push(0);
557 assert!(receiver.verify_recovery_offer(&request, &trailing).is_err());
558 assert!(
559 receiver
560 .verify_recovery_offer(&request, &encoded[..encoded.len() - 1])
561 .is_err()
562 );
563 for field in 0..6 {
564 let mut wrong = request.clone();
565 match field {
566 0 => wrong.workspace[0] ^= 1,
567 1 => wrong.author[0] ^= 1,
568 2 => wrong.epoch += 1,
569 3 => wrong.selection[0] ^= 1,
570 4 => wrong.after = 0,
571 _ => wrong.through += 1,
572 }
573 assert!(receiver.verify_recovery_offer(&wrong, &encoded).is_err());
574 }
575 assert!(receiver.sign_recovery_offer(&request, &packets).is_err());
576 let outsider = Workspace::create([5; 32], "Outsider").unwrap();
577 assert!(outsider.verify_recovery_offer(&request, &encoded).is_err());
578 let empty = sender.sign_recovery_offer(&request, &[]).unwrap();
579 let verified_empty = receiver.verify_recovery_offer(&request, &empty).unwrap();
580 verified_empty.verify_packets(&[]).unwrap();
581 assert!(verified_empty.verify_packets(&packets).is_err());
582 assert!(
583 sender
584 .sign_recovery_offer(&request, &[packets[0]; MAX_RECOVERY_PACKETS + 1])
585 .is_err()
586 );
587 assert!(
588 sender
589 .sign_recovery_offer(&request, &[packets[0]; 2])
590 .is_err()
591 );
592 assert!(sender.sign_recovery_offer(&request, &[(b"", b"")]).is_err());
593 assert!(
594 sender
595 .sign_recovery_offer(&request, &[(&[0; MAX_APPLICATION_CONTEXT + 1], b"x")])
596 .is_err()
597 );
598 assert!(
599 sender
600 .sign_recovery_offer(&request, &[(b"", &[0; MAX_APPLICATION_CIPHERTEXT + 1])])
601 .is_err()
602 );
603 let mut invalid = request.clone();
604 invalid.through = invalid.after;
605 assert!(sender.sign_recovery_offer(&invalid, &packets).is_err());
606 let mut candidate = Workspace::restore(&key, [2; 32], receiver.id(), &before).unwrap();
607 for (context, packet) in &packets {
608 let mut message = candidate.unprotect_application(context, packet).unwrap();
609 verified.verify_origin(&message).unwrap();
610 message.endpoint = [8; 32];
611 assert!(verified.verify_origin(&message).is_err());
612 message.endpoint = [1; 32];
613 message.member = [8; 32];
614 assert!(verified.verify_origin(&message).is_err());
615 }
616 let saved = candidate.seal(&key).unwrap();
617 let mut restored = Workspace::restore(&key, [2; 32], receiver.id(), &saved).unwrap();
618 assert!(
619 restored
620 .unprotect_application(packets[0].0, packets[0].1)
621 .is_err()
622 );
623 let incomplete = sender.sign_recovery_offer(&request, &packets[1..]).unwrap();
626 receiver
627 .verify_recovery_offer(&request, &incomplete)
628 .unwrap()
629 .verify_packets(&packets[1..])
630 .unwrap();
631 drop(sender); receiver
633 .verify_recovery_offer(&request, &encoded)
634 .unwrap()
635 .verify_packets(&packets)
636 .unwrap();
637}