Past epoch secret deletion

The Delivery Service may not be able to guarantee that application messages from one epoch are sent before the beginning of the next epoch. To address this, applications can configure their groups to keep the necessary key material around for past epochs by configuring the past epoch deletion policy on the MlsGroupCreateConfig.

The PastEpochDeletionPolicy will be applied to the group automatically when a commit is merged.

Setting a past epoch secrets deletion policy for a group

As part of creating a group, the PastEpochDeletionPolicy can be set on a group creation config:

    // set up the group creation config
    let mls_group_create_config = MlsGroupCreateConfig::builder()
        // keep at most 3 past epoch secrets
        .set_past_epoch_deletion_policy(PastEpochDeletionPolicy::MaxEpochs(3))
        .ciphersuite(ciphersuite)
        .build();

The policy can also be updated on an existing group:

    // keep all past epoch secrets by default
    mls_group
        .set_past_epoch_deletion_policy(provider, PastEpochDeletionPolicy::KeepAll)
        .expect("error setting past epoch deletion policy");

    // keep a maximum of 3 past epoch secrets
    mls_group
        .set_past_epoch_deletion_policy(provider, PastEpochDeletionPolicy::MaxEpochs(3))
        .expect("error setting past epoch deletion policy");

Time-based deletion schedules

It is possible to configure time-based deletion schedules for past epoch secrets. The application can periodically apply a PastEpochDeletion using the MlsGroup::delete_past_epoch_secrets() API.

Generally, when time-based deletion schedules are used, it can be helpful to configure the group to use PastEpochDeletionPolicy::KeepAll, to ensure that automatic deletion conducted by the group is not applied early to a past epoch secret.

Delete all past epoch secrets before a provided timestamp:

    // delete all past epoch secrets before a timestamp
    mls_group
        .delete_past_epoch_secrets(provider, PastEpochDeletion::before_timestamp(timestamp))
        .expect("error deleting past epoch secrets");

Delete all past epoch secrets before a provided timestamp, leaving at most a provided number of epochs:

    // delete past epoch secrets before a timestamp, leaving the latest three, at most
    mls_group
        .delete_past_epoch_secrets(
            provider,
            PastEpochDeletion::before_timestamp(timestamp).max_past_epochs(3),
        )
        .expect("error deleting past epoch secrets");

Delete all past epoch secrets older than a provided duration:

    // delete all past epoch secrets older than a duration
    mls_group
        .delete_past_epoch_secrets(
            provider,
            PastEpochDeletion::older_than_duration(Duration::from_hours(48)),
        )
        .expect("error deleting past epoch secrets");

Delete all past epoch secrets older than a provided duration, leaving at most a provided number of epochs:

    // delete all past epoch secrets older than a duration, leaving the latest three, at most
    mls_group
        .delete_past_epoch_secrets(
            provider,
            PastEpochDeletion::older_than_duration(Duration::from_hours(48)).max_past_epochs(3),
        )
        .expect("error deleting past epoch secrets");

Migration and deleting legacy entries

Epoch secrets that were created using openmls=0.8.1 or earlier will not yet include a timestamp.

After migration, these may not always be deleted by applying a time-based PastEpochDeletion. Only if a new secret that does include a timestamp is added later, and it matches the time-based condition in the PastEpochDeletion, all earlier past epoch secrets without timestamps will be deleted, as well. However, otherwise, past epoch secrets without timestamps will not be affected by applying time-based PastEpochDeletions.

After migration, it is possible to manually delete all past epoch secrets without timestamps:

    // delete all past epoch secrets without timestamps
    mls_group
        .delete_past_epoch_secrets(provider, PastEpochDeletion::delete_all_without_timestamps())
        .expect("error deleting past epoch secrets");

Deleting all past epoch secrets

All past epoch secrets can also be deleted at once:

    // delete all past epoch secrets
    mls_group
        .delete_past_epoch_secrets(provider, PastEpochDeletion::delete_all())
        .expect("error deleting past epoch secrets");

Setting the group’s PastEpochDeletionPolicy to PastEpochDeletionPolicy::MaxEpochs(0) will also delete all past epoch secrets.