core_crypto/mls/credential/

mod.rs

//! This module focuses on [`Credential`]s: cryptographic assertions of identity.
//!
//! Credentials can be basic, or based on an x509 certificate chain.

pub(crate) mod credential_ref;
pub(crate) mod credential_type;
pub(crate) mod crl;
mod error;
mod export_pem;
pub(crate) mod ext;
mod persistence;
pub(crate) mod x509;

use std::sync::Arc;

use core_crypto_keystore::entities::StoredCredential;
use openmls::prelude::{Credential as MlsCredential, CredentialWithKey, KeyPackage, SignatureScheme};
use openmls_basic_credential::SignatureKeyPair;
use openmls_traits::crypto::OpenMlsCrypto;
use tls_codec::Deserialize as _;

pub(crate) use self::error::Result;
pub use self::{
    credential_ref::{CredentialRef, FindFilters, FindFiltersBuilder},
    credential_type::CredentialType,
    error::Error,
};
use crate::{CipherSuite, ClientId, ClientIdRef, OpenMlsError, RecursiveError, TlsCodecError, mls_provider::CRYPTO};

/// A cryptographic credential.
///
/// This is tied to a particular client via either its client id or certificate bundle,
/// depending on its credential type, but is independent of any client instance or storage.
///
/// To attach to a particular client instance and store, see
/// [`TransactionContext::add_credential`][crate::transaction_context::TransactionContext::add_credential].
#[derive(core_crypto_macros::Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct Credential {
    /// Ciphersuite used by this credential
    pub(crate) cipher_suite: CipherSuite,
    /// Credential type
    pub(crate) credential_type: CredentialType,
    /// MLS internal credential. Stores the MLS credential
    pub(crate) mls_credential: MlsCredential,
    /// Public and private keys, and the signature scheme.
    #[sensitive]
    pub(crate) signature_key_pair: SignatureKeyPair,
    /// Earliest point at which this credential is valid, in seconds since the unix epoch.
    ///
    /// For an X509 credential this is the leaf certificate's `not_before` claim. A basic credential has
    /// no such claim: it reads 0 until the credential is persisted, and the insertion time thereafter.
    pub(crate) earliest_validity: u64,
}

impl TryFrom<Arc<StoredCredential>> for Credential {
    type Error = Error;

    fn try_from(stored_credential: Arc<StoredCredential>) -> Result<Credential> {
        let mls_credential = MlsCredential::tls_deserialize(&mut stored_credential.credential.as_slice())
            .map_err(TlsCodecError::deserialize("mls credential"))?;
        let cipher_suite = CipherSuite::try_from(stored_credential.ciphersuite)?;
        let signature_key_pair = openmls_basic_credential::SignatureKeyPair::from_raw(
            cipher_suite.signature_algorithm(),
            stored_credential.private_key.to_owned(),
            stored_credential.public_key.to_owned(),
        );
        let credential_type = mls_credential
            .credential_type()
            .try_into()
            .map_err(RecursiveError::context("loading credential from db"))?;
        let earliest_validity = stored_credential.created_at;
        Ok(Credential {
            cipher_suite,
            signature_key_pair,
            credential_type,
            mls_credential,
            earliest_validity,
        })
    }
}

impl Credential {
    /// Generate a basic credential.
    ///
    /// The result is independent of any client instance and the database; it lives in memory only.
    ///
    /// The earliest validity of this credential is always 0. It will be updated once the credential is added to a
    /// session.
    pub fn basic(cipher_suite: CipherSuite, client_id: ClientId) -> Result<Self> {
        let signature_scheme = cipher_suite.signature_algorithm();
        let (private_key, public_key) = CRYPTO
            .signature_key_gen(signature_scheme)
            .map_err(OpenMlsError::wrap("generating signature key"))?;
        let signature_key_pair = SignatureKeyPair::from_raw(signature_scheme, private_key, public_key);

        Ok(Self {
            cipher_suite,
            credential_type: CredentialType::Basic,
            mls_credential: MlsCredential::new_basic(client_id.into_inner()),
            signature_key_pair,
            earliest_validity: 0,
        })
    }

    /// Recover the public half of the credential which produced a key package.
    ///
    /// The result carries no private signature key, so it can be persisted and it identifies its
    /// client, but it can never sign. That is all a history client ever has: the private key of its
    /// credential is discarded as soon as the history secret is generated, which is what makes
    /// such a client incapable of producing messages of its own.
    pub(crate) fn public_only(key_package: &KeyPackage) -> Result<Self> {
        let cipher_suite = CipherSuite::from(key_package.ciphersuite());
        let leaf_node = key_package.leaf_node();
        let mls_credential = leaf_node.credential().clone();
        let credential_type = mls_credential.credential_type().try_into()?;
        let signature_key_pair = SignatureKeyPair::from_raw(
            cipher_suite.signature_algorithm(),
            Vec::new(),
            leaf_node.signature_key().as_slice().to_vec(),
        );

        Ok(Self {
            cipher_suite,
            credential_type,
            mls_credential,
            signature_key_pair,
            earliest_validity: 0,
        })
    }

    /// Get the Openmls Credential type.
    ///
    /// This stores the credential type (basic/x509).
    pub fn mls_credential(&self) -> &MlsCredential {
        &self.mls_credential
    }

    /// Get the credential type
    pub fn credential_type(&self) -> CredentialType {
        self.credential_type
    }

    /// Get a reference to the `SignatureKeyPair`.
    pub(crate) fn signature_key(&self) -> &SignatureKeyPair {
        &self.signature_key_pair
    }

    /// The **private** half of this credential's signature key.
    pub fn signature_key_bytes(&self) -> &[u8] {
        self.signature_key_pair.private()
    }

    /// Get the signature scheme
    pub fn signature_scheme(&self) -> SignatureScheme {
        self.signature_key_pair.signature_scheme()
    }

    /// Get the cipher suite
    pub fn cipher_suite(&self) -> CipherSuite {
        self.cipher_suite
    }

    /// Generate a `CredentialWithKey`, which combines the credential type with the public portion of the keypair.
    pub fn to_mls_credential_with_key(&self) -> CredentialWithKey {
        CredentialWithKey {
            credential: self.mls_credential.clone(),
            signature_key: self.signature_key_pair.to_public_vec().into(),
        }
    }

    /// Earliest point at which this credential is valid, in seconds since the unix epoch.
    ///
    /// For an X509 credential this is the leaf certificate's `not_before` claim. A basic credential has
    /// no such claim: it reads 0 until the credential is persisted, and the insertion time thereafter.
    pub fn earliest_validity(&self) -> u64 {
        self.earliest_validity
    }

    /// Get the client ID associated with this credential
    pub fn client_id(&self) -> &ClientIdRef {
        self.mls_credential.identity().into()
    }
}

impl From<Credential> for CredentialWithKey {
    fn from(cb: Credential) -> Self {
        Self {
            credential: cb.mls_credential,
            signature_key: cb.signature_key_pair.public().into(),
        }
    }
}

impl Eq for Credential {}
impl PartialEq for Credential {
    fn eq(&self, other: &Self) -> bool {
        self.mls_credential == other.mls_credential && self.earliest_validity == other.earliest_validity && {
            let sk = &self.signature_key_pair;
            let ok = &other.signature_key_pair;
            sk.signature_scheme() == ok.signature_scheme() && sk.public() == ok.public()
            // public key equality implies private key equality
        }
    }
}

#[cfg(test)]
mod tests {
    use rusty_jwt_tools::jsonwebtoken::DecodingKey;
    use wire_e2e_identity::CiphersuiteExt as _;

    use super::{x509::CertificateBundle, *};
    use crate::{
        CredentialType, E2eiConversationState, MlsCiphersuite,
        mls::credential::x509::CertificatePrivateKey,
        test_utils::{
            x509::{CertificateParams, PkiKeypair, X509TestChain},
            *,
        },
    };

    #[apply(all_cred_cipher)]
    async fn basic_clients_can_send_messages(case: TestContext) {
        if !case.is_basic() {
            return;
        }
        let [alice, bob] = case.sessions_basic().await;
        let conversation = case.create_conversation([&alice, &bob]).await;
        assert!(conversation.is_functional_and_contains([&alice, &bob]).await);
    }

    #[apply(all_cred_cipher)]
    async fn certificate_clients_can_send_messages(case: TestContext) {
        if !case.is_x509() {
            return;
        }
        let [alice, bob] = case.sessions_x509().await;
        let conversation = case.create_conversation([&alice, &bob]).await;
        assert!(conversation.is_functional_and_contains([&alice, &bob]).await);
    }

    /// Certificate acquisition converts the raw private keys of our MLS provider to PEM with rusty-jwt-tools.
    #[apply(all_cred_cipher)]
    async fn signature_key_should_convert_to_pem(case: TestContext) {
        if !case.is_basic() {
            return;
        }
        // ciphersuites without a JWS algorithm don't support certificate acquisition
        let Some(alg) = MlsCiphersuite::from(case.cipher_suite()).jws_algorithm() else {
            return;
        };
        let [client_id] = case.client_ids();
        let credential = Credential::basic(case.cipher_suite(), client_id).unwrap();

        let pem = alg.keypair_from_bytes(credential.signature_key_bytes()).unwrap();
        let jwk = alg.public_jwk(&pem).unwrap();
        let public_key = DecodingKey::from_jwk(&jwk).unwrap();
        assert_eq!(
            public_key.try_get_as_bytes().unwrap(),
            credential.signature_key().public()
        );
    }

    #[apply(all_cred_cipher)]
    async fn heterogeneous_clients_can_send_messages(case: TestContext) {
        if !case.supports_x509() {
            return;
        }

        // check that both credentials can initiate/join a group
        let ([x509_session], [basic_session]) = case.sessions_mixed_credential_types().await;

        // That way the conversation creator (Alice) will have a different credential type than Bob
        let (alice, bob) = match case.credential_type {
            CredentialType::Basic => (x509_session, basic_session),
            CredentialType::X509 => (basic_session, x509_session),
        };

        let conversation = case.create_conversation([&alice, &bob]).await;
        assert!(conversation.is_functional_and_contains([&alice, &bob]).await);
    }

    #[apply(all_cred_cipher)]
    async fn should_fail_when_certificate_chain_is_empty(case: TestContext) {
        if !case.supports_x509() {
            return;
        }
        let x509_test_chain = X509TestChain::init_empty(case.signature_scheme());

        let x509_intermediate = x509_test_chain.find_local_intermediate_ca();

        let mut cert = CertificateBundle::rand(&"alice".into(), x509_intermediate);
        cert.certificate_chain = vec![];
        let err = Credential::x509(case.cipher_suite(), cert).unwrap_err();

        assert!(innermost_source_matches!(err, Error::InvalidIdentity));
    }

    #[apply(all_cred_cipher)]
    async fn should_fail_when_signature_key_doesnt_match_certificate_public_key(case: TestContext) {
        if !case.is_x509() {
            return;
        }
        let x509_test_chain = X509TestChain::init_empty(case.signature_scheme());
        let x509_intermediate = x509_test_chain.find_local_intermediate_ca();

        let certs = CertificateBundle::rand(&"alice".into(), x509_intermediate);
        let new_keypair = CRYPTO.signature_key_gen(case.signature_scheme()).unwrap();
        let new_pki_kp = PkiKeypair::new(case.signature_scheme(), new_keypair.0).unwrap();

        let eve_key = CertificatePrivateKey::new(new_pki_kp.signing_key_bytes());
        let cb = CertificateBundle {
            certificate_chain: certs.certificate_chain,
            private_key: eve_key,
            signature_scheme: case.cipher_suite().signature_algorithm(),
        };
        let err = Credential::x509(case.cipher_suite(), cb).unwrap_err();

        assert!(innermost_source_matches!(
            err,
            crate::OpenMlsErrorKind::MlsCryptoError(openmls::prelude::CryptoError::MismatchKeypair),
        ));
    }

    #[apply(all_cred_cipher)]
    async fn should_fail_when_certificate_signature_doesnt_match_ciphersuite(case: TestContext) {
        use openmls::prelude::Ciphersuite;
        if !case.is_x509() {
            return;
        }

        let [alice] = case.sessions_x509().await;
        let conversation = case.create_conversation([&alice]).await;

        let other_cipher_suite = match case.cipher_suite() {
            CipherSuite(Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519) => {
                CipherSuite(Ciphersuite::MLS_128_DHKEMP256_AES128GCM_SHA256_P256)
            }
            _ => CipherSuite(Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519),
        };

        let mixed_cipher_suite_case = TestContext::new(CredentialType::X509, *other_cipher_suite);
        let [bob] = mixed_cipher_suite_case.sessions_x509().await;

        let bob_kp = bob
            .transaction
            .generate_key_package(&bob.initial_credential, None)
            .await
            .unwrap()
            .into();

        assert!(conversation.guard().await.add_members(vec![bob_kp]).await.is_err());
    }

    #[apply(all_cred_cipher)]
    async fn should_not_fail_but_degrade_when_certificate_expired(case: TestContext) {
        if !case.is_x509() {
            return;
        }
        let mut x509_test_chain = case.set_test_chain(&[], &[], None).await;
        let expiration_time = core::time::Duration::from_secs(8);
        let start = web_time::Instant::now();

        let alice_cert = x509_test_chain.issue_simple_certificate_bundle("alice", None);
        let alice_cred = Credential::x509(case.cipher_suite(), alice_cert).unwrap();
        let bob_cert = x509_test_chain.issue_simple_certificate_bundle("bob", Some(expiration_time));
        let bob_cred = Credential::x509(case.cipher_suite(), bob_cert).unwrap();
        let alice = SessionContext::new_with_credential(&case, alice_cred, case.sessions_in_memory)
            .await
            .unwrap();
        let bob = SessionContext::new_with_credential(&case, bob_cred, case.sessions_in_memory)
            .await
            .unwrap();

        let conversation = case.create_conversation([&alice, &bob]).await;
        // this should work since the certificate is not yet expired
        assert!(conversation.is_functional_and_contains([&alice, &bob]).await);

        assert_eq!(
            conversation.guard().await.e2ei_conversation_state().await.unwrap(),
            E2eiConversationState::Verified
        );

        let elapsed = start.elapsed();
        // Give time to the certificate to expire
        if expiration_time > elapsed {
            smol::Timer::after(expiration_time - elapsed + core::time::Duration::from_secs(1)).await;
        }

        assert!(conversation.is_functional_and_contains([&alice, &bob]).await);
        assert_eq!(
            conversation.guard().await.e2ei_conversation_state().await.unwrap(),
            E2eiConversationState::NotVerified
        );
    }

    #[apply(all_cred_cipher)]
    async fn should_not_fail_but_degrade_when_basic_joins(case: TestContext) {
        if !case.is_x509() {
            return;
        }
        Box::pin(async {
            let ([alice, bob], [charlie]) = case.sessions_mixed_credential_types().await;
            let conversation = case.create_conversation([&alice, &bob]).await;

            // this should work since the certificate is not yet expired
            assert!(conversation.is_functional_and_contains([&alice, &bob]).await);
            assert_eq!(
                conversation.guard().await.e2ei_conversation_state().await.unwrap(),
                E2eiConversationState::Verified
            );
            assert_eq!(
                conversation
                    .guard_of(&bob)
                    .await
                    .e2ei_conversation_state()
                    .await
                    .unwrap(),
                E2eiConversationState::Verified
            );

            // Charlie is a basic client that tries to join (i.e. emulates guest links in Wire)
            let conversation = conversation
                .invite_with_credential_notify([(&charlie, &charlie.initial_credential)])
                .await;

            assert_eq!(
                conversation.guard().await.e2ei_conversation_state().await.unwrap(),
                E2eiConversationState::NotVerified
            );
            assert!(conversation.is_functional_and_contains([&alice, &bob, &charlie]).await);
            assert_eq!(
                conversation.guard().await.e2ei_conversation_state().await.unwrap(),
                E2eiConversationState::NotVerified
            );
        })
        .await;
    }

    /// Persisting an X509 credential must not overwrite the certificate's `not_before` claim.
    ///
    /// `Credential::save` used to stamp every credential with the insertion time, which discarded
    /// the claim `Credential::x509` had just computed and made `FindFilters::earliest_validity`
    /// -- documented as "point of earliest validity" -- match nothing.
    #[apply(all_cred_cipher)]
    async fn saving_an_x509_credential_keeps_the_certificate_validity(case: TestContext) {
        if !case.is_x509() {
            return;
        }
        let [alice] = case.sessions().await;
        Box::pin(async move {
            let x509_test_chain = X509TestChain::init_empty(case.signature_scheme());
            let local_ca = x509_test_chain.find_local_intermediate_ca();

            // An hour in the past, so a stamp of "now" is unmistakably different.
            let an_hour_ago = now_std() - core::time::Duration::from_secs(3600);
            // Must be alice's own client id: `add_credential` rejects a credential belonging to
            // anyone else.
            let client_id = alice.get_client_id().await;
            let cert = local_ca.create_and_sign_end_identity(CertificateParams {
                common_name: Some("Alice Smith".to_string()),
                handle: Some("alice_wire".to_string()),
                client_id: Some(client_id),
                validity_start: Some(an_hour_ago),
                ..Default::default()
            });
            let bundle = CertificateBundle::from_certificate_and_issuer(&cert, local_ca);
            let credential = Credential::x509(case.cipher_suite(), bundle).unwrap();

            // The fixture's conversion of `validity_start` can be off by a second, so allow a
            // little slack here; what matters is that this is an hour ago and not "now".
            let from_certificate = credential.earliest_validity();
            assert!(
                from_certificate.abs_diff(an_hour_ago.as_secs()) <= 5,
                "the credential must start out carrying the certificate's `not_before`: \
                 got {from_certificate}, expected about {}",
                an_hour_ago.as_secs()
            );

            let credential_ref = alice
                .add_credential(credential)
                .await
                .expect("adding the credential should succeed");

            assert_eq!(
                credential_ref.earliest_validity(),
                from_certificate,
                "persisting must not replace the certificate claim with the insertion time"
            );
        })
        .await;
    }

    #[apply(all_cred_cipher)]
    async fn should_fail_when_certificate_not_valid_yet(case: TestContext) {
        use crate::OpenMlsErrorKind;

        if !case.is_x509() {
            return;
        }
        let x509_test_chain = X509TestChain::init_empty(case.signature_scheme());

        let tomorrow = now_std() + core::time::Duration::from_secs(3600 * 24);
        let local_ca = x509_test_chain.find_local_intermediate_ca();
        let alice_cert = {
            let name = "alice";
            let common_name = format!("{name} Smith");
            let handle = format!("{}_wire", name.to_lowercase());
            let [client_id] = case.client_ids();
            local_ca.create_and_sign_end_identity(CertificateParams {
                common_name: Some(common_name.clone()),
                handle: Some(handle.clone()),
                client_id: Some(client_id.clone()),
                validity_start: Some(tomorrow),
                ..Default::default()
            })
        };
        let cb = CertificateBundle::from_certificate_and_issuer(&alice_cert, local_ca);
        let err = Credential::x509(case.cipher_suite(), cb).unwrap_err();

        assert!(innermost_source_matches!(
            err,
            OpenMlsErrorKind::MlsCryptoError(openmls::prelude::CryptoError::ExpiredCertificate),
        ))
    }

    /// In order to be WASM-compatible
    // pub fn now() -> wire_e2e_identity::OffsetDateTime {
    //     let now_since_epoch = now_std().as_secs() as i64;
    //     wire_e2e_identity::OffsetDateTime::from_unix_timestamp(now_since_epoch).unwrap()
    // }
    pub(crate) fn now_std() -> std::time::Duration {
        let now = web_time::SystemTime::now();
        now.duration_since(web_time::UNIX_EPOCH).unwrap()
    }
}