MLS conversations (groups) are the core communication entities in Wire CoreCrypto. A conversation holds the group state — epoch, member list, pending proposals and commits — and provides operations for messaging and membership management.
All mutating conversation operations go through ConversationGuard, obtained via TransactionContext::conversation.
Creating conversations
new_conversation
pub async fn new_conversation(
&self,
id: &ConversationIdRef,
credential_ref: &CredentialRef,
config: MlsConversationConfiguration,
) -> Result<()>
id
&ConversationIdRef
required
Unique group identifier bytes. Wire typically uses a UUID encoded as bytes.
Reference to the credential the creator uses for this group. See Credentials. config
MlsConversationConfiguration
required
let id: Vec<u8> = uuid::Uuid::new_v4().as_bytes().to_vec();
tx.new_conversation(&id, &credential_ref, MlsConversationConfiguration {
ciphersuite: Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519,
..Default::default()
}).await?;
tx.finish().await?;
MlsConversationConfiguration
pub struct MlsConversationConfiguration {
pub ciphersuite: Ciphersuite,
pub external_senders: Vec<ExternalSender>,
pub custom: MlsCustomConfiguration,
}
The MLS ciphersuite for the group. Defaults to MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519.
Delivery service public signature keys used for external proposals. Provide via set_raw_external_senders to accept both JWK and raw key formats.
MlsCustomConfiguration
pub struct MlsCustomConfiguration {
pub key_rotation_span: Option<Duration>,
pub wire_policy: MlsWirePolicy,
pub out_of_order_tolerance: u32,
pub maximum_forward_distance: u32,
}
Planned: automatic key rotation interval. Not yet implemented.
Controls whether handshake messages are encrypted. Plaintext (default) or Ciphertext.
How many application messages within an epoch can arrive out of order before they are rejected. Default: 2.
Maximum number of application messages that may be skipped (dropped by the DS) within an epoch. Default: 1000.
Querying conversations
conversation_exists
pub async fn conversation_exists(
&self,
id: &ConversationIdRef,
) -> Result<bool>
true if a fully-merged conversation with the given ID exists locally.
get_client_ids
// on ConversationGuard (via the Conversation trait)
pub async fn get_client_ids(&self) -> Vec<ClientId>
ClientId of every current group member, derived from their MLS credential identity.
mark_as_child_of
// on ConversationGuard
pub async fn mark_as_child_of(
&mut self,
parent_id: &ConversationIdRef,
) -> Result<()>
parent_id
&ConversationIdRef
required
The ID of the parent conversation.
Membership management
add_members
// on ConversationGuard
pub async fn add_members(
&mut self,
key_packages: Vec<KeyPackageIn>,
) -> Result<NewCrlDistributionPoints>
MlsTransport::send_commit_bundle and merged locally on success.
key_packages
Vec<KeyPackageIn>
required
Deserialised KeyPackageIn objects for each new member.
Any new CRL distribution points found in the incoming X.509 credentials. Your application should fetch these CRLs and register them with e2ei_register_crl.
let tx = cc.new_transaction().await?;
let mut guard = tx.conversation(&conv_id).await?;
guard.add_members(key_packages).await?;
tx.finish().await?;
remove_members
// on ConversationGuard
pub async fn remove_members(
&mut self,
clients: &[impl Borrow<ClientIdRef>],
) -> Result<()>
The client IDs to remove.
update_key_material
// on ConversationGuard
pub async fn update_key_material(&mut self) -> Result<()>
commit_pending_proposals
// on ConversationGuard
pub async fn commit_pending_proposals(&mut self) -> Result<()>
Proposals
Proposals are pre-staged changes that a member can create without yet committing them. Another member (or the same one) then commits them.
new_add_proposal
pub async fn new_add_proposal(
&self,
id: &ConversationId,
key_package: KeyPackage,
) -> Result<MlsProposalBundle>
new_remove_proposal
pub async fn new_remove_proposal(
&self,
id: &ConversationId,
client_id: ClientId,
) -> Result<MlsProposalBundle>
new_update_proposal
pub async fn new_update_proposal(
&self,
id: &ConversationId,
) -> Result<MlsProposalBundle>
Messaging
encrypt_message
// on ConversationGuard
pub async fn encrypt_message(
&mut self,
message: impl AsRef<[u8]>,
) -> Result<Vec<u8>>
MlsCiphertext.
Encryption is not available when there is a pending commit or pending proposals. Commit or clear them first.
The raw plaintext bytes to encrypt.
TLS-serialised MlsCiphertext ready to be forwarded to the Delivery Service.
let tx = cc.new_transaction().await?;
let mut guard = tx.conversation(&conv_id).await?;
let ciphertext = guard.encrypt_message(b"Hello, world!").await?;
tx.finish().await?;
decrypt_message
// on ConversationGuard
pub async fn decrypt_message(
&mut self,
message: impl AsRef<[u8]>,
) -> Result<MlsConversationDecryptMessage>
TLS-serialised MlsMessage bytes received from the Delivery Service.
MlsConversationDecryptMessage
MlsConversationDecryptMessage
MlsConversationDecryptMessage
pub struct MlsConversationDecryptMessage {
pub app_msg: Option<Vec<u8>>,
pub proposals: Vec<MlsProposalBundle>,
pub is_active: bool,
pub delay: Option<u64>,
pub sender_client_id: Option<ClientId>,
/// Deprecated: prefer the EpochObserver interface
#[deprecated]
pub has_epoch_changed: bool,
pub identity: WireIdentity,
pub buffered_messages: Option<Vec<MlsBufferedConversationDecryptMessage>>,
pub crl_new_distribution_points: NewCrlDistributionPoints,
}
The decrypted application message payload. None for commit and proposal messages.
Renewed proposals that could not be included in a received commit. Your application should re-fan these out to other members.
false when the current client was removed from the group by the commit just processed. The conversation is wiped locally in that case.
Suggested delay in seconds before the client should commit pending proposals. Provided to pace commit storms.
The ClientId of the sender. Present only for application messages.
true if processing this message caused an epoch change. Deprecated — prefer implementing the EpochObserver interface instead, which provides richer epoch-change notifications.
Identity claims from the sender’s credential. See WireIdentity. buffered_messages
Option<Vec<MlsBufferedConversationDecryptMessage>>
Messages that were received before their epoch’s commit and buffered. Replayed automatically once the commit arrives. Present only on commit decryption.
crl_new_distribution_points
New CRL distribution points introduced by credentials in this message. Fetch and register them with e2ei_register_crl.
External commits
join_by_external_commit
pub async fn join_by_external_commit(
&self,
group_info: VerifiableGroupInfo,
credential_ref: &CredentialRef,
) -> Result<WelcomeBundle>
MlsTransport::send_commit_bundle, and merges locally on acceptance.
If the Delivery Service rejects the commit, clear the pending state and retry by calling this method again with a fresh VerifiableGroupInfo.
group_info
VerifiableGroupInfo
required
A VerifiableGroupInfo (TLS-deserialised from the DS). Must include the ratchet tree extension.
Credential to use when joining the group.
Contains the new ConversationId and any CRL distribution points from the group.
Secret export and sub-conversations
export_secret_key
// on ConversationGuard (via Conversation trait)
pub async fn export_secret_key(
&self,
key_length: usize,
) -> Result<Vec<u8>>
key_length bytes from the current group epoch using the MLS exporter. Used to bootstrap sub-protocols.
Desired output length in bytes. Must not exceed u16::MAX or context_hash * 255.
get_external_sender
// on ConversationGuard (via Conversation trait)
pub async fn get_external_sender(&self) -> Result<Vec<u8>>
wipe (wipe_conversation)
// on ConversationGuard
pub async fn wipe(&mut self) -> Result<()>
MlsCommitBundle
Returned internally when a commit is produced. Passed to MlsTransport::send_commit_bundle.
pub struct MlsCommitBundle {
pub welcome: Option<MlsMessageOut>,
pub commit: MlsMessageOut,
pub group_info: MlsGroupInfoBundle,
pub encrypted_message: Option<Vec<u8>>,
}
Welcome message for newly added members. None if no members were added.
The commit message to be fanned out to existing group members.
Updated GroupInfo for clients that want to join via external commit after this epoch.
An optional encrypted message to fan out to the new epoch. Reserved for history sharing.
