Struct StagedWelcome 

pub struct StagedWelcome { /* private fields */ }

Available on 32-bit or 64-bit only.

A StagedWelcome can be inspected and then turned into a MlsGroup. This allows checking who authored the Welcome message.

Implementations

impl StagedWelcome

pub fn new_from_welcome<Provider: OpenMlsProvider>( provider: &Provider, mls_group_config: &MlsGroupJoinConfig, welcome: Welcome, ratchet_tree: Option<RatchetTreeIn>, ) -> Result<Self, WelcomeError<Provider::StorageError>>

Creates a new staged welcome from a Welcome message. Returns an error (WelcomeError::NoMatchingKeyPackage) if no KeyPackage can be found. Note: calling this function will consume the key material for decrypting the Welcome message, even if the caller does not turn the StagedWelcome into an MlsGroup. A virtual client’s key material is only consumed by Self::into_group.

pub fn build_from_welcome<'a, Provider: OpenMlsProvider>( provider: &'a Provider, mls_group_config: &MlsGroupJoinConfig, welcome: Welcome, ) -> Result<JoinBuilder<'a, Provider>, WelcomeError<Provider::StorageError>>

Similar to StagedWelcome::new_from_welcome but as a builder.

The builder allows to set the ratchet tree, skip leaf node lifetime validation, and get the ProcessedWelcome for inspection before staging.

pub fn build_from_branch<'a, Provider: OpenMlsProvider>( provider: &'a Provider, mls_group_config: &MlsGroupJoinConfig, welcome: Welcome, branch_info: BranchInfo, ) -> Result<JoinBuilder<'a, Provider>, WelcomeError<Provider::StorageError>>

Builder to create a StagedWelcome for a subgroup branched from a parent group, as described in RFC 9420 §11.3.

The parent group’s parameters are provided via branch_info, which the parent exports with MlsGroup::branch_info.

In addition to the regular StagedWelcome::build_from_welcome processing, this uses the parent’s resumption PSK secret (which is required to derive the subgroup’s key schedule from the branch PSK) and enforces the receiver-side checks the RFC mandates when joining a branched subgroup.

The branch PSK carried in the Welcome must reference the same parent group and epoch as the supplied branch_info.

The remaining checks run when JoinBuilder::build is called:

• the protocol version and ciphersuite match the parent group,
• the subgroup is at epoch 1, and
• every member of the subgroup matches a member of the parent group (unless disabled via JoinBuilder::check_members).

Matching members is left to the application by the RFC; here we use credential equality for equivalent identifiers.

If the receiver does not yet know which parent epoch the branch was taken from (its own view of the parent group may have advanced), use StagedWelcome::process_resuming_welcome to read the parent reference from the Welcome first and then pick the matching branch_info. This one-shot method is a convenience for callers who already know the parent and epoch.

pub fn build_from_reinit<'a, Provider: OpenMlsProvider>( provider: &'a Provider, mls_group_config: &MlsGroupJoinConfig, welcome: Welcome, reinit_info: ReInitInfo, ) -> Result<JoinBuilder<'a, Provider>, WelcomeError<Provider::StorageError>>

Builder to create a StagedWelcome for a reinit of a predecessor group, as described in RFC 9420 §11.2.

The predecessor group’s parameters are provided via reinit_info, which the predecessor exports with MlsGroup::reinit_info.

In addition to the regular StagedWelcome::build_from_welcome processing, this uses the predecessor’s resumption PSK secret (which is required to derive the new key schedule from the reinit PSK) and enforces the receiver-side checks the RFC mandates when joining a reinitialized group.

The reinit PSK carried in the Welcome must reference the same predecessor group and epoch as the supplied reinit_info.

The remaining checks run when JoinBuilder::build is called:

• the protocol version, ciphersuite, group_id, and extensions match the reinit proposal in the predecessor,
• the welcome is at epoch 1, and
• the set of member credentials is identical to the predecessor (unless disabled via JoinBuilder::check_members).

Matching members is left to the application by the RFC; here we use credential equality for equivalent identifiers.

If the receiver does not yet know which predecessor group is being reinitialized, use StagedWelcome::process_resuming_welcome to read the psk_id from the Welcome first and then pick the matching reinit_info. This one-shot method is a convenience for callers that already know the predecessor.

pub fn process_resuming_welcome<Provider: OpenMlsProvider>( provider: &Provider, mls_group_config: &MlsGroupJoinConfig, welcome: Welcome, ) -> Result<PendingResumingWelcome, WelcomeError<Provider::StorageError>>

Decrypt a Welcome’s group secrets so its branch or reinit reference can be inspected before selecting the matching BranchInfo or ReInitInfo.

Call PendingResumingWelcome::required_resumption_secret to read the parent or predecessor (group_id, epoch) the group derives from (RFC 9420 §8.4), select the BranchInfo or ReInitInfo for that source, then finish with PendingResumingWelcome::build_from_branch or PendingResumingWelcome::build_from_reinit.

If PendingResumingWelcome::required_resumption_secret returns None the Welcome is not a branch or reinit welcome and must be completed with PendingResumingWelcome::build.

pub fn welcome_sender_index(&self) -> LeafNodeIndex

Returns the LeafNodeIndex of the group member that authored the Welcome message.

pub fn welcome_sender(&self) -> Result<&LeafNode, LibraryError>

Returns the LeafNode of the group member that authored the Welcome message.

pub fn own_leaf_index(&self) -> LeafNodeIndex

Returns the leaf index of the client in this welcome’s PublicGroup.

pub fn own_leaf_node(&self) -> Option<&LeafNode>

Returns the leaf node of the client in this welcome’s PublicGroup.

pub fn group_context(&self) -> &GroupContext

Get the GroupContext of this welcome’s PublicGroup.

pub fn members(&self) -> impl Iterator<Item = Member> + '_

Get an iterator over all Members of this welcome’s PublicGroup.

pub fn application_export_secret(&self) -> &ApplicationExportSecret

Available on crate feature extensions-draft only.

Get the ApplicationExportSecret of this welcome.

pub fn emulation_group(self, emulation_group: bool) -> Self

Available on crate feature virtual-clients-draft only.

Join the group as an emulation group of a virtual client. See MlsGroupCreateConfigBuilder::emulation_group for what an emulation group is.

Nothing on the wire marks a group as an emulation group, so a joiner has to set this itself. Joining an emulation group without it leaves the virtual client’s secrets underived.

pub fn into_group<Provider: OpenMlsProvider>( self, provider: &Provider, ) -> Result<MlsGroup, WelcomeError<Provider::StorageError>>

Consumes the StagedWelcome and returns the respective MlsGroup.

pub fn export_secret<CryptoProvider: OpenMlsCrypto>( &self, crypto: &CryptoProvider, label: &str, context: &[u8], key_length: usize, ) -> Result<ExportedSecret<StagedWelcomeExport>, ExportSecretError>

Exports a secret from the epoch of the group that is joined using this StagedWelcome. Returns ExportSecretError::KeyLengthTooLong if the requested key length is too long.

Trait Implementations

impl Debug for StagedWelcome

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

Formats the value using the given formatter.