openmls/group/mls_group/commit_builder/

external_commits.rs

use openmls_traits::{crypto::OpenMlsCrypto, types::Ciphersuite};
use thiserror::Error;
use tls_codec::Serialize as _;

#[cfg(doc)]
use super::CommitMessageBundle;
#[cfg(doc)]
use crate::treesync::LeafNodeParameters;

use crate::{
    binary_tree::LeafNodeIndex,
    credentials::CredentialWithKey,
    error::LibraryError,
    framing::{ContentType, DecryptedMessage, PublicMessageIn, Sender},
    group::{
        commit_builder::{CommitBuilder, ExternalCommitInfo, Initial},
        past_secrets::MessageSecretsStore,
        public_group::errors::CreationFromExternalError,
        ExternalCommitBuilderFinalizeError, GroupContext, LeafNodeLifetimePolicy, MlsGroup,
        MlsGroupJoinConfig, MlsGroupState, PendingCommitState, ProposalStore, PublicGroup,
        QueuedProposal, ValidationError, PURE_PLAINTEXT_WIRE_FORMAT_POLICY,
    },
    messages::{
        group_info::{GroupInfo, VerifiableGroupInfo},
        proposals::{
            ExternalInitProposal, PreSharedKeyProposal, Proposal, ProposalOrRefType, ProposalType,
            RemoveProposal,
        },
    },
    schedule::{psk::store::ResumptionPskStore, EpochSecrets, InitSecret},
    storage::OpenMlsProvider,
    treesync::RatchetTreeIn,
    versions::ProtocolVersion,
};

/// Error type for the [`ExternalCommitBuilder`].
#[derive(Debug, Error)]
pub enum ExternalCommitBuilderError<StorageError> {
    /// See [`LibraryError`] for more details.
    #[error(transparent)]
    LibraryError(#[from] LibraryError),
    /// No ratchet tree available to build initial tree.
    #[error("No ratchet tree available to build initial tree.")]
    MissingRatchetTree,
    /// No external_pub extension available to join group by external commit.
    #[error("No external_pub extension available to join group by external commit.")]
    MissingExternalPub,
    /// We don't support the ciphersuite of the group we are trying to join.
    #[error("Ciphersuite {0:?} of the group we are trying to join is not supported by the crypto provider.")]
    UnsupportedCiphersuite(Ciphersuite),
    /// This error indicates the public tree is invalid. See
    /// [`CreationFromExternalError`] for more details.
    #[error(transparent)]
    PublicGroupError(#[from] CreationFromExternalError<StorageError>),
    /// An error occurred when writing group to storage
    #[error("An error occurred when writing group to storage.")]
    StorageError(StorageError),
    /// Error validating proposals.
    #[error("Error validating proposals: {0}")]
    InvalidProposal(#[from] ValidationError),
}

/// This is the builder for external commits. It allows you to build an external
/// commit that can be used to join a group externally. Parameters such as
/// optional SelfRemove proposals from other members, the ratchet tree, and the
/// group join configuration can be set in the first builder stage.
///
/// [`Self::build_group`] verifies the group info and ratchet tree and returns
/// a [`CommitBuilder`]. To inspect the verified group info and group context
/// before building the external commit, use [`Self::verify_group`] instead,
/// which returns a [`VerifiedExternalCommitBuilder`].
///
/// The [`CommitBuilder`] stage can be used to add one or more proposals by
/// value to the external commit and specify [`LeafNodeParameters`]. Note that
/// only proposal types that RFC 9420 and the MLS extensions draft allow in an
/// external commit pass validation when the commit is built.
#[derive(Default)]
pub struct ExternalCommitBuilder {
    proposals: Vec<PublicMessageIn>,
    ratchet_tree: Option<RatchetTreeIn>,
    config: MlsGroupJoinConfig,
    validate_lifetimes: LeafNodeLifetimePolicy,
    aad: Vec<u8>,
    /// Whether to join the group as an emulation group of a virtual client. Set
    /// by [`Self::emulation_group`].
    #[cfg(feature = "virtual-clients-draft")]
    emulation_group: bool,
}

impl MlsGroup {
    /// Creates a new [`ExternalCommitBuilder`] to build an external commit.
    pub fn external_commit_builder() -> ExternalCommitBuilder {
        ExternalCommitBuilder::new()
    }
}

impl ExternalCommitBuilder {
    /// Creates a new [`ExternalCommitBuilder`] with default values.
    pub fn new() -> Self {
        Self::default()
    }

    /// Adds SelfRemove proposals to the external commit. Other proposals or
    /// other types of messages are ignored.
    pub fn with_proposals(mut self, proposals: Vec<PublicMessageIn>) -> Self {
        self.proposals = proposals;
        self
    }

    /// Specifies the ratchet tree to use for the external commit. This is only
    /// used if the ratchet tree is not provided in the [`VerifiableGroupInfo`]
    /// extensions. A ratchet tree must be provided, either in the
    /// [`VerifiableGroupInfo`] extensions or via this method.
    pub fn with_ratchet_tree(mut self, ratchet_tree: RatchetTreeIn) -> Self {
        self.ratchet_tree = Some(ratchet_tree);
        self
    }

    /// Specifies the configuration to use for the group built as part of the
    /// external commit. Note that the external commit will always be a
    /// `PublicMessage` regardless of the wire format policy set in the group
    /// config.
    pub fn with_config(mut self, config: MlsGroupJoinConfig) -> Self {
        self.config = config;
        self
    }

    /// Specifies additional authenticated data (AAD) to be included in the
    /// external commit. It applies to the external commit only and is not
    /// retained as the AAD of the group that is being joined.
    pub fn with_aad(mut self, aad: Vec<u8>) -> Self {
        self.aad = aad;
        self
    }

    /// 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 an emulator
    /// client resyncing into one has to set this itself. The external commit
    /// changes membership, so merging it registers the epoch it creates as a
    /// derivation epoch, converging with the members already in the group.
    ///
    /// [`MlsGroupCreateConfigBuilder::emulation_group`]: crate::group::MlsGroupCreateConfigBuilder::emulation_group
    #[cfg(feature = "virtual-clients-draft")]
    pub fn emulation_group(mut self, emulation_group: bool) -> Self {
        self.emulation_group = emulation_group;
        self
    }

    /// Skip the validation of lifetimes in leaf nodes in the ratchet tree.
    /// Note that only the leaf nodes are checked that were never updated.
    ///
    /// By default they are validated.
    pub fn skip_lifetime_validation(mut self) -> Self {
        self.validate_lifetimes = LeafNodeLifetimePolicy::Skip;
        self
    }

    /// Sets how the lifetimes of leaf nodes in the ratchet tree are checked.
    /// [`Self::skip_lifetime_validation`] is the same as passing
    /// [`LeafNodeLifetimePolicy::Skip`].
    pub fn leaf_node_lifetime_policy(mut self, lifetime_policy: LeafNodeLifetimePolicy) -> Self {
        self.validate_lifetimes = lifetime_policy;
        self
    }

    /// Build the [`MlsGroup`] from the provided [`VerifiableGroupInfo`] and
    /// [`CredentialWithKey`].
    ///
    /// This is equivalent to calling [`Self::verify_group`] followed by
    /// [`VerifiedExternalCommitBuilder::build_group`].
    ///
    /// Returns a [`CommitBuilder`] that can be used to further configure the
    /// external commit.
    pub fn build_group<Provider: OpenMlsProvider>(
        self,
        provider: &Provider,
        verifiable_group_info: VerifiableGroupInfo,
        credential_with_key: CredentialWithKey,
    ) -> Result<
        CommitBuilder<'_, Initial, MlsGroup>,
        ExternalCommitBuilderError<Provider::StorageError>,
    > {
        self.verify_group(provider, verifiable_group_info)?
            .build_group(provider, credential_with_key)
    }

    /// Verify the provided [`VerifiableGroupInfo`] and the ratchet tree of the
    /// group to be joined, without building an external commit. The ratchet
    /// tree is taken from the [`VerifiableGroupInfo`] extensions if present,
    /// and from [`Self::with_ratchet_tree`] otherwise.
    ///
    /// Returns a [`VerifiedExternalCommitBuilder`] that exposes the verified
    /// [`GroupInfo`] and [`GroupContext`] and can build the external commit.
    pub fn verify_group<Provider: OpenMlsProvider>(
        self,
        provider: &Provider,
        verifiable_group_info: VerifiableGroupInfo,
    ) -> Result<VerifiedExternalCommitBuilder, ExternalCommitBuilderError<Provider::StorageError>>
    {
        let ExternalCommitBuilder {
            proposals,
            ratchet_tree,
            config,
            aad,
            validate_lifetimes,
            #[cfg(feature = "virtual-clients-draft")]
            emulation_group,
        } = self;

        let group_ciphersuite = verifiable_group_info.ciphersuite();
        provider
            .crypto()
            .supports(group_ciphersuite)
            .map_err(|_| ExternalCommitBuilderError::UnsupportedCiphersuite(group_ciphersuite))?;

        // Set nodes either from the extension or from the `ratchet_tree`.
        let ratchet_tree = match verifiable_group_info.extensions().ratchet_tree() {
            Some(extension) => extension.ratchet_tree().clone(),
            None => match ratchet_tree {
                Some(ratchet_tree) => ratchet_tree,
                None => return Err(ExternalCommitBuilderError::MissingRatchetTree),
            },
        };

        let (public_group, group_info) = PublicGroup::from_ratchet_tree(
            provider.crypto(),
            ratchet_tree,
            verifiable_group_info,
            ProposalStore::new(),
            validate_lifetimes,
        )?;

        Ok(VerifiedExternalCommitBuilder {
            public_group,
            group_info,
            proposals,
            config,
            aad,
            #[cfg(feature = "virtual-clients-draft")]
            emulation_group,
        })
    }
}

/// The second stage of the [`ExternalCommitBuilder`], returned by
/// [`ExternalCommitBuilder::verify_group`]. It holds the verified group info
/// and ratchet tree of the group to be joined, so they can be inspected before
/// the external commit is built.
pub struct VerifiedExternalCommitBuilder {
    public_group: PublicGroup,
    group_info: GroupInfo,
    proposals: Vec<PublicMessageIn>,
    config: MlsGroupJoinConfig,
    aad: Vec<u8>,
    #[cfg(feature = "virtual-clients-draft")]
    emulation_group: bool,
}

impl VerifiedExternalCommitBuilder {
    /// Returns the verified [`GroupInfo`] of the group to be joined.
    pub fn group_info(&self) -> &GroupInfo {
        &self.group_info
    }

    /// Returns the [`GroupContext`] of the group to be joined.
    pub fn group_context(&self) -> &GroupContext {
        self.public_group.group_context()
    }

    /// Build the [`MlsGroup`] from the verified group and the provided
    /// [`CredentialWithKey`].
    ///
    /// Returns a [`CommitBuilder`] that can be used to further configure the
    /// external commit.
    pub fn build_group<Provider: OpenMlsProvider>(
        self,
        provider: &Provider,
        credential_with_key: CredentialWithKey,
    ) -> Result<
        CommitBuilder<'_, Initial, MlsGroup>,
        ExternalCommitBuilderError<Provider::StorageError>,
    > {
        let VerifiedExternalCommitBuilder {
            public_group,
            group_info,
            proposals,
            mut config,
            aad,
            #[cfg(feature = "virtual-clients-draft")]
            emulation_group,
        } = self;

        let group_context = public_group.group_context();

        // Obtain external_pub from GroupInfo extensions.
        let external_pub = group_info
            .extensions()
            .external_pub()
            .ok_or(ExternalCommitBuilderError::MissingExternalPub)?
            .external_pub();

        let (init_secret, kem_output) = InitSecret::from_group_context(
            provider.crypto(),
            group_context,
            external_pub.as_slice(),
        )
        .map_err(|_| {
            ExternalCommitBuilderError::UnsupportedCiphersuite(group_context.ciphersuite())
        })?;

        // The `EpochSecrets` we create here are essentially zero, with the
        // exception of the `InitSecret`, which is all we need here for the
        // external commit.
        let ciphersuite = group_context.ciphersuite();
        let epoch_secrets =
            EpochSecrets::with_init_secret(provider.crypto(), ciphersuite, init_secret)
                .map_err(LibraryError::unexpected_crypto_error)?;
        let (group_epoch_secrets, message_secrets) = epoch_secrets.split_secrets(
            group_context
                .tls_serialize_detached()
                .map_err(LibraryError::missing_bound_check)?,
            public_group.tree_size(),
            // We use a fake own index of 0 here, as we're not going to use the
            // tree for encryption until after the first commit. This issue is
            // tracked in #767.
            LeafNodeIndex::new(0u32),
        );
        let message_secrets_store = MessageSecretsStore::new_with_secret(
            config.past_epoch_deletion_policy(),
            message_secrets,
        );

        let external_init_proposal =
            Proposal::external_init(ExternalInitProposal::from(kem_output));

        // Authenticate the proposals as best as we can
        let serialized_context = group_context
            .tls_serialize_detached()
            .map_err(LibraryError::missing_bound_check)?;
        let mut queued_proposals = Vec::new();
        for message in proposals {
            if message.content_type() != ContentType::Proposal {
                continue; // We only want proposals.
            }
            let decrypted_message = DecryptedMessage::from_inbound_public_message(
                message,
                None,
                serialized_context.clone(),
                provider.crypto(),
                ciphersuite,
            )?;
            let unverified_message = public_group.parse_message(decrypted_message, None)?;
            let verified = unverified_message.verify(
                ciphersuite,
                provider.crypto(),
                ProtocolVersion::default(),
                // The policy of the builder applies to the ratchet tree only.
                LeafNodeLifetimePolicy::Verify,
            )?;
            let queued_proposal = QueuedProposal::from_authenticated_content(
                ciphersuite,
                provider.crypto(),
                verified.content,
                ProposalOrRefType::Reference,
            )?;
            // We ignore any proposal that is not a SelfRemove.
            if queued_proposal.proposal().is_type(ProposalType::SelfRemove) {
                queued_proposals.push(queued_proposal);
            }
        }

        let inline_proposals = [external_init_proposal].into_iter();

        // If there is a group member in the group with the same identity as us,
        // commit a remove proposal.
        let our_signature_key = credential_with_key.signature_key.as_slice();
        let remove_proposal = public_group.members().find_map(|member| {
            (member.signature_key == our_signature_key).then_some(Proposal::remove(
                RemoveProposal {
                    removed: member.index,
                },
            ))
        });

        let inline_proposals = inline_proposals
            .chain(remove_proposal)
            .map(|p| {
                QueuedProposal::from_proposal_and_sender(
                    ciphersuite,
                    provider.crypto(),
                    p,
                    &Sender::NewMemberCommit,
                )
            })
            .collect::<Result<Vec<_>, _>>()?;

        queued_proposals.extend(inline_proposals);

        let own_leaf_index = public_group.leftmost_free_index(queued_proposals.iter())?;

        let original_wire_format_policy = config.wire_format_policy;

        // We set this to PURE_PLAINTEXT_WIRE_FORMAT_POLICY so that the
        // external commit can be sent as a PublicMessageIn. The wire format
        // policy will be set to the original wire format policy after the
        // external commit has been sent.
        config.wire_format_policy = PURE_PLAINTEXT_WIRE_FORMAT_POLICY;

        let mut mls_group = MlsGroup {
            mls_group_config: config,
            own_leaf_nodes: vec![],
            aad: vec![],
            #[cfg(feature = "extensions-draft")]
            safe_aad: crate::framing::SafeAad::empty(),
            group_state: MlsGroupState::Operational,
            public_group,
            group_epoch_secrets,
            own_leaf_index,
            message_secrets_store,
            resumption_psk_store: ResumptionPskStore::new(32),
            // This is set to `None` for now. It will be set once the external
            // commit is merged.
            #[cfg(feature = "extensions-draft")]
            application_export_tree: None,
            #[cfg(feature = "virtual-clients-draft")]
            emulation_group,
        };

        // Add all proposals to the proposal store.
        let proposal_store = mls_group.proposal_store_mut();
        for queued_proposal in queued_proposals {
            proposal_store.add(queued_proposal);
        }

        let mut commit_builder = CommitBuilder::<'_, Initial, MlsGroup>::new(mls_group);

        commit_builder.stage.force_self_update = true;
        commit_builder.stage.bare_aad = Some(aad);
        commit_builder.stage.external_commit_info = Some(ExternalCommitInfo {
            wire_format_policy: original_wire_format_policy,
            credential: credential_with_key,
        });

        Ok(commit_builder)
    }
}

// Impls that only apply to external commits.
impl<'a> CommitBuilder<'a, Initial, MlsGroup> {
    /// Adds a proposal to the proposals to be committed by value. To add
    /// multiple proposals, use [`Self::add_proposals`].
    ///
    /// Only proposal types that are allowed by value in an external commit
    /// (such as PreSharedKey, Remove, or AppEphemeral) pass validation when
    /// the commit is built. Other types cause `build` to fail with
    /// [`ExternalCommitValidationError::InvalidInlineProposals`].
    ///
    /// [`ExternalCommitValidationError::InvalidInlineProposals`]:
    ///     crate::group::errors::ExternalCommitValidationError::InvalidInlineProposals
    pub fn add_proposal(mut self, proposal: Proposal) -> Self {
        self.stage.own_proposals.push(proposal);
        self
    }

    /// Adds the proposals in the iterator to the proposals to be committed by
    /// value. See [`Self::add_proposal`] for the proposal types allowed in an
    /// external commit.
    pub fn add_proposals(mut self, proposals: impl IntoIterator<Item = Proposal>) -> Self {
        self.stage.own_proposals.extend(proposals);
        self
    }

    /// Adds a [`PreSharedKeyProposal`] to the proposals to be committed.
    pub fn add_psk_proposal(mut self, proposal: PreSharedKeyProposal) -> Self {
        self.stage.own_proposals.push(Proposal::psk(proposal));
        self
    }

    /// Adds the [`PreSharedKeyProposal`] in the iterator to the proposals to be
    /// committed.
    pub fn add_psk_proposals(
        mut self,
        proposals: impl IntoIterator<Item = PreSharedKeyProposal>,
    ) -> Self {
        self.stage
            .own_proposals
            .extend(proposals.into_iter().map(Proposal::psk));
        self
    }

    /// Adds an AppDataUpdateProposal.
    #[cfg(feature = "extensions-draft")]
    pub fn add_app_data_update_proposal(
        mut self,
        proposal: crate::messages::proposals::AppDataUpdateProposal,
    ) -> Self {
        self.stage
            .own_proposals
            .push(Proposal::AppDataUpdate(Box::new(proposal)));
        self
    }
}

// Impls that apply only to external commits.
impl CommitBuilder<'_, super::Complete, MlsGroup> {
    /// 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.
    #[openmls_traits::maybe_async]
    pub async fn finalize<Provider: OpenMlsProvider>(
        self,
        provider: &Provider,
    ) -> Result<
        (MlsGroup, super::CommitMessageBundle),
        ExternalCommitBuilderFinalizeError<Provider::StorageError>,
    > {
        let Self {
            mut group,
            stage:
                super::Complete {
                    result: create_commit_result,
                    original_wire_format_policy,
                },
            ..
        } = self;

        // Convert AuthenticatedContent messages to MLSMessage. An external
        // commit is always framed as a PublicMessage, so it carries no
        // handshake confirmation data.
        let mls_message = group
            .content_to_mls_message(create_commit_result.commit, provider)
            .await?
            .message;

        group.reset_aad();

        // Restore the original wire format policy.
        if let Some(wire_format_policy) = original_wire_format_policy {
            group.mls_group_config.wire_format_policy = wire_format_policy;
        }

        // Store the group in storage.
        group
            .store(provider.storage())
            .await
            .map_err(ExternalCommitBuilderFinalizeError::StorageError)?;

        // Set the current group state to [`MlsGroupState::PendingCommit`],
        // storing the current [`StagedCommit`] from the commit results
        group.group_state = MlsGroupState::PendingCommit(Box::new(PendingCommitState::Member(
            create_commit_result.staged_commit,
        )));

        group.merge_pending_commit(provider).await?;

        let bundle = super::CommitMessageBundle {
            version: group.version(),
            commit: mls_message,
            welcome: create_commit_result.welcome_option,
            group_info: create_commit_result.group_info,
            #[cfg(feature = "virtual-clients-draft")]
            confirmation: None,
        };

        Ok((group, bundle))
    }
}