Debian Codegraph @

third_party/rust/mls-platform-api/src/lib.rs

raw
1 // Copyright (c) 2024 Mozilla Corporation and contributors.
2 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
3
4 mod state;
5
6 use mls_rs::error::{AnyError, IntoAnyError};
7 use mls_rs::group::proposal::{CustomProposal, ProposalType};
8 use mls_rs::group::{Capabilities, CommitEffect, ExportedTree, ReceivedMessage};
9 use mls_rs::identity::SigningIdentity;
10 use mls_rs::mls_rs_codec::{MlsDecode, MlsEncode};
11 use mls_rs::{CipherSuiteProvider, CryptoProvider, Extension, ExtensionList};
12
13 use serde::de::{self, MapAccess, Visitor};
14 use serde::ser::SerializeStruct;
15 use serde::{Deserialize, Deserializer, Serialize, Serializer};
16
17 pub use state::{PlatformState, TemporaryState};
18 use std::fmt;
19
20 pub type DefaultCryptoProvider = mls_rs_crypto_nss::NssCryptoProvider;
21 pub type DefaultIdentityProvider = mls_rs::identity::basic::BasicIdentityProvider;
22
23 // Re-export the mls_rs types
24 pub use mls_rs::CipherSuite;
25 pub use mls_rs::MlsMessage;
26 pub use mls_rs::ProtocolVersion;
27
28 // Define new types
29 pub type GroupState = Vec<u8>;
30
31 pub type MlsGroupId = Vec<u8>;
32 pub type MlsGroupIdArg<'a> = &'a [u8];
33
34 pub type MlsGroupEpoch = u64;
35
36 pub type MlsCredential = Vec<u8>;
37 pub type MlsCredentialArg<'a> = &'a [u8];
38
39 pub type Identity = Vec<u8>;
40 pub type IdentityArg<'a> = &'a [u8];
41
42 #[derive(Debug, Clone)]
43 #[allow(clippy::large_enum_variant)]
44 pub enum MessageOrAck {
45 Ack(MlsGroupId),
46 MlsMessage(MlsMessage),
47 }
48
49 ///
50 /// Errors
51 ///
52 #[derive(Debug, thiserror::Error)]
53 pub enum PlatformError {
54 #[error("CoreError")]
55 CoreError,
56 #[error(transparent)]
57 LibraryError(#[from] mls_rs::error::MlsError),
58 #[error("InternalError")]
59 InternalError,
60 #[error("IdentityError")]
61 IdentityError(AnyError),
62 #[error("CryptoError")]
63 CryptoError(AnyError),
64 #[error("UnsupportedCiphersuite")]
65 UnsupportedCiphersuite,
66 #[error("UnsupportedGroupConfig")]
67 UnsupportedGroupConfig,
68 #[error("UnsupportedMessage")]
69 UnsupportedMessage,
70 #[error("UndefinedIdentity")]
71 UndefinedIdentity,
72 #[error("StorageError")]
73 StorageError(AnyError),
74 #[error("UnavailableSecret")]
75 UnavailableSecret,
76 #[error("MutexError")]
77 MutexError,
78 #[error("JsonConversionError")]
79 JsonConversionError,
80 #[error(transparent)]
81 CodecError(#[from] mls_rs::mls_rs_codec::Error),
82 #[error(transparent)]
83 BincodeError(#[from] bincode::Error),
84 #[error(transparent)]
85 IOError(#[from] std::io::Error),
86 }
87
88 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
89 pub struct GroupIdEpoch {
90 pub group_id: MlsGroupId,
91 pub group_epoch: MlsGroupEpoch,
92 }
93
94 ///
95 /// Generate or Retrieve a PlatformState.
96 ///
97 pub fn state_access(name: &str, key: &[u8; 32]) -> Result<PlatformState, PlatformError> {
98 PlatformState::new(name, key)
99 }
100
101 ///
102 /// Delete a PlatformState.
103 ///
104 pub fn state_delete(name: &str) -> Result<(), PlatformError> {
105 PlatformState::delete(name)
106 }
107
108 ///
109 /// Delete a specific group in the PlatformState.
110 ///
111 pub fn state_delete_group(
112 state: &PlatformState,
113 gid: MlsGroupIdArg,
114 myself: IdentityArg,
115 ) -> Result<GroupIdEpoch, PlatformError> {
116 state.delete_group(gid, myself)?;
117
118 // Return the group id and 0xFF..FF epoch to signal the group is closed
119 Ok(GroupIdEpoch {
120 group_id: gid.to_vec(),
121 group_epoch: 0xFFFFFFFFFFFFFFFF,
122 })
123 }
124
125 ///
126 /// Configurations
127 ///
128
129 // Possibly temporary, allows to add an option to the config without changing every
130 // call to client() function
131 #[derive(Clone, Debug, Default)]
132 pub struct ClientConfig {
133 pub key_package_extensions: Option<ExtensionList>,
134 pub leaf_node_extensions: Option<ExtensionList>,
135 pub leaf_node_capabilities: Option<Capabilities>,
136 pub key_package_lifetime_s: Option<u64>,
137 pub allow_external_commits: bool,
138 }
139
140 // Assuming GroupConfig is a struct
141 #[derive(Debug, Clone)]
142 pub struct GroupConfig {
143 pub ciphersuite: CipherSuite,
144 pub version: ProtocolVersion,
145 pub options: ExtensionList,
146 }
147
148 impl Default for GroupConfig {
149 fn default() -> Self {
150 GroupConfig {
151 // Set default ciphersuite.
152 ciphersuite: CipherSuite::CURVE25519_AES128,
153 // Set default protocol version.
154 version: ProtocolVersion::MLS_10,
155 // Set default options.
156 options: ExtensionList::new(),
157 }
158 }
159 }
160
161 ///
162 /// Generate a credential.
163 ///
164 pub fn mls_generate_credential_basic(content: &[u8]) -> Result<MlsCredential, PlatformError> {
165 let credential =
166 mls_rs::identity::basic::BasicCredential::new(content.to_vec()).into_credential();
167 let credential_bytes = credential.mls_encode_to_vec()?;
168 Ok(credential_bytes)
169 }
170
171 ///
172 /// Generate a Signature Keypair
173 ///
174 pub fn mls_generate_identity(
175 state: &PlatformState,
176 cs: CipherSuite,
177 // _randomness: Option<Vec<u8>>,
178 ) -> Result<Vec<u8>, PlatformError> {
179 let crypto_provider = DefaultCryptoProvider::default();
180 let cipher_suite = crypto_provider
181 .cipher_suite_provider(cs)
182 .ok_or(PlatformError::UnsupportedCiphersuite)?;
183
184 // Generate a signature key pair.
185 let (signature_key, signature_pubkey) = cipher_suite
186 .signature_key_generate()
187 .map_err(|_| PlatformError::UnsupportedCiphersuite)?;
188
189 let cipher_suite_provider = crypto_provider
190 .cipher_suite_provider(cs)
191 .ok_or(PlatformError::UnsupportedCiphersuite)?;
192
193 let identifier = cipher_suite_provider
194 .hash(&signature_pubkey)
195 .map_err(|e| PlatformError::CryptoError(e.into_any_error()))?;
196
197 // Store the signature key pair.
198 state.insert_sigkey(&signature_key, &signature_pubkey, cs, &identifier)?;
199
200 Ok(identifier)
201 }
202
203 ///
204 /// Generate a KeyPackage.
205 ///
206 pub fn mls_generate_key_package(
207 state: &PlatformState,
208 myself: IdentityArg,
209 credential: MlsCredentialArg,
210 config: &ClientConfig,
211 // _randomness: Option<Vec<u8>>,
212 ) -> Result<MlsMessage, PlatformError> {
213 // Decode the Credential
214 let mut credential_slice: &[u8] = credential;
215 let decoded_cred = mls_rs::identity::Credential::mls_decode(&mut credential_slice)?;
216
217 // Create a client for that state
218 let client = state.client(myself, Some(decoded_cred), ProtocolVersion::MLS_10, config)?;
219
220 // Generate a KeyPackage from that client_default
221 let key_package_extensions = config.key_package_extensions.clone().unwrap_or_default();
222 let leaf_node_extensions = config.leaf_node_extensions.clone().unwrap_or_default();
223
224 let key_package =
225 client.generate_key_package_message(key_package_extensions, leaf_node_extensions)?;
226
227 // Result
228 Ok(key_package)
229 }
230
231 ///
232 /// Get group members.
233 ///
234
235 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
236 pub struct ClientIdentifiers {
237 pub identity: Identity,
238 pub credential: MlsCredential,
239 // TODO: identities: Vec<(Identity, Credential, ExtensionList, Capabilities)>,
240 }
241
242 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
243 pub struct GroupDetails {
244 pub group_id: MlsGroupId,
245 pub group_epoch: u64,
246 pub group_members: Vec<ClientIdentifiers>,
247 }
248
249 // Note: The identity is needed because it is allowed to have multiple
250 // identities in a group.
251 pub fn mls_group_details(
252 state: &PlatformState,
253 gid: MlsGroupIdArg,
254 myself: IdentityArg,
255 ) -> Result<GroupDetails, PlatformError> {
256 let crypto_provider = DefaultCryptoProvider::default();
257
258 let group = state.client_default(myself)?.load_group(gid)?;
259 let epoch = group.current_epoch();
260
261 let cipher_suite_provider = crypto_provider
262 .cipher_suite_provider(group.cipher_suite())
263 .ok_or(PlatformError::UnsupportedCiphersuite)?;
264
265 // Return Vec<(Identity, Credential)>
266 let members = group
267 .roster()
268 .member_identities_iter()
269 .map(|identity| {
270 Ok(ClientIdentifiers {
271 identity: cipher_suite_provider
272 .hash(&identity.signature_key)
273 .map_err(|e| PlatformError::CryptoError(e.into_any_error()))?,
274 credential: identity.credential.mls_encode_to_vec()?,
275 })
276 })
277 .collect::<Result<Vec<_>, PlatformError>>()?;
278
279 let group_details = GroupDetails {
280 group_id: gid.to_vec(),
281 group_epoch: epoch,
282 group_members: members,
283 };
284
285 Ok(group_details)
286 }
287
288 ///
289 /// Group management: Create a Group
290 ///
291
292 // Note: We internally set the protocol version to avoid issues with compat
293 pub fn mls_group_create(
294 pstate: &mut PlatformState,
295 myself: IdentityArg,
296 credential: MlsCredentialArg,
297 gid: Option<MlsGroupIdArg>,
298 group_context_extensions: Option<ExtensionList>,
299 config: &ClientConfig,
300 ) -> Result<GroupIdEpoch, PlatformError> {
301 // Build the client
302 let mut credential_slice: &[u8] = credential;
303 let decoded_cred = mls_rs::identity::Credential::mls_decode(&mut credential_slice)?;
304
305 let client = pstate.client(myself, Some(decoded_cred), ProtocolVersion::MLS_10, config)?;
306
307 // Generate a GroupId if none is provided
308 let mut group = match gid {
309 Some(gid) => client.create_group_with_id(
310 gid.to_vec(),
311 group_context_extensions.unwrap_or_default().clone(),
312 config.leaf_node_extensions.clone().unwrap_or_default(),
313 )?,
314 None => client.create_group(
315 group_context_extensions.unwrap_or_default().clone(),
316 config.leaf_node_extensions.clone().unwrap_or_default(),
317 )?,
318 };
319
320 // The state needs to be returned or stored somewhere
321 group.write_to_storage()?;
322 let gid = group.group_id().to_vec();
323 let epoch = group.current_epoch();
324
325 // Return
326 Ok(GroupIdEpoch {
327 group_id: gid,
328 group_epoch: epoch,
329 })
330 }
331
332 ///
333 /// Group management: Adding a user.
334 ///
335
336 #[derive(Clone, Debug, PartialEq)]
337 pub struct MlsCommitOutput {
338 pub commit: MlsMessage,
339 pub welcome: Vec<MlsMessage>,
340 pub group_info: Option<MlsMessage>,
341 pub ratchet_tree: Option<Vec<u8>>,
342 // pub unused_proposals: Vec<crate::mls_rules::ProposalInfo<Proposal>>, from mls_rs
343 pub identity: Option<Identity>,
344 }
345
346 impl Serialize for MlsCommitOutput {
347 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
348 where
349 S: Serializer,
350 {
351 let mut state = serializer.serialize_struct("MlsCommitOutput", 4)?;
352
353 // Handle serialization for `commit`
354 let commit_bytes = self
355 .commit
356 .mls_encode_to_vec()
357 .map_err(serde::ser::Error::custom)?;
358 state.serialize_field("commit", &commit_bytes)?;
359
360 // Handle serialization for `welcome`. Collect into a Result to handle potential errors.
361 let welcome_bytes: Result<Vec<_>, _> = self
362 .welcome
363 .iter()
364 .map(|msg| msg.mls_encode_to_vec().map_err(serde::ser::Error::custom))
365 .collect();
366 // Unwrap the Result here, after all potential errors have been handled.
367 state.serialize_field("welcome", &welcome_bytes?)?;
368
369 // Handle serialization for `group_info`
370 let group_info_bytes = match self.group_info.as_ref().map(|gi| gi.mls_encode_to_vec()) {
371 Some(Ok(bytes)) => Some(bytes),
372 Some(Err(e)) => return Err(serde::ser::Error::custom(e)),
373 None => None,
374 };
375 state.serialize_field("group_info", &group_info_bytes)?;
376
377 // Directly serialize `ratchet_tree` as it is already an Option<Vec<u8>>
378 state.serialize_field("ratchet_tree", &self.ratchet_tree)?;
379
380 state.end()
381 }
382 }
383
384 impl<'de> Deserialize<'de> for MlsCommitOutput {
385 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
386 where
387 D: Deserializer<'de>,
388 {
389 struct MlsCommitOutputVisitor;
390
391 impl<'de> Visitor<'de> for MlsCommitOutputVisitor {
392 type Value = MlsCommitOutput;
393
394 fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
395 formatter.write_str("struct MlsCommitOutput")
396 }
397
398 fn visit_map<V>(self, mut map: V) -> Result<MlsCommitOutput, V::Error>
399 where
400 V: MapAccess<'de>,
401 {
402 let mut commit = None;
403 let mut welcome = None;
404 let mut group_info = None;
405 let mut ratchet_tree = None;
406
407 while let Some(key) = map.next_key::<String>()? {
408 match key.as_str() {
409 "commit" => {
410 let value: Vec<u8> = map.next_value()?;
411 commit = Some(
412 MlsMessage::mls_decode(&mut &value[..])
413 .map_err(de::Error::custom)?,
414 );
415 }
416 "welcome" => {
417 let values: Vec<Vec<u8>> = map.next_value()?;
418 welcome = Some(
419 values
420 .into_iter()
421 .map(|v| {
422 MlsMessage::mls_decode(&mut &v[..])
423 .map_err(de::Error::custom)
424 })
425 .collect::<Result<_, _>>()?,
426 );
427 }
428 "group_info" => {
429 if let Some(value) = map.next_value::<Option<Vec<u8>>>()? {
430 group_info = Some(
431 MlsMessage::mls_decode(&mut &value[..])
432 .map_err(de::Error::custom)?,
433 );
434 }
435 }
436 "ratchet_tree" => {
437 ratchet_tree = map.next_value()?;
438 }
439 _ => { /* Ignore unknown fields */ }
440 }
441 }
442
443 Ok(MlsCommitOutput {
444 commit: commit.ok_or_else(|| de::Error::missing_field("commit"))?,
445 welcome: welcome.ok_or_else(|| de::Error::missing_field("welcome"))?,
446 group_info,
447 ratchet_tree,
448 identity: None,
449 })
450 }
451 }
452
453 const FIELDS: &[&str] = &["commit", "welcome", "group_info", "ratchet_tree"];
454 deserializer.deserialize_struct("MlsCommitOutput", FIELDS, MlsCommitOutputVisitor)
455 }
456 }
457
458 pub fn mls_group_add(
459 pstate: &mut PlatformState,
460 gid: MlsGroupIdArg,
461 myself: IdentityArg,
462 new_members: Vec<MlsMessage>,
463 ) -> Result<MlsCommitOutput, PlatformError> {
464 // Get the group from the state
465 let client = pstate.client_default(myself)?;
466 let mut group = client.load_group(gid)?;
467
468 let commit_output = new_members
469 .into_iter()
470 .try_fold(group.commit_builder(), |commit_builder, user| {
471 commit_builder.add_member(user)
472 })?
473 .build()?;
474
475 // We use the default mode which returns only one welcome message
476 let welcomes = commit_output.welcome_messages; //.remove(0);
477
478 let commit_output = MlsCommitOutput {
479 commit: commit_output.commit_message.clone(),
480 welcome: welcomes,
481 group_info: commit_output.external_commit_group_info,
482 ratchet_tree: None, // TODO: Handle this !
483 identity: None,
484 };
485
486 // Write the group to the storage
487 group.write_to_storage()?;
488
489 Ok(commit_output)
490 }
491
492 pub fn mls_group_propose_add(
493 pstate: &mut PlatformState,
494 gid: MlsGroupIdArg,
495 myself: IdentityArg,
496 new_member: MlsMessage,
497 ) -> Result<MlsMessage, PlatformError> {
498 let client = pstate.client_default(myself)?;
499 let mut group = client.load_group(gid)?;
500
501 let proposal = group.propose_add(new_member, vec![])?;
502 group.write_to_storage()?;
503
504 Ok(proposal.clone())
505 }
506
507 // Variant 1: Vec<MlsMessage>
508 // pub fn mls_group_propose_add(
509 // pstate: &mut PlatformState,
510 // gid: &MlsGroupId,
511 // myself: &Identity,
512 // new_members: Vec<MlsMessage>,
513 // ) -> Result<MlsMessage, PlatformError> {
514 // let client = pstate.client_default(myself)?;
515 // let mut group = client.load_group(gid)?;
516
517 // let proposals: Result<Vec<_>, _> = new_members
518 // .into_iter()
519 // .map(|member| group.propose_add(member, vec![]))
520 // .collect();
521 // let proposals = proposals?;
522
523 // let proposal = proposals.first().unwrap();
524 // group.write_to_storage()?;
525
526 // Ok(proposal.clone())
527 // }
528
529 ///
530 /// Group management: Removing a user.
531 ///
532 pub fn mls_group_remove(
533 pstate: &PlatformState,
534 gid: MlsGroupIdArg,
535 myself: IdentityArg,
536 removed: IdentityArg, // TODO: Make this Vec<Identities>?
537 ) -> Result<MlsCommitOutput, PlatformError> {
538 let mut group = pstate.client_default(myself)?.load_group(gid)?;
539
540 let crypto_provider = DefaultCryptoProvider::default();
541
542 let cipher_suite_provider = crypto_provider
543 .cipher_suite_provider(group.cipher_suite())
544 .ok_or(PlatformError::UnsupportedCiphersuite)?;
545
546 let removed = group
547 .roster()
548 .members_iter()
549 .find_map(|m| {
550 let h = cipher_suite_provider
551 .hash(&m.signing_identity.signature_key)
552 .ok()?;
553 (h == *removed).then_some(m.index)
554 })
555 .ok_or(PlatformError::UndefinedIdentity)?;
556 // Handle separate error message for inability to remove yourself
557
558 let commit = group.commit_builder().remove_member(removed)?.build()?;
559
560 // Write the group to the storage
561 group.write_to_storage()?;
562
563 let commit_output = MlsCommitOutput {
564 commit: commit.commit_message,
565 welcome: commit.welcome_messages,
566 group_info: commit.external_commit_group_info,
567 ratchet_tree: commit
568 .ratchet_tree
569 .map(|tree| tree.to_bytes())
570 .transpose()?,
571 identity: None,
572 };
573
574 Ok(commit_output)
575 }
576
577 pub fn mls_group_propose_remove(
578 pstate: &PlatformState,
579 gid: MlsGroupIdArg,
580 myself: IdentityArg,
581 removed: IdentityArg, // TODO: Make this Vec<Identities>?
582 ) -> Result<MlsMessage, PlatformError> {
583 let mut group = pstate.client_default(myself)?.load_group(gid)?;
584
585 let crypto_provider = DefaultCryptoProvider::default();
586
587 let cipher_suite_provider = crypto_provider
588 .cipher_suite_provider(group.cipher_suite())
589 .ok_or(PlatformError::UnsupportedCiphersuite)?;
590
591 let removed = group
592 .roster()
593 .members_iter()
594 .find_map(|m| {
595 let h = cipher_suite_provider
596 .hash(&m.signing_identity.signature_key)
597 .ok()?;
598 (h == *removed).then_some(m.index)
599 })
600 .ok_or(PlatformError::UndefinedIdentity)?;
601
602 let proposal = group.propose_remove(removed, vec![])?;
603
604 // Remember the proposal
605 group.write_to_storage()?;
606
607 Ok(proposal)
608 }
609
610 ///
611 /// Key updates
612 ///
613
614 /// TODO: Possibly add a random nonce as an optional parameter.
615 pub fn mls_group_update(
616 pstate: &mut PlatformState,
617 gid: MlsGroupIdArg,
618 myself: IdentityArg,
619 signature_key: Option<&[u8]>,
620 credential: Option<MlsCredentialArg>,
621 group_context_extensions: Option<ExtensionList>,
622 config: &ClientConfig,
623 ) -> Result<MlsCommitOutput, PlatformError> {
624 let crypto_provider = DefaultCryptoProvider::default();
625
626 // Propose + Commit
627 let decoded_cred = credential
628 .as_ref()
629 .map(|credential| {
630 let mut credential_slice: &[u8] = credential;
631 mls_rs::identity::Credential::mls_decode(&mut credential_slice)
632 })
633 .transpose()?;
634
635 let client = pstate.client(myself, decoded_cred, ProtocolVersion::MLS_10, config)?;
636 let mut group = client.load_group(gid)?;
637
638 let cipher_suite_provider = crypto_provider
639 .cipher_suite_provider(group.cipher_suite())
640 .ok_or(PlatformError::UnsupportedCiphersuite)?;
641
642 let mut commit_builder = group.commit_builder();
643
644 if let Some(group_context_extensions) = group_context_extensions {
645 commit_builder = commit_builder.set_group_context_ext(group_context_extensions)?;
646 }
647
648 if let Some(leaf_node_extensions) = config.leaf_node_extensions.clone() {
649 commit_builder = commit_builder.set_leaf_node_extensions(leaf_node_extensions);
650 }
651
652 let identity = if let Some((key, cred)) = signature_key.zip(credential) {
653 let signature_secret_key = key.to_vec().into();
654 let signature_public_key = cipher_suite_provider
655 .signature_key_derive_public(&signature_secret_key)
656 .map_err(|e| PlatformError::CryptoError(e.into_any_error()))?;
657
658 let mut credential_slice: &[u8] = cred;
659 let decoded_cred = mls_rs::identity::Credential::mls_decode(&mut credential_slice)?;
660 let signing_identity = SigningIdentity::new(decoded_cred, signature_public_key);
661
662 // Return the identity
663 cipher_suite_provider
664 .hash(&signing_identity.signature_key)
665 .map_err(|e| PlatformError::CryptoError(e.into_any_error()))?
666 } else {
667 myself.to_vec().into()
668 };
669
670 let commit = commit_builder.build()?;
671
672 group.write_to_storage()?;
673
674 let commit_output = MlsCommitOutput {
675 commit: commit.commit_message,
676 welcome: commit.welcome_messages,
677 group_info: commit.external_commit_group_info,
678 ratchet_tree: commit
679 .ratchet_tree
680 .map(|tree| tree.to_bytes())
681 .transpose()?,
682 identity: Some(identity),
683 };
684 // Generate the signature keypair
685 // Return the signing Identity
686 // Hash the signingIdentity to get the Identifier
687
688 Ok(commit_output)
689 }
690
691 ///
692 /// Process Welcome message.
693 ///
694
695 pub fn mls_group_join(
696 pstate: &PlatformState,
697 myself: IdentityArg,
698 welcome: &MlsMessage,
699 ratchet_tree: Option<ExportedTree<'static>>,
700 ) -> Result<GroupIdEpoch, PlatformError> {
701 let client = pstate.client_default(myself)?;
702 let (mut group, _info) = client.join_group(ratchet_tree, welcome)?;
703 let gid = group.group_id().to_vec();
704 let epoch = group.current_epoch();
705
706 // Store the state
707 group.write_to_storage()?;
708
709 // Return the group identifier
710 Ok(GroupIdEpoch {
711 group_id: gid,
712 group_epoch: epoch,
713 })
714 }
715
716 ///
717 /// Close a group by removing all members.
718 ///
719
720 // TODO: Define a custom proposal instead.
721 pub fn mls_group_close(
722 pstate: &PlatformState,
723 gid: MlsGroupIdArg,
724 myself: IdentityArg,
725 ) -> Result<MlsCommitOutput, PlatformError> {
726 // Remove everyone from the group.
727 let mut group = pstate.client_default(myself)?.load_group(gid)?;
728 let self_index = group.current_member_index();
729
730 let all_but_me = group
731 .roster()
732 .members_iter()
733 .filter_map(|m| (m.index != self_index).then_some(m.index))
734 .collect::<Vec<_>>();
735
736 let commit_output = all_but_me
737 .into_iter()
738 .try_fold(group.commit_builder(), |builder, index| {
739 builder.remove_member(index)
740 })?
741 .build()?;
742
743 let commit_output = MlsCommitOutput {
744 commit: commit_output.commit_message.clone(),
745 welcome: vec![],
746 group_info: commit_output.external_commit_group_info,
747 ratchet_tree: None, // TODO: Handle this !
748 identity: None,
749 };
750 // TODO we should delete state when we receive an ACK. but it's not super clear how to
751 // determine on receive that this was a "close" commit. Would be easier if we had a custom
752 // proposal
753
754 // Write the group to the storage
755 group.write_to_storage()?;
756
757 Ok(commit_output)
758 }
759
760 ///
761 /// Receive a message
762 ///
763
764 #[derive(Clone, Debug, PartialEq)]
765 #[allow(clippy::large_enum_variant)]
766 pub enum Received {
767 None,
768 ApplicationMessage(Vec<u8>),
769 GroupIdEpoch(GroupIdEpoch),
770 CommitOutput(MlsCommitOutput),
771 }
772
773 pub fn mls_receive(
774 pstate: &PlatformState,
775 myself: IdentityArg,
776 message_or_ack: &MessageOrAck,
777 ) -> Result<(Vec<u8>, Received), PlatformError> {
778 // Extract the gid from the Message
779 let gid = match &message_or_ack {
780 MessageOrAck::Ack(gid) => gid,
781 MessageOrAck::MlsMessage(message) => match message.group_id() {
782 Some(gid) => gid,
783 None => return Err(PlatformError::UnsupportedMessage),
784 },
785 };
786
787 let mut group = pstate.client_default(myself)?.load_group(gid)?;
788
789 let received_message = match &message_or_ack {
790 MessageOrAck::Ack(_) => group.apply_pending_commit().map(ReceivedMessage::Commit),
791 MessageOrAck::MlsMessage(message) => group.process_incoming_message(message.clone()),
792 };
793
794 //
795 let result = match received_message? {
796 ReceivedMessage::ApplicationMessage(app_data_description) => Ok((
797 gid.to_vec(),
798 Received::ApplicationMessage(app_data_description.data().to_vec()),
799 )),
800 ReceivedMessage::Proposal(_proposal) => {
801 // TODO: We inconditionally return the commit for the received proposal
802 let commit = group.commit(vec![])?;
803
804 group.write_to_storage()?;
805
806 let commit_output = MlsCommitOutput {
807 commit: commit.commit_message,
808 welcome: commit.welcome_messages,
809 group_info: commit.external_commit_group_info,
810 ratchet_tree: commit
811 .ratchet_tree
812 .map(|tree| tree.to_bytes())
813 .transpose()?,
814 identity: None,
815 };
816 Ok((gid.to_vec(), Received::CommitOutput(commit_output)))
817 }
818 ReceivedMessage::Commit(commit) => {
819 // Check if the group is active or not after applying the commit
820 match commit.effect {
821 CommitEffect::Removed { .. } => {
822 // Delete the group from the state of the client
823 pstate.delete_group(gid, myself)?;
824
825 // Return the group id and 0xFF..FF epoch to signal the group is closed
826 let group_epoch = GroupIdEpoch {
827 group_id: group.group_id().to_vec(),
828 group_epoch: 0xFFFFFFFFFFFFFFFF,
829 };
830
831 Ok((gid.to_vec(), Received::GroupIdEpoch(group_epoch)))
832 }
833 _ => {
834 // TODO: Receiving a group_close commit means the sender receiving
835 // is left alone in the group. We should be able delete group automatically.
836 // As of now, the user calling group_close has to delete group manually.
837
838 // If this is a normal commit, return the affected group and new epoch
839 let group_epoch = GroupIdEpoch {
840 group_id: group.group_id().to_vec(),
841 group_epoch: group.current_epoch(),
842 };
843
844 Ok((gid.to_vec(), Received::GroupIdEpoch(group_epoch)))
845 }
846 }
847 }
848 // TODO: We could make this more user friendly by allowing to
849 // pass a Welcome message. KeyPackages should be rejected.
850 _ => Err(PlatformError::UnsupportedMessage),
851 }?;
852
853 // Write the state to storage
854 group.write_to_storage()?;
855
856 Ok(result)
857 }
858
859 pub fn mls_has_pending_proposals(
860 pstate: &PlatformState,
861 gid: MlsGroupIdArg,
862 myself: IdentityArg,
863 ) -> Result<bool, PlatformError> {
864 let group = pstate.client_default(myself)?.load_group(gid)?;
865 let result = group.commit_required();
866 Ok(result)
867 }
868
869 pub fn mls_clear_pending_proposals(
870 pstate: &PlatformState,
871 gid: MlsGroupIdArg,
872 myself: IdentityArg,
873 ) -> Result<bool, PlatformError> {
874 let mut group = pstate.client_default(myself)?.load_group(gid)?;
875 group.clear_proposal_cache();
876 group.write_to_storage()?;
877 Ok(true)
878 }
879
880 pub fn mls_has_pending_commit(
881 pstate: &PlatformState,
882 gid: MlsGroupIdArg,
883 myself: IdentityArg,
884 ) -> Result<bool, PlatformError> {
885 let group = pstate.client_default(myself)?.load_group(gid)?;
886 let result = group.has_pending_commit();
887 Ok(result)
888 }
889
890 pub fn mls_clear_pending_commit(
891 pstate: &PlatformState,
892 gid: MlsGroupIdArg,
893 myself: IdentityArg,
894 ) -> Result<bool, PlatformError> {
895 let mut group = pstate.client_default(myself)?.load_group(gid)?;
896 group.clear_pending_commit();
897 group.write_to_storage()?;
898 Ok(true)
899 }
900
901 pub fn mls_apply_pending_commit(
902 pstate: &PlatformState,
903 gid: MlsGroupIdArg,
904 myself: IdentityArg,
905 ) -> Result<Received, PlatformError> {
906 let mut group = pstate.client_default(myself)?.load_group(gid)?;
907
908 let received_message = group.apply_pending_commit().map(ReceivedMessage::Commit);
909
910 // Check if the group is active or not after applying the commit
911 let result = match received_message? {
912 ReceivedMessage::Commit(commit) => {
913 // Check if the group is active or not after applying the commit
914 match commit.effect {
915 CommitEffect::Removed { .. } => {
916 // Delete the group from the state of the client
917 pstate.delete_group(gid, myself)?;
918
919 // Return the group id and 0xFF..FF epoch to signal the group is closed
920 let group_epoch = GroupIdEpoch {
921 group_id: group.group_id().to_vec(),
922 group_epoch: 0xFFFFFFFFFFFFFFFF,
923 };
924
925 Ok(Received::GroupIdEpoch(group_epoch))
926 }
927 _ => {
928 // TODO: Receiving a group_close commit means the sender receiving
929 // is left alone in the group. We should be able delete group automatically.
930 // As of now, the user calling group_close has to delete group manually.
931
932 // If this is a normal commit, return the affected group and new epoch
933 let group_epoch = GroupIdEpoch {
934 group_id: group.group_id().to_vec(),
935 group_epoch: group.current_epoch(),
936 };
937
938 Ok(Received::GroupIdEpoch(group_epoch))
939 }
940 }
941 }
942 _ => Err(PlatformError::UnsupportedMessage),
943 }?;
944
945 // Write the state to storage
946 group.write_to_storage()?;
947
948 Ok(result)
949 }
950
951 //
952 // Encrypt a message.
953 //
954
955 pub fn mls_send(
956 pstate: &PlatformState,
957 gid: MlsGroupIdArg,
958 myself: IdentityArg,
959 message: &[u8],
960 ) -> Result<MlsMessage, PlatformError> {
961 let mut group = pstate.client_default(myself)?.load_group(gid)?;
962
963 let out = group.encrypt_application_message(message, vec![])?;
964 group.write_to_storage()?;
965
966 Ok(out)
967 }
968
969 ///
970 /// Propose + Commit a GroupContextExtension
971 ///
972 pub fn mls_send_group_context_extension(
973 pstate: &PlatformState,
974 gid: MlsGroupIdArg,
975 myself: IdentityArg,
976 new_gce: Vec<Extension>,
977 ) -> Result<mls_rs::MlsMessage, PlatformError> {
978 let mut group = pstate.client_default(myself)?.load_group(&gid)?;
979
980 let commit = group
981 .commit_builder()
982 .set_group_context_ext(new_gce.into())?
983 .build()?;
984
985 Ok(commit.commit_message)
986 }
987
988 ///
989 /// Create and send a custom proposal.
990 ///
991 pub fn mls_send_custom_proposal(
992 pstate: &PlatformState,
993 gid: MlsGroupIdArg,
994 myself: IdentityArg,
995 proposal_type: ProposalType,
996 data: Vec<u8>,
997 ) -> Result<mls_rs::MlsMessage, PlatformError> {
998 let mut group = pstate.client_default(myself)?.load_group(&gid)?;
999 let custom_proposal = CustomProposal::new(proposal_type, data);
1000 let proposal = group.propose_custom(custom_proposal, vec![])?;
1001
1002 Ok(proposal)
1003 }
1004
1005 ///
1006 /// Export a group secret.
1007 ///
1008
1009 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
1010 pub struct ExporterOutput {
1011 pub group_id: MlsGroupId,
1012 pub group_epoch: MlsGroupEpoch,
1013 pub label: Vec<u8>,
1014 pub context: Vec<u8>,
1015 pub exporter: Vec<u8>,
1016 }
1017
1018 pub fn mls_derive_exporter(
1019 pstate: &PlatformState,
1020 gid: MlsGroupIdArg,
1021 myself: IdentityArg,
1022 label: &[u8],
1023 context: &[u8],
1024 len: u64,
1025 ) -> Result<ExporterOutput, PlatformError> {
1026 let group = pstate.client_default(myself)?.load_group(gid)?;
1027 let secret = group
1028 .export_secret(label, context, len.try_into().unwrap())?
1029 .to_vec();
1030
1031 // Construct the output object
1032 let epoch_and_exporter = ExporterOutput {
1033 group_id: gid.to_vec(),
1034 group_epoch: group.current_epoch(),
1035 label: label.to_vec(),
1036 context: label.to_vec(),
1037 exporter: secret,
1038 };
1039
1040 Ok(epoch_and_exporter)
1041 }
1042
1043 ///
1044 /// Join a group using the external commit mechanism
1045 ///
1046
1047 #[derive(Clone, Debug, PartialEq)]
1048 pub struct MlsExternalCommitOutput {
1049 pub gid: MlsGroupId,
1050 pub external_commit: MlsMessage,
1051 }
1052
1053 impl Serialize for MlsExternalCommitOutput {
1054 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1055 where
1056 S: Serializer,
1057 {
1058 let mut state = serializer.serialize_struct("MlsExternalCommitOutput", 2)?;
1059 state.serialize_field("gid", &self.gid)?;
1060
1061 // Handle serialization for `commit`
1062 let external_commit_bytes = self
1063 .external_commit
1064 .mls_encode_to_vec()
1065 .map_err(serde::ser::Error::custom)?;
1066
1067 state.serialize_field("external_commit", &external_commit_bytes)?;
1068
1069 state.end()
1070 }
1071 }
1072
1073 impl<'de> Deserialize<'de> for MlsExternalCommitOutput {
1074 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1075 where
1076 D: Deserializer<'de>,
1077 {
1078 struct MlsExternalCommitOutputVisitor;
1079
1080 impl<'de> Visitor<'de> for MlsExternalCommitOutputVisitor {
1081 type Value = MlsExternalCommitOutput;
1082
1083 fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
1084 formatter.write_str("struct MlsExternalCommitOutput")
1085 }
1086
1087 fn visit_map<V>(self, mut map: V) -> Result<MlsExternalCommitOutput, V::Error>
1088 where
1089 V: MapAccess<'de>,
1090 {
1091 let mut gid = None;
1092 let mut external_commit = None;
1093
1094 while let Some(key) = map.next_key::<String>()? {
1095 match key.as_str() {
1096 "external_commit" => {
1097 let value: Vec<u8> = map.next_value()?;
1098 external_commit = Some(
1099 MlsMessage::mls_decode(&mut &value[..])
1100 .map_err(de::Error::custom)?,
1101 );
1102 }
1103 "gid" => gid = Some(map.next_value()?),
1104 _ => { /* Ignore unknown fields */ }
1105 }
1106 }
1107
1108 Ok(MlsExternalCommitOutput {
1109 gid: gid.ok_or_else(|| de::Error::missing_field("gid"))?,
1110 external_commit: external_commit
1111 .ok_or_else(|| de::Error::missing_field("external_commit"))?,
1112 })
1113 }
1114 }
1115
1116 const FIELDS: &[&str] = &["gid", "external_commit"];
1117 deserializer.deserialize_struct(
1118 "MlsExternalCommitOutput",
1119 FIELDS,
1120 MlsExternalCommitOutputVisitor,
1121 )
1122 }
1123 }
1124
1125 pub fn mls_group_external_commit(
1126 pstate: &PlatformState,
1127 myself: IdentityArg,
1128 credential: MlsCredentialArg,
1129 group_info: &MlsMessage,
1130 ratchet_tree: Option<ExportedTree<'static>>,
1131 ) -> Result<MlsExternalCommitOutput, PlatformError> {
1132 // Clone the credential to avoid mutating the original
1133 let mut credential_slice: &[u8] = credential;
1134
1135 // Decode the credential
1136 let decoded_cred = mls_rs::identity::Credential::mls_decode(&mut credential_slice)?;
1137
1138 let client = pstate.client(
1139 myself,
1140 Some(decoded_cred),
1141 ProtocolVersion::MLS_10,
1142 &ClientConfig::default(),
1143 )?;
1144
1145 let mut commit_builder = client.external_commit_builder()?;
1146
1147 if let Some(ratchet_tree) = ratchet_tree {
1148 commit_builder = commit_builder.with_tree_data(ratchet_tree);
1149 }
1150
1151 let (mut group, external_commit) = commit_builder.build(group_info.clone())?;
1152 let gid = group.group_id().to_vec();
1153
1154 // Store the state
1155 group.write_to_storage()?;
1156
1157 // Encode the output
1158 let gid_and_message = MlsExternalCommitOutput {
1159 gid,
1160 external_commit,
1161 };
1162
1163 Ok(gid_and_message)
1164 }
1165
1166 ///
1167 /// Utility functions
1168 ///
1169
1170 pub fn mls_get_group_id(message_or_ack: &MessageOrAck) -> Result<Vec<u8>, PlatformError> {
1171 // Extract the gid from the Message
1172 let gid = match &message_or_ack {
1173 MessageOrAck::Ack(gid) => gid,
1174 MessageOrAck::MlsMessage(message) => match message.group_id() {
1175 Some(gid) => gid,
1176 None => return Err(PlatformError::UnsupportedMessage),
1177 },
1178 };
1179
1180 Ok(gid.to_vec())
1181 }
1182
1183 pub fn mls_get_group_epoch(message_or_ack: &MessageOrAck) -> Result<u64, PlatformError> {
1184 let group_epoch: Option<u64> = match &message_or_ack {
1185 MessageOrAck::MlsMessage(message) => message.epoch(),
1186 _ => None,
1187 };
1188
1189 Ok(group_epoch.expect("Group epoch not found"))
1190 }
1191
1192 // TODO:
1193 // - Is key available for the message ?