matrix-rust-sdk

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

```rust,no_run

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.

[Matrix]: https://matrix.org/

[matrix-sdk]: https://github.com/matrix-org/matrix-rust-sdk/

# 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`):

```no_compile

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].

[tracing-subscriber documentation]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/