Struct core_crypto::prelude::MlsGroup

pub struct MlsGroup {
    pub own_leaf_nodes: Vec<LeafNode>,
    /* 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.

Fields

own_leaf_nodes: Vec<LeafNode>

Implementations

impl MlsGroup

pub async fn delete_previous_epoch_keypairs<KeyStore>( &self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, ) -> Result<(), <KeyStore as OpenMlsKeyStore>::Error>

where KeyStore: OpenMlsKeyStore,

re-export

impl MlsGroup

pub fn create_message( &mut self, backend: &impl OpenMlsCryptoProvider, 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 async fn new<KeyStore>( backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, mls_group_config: &MlsGroupConfig, credential_with_key: CredentialWithKey, ) -> Result<MlsGroup, NewGroupError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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 async fn new_with_group_id<KeyStore>( backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, mls_group_config: &MlsGroupConfig, group_id: GroupId, credential_with_key: CredentialWithKey, ) -> Result<MlsGroup, NewGroupError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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

pub async fn new_from_welcome<KeyStore>( backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, mls_group_config: &MlsGroupConfig, welcome: Welcome, ratchet_tree: Option<RatchetTreeIn>, ) -> Result<MlsGroup, WelcomeError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

Creates a new group from a [Welcome] message. Returns an error ([WelcomeError::NoMatchingKeyPackage]) if no KeyPackage can be found.

pub async fn join_by_external_commit( backend: &impl OpenMlsCryptoProvider, signer: &impl Signer, ratchet_tree: Option<RatchetTreeIn>, verifiable_group_info: VerifiableGroupInfo, mls_group_config: &MlsGroupConfig, aad: &[u8], credential_with_key: CredentialWithKey, ) -> Result<(MlsGroup, MlsMessageOut, Option<GroupInfo>), ExternalCommitError>

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( &self, backend: &impl OpenMlsCryptoProvider, 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( &self, backend: &impl OpenMlsCryptoProvider, signer: &impl Signer, with_ratchet_tree: bool, ) -> Result<MlsMessageOut, ExportGroupInfoError>

Export a group info object for this group.

impl MlsGroup

pub async fn self_update<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), SelfUpdateError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

Updates the own leaf node.

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.

TODO #1208 : The caller should be able to optionally provide a [LeafNode] here, so that things like extensions can be changed via commit.

pub async fn explicit_self_update<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, leaf_node: Option<LeafNode>, ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), SelfUpdateError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

Like Self::self_update but accepts an explicit node. Mostly to rotate its credential

pub async fn propose_self_update<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, ) -> Result<(MlsMessageOut, HashReference), ProposeSelfUpdateError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

Creates a proposal to update the own leaf node.

pub async fn propose_self_update_by_value<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, ) -> Result<(MlsMessageOut, HashReference), ProposeSelfUpdateError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

Creates a proposal to update the own leaf node.

pub async fn propose_explicit_self_update<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, leaf_node: LeafNode, leaf_node_signer: &impl Signer, ) -> Result<(MlsMessageOut, HashReference), ProposeSelfUpdateError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

Creates a proposal to update the own leaf node.

impl MlsGroup

pub fn propose_extensions( &mut self, backend: &impl OpenMlsCryptoProvider, signer: &impl Signer, extensions: Extensions, ) -> Result<(MlsMessageOut, HashReference), ProposeGroupContextExtensionError>

Propose to update the group context extensions. This replaces the existing extensions of the group but does not merge them yet.

Returns an error if there is a pending commit.

pub async fn update_extensions<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, extensions: Extensions, ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), UpdateExtensionsError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

Updates the extensions of the group

This operation results in a Commit with a path, i.e. it includes an update of the committer’s leaf KeyPackage.

If successful, it returns a triple where the first element 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 group_context_extensions(&self) -> &Extensions

Get the group’s [Extensions].

impl MlsGroup

pub async fn add_members<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, key_packages: Vec<KeyPackageIn>, ) -> Result<(MlsMessageOut, MlsMessageOut, Option<GroupInfo>), AddMembersError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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.

If successful, it returns a triple of [MlsMessageOut]s, 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 async fn remove_members<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, members: &[LeafNodeIndex], ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), RemoveMembersError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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( &mut self, backend: &impl OpenMlsCryptoProvider, signer: &impl Signer, ) -> Result<MlsMessageOut, LeaveGroupError>

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 members(&self) -> impl Iterator<Item = Member>

Returns a list of [Member]s in the group.

pub fn members_credentials(&self) -> impl Iterator<Item = &Credential>

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.

impl MlsGroup

pub async fn process_message( &mut self, backend: &impl OpenMlsCryptoProvider, 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(&mut self, proposal: QueuedProposal)

Stores a standalone proposal in the internal [ProposalStore]

pub async fn commit_to_pending_proposals<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), CommitToPendingProposalsError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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 async fn merge_staged_commit<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, staged_commit: StagedCommit, ) -> Result<(), MergeCommitError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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

pub async fn merge_pending_commit<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, ) -> Result<(), MergePendingCommitError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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

If the commit contains a ReInit proposal it will return a welcome message, a new group and set the current as inactive.

impl MlsGroup

pub async fn propose_add_member_by_value<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, joiner_key_package: KeyPackageIn, ) -> Result<(MlsMessageOut, HashReference), ProposalError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, value: LeafNodeIndex, ) -> Result<(MlsMessageOut, HashReference), ProposalError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, value: PreSharedKeyId, ) -> Result<(MlsMessageOut, HashReference), ProposalError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, value: PreSharedKeyId, ) -> Result<(MlsMessageOut, HashReference), ProposalError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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

Returns an error if there is a pending commit.

pub async fn propose<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, propose: Propose, ref_or_value: ProposalOrRefType, ) -> Result<(MlsMessageOut, HashReference), ProposalError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

Generate a proposal

pub async fn propose_add_member( &mut self, backend: &impl OpenMlsCryptoProvider, signer: &impl Signer, joiner_key_package: KeyPackageIn, ) -> Result<(MlsMessageOut, HashReference), ProposeAddMemberError>

Creates proposals to add members to the group.

Returns an error if there is a pending commit.

pub fn propose_remove_member( &mut self, backend: &impl OpenMlsCryptoProvider, signer: &impl Signer, member: LeafNodeIndex, ) -> Result<(MlsMessageOut, HashReference), ProposeRemoveMemberError>

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( &mut self, backend: &impl OpenMlsCryptoProvider, signer: &impl Signer, member: &Credential, ) -> Result<(MlsMessageOut, HashReference), ProposeRemoveMemberError>

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<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, member: &Credential, ) -> Result<(MlsMessageOut, HashReference), ProposalError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

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.

impl MlsGroup

pub fn propose_reinit( &mut self, backend: &impl OpenMlsCryptoProvider, signer: &impl Signer, extensions: Extensions, ciphersuite: Ciphersuite, version: ProtocolVersion, ) -> Result<(MlsMessageOut, HashReference), ProposeReInitError>

Propose the group to be reinitialized. When commited this will make the current group innactive and a new one should be created from the commit message. The new group will have the new given extensions, ciphersuite and version from the proposal.

Returns an error if there is a pending commit, if the new proposed version is older than the current or if any member doesn’t support the proposed extensions and/or ciphersuite.

pub async fn reinit<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, signer: &impl Signer, extensions: Extensions, ciphersuite: Ciphersuite, version: ProtocolVersion, ) -> Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), ReInitError<<KeyStore as OpenMlsKeyStore>::Error>>

where KeyStore: OpenMlsKeyStore,

ReInits the group. If there are any proposals in the ProposalStore they are going to be commited, but the ReInit won’t be issued. A ReInit must be done exclusively with a empty ProposalStore. In that case the ReInit must be reissued.

If successful, it returns a triple where the first element 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.

impl MlsGroup

pub fn configuration(&self) -> &MlsGroupConfig

Returns the configuration.

pub fn set_configuration(&mut self, mls_group_config: &MlsGroupConfig)

Sets the configuration.

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

Returns the AAD used in the framing.

pub fn set_aad(&mut self, aad: &[u8])

Sets the AAD used in the framing.

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_identity(&self) -> Option<&[u8]>

Get the identity of the client’s Credential owning this group.

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

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 async fn load( group_id: &GroupId, backend: &impl OpenMlsCryptoProvider, ) -> Option<MlsGroup>

Loads the state from persisted state.

pub async fn save<KeyStore>( &mut self, backend: &impl OpenMlsCryptoProvider<KeyStoreProvider = KeyStore>, ) -> Result<(), <KeyStore as OpenMlsKeyStore>::Error>

where KeyStore: OpenMlsKeyStore,

Persists the state.

pub fn state_changed(&self) -> InnerState

Returns true if the internal state has changed and needs to be persisted and false otherwise. Calling Self::save() resets the value to false.

pub fn set_state(&mut self, state: InnerState)

Meh

pub fn export_ratchet_tree(&self) -> RatchetTree

Exports the Ratchet Tree.

pub fn compute_confirmation_tag( &self, backend: &impl OpenMlsCryptoProvider, ) -> Result<ConfirmationTag, CryptoError>

Calculates the confirmation tag of the current group

impl MlsGroup

pub fn export_group_context(&self) -> &GroupContext

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

pub fn clear_pending_proposals(&mut self)

Clear the pending proposals.

pub async fn remove_pending_proposal( &mut self, keystore: &impl OpenMlsKeyStore, proposal_ref: &HashReference, ) -> Result<(), MlsGroupStateError>

Removes a specific proposal from the store.

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

Trait Implementations

impl Debug for MlsGroup

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

Formats the value using the given formatter.

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

fn deserialize<D>( deserializer: D, ) -> Result<MlsGroup, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl MlsEntity for MlsGroup

const ID: MlsEntityId = MlsEntityId::GroupState

Identifier used to downcast the actual entity within an [OpenMlsKeyStore] method. In case for example you need to select a SQL table depending on the entity type

fn downcast<T>(&self) -> Option<&T>

where T: MlsEntity,

impl Serialize for MlsGroup

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.