From 1773625b8b18ea2d4b0dd510d369f972711dd0a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Fri, 28 Jul 2023 16:38:30 +0200 Subject: [PATCH] chore: Rework the crypto crate README --- crates/matrix-sdk-crypto/README.md | 48 +++++++++++++++++++----------- 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/crates/matrix-sdk-crypto/README.md b/crates/matrix-sdk-crypto/README.md index 8f92c787bc8..154c9f0fed7 100644 --- a/crates/matrix-sdk-crypto/README.md +++ b/crates/matrix-sdk-crypto/README.md @@ -1,13 +1,11 @@ -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. +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: @@ -52,28 +50,42 @@ async fn main() -> Result<(), OlmError> { 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 forwarding algorithm +# Crate Feature Flags -The decision tree below visualizes the way this crate decides whether a message -key ("room key") will be [forwarded][forwarded_room_key] to a requester upon a -key request, provided the `automatic-room-key-forwarding` feature is enabled. -Key forwarding is sometimes also referred to as key *gossiping*. +The following crate feature flags are available: -[forwarded_room_key]: +| 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. | -![](https://raw.githubusercontent.com/matrix-org/matrix-rust-sdk/main/contrib/key-sharing-algorithm/model.png) +* `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 -# Crate Feature Flags +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`): -The following crate feature flags are available: +```no_compile +tracing_subscriber::fmt::init(); +``` -* `qrcode`: Enbles QRcode generation and reading code +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. -* `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. +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]. -* `_disable-minimum-rotation-period-ms`: Do not use except for testing. Disables the floor on the rotation period of room keys. +[tracing-subscriber documentation]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/