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}