Struct MlsGroup 

pub struct MlsGroup { /* private fields */ }

Available on 32-bit or 64-bit only.

A MlsGroup represents an MLS group with a high-level API. The API exposes high level functions to manage a group by adding/removing members, get the current member list, etc.

The API is modeled such that it can serve as a direct interface to the Delivery Service. Functions that modify the public state of the group will return a Vec<MLSMessageOut> that can be sent to the Delivery Service directly. Conversely, incoming messages from the Delivery Service can be fed into process_message().

An MlsGroup has an internal queue of pending proposals that builds up as new messages are processed. When creating proposals, those messages are not automatically appended to this queue, instead they have to be processed again through process_message(). This allows the Delivery Service to reject them (e.g. if they reference the wrong epoch).

If incoming messages or applied operations are semantically or syntactically incorrect, an error event will be returned with a corresponding error message and the state of the group will remain unchanged.

An MlsGroup has an internal state variable determining if it is active or inactive, as well as if it has a pending commit. See MlsGroupState for more information.

Implementations

impl MlsGroup

pub fn create_message<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, message: &[u8], ) -> Result<MlsMessageOut, CreateMessageError<Provider::StorageError>>

Available on crate feature virtual-clients-draft and (crate features test-utils) only.

Creates an application message. Returns CreateMessageError::MlsGroupStateError::UseAfterEviction if the member is no longer part of the group. Returns CreateMessageError::MlsGroupStateError::PendingProposal if pending proposals exist. In that case .process_pending_proposals() must be called first and incoming messages from the DS must be processed afterwards.

pub fn create_unconfirmed_message<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, message: &[u8], ) -> Result<UnconfirmedMessage, CreateMessageError<Provider::StorageError>>

Available on crate feature virtual-clients-draft only.

Creates an application message. Encryption secrets are only deleted after the message has been confirmed via confirm_application_message().

Returns the ratchet generation used for encryption, an optional GenerationId, and the encrypted message. The generation is passed back to confirm_application_message to delete the retained encryption secret once the DS has accepted the message. The GenerationId is present when the group is bound to a derivation epoch and None otherwise. When present, the application attaches it to the fanned-out message so a strongly-consistent DS can detect generation collisions between siblings.

Returns CreateMessageError::MlsGroupStateError::UseAfterEviction if the member is no longer part of the group. Returns CreateMessageError::MlsGroupStateError::PendingProposal if pending proposals exist. In that case .process_pending_proposals() must be called first and incoming messages from the DS must be processed afterwards.

pub fn confirm_application_message<Storage: StorageProvider>( &mut self, storage: &Storage, epoch: GroupEpoch, generation: u32, ) -> Result<(), ConfirmMessageError<Storage::Error>>

Available on crate feature virtual-clients-draft only.

Deletes the retained encryption secret of the application message created at (epoch, generation). A confirm call deletes exactly the secret its corresponding MlsGroup::create_unconfirmed_message call retained, or nothing.

This is a no-op success when the epoch has aged out of the message secrets store, or when the generation’s secret is already gone (already confirmed, or consumed by processing the message’s own echo).

Returns ConfirmMessageError::FutureEpoch when epoch is newer than the group’s current epoch.

Only confirm once the DS has accepted exactly this message. After a lost race against a sibling (the DS rejected the send because of a generation collision), the secret must not be confirmed, since it is what decrypts the sibling’s winning message at the same generation.

pub fn confirm_handshake_message<Storage: StorageProvider>( &mut self, storage: &Storage, epoch: GroupEpoch, generation: u32, ) -> Result<(), ConfirmMessageError<Storage::Error>>

Available on crate feature virtual-clients-draft only.

Deletes the retained encryption secret of the handshake message (proposal or commit) created at (epoch, generation). A confirm call deletes exactly the secret its corresponding create call retained, or nothing.

Proposals and commits draw generations from the same per-epoch handshake ratchet, so this single endpoint covers both.

This is a no-op success when the epoch has aged out of the message secrets store, or when the generation’s secret is already gone (already confirmed, or consumed by processing the message’s own echo).

Returns ConfirmMessageError::FutureEpoch when epoch is newer than the group’s current epoch.

Only confirm once the DS has accepted exactly this message. After a lost race against a sibling (the DS rejected the send because of a generation collision), the secret must not be confirmed, since it is what decrypts the sibling’s winning message at the same generation.

impl MlsGroup

pub fn export_secret<CryptoProvider: OpenMlsCrypto>( &self, crypto: &CryptoProvider, label: &str, context: &[u8], key_length: usize, ) -> Result<Vec<u8>, ExportSecretError>

Exports a secret from the current epoch. Returns ExportSecretError::KeyLengthTooLong if the requested key length is too long. Returns ExportSecretError::GroupStateError(MlsGroupStateError::UseAfterEviction) if the group is not active.

pub fn safe_export_secret<Crypto: OpenMlsCrypto, Storage: StorageProvider>( &mut self, crypto: &Crypto, storage: &Storage, component_id: ComponentId, ) -> Result<Vec<u8>, SafeExportSecretError<Storage::Error>>

Available on crate feature extensions-draft only.

Export a secret from the forward secure exporter for the component with the given component ID.

pub fn safe_export_secret_from_pending<Provider: StorageProvider>( &mut self, crypto: &impl OpenMlsCrypto, storage: &Provider, component_id: ComponentId, ) -> Result<Vec<u8>, PendingSafeExportSecretError<Provider::Error>>

Available on crate feature extensions-draft only.

Export a secret from the forward secure exporter of the pending commit state for the component with the given component ID.

pub fn epoch_authenticator(&self) -> &EpochAuthenticator

Returns the epoch authenticator of the current epoch.

pub fn resumption_psk_secret(&self) -> &ResumptionPskSecret

Returns the resumption PSK secret of the current epoch.

pub fn get_past_resumption_psk( &self, epoch: GroupEpoch, ) -> Option<&ResumptionPskSecret>

Returns a resumption psk for a given epoch. If no resumption psk is available for that epoch, None is returned.

pub fn export_group_info<CryptoProvider: OpenMlsCrypto>( &self, crypto: &CryptoProvider, signer: &impl Signer, with_ratchet_tree: bool, ) -> Result<MlsMessageOut, ExportGroupInfoError>

Export a group info object for this group.

pub fn export_group_info_with_additional_extensions<CryptoProvider: OpenMlsCrypto>( &self, crypto: &CryptoProvider, signer: &impl Signer, with_ratchet_tree: bool, additional_extensions: impl IntoIterator<Item = Extension>, ) -> Result<MlsMessageOut, ExportGroupInfoError>

Export a group info object for this group, with additional extensions.

Returns an error if a RatchetTreeExtension or ExternalPubExtension is added directly here.

impl MlsGroup

pub fn self_update<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, leaf_node_parameters: LeafNodeParameters, ) -> Result<CommitMessageBundle, SelfUpdateError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Updates the own leaf node. The application can choose to update the credential, the capabilities, and the extensions by buliding the LeafNodeParameters.

If successful, it returns a tuple of MlsMessageOut (containing the commit), an optional MlsMessageOut (containing the Welcome) and the GroupInfo. The Welcome is Some when the queue of pending proposals contained add proposals The GroupInfo is Some if the group has the use_ratchet_tree_extension flag set.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use MlsGroup::commit_builder, whose CommitMessageBundle::confirmation surfaces the handshake confirmation data.

pub fn self_update_with_new_signer<Provider: OpenMlsProvider, S: Signer>( &mut self, provider: &Provider, old_signer: &impl Signer, new_signer: NewSignerBundle<'_, S>, leaf_node_parameters: LeafNodeParameters, ) -> Result<CommitMessageBundle, SelfUpdateError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Updates the own leaf node. The application can choose to update the credential, the capabilities, and the extensions by buliding the LeafNodeParameters.

In contrast to self_update, this function allows updating the signature public key in the senders leaf node. Note that new_signer MUST be the private key corresponding to the public key set in the leaf_node_parameters.

If successful, it returns a tuple of MlsMessageOut (containing the commit), an optional MlsMessageOut (containing the Welcome) and the GroupInfo. The Welcome is Some when the queue of pending proposals contained add proposals The GroupInfo is Some if the group has the use_ratchet_tree_extension flag set.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use MlsGroup::commit_builder, whose CommitMessageBundle::confirmation surfaces the handshake confirmation data.

pub fn propose_self_update<Provider: OpenMlsProvider, S: Signer>( &mut self, provider: &Provider, signer: &S, leaf_node_parameters: LeafNodeParameters, ) -> Result<(MlsMessageOut, ProposalRef), ProposeSelfUpdateError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates a proposal to update the own leaf node. The application can choose to update the credential, the capabilities, and the extensions by building the LeafNodeParameters.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed with Propose::Update, which retains the handshake secret and returns the confirmation data.

pub fn propose_self_update_with_new_signer<Provider: OpenMlsProvider, S: Signer>( &mut self, provider: &Provider, old_signer: &impl Signer, new_signer: NewSignerBundle<'_, S>, leaf_node_parameters: LeafNodeParameters, ) -> Result<(MlsMessageOut, ProposalRef), ProposeSelfUpdateError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates an Update proposal that rotates the sender’s signature key.

In contrast to Self::propose_self_update, this function allows updating the signature public key of the sender’s leaf node. The produced MLS message’s envelope is authenticated using old_signer (required because the sender’s current leaf in the group tree still carries the old signature key), while the new leaf embedded in the UpdateProposal is self-signed by new_signer.signer so that it validates against its own signature_key field at the receiver.

If leaf_node_parameters sets credential_with_key, it MUST equal new_signer.credential_with_key. If it is not set the new-signer credential is folded in automatically.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_self_update_with_new_signer_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_self_update_with_new_signer_unconfirmed<Provider: OpenMlsProvider, S: Signer>( &mut self, provider: &Provider, old_signer: &impl Signer, new_signer: NewSignerBundle<'_, S>, leaf_node_parameters: LeafNodeParameters, ) -> Result<(MlsMessageOut, ProposalRef, Option<HandshakeConfirmationData>), ProposeSelfUpdateError<Provider::StorageError>>

Available on crate feature virtual-clients-draft only.

Like Self::propose_self_update_with_new_signer, but retains the handshake secret and returns the HandshakeConfirmationData alongside the framed proposal, so a virtual client can confirm the proposal with MlsGroup::confirm_handshake_message once the Delivery Service has accepted it. The confirmation is None for a proposal framed as a plaintext PublicMessage.

impl MlsGroup

pub fn external_commit_builder() -> ExternalCommitBuilder

Creates a new ExternalCommitBuilder to build an external commit.

impl MlsGroup

pub fn commit_builder(&mut self) -> CommitBuilder<'_, Initial>

Returns a builder for commits.

impl MlsGroup

pub fn builder() -> MlsGroupBuilder

Creates a builder which can be used to configure and build a new MlsGroup.

pub fn new<Provider: OpenMlsProvider>( provider: &Provider, signer: &impl Signer, mls_group_create_config: &MlsGroupCreateConfig, credential_with_key: CredentialWithKey, ) -> Result<Self, NewGroupError<Provider::StorageError>>

Creates a new group with the creator as the only member (and a random group ID).

pub fn new_with_group_id<Provider: OpenMlsProvider>( provider: &Provider, signer: &impl Signer, mls_group_create_config: &MlsGroupCreateConfig, group_id: GroupId, credential_with_key: CredentialWithKey, ) -> Result<Self, NewGroupError<Provider::StorageError>>

Creates a new group with a given group ID with the creator as the only member.

pub fn join_by_external_commit<Provider: OpenMlsProvider>( provider: &Provider, signer: &impl Signer, ratchet_tree: Option<RatchetTreeIn>, verifiable_group_info: VerifiableGroupInfo, mls_group_config: &MlsGroupJoinConfig, capabilities: Option<Capabilities>, extensions: Option<Extensions<LeafNode>>, aad: &[u8], credential_with_key: CredentialWithKey, ) -> Result<(Self, MlsMessageOut, Option<GroupInfo>), ExternalCommitError<Provider::StorageError>>

👎Deprecated since 0.7.1:

Use the MlsGroup::external_commit_builder instead.

Join an existing group through an External Commit. The resulting MlsGroup instance starts off with a pending commit (the external commit, which adds this client to the group). Merging this commit is necessary for this MlsGroup instance to function properly, as, for example, this client is not yet part of the tree. As a result, it is not possible to clear the pending commit. If the external commit was rejected due to an epoch change, the MlsGroup instance has to be discarded and a new one has to be created using this function based on the latest ratchet_tree and group info. For more information on the external init process, please see Section 11.2.1 in the MLS specification.

Note: If there is a group member in the group with the same identity as us, this will create a remove proposal.

impl MlsGroup

pub fn vc_external_commit_join_builder() -> VcExternalCommitJoinBuilder

Available on crate feature virtual-clients-draft only.

Returns a new VcExternalCommitJoinBuilder for joining a higher-level group as a virtual client’s sibling emulator client, by processing another sibling’s external commit.

pub fn vc_join_at_creation<Provider: OpenMlsProvider>( provider: &Provider, join_config: &MlsGroupJoinConfig, verifiable_group_info: VerifiableGroupInfo, ratchet_tree: Option<RatchetTreeIn>, epoch_id: EpochId, ) -> Result<MlsGroup, VcGroupCreationJoinError<Provider::StorageError>>

Available on crate feature virtual-clients-draft only.

Bootstrap a virtual client’s sibling emulator client into a higher-level group the virtual client created, when this client is not yet a member.

The creator emulator client built the group with MlsGroupBuilder::vc_emulation, its key_package-sourced leaf key material derived from a key_package operation secret. Sharing the same derivation epoch (epoch_id), this client reconstructs the epoch-0 state: it verifies the GroupInfo and single-leaf ratchet tree (which may instead travel in the GroupInfo’s ratchet_tree extension), rederives the creator leaf’s key material from the shared operation secret tree, and derives the same epoch-0 epoch_secret from the creator’s KeyPackage seed. No secret travels on the wire. On success the returned group sits at epoch 0 with this client on the shared virtual-client leaf (index 0).

impl MlsGroup

pub fn add_members<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, key_packages: &[KeyPackage], ) -> Result<(MlsMessageOut, MlsMessageOut, Option<GroupInfo>), AddMembersError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Adds members to the group.

New members are added by providing a KeyPackage for each member.

This operation results in a Commit with a path, i.e. it includes an update of the committer’s leaf KeyPackage. To add members without forcing an update of the committer’s leaf KeyPackage, use Self::add_members_without_update().

If successful, it returns a triple of MlsMessageOuts, where the first contains the commit, the second one the Welcome and the third an optional GroupInfo that will be Some if the group has the use_ratchet_tree_extension flag set.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use MlsGroup::commit_builder, whose CommitMessageBundle::confirmation surfaces the handshake confirmation data.

pub fn swap_members<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, members: &[LeafNodeIndex], key_packages: &[KeyPackage], ) -> Result<WelcomeCommitMessages, SwapMembersError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Swap members.

This function replaces a set of members of the group with new members. The members-to-be-replaced are identified by their index, and the new members are identified by the provided key_packages.

This function can be used in scenarios where members are no longer in sync with the rest of the group and need to be re-added. Note however that this function does not enforce that the removed members and new members in the key_packages correspond.

Under the virtual-clients-draft feature this function is unavailable. Use MlsGroup::commit_builder, whose CommitMessageBundle::confirmation surfaces the handshake confirmation data.

pub fn add_members_without_update<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, key_packages: &[KeyPackage], ) -> Result<(MlsMessageOut, MlsMessageOut, Option<GroupInfo>), AddMembersError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Adds members to the group.

New members are added by providing a KeyPackage for each member.

This operation results in a Commit that does not necessarily include a path, i.e. an update of the committer’s leaf KeyPackage. In particular, it will only include a path if the group’s proposal store includes one or more proposals that require a path (see Section 17.4 of RFC 9420 for a list of proposals and whether they require a path).

If successful, it returns a triple of MlsMessageOuts, where the first contains the commit, the second one the Welcome and the third an optional GroupInfo that will be Some if the group has the use_ratchet_tree_extension flag set.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use MlsGroup::commit_builder, whose CommitMessageBundle::confirmation surfaces the handshake confirmation data.

pub fn own_leaf(&self) -> Option<&LeafNode>

Returns a reference to the own LeafNode.

pub fn remove_members<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, members: &[LeafNodeIndex], ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), RemoveMembersError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Removes members from the group.

Members are removed by providing the member’s leaf index.

If successful, it returns a tuple of MlsMessageOut (containing the commit), an optional MlsMessageOut (containing the Welcome) and the current GroupInfo. The Welcome is Some when the queue of pending proposals contained add proposals The GroupInfo is Some if the group has the use_ratchet_tree_extension flag set.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use MlsGroup::commit_builder, whose CommitMessageBundle::confirmation surfaces the handshake confirmation data.

pub fn leave_group<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, ) -> Result<MlsMessageOut, LeaveGroupError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Leave the group.

Creates a Remove Proposal that needs to be covered by a Commit from a different member. The Remove Proposal is returned as a MlsMessageOut.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed with Propose::Remove of the own leaf index, which retains the handshake secret and returns the confirmation data.

pub fn leave_group_via_self_remove<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, ) -> Result<MlsMessageOut, LeaveGroupError<Provider::StorageError>>

Leave the group via a SelfRemove proposal.

Creates a SelfRemove Proposal that needs to be covered by a Commit from a different member. The SelfRemove Proposal is returned as a MlsMessageOut.

Since SelfRemove proposals are always sent as PublicMessages, this function can only be used if the group’s WireFormatPolicy allows for it.

Returns an error if there is a pending commit.

pub fn members(&self) -> impl Iterator<Item = Member> + '_

Returns a list of Members in the group.

pub fn member_leaf_index( &self, credential: &Credential, ) -> Option<LeafNodeIndex>

Returns the LeafNodeIndex of a member corresponding to the given credential. Returns None if the member can not be found in this group.

pub fn member(&self, leaf_index: LeafNodeIndex) -> Option<&Credential>

Returns the Credential of a member corresponding to the given leaf index. Returns None if the member can not be found in this group.

pub fn member_at(&self, leaf_index: LeafNodeIndex) -> Option<Member>

Returns the Member corresponding to the given leaf index. Returns None if the member can not be found in this group.

impl MlsGroup

pub fn process_message<Provider: OpenMlsProvider>( &mut self, provider: &Provider, message: impl Into<ProtocolMessage>, ) -> Result<ProcessedMessage, ProcessMessageError<Provider::StorageError>>

Parses incoming messages from the DS. Checks for syntactic errors and makes some semantic checks as well. If the input is an encrypted message, it will be decrypted. This processing function does syntactic and semantic validation of the message. It returns a ProcessedMessage enum.

A commit covering AppDataUpdate proposals is returned as ProcessedMessageContent::UnresolvedAppDataCommit, since the application has to interpret the proposals before the commit can be staged via MlsGroup::stage_app_data_commit().

Errors:

Returns an ProcessMessageError when the validation checks fail with the exact reason of the failure.

pub fn app_data_dictionary_updater<'a>(&'a self) -> AppDataDictionaryUpdater<'a>

Available on crate feature extensions-draft only.

Returns a new helper struct for updating the app data

pub fn store_pending_proposal<Storage: StorageProvider>( &mut self, storage: &Storage, proposal: QueuedProposal, ) -> Result<(), Storage::Error>

Stores a standalone proposal in the internal ProposalStore

pub fn has_pending_proposals(&self) -> bool

Returns true if there are pending proposals queued in the proposal store.

pub fn commit_to_pending_proposals<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), CommitToPendingProposalsError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates a Commit message that covers the pending proposals that are currently stored in the group’s ProposalStore. The Commit message is created even if there are no valid pending proposals.

Returns an error if there is a pending commit. Otherwise it returns a tuple of Commit, Option<Welcome>, Option<GroupInfo>, where Commit and Welcome are MlsMessages of the type MlsMessageOut.

Under the virtual-clients-draft feature this function is unavailable. Use MlsGroup::commit_builder, whose CommitMessageBundle::confirmation surfaces the handshake confirmation data.

pub fn merge_staged_commit<Provider: OpenMlsProvider>( &mut self, provider: &Provider, staged_commit: StagedCommit, ) -> Result<(), MergeCommitError<Provider::StorageError>>

Merge a StagedCommit into the group after inspection. As this advances the epoch of the group, it also clears any pending commits.

pub fn merge_pending_commit<Provider: OpenMlsProvider>( &mut self, provider: &Provider, ) -> Result<(), MergePendingCommitError<Provider::StorageError>>

Merges the pending StagedCommit if there is one, and clears the field by setting it to None.

pub fn stage_app_data_commit<Provider: OpenMlsProvider>( &self, provider: &Provider, unresolved_commit: UnresolvedAppDataCommit, app_data_dict_updates: Option<AppDataUpdates>, ) -> Result<StagedCommit, StageCommitError>

Available on crate feature extensions-draft only.

Stages a Commit covering AppDataUpdate proposals, after the application has interpreted the proposals and computed the resulting AppDataUpdates.

The returned StagedCommit can be inspected and merged into the group’s state using MlsGroup::merge_staged_commit().

pub fn resolve_app_data_commit<Provider: OpenMlsProvider>( &self, provider: &Provider, processed_message: ProcessedMessage, app_data_dict_updates: Option<AppDataUpdates>, ) -> Result<ProcessedMessage, ResolveAppDataCommitError>

Available on crate feature extensions-draft only.

Resolves a ProcessedMessage carrying an ProcessedMessageContent::UnresolvedAppDataCommit: stages the commit with the application-computed AppDataUpdates and returns the same message with the resulting StagedCommit as regular ProcessedMessageContent::StagedCommitMessage content. All other message fields (sender, credential, authenticated data) are preserved.

Use this instead of MlsGroup::stage_app_data_commit() when the caller needs the resolved commit in ProcessedMessage form, e.g. to keep a single code path for commits with and without AppDataUpdate proposals.

Returns an error if the message content is not an unresolved app data commit; the message is consumed either way.

impl MlsGroup

pub fn propose_add_member_by_value<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, value: KeyPackage, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates a proposal to add a member to the group, committed by value.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_remove_member_by_value<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, value: LeafNodeIndex, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates a proposal to remove a member from the group, committed by value.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_pre_shared_key<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, value: PreSharedKeyId, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates a proposal to add a pre-shared key to the key schedule, committed by reference.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_pre_shared_key_by_value<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, value: PreSharedKeyId, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates a proposal to add a pre-shared key to the key schedule, committed by value.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_external_psk<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, value: PreSharedKeyId, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

👎Deprecated:

Renamed to propose_pre_shared_key; works for any non-resumption PSK, not just external

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates proposals to add a non-resumption PSK to the key schedule.

pub fn propose_external_psk_by_value<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, value: PreSharedKeyId, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

👎Deprecated:

Renamed to propose_pre_shared_key_by_value; works for any non-resumption PSK, not just external

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates proposals to add a non-resumption PSK to the key schedule by value.

pub fn propose_custom_proposal_by_value<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, value: CustomProposal, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates a custom proposal, committed by value.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_custom_proposal_by_reference<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, value: CustomProposal, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates a custom proposal, committed by reference.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, propose: Propose, ref_or_value: ProposalOrRefType, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Generate a proposal.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_unconfirmed<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, propose: Propose, ref_or_value: ProposalOrRefType, ) -> Result<(MlsMessageOut, ProposalRef, Option<HandshakeConfirmationData>), ProposalError<Provider::StorageError>>

Available on crate feature virtual-clients-draft only.

Like Self::propose, but retains the handshake secret and returns the HandshakeConfirmationData alongside the framed proposal, so a virtual client can confirm the proposal with MlsGroup::confirm_handshake_message once the DS has accepted it. The confirmation is None for a proposal framed as a plaintext PublicMessage.

pub fn propose_add_member<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, key_package: &KeyPackage, ) -> Result<(MlsMessageOut, ProposalRef), ProposeAddMemberError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates proposals to add members to the group.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_remove_member<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, member: LeafNodeIndex, ) -> Result<(MlsMessageOut, ProposalRef), ProposeRemoveMemberError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates proposals to remove members from the group. The member has to be the member’s leaf index.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_remove_member_by_credential<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, member: &Credential, ) -> Result<(MlsMessageOut, ProposalRef), ProposeRemoveMemberError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates proposals to remove members from the group. The member has to be the member’s credential.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_remove_member_by_credential_by_value<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, member: &Credential, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates proposals to remove members from the group. The member has to be the member’s credential.

Returns an error if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn propose_group_context_extensions<Provider: OpenMlsProvider>( &mut self, provider: &Provider, extensions: Extensions<GroupContext>, signer: &impl Signer, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Creates a proposals with a new set of extensions for the group context.

Returns an error when the group does not support all the required capabilities in the new extensions.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed with Propose::GroupContextExtensions, which retains the handshake secret and returns the confirmation data.

pub fn update_group_context_extensions<Provider: OpenMlsProvider>( &mut self, provider: &Provider, extensions: Extensions<GroupContext>, signer: &impl Signer, ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), CreateGroupContextExtProposalError<Provider::StorageError>>

Available on crate feature test-utils or non-crate feature virtual-clients-draft only.

Updates Group Context Extensions

Commits to the Group Context Extension inline proposal using the Extensions

Returns an error when the group does not support all the required capabilities in the new extensions or if there is a pending commit.

Under the virtual-clients-draft feature this function is unavailable. Use MlsGroup::commit_builder, whose CommitMessageBundle::confirmation surfaces the handshake confirmation data.

pub fn propose_app_data_update<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, component_id: ComponentId, operation: AppDataUpdateOperation, ) -> Result<(MlsMessageOut, ProposalRef), ProposalError<Provider::StorageError>>

Available on crate feature extensions-draft and (crate feature test-utils or non-crate feature virtual-clients-draft) only.

Updates the AppDataDictionary, committed by value.

Under the virtual-clients-draft feature this function is unavailable. Use Self::propose_unconfirmed, which retains the handshake secret and returns the confirmation data.

pub fn remove_pending_proposal<Storage: StorageProvider>( &mut self, storage: &Storage, proposal_ref: &ProposalRef, ) -> Result<(), RemoveProposalError<Storage::Error>>

Removes a specific proposal from the store.

impl MlsGroup

pub fn create_targeted_message<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, recipient_leaf_index: LeafNodeIndex, application_data: &[u8], ) -> Result<MlsMessageOut, CreateTargetedMessageError>

Available on crate feature targeted-messages-draft only.

Creates a targeted message for a specific group member. The application_data payload is encrypted to the recipient’s leaf encryption key. The sender is authenticated via signature. The number of zero bytes appended to the plaintext before encryption to obscure the application data length is taken from the group’s configured padding size.

pub fn process_targeted_message<Provider: OpenMlsProvider>( &self, provider: &Provider, message: &TargetedMessageIn, ) -> Result<ProcessedTargetedMessage, ProcessTargetedMessageError<Provider::StorageError>>

Available on crate feature targeted-messages-draft only.

Processes a received targeted message. Decrypts the message content and verifies the sender’s signature. Returns the sender’s leaf index and the decrypted application data.

impl MlsGroup

pub fn configuration(&self) -> &MlsGroupJoinConfig

Returns the configuration.

pub fn set_configuration<Storage: StorageProvider>( &mut self, storage: &Storage, mls_group_config: &MlsGroupJoinConfig, ) -> Result<(), Storage::Error>

Sets the configuration.

pub fn set_aad(&mut self, aad: Vec<u8>)

Sets the additional authenticated data (AAD) for the next outgoing message. This is ephemeral and will be reset by every API call that successfully returns an MlsMessageOut.

pub fn aad(&self) -> &[u8]

Returns the additional authenticated data (AAD) for the next outgoing message.

pub fn set_safe_aad( &mut self, items: Vec<SafeAadItem>, ) -> Result<(), SafeAadError>

Available on crate feature extensions-draft only.

Stage Safe AAD items for the next outgoing message. Items must be sorted by ComponentId in strictly-increasing order and contain no duplicates; otherwise the call fails and the previously staged items are left untouched.

Ephemeral, like Self::set_aad: cleared whenever an outgoing message is produced.

pub fn safe_aad_items(&self) -> &[SafeAadItem]

Available on crate feature extensions-draft only.

Returns the currently staged Safe AAD items for the next outgoing message.

pub fn ciphersuite(&self) -> Ciphersuite

Returns the group’s ciphersuite.

pub fn confirmation_tag(&self) -> &ConfirmationTag

Get confirmation tag.

pub fn is_active(&self) -> bool

Returns whether the own client is still a member of the group or if it was already evicted

pub fn credential(&self) -> Result<&Credential, MlsGroupStateError>

Returns own credential. If the group is inactive, it returns a UseAfterEviction error.

pub fn own_leaf_index(&self) -> LeafNodeIndex

Returns the leaf index of the client in the tree owning this group.

pub fn own_leaf_node(&self) -> Option<&LeafNode>

Returns the leaf node of the client in the tree owning this group.

pub fn group_id(&self) -> &GroupId

Returns the group ID.

pub fn epoch(&self) -> GroupEpoch

Returns the epoch.

pub fn pending_proposals(&self) -> impl Iterator<Item = &QueuedProposal>

Returns an Iterator over pending proposals.

pub fn treesync(&self) -> &TreeSync

Returns the current tree state of the group, in the form of a TreeSync.

pub fn pending_commit(&self) -> Option<&StagedCommit>

Returns a reference to the StagedCommit of the most recently created commit. If there was no commit created in this epoch, either because this commit or another commit was merged, it returns None.

pub fn clear_pending_commit<Storage: StorageProvider>( &mut self, storage: &Storage, ) -> Result<(), Storage::Error>

Sets the group_state to MlsGroupState::Operational, thus clearing any potentially pending commits.

Note that this has no effect if the group was created through an external commit and the resulting external commit has not been merged yet. For more information, see MlsGroup::external_commit_builder().

Use with caution! This function should only be used if it is clear that the pending commit will not be used in the group. In particular, if a pending commit is later accepted by the group, this client will lack the key material to encrypt or decrypt group messages.

pub fn clear_pending_proposals<Storage: StorageProvider>( &mut self, storage: &Storage, ) -> Result<(), Storage::Error>

Clear the pending proposals, if the proposal store is not empty.

Warning: Once the pending proposals are cleared it will be impossible to process a Commit message that references those proposals. Only use this function as a last resort, e.g. when a call to MlsGroup::commit_to_pending_proposals fails.

pub fn extensions(&self) -> &Extensions<GroupContext>

Get a reference to the group context Extensions of this MlsGroup.

pub fn ext_commit_sender_index( &self, commit: &StagedCommit, ) -> Result<LeafNodeIndex, LibraryError>

Returns the index of the sender of a staged, external commit.

pub fn load<Storage: StorageProvider>( storage: &Storage, group_id: &GroupId, ) -> Result<Option<MlsGroup>, Storage::Error>

Loads the state of the group with given id from persisted state.

pub fn delete<Storage: StorageProvider>( &mut self, storage: &Storage, ) -> Result<(), Storage::Error>

Remove the persisted state of this group from storage. Note that signature key material is not managed by OpenMLS and has to be removed from the storage provider separately (if desired).

pub fn export_ratchet_tree(&self) -> RatchetTree

Exports the Ratchet Tree.

impl MlsGroup

pub fn past_epoch_deletion_policy(&self) -> &PastEpochDeletionPolicy

Get the past epoch secret deletion policy for the group.

pub fn set_past_epoch_deletion_policy<Provider: OpenMlsProvider>( &mut self, provider: &Provider, policy: PastEpochDeletionPolicy, ) -> Result<(), SetPastEpochDeletionPolicyError<Provider::StorageError>>

Set the past epoch secret deletion policy for the group.

pub fn is_emulation_group(&self) -> bool

Available on crate feature virtual-clients-draft only.

Returns whether this group is an emulation group of a virtual client.

The flag is set when the application creates the group as an emulation group or joins one, and it is restored from storage when the group is loaded. See MlsGroupCreateConfigBuilder::emulation_group.

pub fn newest_vc_derivation_epoch<Storage: StorageProvider>( &self, storage: &Storage, ) -> Result<Option<EpochId>, Storage::Error>

Available on crate feature virtual-clients-draft only.

Returns the EpochId of the newest derivation epoch of this emulation group, or None if none was registered yet.

All virtual-client operations resolve to this derivation epoch. It is sourced from the newest group epoch that was a derivation epoch, which may be older than the group’s current epoch: only commits that change membership or that carry a new_derivation_epoch action create one.

The sender-side operation entry points take the emulation group and resolve the epoch themselves, so this getter is for inspection only.

Returns None for groups that are not emulation groups.

pub fn delete_past_epoch_secrets<Provider: OpenMlsProvider>( &mut self, provider: &Provider, policy: PastEpochDeletion, ) -> Result<(), DeletePastEpochSecretsError<Provider::StorageError>>

Delete all past epoch secrets.

For more information on the arguments to this method, see PastEpochDeletion.

pub fn proposal_store(&self) -> &ProposalStore

Returns a reference to the proposal store.

pub fn public_group(&self) -> &PublicGroup

Returns a reference to the public group.

impl MlsGroup

pub fn export_group_context(&self) -> &GroupContext

Available on crate features test-utils only.

pub fn tree_hash(&self) -> &[u8]

Available on crate features test-utils only.

pub fn print_ratchet_tree(&self, message: &str)

Available on crate features test-utils only.

pub fn ensure_persistence( &self, storage: &impl StorageProvider, ) -> Result<(), LibraryError>

Available on crate features test-utils only.

impl MlsGroup

pub fn recover_fork_by_readding( &mut self, own_partition: &[LeafNodeIndex], ) -> Result<CommitBuilder<'_, ReAddExpectKeyPackages>, ReAddError>

Available on crate feature fork-resolution only.

Create a CommitBuilder that is preparing to remove and re-add members from other fork partitions. own_partition is the list of LeafNodeIndex that are members in the partition that the initiating client is in. This should include the LeafNodeIndex of the initiating client.

impl MlsGroup

pub fn reboot(&self, group_id: GroupId) -> RebootBuilder<'_>

Available on crate feature fork-resolution only.

The first step towards creating a new group based on the parameters and membership list of the current one.

Trait Implementations

impl Clone for MlsGroup

Available on crate feature test-utils only.

fn clone(&self) -> MlsGroup

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MlsGroup

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MlsGroup

Available on crate feature migration-import only.

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for MlsGroup

Available on crate feature test-utils only.

fn eq(&self, other: &MlsGroup) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for MlsGroup

Available on crate features migration-import and test-utils only.

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for MlsGroup

Available on crate feature test-utils only.