core_crypto/

ephemeral.rs

//! Utilities for ephemeral CoreCrypto instances.
//!
//! Ephemeral instances are intended to support history sharing. History sharing works like this:
//! every history-enabled conversation has a passive "history client" as a member. This client
//! is a member of the MLS group (and can therefore decrypt messages), but it is not actively running
//! on any device or decrypting any messages.
//!
//! Approximately once daily, and whenever a member is removed from the group, a new history-sharing era
//! begins. The client submitting the commit which instantiates the new history-sharing era is responsible
//! for ensuring that the old history client is removed from the group, and new one is added. Additionally,
//! one of the first application messages in the new history-sharing era contains the serialized history
//! secret.
//!
//! When a new client joins the history-enabled conversation, they receive a list of history secrets
//! and their associated history-sharing eras (identified by the epoch number at which they start).
//! For each history-sharing era, they can instantiate an ephemeral client from the history secret,
//! and use that client to decrypt all messages in this era.
//!
//! Though ephemeral clients are full instances of `CoreCrypto` and contain the same API, they cannot
//! be used to generate messages for sending, as they don't posess a credential with a signature key:
//! Any attempt to encrypt a message will fail because the client cannot retrieve the signature key from
//! its keystore.

use std::{borrow::Borrow, sync::Arc};

use core_crypto_keystore::Database;
use obfuscate::{Obfuscate, Obfuscated};
use openmls::prelude::KeyPackageSecretEncapsulation;

use crate::{
    CipherSuite, ClientId, ClientIdRef, CoreCrypto, CoreCryptoTransportNotImplementedProvider, Credential, Error,
    OpenMlsError, RecursiveError, Result, Session, mls_provider::CryptoProvider,
};

/// We always instantiate history clients with this prefix in their client id, so
/// we can use prefix testing to determine with some accuracy whether or not something is a history client.
pub const HISTORY_CLIENT_ID_PREFIX: &str = "history-client";

/// A `HistorySecret` encodes sufficient client state that it can be used to instantiate an
/// ephemeral client.
#[derive(serde::Serialize, serde::Deserialize)]
pub struct HistorySecret {
    /// Client id of the associated history client
    pub client_id: ClientId,
    pub(crate) key_package: KeyPackageSecretEncapsulation,
}

impl Obfuscate for HistorySecret {
    fn obfuscate(&self, f: &mut std::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("HistorySecret")
            .field("client_id", &self.client_id)
            .field("key_package", &Obfuscated::from(&self.key_package))
            .finish()
    }
}

/// Generate a new [`HistorySecret`].
///
/// This is useful when it's this client's turn to generate a new history client.
///
/// The generated secret is cryptographically unrelated to the current CoreCrypto client.
///
/// Note that this is a crate-private function; the public interface for this feature is
/// [`Conversation::generate_history_secret`][crate::mls::conversation::Conversation::generate_history_secret].
/// This implementation lives here instead of there for organizational reasons.
pub(crate) async fn generate_history_secret(cipher_suite: CipherSuite) -> Result<HistorySecret> {
    // generate a new client id
    let session_id = ClientId::new_ephemeral();

    let database =
        Database::open_in_memory().expect("Opening an in-memory database to generate a history secret cannot fail");

    let cc = CoreCrypto::new(database.clone());
    let tx = cc
        .new_transaction()
        .await
        .map_err(RecursiveError::transaction("creating new transaction"))?;

    let transport = Arc::new(CoreCryptoTransportNotImplementedProvider::default());
    tx.mls_init(session_id.clone(), transport)
        .await
        .map_err(RecursiveError::transaction("initializing ephemeral cc"))?;
    let session = tx
        .session()
        .await
        .map_err(RecursiveError::transaction("Getting mls session"))?;
    let credential = Credential::basic(cipher_suite, session_id.clone()).map_err(RecursiveError::mls_credential(
        "generating basic credential for ephemeral client",
    ))?;
    let credential_ref = tx
        .add_credential(credential)
        .await
        .map_err(RecursiveError::transaction(
            "adding basic credential to ephemeral client",
        ))?;

    // we can generate a key package from the ephemeral cc and ciphersutite
    let key_package = tx
        .generate_key_package(&credential_ref, None)
        .await
        .map_err(RecursiveError::transaction("generating keypackage"))?;
    let key_package = KeyPackageSecretEncapsulation::load(&session.crypto_provider, key_package)
        .await
        .map_err(OpenMlsError::wrap("encapsulating key package"))?;

    // we don't need to finish the transaction here--the point of the ephemeral CC was that no mutations would be saved
    // there
    let _ = tx.abort().await;

    Ok(HistorySecret {
        client_id: session_id,
        key_package,
    })
}

pub(crate) fn is_history_client(client_id: impl Borrow<ClientIdRef>) -> bool {
    client_id.borrow().starts_with(HISTORY_CLIENT_ID_PREFIX.as_bytes())
}

impl CoreCrypto {
    /// Instantiate a history client.
    ///
    /// This client exposes the full interface of `CoreCrypto`, but it should only be used to decrypt messages.
    /// Other use is a logic error.
    pub async fn history_client(history_secret: HistorySecret) -> Result<Arc<Self>> {
        if !history_secret
            .client_id
            .starts_with(HISTORY_CLIENT_ID_PREFIX.as_bytes())
        {
            return Err(Error::InvalidHistorySecret("client id has invalid format"));
        }

        // pass in-memory database
        let database =
            Database::open_in_memory().expect("Opening an in-memory database for a history client cannot fail");

        let cc = CoreCrypto::new(database.clone());
        let tx = cc
            .new_transaction()
            .await
            .map_err(RecursiveError::transaction("creating new transaction"))?;

        // store the client id (with some other stuff)
        let mls_backend = CryptoProvider::new(database.clone());
        let transport = Arc::new(CoreCryptoTransportNotImplementedProvider::default());
        let session = Session::new(
            history_secret.client_id.clone(),
            mls_backend,
            database.into(),
            transport,
        );

        session
            .restore_from_history_secret(history_secret)
            .await
            .map_err(RecursiveError::mls_client(
                "restoring ephemeral session from history secret",
            ))?;

        tx.set_mls_session(session)
            .await
            .map_err(RecursiveError::transaction("Setting mls session"))?;

        tx.finish()
            .await
            .map_err(RecursiveError::transaction("finishing transaction"))?;

        Ok(cc)
    }
}

#[cfg(test)]
mod tests {
    use rstest::rstest;
    use rstest_reuse::apply;

    use crate::test_utils::{TestContext, all_cred_cipher};

    /// Create a history secret, and restore it into a CoreCrypto instance
    #[apply(all_cred_cipher)]
    async fn can_create_ephemeral_client(case: TestContext) {
        let [alice] = case.sessions().await;
        let conversation = case.create_conversation([&alice]).await;
        let conversation = conversation.enable_history_sharing_notify().await;

        assert_eq!(
            conversation.member_count().await,
            2,
            "the conversation should now magically have a second member"
        );

        let ephemeral_client = conversation.members().nth(1).unwrap();
        assert!(
            conversation.can_one_way_communicate(&alice, ephemeral_client).await,
            "alice can send messages to the history client"
        );
        assert!(
            !conversation.can_one_way_communicate(ephemeral_client, &alice).await,
            "the history client cannot send messages"
        );
    }
}