matrix_sdk/encryption/secret_storage/secret_store.rs
1// Copyright 2023 The Matrix.org Foundation C.I.C.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use std::fmt;
16
17use matrix_sdk_base::crypto::{secret_storage::SecretStorageKey, CrossSigningKeyExport};
18use ruma::{
19 events::{
20 secret::request::SecretName, secret_storage::secret::SecretEventContent,
21 GlobalAccountDataEventType,
22 },
23 serde::Raw,
24};
25use serde_json::value::to_raw_value;
26use tracing::{
27 error,
28 field::{debug, display},
29 info, instrument, warn, Span,
30};
31use zeroize::Zeroize;
32
33use super::{DecryptionError, Result};
34use crate::Client;
35
36#[cfg_attr(doc, aquamarine::aquamarine)]
37/// Secure key/value storage for Matrix users.
38///
39/// The `SecretStore` struct encapsulates the secret storage mechanism for
40/// Matrix users, as it is specified in the [Matrix specification].
41///
42/// This specialized storage is tied to the user's Matrix account and serves as
43/// an encrypted key/value store, backed by [account data] residing on the
44/// homeserver. Any secrets uploaded to the homeserver using the
45/// [`SecretStore::put_secret()`] method are automatically encrypted by the
46/// [`SecretStore`].
47///
48/// [`SecretStore`] enables you to safely manage and access sensitive
49/// information while ensuring that it remains protected from unauthorized
50/// access. It plays a crucial role in maintaining the privacy and security of a
51/// Matrix user's data.
52///
53/// **Data Flow Overview:**
54/// ```mermaid
55/// flowchart LR
56/// subgraph Client
57/// SecretStore
58/// end
59/// subgraph Homeserver
60/// data[Account Data]
61/// end
62/// SecretStore <== Encrypted ==> data
63/// ```
64///
65/// **Note**: It's important to emphasize that the `SecretStore` should not be
66/// used for storing large volumes of data due to its nature as a key/value
67/// store for sensitive information.
68///
69/// # Examples
70///
71/// ```no_run
72/// # use matrix_sdk::Client;
73/// # use url::Url;
74/// # async {
75/// # let homeserver = Url::parse("http://example.com")?;
76/// # let client = Client::new(homeserver).await?;
77/// use ruma::events::secret::request::SecretName;
78///
79/// let secret_store = client
80/// .encryption()
81/// .secret_storage()
82/// .open_secret_store("It's a secret to everybody")
83/// .await?;
84///
85/// let my_secret = "Top secret secret";
86/// let my_secret_name = SecretName::from("m.treasure");
87///
88/// secret_store.put_secret(my_secret_name, my_secret);
89///
90/// # anyhow::Ok(()) };
91/// ```
92///
93/// [Matrix specification]: https://spec.matrix.org/v1.8/client-server-api/#secret-storage
94/// [account data]: https://spec.matrix.org/v1.8/client-server-api/#client-config
95pub struct SecretStore {
96 pub(super) client: Client,
97 pub(super) key: SecretStorageKey,
98}
99
100impl SecretStore {
101 /// Export the [`SecretStorageKey`] of this [`SecretStore`] as a
102 /// base58-encoded string as defined in the [spec].
103 ///
104 /// *Note*: This returns a copy of the private key material of the
105 /// [`SecretStorageKey`] as a string. The caller needs to ensure that this
106 /// string is zeroized.
107 ///
108 /// [spec]: https://spec.matrix.org/v1.8/client-server-api/#key-representation
109 pub fn secret_storage_key(&self) -> String {
110 self.key.to_base58()
111 }
112
113 /// Retrieve a secret from the homeserver's account data
114 ///
115 /// This method allows you to retrieve a secret from the account data stored
116 /// on the Matrix homeserver.
117 ///
118 /// # Arguments
119 ///
120 /// - `secret_name`: The name of the secret. The provided `secret_name`
121 /// serves as the event type for the associated account data event.
122 ///
123 /// The `retrieve_secret` method enables you to access and decrypt secrets
124 /// previously stored in the user's account data on the homeserver. You can
125 /// use the `secret_name` parameter to specify the desired secret to
126 /// retrieve.
127 ///
128 /// # Examples
129 ///
130 /// ```no_run
131 /// # use matrix_sdk::Client;
132 /// # use url::Url;
133 /// # async {
134 /// # let homeserver = Url::parse("http://example.com")?;
135 /// # let client = Client::new(homeserver).await?;
136 /// use ruma::events::secret::request::SecretName;
137 ///
138 /// let secret_store = client
139 /// .encryption()
140 /// .secret_storage()
141 /// .open_secret_store("It's a secret to everybody")
142 /// .await?;
143 ///
144 /// let my_secret_name = SecretName::from("m.treasure");
145 ///
146 /// let secret = secret_store.get_secret(my_secret_name).await?;
147 ///
148 /// # anyhow::Ok(()) };
149 /// ```
150 pub async fn get_secret(&self, secret_name: impl Into<SecretName>) -> Result<Option<String>> {
151 let secret_name = secret_name.into();
152 let event_type = GlobalAccountDataEventType::from(secret_name.to_owned());
153
154 if let Some(secret_content) = self.client.account().fetch_account_data(event_type).await? {
155 let mut secret_content =
156 secret_content.deserialize_as_unchecked::<SecretEventContent>()?;
157
158 // The `SecretEventContent` contains a map from the secret storage key ID to the
159 // ciphertext. Let's try to find a secret which was encrypted using our
160 // [`SecretStorageKey`].
161 if let Some(secret_content) = secret_content.encrypted.remove(self.key.key_id()) {
162 // We found a secret we should be able to decrypt, let's try to do so.
163 let decrypted = self
164 .key
165 .decrypt(&secret_content.try_into()?, &secret_name)
166 .map_err(DecryptionError::from)?;
167
168 let secret = String::from_utf8(decrypted).map_err(DecryptionError::from)?;
169
170 Ok(Some(secret))
171 } else {
172 // We did not find a secret which was encrypted using our [`SecretStorageKey`],
173 // no need to try to decrypt.
174 Ok(None)
175 }
176 } else {
177 Ok(None)
178 }
179 }
180
181 /// Store a secret in the homeserver's account data
182 ///
183 /// This method allows you to securely store a secret on the Matrix
184 /// homeserver as an encrypted account data event.
185 ///
186 /// # Arguments
187 ///
188 /// - `secret_name`: The name of the secret. The provided `secret_name`
189 /// serves as the event type for the account data event on the homeserver.
190 ///
191 /// - `secret`: The secret to be stored on the homeserver. The secret is
192 /// encrypted before being stored, ensuring its confidentiality and
193 /// integrity.
194 ///
195 /// # Examples
196 ///
197 /// ```no_run
198 /// # use matrix_sdk::Client;
199 /// # use url::Url;
200 /// # async {
201 /// # let homeserver = Url::parse("http://example.com")?;
202 /// # let client = Client::new(homeserver).await?;
203 /// use ruma::events::secret::request::SecretName;
204 ///
205 /// let secret_store = client
206 /// .encryption()
207 /// .secret_storage()
208 /// .open_secret_store("It's a secret to everybody")
209 /// .await?;
210 ///
211 /// let my_secret = "Top secret secret";
212 /// let my_secret_name = SecretName::from("m.treasure");
213 ///
214 /// secret_store.put_secret(my_secret_name, my_secret);
215 ///
216 /// # anyhow::Ok(()) };
217 /// ```
218 pub async fn put_secret(&self, secret_name: impl Into<SecretName>, secret: &str) -> Result<()> {
219 // This function does a read/update/store of an account data event stored on the
220 // homeserver. We first fetch the existing account data event, the event
221 // contains a map which gets updated by this method, finally we upload the
222 // modified event.
223 //
224 // To prevent multiple calls to this method trying to update a secret at the
225 // same time, and thus trampling on each other we introduce a lock which
226 // acts as a semaphore.
227 //
228 // Technically there's a low chance of this happening since we're not storing
229 // many secrets and the bigger problem is that another client might be
230 // doing this as well and the server doesn't have a mechanism to protect against
231 // this.
232 //
233 // We could make this lock be per `secret_name` but this is not a performance
234 // critical method.
235 let _guard = self.client.locks().store_secret_lock.lock().await;
236
237 let secret_name = secret_name.into();
238 let event_type = GlobalAccountDataEventType::from(secret_name.to_owned());
239
240 // Get the existing account data event or create a new empty one.
241 let mut secret_content = if let Some(secret_content) =
242 self.client.account().fetch_account_data(event_type.to_owned()).await?
243 {
244 secret_content
245 .deserialize_as_unchecked::<SecretEventContent>()
246 .unwrap_or_else(|_| SecretEventContent::new(Default::default()))
247 } else {
248 SecretEventContent::new(Default::default())
249 };
250
251 // Encrypt the secret.
252 let secret = secret.as_bytes().to_vec();
253 let encrypted_secret = self.key.encrypt(secret, &secret_name);
254
255 // Insert the encrypted secret into the account data event.
256 secret_content.encrypted.insert(self.key.key_id().to_owned(), encrypted_secret.into());
257 let secret_content = Raw::from_json(to_raw_value(&secret_content)?);
258
259 // Upload the modified account data event, now that the new secret has been
260 // inserted.
261 self.client.account().set_account_data_raw(event_type, secret_content).await?;
262
263 Ok(())
264 }
265
266 /// Get all the well-known private parts/keys of the [`OwnUserIdentity`] as
267 /// a [`CrossSigningKeyExport`].
268 ///
269 /// The export can be imported into the [`OlmMachine`] using
270 /// [`OlmMachine::import_cross_signing_keys()`].
271 async fn get_cross_signing_keys(&self) -> Result<CrossSigningKeyExport> {
272 let mut export = CrossSigningKeyExport::default();
273
274 export.master_key = self.get_secret(SecretName::CrossSigningMasterKey).await?;
275 export.self_signing_key = self.get_secret(SecretName::CrossSigningSelfSigningKey).await?;
276 export.user_signing_key = self.get_secret(SecretName::CrossSigningUserSigningKey).await?;
277
278 Ok(export)
279 }
280
281 async fn put_cross_signing_keys(&self, export: CrossSigningKeyExport) -> Result<()> {
282 if let Some(master_key) = &export.master_key {
283 self.put_secret(SecretName::CrossSigningMasterKey, master_key).await?;
284 }
285
286 if let Some(user_signing_key) = &export.user_signing_key {
287 self.put_secret(SecretName::CrossSigningUserSigningKey, user_signing_key).await?;
288 }
289
290 if let Some(self_signing_key) = &export.self_signing_key {
291 self.put_secret(SecretName::CrossSigningSelfSigningKey, self_signing_key).await?;
292 }
293
294 Ok(())
295 }
296
297 async fn maybe_enable_backups(&self) -> Result<()> {
298 if let Some(mut secret) = self.get_secret(SecretName::RecoveryKey).await? {
299 let ret = self.client.encryption().backups().maybe_enable_backups(&secret).await;
300
301 if let Err(e) = &ret {
302 warn!("Could not enable backups from secret storage: {e:?}");
303 }
304
305 secret.zeroize();
306
307 Ok(ret.map(|_| ())?)
308 } else {
309 info!("No backup recovery key found.");
310
311 Ok(())
312 }
313 }
314
315 /// Retrieve and store well-known secrets locally
316 ///
317 /// This method retrieves and stores all well-known secrets from the account
318 /// data on the Matrix homeserver to enhance local security and identity
319 /// verification.
320 ///
321 /// The following secrets are retrieved by this method:
322 ///
323 /// - `m.cross_signing.master`: The master cross-signing key.
324 /// - `m.cross_signing.self_signing`: The self-signing cross-signing key.
325 /// - `m.cross_signing.user_signing`: The user-signing cross-signing key.
326 /// - `m.megolm_backup.v1`: The backup recovery key.
327 ///
328 /// If the `m.cross_signing.self_signing` key is successfully imported, it
329 /// is used to sign our own [`Device`], marking it as verified. This step is
330 /// establishes trust in your own device's identity.
331 ///
332 /// By invoking this method, you ensure that your device has access to
333 /// the necessary secrets for device and identity verification.
334 ///
335 /// # Examples
336 ///
337 /// ```no_run
338 /// # use matrix_sdk::Client;
339 /// # use url::Url;
340 /// # async {
341 /// # let homeserver = Url::parse("http://example.com")?;
342 /// # let client = Client::new(homeserver).await?;
343 /// use ruma::events::secret::request::SecretName;
344 ///
345 /// let secret_store = client
346 /// .encryption()
347 /// .secret_storage()
348 /// .open_secret_store("It's a secret to everybody")
349 /// .await?;
350 ///
351 /// secret_store.import_secrets().await?;
352 ///
353 /// let status = client
354 /// .encryption()
355 /// .cross_signing_status()
356 /// .await
357 /// .expect("We should be able to check out cross-signing status");
358 ///
359 /// println!("Cross-signing status {status:?}");
360 ///
361 /// # anyhow::Ok(()) };
362 /// ```
363 ///
364 /// [`Device`]: crate::encryption::identities::Device
365 #[instrument(fields(user_id, device_id, cross_signing_status))]
366 pub async fn import_secrets(&self) -> Result<()> {
367 let olm_machine = self.client.olm_machine().await;
368 let olm_machine = olm_machine.as_ref().ok_or(crate::Error::NoOlmMachine)?;
369
370 Span::current()
371 .record("user_id", display(olm_machine.user_id()))
372 .record("device_id", display(olm_machine.device_id()));
373
374 info!("Fetching the private cross-signing keys from the secret store");
375
376 // Get all our private cross-signing keys from the secret store.
377 let export = self.get_cross_signing_keys().await?;
378
379 info!(cross_signing_keys = ?export, "Received the cross signing keys from the server");
380
381 // We need to ensure that we have the public parts of the cross-signing keys,
382 // those are represented as the `OwnUserIdentity` struct. The public
383 // parts from the server are compared to the public parts re-derived from the
384 // private parts. We will only import the private parts of the cross-signing
385 // keys if they match to the public parts, otherwise we would risk
386 // importing some stale cross-signing keys leftover in the secret store.
387 let (request_id, request) = olm_machine.query_keys_for_users([olm_machine.user_id()]);
388 self.client.keys_query(&request_id, request.device_keys).await?;
389
390 // Let's now try to import our private cross-signing keys.
391 let status = olm_machine.import_cross_signing_keys(export).await?;
392
393 Span::current().record("cross_signing_status", debug(&status));
394
395 info!("Done importing the cross signing keys");
396
397 if status.has_self_signing {
398 info!("Successfully imported the self-signing key, attempting to sign our own device");
399
400 // Now that we successfully imported them, the self-signing key can be used to
401 // verify our own device so other devices and user identities trust
402 // it if the trust our user identity.
403 if let Some(own_device) = self.client.encryption().get_own_device().await? {
404 own_device.verify().await?;
405
406 // Another /keys/query request to ensure that the signatures we uploaded using
407 // `own_device.verify()` are attached to the `Device` we have in storage.
408 let (request_id, request) =
409 olm_machine.query_keys_for_users([olm_machine.user_id()]);
410 self.client.keys_query(&request_id, request.device_keys).await?;
411
412 info!("Successfully signed our own device, the device is now verified");
413 } else {
414 error!("Couldn't find our own device in the store");
415 }
416 }
417
418 self.maybe_enable_backups().await?;
419
420 Ok(())
421 }
422
423 pub(super) async fn export_secrets(&self) -> Result<()> {
424 let olm_machine = self.client.olm_machine().await;
425 let olm_machine = olm_machine.as_ref().ok_or(crate::Error::NoOlmMachine)?;
426
427 if let Some(cross_signing_keys) = olm_machine.export_cross_signing_keys().await? {
428 self.put_cross_signing_keys(cross_signing_keys).await?;
429 }
430
431 let backup_keys = olm_machine.backup_machine().get_backup_keys().await?;
432
433 if let Some(backup_recovery_key) = backup_keys.decryption_key {
434 let mut key = backup_recovery_key.to_base64();
435 self.put_secret(SecretName::RecoveryKey, &key).await?;
436
437 key.zeroize();
438 }
439
440 Ok(())
441 }
442}
443
444impl fmt::Debug for SecretStore {
445 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
446 f.debug_struct("SecretStore").field("key", &self.key).finish_non_exhaustive()
447 }
448}