-
Notifications
You must be signed in to change notification settings - Fork 252
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
30 additions
and
55 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,71 +1,46 @@ | ||
| A no-network-IO implementation of a state machine that handles E2EE for | ||
| [Matrix] clients. | ||
|
|
||
| # Usage | ||
| 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 E2EE 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::{OlmMachine, OlmError}; | ||
| use ruma::{ | ||
| api::client::sync::sync_events::{v3::ToDevice, 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()); | ||
| // Push changes that the server sent to us in a sync response. | ||
| let decrypted_to_device = machine.receive_sync_changes( | ||
| vec![], | ||
| &changed_devices, | ||
| &one_time_key_counts, | ||
| unused_fallback_keys.as_deref(), | ||
| ).await?; | ||
| // Pull requests that we need to send out. | ||
| let outgoing_requests = machine.outgoing_requests().await?; | ||
| However, if you're looking to add end-to-end encryption to an existing Matrix | ||
| client or library, read on. | ||
|
|
||
| // Send the requests here out 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/ | ||
|
|
||
| # Room key sharing algorithm | ||
| # Crate Feature Flags | ||
|
|
||
| The following crate feature flags are available: | ||
|
|
||
| The decision tree below visualizes the way this crate decides whether a room | ||
| key will be shared with a requester upon a key request. | ||
| | 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. | | ||
|
|
||
|  | ||
| # 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`): | ||
|
|
||
| # Crate Feature Flags | ||
| ```rust | ||
| tracing_subscriber::fmt::init(); | ||
| ``` | ||
|
|
||
| The following crate feature flags are available: | ||
| 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. | ||
|
|
||
| * `qrcode`: Enbles QRcode generation and reading code | ||
| 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]. | ||
|
|
||
| * `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. | ||
| [examples]: https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk/examples | ||
| [tracing-subscriber documentation]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/ |