MlsGroup - OpenMLS

MlsGroup represents an MLS group with a high-level API for managing group membership, sending messages, and handling commits. This is the primary interface for interacting with MLS groups in OpenMLS.

Overview

The MlsGroup struct provides a complete interface to the Delivery Service, where functions that modify the public state return messages that can be sent directly to the Delivery Service. Incoming messages from the Delivery Service can be processed through process_message().

Creating a group

new

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

provider

&Provider

OpenMLS provider for cryptographic operations and storage

signer

&impl Signer

Signer for creating signatures

mls_group_create_config

&MlsGroupCreateConfig

Configuration for group creation

credential_with_key

CredentialWithKey

The creator’s credential with associated key material

Result

Result<MlsGroup, NewGroupError>

Returns a new MlsGroup instance or an error if group creation fails

let group = MlsGroup::new(
    provider,
    signer,
    &mls_group_create_config,
    credential_with_key,
)?;

new_with_group_id

Creates a new group with a specified group ID.

provider

&Provider

OpenMLS provider for cryptographic operations and storage

signer

&impl Signer

Signer for creating signatures

mls_group_create_config

&MlsGroupCreateConfig

Configuration for group creation

group_id

GroupId

The desired group ID

credential_with_key

CredentialWithKey

The creator’s credential with associated key material

Result

Result<MlsGroup, NewGroupError>

Returns a new MlsGroup instance or an error

let group = MlsGroup::new_with_group_id(
    provider,
    signer,
    &mls_group_create_config,
    group_id,
    credential_with_key,
)?;

Group membership

add_members

Adds members to the group by providing their key packages. This operation includes an update path (updating the committer’s leaf).

provider

&Provider

OpenMLS provider for cryptographic operations and storage

signer

&impl Signer

Signer for creating the commit

key_packages

&[KeyPackage]

Key packages for the members to add

Result

Result<(MlsMessageOut, MlsMessageOut, Option<GroupInfo>), AddMembersError>

Returns a tuple of (Commit, Welcome, optional GroupInfo) or an error. Returns error if there is a pending commit.

let (commit, welcome, group_info) = group.add_members(
    provider,
    signer,
    &[key_package1, key_package2],
)?;

add_members_without_update

Adds members without forcing an update of the committer’s leaf. Only includes a path if required by pending proposals.

provider

&Provider

OpenMLS provider

signer

&impl Signer

Signer for creating the commit

key_packages

&[KeyPackage]

Key packages for the members to add

Result

Result<(MlsMessageOut, MlsMessageOut, Option<GroupInfo>), AddMembersError>

Returns (Commit, Welcome, optional GroupInfo)

remove_members

Removes members from the group by their leaf indices.

provider

&Provider

OpenMLS provider

signer

&impl Signer

Signer for creating the commit

members

&[LeafNodeIndex]

Leaf indices of members to remove

Result

Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), RemoveMembersError>

Returns (Commit, optional Welcome if add proposals were pending, optional GroupInfo)

let (commit, welcome, group_info) = group.remove_members(
    provider,
    signer,
    &[leaf_index],
)?;

leave_group

Leaves the group by creating a Remove proposal. The proposal must be committed by another member.

provider

&Provider

OpenMLS provider

signer

&impl Signer

Signer for the proposal

Result

Result<MlsMessageOut, LeaveGroupError>

Returns the Remove proposal message

let remove_proposal = group.leave_group(provider, signer)?;

members

Returns an iterator over all members in the group.

Iterator

impl Iterator<Item = Member>

Iterator over group members

for member in group.members() {
    println!("Member: {:?}", member.credential);
}

Message processing

process_message

Processes incoming messages from the Delivery Service. Performs syntactic and semantic validation, and decrypts encrypted messages.

provider

&Provider

OpenMLS provider

message

impl Into<ProtocolMessage>

The message to process

Result

Result<ProcessedMessage, ProcessMessageError>

Returns the processed message or an error

let processed = group.process_message(provider, protocol_message)?;

match processed.into_content() {
    ProcessedMessageContent::ApplicationMessage(msg) => {
        // Handle application message
    }
    ProcessedMessageContent::ProposalMessage(proposal) => {
        // Store proposal
        group.store_pending_proposal(provider.storage(), *proposal)?;
    }
    ProcessedMessageContent::StagedCommitMessage(staged_commit) => {
        // Inspect and merge commit
        group.merge_staged_commit(provider, *staged_commit)?;
    }
    _ => {}
}

merge_staged_commit

Merges a staged commit into the group state after inspection.

provider

&Provider

OpenMLS provider

staged_commit

StagedCommit

The staged commit to merge

Result

Result<(), MergeCommitError>

Returns () on success

Proposals

propose_add_member

Creates a proposal to add a member to the group.

provider

&Provider

OpenMLS provider

signer

&impl Signer

Signer for the proposal

key_package

&KeyPackage

Key package of the member to add

Result

Result<(MlsMessageOut, ProposalRef), ProposeAddMemberError>

Returns (proposal message, proposal reference)

let (proposal, proposal_ref) = group.propose_add_member(
    provider,
    signer,
    &key_package,
)?;

propose_remove_member

Creates a proposal to remove a member from the group.

provider

&Provider

OpenMLS provider

signer

&impl Signer

Signer for the proposal

member

LeafNodeIndex

Leaf index of the member to remove

Result

Result<(MlsMessageOut, ProposalRef), ProposeRemoveMemberError>

Returns (proposal message, proposal reference)

commit_to_pending_proposals

Creates a Commit that covers all pending proposals in the group’s proposal store.

provider

&Provider

OpenMLS provider

signer

&impl Signer

Signer for the commit

Result

Result<(MlsMessageOut, Option<MlsMessageOut>, Option<GroupInfo>), CommitToPendingProposalsError>

Returns (Commit, optional Welcome, optional GroupInfo). Returns error if there is a pending commit.

let (commit, welcome, group_info) = group.commit_to_pending_proposals(
    provider,
    signer,
)?;

Getters and configuration

group_id

Returns the group ID.

GroupId

&GroupId

Reference to the group ID

let id = group.group_id();

epoch

Returns the current epoch.

GroupEpoch

The current group epoch

let epoch = group.epoch();

ciphersuite

Returns the group’s ciphersuite.

Ciphersuite

The ciphersuite used by the group

own_leaf_index

Returns the leaf index of the client in the tree.

LeafNodeIndex

The client’s leaf index

is_active

Returns whether the client is still a member of the group.

bool

true if the client is a member, false if evicted

if group.is_active() {
    // Process messages
}

pending_commit

Returns a reference to the pending commit if one exists.

Option

Option<&StagedCommit>

Optional reference to the pending commit

pending_proposals

Returns an iterator over pending proposals.

Iterator

impl Iterator<Item = &QueuedProposal>

Iterator over queued proposals

for proposal in group.pending_proposals() {
    println!("Proposal: {:?}", proposal.proposal());
}

configuration

Returns the group configuration.

MlsGroupJoinConfig

&MlsGroupJoinConfig

Reference to the group configuration

set_configuration

Sets the group configuration.

storage

&Storage

Storage provider

mls_group_config

&MlsGroupJoinConfig

New configuration

Result

Result<(), Storage::Error>

Returns () on success

Export and secrets

export_secret

Exports a secret from the current epoch.

crypto

&CryptoProvider

Cryptographic provider

label

&str

Label for the exported secret

context

&[u8]

Context bytes for the derivation

key_length

usize

Desired key length in bytes (max: u16::MAX)

Result

Result<Vec<u8>, ExportSecretError>

Returns the exported secret or an error

let secret = group.export_secret(
    provider.crypto(),
    "my-app-secret",
    b"context",
    32,
)?;

export_group_info

Exports a GroupInfo object for this group.

crypto

&CryptoProvider

Cryptographic provider

signer

&impl Signer

Signer for signing the GroupInfo

with_ratchet_tree

bool

Whether to include the ratchet tree extension

Result

Result<MlsMessageOut, ExportGroupInfoError>

Returns the GroupInfo message

let group_info = group.export_group_info(
    provider.crypto(),
    signer,
    true, // include ratchet tree
)?;

export_ratchet_tree

Exports the ratchet tree of the group.

RatchetTree

The group’s ratchet tree

let tree = group.export_ratchet_tree();

epoch_authenticator

Returns the epoch authenticator of the current epoch.

EpochAuthenticator

&EpochAuthenticator

Reference to the epoch authenticator

resumption_psk_secret

Returns the resumption PSK secret of the current epoch.

ResumptionPskSecret

&ResumptionPskSecret

Reference to the resumption PSK secret

Storage

load

Loads a group from persistent storage.

storage

&Storage

Storage provider

group_id

&GroupId

ID of the group to load

Result

Result<Option<MlsGroup>, Storage::Error>

Returns the group if found, None if not found, or an error

if let Some(group) = MlsGroup::load(provider.storage(), &group_id)? {
    // Use the group
}

delete

Removes the group’s persisted state from storage.

storage

&Storage

Storage provider

Result

Result<(), Storage::Error>

Returns () on success

group.delete(provider.storage())?;

State management

clear_pending_commit

Clears any pending commit, setting the group state to operational.

storage

&Storage

Storage provider

Result

Result<(), Storage::Error>

Returns () on success

Use with caution! Only clear a pending commit if you’re certain it won’t be used. If the commit is later accepted by the group, this client will lack key material for encryption/decryption.

clear_pending_proposals

Clears all pending proposals from the proposal store.

storage

&Storage

Storage provider

Result

Result<(), Storage::Error>

Returns () on success

Once proposals are cleared, it becomes impossible to process a Commit that references them. Use only as a last resort.

Group state

The MlsGroup maintains an internal state that determines available operations:

Operational: Normal state with full functionality
PendingCommit: A commit has been created but not yet merged; most operations are restricted
Inactive: The client has been removed from the group; no operations are available

For more details, see the MlsGroupState documentation.

Documentation Index

​Overview

​Creating a group

​new

​new_with_group_id

​Group membership

​add_members

​add_members_without_update

​remove_members

​leave_group

​members

​Message processing

​process_message

​merge_staged_commit

​Proposals

​propose_add_member

​propose_remove_member

​commit_to_pending_proposals

​Getters and configuration

​group_id

​epoch

​ciphersuite

​own_leaf_index

​is_active

​pending_commit

​pending_proposals

​configuration

​set_configuration

​Export and secrets

​export_secret

​export_group_info

​export_ratchet_tree

​epoch_authenticator

​resumption_psk_secret

​Storage

​load

​delete

​State management

​clear_pending_commit

​clear_pending_proposals

​Group state

Overview

Creating a group

new

new_with_group_id

Group membership

add_members

add_members_without_update

remove_members

leave_group

members

Message processing

process_message

merge_staged_commit

Proposals

propose_add_member

propose_remove_member

commit_to_pending_proposals

Getters and configuration

group_id

epoch

ciphersuite

own_leaf_index

is_active

pending_commit

pending_proposals

configuration

set_configuration

Export and secrets

export_secret

export_group_info

export_ratchet_tree

epoch_authenticator

resumption_psk_secret

Storage

load

delete

State management

clear_pending_commit

clear_pending_proposals

Group state