Struct CentralContext

pub struct CentralContext { /* private fields */ }

This struct provides transactional support for Core Crypto.

This is struct provides mutable access to the internals of Core Crypto. Every operation that causes data to be persisted needs to be done through this struct. This struct will buffer all operations in memory and when CentralContext::finish is called, it will persist the data into the keystore.

Implementations

impl CentralContext

pub async fn get_or_create_client_keypackages( &self, ciphersuite: MlsCiphersuite, credential_type: MlsCredentialType, amount_requested: usize, ) -> Result<Vec<KeyPackage>, Error>

Returns amount_requested OpenMLS openmls::key_packages::KeyPackages. Will always return the requested amount as it will generate the necessary (lacking) amount on-the-fly

Note: Keypackage pruning is performed as a first step

Arguments

• amount_requested - number of KeyPackages to request and fill the KeyPackageBundle

Return type

A vector of KeyPackageBundle

Errors

Errors can happen when accessing the KeyStore

pub async fn client_valid_key_packages_count( &self, ciphersuite: MlsCiphersuite, credential_type: MlsCredentialType, ) -> Result<usize, Error>

Returns the count of valid, non-expired, unclaimed keypackages in store for the given MlsCiphersuite and MlsCredentialType

pub async fn delete_keypackages( &self, refs: &[KeyPackageRef], ) -> Result<(), Error>

Prunes local KeyPackages after making sure they also have been deleted on the backend side You should only use this after CentralContext::save_x509_credential

impl CentralContext

pub async fn set_raw_external_senders( &self, cfg: &mut MlsConversationConfiguration, external_senders: Vec<Vec<u8>>, ) -> Result<()>

Parses supplied key from Delivery Service in order to build back an [ExternalSender]

impl CentralContext

pub async fn process_raw_welcome_message( &self, welcome: Vec<u8>, custom_cfg: MlsCustomConfiguration, ) -> Result<WelcomeBundle>

Create a conversation from a TLS serialized MLS Welcome message. The MlsConversationConfiguration used in this function will be the default implementation.

Arguments

• welcome - a TLS serialized welcome message
• configuration - configuration of the MLS conversation fetched from the Delivery Service

Return type

This function will return the conversation/group id

Errors

see CentralContext::process_welcome_message

pub async fn process_welcome_message( &self, welcome: MlsMessageIn, custom_cfg: MlsCustomConfiguration, ) -> Result<WelcomeBundle>

Create a conversation from a received MLS Welcome message

Arguments

• welcome - a Welcome message received as a result of a commit adding new members to a group
• configuration - configuration of the group/conversation

Return type

This function will return the conversation/group id

Errors

Errors can be originating from the KeyStore of from OpenMls:

• if no openmls::key_packages::KeyPackage can be read from the KeyStore
• if the message can’t be decrypted

impl CentralContext

pub async fn wipe_conversation(&self, id: &ConversationId) -> Result<()>

Destroys a group locally

Errors

KeyStore errors, such as IO

impl CentralContext

pub async fn conversation( &self, id: &ConversationId, ) -> Result<ConversationGuard>

Acquire a conversation guard.

This helper struct permits mutations on a conversation.

impl CentralContext

pub async fn join_by_external_commit( &self, group_info: VerifiableGroupInfo, custom_cfg: MlsCustomConfiguration, credential_type: MlsCredentialType, ) -> Result<WelcomeBundle>

Issues an external commit and stores the group in a temporary table. This method is intended for example when a new client wants to join the user’s existing groups. On success this function will return the group id and a message to be fanned out to other clients.

If the Delivery Service accepts the external commit, you have to [PendingConversation::merge] in order to get back a functional MLS group. On the opposite, if it rejects it, you can either retry by just calling again CentralContext::join_by_external_commit.

Arguments

• group_info - a GroupInfo wrapped in a MLS message. it can be obtained by deserializing a TLS serialized GroupInfo object
• custom_cfg - configuration of the MLS conversation fetched from the Delivery Service
• credential_type - kind of openmls::prelude::Credential to use for joining this group. If MlsCredentialType::Basic is chosen and no Credential has been created yet for it, a new one will be generated. When MlsCredentialType::X509 is chosen, it fails when no openmls::prelude::Credential has been created for the given Ciphersuite.

Returns WelcomeBundle

Errors

Errors resulting from OpenMls, the KeyStore calls and serialization

impl CentralContext

pub async fn new_external_add_proposal( &self, conversation_id: ConversationId, epoch: GroupEpoch, ciphersuite: MlsCiphersuite, credential_type: MlsCredentialType, ) -> Result<MlsMessageOut>

Crafts a new external Add proposal. Enables a client outside a group to request addition to this group. For Wire only, the client must belong to an user already in the group

Arguments

• conversation_id - the group/conversation id
• epoch - the current epoch of the group. See openmls::group::GroupEpoch
• ciphersuite - of the new openmls::prelude::KeyPackage to create
• credential_type - of the new openmls::prelude::KeyPackage to create

Return type

Returns a message with the proposal to be add a new client

Errors

Errors resulting from the creation of the proposal within OpenMls. Fails when credential_type is MlsCredentialType::X509 and no Credential has been created for it beforehand with CentralContext::e2ei_mls_init_only or variants.

impl CentralContext

pub async fn new_add_proposal( &self, id: &ConversationId, key_package: KeyPackage, ) -> Result<MlsProposalBundle>

Creates a new Add proposal

pub async fn new_remove_proposal( &self, id: &ConversationId, client_id: ClientId, ) -> Result<MlsProposalBundle>

Creates a new Add proposal

pub async fn new_update_proposal( &self, id: &ConversationId, ) -> Result<MlsProposalBundle>

Creates a new Add proposal

impl CentralContext

pub async fn mls_init( &self, identifier: ClientIdentifier, ciphersuites: Vec<MlsCiphersuite>, nb_init_key_packages: Option<usize>, ) -> Result<()>

Initializes the MLS client if super::CoreCrypto has previously been initialized with CoreCrypto::deferred_init instead of CoreCrypto::new. This should stay as long as proteus is supported. Then it should be removed.

pub async fn mls_generate_keypairs( &self, ciphersuites: Vec<MlsCiphersuite>, ) -> Result<Vec<ClientId>>

Generates MLS KeyPairs/CredentialBundle with a temporary, random client ID. This method is designed to be used in conjunction with CentralContext::mls_init_with_client_id and represents the first step in this process.

This returns the TLS-serialized identity keys (i.e. the signature keypair’s public key)

pub async fn mls_init_with_client_id( &self, client_id: ClientId, tmp_client_ids: Vec<ClientId>, ciphersuites: Vec<MlsCiphersuite>, ) -> Result<()>

Updates the current temporary Client ID with the newly provided one. This is the second step in the externally-generated clients process

Important: This is designed to be called after CentralContext::mls_generate_keypairs

pub async fn client_public_key( &self, ciphersuite: MlsCiphersuite, credential_type: MlsCredentialType, ) -> Result<Vec<u8>>

see MlsCentral::client_public_key

pub async fn client_id(&self) -> Result<ClientId>

see MlsCentral::client_id

pub async fn new_conversation( &self, id: &ConversationId, creator_credential_type: MlsCredentialType, config: MlsConversationConfiguration, ) -> Result<()>

Create a new empty conversation

Arguments

• id - identifier of the group/conversation (must be unique otherwise the existing group will be overridden)
• creator_credential_type - kind of credential the creator wants to create the group with
• config - configuration of the group/conversation

Errors

Errors can happen from the KeyStore or from OpenMls for ex if no openmls::key_packages::KeyPackage can be found in the KeyStore

pub async fn conversation_exists(&self, id: &ConversationId) -> Result<bool>

Checks if a given conversation id exists locally

pub async fn random_bytes(&self, len: usize) -> Result<Vec<u8>>

Generates a random byte array of the specified size

impl CentralContext

pub async fn e2ei_verify_group_state( &self, group_info: VerifiableGroupInfo, ) -> Result<E2eiConversationState>

See MlsCentral::e2ei_verify_group_state.

pub async fn get_credential_in_use( &self, group_info: VerifiableGroupInfo, credential_type: MlsCredentialType, ) -> Result<E2eiConversationState>

See MlsCentral::get_credential_in_use.

impl CentralContext

pub async fn e2ei_is_enabled( &self, signature_scheme: SignatureScheme, ) -> Result<bool>

See MlsCentral::e2ei_is_enabled

impl CentralContext

pub async fn e2ei_is_pki_env_setup(&self) -> Result<bool>

See MlsCentral::e2ei_is_pki_env_setup. Unlike MlsCentral::e2ei_is_pki_env_setup, this function returns a result.

pub async fn e2ei_dump_pki_env(&self) -> Result<Option<E2eiDumpedPkiEnv>>

See MlsCentral::e2ei_dump_pki_env.

pub async fn e2ei_register_acme_ca( &self, trust_anchor_pem: String, ) -> Result<()>

Registers a Root Trust Anchor CA for the use in E2EI processing.

Please note that without a Root Trust Anchor, all validations will fail; So this is the first step to perform after initializing your E2EI client

Parameters

• trust_anchor_pem - PEM certificate to anchor as a Trust Root

pub async fn e2ei_register_intermediate_ca_pem( &self, cert_pem: String, ) -> Result<NewCrlDistributionPoint>

Registers an Intermediate CA for the use in E2EI processing.

Please note that a Root Trust Anchor CA is needed to validate Intermediate CAs; You need to have a Root CA registered before calling this

Parameters

• cert_pem - PEM certificate to register as an Intermediate CA

pub async fn e2ei_register_crl( &self, crl_dp: String, crl_der: Vec<u8>, ) -> Result<CrlRegistration>

Registers a CRL for the use in E2EI processing.

Please note that a Root Trust Anchor CA is needed to validate CRLs; You need to have a Root CA registered before calling this

Parameters

• crl_dp - CRL Distribution Point; Basically the URL you fetched it from
• crl_der - DER representation of the CRL

Returns

A CrlRegistration with the dirty state of the new CRL (see struct) and its expiration timestamp

impl CentralContext

pub async fn e2ei_new_activation_enrollment( &self, display_name: String, handle: String, team: Option<String>, expiry_sec: u32, ciphersuite: MlsCiphersuite, ) -> Result<E2eiEnrollment>

Generates an E2EI enrollment instance for a “regular” client (with a Basic credential) willing to migrate to E2EI. As a consequence, this method does not support changing the ClientId which should remain the same as the Basic one. Once the enrollment is finished, use the instance in CentralContext::save_x509_credential to save the new credential.

pub async fn e2ei_new_rotate_enrollment( &self, display_name: Option<String>, handle: Option<String>, team: Option<String>, expiry_sec: u32, ciphersuite: MlsCiphersuite, ) -> Result<E2eiEnrollment>

Generates an E2EI enrollment instance for a E2EI client (with a X509 certificate credential) having to change/rotate their credential, either because the former one is expired or it has been revoked. As a consequence, this method does not support changing neither ClientId which should remain the same as the previous one. It lets you change the DisplayName or the handle if you need to. Once the enrollment is finished, use the instance in CentralContext::save_x509_credential to do the rotation.

pub async fn save_x509_credential( &self, enrollment: &mut E2eiEnrollment, certificate_chain: String, ) -> Result<NewCrlDistributionPoint>

Saves a new X509 credential. Requires first having enrolled a new X509 certificate with either CentralContext::e2ei_new_activation_enrollment or CentralContext::e2ei_new_rotate_enrollment.

Expected actions to perform after this function (in this order)

1. Rotate credentials for each conversation in crate::mls::conversation::ConversationGuard::e2ei_rotate
2. Generate new key packages with [Client::generate_new_keypackages]
3. Use these to replace the stale ones the in the backend
4. Delete the stale ones locally using Self::delete_stale_key_packages
   • This is the last step because you might still need the old key packages to avoid an orphan welcome message

pub async fn delete_stale_key_packages( &self, cipher_suite: MlsCiphersuite, ) -> Result<()>

Deletes all key packages whose leaf node’s credential does not match the most recently saved x509 credential with the provided signature scheme.

impl CentralContext

pub async fn e2ei_enrollment_stash( &self, enrollment: E2eiEnrollment, ) -> Result<Vec<u8>>

Allows persisting an active enrollment (for example while redirecting the user during OAuth) in order to resume it later with CentralContext::e2ei_enrollment_stash_pop

Arguments

• enrollment - the enrollment instance to persist

Returns

A handle for retrieving the enrollment later on

pub async fn e2ei_enrollment_stash_pop( &self, handle: Vec<u8>, ) -> Result<E2eiEnrollment>

Fetches the persisted enrollment and deletes it from the keystore

Arguments

• handle - returned by CentralContext::e2ei_enrollment_stash

impl CentralContext

pub async fn e2ei_new_enrollment( &self, client_id: ClientId, display_name: String, handle: String, team: Option<String>, expiry_sec: u32, ciphersuite: MlsCiphersuite, ) -> Result<E2eiEnrollment>

Creates an enrollment instance with private key material you can use in order to fetch a new x509 certificate from the acme server.

Parameters

• client_id - client identifier e.g. b7ac11a4-8f01-4527-af88-1c30885a7931:6add501bacd1d90e@example.com
• display_name - human readable name displayed in the application e.g. Smith, Alice M (QA)
• handle - user handle e.g. alice.smith.qa@example.com
• expiry_sec - generated x509 certificate expiry in seconds

pub async fn e2ei_mls_init_only( &self, enrollment: &mut E2eiEnrollment, certificate_chain: String, nb_init_key_packages: Option<usize>, ) -> Result<NewCrlDistributionPoint>

Parses the ACME server response from the endpoint fetching x509 certificates and uses it to initialize the MLS client with a certificate

impl CentralContext

pub async fn proteus_init(&self) -> Result<()>

Initializes the proteus client

pub async fn proteus_reload_sessions(&self) -> Result<()>

Reloads the sessions from the key store

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or it will do nothing

pub async fn proteus_session_from_prekey( &self, session_id: &str, prekey: &[u8], ) -> Result<Arc<RwLock<ProteusConversationSession>>>

Creates a proteus session from a prekey

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_session_from_message( &self, session_id: &str, envelope: &[u8], ) -> Result<(Arc<RwLock<ProteusConversationSession>>, Vec<u8>)>

Creates a proteus session from a Proteus message envelope

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_session_save(&self, session_id: &str) -> Result<()>

Saves a proteus session in the keystore

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_session_delete(&self, session_id: &str) -> Result<()>

Deletes a proteus session from the keystore

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_session( &self, session_id: &str, ) -> Result<Option<Arc<RwLock<ProteusConversationSession>>>>

Proteus session accessor

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_session_exists(&self, session_id: &str) -> Result<bool>

Proteus session exists

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_decrypt( &self, session_id: &str, ciphertext: &[u8], ) -> Result<Vec<u8>>

Decrypts a proteus message envelope

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_encrypt( &self, session_id: &str, plaintext: &[u8], ) -> Result<Vec<u8>>

Encrypts proteus message for a given session ID

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_encrypt_batched( &self, sessions: &[impl AsRef<str>], plaintext: &[u8], ) -> Result<HashMap<String, Vec<u8>>>

Encrypts a proteus message for several sessions ID. This is more efficient than other methods as the calls are batched. This also reduces the rountrips when crossing over the FFI

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_new_prekey(&self, prekey_id: u16) -> Result<Vec<u8>>

Creates a new Proteus prekey and returns the CBOR-serialized version of the prekey bundle

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_new_prekey_auto(&self) -> Result<(u16, Vec<u8>)>

Creates a new Proteus prekey with an automatically incremented ID and returns the CBOR-serialized version of the prekey bundle

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_last_resort_prekey(&self) -> Result<Vec<u8>>

Returns the last resort prekey

pub fn proteus_last_resort_prekey_id() -> u16

Returns the proteus last resort prekey id (u16::MAX = 65535)

pub async fn proteus_fingerprint(&self) -> Result<String>

Returns the proteus identity’s public key fingerprint

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_fingerprint_local( &self, session_id: &str, ) -> Result<String>

Returns the proteus identity’s public key fingerprint

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_fingerprint_remote( &self, session_id: &str, ) -> Result<String>

Returns the proteus identity’s public key fingerprint

Warning: The Proteus client MUST be initialized with CentralContext::proteus_init first or an error will be returned

pub async fn proteus_cryptobox_migrate(&self, path: &str) -> Result<()>

Migrates an existing Cryptobox data store (whether a folder or an IndexedDB database) located at path to the keystore.

The client can then be initialized with CentralContext::proteus_init

impl CentralContext

pub async fn mls_provider(&self) -> Result<MlsCryptoProvider>

Clones all references that the MlsCryptoProvider comprises.

pub async fn finish(&self) -> Result<()>

Commits the transaction, meaning it takes all the enqueued operations and persist them into the keystore. After that the internal state is switched to invalid, causing errors if something is called from this object.

pub async fn abort(&self) -> Result<()>

Aborts the transaction, meaning it discards all the enqueued operations. After that the internal state is switched to invalid, causing errors if something is called from this object.

pub async fn set_data(&self, data: Vec<u8>) -> Result<()>

Set arbitrary data to be retrieved by CentralContext::get_data. This is meant to be used as a check point at the end of a transaction. The data should be limited to a reasonable size.

pub async fn get_data(&self) -> Result<Option<Vec<u8>>>

Get the data that has previously been set by CentralContext::set_data. This is meant to be used as a check point at the end of a transaction.

Trait Implementations

impl Clone for CentralContext

fn clone(&self) -> CentralContext

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CentralContext

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

Formats the value using the given formatter.