fixup! WIP tutorial

Author: poljar

crates/matrix-sdk-crypto/src/lib.rs

@@ -112,8 +112,21 @@ pub mod vodozemac {
 /// A step by step guide that explains how to include [end-to-end-encryption]
 /// support in a [Matrix] client library.
 ///
-/// If you're not familiar with Matrix or how clients communicate with a Matrix
-/// homeserver it's advised to get yourself familiar with the [client-server spec](https://matrix.org/docs/spec/client_server/).
+/// This crate implements a [sans-network-io](https://sans-io.readthedocs.io/)
+/// state machine that allows you to add [end-to-end-encryption] support to a
+/// [Matrix] client library.
+///
+/// This guide aims to provide a comprehensive understanding of end-to-end
+/// encryption in Matrix without any prior knowledge requirements. However, it
+/// is recommended that the reader has a basic understanding of Matrix and its
+/// [client-server specification] for a more informed and efficient learning
+/// experience.
+///
+/// The [introductory](#introduction) section provides a simplified explanation
+/// of end-to-end encryption and its implementation in Matrix for those who may
+/// not have prior knowledge. If you already have a solid understanding of
+/// end-to-end encryption, including the [Olm] and [Megolm] protocols, you may
+/// choose to skip directly to the [Getting Started](#getting-started) section.
 ///
 /// # Table of contents
 /// 1. [Introduction](#introduction)
@@ -124,9 +137,20 @@ pub mod vodozemac {
 ///
 /// # Introduction
 ///
-/// This crate implements a [sans-network-io](https://sans-io.readthedocs.io/) state machine that
-/// allows you to add [end-to-end-encryption] support to a [Matrix] client
-/// library.
+/// Welcome to the first part of this guide, where we will introduce the
+/// fundamental concepts of end-to-end encryption and its implementation in
+/// Matrix.
+///
+/// This section will provide a clear and concise overview of what
+/// end-to-end encryption is and why it is important for secure communication.
+/// You will also learn about how Matrix uses end-to-end encryption to protect
+/// the privacy and security of its users' communications. Whether you are new
+/// to the topic or simply want to improve your understanding, this section will
+/// serve as a solid foundation for the rest of the guide.
+///
+/// Let's dive in!
+///
+/// ## Notation
 ///
 /// ## End-to-end-encryption
 ///
@@ -143,7 +167,7 @@ pub mod vodozemac {
 /// flowchart LR
 ///     alice[Alice]
 ///     bob[Bob]
-///     subgraph Server
+///     subgraph Homeserver
 ///         direction LR
 ///         outbox[Alice outbox]
 ///         inbox[Bob inbox]
@@ -161,7 +185,7 @@ pub mod vodozemac {
 /// flowchart LR
 ///     alice[Alice]
 ///     bob[Bob]
-///     subgraph Server
+///     subgraph Homeserver
 ///         direction LR
 ///         outbox[Alice outbox]
 ///         inbox[Bob inbox]
@@ -174,6 +198,10 @@ pub mod vodozemac {
 ///
 /// Note that the path from the outbox to the inbox is now encrypted as well.
 ///
+/// Alice and Bob have created a secure communication channel
+/// through which they can exchange messages confidentially, without the risk of
+/// the server accessing the contents of their messages.
+///
 /// ## Publishing cryptographic identities of devices
 ///
 /// If Alice and Bob want to establish a secure channel over which they can
@@ -192,13 +220,10 @@ pub mod vodozemac {
 /// the directory to find the public key of the user they wish to communicate
 /// with, and download it to their own device.
 ///
-/// Once a user has the other user's public key, they can use it to establish an
-/// end-to-end encrypted channel using a [key-agreement] protocol.
-///
 /// ```mermaid
 /// flowchart LR
 ///     alice[Alice]
-///     subgraph server[Server]
+///     subgraph homeserver[Homeserver]
 ///         direction LR
 ///         directory[(Public key directory)]
 ///     end
@@ -208,6 +233,45 @@ pub mod vodozemac {
 ///     directory -- download keys --> bob
 /// ```
 ///
+/// Once a user has the other user's public key, they can use it to establish an
+/// end-to-end encrypted channel using a [key-agreement] protocol.
+///
+/// ## Using the Triple Diffie-Hellman key-agreement protocol
+///
+/// In X3DH, each user generates a long-term identity key pair and a set of
+/// one-time prekeys. When two users want to establish a shared secret key, they
+/// exchange their public identity keys and one of their prekeys. These public
+/// keys are then used in a [Diffie-Hellman] key exchange to compute a shared
+/// secret key.
+///
+/// The use of one-time prekeys ensures that the shared secret key is different
+/// for each session, even if the same identity keys are used.
+///
+/// ```mermaid
+/// flowchart LR
+/// subgraph alice_keys[Alice Keys]
+///     direction TB
+///     alice_key[Alice's identity key]
+///     alice_base_key[Alice's one-time key]
+/// end
+///
+/// subgraph bob_keys[Bob Keys]
+///     direction TB
+///     bob_key[Bob's identity key]
+///     bob_one_time[Bob's one-time key]
+/// end
+///
+/// alice_key <--> bob_one_time
+/// alice_base_key <--> bob_one_time
+/// alice_base_key <--> bob_key
+/// ```
+///
+/// Similar to [X3DH] (Extended Triple Diffie-Hellman) key agreement protocol
+///
+/// ## Speeding up encryption for large groups
+///
+/// TODO Explain how megolm fits into this
+///
 /// # Getting started
 ///
 /// In the [Matrix] world the server is called a [homeserver]
@@ -261,13 +325,27 @@ pub mod vodozemac {
 ///
 /// # Decryption
 ///
+/// In the world of encrypted communication, it is common to start with the
+/// encryption step when implementing a protocol. However, in the case of adding
+/// end-to-end encryption support to a Matrix client library, a simpler approach
+/// is to first focus on the decryption process. This is because there are
+/// already Matrix clients in existence that support encryption, which means
+/// that our client library can simply receive encrypted messages and then
+/// decrypt them.
+///
+/// In this section, we will guide you through the minimal steps
+/// necessary to get the decryption process up and running using the
+/// matrix-sdk-crypto Rust crate. By the end of this section you should have a
+/// Matrix client that is able to decrypt room events that other clients have
+/// sent.
+///
 /// To enable decryption the following three steps are needed:
 ///
 /// 1. [The cryptographic identity of your device needs to be published to the
-/// homeserver](#uploading-identity-and-one-time-key)
+/// homeserver](#uploading-identity-and-one-time-keys).
 /// 2. [Decryption keys coming in from other devices need to be processed and
-/// stored](#receiving-room-keys-and-related-changes)
-/// 3. [Messages need to be decrypted](#decrypting-room-events)
+/// stored](#receiving-room-keys-and-related-changes).
+/// 3. [Individual messages need to be decrypted](#decrypting-room-events).
 ///
 /// The simplified flowchart
 /// ```mermaid
@@ -285,7 +363,16 @@ pub mod vodozemac {
 ///
 /// ## Uploading identity and one-time keys.
 ///
-/// TODO
+/// The first step is to announce the support for it to other users in the
+/// Matrix network. This involves publishing your long-term device keys and a
+/// set of one-time prekeys to the homeserver. This information is used by other
+/// devices to encrypt messages specifically for your device.
+///
+/// To achieve this, you will need to extract any requests that need to be sent
+/// to the homeserver from the [`OlmMachine`] and send them to the homeserver.
+/// The following snipped showcases how to achieve this using the
+/// [`OlmMachine::outgoing_requests()`] method:
+///
 /// ```no_run
 /// # use std::collections::BTreeMap;
 /// # use ruma::api::client::keys::upload_keys::v3::Response;
@@ -303,6 +390,7 @@ pub mod vodozemac {
 ///
 /// // Send each request to the server and push the response into the state machine.
 /// for request in outgoing_requests {
+///     // You can safely send out these requests out in parallel.
 ///     let request_id = request.request_id();
 ///     let response = send_request(request).await?;
 ///     machine.mark_request_as_sent(&request_id, &response).await?;
@@ -313,8 +401,6 @@ pub mod vodozemac {
 ///
 /// ## Receiving room keys and related changes
 ///
-/// TODO
-///
 /// ```no_run
 /// # use std::collections::BTreeMap;
 /// # use anyhow::Result;
@@ -341,6 +427,15 @@ pub mod vodozemac {
 ///
 /// ## Decrypting room events
 ///
+/// The final step in the decryption process is to decrypt the room events that
+/// are received from the server. To do this, the encrypted events must be
+/// passed to the [`OlmMachine`], which will use the keys that were previously
+/// exchanged between devices to decrypt the events. The decrypted events can
+/// then be processed and displayed to the user in the Matrix client.
+///
+/// Room events can be decrypted using the [`OlmMachine::decrypt_room_event()`]
+/// method.
+///
 /// ```no_run
 /// # use std::collections::BTreeMap;
 /// # use anyhow::Result;
@@ -465,6 +560,21 @@ pub mod vodozemac {
 /// ```
 ///
 /// ## Encrypting room events
+///
+/// ```no_run
+/// # use anyhow::Result;
+/// # use matrix_sdk_crypto::OlmMachine;
+/// # #[tokio::main]
+/// # async fn main() -> Result<()> {
+/// # let room_id = unimplemented!();
+/// # let event = unimplemented!();
+/// # let machine: OlmMachine = unimplemented!();
+/// // Decrypt each room event you'd like to display to the user using this method.
+/// let decrypted = machine.decrypt_room_event(event, room_id)?;
+/// # Ok(())
+/// # }
+/// ```
+
 ///
 /// TODO
 ///
@@ -474,10 +584,15 @@ pub mod vodozemac {
 /// TODO
 ///
 /// [Matrix]: https://matrix.org/
+/// [Olm]: https://gitlab.matrix.org/matrix-org/olm/-/blob/master/docs/olm.md
+/// [Diffie-Hellman]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange
+/// [Megolm]: https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md
 /// [end-to-end-encryption]: https://en.wikipedia.org/wiki/End-to-end_encryption
 /// [homeserver]: https://spec.matrix.org/unstable/#architecture
 /// [key-agreement]: https://en.wikipedia.org/wiki/Key-agreement_protocol
+/// [client-server specification]: https://matrix.org/docs/spec/client_server/
+/// [forward secrecy]: https://en.wikipedia.org/wiki/Forward_secrecy
+/// [replay attacks]: https://en.wikipedia.org/wiki/Replay_attack
 ///
 /// [X3DH]: https://signal.org/docs/specifications/x3dh/
-/// [diffie-hellman]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange
 pub mod tutorial {}