fixup! crypto: support for building key bundles

improve docuemntation and rename struct

Author: richvdh

crates/matrix-sdk-crypto/src/olm/group_sessions/inbound.rs

@@ -40,6 +40,8 @@ use super::{
     BackedUpRoomKey, ExportedRoomKey, OutboundGroupSession, SenderData, SenderDataType,
     SessionCreationError, SessionKey,
 };
+#[cfg(doc)]
+use crate::types::{events::room_key::RoomKeyContent, room_history::HistoricRoomKey};
 use crate::{
     error::{EventError, MegolmResult},
     types::{
@@ -107,6 +109,60 @@ pub(crate) struct SessionCreatorInfo {
 /// access of the vodozemac type.
 ///
 /// [vodozemac]: https://matrix-org.github.io/vodozemac/vodozemac/index.html
+///
+/// ## Structures representing serialised versions of an `InboundGroupSession`
+///
+/// This crate contains a number of structures which are used for exporting or
+/// sharing `InboundGroupSession` between users or devices, in different
+/// circumstances. The following is an attempt to catalogue them.
+///
+/// 1. First, we have the contents of an `m.room_key` to-device message (i.e., a
+///    [`RoomKeyContent`]. `RoomKeyContent` is unusual in that it can be created
+///    only by the original creator of the session (i.e., someone in possession
+///    of the corresponding [`OutboundGroupSession`]), since the embedded
+///    `session_key` is self-signed.
+///
+///    `RoomKeyContent` does **not** include any information about the creator
+///    of the session (such as the creator's public device keys), since it is
+///    assumed that the original creator of the session is the same as the
+///    device sending the to-device message; it is therefore implied by the Olm
+///    channel used to send the message.
+///
+///    All the other structs in this list include a `sender_key` field which
+///    contains the Curve25519 key belonging to the device which created the
+///    Megolm session (at least, according to the creator of the struct); they
+///    also include the Ed25519 key, though the exact serialisation mechanism
+///    varies.
+///
+/// 2. Next, we have the contents of an `m.forwarded_room_key` message (i.e. a
+///    [`ForwardedRoomKeyContent`]). This modifies `RoomKeyContent` by (a) using
+///    a `session_key` which is not self-signed, (b) adding a `sender_key` field
+///    as mentioned above, (c) adding a `sender_claimed_ed25519_key` field
+///    containing the original sender's Ed25519 key; (d) adding a
+///    `forwarding_curve25519_key_chain` field, which is intended to be used
+///    when the key is re-forwarded, but in practice is of little use.
+///
+/// 3. [`ExportedRoomKey`] is very similar to `ForwardedRoomKeyContent`. The
+///    only difference is that the original sender's Ed25519 key is embedded in
+///    a `sender_claimed_keys` map rather than a top-level
+///    `sender_claimed_ed25519_key` field.
+///
+/// 4. [`BackedUpRoomKey`] is essentially the same as `ExportedRoomKey`, but
+///    lacks explicit `room_id` and `session_id` (since those are implied by
+///    other parts of the key backup structure).
+///
+/// 5. [`HistoricRoomKey`] is also similar to `ExportedRoomKey`, but omits
+///    `forwarding_curve25519_key_chain` (since it has not been useful in
+///    practice) and `shared_history` (because any key being shared via that
+///    mechanism is inherently suitable for sharing with other users).
+///
+/// | Type     | Self-signed room key | `room_id`, `session_id` | `sender_key` | Sender's Ed25519 key | `forwarding _curve25519 _key _chain` | `shared _history` |
+/// |----------|----------------------|-------------------------|--------------|----------------------|------------------------------------|------------------|
+/// | [`RoomKeyContent`]          | ✅ | ✅                       | ❌            | ❌                    | ❌                                  | ✅                |
+/// | [`ForwardedRoomKeyContent`] | ❌ | ✅                       | ✅            | `sender_claimed_ed25519_key` | ✅                          | ✅                |
+/// | [`ExportedRoomKey`]         | ❌ | ✅                       | ✅            | `sender_claimed_keys` | ✅                                 | ✅                |
+/// | [`BackedUpRoomKey`]         | ❌ | ❌                       | ✅            | `sender_claimed_keys` | ✅                                 | ✅                |
+/// | [`HistoricRoomKey`]         | ❌ | ✅                       | ✅            | `sender_claimed_keys` | ❌                                 | ❌                |
 #[derive(Clone)]
 pub struct InboundGroupSession {
     inner: Arc<Mutex<InnerSession>>,

crates/matrix-sdk-crypto/src/olm/group_sessions/mod.rs

@@ -64,9 +64,11 @@ pub enum SessionExportError {
     MissingEd25519Key,
 }
 
-/// An exported version of an `InboundGroupSession`
+/// An exported version of an [`InboundGroupSession`].
 ///
 /// This can be used to share the `InboundGroupSession` in an exported file.
+///
+/// See <https://spec.matrix.org/v1.13/client-server-api/#key-export-format>.
 #[derive(Deserialize, Serialize)]
 #[allow(missing_debug_implementations)]
 pub struct ExportedRoomKey {
@@ -144,7 +146,9 @@ impl ExportedRoomKey {
 /// This can be used to back up the [`InboundGroupSession`] to the server using
 /// [server-side key backups].
 ///
-/// [server-side key backups]: https://spec.matrix.org/unstable/client-server-api/#server-side-key-backups
+/// See <https://spec.matrix.org/v1.13/client-server-api/#definition-backedupsessiondata>.
+///
+/// [server-side key backups]: https://spec.matrix.org/v1.13/client-server-api/#server-side-key-backups
 #[derive(Deserialize, Serialize)]
 #[allow(missing_debug_implementations)]
 pub struct BackedUpRoomKey {

crates/matrix-sdk-crypto/src/types/events/forwarded_room_key.rs

@@ -22,6 +22,8 @@ use serde_json::Value;
 use vodozemac::{megolm::ExportedSessionKey, Curve25519PublicKey, Ed25519PublicKey};
 
 use super::{EventType, ToDeviceEvent};
+#[cfg(doc)]
+use crate::olm::InboundGroupSession;
 use crate::types::{
     deserialize_curve_key, deserialize_curve_key_vec, deserialize_ed25519_key, serialize_curve_key,
     serialize_curve_key_vec, serialize_ed25519_key, EventEncryptionAlgorithm, SigningKeys,
@@ -39,11 +41,15 @@ impl ForwardedRoomKeyEvent {
 
 /// The `m.forwarded_room_key` event content.
 ///
-/// This is an enum over the different room key algorithms we support.
+/// This is an enum over the different room key algorithms we support. The
+/// currently-supported implementations are used to share
+/// [`InboundGroupSession`]s.
 ///
 /// This event type is used to forward keys for end-to-end encryption.
-/// Typically it is encrypted as an m.room.encrypted event, then sent as a
+/// Typically, it is encrypted as an m.room.encrypted event, then sent as a
 /// to-device event.
+///
+/// See <https://spec.matrix.org/v1.13/client-server-api/#mforwarded_room_key>.
 #[derive(Debug, Deserialize)]
 #[serde(try_from = "RoomKeyHelper")]
 pub enum ForwardedRoomKeyContent {

crates/matrix-sdk-crypto/src/types/events/room_key.rs

@@ -22,6 +22,8 @@ use serde_json::{value::to_raw_value, Value};
 use vodozemac::megolm::SessionKey;
 
 use super::{EventType, ToDeviceEvent};
+#[cfg(doc)]
+use crate::olm::InboundGroupSession;
 use crate::types::EventEncryptionAlgorithm;
 
 /// The `m.room_key` to-device event.
@@ -40,11 +42,15 @@ impl EventType for RoomKeyContent {
 
 /// The `m.room_key` event content.
 ///
-/// This is an enum over the different room key algorithms we support.
+/// This is an enum over the different room key algorithms we support.  The
+/// currently-supported implementations are used to share
+/// [`InboundGroupSession`]s.
 ///
 /// This event type is used to exchange keys for end-to-end encryption.
-/// Typically it is encrypted as an m.room.encrypted event, then sent as a
+/// Typically, it is encrypted as an m.room.encrypted event, then sent as a
 /// to-device event.
+///
+/// See <https://spec.matrix.org/v1.13/client-server-api/#mroom_key>.
 #[derive(Debug, Deserialize)]
 #[serde(try_from = "RoomKeyHelper")]
 pub enum RoomKeyContent {

crates/matrix-sdk-crypto/src/types/room_history.rs

@@ -24,36 +24,45 @@ use ruma::{DeviceKeyAlgorithm, OwnedRoomId};
 use serde::{Deserialize, Serialize};
 use vodozemac::{megolm::ExportedSessionKey, Curve25519PublicKey};
 
-#[cfg(doc)]
-use crate::olm::InboundGroupSession;
 use crate::{
     olm::ExportedRoomKey,
     types::{
         deserialize_curve_key, events::room_key_withheld::RoomKeyWithheldContent,
         serialize_curve_key, EventEncryptionAlgorithm, SigningKeys,
     },
 };
+#[cfg(doc)]
+use crate::{olm::InboundGroupSession, types::events::room_key::RoomKeyContent};
 
-/// A bundle of room keys, for sharing encrypted room history.
+/// A bundle of historic room keys, for sharing encrypted room history, per
+/// [MSC4268].
+///
+/// [MSC4268]: https://github.com/matrix-org/matrix-spec-proposals/pull/4268
 #[derive(Deserialize, Serialize, Debug, Default)]
 pub struct RoomKeyBundle {
     /// Keys that we are sharing with the recipient.
-    pub room_keys: Vec<SharedRoomKey>,
+    pub room_keys: Vec<HistoricRoomKey>,
 
     /// Keys that we are *not* sharing with the recipient.
     pub withheld: Vec<RoomKeyWithheldContent>,
 }
 
-/// An [`InboundGroupSession`] for sharing as part of the key bundle.
+/// An [`InboundGroupSession`] for sharing as part of a [`RoomKeyBundle`].
+///
+/// Note: unlike a room key received via an `m.room_key` message (i.e., a
+/// [`RoomKeyContent`]), we have no direct proof that the original sender
+/// actually created this session; rather, we have to take the word of
+/// whoever sent us this key bundle.
 #[derive(Deserialize, Serialize)]
-pub struct SharedRoomKey {
+pub struct HistoricRoomKey {
     /// The encryption algorithm that the session uses.
     pub algorithm: EventEncryptionAlgorithm,
 
     /// The room where the session is used.
     pub room_id: OwnedRoomId,
 
-    /// The Curve25519 key of the device which initiated the session originally.
+    /// The Curve25519 key of the device which initiated the session originally,
+    /// according to the device that sent us this key.
     #[serde(deserialize_with = "deserialize_curve_key", serialize_with = "serialize_curve_key")]
     pub sender_key: Curve25519PublicKey,
 
@@ -63,12 +72,13 @@ pub struct SharedRoomKey {
     /// The key for the session.
     pub session_key: ExportedSessionKey,
 
-    /// The Ed25519 key of the device which initiated the session originally.
+    /// The Ed25519 key of the device which initiated the session originally,
+    /// according to the device that sent us this key.
     #[serde(default)]
     pub sender_claimed_keys: SigningKeys<DeviceKeyAlgorithm>,
 }
 
-impl Debug for SharedRoomKey {
+impl Debug for HistoricRoomKey {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("SharedRoomKey")
             .field("algorithm", &self.algorithm)
@@ -80,7 +90,7 @@ impl Debug for SharedRoomKey {
     }
 }
 
-impl From<ExportedRoomKey> for SharedRoomKey {
+impl From<ExportedRoomKey> for HistoricRoomKey {
     fn from(exported_room_key: ExportedRoomKey) -> Self {
         let ExportedRoomKey {
             algorithm,
@@ -92,7 +102,7 @@ impl From<ExportedRoomKey> for SharedRoomKey {
             shared_history: _,
             forwarding_curve25519_key_chain: _,
         } = exported_room_key;
-        SharedRoomKey {
+        HistoricRoomKey {
             algorithm,
             room_id,
             sender_key,