ruma_client_api/
backup.rs

1//! Endpoints for server-side key backups.
2
3pub mod add_backup_keys;
4pub mod add_backup_keys_for_room;
5pub mod add_backup_keys_for_session;
6pub mod create_backup_version;
7pub mod delete_backup_keys;
8pub mod delete_backup_keys_for_room;
9pub mod delete_backup_keys_for_session;
10pub mod delete_backup_version;
11pub mod get_backup_info;
12pub mod get_backup_keys;
13pub mod get_backup_keys_for_room;
14pub mod get_backup_keys_for_session;
15pub mod get_latest_backup_info;
16pub mod update_backup_version;
17
18use std::collections::BTreeMap;
19
20use js_int::UInt;
21use ruma_common::{
22    serde::{Base64, Raw},
23    CrossSigningOrDeviceSignatures,
24};
25use serde::{Deserialize, Serialize};
26
27/// A wrapper around a mapping of session IDs to key data.
28#[derive(Clone, Debug, Serialize, Deserialize)]
29#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
30pub struct RoomKeyBackup {
31    /// A map of session IDs to key data.
32    pub sessions: BTreeMap<String, Raw<KeyBackupData>>,
33}
34
35impl RoomKeyBackup {
36    /// Creates a new `RoomKeyBackup` with the given sessions.
37    pub fn new(sessions: BTreeMap<String, Raw<KeyBackupData>>) -> Self {
38        Self { sessions }
39    }
40}
41
42/// The algorithm used for storing backups.
43#[derive(Clone, Debug, Serialize, Deserialize)]
44#[serde(tag = "algorithm", content = "auth_data")]
45#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
46pub enum BackupAlgorithm {
47    /// `m.megolm_backup.v1.curve25519-aes-sha2` backup algorithm.
48    #[serde(rename = "m.megolm_backup.v1.curve25519-aes-sha2")]
49    MegolmBackupV1Curve25519AesSha2 {
50        /// The curve25519 public key used to encrypt the backups, encoded in unpadded base64.
51        public_key: Base64,
52
53        /// Signatures of the auth_data as Signed JSON.
54        signatures: CrossSigningOrDeviceSignatures,
55    },
56}
57
58/// Information about the backup key.
59///
60/// To create an instance of this type, first create a [`KeyBackupDataInit`] and convert it via
61/// `KeyBackupData::from` / `.into()`.
62#[derive(Clone, Debug, Serialize, Deserialize)]
63#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
64pub struct KeyBackupData {
65    /// The index of the first message in the session that the key can decrypt.
66    pub first_message_index: UInt,
67
68    /// The number of times this key has been forwarded via key-sharing between devices.
69    pub forwarded_count: UInt,
70
71    /// Whether the device backing up the key verified the device that the key is from.
72    pub is_verified: bool,
73
74    /// Encrypted data about the session.
75    pub session_data: EncryptedSessionData,
76}
77
78/// Information about the backup key.
79///
80/// This struct will not be updated even if additional fields are added to [`KeyBackupData`] in a
81/// new (non-breaking) release of the Matrix specification.
82#[derive(Debug)]
83#[allow(clippy::exhaustive_structs)]
84pub struct KeyBackupDataInit {
85    /// The index of the first message in the session that the key can decrypt.
86    pub first_message_index: UInt,
87
88    /// The number of times this key has been forwarded via key-sharing between devices.
89    pub forwarded_count: UInt,
90
91    /// Whether the device backing up the key verified the device that the key is from.
92    pub is_verified: bool,
93
94    /// Encrypted data about the session.
95    pub session_data: EncryptedSessionData,
96}
97
98impl From<KeyBackupDataInit> for KeyBackupData {
99    fn from(init: KeyBackupDataInit) -> Self {
100        let KeyBackupDataInit { first_message_index, forwarded_count, is_verified, session_data } =
101            init;
102        Self { first_message_index, forwarded_count, is_verified, session_data }
103    }
104}
105
106/// The encrypted algorithm-dependent data for backups.
107///
108/// To create an instance of this type, first create an [`EncryptedSessionDataInit`] and convert it
109/// via `EncryptedSessionData::from` / `.into()`.
110#[derive(Clone, Debug, Serialize, Deserialize)]
111#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
112pub struct EncryptedSessionData {
113    /// Unpadded base64-encoded public half of the ephemeral key.
114    pub ephemeral: Base64,
115
116    /// Ciphertext, encrypted using AES-CBC-256 with PKCS#7 padding, encoded in base64.
117    pub ciphertext: Base64,
118
119    /// First 8 bytes of MAC key, encoded in base64.
120    pub mac: Base64,
121}
122
123/// The encrypted algorithm-dependent data for backups.
124///
125/// This struct will not be updated even if additional fields are added to [`EncryptedSessionData`]
126/// in a new (non-breaking) release of the Matrix specification.
127#[derive(Debug)]
128#[allow(clippy::exhaustive_structs)]
129pub struct EncryptedSessionDataInit {
130    /// Unpadded base64-encoded public half of the ephemeral key.
131    pub ephemeral: Base64,
132
133    /// Ciphertext, encrypted using AES-CBC-256 with PKCS#7 padding, encoded in base64.
134    pub ciphertext: Base64,
135
136    /// First 8 bytes of MAC key, encoded in base64.
137    pub mac: Base64,
138}
139
140impl From<EncryptedSessionDataInit> for EncryptedSessionData {
141    fn from(init: EncryptedSessionDataInit) -> Self {
142        let EncryptedSessionDataInit { ephemeral, ciphertext, mac } = init;
143        Self { ephemeral, ciphertext, mac }
144    }
145}
ruma_client_api/backup.rs

ruma_client_api/
backup.rs
