A no-network-IO implementation of a state machine that handles end-to-end encryption for Matrix clients.

If you're just trying to write a Matrix client or bot in Rust, you're probably looking for matrix-sdk instead.

However, if you're looking to add end-to-end encryption to an existing Matrix client or library, read on.

The state machine works in a push/pull manner:

you push state changes and events retrieved from a Matrix homeserver /sync response into the state machine
you pull requests that you'll need to send back to the homeserver out of the state machine

use std::collections::BTreeMap;

use matrix_sdk_crypto::{
    DecryptionSettings, EncryptionSyncChanges, OlmError, OlmMachine, TrustRequirement,
};
use ruma::{api::client::sync::sync_events::DeviceLists, device_id, user_id};

#[tokio::main]
async fn main() -> Result<(), OlmError> {
    let alice = user_id!("@alice:example.org");
    let machine = OlmMachine::new(&alice, device_id!("DEVICEID")).await;

    let changed_devices = DeviceLists::default();
    let one_time_key_counts = BTreeMap::default();
    let unused_fallback_keys = Some(Vec::new());
    let next_batch_token = "T0K3N".to_owned();

    let decryption_settings =
        DecryptionSettings { sender_device_trust_requirement: TrustRequirement::Untrusted };

    // Push changes that the server sent to us in a sync response.
    let decrypted_to_device = machine
        .receive_sync_changes(
            EncryptionSyncChanges {
                to_device_events: vec![],
                changed_devices: &changed_devices,
                one_time_keys_counts: &one_time_key_counts,
                unused_fallback_keys: unused_fallback_keys.as_deref(),
                next_batch_token: Some(next_batch_token),
            },
            &decryption_settings,
        )
        .await?;

    // Pull requests that we need to send out.
    let outgoing_requests = machine.outgoing_requests().await?;

    // Send the requests out here and call machine.mark_request_as_sent().

    Ok(())
}

It is recommended to use the [tutorial] to understand how end-to-end encryption works in Matrix and how to add end-to-end encryption support in your Matrix client library.

Crate Feature Flags

The following crate feature flags are available:

Feature	Default	Description
`qrcode`	No	Enables QR code based interactive verification
`js`	No	Enables JavaScript API usage for things like the current system time on WASM (does nothing on other targets)
`testing`	No	Provides facilities and functions for tests, in particular for integration testing store implementations. ATTENTION: do not ever use outside of tests, we do not provide any stability warantees on these, these are merely helpers. If you find you need any function provided here outside of tests, please open a Github Issue and inform us about your use case for us to consider.

testing: Provides facilities and functions for tests, in particular for integration testing store implementations. ATTENTION: do not ever use outside of tests, we do not provide any stability warantees on these, these are merely helpers. If you find you need any function provided here outside of tests, please open a Github Issue and inform us about your use case for us to consider.
_disable-minimum-rotation-period-ms: Do not use except for testing. Disables the floor on the rotation period of room keys.

Enabling logging

Users of the matrix-sdk-crypto crate can enable log output by depending on the tracing-subscriber crate and including the following line in their application (e.g. at the start of main):

tracing_subscriber::fmt::init();

The log output is controlled via the RUST_LOG environment variable by setting it to one of the error, warn, info, debug or trace levels. The output is printed to stdout.

The RUST_LOG variable also supports a more advanced syntax for filtering log output more precisely, for instance with crate-level granularity. For more information on this, check out the tracing-subscriber documentation.