Struct OlmMachine

pub struct OlmMachine { /* private fields */ }

A high level state machine that handles E2EE for Matrix.

Implementations

impl OlmMachine

pub fn new( user_id: String, device_id: String, path: String, passphrase: Option<String>, ) -> Result<Arc<Self>, CryptoStoreError>

Create a new OlmMachine

Arguments

• user_id - The unique ID of the user that owns this machine.

• device_id - The unique ID of the device that owns this machine.

• path - The path where the state of the machine should be persisted.

• passphrase - The passphrase that should be used to encrypt the data at rest in the crypto store. Warning, if no passphrase is given, the store and all its data will remain unencrypted.

pub fn user_id(&self) -> String

Get the user ID of the owner of this OlmMachine.

pub fn device_id(&self) -> String

Get the device ID of the device of this OlmMachine.

pub fn identity_keys(&self) -> HashMap<String, String>

Get our own identity keys.

pub fn cross_signing_status(&self) -> CrossSigningStatus

Get the status of the private cross signing keys.

This can be used to check which private cross signing keys we have stored locally.

pub fn get_identity( &self, user_id: String, timeout: u32, ) -> Result<Option<UserIdentity>, CryptoStoreError>

Get a cross signing user identity for the given user ID.

Arguments

• user_id - The unique id of the user that the identity belongs to

• timeout - The time in seconds we should wait before returning if the user’s device list has been marked as stale. Passing a 0 as the timeout means that we won’t wait at all. Note, this assumes that the requests from OlmMachine::outgoing_requests are being processed and sent out. Namely, this waits for a /keys/query response to be received.

pub fn is_identity_verified( &self, user_id: String, ) -> Result<bool, CryptoStoreError>

Check if a user identity is considered to be verified by us.

pub fn verify_identity( &self, user_id: String, ) -> Result<SignatureUploadRequest, SignatureError>

Manually the user with the given user ID.

This method will attempt to sign the user identity using either our private cross signing key, for other user identities, or our device keys for our own user identity.

This method can fail if we don’t have the private part of our user-signing key.

Returns a request that needs to be sent out for the user identity to be marked as verified.

pub fn get_device( &self, user_id: String, device_id: String, timeout: u32, ) -> Result<Option<Device>, CryptoStoreError>

Get a Device from the store.

Arguments

• user_id - The id of the device owner.

• device_id - The id of the device itself.

• timeout - The time in seconds we should wait before returning if the user’s device list has been marked as stale. Passing a 0 as the timeout means that we won’t wait at all. Note, this assumes that the requests from OlmMachine::outgoing_requests are being processed and sent out. Namely, this waits for a /keys/query response to be received.

pub fn verify_device( &self, user_id: String, device_id: String, ) -> Result<SignatureUploadRequest, SignatureError>

Manually the device of the given user with the given device ID.

This method will attempt to sign the device using our private cross signing key.

This method will always fail if the device belongs to someone else, we can only sign our own devices.

It can also fail if we don’t have the private part of our self-signing key.

Returns a request that needs to be sent out for the device to be marked as verified.

pub fn set_local_trust( &self, user_id: String, device_id: String, trust_state: LocalTrust, ) -> Result<(), CryptoStoreError>

Set local trust state for the device of the given user without creating or uploading any signatures if verified

pub fn get_user_devices( &self, user_id: String, timeout: u32, ) -> Result<Vec<Device>, CryptoStoreError>

Get all devices of an user.

Arguments

• user_id - The id of the device owner.

• timeout - The time in seconds we should wait before returning if the user’s device list has been marked as stale. Passing a 0 as the timeout means that we won’t wait at all. Note, this assumes that the requests from OlmMachine::outgoing_requests are being processed and sent out. Namely, this waits for a /keys/query response to be received.

pub fn outgoing_requests(&self) -> Result<Vec<Request>, CryptoStoreError>

Get the list of outgoing requests that need to be sent to the homeserver.

After the request was sent out and a successful response was received the response body should be passed back to the state machine using the mark_request_as_sent() method.

Note: This method call should be locked per call.

pub fn mark_request_as_sent( &self, request_id: String, request_type: RequestType, response_body: String, ) -> Result<(), CryptoStoreError>

Mark a request that was sent to the server as sent.

Arguments

• request_id - The unique ID of the request that was sent out. This needs to be an UUID.

• request_type - The type of the request that was sent out.

• response_body - The body of the response that was received.

pub fn receive_sync_changes( &self, events: String, device_changes: DeviceLists, key_counts: HashMap<String, i32>, unused_fallback_keys: Option<Vec<String>>, next_batch_token: String, ) -> Result<SyncChangesResult, CryptoStoreError>

Let the state machine know about E2EE related sync changes that we received from the server.

This needs to be called after every sync, ideally before processing any other sync changes.

Arguments

• events - A serialized array of to-device events we received in the current sync response.

• device_changes - The list of devices that have changed in some way since the previous sync.

• key_counts - The map of uploaded one-time key types and counts.

pub fn update_tracked_users( &self, users: Vec<String>, ) -> Result<(), CryptoStoreError>

Add the given list of users to be tracked, triggering a key query request for them.

The OlmMachine maintains a list of users whose devices we are keeping track of: these are known as “tracked users”. These must be users that we share a room with, so that the server sends us updates for their device lists.

Note: Only users that aren’t already tracked will be considered for an update. It’s safe to call this with already tracked users, it won’t result in excessive /keys/query requests.

Arguments

users - The users that should be queued up for a key query.

pub fn is_user_tracked(&self, user_id: String) -> Result<bool, CryptoStoreError>

Check if the given user is considered to be tracked.

A user can be marked for tracking using the OlmMachine::update_tracked_users() method.

pub fn get_missing_sessions( &self, users: Vec<String>, ) -> Result<Option<Request>, CryptoStoreError>

Generate one-time key claiming requests for all the users we are missing sessions for.

After the request was sent out and a successful response was received the response body should be passed back to the state machine using the mark_request_as_sent() method.

This method should be called every time before a call to share_room_key() is made.

Arguments

• users - The list of users for which we would like to establish 1:1 Olm sessions for.

pub fn get_room_settings( &self, room_id: String, ) -> Result<Option<RoomSettings>, CryptoStoreError>

Get the stored room settings, such as the encryption algorithm or whether to encrypt only for trusted devices.

These settings can be modified via set_room_algorithm() and set_room_only_allow_trusted_devices() methods.

pub fn set_room_algorithm( &self, room_id: String, algorithm: EventEncryptionAlgorithm, ) -> Result<(), CryptoStoreError>

Set the room algorithm used for encrypting messages to one of the available variants

pub fn set_room_only_allow_trusted_devices( &self, room_id: String, only_allow_trusted_devices: bool, ) -> Result<(), CryptoStoreError>

Set flag whether this room should encrypt messages for untrusted devices, or whether they should be excluded from the conversation.

Note that per-room setting may be overridden by a global set_only_allow_trusted_devices() method.

pub fn get_only_allow_trusted_devices(&self) -> Result<bool, CryptoStoreError>

Check whether there is a global flag to only encrypt messages for trusted devices or for everyone.

Note that if the global flag is false, individual rooms may still be encrypting only for trusted devices, depending on the per-room only_allow_trusted_devices flag.

pub fn set_only_allow_trusted_devices( &self, only_allow_trusted_devices: bool, ) -> Result<(), CryptoStoreError>

Set global flag whether to encrypt messages for untrusted devices, or whether they should be excluded from the conversation.

Note that if enabled, it will override any per-room settings.

pub fn share_room_key( &self, room_id: String, users: Vec<String>, settings: EncryptionSettings, ) -> Result<Vec<Request>, CryptoStoreError>

Share a room key with the given list of users for the given room.

After the request was sent out and a successful response was received the response body should be passed back to the state machine using the mark_request_as_sent() method.

This method should be called every time before a call to encrypt() with the given room_id is made.

Arguments

• room_id - The unique id of the room, note that this doesn’t strictly need to be a Matrix room, it just needs to be an unique identifier for the group that will participate in the conversation.

• users - The list of users which are considered to be members of the room and should receive the room key.

• settings - The settings that should be used for the room key.

pub fn encrypt( &self, room_id: String, event_type: String, content: String, ) -> Result<String, CryptoStoreError>

Encrypt the given event with the given type and content for the given room.

Note: A room key needs to be shared with the group of users that are members in the given room. If this is not done this method will panic.

The usual flow to encrypt an event using this state machine is as follows:

1. Get the one-time key claim request to establish 1:1 Olm sessions for the room members of the room we wish to participate in. This is done using the get_missing_sessions() method. This method call should be locked per call.

2. Share a room key with all the room members using the share_room_key(). This method call should be locked per room.

3. Encrypt the event using this method.

4. Send the encrypted event to the server.

After the room key is shared steps 1 and 2 will become noops, unless there’s some changes in the room membership or in the list of devices a member has.

Arguments

• room_id - The unique id of the room where the event will be sent to.

• even_type - The type of the event.

• content - The serialized content of the event.

pub fn create_encrypted_to_device_request( &self, user_id: String, device_id: String, event_type: String, content: String, ) -> Result<Option<Request>, CryptoStoreError>

Encrypt the given event with the given type and content for the given device. This method is used to send an event to a specific device.

Arguments

• user_id - The ID of the user who owns the target device.
• device_id - The ID of the device to which the message will be sent.
• event_type - The event type.
• content - The serialized content of the event.

Returns

A Result containing the request to be sent out if the encryption was successful. If the device is not found, the result will be Ok(None).

The caller should ensure that there is an olm session (see get_missing_sessions) with the target device before calling this method.

pub fn decrypt_room_event( &self, event: String, room_id: String, handle_verification_events: bool, strict_shields: bool, decryption_settings: DecryptionSettings, ) -> Result<DecryptedEvent, DecryptionError>

Decrypt the given event that was sent in the given room.

Arguments

• event - The serialized encrypted version of the event.

• room_id - The unique id of the room where the event was sent to.

• strict_shields - If true, messages will be decorated with strict warnings (use false to match legacy behaviour where unsafe keys have lower severity warnings and unverified identities are not decorated).

• decryption_settings - The setting for decrypting messages.

pub fn request_room_key( &self, event: String, room_id: String, ) -> Result<KeyRequestPair, DecryptionError>

Request or re-request a room key that was used to encrypt the given event.

Arguments

• event - The undecryptable event that we would wish to request a room key for.

• room_id - The id of the room the event was sent to.

pub fn export_room_keys( &self, passphrase: String, rounds: i32, ) -> Result<String, CryptoStoreError>

Export all of our room keys.

Arguments

• passphrase - The passphrase that should be used to encrypt the key export.

• rounds - The number of rounds that should be used when expanding the passphrase into an key.

pub fn import_room_keys( &self, keys: String, passphrase: String, progress_listener: Box<dyn ProgressListener>, ) -> Result<KeysImportResult, KeyImportError>

Import room keys from the given serialized key export.

Arguments

• keys - The serialized version of the key export.

• passphrase - The passphrase that was used to encrypt the key export.

• progress_listener - A callback that can be used to introspect the progress of the key import.

pub fn import_decrypted_room_keys( &self, keys: String, progress_listener: Box<dyn ProgressListener>, ) -> Result<KeysImportResult, KeyImportError>

Import room keys from the given serialized unencrypted key export.

This method is the same as OlmMachine::import_room_keys but the decryption step is skipped and should be performed by the caller. This should be used if the room keys are coming from the server-side backup, the method will mark all imported room keys as backed up.

Note: This has been deprecated. Use OlmMachine::import_room_keys_from_backup instead.

Arguments

• keys - The serialized version of the unencrypted key export.

• progress_listener - A callback that can be used to introspect the progress of the key import.

pub fn import_room_keys_from_backup( &self, keys: String, backup_version: String, progress_listener: Box<dyn ProgressListener>, ) -> Result<KeysImportResult, KeyImportError>

Import room keys from the given serialized unencrypted key export.

This method is the same as OlmMachine::import_room_keys but the decryption step is skipped and should be performed by the caller. This should be used if the room keys are coming from the server-side backup. The method will mark all imported room keys as backed up.

Arguments

• keys - The serialized version of the unencrypted key export.

• backup_version - The version of the backup that these keys came from.

• progress_listener - A callback that can be used to introspect the progress of the key import.

pub fn discard_room_key(&self, room_id: String) -> Result<(), CryptoStoreError>

Discard the currently active room key for the given room if there is one.

pub fn receive_unencrypted_verification_event( &self, event: String, room_id: String, ) -> Result<(), CryptoStoreError>

Receive an unencrypted verification event.

This method can be used to pass verification events that are happening in unencrypted rooms to the OlmMachine.

Note: This has been deprecated.

pub fn receive_verification_event( &self, event: String, room_id: String, ) -> Result<(), CryptoStoreError>

Receive a verification event.

This method can be used to pass verification events that are happening in rooms to the OlmMachine. The event should be in the decrypted form.

pub fn get_verification_requests( &self, user_id: String, ) -> Vec<Arc<VerificationRequest>>

Get all the verification requests that we share with the given user.

Arguments

• user_id - The ID of the user for which we would like to fetch the verification requests.

pub fn get_verification_request( &self, user_id: String, flow_id: String, ) -> Option<Arc<VerificationRequest>>

Get a verification requests that we share with the given user with the given flow id.

Arguments

• user_id - The ID of the user for which we would like to fetch the verification requests.

• flow_id - The ID that uniquely identifies the verification flow.

pub fn verification_request_content( &self, user_id: String, methods: Vec<String>, ) -> Result<Option<String>, CryptoStoreError>

Get an m.key.verification.request content for the given user.

Arguments

• user_id - The ID of the user which we would like to request to verify.

• methods - The list of verification methods we want to advertise to support.

pub fn request_verification( &self, user_id: String, room_id: String, event_id: String, methods: Vec<String>, ) -> Result<Option<Arc<VerificationRequest>>, CryptoStoreError>

Request a verification flow to begin with the given user in the given room.

Arguments

• user_id - The ID of the user which we would like to request to verify.

• room_id - The ID of the room that represents a DM with the given user.

• event_id - The event ID of the m.key.verification.request event that we sent out to request the verification to begin. The content for this request can be created using the verification_request_content() method.

• methods - The list of verification methods we advertised as supported in the m.key.verification.request event.

pub fn request_verification_with_device( &self, user_id: String, device_id: String, methods: Vec<String>, ) -> Result<Option<RequestVerificationResult>, CryptoStoreError>

Request a verification flow to begin with the given user’s device.

Arguments

• user_id - The ID of the user which we would like to request to verify.

• device_id - The ID of the device that we wish to verify.

• methods - The list of verification methods we advertised as supported in the m.key.verification.request event.

pub fn request_self_verification( &self, methods: Vec<String>, ) -> Result<Option<RequestVerificationResult>, CryptoStoreError>

Request a verification flow to begin with our other devices.

Arguments

methods - The list of verification methods we want to advertise to support.

pub fn get_verification( &self, user_id: String, flow_id: String, ) -> Option<Arc<Verification>>

Get a verification flow object for the given user with the given flow id.

Arguments

• user_id - The ID of the user for which we would like to fetch the verification.

• flow_id - The ID that uniquely identifies the verification flow.

pub fn start_sas_with_device( &self, user_id: String, device_id: String, ) -> Result<Option<StartSasResult>, CryptoStoreError>

Start short auth string verification with a device without going through a verification request first.

Note: This has been largely deprecated and the request_verification_with_device() method should be used instead.

Arguments

• user_id - The ID of the user for which we would like to start the SAS verification.

• device_id - The ID of device we would like to verify.

pub fn bootstrap_cross_signing( &self, ) -> Result<BootstrapCrossSigningResult, CryptoStoreError>

Create a new private cross signing identity and create a request to upload the public part of it to the server.

pub fn export_cross_signing_keys( &self, ) -> Result<Option<CrossSigningKeyExport>, CryptoStoreError>

Export all our private cross signing keys.

The export will contain the seed for the ed25519 keys as a base64 encoded string.

This method returns None if we don’t have any private cross signing keys.

pub fn import_cross_signing_keys( &self, export: CrossSigningKeyExport, ) -> Result<(), SecretImportError>

Import our private cross signing keys.

The export needs to contain the seed for the ed25519 keys as a base64 encoded string.

pub fn query_missing_secrets_from_other_sessions( &self, ) -> Result<bool, CryptoStoreError>

Request missing local secrets from our devices (cross signing private keys, megolm backup). This will ask the sdk to create outgoing request to get the missing secrets.

The requests will be processed as soon as outgoing_requests() is called to process them.

pub fn enable_backup_v1( &self, key: MegolmV1BackupKey, version: String, ) -> Result<(), DecodeError>

Activate the given backup key to be used with the given backup version.

Warning: The caller needs to make sure that the given BackupKey is trusted, otherwise we might be encrypting room keys that a malicious party could decrypt.

The OlmMachine::verify_backup method can be used to so.

pub fn backup_enabled(&self) -> bool

Are we able to encrypt room keys.

This returns true if we have an active BackupKey and backup version registered with the state machine.

pub fn disable_backup(&self) -> Result<(), CryptoStoreError>

Disable and reset our backup state.

This will remove any pending backup request, remove the backup key and reset the backup state of each room key we have.

pub fn backup_room_keys(&self) -> Result<Option<Request>, CryptoStoreError>

Encrypt a batch of room keys and return a request that needs to be sent out to backup the room keys.

pub fn room_key_counts(&self) -> Result<RoomKeyCounts, CryptoStoreError>

Get the number of backed up room keys and the total number of room keys.

pub fn save_recovery_key( &self, key: Option<Arc<BackupRecoveryKey>>, version: Option<String>, ) -> Result<(), CryptoStoreError>

Store the recovery key in the crypto store.

This is useful if the client wants to support gossiping of the backup key.

pub fn get_backup_keys( &self, ) -> Result<Option<Arc<BackupKeys>>, CryptoStoreError>

Get the backup keys we have saved in our crypto store.

pub fn sign( &self, message: String, ) -> Result<HashMap<String, HashMap<String, String>>, CryptoStoreError>

Sign the given message using our device key and if available cross signing master key.

pub fn verify_backup( &self, backup_info: String, ) -> Result<SignatureVerification, CryptoStoreError>

Check if the given backup has been verified by us or by another of our devices that we trust.

The backup_info should be a JSON encoded object with the following format:

{
    "algorithm": "m.megolm_backup.v1.curve25519-aes-sha2",
    "auth_data": {
        "public_key":"XjhWTCjW7l59pbfx9tlCBQolfnIQWARoKOzjTOPSlWM",
        "signatures": {}
    }
}

pub fn dehydrated_devices(&self) -> Arc<DehydratedDevices>

Manage dehydrated devices.

Trait Implementations

impl Drop for OlmMachine

fn drop(&mut self)

Executes the destructor for this type.

impl<UT> LiftRef<UT> for OlmMachine

type LiftType = Arc<OlmMachine>

impl<UT> LowerError<UT> for OlmMachine

fn lower_error(obj: Self) -> RustBuffer

Lower this value for scaffolding function return

impl<UT> LowerReturn<UT> for OlmMachine

type ReturnType = <Arc<OlmMachine> as LowerReturn<UniFfiTag>>::ReturnType

The type that should be returned by scaffolding functions for this type.

fn lower_return(obj: Self) -> Result<Self::ReturnType, RustBuffer>

Lower this value for scaffolding function return

fn handle_failed_lift(arg_name: &str, e: Error) -> Self

If possible, get a serialized error for failed argument lifts

impl<UT> TypeId<UT> for OlmMachine

const TYPE_ID_META: MetadataBuffer = _