Struct CommitBuilder 

pub struct CommitBuilder<'a, T, G = &'a mut MlsGroup>
where
    G: BorrowMut<MlsGroup>,
{ /* private fields */ }

The CommitBuilder is used to easily and dynamically build commit messages. It operates in a series of stages:

The Initial stage is used to populate the builder with proposals and other data using method calls on the builder that let the builder stay in the same stage.

The next stage is LoadedPsks, and it signifies the stage after the builder loaded the the pre-shared keys for the PreSharedKey proposals in this commit.

Then comes the Complete stage, which denotes that all data has been validated. From this stage, the commit can be staged in the group, and the outgoing messages returned.

For example, to create a commit to a new Add proposal with a KeyPackage key_package_to_add that does not commit to the proposals in the proposal store, one could build the commit as follows:

let message_bundle: CommitMessageBundle = mls_group
  .commit_builder()
  .consume_proposal_store(false)
  .add_proposal(key_package_to_add)
  .load_psks(provider.storage())?
  .build(provider.rand(), provider.crypto(), signer, app_policy_proposals)?
  .stage_commit(provider)?;

let commit = message_bundle.commit();
let welcome = message_bundle.welcome().expect("expected a welcome since there was an add");
let group_info = message_bundle.welcome().expect("expected a group info since there was an add");

In this example signer is a reference to a [Signer] and app_policy_proposals is the application-defined policy for which proposals to accept, implemented by an FnMut(&QueuedProposal) -> bool.

See the book for another example.

Implementations

impl<'a> CommitBuilder<'a, Initial, MlsGroup>

pub fn add_psk_proposal( self, proposal: PreSharedKeyProposal, ) -> CommitBuilder<'a, Initial, MlsGroup>

Adds a PreSharedKeyProposal to the proposals to be committed.

pub fn add_psk_proposals( self, proposals: impl IntoIterator<Item = PreSharedKeyProposal>, ) -> CommitBuilder<'a, Initial, MlsGroup>

Adds the PreSharedKeyProposal in the iterator to the proposals to be committed.

impl CommitBuilder<'_, Complete, MlsGroup>

pub fn finalize<Provider>( self, provider: &Provider, ) -> Result<(MlsGroup, CommitMessageBundle), ExternalCommitBuilderFinalizeError<<Provider as OpenMlsProvider>::StorageError>>

where Provider: OpenMlsProvider,

Finalizes and returns the MlsGroup, as well as the [CommitMessageBundle].

In contrast to the deprecated MlsGroup::join_by_external_commit there is no need to merge the pending commit.

impl<'a> CommitBuilder<'a, Initial, &mut MlsGroup>

pub fn consume_proposal_store( self, consume_proposal_store: bool, ) -> CommitBuilder<'a, Initial, &mut MlsGroup>

Sets whether or not the proposals in the proposal store of the group should be included in the commit. Defaults to true.

pub fn force_self_update( self, force_self_update: bool, ) -> CommitBuilder<'a, Initial, &mut MlsGroup>

Sets whether or not the commit should force a self-update. Defaults to false.

pub fn propose_adds( self, key_packages: impl IntoIterator<Item = KeyPackage>, ) -> CommitBuilder<'a, Initial, &mut MlsGroup>

Adds an Add proposal to the provided KeyPackage to the list of proposals to be committed.

pub fn propose_removals( self, removed: impl IntoIterator<Item = LeafNodeIndex>, ) -> CommitBuilder<'a, Initial, &mut MlsGroup>

Adds a Remove proposal for the provided LeafNodeIndexes to the list of proposals to be committed.

pub fn propose_group_context_extensions( self, extensions: Extensions, ) -> CommitBuilder<'a, Initial, &mut MlsGroup>

Adds a GroupContextExtensions proposal for the provided Extensions to the list of proposals to be committed.

pub fn add_proposal( self, proposal: Proposal, ) -> CommitBuilder<'a, Initial, &mut MlsGroup>

Adds a proposal to the proposals to be committed. To add multiple proposals, use Self::add_proposals.

pub fn add_proposals( self, proposals: impl IntoIterator<Item = Proposal>, ) -> CommitBuilder<'a, Initial, &mut MlsGroup>

Adds the proposals in the iterator to the proposals to be committed.

impl<'a, G> CommitBuilder<'a, Initial, G>

where G: BorrowMut<MlsGroup>,

pub fn new(group: G) -> CommitBuilder<'a, Initial, G>

returns a new CommitBuilder for the given MlsGroup.

pub fn create_group_info( self, create_group_info: bool, ) -> CommitBuilder<'a, Initial, G>

Sets whether or not a GroupInfo should be created when the commit is staged. Defaults to the value of the MlsGroups [MlsGroupJoinConfig].

pub fn leaf_node_parameters( self, leaf_node_parameters: LeafNodeParameters, ) -> CommitBuilder<'a, Initial, G>

Sets the leaf node parameters for the new leaf node in a self-update. Implies that a self-update takes place.

pub fn load_psks<Storage>( self, storage: &'a Storage, ) -> Result<CommitBuilder<'a, LoadedPsks, G>, CreateCommitError>

where Storage: StorageProvider,

Loads the PSKs for the PskProposals marked for inclusion and moves on to the next phase.

impl<'a, G> CommitBuilder<'a, LoadedPsks, G>

where G: BorrowMut<MlsGroup>,

pub fn build<S>( self, rand: &impl OpenMlsRand, crypto: &impl OpenMlsCrypto, signer: &S, f: impl FnMut(&QueuedProposal) -> bool, ) -> Result<CommitBuilder<'a, Complete, G>, CreateCommitError>

where S: Signer,

Validates the inputs and builds the commit. The last argument f is a function that lets the caller filter the proposals that are considered for inclusion. This provides a way for the application to enforce custom policies in the creation of commits.

pub fn build_with_new_signer<S>( self, rand: &impl OpenMlsRand, crypto: &impl OpenMlsCrypto, old_signer: &impl Signer, new_signer: NewSignerBundle<'_, S>, f: impl FnMut(&QueuedProposal) -> bool, ) -> Result<CommitBuilder<'a, Complete, G>, CreateCommitError>

where S: Signer,

Just like build, this function validates the inputs and builds the commit. The last argument f is a function that lets the caller filter the proposals that are considered for inclusion. This provides a way for the application to enforce custom policies in the creation of commits.

In contrast to build, this function can be used to create commits that rotate the own leaf node’s signature key.

impl CommitBuilder<'_, Complete, &mut MlsGroup>

pub fn stage_commit<Provider>( self, provider: &Provider, ) -> Result<CommitMessageBundle, CommitBuilderStageError<<Provider as OpenMlsProvider>::StorageError>>

where Provider: OpenMlsProvider,

Stages the commit and returns the protocol messages.

Trait Implementations

impl<'a, T, G> Debug for CommitBuilder<'a, T, G>

where T: Debug, G: Debug + BorrowMut<MlsGroup>,

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

Formats the value using the given formatter.