Creating MLS Groups

Create new MLS groups with OpenMLS

Overview

Create a new MLS group with yourself as the only member. Groups can be created with a random or custom group ID.

Creating a Group

Basic Creation

Create a group with a random group ID:

use openmls::prelude::*;

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

With Custom Group ID

Create a group with a specific group ID:

let group_id = GroupId::from_slice(b"My Group");

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

Using the Builder

For advanced configuration, use the builder pattern:

let mls_group = MlsGroup::builder()
    .with_group_id(group_id)
    .ciphersuite(Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519)
    .with_wire_format_policy(WireFormatPolicy::default())
    .max_past_epochs(3)
    .use_ratchet_tree_extension(true)
    .build(provider, &signer, credential_with_key)?;

Method Signatures

MlsGroup::new

provider · &Provider · required

OpenMLS provider for crypto and storage operations

signer · &impl Signer · required

Signature key for authenticating group operations

mls_group_create_config · &MlsGroupCreateConfig · required

Configuration for the new group (ciphersuite, extensions, etc.)

credential_with_key · CredentialWithKey · required

Your credential and public key

Returns: Result<MlsGroup, NewGroupError>

Location: openmls/src/group/mls_group/creation.rs:45

MlsGroup::new_with_group_id

provider · &Provider · required

OpenMLS provider for crypto and storage operations

signer · &impl Signer · required

Signature key for authenticating group operations

mls_group_create_config · &MlsGroupCreateConfig · required

Configuration for the new group

group_id · GroupId · required

Custom group identifier

credential_with_key · CredentialWithKey · required

Your credential and public key

Returns: Result<MlsGroup, NewGroupError>

Location: openmls/src/group/mls_group/creation.rs:61

MlsGroup::builder

Returns an MlsGroupBuilder for configuring group creation.

Location: openmls/src/group/mls_group/creation.rs:36

Builder Configuration Options

with_group_id · GroupId

Set a custom group ID (default: random)

ciphersuite · Ciphersuite

Set the cryptographic ciphersuite

with_wire_format_policy · WireFormatPolicy

Configure message wire format (plaintext/ciphertext)

max_past_epochs · usize

Number of past epochs to keep for decryption (default: 0)

use_ratchet_tree_extension · bool

Include ratchet tree in Welcome messages (default: false)

with_group_context_extensions · Extensions<GroupContext>

Set group-level extensions

with_leaf_node_extensions · Extensions<LeafNode>

Set leaf node extensions

with_capabilities · Capabilities

Set supported capabilities

replace_old_group · bool

Replace existing group with same ID if it exists

Complete Example

1. Setup credentials and provider

   let provider = OpenMlsRustCrypto::default();
   let (credential_with_key, signer) = setup_identity(&provider)?;
   
2. Configure the group

   let mls_group_create_config = MlsGroupCreateConfig::builder()
       .ciphersuite(Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519)
       .use_ratchet_tree_extension(true)
       .build();
   
3. Create the group

   let mut alice_group = MlsGroup::new(
       &provider,
       &signer,
       &mls_group_create_config,
       credential_with_key,
   )?;
   
4. Persist to storage

   // Group is automatically saved to provider.storage()
   // Retrieve later with:
   let loaded_group = MlsGroup::load(
       provider.storage(),
       alice_group.group_id()
   )?;
   

Error Handling

Group creation can fail with NewGroupError:

• GroupAlreadyExists - A group with this ID already exists in storage
• UnsupportedProposalType - Configuration includes unsupported proposals
• InvalidExtensions - Invalid extension configuration
• StorageError - Failed to persist group to storage

match MlsGroup::new(provider, &signer, &config, credential) {
    Ok(group) => {
        println!("Group created: {:?}", group.group_id());
    }
    Err(NewGroupError::GroupAlreadyExists) => {
        // Handle duplicate group ID
    }
    Err(e) => {
        eprintln!("Failed to create group: {}", e);
    }
}

Next Steps

• Add members to grow your group
• Update your own key material
• Remove members from the group