Struct MlsGroup

pub struct MlsGroup { /* private fields */ }

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>

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.

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).

This function removes the private key corresponding to the key_package from the key store.

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>, aad: &[u8], credential_with_key: CredentialWithKey, ) -> Result<(Self, MlsMessageOut, Option<GroupInfo>), ExternalCommitError<Provider::StorageError>>

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 export_secret<Provider: OpenMlsProvider>( &self, provider: &Provider, 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 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<Provider: OpenMlsProvider>( &self, provider: &Provider, signer: &impl Signer, with_ratchet_tree: bool, ) -> Result<MlsMessageOut, ExportGroupInfoError>

Export a group info object for this group.

impl MlsGroup

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

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.

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

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.

impl MlsGroup

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

Returns a builder for commits.

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>>

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.

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>>

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.

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>>

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.

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

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.

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(&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>

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.

Errors:

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

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 commit_to_pending_proposals<Provider: OpenMlsProvider>( &mut self, provider: &Provider, signer: &impl Signer, ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), CommitToPendingProposalsError<Provider::StorageError>>

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.

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.

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>>

Creates proposals to add an external PSK to the key schedule.

Returns an error if there is a pending commit.

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

Creates proposals to add an external PSK to the key schedule.

Returns an error if there is a pending commit.

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

Creates proposals to add an external PSK to the key schedule.

Returns an error if there is a pending commit.

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

Creates proposals to add an external PSK to the key schedule.

Returns an error if there is a pending commit.

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

Creates proposals to add an external PSK to the key schedule.

Returns an error if there is a pending commit.

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

Creates proposals to add an external PSK to the key schedule.

Returns an error if there is a pending commit.

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

Generate a proposal

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

Creates proposals to add members to the group.

Returns an error if there is a pending commit.

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

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.

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

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.

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>>

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.

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

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.

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

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.

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 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 ciphersuite(&self) -> Ciphersuite

Returns the group’s ciphersuite.

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 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::join_by_external_commit().

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

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.

Trait Implementations

impl Debug for MlsGroup

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

Formats the value using the given formatter.