matrix_sdk_crypto/machine/
mod.rs

1// Copyright 2020 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
15#[cfg(feature = "experimental-encrypted-state-events")]
16use std::borrow::Borrow;
17use std::{
18    collections::{BTreeMap, HashMap, HashSet},
19    sync::Arc,
20    time::Duration,
21};
22
23use itertools::Itertools;
24#[cfg(feature = "experimental-send-custom-to-device")]
25use matrix_sdk_common::deserialized_responses::WithheldCode;
26use matrix_sdk_common::{
27    deserialized_responses::{
28        AlgorithmInfo, DecryptedRoomEvent, DeviceLinkProblem, EncryptionInfo,
29        ProcessedToDeviceEvent, ToDeviceUnableToDecryptInfo, ToDeviceUnableToDecryptReason,
30        UnableToDecryptInfo, UnableToDecryptReason, UnsignedDecryptionResult,
31        UnsignedEventLocation, VerificationLevel, VerificationState,
32    },
33    locks::RwLock as StdRwLock,
34    timer, BoxFuture,
35};
36#[cfg(feature = "experimental-encrypted-state-events")]
37use ruma::events::{AnyStateEventContent, StateEventContent};
38use ruma::{
39    api::client::{
40        dehydrated_device::DehydratedDeviceData,
41        keys::{
42            claim_keys::v3::Request as KeysClaimRequest,
43            get_keys::v3::Response as KeysQueryResponse,
44            upload_keys::v3::{Request as UploadKeysRequest, Response as UploadKeysResponse},
45            upload_signatures::v3::Request as UploadSignaturesRequest,
46        },
47        sync::sync_events::DeviceLists,
48    },
49    assign,
50    events::{
51        secret::request::SecretName, AnyMessageLikeEvent, AnyMessageLikeEventContent,
52        AnyTimelineEvent, AnyToDeviceEvent, MessageLikeEventContent,
53    },
54    serde::{JsonObject, Raw},
55    DeviceId, MilliSecondsSinceUnixEpoch, OneTimeKeyAlgorithm, OwnedDeviceId, OwnedDeviceKeyId,
56    OwnedTransactionId, OwnedUserId, RoomId, TransactionId, UInt, UserId,
57};
58use serde_json::{value::to_raw_value, Value};
59use tokio::sync::Mutex;
60use tracing::{
61    debug, error,
62    field::{debug, display},
63    info, instrument, trace, warn, Span,
64};
65use vodozemac::{
66    megolm::{DecryptionError, SessionOrdering},
67    Curve25519PublicKey, Ed25519Signature,
68};
69
70#[cfg(feature = "experimental-send-custom-to-device")]
71use crate::session_manager::split_devices_for_share_strategy;
72use crate::{
73    backups::{BackupMachine, MegolmV1BackupKey},
74    dehydrated_devices::{DehydratedDevices, DehydrationError},
75    error::{EventError, MegolmError, MegolmResult, OlmError, OlmResult, SetRoomSettingsError},
76    gossiping::GossipMachine,
77    identities::{user::UserIdentity, Device, IdentityManager, UserDevices},
78    olm::{
79        Account, CrossSigningStatus, EncryptionSettings, IdentityKeys, InboundGroupSession,
80        KnownSenderData, OlmDecryptionInfo, PrivateCrossSigningIdentity, SenderData,
81        SenderDataFinder, SessionType, StaticAccountData,
82    },
83    session_manager::{GroupSessionManager, SessionManager},
84    store::{
85        caches::StoreCache,
86        types::{
87            Changes, CrossSigningKeyExport, DeviceChanges, IdentityChanges, PendingChanges,
88            RoomKeyInfo, RoomSettings, StoredRoomKeyBundleData,
89        },
90        CryptoStoreWrapper, IntoCryptoStore, MemoryStore, Result as StoreResult, SecretImportError,
91        Store, StoreTransaction,
92    },
93    types::{
94        events::{
95            olm_v1::{AnyDecryptedOlmEvent, DecryptedRoomKeyBundleEvent, DecryptedRoomKeyEvent},
96            room::encrypted::{
97                EncryptedEvent, EncryptedToDeviceEvent, RoomEncryptedEventContent,
98                RoomEventEncryptionScheme, SupportedEventEncryptionSchemes,
99                ToDeviceEncryptedEventContent,
100            },
101            room_key::{MegolmV1AesSha2Content, RoomKeyContent},
102            room_key_bundle::RoomKeyBundleContent,
103            room_key_withheld::{
104                MegolmV1AesSha2WithheldContent, RoomKeyWithheldContent, RoomKeyWithheldEvent,
105            },
106            ToDeviceEvent, ToDeviceEvents,
107        },
108        requests::{
109            AnyIncomingResponse, KeysQueryRequest, OutgoingRequest, ToDeviceRequest,
110            UploadSigningKeysRequest,
111        },
112        EventEncryptionAlgorithm, Signatures,
113    },
114    utilities::timestamp_to_iso8601,
115    verification::{Verification, VerificationMachine, VerificationRequest},
116    CollectStrategy, CryptoStoreError, DecryptionSettings, DeviceData, LocalTrust,
117    RoomEventDecryptionResult, SignatureError, TrustRequirement,
118};
119
120/// State machine implementation of the Olm/Megolm encryption protocol used for
121/// Matrix end to end encryption.
122#[derive(Clone)]
123pub struct OlmMachine {
124    pub(crate) inner: Arc<OlmMachineInner>,
125}
126
127pub struct OlmMachineInner {
128    /// The unique user id that owns this account.
129    user_id: OwnedUserId,
130    /// The unique device ID of the device that holds this account.
131    device_id: OwnedDeviceId,
132    /// The private part of our cross signing identity.
133    /// Used to sign devices and other users, might be missing if some other
134    /// device bootstrapped cross signing or cross signing isn't bootstrapped at
135    /// all.
136    user_identity: Arc<Mutex<PrivateCrossSigningIdentity>>,
137    /// Store for the encryption keys.
138    /// Persists all the encryption keys so a client can resume the session
139    /// without the need to create new keys.
140    store: Store,
141    /// A state machine that handles Olm sessions creation.
142    session_manager: SessionManager,
143    /// A state machine that keeps track of our outbound group sessions.
144    pub(crate) group_session_manager: GroupSessionManager,
145    /// A state machine that is responsible to handle and keep track of SAS
146    /// verification flows.
147    verification_machine: VerificationMachine,
148    /// The state machine that is responsible to handle outgoing and incoming
149    /// key requests.
150    pub(crate) key_request_machine: GossipMachine,
151    /// State machine handling public user identities and devices, keeping track
152    /// of when a key query needs to be done and handling one.
153    identity_manager: IdentityManager,
154    /// A state machine that handles creating room key backups.
155    backup_machine: BackupMachine,
156}
157
158#[cfg(not(tarpaulin_include))]
159impl std::fmt::Debug for OlmMachine {
160    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
161        f.debug_struct("OlmMachine")
162            .field("user_id", &self.user_id())
163            .field("device_id", &self.device_id())
164            .finish()
165    }
166}
167
168impl OlmMachine {
169    const CURRENT_GENERATION_STORE_KEY: &'static str = "generation-counter";
170    const HAS_MIGRATED_VERIFICATION_LATCH: &'static str = "HAS_MIGRATED_VERIFICATION_LATCH";
171
172    /// Create a new memory based OlmMachine.
173    ///
174    /// The created machine will keep the encryption keys only in memory and
175    /// once the object is dropped the keys will be lost.
176    ///
177    /// # Arguments
178    ///
179    /// * `user_id` - The unique id of the user that owns this machine.
180    ///
181    /// * `device_id` - The unique id of the device that owns this machine.
182    pub async fn new(user_id: &UserId, device_id: &DeviceId) -> Self {
183        OlmMachine::with_store(user_id, device_id, MemoryStore::new(), None)
184            .await
185            .expect("Reading and writing to the memory store always succeeds")
186    }
187
188    pub(crate) async fn rehydrate(
189        &self,
190        pickle_key: &[u8; 32],
191        device_id: &DeviceId,
192        device_data: Raw<DehydratedDeviceData>,
193    ) -> Result<OlmMachine, DehydrationError> {
194        let account = Account::rehydrate(pickle_key, self.user_id(), device_id, device_data)?;
195        let static_account = account.static_data().clone();
196
197        let store =
198            Arc::new(CryptoStoreWrapper::new(self.user_id(), device_id, MemoryStore::new()));
199        let device = DeviceData::from_account(&account);
200        store.save_pending_changes(PendingChanges { account: Some(account) }).await?;
201        store
202            .save_changes(Changes {
203                devices: DeviceChanges { new: vec![device], ..Default::default() },
204                ..Default::default()
205            })
206            .await?;
207
208        let (verification_machine, store, identity_manager) =
209            Self::new_helper_prelude(store, static_account, self.store().private_identity());
210
211        Ok(Self::new_helper(
212            device_id,
213            store,
214            verification_machine,
215            identity_manager,
216            self.store().private_identity(),
217            None,
218        ))
219    }
220
221    fn new_helper_prelude(
222        store_wrapper: Arc<CryptoStoreWrapper>,
223        account: StaticAccountData,
224        user_identity: Arc<Mutex<PrivateCrossSigningIdentity>>,
225    ) -> (VerificationMachine, Store, IdentityManager) {
226        let verification_machine =
227            VerificationMachine::new(account.clone(), user_identity.clone(), store_wrapper.clone());
228        let store = Store::new(account, user_identity, store_wrapper, verification_machine.clone());
229
230        let identity_manager = IdentityManager::new(store.clone());
231
232        (verification_machine, store, identity_manager)
233    }
234
235    fn new_helper(
236        device_id: &DeviceId,
237        store: Store,
238        verification_machine: VerificationMachine,
239        identity_manager: IdentityManager,
240        user_identity: Arc<Mutex<PrivateCrossSigningIdentity>>,
241        maybe_backup_key: Option<MegolmV1BackupKey>,
242    ) -> Self {
243        let group_session_manager = GroupSessionManager::new(store.clone());
244
245        let users_for_key_claim = Arc::new(StdRwLock::new(BTreeMap::new()));
246        let key_request_machine = GossipMachine::new(
247            store.clone(),
248            identity_manager.clone(),
249            group_session_manager.session_cache(),
250            users_for_key_claim.clone(),
251        );
252
253        let session_manager =
254            SessionManager::new(users_for_key_claim, key_request_machine.clone(), store.clone());
255
256        let backup_machine = BackupMachine::new(store.clone(), maybe_backup_key);
257
258        let inner = Arc::new(OlmMachineInner {
259            user_id: store.user_id().to_owned(),
260            device_id: device_id.to_owned(),
261            user_identity,
262            store,
263            session_manager,
264            group_session_manager,
265            verification_machine,
266            key_request_machine,
267            identity_manager,
268            backup_machine,
269        });
270
271        Self { inner }
272    }
273
274    /// Create a new OlmMachine with the given [`CryptoStore`].
275    ///
276    /// If the store already contains encryption keys for the given user/device
277    /// pair those will be re-used. Otherwise new ones will be created and
278    /// stored.
279    ///
280    /// # Arguments
281    ///
282    /// * `user_id` - The unique id of the user that owns this machine.
283    ///
284    /// * `device_id` - The unique id of the device that owns this machine.
285    ///
286    /// * `store` - A `CryptoStore` implementation that will be used to store
287    /// the encryption keys.
288    ///
289    /// * `custom_account` - A custom [`vodozemac::olm::Account`] to be used for
290    ///   the identity and one-time keys of this [`OlmMachine`]. If no account
291    ///   is provided, a new default one or one from the store will be used. If
292    ///   an account is provided and one already exists in the store for this
293    ///   [`UserId`]/[`DeviceId`] combination, an error will be raised. This is
294    ///   useful if one wishes to create identity keys before knowing the
295    ///   user/device IDs, e.g., to use the identity key as the device ID.
296    ///
297    /// [`CryptoStore`]: crate::store::CryptoStore
298    #[instrument(skip(store, custom_account), fields(ed25519_key, curve25519_key))]
299    pub async fn with_store(
300        user_id: &UserId,
301        device_id: &DeviceId,
302        store: impl IntoCryptoStore,
303        custom_account: Option<vodozemac::olm::Account>,
304    ) -> StoreResult<Self> {
305        let store = store.into_crypto_store();
306
307        let static_account = match store.load_account().await? {
308            Some(account) => {
309                if user_id != account.user_id()
310                    || device_id != account.device_id()
311                    || custom_account.is_some()
312                {
313                    return Err(CryptoStoreError::MismatchedAccount {
314                        expected: (account.user_id().to_owned(), account.device_id().to_owned()),
315                        got: (user_id.to_owned(), device_id.to_owned()),
316                    });
317                }
318
319                Span::current()
320                    .record("ed25519_key", display(account.identity_keys().ed25519))
321                    .record("curve25519_key", display(account.identity_keys().curve25519));
322                debug!("Restored an Olm account");
323
324                account.static_data().clone()
325            }
326
327            None => {
328                let account = if let Some(account) = custom_account {
329                    Account::new_helper(account, user_id, device_id)
330                } else {
331                    Account::with_device_id(user_id, device_id)
332                };
333
334                let static_account = account.static_data().clone();
335
336                Span::current()
337                    .record("ed25519_key", display(account.identity_keys().ed25519))
338                    .record("curve25519_key", display(account.identity_keys().curve25519));
339
340                let device = DeviceData::from_account(&account);
341
342                // We just created this device from our own Olm `Account`. Since we are the
343                // owners of the private keys of this device we can safely mark
344                // the device as verified.
345                device.set_trust_state(LocalTrust::Verified);
346
347                let changes = Changes {
348                    devices: DeviceChanges { new: vec![device], ..Default::default() },
349                    ..Default::default()
350                };
351                store.save_changes(changes).await?;
352                store.save_pending_changes(PendingChanges { account: Some(account) }).await?;
353
354                debug!("Created a new Olm account");
355
356                static_account
357            }
358        };
359
360        let identity = match store.load_identity().await? {
361            Some(i) => {
362                let master_key = i
363                    .master_public_key()
364                    .await
365                    .and_then(|m| m.get_first_key().map(|m| m.to_owned()));
366                debug!(?master_key, "Restored the cross signing identity");
367                i
368            }
369            None => {
370                debug!("Creating an empty cross signing identity stub");
371                PrivateCrossSigningIdentity::empty(user_id)
372            }
373        };
374
375        // FIXME: This is a workaround for `regenerate_olm` clearing the backup
376        // state. Ideally, backups should not get automatically enabled since
377        // the `OlmMachine` doesn't get enough info from the homeserver for this
378        // to work reliably.
379        let saved_keys = store.load_backup_keys().await?;
380        let maybe_backup_key = saved_keys.decryption_key.and_then(|k| {
381            if let Some(version) = saved_keys.backup_version {
382                let megolm_v1_backup_key = k.megolm_v1_public_key();
383                megolm_v1_backup_key.set_version(version);
384                Some(megolm_v1_backup_key)
385            } else {
386                None
387            }
388        });
389
390        let identity = Arc::new(Mutex::new(identity));
391        let store = Arc::new(CryptoStoreWrapper::new(user_id, device_id, store));
392
393        let (verification_machine, store, identity_manager) =
394            Self::new_helper_prelude(store, static_account, identity.clone());
395
396        // FIXME: We might want in the future a more generic high-level data migration
397        // mechanism (at the store wrapper layer).
398        Self::migration_post_verified_latch_support(&store, &identity_manager).await?;
399
400        Ok(Self::new_helper(
401            device_id,
402            store,
403            verification_machine,
404            identity_manager,
405            identity,
406            maybe_backup_key,
407        ))
408    }
409
410    // The sdk now support verified identity change detection.
411    // This introduces a new local flag (`verified_latch` on
412    // `OtherUserIdentityData`). In order to ensure that this flag is up-to-date and
413    // for the sake of simplicity we force a re-download of tracked users by marking
414    // them as dirty.
415    //
416    // pub(crate) visibility for testing.
417    pub(crate) async fn migration_post_verified_latch_support(
418        store: &Store,
419        identity_manager: &IdentityManager,
420    ) -> Result<(), CryptoStoreError> {
421        let maybe_migrate_for_identity_verified_latch =
422            store.get_custom_value(Self::HAS_MIGRATED_VERIFICATION_LATCH).await?.is_none();
423
424        if maybe_migrate_for_identity_verified_latch {
425            identity_manager.mark_all_tracked_users_as_dirty(store.cache().await?).await?;
426
427            store.set_custom_value(Self::HAS_MIGRATED_VERIFICATION_LATCH, vec![0]).await?
428        }
429        Ok(())
430    }
431
432    /// Get the crypto store associated with this `OlmMachine` instance.
433    pub fn store(&self) -> &Store {
434        &self.inner.store
435    }
436
437    /// The unique user id that owns this `OlmMachine` instance.
438    pub fn user_id(&self) -> &UserId {
439        &self.inner.user_id
440    }
441
442    /// The unique device ID that identifies this `OlmMachine`.
443    pub fn device_id(&self) -> &DeviceId {
444        &self.inner.device_id
445    }
446
447    /// The time at which the `Account` backing this `OlmMachine` was created.
448    ///
449    /// An [`Account`] is created when an `OlmMachine` is first instantiated
450    /// against a given [`Store`], at which point it creates identity keys etc.
451    /// This method returns the timestamp, according to the local clock, at
452    /// which that happened.
453    pub fn device_creation_time(&self) -> MilliSecondsSinceUnixEpoch {
454        self.inner.store.static_account().creation_local_time()
455    }
456
457    /// Get the public parts of our Olm identity keys.
458    pub fn identity_keys(&self) -> IdentityKeys {
459        let account = self.inner.store.static_account();
460        account.identity_keys()
461    }
462
463    /// Get the display name of our own device
464    pub async fn display_name(&self) -> StoreResult<Option<String>> {
465        self.store().device_display_name().await
466    }
467
468    /// Get the list of "tracked users".
469    ///
470    /// See [`update_tracked_users`](#method.update_tracked_users) for more
471    /// information.
472    pub async fn tracked_users(&self) -> StoreResult<HashSet<OwnedUserId>> {
473        let cache = self.store().cache().await?;
474        Ok(self.inner.identity_manager.key_query_manager.synced(&cache).await?.tracked_users())
475    }
476
477    /// Enable or disable room key requests.
478    ///
479    /// Room key requests allow the device to request room keys that it might
480    /// have missed in the original share using `m.room_key_request`
481    /// events.
482    ///
483    /// See also [`OlmMachine::set_room_key_forwarding_enabled`] and
484    /// [`OlmMachine::are_room_key_requests_enabled`].
485    #[cfg(feature = "automatic-room-key-forwarding")]
486    pub fn set_room_key_requests_enabled(&self, enable: bool) {
487        self.inner.key_request_machine.set_room_key_requests_enabled(enable)
488    }
489
490    /// Query whether we should send outgoing `m.room_key_request`s on
491    /// decryption failure.
492    ///
493    /// See also [`OlmMachine::set_room_key_requests_enabled`].
494    pub fn are_room_key_requests_enabled(&self) -> bool {
495        self.inner.key_request_machine.are_room_key_requests_enabled()
496    }
497
498    /// Enable or disable room key forwarding.
499    ///
500    /// If room key forwarding is enabled, we will automatically reply to
501    /// incoming `m.room_key_request` messages from verified devices by
502    /// forwarding the requested key (if we have it).
503    ///
504    /// See also [`OlmMachine::set_room_key_requests_enabled`] and
505    /// [`OlmMachine::is_room_key_forwarding_enabled`].
506    #[cfg(feature = "automatic-room-key-forwarding")]
507    pub fn set_room_key_forwarding_enabled(&self, enable: bool) {
508        self.inner.key_request_machine.set_room_key_forwarding_enabled(enable)
509    }
510
511    /// Is room key forwarding enabled?
512    ///
513    /// See also [`OlmMachine::set_room_key_forwarding_enabled`].
514    pub fn is_room_key_forwarding_enabled(&self) -> bool {
515        self.inner.key_request_machine.is_room_key_forwarding_enabled()
516    }
517
518    /// Get the outgoing requests that need to be sent out.
519    ///
520    /// This returns a list of [`OutgoingRequest`]. Those requests need to be
521    /// sent out to the server and the responses need to be passed back to
522    /// the state machine using [`mark_request_as_sent`].
523    ///
524    /// [`mark_request_as_sent`]: #method.mark_request_as_sent
525    pub async fn outgoing_requests(&self) -> StoreResult<Vec<OutgoingRequest>> {
526        let mut requests = Vec::new();
527
528        {
529            let store_cache = self.inner.store.cache().await?;
530            let account = store_cache.account().await?;
531            if let Some(r) = self.keys_for_upload(&account).await.map(|r| OutgoingRequest {
532                request_id: TransactionId::new(),
533                request: Arc::new(r.into()),
534            }) {
535                requests.push(r);
536            }
537        }
538
539        for request in self
540            .inner
541            .identity_manager
542            .users_for_key_query()
543            .await?
544            .into_iter()
545            .map(|(request_id, r)| OutgoingRequest { request_id, request: Arc::new(r.into()) })
546        {
547            requests.push(request);
548        }
549
550        requests.append(&mut self.inner.verification_machine.outgoing_messages());
551        requests.append(&mut self.inner.key_request_machine.outgoing_to_device_requests().await?);
552
553        Ok(requests)
554    }
555
556    /// Generate an "out-of-band" key query request for the given set of users.
557    ///
558    /// This can be useful if we need the results from [`get_identity`] or
559    /// [`get_user_devices`] to be as up-to-date as possible.
560    ///
561    /// Note that this request won't be awaited by other calls waiting for a
562    /// user's or device's keys, since this is an out-of-band query.
563    ///
564    /// # Arguments
565    ///
566    /// * `users` - list of users whose keys should be queried
567    ///
568    /// # Returns
569    ///
570    /// A request to be sent out to the server. Once sent, the response should
571    /// be passed back to the state machine using [`mark_request_as_sent`].
572    ///
573    /// [`mark_request_as_sent`]: OlmMachine::mark_request_as_sent
574    /// [`get_identity`]: OlmMachine::get_identity
575    /// [`get_user_devices`]: OlmMachine::get_user_devices
576    pub fn query_keys_for_users<'a>(
577        &self,
578        users: impl IntoIterator<Item = &'a UserId>,
579    ) -> (OwnedTransactionId, KeysQueryRequest) {
580        self.inner.identity_manager.build_key_query_for_users(users)
581    }
582
583    /// Mark the request with the given request id as sent.
584    ///
585    /// # Arguments
586    ///
587    /// * `request_id` - The unique id of the request that was sent out. This is
588    ///   needed to couple the response with the now sent out request.
589    ///
590    /// * `response` - The response that was received from the server after the
591    ///   outgoing request was sent out.
592    pub async fn mark_request_as_sent<'a>(
593        &self,
594        request_id: &TransactionId,
595        response: impl Into<AnyIncomingResponse<'a>>,
596    ) -> OlmResult<()> {
597        match response.into() {
598            AnyIncomingResponse::KeysUpload(response) => {
599                Box::pin(self.receive_keys_upload_response(response)).await?;
600            }
601            AnyIncomingResponse::KeysQuery(response) => {
602                Box::pin(self.receive_keys_query_response(request_id, response)).await?;
603            }
604            AnyIncomingResponse::KeysClaim(response) => {
605                Box::pin(
606                    self.inner.session_manager.receive_keys_claim_response(request_id, response),
607                )
608                .await?;
609            }
610            AnyIncomingResponse::ToDevice(_) => {
611                Box::pin(self.mark_to_device_request_as_sent(request_id)).await?;
612            }
613            AnyIncomingResponse::SigningKeysUpload(_) => {
614                Box::pin(self.receive_cross_signing_upload_response()).await?;
615            }
616            AnyIncomingResponse::SignatureUpload(_) => {
617                self.inner.verification_machine.mark_request_as_sent(request_id);
618            }
619            AnyIncomingResponse::RoomMessage(_) => {
620                self.inner.verification_machine.mark_request_as_sent(request_id);
621            }
622            AnyIncomingResponse::KeysBackup(_) => {
623                Box::pin(self.inner.backup_machine.mark_request_as_sent(request_id)).await?;
624            }
625        }
626
627        Ok(())
628    }
629
630    /// Mark the cross signing identity as shared.
631    async fn receive_cross_signing_upload_response(&self) -> StoreResult<()> {
632        let identity = self.inner.user_identity.lock().await;
633        identity.mark_as_shared();
634
635        let changes = Changes { private_identity: Some(identity.clone()), ..Default::default() };
636
637        self.store().save_changes(changes).await
638    }
639
640    /// Create a new cross signing identity and get the upload request to push
641    /// the new public keys to the server.
642    ///
643    /// **Warning**: if called with `reset`, this will delete any existing cross
644    /// signing keys that might exist on the server and thus will reset the
645    /// trust between all the devices.
646    ///
647    /// # Returns
648    ///
649    /// A triple of requests which should be sent out to the server, in the
650    /// order they appear in the return tuple.
651    ///
652    /// The first request's response, if present, should be passed back to the
653    /// state machine using [`mark_request_as_sent`].
654    ///
655    /// These requests may require user interactive auth.
656    ///
657    /// [`mark_request_as_sent`]: #method.mark_request_as_sent
658    pub async fn bootstrap_cross_signing(
659        &self,
660        reset: bool,
661    ) -> StoreResult<CrossSigningBootstrapRequests> {
662        // Don't hold the lock, otherwise we might deadlock in
663        // `bootstrap_cross_signing()` on `account` if a sync task is already
664        // running (which locks `account`), or we will deadlock
665        // in `upload_device_keys()` which locks private identity again.
666        let identity = self.inner.user_identity.lock().await.clone();
667
668        let (upload_signing_keys_req, upload_signatures_req) = if reset || identity.is_empty().await
669        {
670            info!("Creating new cross signing identity");
671
672            let (identity, upload_signing_keys_req, upload_signatures_req) = {
673                let cache = self.inner.store.cache().await?;
674                let account = cache.account().await?;
675                account.bootstrap_cross_signing().await
676            };
677
678            let public = identity.to_public_identity().await.expect(
679                "Couldn't create a public version of the identity from a new private identity",
680            );
681
682            *self.inner.user_identity.lock().await = identity.clone();
683
684            self.store()
685                .save_changes(Changes {
686                    identities: IdentityChanges { new: vec![public.into()], ..Default::default() },
687                    private_identity: Some(identity),
688                    ..Default::default()
689                })
690                .await?;
691
692            (upload_signing_keys_req, upload_signatures_req)
693        } else {
694            info!("Trying to upload the existing cross signing identity");
695            let upload_signing_keys_req = identity.as_upload_request().await;
696
697            // TODO remove this expect.
698            let upload_signatures_req = identity
699                .sign_account(self.inner.store.static_account())
700                .await
701                .expect("Can't sign device keys");
702
703            (upload_signing_keys_req, upload_signatures_req)
704        };
705
706        // If there are any *device* keys to upload (i.e. the account isn't shared),
707        // upload them before we upload the signatures, since the signatures may
708        // reference keys to be uploaded.
709        let upload_keys_req =
710            self.upload_device_keys().await?.map(|(_, request)| OutgoingRequest::from(request));
711
712        Ok(CrossSigningBootstrapRequests {
713            upload_signing_keys_req,
714            upload_keys_req,
715            upload_signatures_req,
716        })
717    }
718
719    /// Upload the device keys for this [`OlmMachine`].
720    ///
721    /// **Warning**: Do not use this method if
722    /// [`OlmMachine::outgoing_requests()`] is already in use. This method
723    /// is intended for explicitly uploading the device keys before starting
724    /// a sync and before using [`OlmMachine::outgoing_requests()`].
725    ///
726    /// # Returns
727    ///
728    /// A tuple containing a transaction ID and a request if the device keys
729    /// need to be uploaded. Otherwise, returns `None`.
730    pub async fn upload_device_keys(
731        &self,
732    ) -> StoreResult<Option<(OwnedTransactionId, UploadKeysRequest)>> {
733        let cache = self.store().cache().await?;
734        let account = cache.account().await?;
735
736        Ok(self.keys_for_upload(&account).await.map(|request| (TransactionId::new(), request)))
737    }
738
739    /// Receive a successful `/keys/upload` response.
740    ///
741    /// # Arguments
742    ///
743    /// * `response` - The response of the `/keys/upload` request that the
744    ///   client performed.
745    async fn receive_keys_upload_response(&self, response: &UploadKeysResponse) -> OlmResult<()> {
746        self.inner
747            .store
748            .with_transaction(|mut tr| async {
749                let account = tr.account().await?;
750                account.receive_keys_upload_response(response)?;
751                Ok((tr, ()))
752            })
753            .await
754    }
755
756    /// Get a key claiming request for the user/device pairs that we are
757    /// missing Olm sessions for.
758    ///
759    /// Returns None if no key claiming request needs to be sent out.
760    ///
761    /// Sessions need to be established between devices so group sessions for a
762    /// room can be shared with them.
763    ///
764    /// This should be called every time a group session needs to be shared as
765    /// well as between sync calls. After a sync some devices may request room
766    /// keys without us having a valid Olm session with them, making it
767    /// impossible to server the room key request, thus it's necessary to check
768    /// for missing sessions between sync as well.
769    ///
770    /// **Note**: Care should be taken that only one such request at a time is
771    /// in flight, e.g. using a lock.
772    ///
773    /// The response of a successful key claiming requests needs to be passed to
774    /// the `OlmMachine` with the [`mark_request_as_sent`].
775    ///
776    /// # Arguments
777    ///
778    /// `users` - The list of users that we should check if we lack a session
779    /// with one of their devices. This can be an empty iterator when calling
780    /// this method between sync requests.
781    ///
782    /// [`mark_request_as_sent`]: #method.mark_request_as_sent
783    #[instrument(skip_all)]
784    pub async fn get_missing_sessions(
785        &self,
786        users: impl Iterator<Item = &UserId>,
787    ) -> StoreResult<Option<(OwnedTransactionId, KeysClaimRequest)>> {
788        self.inner.session_manager.get_missing_sessions(users).await
789    }
790
791    /// Receive a successful `/keys/query` response.
792    ///
793    /// Returns a list of newly discovered devices and devices that changed.
794    ///
795    /// # Arguments
796    ///
797    /// * `response` - The response of the `/keys/query` request that the client
798    ///   performed.
799    async fn receive_keys_query_response(
800        &self,
801        request_id: &TransactionId,
802        response: &KeysQueryResponse,
803    ) -> OlmResult<(DeviceChanges, IdentityChanges)> {
804        self.inner.identity_manager.receive_keys_query_response(request_id, response).await
805    }
806
807    /// Get a request to upload E2EE keys to the server.
808    ///
809    /// Returns None if no keys need to be uploaded.
810    ///
811    /// The response of a successful key upload requests needs to be passed to
812    /// the [`OlmMachine`] with the [`receive_keys_upload_response`].
813    ///
814    /// [`receive_keys_upload_response`]: #method.receive_keys_upload_response
815    async fn keys_for_upload(&self, account: &Account) -> Option<UploadKeysRequest> {
816        let (mut device_keys, one_time_keys, fallback_keys) = account.keys_for_upload();
817
818        // When uploading the device keys, if all private cross-signing keys are
819        // available locally, sign the device using these cross-signing keys.
820        // This will mark the device as verified if the user identity (i.e., the
821        // cross-signing keys) is also marked as verified.
822        //
823        // This approach eliminates the need to upload signatures in a separate request,
824        // ensuring that other users/devices will never encounter this device
825        // without a signature from their user identity. Consequently, they will
826        // never see the device as unverified.
827        if let Some(device_keys) = &mut device_keys {
828            let private_identity = self.store().private_identity();
829            let guard = private_identity.lock().await;
830
831            if guard.status().await.is_complete() {
832                guard.sign_device_keys(device_keys).await.expect(
833                    "We should be able to sign our device keys since we confirmed that we \
834                     have a complete set of private cross-signing keys",
835                );
836            }
837        }
838
839        if device_keys.is_none() && one_time_keys.is_empty() && fallback_keys.is_empty() {
840            None
841        } else {
842            let device_keys = device_keys.map(|d| d.to_raw());
843
844            Some(assign!(UploadKeysRequest::new(), {
845                device_keys, one_time_keys, fallback_keys
846            }))
847        }
848    }
849
850    /// Decrypt and handle a to-device event.
851    ///
852    /// If decryption (or checking the sender device) fails, returns an
853    /// `Err(DecryptToDeviceError::OlmError)`.
854    ///
855    /// If we are in strict "exclude insecure devices" mode and the sender
856    /// device is not verified, and the decrypted event type is not on the
857    /// allow list, returns `Err(DecryptToDeviceError::UnverifiedSender)`
858    ///
859    /// (The allow list of types that are processed even if the sender is
860    /// unverified is: `m.room_key`, `m.room_key.withheld`,
861    /// `m.room_key_request`, `m.secret.request` and `m.key.verification.*`.)
862    ///
863    /// If the sender device is dehydrated, does no handling and immediately
864    /// returns `Err(DecryptToDeviceError::FromDehydratedDevice)`.
865    ///
866    /// Otherwise, handles the decrypted event and returns it (decrypted) as
867    /// `Ok(OlmDecryptionInfo)`.
868    ///
869    /// # Arguments
870    ///
871    /// * `event` - The to-device event that should be decrypted.
872    async fn decrypt_to_device_event(
873        &self,
874        transaction: &mut StoreTransaction,
875        event: &EncryptedToDeviceEvent,
876        changes: &mut Changes,
877        decryption_settings: &DecryptionSettings,
878    ) -> Result<OlmDecryptionInfo, DecryptToDeviceError> {
879        // Decrypt the event
880        let mut decrypted = transaction
881            .account()
882            .await?
883            .decrypt_to_device_event(&self.inner.store, event, decryption_settings)
884            .await?;
885
886        // Return early if the sending device is a dehydrated device
887        self.check_to_device_event_is_not_from_dehydrated_device(&decrypted, &event.sender).await?;
888
889        // Device is not dehydrated: handle it as normal e.g. create a Megolm session
890        self.handle_decrypted_to_device_event(transaction.cache(), &mut decrypted, changes).await?;
891
892        Ok(decrypted)
893    }
894
895    #[instrument(
896        skip_all,
897        // This function is only ever called by add_room_key via
898        // handle_decrypted_to_device_event, so sender, sender_key, and algorithm are
899        // already recorded.
900        fields(room_id = ? content.room_id, session_id, message_index)
901    )]
902    async fn handle_key(
903        &self,
904        sender_key: Curve25519PublicKey,
905        event: &DecryptedRoomKeyEvent,
906        content: &MegolmV1AesSha2Content,
907    ) -> OlmResult<Option<InboundGroupSession>> {
908        let session =
909            InboundGroupSession::from_room_key_content(sender_key, event.keys.ed25519, content);
910
911        match session {
912            Ok(mut session) => {
913                Span::current().record("session_id", session.session_id());
914                Span::current().record("message_index", session.first_known_index());
915
916                let sender_data =
917                    SenderDataFinder::find_using_event(self.store(), sender_key, event, &session)
918                        .await?;
919
920                session.sender_data = sender_data;
921
922                match self.store().compare_group_session(&session).await? {
923                    SessionOrdering::Better => {
924                        info!("Received a new megolm room key");
925
926                        Ok(Some(session))
927                    }
928                    comparison_result => {
929                        warn!(
930                            ?comparison_result,
931                            "Received a megolm room key that we already have a better version \
932                             of, discarding"
933                        );
934
935                        Ok(None)
936                    }
937                }
938            }
939            Err(e) => {
940                Span::current().record("session_id", &content.session_id);
941                warn!("Received a room key event which contained an invalid session key: {e}");
942
943                Ok(None)
944            }
945        }
946    }
947
948    /// Create a group session from a room key and add it to our crypto store.
949    #[instrument(skip_all, fields(algorithm = ?event.content.algorithm()))]
950    async fn add_room_key(
951        &self,
952        sender_key: Curve25519PublicKey,
953        event: &DecryptedRoomKeyEvent,
954    ) -> OlmResult<Option<InboundGroupSession>> {
955        match &event.content {
956            RoomKeyContent::MegolmV1AesSha2(content) => {
957                self.handle_key(sender_key, event, content).await
958            }
959            #[cfg(feature = "experimental-algorithms")]
960            RoomKeyContent::MegolmV2AesSha2(content) => {
961                self.handle_key(sender_key, event, content).await
962            }
963            RoomKeyContent::Unknown(_) => {
964                warn!("Received a room key with an unsupported algorithm");
965                Ok(None)
966            }
967        }
968    }
969
970    /// Handle a received, decrypted, `io.element.msc4268.room_key_bundle`
971    /// to-device event.
972    #[instrument()]
973    async fn receive_room_key_bundle_data(
974        &self,
975        sender_key: Curve25519PublicKey,
976        event: &DecryptedRoomKeyBundleEvent,
977        changes: &mut Changes,
978    ) -> OlmResult<()> {
979        let Some(sender_device_keys) = &event.sender_device_keys else {
980            warn!("Received a room key bundle with no sender device keys: ignoring");
981            return Ok(());
982        };
983
984        // NOTE: We already checked that `sender_device_keys` matches the actual sender
985        // of the message when we decrypted the message, which included doing
986        // `DeviceData::try_from` on it, so it can't fail.
987
988        let sender_device_data =
989            DeviceData::try_from(sender_device_keys).expect("failed to verify sender device keys");
990        let sender_device = self.store().wrap_device_data(sender_device_data).await?;
991
992        changes.received_room_key_bundles.push(StoredRoomKeyBundleData {
993            sender_user: event.sender.clone(),
994            sender_data: SenderData::from_device(&sender_device),
995            sender_key,
996            bundle_data: event.content.clone(),
997        });
998        Ok(())
999    }
1000
1001    fn add_withheld_info(&self, changes: &mut Changes, event: &RoomKeyWithheldEvent) {
1002        debug!(?event.content, "Processing `m.room_key.withheld` event");
1003
1004        if let RoomKeyWithheldContent::MegolmV1AesSha2(
1005            MegolmV1AesSha2WithheldContent::BlackListed(c)
1006            | MegolmV1AesSha2WithheldContent::Unverified(c),
1007        ) = &event.content
1008        {
1009            changes
1010                .withheld_session_info
1011                .entry(c.room_id.to_owned())
1012                .or_default()
1013                .insert(c.session_id.to_owned(), event.to_owned());
1014        }
1015    }
1016
1017    #[cfg(test)]
1018    pub(crate) async fn create_outbound_group_session_with_defaults_test_helper(
1019        &self,
1020        room_id: &RoomId,
1021    ) -> OlmResult<()> {
1022        let (_, session) = self
1023            .inner
1024            .group_session_manager
1025            .create_outbound_group_session(
1026                room_id,
1027                EncryptionSettings::default(),
1028                SenderData::unknown(),
1029            )
1030            .await?;
1031
1032        self.store().save_inbound_group_sessions(&[session]).await?;
1033
1034        Ok(())
1035    }
1036
1037    #[cfg(test)]
1038    #[allow(dead_code)]
1039    pub(crate) async fn create_inbound_session_test_helper(
1040        &self,
1041        room_id: &RoomId,
1042    ) -> OlmResult<InboundGroupSession> {
1043        let (_, session) = self
1044            .inner
1045            .group_session_manager
1046            .create_outbound_group_session(
1047                room_id,
1048                EncryptionSettings::default(),
1049                SenderData::unknown(),
1050            )
1051            .await?;
1052
1053        Ok(session)
1054    }
1055
1056    /// Encrypt a room message for the given room.
1057    ///
1058    /// Beware that a room key needs to be shared before this method
1059    /// can be called using the [`OlmMachine::share_room_key`] method.
1060    ///
1061    /// # Arguments
1062    ///
1063    /// * `room_id` - The id of the room for which the message should be
1064    ///   encrypted.
1065    ///
1066    /// * `content` - The plaintext content of the message that should be
1067    ///   encrypted.
1068    ///
1069    /// # Panics
1070    ///
1071    /// Panics if a room key for the given room wasn't shared beforehand.
1072    pub async fn encrypt_room_event(
1073        &self,
1074        room_id: &RoomId,
1075        content: impl MessageLikeEventContent,
1076    ) -> MegolmResult<Raw<RoomEncryptedEventContent>> {
1077        let event_type = content.event_type().to_string();
1078        let content = Raw::new(&content)?.cast_unchecked();
1079        self.encrypt_room_event_raw(room_id, &event_type, &content).await
1080    }
1081
1082    /// Encrypt a raw JSON content for the given room.
1083    ///
1084    /// This method is equivalent to the [`OlmMachine::encrypt_room_event()`]
1085    /// method but operates on an arbitrary JSON value instead of strongly-typed
1086    /// event content struct.
1087    ///
1088    /// # Arguments
1089    ///
1090    /// * `room_id` - The id of the room for which the message should be
1091    ///   encrypted.
1092    ///
1093    /// * `content` - The plaintext content of the message that should be
1094    ///   encrypted as a raw JSON value.
1095    ///
1096    /// * `event_type` - The plaintext type of the event.
1097    ///
1098    /// # Panics
1099    ///
1100    /// Panics if a group session for the given room wasn't shared beforehand.
1101    pub async fn encrypt_room_event_raw(
1102        &self,
1103        room_id: &RoomId,
1104        event_type: &str,
1105        content: &Raw<AnyMessageLikeEventContent>,
1106    ) -> MegolmResult<Raw<RoomEncryptedEventContent>> {
1107        self.inner.group_session_manager.encrypt(room_id, event_type, content).await
1108    }
1109
1110    /// Encrypt a state event for the given room.
1111    ///
1112    /// # Arguments
1113    ///
1114    /// * `room_id` - The id of the room for which the event should be
1115    ///   encrypted.
1116    ///
1117    /// * `content` - The plaintext content of the event that should be
1118    ///   encrypted.
1119    ///
1120    /// * `state_key` - The associated state key of the event.
1121    #[cfg(feature = "experimental-encrypted-state-events")]
1122    pub async fn encrypt_state_event<C, K>(
1123        &self,
1124        room_id: &RoomId,
1125        content: C,
1126        state_key: K,
1127    ) -> MegolmResult<Raw<RoomEncryptedEventContent>>
1128    where
1129        C: StateEventContent,
1130        C::StateKey: Borrow<K>,
1131        K: AsRef<str>,
1132    {
1133        let event_type = content.event_type().to_string();
1134        let content = Raw::new(&content)?.cast_unchecked();
1135        self.encrypt_state_event_raw(room_id, &event_type, state_key.as_ref(), &content).await
1136    }
1137
1138    /// Encrypt a state event for the given state event using its raw JSON
1139    /// content and state key.
1140    ///
1141    /// This method is equivalent to [`OlmMachine::encrypt_state_event`]
1142    /// method but operates on an arbitrary JSON value instead of strongly-typed
1143    /// event content struct.
1144    ///
1145    /// # Arguments
1146    ///
1147    /// * `room_id` - The id of the room for which the message should be
1148    ///   encrypted.
1149    ///
1150    /// * `event_type` - The type of the event.
1151    ///
1152    /// * `state_key` - The associated state key of the event.
1153    ///
1154    /// * `content` - The plaintext content of the event that should be
1155    ///   encrypted as a raw JSON value.
1156    #[cfg(feature = "experimental-encrypted-state-events")]
1157    pub async fn encrypt_state_event_raw(
1158        &self,
1159        room_id: &RoomId,
1160        event_type: &str,
1161        state_key: &str,
1162        content: &Raw<AnyStateEventContent>,
1163    ) -> MegolmResult<Raw<RoomEncryptedEventContent>> {
1164        self.inner
1165            .group_session_manager
1166            .encrypt_state(room_id, event_type, state_key, content)
1167            .await
1168    }
1169
1170    /// Forces the currently active room key, which is used to encrypt messages,
1171    /// to be rotated.
1172    ///
1173    /// A new room key will be crated and shared with all the room members the
1174    /// next time a message will be sent. You don't have to call this method,
1175    /// room keys will be rotated automatically when necessary. This method is
1176    /// still useful for debugging purposes.
1177    ///
1178    /// Returns true if a session was invalidated, false if there was no session
1179    /// to invalidate.
1180    pub async fn discard_room_key(&self, room_id: &RoomId) -> StoreResult<bool> {
1181        self.inner.group_session_manager.invalidate_group_session(room_id).await
1182    }
1183
1184    /// Get to-device requests to share a room key with users in a room.
1185    ///
1186    /// # Arguments
1187    ///
1188    /// `room_id` - The room id of the room where the room key will be
1189    /// used.
1190    ///
1191    /// `users` - The list of users that should receive the room key.
1192    ///
1193    /// `settings` - Encryption settings that affect when are room keys rotated
1194    /// and who are they shared with.
1195    ///
1196    /// # Returns
1197    ///
1198    /// List of the to-device requests that need to be sent out to the server
1199    /// and the responses need to be passed back to the state machine with
1200    /// [`mark_request_as_sent`], using the to-device `txn_id` as `request_id`.
1201    ///
1202    /// [`mark_request_as_sent`]: #method.mark_request_as_sent
1203    pub async fn share_room_key(
1204        &self,
1205        room_id: &RoomId,
1206        users: impl Iterator<Item = &UserId>,
1207        encryption_settings: impl Into<EncryptionSettings>,
1208    ) -> OlmResult<Vec<Arc<ToDeviceRequest>>> {
1209        self.inner.group_session_manager.share_room_key(room_id, users, encryption_settings).await
1210    }
1211
1212    /// Encrypts the given content using Olm for each of the given devices.
1213    ///
1214    /// The 1-to-1 session must be established prior to this
1215    /// call by using the [`OlmMachine::get_missing_sessions`] method or the
1216    /// encryption will fail.
1217    ///
1218    /// The caller is responsible for sending the encrypted
1219    /// event to the target device, and should do it ASAP to avoid out-of-order
1220    /// messages.
1221    ///
1222    /// # Returns
1223    /// A list of `ToDeviceRequest` to send out the event, and the list of
1224    /// devices where encryption did not succeed (device excluded or no olm)
1225    #[cfg(feature = "experimental-send-custom-to-device")]
1226    pub async fn encrypt_content_for_devices(
1227        &self,
1228        devices: Vec<DeviceData>,
1229        event_type: &str,
1230        content: &Value,
1231        share_strategy: CollectStrategy,
1232    ) -> OlmResult<(Vec<ToDeviceRequest>, Vec<(DeviceData, WithheldCode)>)> {
1233        let mut changes = Changes::default();
1234
1235        let (allowed_devices, mut blocked_devices) =
1236            split_devices_for_share_strategy(&self.inner.store, devices, share_strategy).await?;
1237
1238        let result = self
1239            .inner
1240            .group_session_manager
1241            .encrypt_content_for_devices(allowed_devices, event_type, content.clone(), &mut changes)
1242            .await;
1243
1244        // Persist any changes we might have collected.
1245        if !changes.is_empty() {
1246            let session_count = changes.sessions.len();
1247
1248            self.inner.store.save_changes(changes).await?;
1249
1250            trace!(
1251                session_count = session_count,
1252                "Stored the changed sessions after encrypting a custom to-device event"
1253            );
1254        }
1255
1256        result.map(|(to_device_requests, mut withheld)| {
1257            withheld.append(&mut blocked_devices);
1258            (to_device_requests, withheld)
1259        })
1260    }
1261    /// Collect the devices belonging to the given user, and send the details of
1262    /// a room key bundle to those devices.
1263    ///
1264    /// Returns a list of to-device requests which must be sent.
1265    pub async fn share_room_key_bundle_data(
1266        &self,
1267        user_id: &UserId,
1268        collect_strategy: &CollectStrategy,
1269        bundle_data: RoomKeyBundleContent,
1270    ) -> OlmResult<Vec<ToDeviceRequest>> {
1271        self.inner
1272            .group_session_manager
1273            .share_room_key_bundle_data(user_id, collect_strategy, bundle_data)
1274            .await
1275    }
1276
1277    /// Receive an unencrypted verification event.
1278    ///
1279    /// This method can be used to pass verification events that are happening
1280    /// in unencrypted rooms to the `OlmMachine`.
1281    ///
1282    /// **Note**: This does not need to be called for encrypted events since
1283    /// those will get passed to the `OlmMachine` during decryption.
1284    #[deprecated(note = "Use OlmMachine::receive_verification_event instead", since = "0.7.0")]
1285    pub async fn receive_unencrypted_verification_event(
1286        &self,
1287        event: &AnyMessageLikeEvent,
1288    ) -> StoreResult<()> {
1289        self.inner.verification_machine.receive_any_event(event).await
1290    }
1291
1292    /// Receive a verification event.
1293    ///
1294    /// The event should be in the decrypted form.
1295    pub async fn receive_verification_event(&self, event: &AnyMessageLikeEvent) -> StoreResult<()> {
1296        self.inner.verification_machine.receive_any_event(event).await
1297    }
1298
1299    /// Receive and properly handle a decrypted to-device event.
1300    ///
1301    /// # Arguments
1302    ///
1303    /// * `decrypted` - The decrypted event and some associated metadata.
1304    #[instrument(
1305        skip_all,
1306        fields(
1307            sender_key = ?decrypted.result.sender_key,
1308            event_type = decrypted.result.event.event_type(),
1309        ),
1310    )]
1311    async fn handle_decrypted_to_device_event(
1312        &self,
1313        cache: &StoreCache,
1314        decrypted: &mut OlmDecryptionInfo,
1315        changes: &mut Changes,
1316    ) -> OlmResult<()> {
1317        debug!(
1318            sender_device_keys =
1319                ?decrypted.result.event.sender_device_keys().map(|k| (k.curve25519_key(), k.ed25519_key())).unwrap_or((None, None)),
1320            "Received a decrypted to-device event",
1321        );
1322
1323        match &*decrypted.result.event {
1324            AnyDecryptedOlmEvent::RoomKey(e) => {
1325                let session = self.add_room_key(decrypted.result.sender_key, e).await?;
1326                decrypted.inbound_group_session = session;
1327            }
1328            AnyDecryptedOlmEvent::ForwardedRoomKey(e) => {
1329                let session = self
1330                    .inner
1331                    .key_request_machine
1332                    .receive_forwarded_room_key(decrypted.result.sender_key, e)
1333                    .await?;
1334                decrypted.inbound_group_session = session;
1335            }
1336            AnyDecryptedOlmEvent::SecretSend(e) => {
1337                let name = self
1338                    .inner
1339                    .key_request_machine
1340                    .receive_secret_event(cache, decrypted.result.sender_key, e, changes)
1341                    .await?;
1342
1343                // Set the secret name so other consumers of the event know
1344                // what this event is about.
1345                if let Ok(ToDeviceEvents::SecretSend(mut e)) =
1346                    decrypted.result.raw_event.deserialize_as()
1347                {
1348                    e.content.secret_name = name;
1349                    decrypted.result.raw_event = Raw::from_json(to_raw_value(&e)?);
1350                }
1351            }
1352            AnyDecryptedOlmEvent::Dummy(_) => {
1353                debug!("Received an `m.dummy` event");
1354            }
1355            AnyDecryptedOlmEvent::RoomKeyBundle(e) => {
1356                debug!("Received a room key bundle event {:?}", e);
1357                self.receive_room_key_bundle_data(decrypted.result.sender_key, e, changes).await?;
1358            }
1359            AnyDecryptedOlmEvent::Custom(_) => {
1360                warn!("Received an unexpected encrypted to-device event");
1361            }
1362        }
1363
1364        Ok(())
1365    }
1366
1367    async fn handle_verification_event(&self, event: &ToDeviceEvents) {
1368        if let Err(e) = self.inner.verification_machine.receive_any_event(event).await {
1369            error!("Error handling a verification event: {e:?}");
1370        }
1371    }
1372
1373    /// Mark an outgoing to-device requests as sent.
1374    async fn mark_to_device_request_as_sent(&self, request_id: &TransactionId) -> StoreResult<()> {
1375        self.inner.verification_machine.mark_request_as_sent(request_id);
1376        self.inner.key_request_machine.mark_outgoing_request_as_sent(request_id).await?;
1377        self.inner.group_session_manager.mark_request_as_sent(request_id).await?;
1378        self.inner.session_manager.mark_outgoing_request_as_sent(request_id);
1379        Ok(())
1380    }
1381
1382    /// Get a verification object for the given user id with the given flow id.
1383    pub fn get_verification(&self, user_id: &UserId, flow_id: &str) -> Option<Verification> {
1384        self.inner.verification_machine.get_verification(user_id, flow_id)
1385    }
1386
1387    /// Get a verification request object with the given flow id.
1388    pub fn get_verification_request(
1389        &self,
1390        user_id: &UserId,
1391        flow_id: impl AsRef<str>,
1392    ) -> Option<VerificationRequest> {
1393        self.inner.verification_machine.get_request(user_id, flow_id)
1394    }
1395
1396    /// Get all the verification requests of a given user.
1397    pub fn get_verification_requests(&self, user_id: &UserId) -> Vec<VerificationRequest> {
1398        self.inner.verification_machine.get_requests(user_id)
1399    }
1400
1401    /// Given a to-device event that has either been decrypted or arrived in
1402    /// plaintext, handle it.
1403    ///
1404    /// Here, we only process events that are allowed to arrive in plaintext.
1405    async fn handle_to_device_event(&self, changes: &mut Changes, event: &ToDeviceEvents) {
1406        use crate::types::events::ToDeviceEvents::*;
1407
1408        match event {
1409            // These are handled here because we accept them either plaintext or
1410            // encrypted.
1411            //
1412            // Note: this list should match the allowed types in
1413            // check_to_device_is_from_verified_device_or_allowed_type
1414            RoomKeyRequest(e) => self.inner.key_request_machine.receive_incoming_key_request(e),
1415            SecretRequest(e) => self.inner.key_request_machine.receive_incoming_secret_request(e),
1416            RoomKeyWithheld(e) => self.add_withheld_info(changes, e),
1417            KeyVerificationAccept(..)
1418            | KeyVerificationCancel(..)
1419            | KeyVerificationKey(..)
1420            | KeyVerificationMac(..)
1421            | KeyVerificationRequest(..)
1422            | KeyVerificationReady(..)
1423            | KeyVerificationDone(..)
1424            | KeyVerificationStart(..) => {
1425                self.handle_verification_event(event).await;
1426            }
1427
1428            // We don't process custom or dummy events at all
1429            Custom(_) | Dummy(_) => {}
1430
1431            // Encrypted events are handled elsewhere
1432            RoomEncrypted(_) => {}
1433
1434            // These are handled in `handle_decrypted_to_device_event` because we
1435            // only accept them if they arrive encrypted.
1436            SecretSend(_) | RoomKey(_) | ForwardedRoomKey(_) => {}
1437        }
1438    }
1439
1440    fn record_message_id(event: &Raw<AnyToDeviceEvent>) {
1441        use serde::Deserialize;
1442
1443        #[derive(Deserialize)]
1444        struct ContentStub<'a> {
1445            #[serde(borrow, rename = "org.matrix.msgid")]
1446            message_id: Option<&'a str>,
1447        }
1448        #[derive(Deserialize)]
1449        struct ToDeviceStub<'a> {
1450            sender: &'a str,
1451            #[serde(rename = "type")]
1452            event_type: &'a str,
1453            #[serde(borrow)]
1454            content: ContentStub<'a>,
1455        }
1456
1457        if let Ok(event) = event.deserialize_as_unchecked::<ToDeviceStub<'_>>() {
1458            Span::current().record("sender", event.sender);
1459            Span::current().record("event_type", event.event_type);
1460            Span::current().record("message_id", event.content.message_id);
1461        }
1462    }
1463
1464    /// Decrypt the supplied to-device event (if needed, and if we can) and
1465    /// handle it.
1466    ///
1467    /// Return the same event, decrypted if possible and needed.
1468    ///
1469    /// If we can identify that this to-device event came from a dehydrated
1470    /// device, this method does not process it, and returns `None`.
1471    #[instrument(skip_all, fields(sender, event_type, message_id))]
1472    async fn receive_to_device_event(
1473        &self,
1474        transaction: &mut StoreTransaction,
1475        changes: &mut Changes,
1476        raw_event: Raw<AnyToDeviceEvent>,
1477        decryption_settings: &DecryptionSettings,
1478    ) -> Option<ProcessedToDeviceEvent> {
1479        Self::record_message_id(&raw_event);
1480
1481        let event: ToDeviceEvents = match raw_event.deserialize_as() {
1482            Ok(e) => e,
1483            Err(e) => {
1484                // Skip invalid events.
1485                warn!("Received an invalid to-device event: {e}");
1486                return Some(ProcessedToDeviceEvent::Invalid(raw_event));
1487            }
1488        };
1489
1490        debug!("Received a to-device event");
1491
1492        match event {
1493            ToDeviceEvents::RoomEncrypted(e) => {
1494                self.receive_encrypted_to_device_event(
1495                    transaction,
1496                    changes,
1497                    raw_event,
1498                    e,
1499                    decryption_settings,
1500                )
1501                .await
1502            }
1503            e => {
1504                self.handle_to_device_event(changes, &e).await;
1505                Some(ProcessedToDeviceEvent::PlainText(raw_event))
1506            }
1507        }
1508    }
1509
1510    /// Decrypt the supplied encrypted to-device event (if we can) and handle
1511    /// it.
1512    ///
1513    /// Return the same event, decrypted if possible.
1514    ///
1515    /// If we are in strict "exclude insecure devices" mode and the sender
1516    /// device is not verified, and the decrypted event type is not on the
1517    /// allow list, or if this event comes from a dehydrated device, this method
1518    /// does not process it, and returns `None`.
1519    ///
1520    /// (The allow list of types that are processed even if the sender is
1521    /// unverified is: `m.room_key`, `m.room_key.withheld`,
1522    /// `m.room_key_request`, `m.secret.request` and `m.key.verification.*`.)
1523    async fn receive_encrypted_to_device_event(
1524        &self,
1525        transaction: &mut StoreTransaction,
1526        changes: &mut Changes,
1527        mut raw_event: Raw<AnyToDeviceEvent>,
1528        e: ToDeviceEvent<ToDeviceEncryptedEventContent>,
1529        decryption_settings: &DecryptionSettings,
1530    ) -> Option<ProcessedToDeviceEvent> {
1531        let decrypted = match self
1532            .decrypt_to_device_event(transaction, &e, changes, decryption_settings)
1533            .await
1534        {
1535            Ok(decrypted) => decrypted,
1536            Err(DecryptToDeviceError::OlmError(err)) => {
1537                let reason = if let OlmError::UnverifiedSenderDevice = &err {
1538                    ToDeviceUnableToDecryptReason::UnverifiedSenderDevice
1539                } else {
1540                    ToDeviceUnableToDecryptReason::DecryptionFailure
1541                };
1542
1543                if let OlmError::SessionWedged(sender, curve_key) = err {
1544                    if let Err(e) =
1545                        self.inner.session_manager.mark_device_as_wedged(&sender, curve_key).await
1546                    {
1547                        error!(
1548                            error = ?e,
1549                            "Couldn't mark device to be unwedged",
1550                        );
1551                    }
1552                }
1553
1554                return Some(ProcessedToDeviceEvent::UnableToDecrypt {
1555                    encrypted_event: raw_event,
1556                    utd_info: ToDeviceUnableToDecryptInfo { reason },
1557                });
1558            }
1559            Err(DecryptToDeviceError::FromDehydratedDevice) => return None,
1560        };
1561
1562        // New sessions modify the account so we need to save that
1563        // one as well.
1564        match decrypted.session {
1565            SessionType::New(s) | SessionType::Existing(s) => {
1566                changes.sessions.push(s);
1567            }
1568        }
1569
1570        changes.message_hashes.push(decrypted.message_hash);
1571
1572        if let Some(group_session) = decrypted.inbound_group_session {
1573            changes.inbound_group_sessions.push(group_session);
1574        }
1575
1576        match decrypted.result.raw_event.deserialize_as() {
1577            Ok(event) => {
1578                self.handle_to_device_event(changes, &event).await;
1579
1580                raw_event = event
1581                    .serialize_zeroized()
1582                    .expect("Zeroizing and reserializing our events should always work")
1583                    .cast();
1584            }
1585            Err(e) => {
1586                warn!("Received an invalid encrypted to-device event: {e}");
1587                raw_event = decrypted.result.raw_event;
1588            }
1589        }
1590
1591        Some(ProcessedToDeviceEvent::Decrypted {
1592            raw: raw_event,
1593            encryption_info: decrypted.result.encryption_info,
1594        })
1595    }
1596
1597    /// Return an error if the supplied to-device event was sent from a
1598    /// dehydrated device.
1599    async fn check_to_device_event_is_not_from_dehydrated_device(
1600        &self,
1601        decrypted: &OlmDecryptionInfo,
1602        sender_user_id: &UserId,
1603    ) -> Result<(), DecryptToDeviceError> {
1604        if self.to_device_event_is_from_dehydrated_device(decrypted, sender_user_id).await? {
1605            warn!(
1606                sender = ?sender_user_id,
1607                session = ?decrypted.session,
1608                "Received a to-device event from a dehydrated device. This is unexpected: ignoring event"
1609            );
1610            Err(DecryptToDeviceError::FromDehydratedDevice)
1611        } else {
1612            Ok(())
1613        }
1614    }
1615
1616    /// Decide whether a decrypted to-device event was sent from a dehydrated
1617    /// device.
1618    ///
1619    /// This accepts an [`OlmDecryptionInfo`] because it deals with a decrypted
1620    /// event.
1621    async fn to_device_event_is_from_dehydrated_device(
1622        &self,
1623        decrypted: &OlmDecryptionInfo,
1624        sender_user_id: &UserId,
1625    ) -> OlmResult<bool> {
1626        // Does the to-device message include device info?
1627        if let Some(device_keys) = decrypted.result.event.sender_device_keys() {
1628            // There is no need to check whether the device keys are signed correctly - any
1629            // to-device message that claims to be from a dehydrated device is weird, so we
1630            // will drop it.
1631
1632            // Does the included device info say the device is dehydrated?
1633            if device_keys.dehydrated.unwrap_or(false) {
1634                return Ok(true);
1635            }
1636            // If not, fall through and check our existing list of devices
1637            // below, just in case the sender is sending us incorrect
1638            // information embedded in the to-device message, but we know
1639            // better.
1640        }
1641
1642        // Do we already know about this device?
1643        Ok(self
1644            .store()
1645            .get_device_from_curve_key(sender_user_id, decrypted.result.sender_key)
1646            .await?
1647            .is_some_and(|d| d.is_dehydrated()))
1648    }
1649
1650    /// Handle a to-device and one-time key counts from a sync response.
1651    ///
1652    /// This will decrypt and handle to-device events returning the decrypted
1653    /// versions of them.
1654    ///
1655    /// To decrypt an event from the room timeline, call [`decrypt_room_event`].
1656    ///
1657    /// # Arguments
1658    ///
1659    /// * `sync_changes` - an [`EncryptionSyncChanges`] value, constructed from
1660    ///   a sync response.
1661    ///
1662    /// [`decrypt_room_event`]: #method.decrypt_room_event
1663    ///
1664    /// # Returns
1665    ///
1666    /// A tuple of (decrypted to-device events, updated room keys).
1667    #[instrument(skip_all)]
1668    pub async fn receive_sync_changes(
1669        &self,
1670        sync_changes: EncryptionSyncChanges<'_>,
1671        decryption_settings: &DecryptionSettings,
1672    ) -> OlmResult<(Vec<ProcessedToDeviceEvent>, Vec<RoomKeyInfo>)> {
1673        let mut store_transaction = self.inner.store.transaction().await;
1674
1675        let (events, changes) = self
1676            .preprocess_sync_changes(&mut store_transaction, sync_changes, decryption_settings)
1677            .await?;
1678
1679        // Technically save_changes also does the same work, so if it's slow we could
1680        // refactor this to do it only once.
1681        let room_key_updates: Vec<_> =
1682            changes.inbound_group_sessions.iter().map(RoomKeyInfo::from).collect();
1683
1684        self.store().save_changes(changes).await?;
1685        store_transaction.commit().await?;
1686
1687        Ok((events, room_key_updates))
1688    }
1689
1690    /// Initial processing of the changes specified within a sync response.
1691    ///
1692    /// Returns the to-device events (decrypted where needed and where possible)
1693    /// and the processed set of changes.
1694    ///
1695    /// If any of the to-device events in the supplied changes were sent from
1696    /// dehydrated devices, these are not processed, and are omitted from
1697    /// the returned list, as per MSC3814.
1698    ///
1699    /// If we are in strict "exclude insecure devices" mode and the sender
1700    /// device of any event is not verified, and the decrypted event type is not
1701    /// on the allow list, these events are not processed and are omitted from
1702    /// the returned list.
1703    ///
1704    /// (The allow list of types that are processed even if the sender is
1705    /// unverified is: `m.room_key`, `m.room_key.withheld`,
1706    /// `m.room_key_request`, `m.secret.request` and `m.key.verification.*`.)
1707    pub(crate) async fn preprocess_sync_changes(
1708        &self,
1709        transaction: &mut StoreTransaction,
1710        sync_changes: EncryptionSyncChanges<'_>,
1711        decryption_settings: &DecryptionSettings,
1712    ) -> OlmResult<(Vec<ProcessedToDeviceEvent>, Changes)> {
1713        // Remove verification objects that have expired or are done.
1714        let mut events: Vec<ProcessedToDeviceEvent> = self
1715            .inner
1716            .verification_machine
1717            .garbage_collect()
1718            .iter()
1719            // These are `fake` to device events just serving as local echo
1720            // in order that our own client can react quickly to cancelled transaction.
1721            // Just use PlainText for that.
1722            .map(|e| ProcessedToDeviceEvent::PlainText(e.clone()))
1723            .collect();
1724        // The account is automatically saved by the store transaction created by the
1725        // caller.
1726        let mut changes = Default::default();
1727
1728        {
1729            let account = transaction.account().await?;
1730            account.update_key_counts(
1731                sync_changes.one_time_keys_counts,
1732                sync_changes.unused_fallback_keys,
1733            )
1734        }
1735
1736        if let Err(e) = self
1737            .inner
1738            .identity_manager
1739            .receive_device_changes(
1740                transaction.cache(),
1741                sync_changes.changed_devices.changed.iter().map(|u| u.as_ref()),
1742            )
1743            .await
1744        {
1745            error!(error = ?e, "Error marking a tracked user as changed");
1746        }
1747
1748        for raw_event in sync_changes.to_device_events {
1749            let processed_event = Box::pin(self.receive_to_device_event(
1750                transaction,
1751                &mut changes,
1752                raw_event,
1753                decryption_settings,
1754            ))
1755            .await;
1756
1757            if let Some(processed_event) = processed_event {
1758                events.push(processed_event);
1759            }
1760        }
1761
1762        let changed_sessions = self
1763            .inner
1764            .key_request_machine
1765            .collect_incoming_key_requests(transaction.cache())
1766            .await?;
1767
1768        changes.sessions.extend(changed_sessions);
1769        changes.next_batch_token = sync_changes.next_batch_token;
1770
1771        Ok((events, changes))
1772    }
1773
1774    /// Request a room key from our devices.
1775    ///
1776    /// This method will return a request cancellation and a new key request if
1777    /// the key was already requested, otherwise it will return just the key
1778    /// request.
1779    ///
1780    /// The request cancellation *must* be sent out before the request is sent
1781    /// out, otherwise devices will ignore the key request.
1782    ///
1783    /// # Arguments
1784    ///
1785    /// * `room_id` - The id of the room where the key is used in.
1786    ///
1787    /// * `sender_key` - The curve25519 key of the sender that owns the key.
1788    ///
1789    /// * `session_id` - The id that uniquely identifies the session.
1790    pub async fn request_room_key(
1791        &self,
1792        event: &Raw<EncryptedEvent>,
1793        room_id: &RoomId,
1794    ) -> MegolmResult<(Option<OutgoingRequest>, OutgoingRequest)> {
1795        let event = event.deserialize()?;
1796        self.inner.key_request_machine.request_key(room_id, &event).await
1797    }
1798
1799    /// Find whether an event decrypted via the supplied session is verified,
1800    /// and provide explanation of what is missing/wrong if not.
1801    ///
1802    /// Stores the updated [`SenderData`] for the session in the store
1803    /// if we find an updated value for it.
1804    ///
1805    /// # Arguments
1806    ///
1807    /// * `session` - The inbound Megolm session that was used to decrypt the
1808    ///   event.
1809    /// * `sender` - The `sender` of that event (as claimed by the envelope of
1810    ///   the event).
1811    async fn get_room_event_verification_state(
1812        &self,
1813        session: &InboundGroupSession,
1814        sender: &UserId,
1815    ) -> MegolmResult<(VerificationState, Option<OwnedDeviceId>)> {
1816        let sender_data = self.get_or_update_sender_data(session, sender).await?;
1817
1818        // If the user ID in the sender data doesn't match that in the event envelope,
1819        // this event is not from who it appears to be from.
1820        //
1821        // If `sender_data.user_id()` returns `None`, that means we don't have any
1822        // information about the owner of the session (i.e. we have
1823        // `SenderData::UnknownDevice`); in that case we fall through to the
1824        // logic in `sender_data_to_verification_state` which will pick an appropriate
1825        // `DeviceLinkProblem` for `VerificationLevel::None`.
1826        let (verification_state, device_id) = match sender_data.user_id() {
1827            Some(i) if i != sender => {
1828                (VerificationState::Unverified(VerificationLevel::MismatchedSender), None)
1829            }
1830
1831            Some(_) | None => {
1832                sender_data_to_verification_state(sender_data, session.has_been_imported())
1833            }
1834        };
1835
1836        Ok((verification_state, device_id))
1837    }
1838
1839    /// Get an up-to-date [`SenderData`] for the given session, suitable for
1840    /// determining if messages decrypted using that session are verified.
1841    ///
1842    /// Checks both the stored verification state of the session and a
1843    /// recalculated verification state based on our current knowledge, and
1844    /// returns the more trusted of the two.
1845    ///
1846    /// Stores the updated [`SenderData`] for the session in the store
1847    /// if we find an updated value for it.
1848    ///
1849    /// # Arguments
1850    ///
1851    /// * `session` - The Megolm session that was used to decrypt the event.
1852    /// * `sender` - The claimed sender of that event.
1853    async fn get_or_update_sender_data(
1854        &self,
1855        session: &InboundGroupSession,
1856        sender: &UserId,
1857    ) -> MegolmResult<SenderData> {
1858        let sender_data = if session.sender_data.should_recalculate() {
1859            // The session is not sure of the sender yet. Try to find a matching device
1860            // belonging to the claimed sender of the recently-received event.
1861            //
1862            // It's worth noting that this could in theory result in unintuitive changes,
1863            // like a session which initially appears to belong to Alice turning into a
1864            // session which belongs to Bob [1]. This could mean that a session initially
1865            // successfully decrypts events from Alice, but then stops decrypting those same
1866            // events once we get an update.
1867            //
1868            // That's ok though: if we get good evidence that the session belongs to Bob,
1869            // it's correct to update the session even if we previously had weak
1870            // evidence it belonged to Alice.
1871            //
1872            // [1] For example: maybe Alice and Bob both publish devices with the *same*
1873            // keys (presumably because they are colluding). Initially we think
1874            // the session belongs to Alice, but then we do a device lookup for
1875            // Bob, we find a matching device with a cross-signature, so prefer
1876            // that.
1877            let calculated_sender_data = SenderDataFinder::find_using_curve_key(
1878                self.store(),
1879                session.sender_key(),
1880                sender,
1881                session,
1882            )
1883            .await?;
1884
1885            // Is the newly-calculated sender data more trusted?
1886            if calculated_sender_data.compare_trust_level(&session.sender_data).is_gt() {
1887                // Yes - save it to the store
1888                let mut new_session = session.clone();
1889                new_session.sender_data = calculated_sender_data.clone();
1890                self.store().save_inbound_group_sessions(&[new_session]).await?;
1891
1892                // and use it now.
1893                calculated_sender_data
1894            } else {
1895                // No - use the existing data.
1896                session.sender_data.clone()
1897            }
1898        } else {
1899            session.sender_data.clone()
1900        };
1901
1902        Ok(sender_data)
1903    }
1904
1905    /// Request missing local secrets from our devices (cross signing private
1906    /// keys, megolm backup). This will ask the sdk to create outgoing
1907    /// request to get the missing secrets.
1908    ///
1909    /// The requests will be processed as soon as `outgoing_requests()` is
1910    /// called to process them.
1911    ///
1912    /// # Returns
1913    ///
1914    /// A bool result saying if actual secrets were missing and have been
1915    /// requested
1916    ///
1917    /// # Examples
1918    //
1919    /// ```
1920    /// # async {
1921    /// # use matrix_sdk_crypto::OlmMachine;
1922    /// # let machine: OlmMachine = unimplemented!();
1923    /// if machine.query_missing_secrets_from_other_sessions().await.unwrap() {
1924    ///     let to_send = machine.outgoing_requests().await.unwrap();
1925    ///     // send the to device requests
1926    /// };
1927    /// # anyhow::Ok(()) };
1928    /// ```
1929    pub async fn query_missing_secrets_from_other_sessions(&self) -> StoreResult<bool> {
1930        let identity = self.inner.user_identity.lock().await;
1931        let mut secrets = identity.get_missing_secrets().await;
1932
1933        if self.store().load_backup_keys().await?.decryption_key.is_none() {
1934            secrets.push(SecretName::RecoveryKey);
1935        }
1936
1937        if secrets.is_empty() {
1938            debug!("No missing requests to query");
1939            return Ok(false);
1940        }
1941
1942        let secret_requests = GossipMachine::request_missing_secrets(self.user_id(), secrets);
1943
1944        // Check if there are already in-flight requests for these secrets?
1945        let unsent_request = self.store().get_unsent_secret_requests().await?;
1946        let not_yet_requested = secret_requests
1947            .into_iter()
1948            .filter(|request| !unsent_request.iter().any(|unsent| unsent.info == request.info))
1949            .collect_vec();
1950
1951        if not_yet_requested.is_empty() {
1952            debug!("The missing secrets have already been requested");
1953            Ok(false)
1954        } else {
1955            debug!("Requesting missing secrets");
1956
1957            let changes = Changes { key_requests: not_yet_requested, ..Default::default() };
1958
1959            self.store().save_changes(changes).await?;
1960            Ok(true)
1961        }
1962    }
1963
1964    /// Get some metadata pertaining to a given group session.
1965    ///
1966    /// This includes the session owner's Matrix user ID, their device ID, info
1967    /// regarding the cryptographic algorithm and whether the session, and by
1968    /// extension the events decrypted by the session, are trusted.
1969    async fn get_encryption_info(
1970        &self,
1971        session: &InboundGroupSession,
1972        sender: &UserId,
1973    ) -> MegolmResult<Arc<EncryptionInfo>> {
1974        let (verification_state, device_id) =
1975            self.get_room_event_verification_state(session, sender).await?;
1976
1977        let sender = sender.to_owned();
1978
1979        Ok(Arc::new(EncryptionInfo {
1980            sender,
1981            sender_device: device_id,
1982            algorithm_info: AlgorithmInfo::MegolmV1AesSha2 {
1983                curve25519_key: session.sender_key().to_base64(),
1984                sender_claimed_keys: session
1985                    .signing_keys()
1986                    .iter()
1987                    .map(|(k, v)| (k.to_owned(), v.to_base64()))
1988                    .collect(),
1989                session_id: Some(session.session_id().to_owned()),
1990            },
1991            verification_state,
1992        }))
1993    }
1994
1995    async fn decrypt_megolm_events(
1996        &self,
1997        room_id: &RoomId,
1998        event: &EncryptedEvent,
1999        content: &SupportedEventEncryptionSchemes<'_>,
2000        decryption_settings: &DecryptionSettings,
2001    ) -> MegolmResult<(JsonObject, Arc<EncryptionInfo>)> {
2002        let session =
2003            self.get_inbound_group_session_or_error(room_id, content.session_id()).await?;
2004
2005        // This function is only ever called by decrypt_room_event, so
2006        // room_id, sender, algorithm and session_id are recorded already
2007        //
2008        // While we already record the sender key in some cases from the event, the
2009        // sender key in the event is deprecated, so let's record it now.
2010        Span::current().record("sender_key", debug(session.sender_key()));
2011
2012        let result = session.decrypt(event).await;
2013        match result {
2014            Ok((decrypted_event, _)) => {
2015                let encryption_info = self.get_encryption_info(&session, &event.sender).await?;
2016
2017                self.check_sender_trust_requirement(
2018                    &session,
2019                    &encryption_info,
2020                    &decryption_settings.sender_device_trust_requirement,
2021                )?;
2022
2023                Ok((decrypted_event, encryption_info))
2024            }
2025            Err(error) => Err(
2026                if let MegolmError::Decryption(DecryptionError::UnknownMessageIndex(_, _)) = error {
2027                    let withheld_code = self
2028                        .inner
2029                        .store
2030                        .get_withheld_info(room_id, content.session_id())
2031                        .await?
2032                        .map(|e| e.content.withheld_code());
2033
2034                    if withheld_code.is_some() {
2035                        // Partially withheld, report with a withheld code if we have one.
2036                        MegolmError::MissingRoomKey(withheld_code)
2037                    } else {
2038                        error
2039                    }
2040                } else {
2041                    error
2042                },
2043            ),
2044        }
2045    }
2046
2047    /// Check that a Megolm event satisfies the sender trust
2048    /// requirement from the decryption settings.
2049    ///
2050    /// If the requirement is not satisfied, returns
2051    /// [`MegolmError::SenderIdentityNotTrusted`].
2052    fn check_sender_trust_requirement(
2053        &self,
2054        session: &InboundGroupSession,
2055        encryption_info: &EncryptionInfo,
2056        trust_requirement: &TrustRequirement,
2057    ) -> MegolmResult<()> {
2058        trace!(
2059            verification_state = ?encryption_info.verification_state,
2060            ?trust_requirement, "check_sender_trust_requirement",
2061        );
2062
2063        // VerificationState::Verified is acceptable for all TrustRequirement levels, so
2064        // let's get that out of the way
2065        let verification_level = match &encryption_info.verification_state {
2066            VerificationState::Verified => return Ok(()),
2067            VerificationState::Unverified(verification_level) => verification_level,
2068        };
2069
2070        let ok = match trust_requirement {
2071            TrustRequirement::Untrusted => true,
2072
2073            TrustRequirement::CrossSignedOrLegacy => {
2074                // `VerificationLevel::UnsignedDevice` and `VerificationLevel::None` correspond
2075                // to `SenderData::DeviceInfo` and `SenderData::UnknownDevice`
2076                // respectively, and those cases may be acceptable if the reason
2077                // for the lack of data is that the sessions were established
2078                // before we started collecting SenderData.
2079                let legacy_session = match session.sender_data {
2080                    SenderData::DeviceInfo { legacy_session, .. } => legacy_session,
2081                    SenderData::UnknownDevice { legacy_session, .. } => legacy_session,
2082                    _ => false,
2083                };
2084
2085                // In the CrossSignedOrLegacy case the following rules apply:
2086                //
2087                // 1. Identities we have not yet verified can be decrypted regardless of the
2088                //    legacy state of the session.
2089                // 2. Devices that aren't signed by the owning identity of the device can only
2090                //    be decrypted if it's a legacy session.
2091                // 3. If we have no information about the device, we should only decrypt if it's
2092                //    a legacy session.
2093                // 4. Anything else, should throw an error.
2094                match (verification_level, legacy_session) {
2095                    // Case 1
2096                    (VerificationLevel::UnverifiedIdentity, _) => true,
2097
2098                    // Case 2
2099                    (VerificationLevel::UnsignedDevice, true) => true,
2100
2101                    // Case 3
2102                    (VerificationLevel::None(_), true) => true,
2103
2104                    // Case 4
2105                    (VerificationLevel::VerificationViolation, _)
2106                    | (VerificationLevel::MismatchedSender, _)
2107                    | (VerificationLevel::UnsignedDevice, false)
2108                    | (VerificationLevel::None(_), false) => false,
2109                }
2110            }
2111
2112            // If cross-signing of identities is required, the only acceptable unverified case
2113            // is when the identity is signed but not yet verified by us.
2114            TrustRequirement::CrossSigned => match verification_level {
2115                VerificationLevel::UnverifiedIdentity => true,
2116
2117                VerificationLevel::VerificationViolation
2118                | VerificationLevel::MismatchedSender
2119                | VerificationLevel::UnsignedDevice
2120                | VerificationLevel::None(_) => false,
2121            },
2122        };
2123
2124        if ok {
2125            Ok(())
2126        } else {
2127            Err(MegolmError::SenderIdentityNotTrusted(verification_level.clone()))
2128        }
2129    }
2130
2131    /// Attempt to retrieve an inbound group session from the store.
2132    ///
2133    /// If the session is not found, checks for withheld reports, and returns a
2134    /// [`MegolmError::MissingRoomKey`] error.
2135    async fn get_inbound_group_session_or_error(
2136        &self,
2137        room_id: &RoomId,
2138        session_id: &str,
2139    ) -> MegolmResult<InboundGroupSession> {
2140        match self.store().get_inbound_group_session(room_id, session_id).await? {
2141            Some(session) => Ok(session),
2142            None => {
2143                let withheld_code = self
2144                    .inner
2145                    .store
2146                    .get_withheld_info(room_id, session_id)
2147                    .await?
2148                    .map(|e| e.content.withheld_code());
2149                Err(MegolmError::MissingRoomKey(withheld_code))
2150            }
2151        }
2152    }
2153
2154    /// Attempt to decrypt an event from a room timeline, returning information
2155    /// on the failure if it fails.
2156    ///
2157    /// # Arguments
2158    ///
2159    /// * `event` - The event that should be decrypted.
2160    ///
2161    /// * `room_id` - The ID of the room where the event was sent to.
2162    ///
2163    /// # Returns
2164    ///
2165    /// The decrypted event, if it was successfully decrypted. Otherwise,
2166    /// information on the failure, unless the failure was due to an
2167    /// internal error, in which case, an `Err` result.
2168    pub async fn try_decrypt_room_event(
2169        &self,
2170        raw_event: &Raw<EncryptedEvent>,
2171        room_id: &RoomId,
2172        decryption_settings: &DecryptionSettings,
2173    ) -> Result<RoomEventDecryptionResult, CryptoStoreError> {
2174        match self.decrypt_room_event_inner(raw_event, room_id, true, decryption_settings).await {
2175            Ok(decrypted) => Ok(RoomEventDecryptionResult::Decrypted(decrypted)),
2176            Err(err) => Ok(RoomEventDecryptionResult::UnableToDecrypt(megolm_error_to_utd_info(
2177                raw_event, err,
2178            )?)),
2179        }
2180    }
2181
2182    /// Decrypt an event from a room timeline.
2183    ///
2184    /// # Arguments
2185    ///
2186    /// * `event` - The event that should be decrypted.
2187    ///
2188    /// * `room_id` - The ID of the room where the event was sent to.
2189    pub async fn decrypt_room_event(
2190        &self,
2191        event: &Raw<EncryptedEvent>,
2192        room_id: &RoomId,
2193        decryption_settings: &DecryptionSettings,
2194    ) -> MegolmResult<DecryptedRoomEvent> {
2195        self.decrypt_room_event_inner(event, room_id, true, decryption_settings).await
2196    }
2197
2198    #[instrument(name = "decrypt_room_event", skip_all, fields(?room_id, event_id, origin_server_ts, sender, algorithm, session_id, message_index, sender_key))]
2199    async fn decrypt_room_event_inner(
2200        &self,
2201        event: &Raw<EncryptedEvent>,
2202        room_id: &RoomId,
2203        decrypt_unsigned: bool,
2204        decryption_settings: &DecryptionSettings,
2205    ) -> MegolmResult<DecryptedRoomEvent> {
2206        let _timer = timer!(tracing::Level::TRACE, "_method");
2207
2208        let event = event.deserialize()?;
2209
2210        Span::current()
2211            .record("sender", debug(&event.sender))
2212            .record("event_id", debug(&event.event_id))
2213            .record(
2214                "origin_server_ts",
2215                timestamp_to_iso8601(event.origin_server_ts)
2216                    .unwrap_or_else(|| "<out of range>".to_owned()),
2217            )
2218            .record("algorithm", debug(event.content.algorithm()));
2219
2220        let content: SupportedEventEncryptionSchemes<'_> = match &event.content.scheme {
2221            RoomEventEncryptionScheme::MegolmV1AesSha2(c) => {
2222                Span::current().record("sender_key", debug(c.sender_key));
2223                c.into()
2224            }
2225            #[cfg(feature = "experimental-algorithms")]
2226            RoomEventEncryptionScheme::MegolmV2AesSha2(c) => c.into(),
2227            RoomEventEncryptionScheme::Unknown(_) => {
2228                warn!("Received an encrypted room event with an unsupported algorithm");
2229                return Err(EventError::UnsupportedAlgorithm.into());
2230            }
2231        };
2232
2233        Span::current().record("session_id", content.session_id());
2234        Span::current().record("message_index", content.message_index());
2235
2236        let result =
2237            self.decrypt_megolm_events(room_id, &event, &content, decryption_settings).await;
2238
2239        if let Err(e) = &result {
2240            #[cfg(feature = "automatic-room-key-forwarding")]
2241            match e {
2242                // Optimisation should we request if we received a withheld code?
2243                // Maybe for some code there is no point
2244                MegolmError::MissingRoomKey(_)
2245                | MegolmError::Decryption(DecryptionError::UnknownMessageIndex(_, _)) => {
2246                    self.inner
2247                        .key_request_machine
2248                        .create_outgoing_key_request(room_id, &event)
2249                        .await?;
2250                }
2251                _ => {}
2252            }
2253
2254            warn!("Failed to decrypt a room event: {e}");
2255        }
2256
2257        let (mut decrypted_event, encryption_info) = result?;
2258
2259        let mut unsigned_encryption_info = None;
2260        if decrypt_unsigned {
2261            // Try to decrypt encrypted unsigned events.
2262            unsigned_encryption_info = self
2263                .decrypt_unsigned_events(&mut decrypted_event, room_id, decryption_settings)
2264                .await;
2265        }
2266
2267        let decrypted_event =
2268            serde_json::from_value::<Raw<AnyTimelineEvent>>(decrypted_event.into())?;
2269
2270        #[cfg(feature = "experimental-encrypted-state-events")]
2271        self.verify_packed_state_key(&event, &decrypted_event)?;
2272
2273        Ok(DecryptedRoomEvent { event: decrypted_event, encryption_info, unsigned_encryption_info })
2274    }
2275
2276    /// If the passed event is a state event, verify its outer packed state key
2277    /// matches the inner state key once unpacked.
2278    ///
2279    /// * `original` - The original encrypted event received over the wire.
2280    /// * `decrypted` - The decrypted event.
2281    ///
2282    /// # Errors
2283    ///
2284    /// Returns an error if any of the following are true:
2285    ///
2286    /// * The original event's state key failed to unpack;
2287    /// * The decrypted event could not be deserialised;
2288    /// * The unpacked event type does not match the type of the decrypted
2289    ///   event;
2290    /// * The unpacked event state key does not match the state key of the
2291    ///   decrypted event.
2292    #[cfg(feature = "experimental-encrypted-state-events")]
2293    fn verify_packed_state_key(
2294        &self,
2295        original: &EncryptedEvent,
2296        decrypted: &Raw<AnyTimelineEvent>,
2297    ) -> MegolmResult<()> {
2298        use serde::Deserialize;
2299
2300        // Helper for deserializing.
2301        #[derive(Deserialize)]
2302        struct PayloadDeserializationHelper {
2303            state_key: Option<String>,
2304            #[serde(rename = "type")]
2305            event_type: String,
2306        }
2307
2308        // Deserialize the decrypted event.
2309        let PayloadDeserializationHelper {
2310            state_key: inner_state_key,
2311            event_type: inner_event_type,
2312        } = decrypted
2313            .deserialize_as_unchecked()
2314            .map_err(|_| MegolmError::StateKeyVerificationFailed)?;
2315
2316        // Ensure we have a state key on the outer event iff there is one in the inner.
2317        let (raw_state_key, inner_state_key) = match (&original.state_key, &inner_state_key) {
2318            (Some(raw_state_key), Some(inner_state_key)) => (raw_state_key, inner_state_key),
2319            (None, None) => return Ok(()),
2320            _ => return Err(MegolmError::StateKeyVerificationFailed),
2321        };
2322
2323        // Unpack event type and state key from the raw state key.
2324        let (outer_event_type, outer_state_key) =
2325            raw_state_key.split_once(":").ok_or(MegolmError::StateKeyVerificationFailed)?;
2326
2327        // Check event types match, discard if not.
2328        if outer_event_type != inner_event_type {
2329            return Err(MegolmError::StateKeyVerificationFailed);
2330        }
2331
2332        // Check state keys match, discard if not.
2333        if outer_state_key != inner_state_key {
2334            return Err(MegolmError::StateKeyVerificationFailed);
2335        }
2336        Ok(())
2337    }
2338
2339    /// Try to decrypt the events bundled in the `unsigned` object of the given
2340    /// event.
2341    ///
2342    /// # Arguments
2343    ///
2344    /// * `main_event` - The event that may contain bundled encrypted events in
2345    ///   its `unsigned` object.
2346    ///
2347    /// * `room_id` - The ID of the room where the event was sent to.
2348    async fn decrypt_unsigned_events(
2349        &self,
2350        main_event: &mut JsonObject,
2351        room_id: &RoomId,
2352        decryption_settings: &DecryptionSettings,
2353    ) -> Option<BTreeMap<UnsignedEventLocation, UnsignedDecryptionResult>> {
2354        let unsigned = main_event.get_mut("unsigned")?.as_object_mut()?;
2355        let mut unsigned_encryption_info: Option<
2356            BTreeMap<UnsignedEventLocation, UnsignedDecryptionResult>,
2357        > = None;
2358
2359        // Search for an encrypted event in `m.replace`, an edit.
2360        let location = UnsignedEventLocation::RelationsReplace;
2361        let replace = location.find_mut(unsigned);
2362        if let Some(decryption_result) =
2363            self.decrypt_unsigned_event(replace, room_id, decryption_settings).await
2364        {
2365            unsigned_encryption_info
2366                .get_or_insert_with(Default::default)
2367                .insert(location, decryption_result);
2368        }
2369
2370        // Search for an encrypted event in `latest_event` in `m.thread`, the
2371        // latest event of a thread.
2372        let location = UnsignedEventLocation::RelationsThreadLatestEvent;
2373        let thread_latest_event = location.find_mut(unsigned);
2374        if let Some(decryption_result) =
2375            self.decrypt_unsigned_event(thread_latest_event, room_id, decryption_settings).await
2376        {
2377            unsigned_encryption_info
2378                .get_or_insert_with(Default::default)
2379                .insert(location, decryption_result);
2380        }
2381
2382        unsigned_encryption_info
2383    }
2384
2385    /// Try to decrypt the given bundled event.
2386    ///
2387    /// # Arguments
2388    ///
2389    /// * `event` - The bundled event that may be encrypted
2390    ///
2391    /// * `room_id` - The ID of the room where the event was sent to.
2392    fn decrypt_unsigned_event<'a>(
2393        &'a self,
2394        event: Option<&'a mut Value>,
2395        room_id: &'a RoomId,
2396        decryption_settings: &'a DecryptionSettings,
2397    ) -> BoxFuture<'a, Option<UnsignedDecryptionResult>> {
2398        Box::pin(async move {
2399            let event = event?;
2400
2401            let is_encrypted = event
2402                .get("type")
2403                .and_then(|type_| type_.as_str())
2404                .is_some_and(|s| s == "m.room.encrypted");
2405            if !is_encrypted {
2406                return None;
2407            }
2408
2409            let raw_event = serde_json::from_value(event.clone()).ok()?;
2410            match self
2411                .decrypt_room_event_inner(&raw_event, room_id, false, decryption_settings)
2412                .await
2413            {
2414                Ok(decrypted_event) => {
2415                    // Replace the encrypted event.
2416                    *event = serde_json::to_value(decrypted_event.event).ok()?;
2417                    Some(UnsignedDecryptionResult::Decrypted(decrypted_event.encryption_info))
2418                }
2419                Err(err) => {
2420                    // For now, we throw away crypto store errors and just treat the unsigned event
2421                    // as unencrypted. Crypto store errors represent problems with the application
2422                    // rather than normal UTD errors, so they should probably be propagated
2423                    // rather than swallowed.
2424                    let utd_info = megolm_error_to_utd_info(&raw_event, err).ok()?;
2425                    Some(UnsignedDecryptionResult::UnableToDecrypt(utd_info))
2426                }
2427            }
2428        })
2429    }
2430
2431    /// Check if we have the room key for the given event in the store.
2432    ///
2433    /// # Arguments
2434    ///
2435    /// * `event` - The event to get information for.
2436    /// * `room_id` - The ID of the room where the event was sent to.
2437    pub async fn is_room_key_available(
2438        &self,
2439        event: &Raw<EncryptedEvent>,
2440        room_id: &RoomId,
2441    ) -> Result<bool, CryptoStoreError> {
2442        let event = event.deserialize()?;
2443
2444        let (session_id, message_index) = match &event.content.scheme {
2445            RoomEventEncryptionScheme::MegolmV1AesSha2(c) => {
2446                (&c.session_id, c.ciphertext.message_index())
2447            }
2448            #[cfg(feature = "experimental-algorithms")]
2449            RoomEventEncryptionScheme::MegolmV2AesSha2(c) => {
2450                (&c.session_id, c.ciphertext.message_index())
2451            }
2452            RoomEventEncryptionScheme::Unknown(_) => {
2453                // We don't support this encryption algorithm, so clearly don't have its key.
2454                return Ok(false);
2455            }
2456        };
2457
2458        // Check that we have the session in the store, and that its first known index
2459        // predates the index of our message.
2460        Ok(self
2461            .store()
2462            .get_inbound_group_session(room_id, session_id)
2463            .await?
2464            .filter(|s| s.first_known_index() <= message_index)
2465            .is_some())
2466    }
2467
2468    /// Get encryption info for a decrypted timeline event.
2469    ///
2470    /// This recalculates the [`EncryptionInfo`] data that is returned by
2471    /// [`OlmMachine::decrypt_room_event`], based on the current
2472    /// verification status of the sender, etc.
2473    ///
2474    /// Returns an error for an unencrypted event.
2475    ///
2476    /// # Arguments
2477    ///
2478    /// * `event` - The event to get information for.
2479    /// * `room_id` - The ID of the room where the event was sent to.
2480    #[instrument(skip(self, event), fields(event_id, sender, session_id))]
2481    pub async fn get_room_event_encryption_info(
2482        &self,
2483        event: &Raw<EncryptedEvent>,
2484        room_id: &RoomId,
2485    ) -> MegolmResult<Arc<EncryptionInfo>> {
2486        let event = event.deserialize()?;
2487
2488        let content: SupportedEventEncryptionSchemes<'_> = match &event.content.scheme {
2489            RoomEventEncryptionScheme::MegolmV1AesSha2(c) => c.into(),
2490            #[cfg(feature = "experimental-algorithms")]
2491            RoomEventEncryptionScheme::MegolmV2AesSha2(c) => c.into(),
2492            RoomEventEncryptionScheme::Unknown(_) => {
2493                return Err(EventError::UnsupportedAlgorithm.into());
2494            }
2495        };
2496
2497        Span::current()
2498            .record("sender", debug(&event.sender))
2499            .record("event_id", debug(&event.event_id))
2500            .record("session_id", content.session_id());
2501
2502        self.get_session_encryption_info(room_id, content.session_id(), &event.sender).await
2503    }
2504
2505    /// Get encryption info for an event decrypted with a megolm session.
2506    ///
2507    /// This recalculates the [`EncryptionInfo`] data that is returned by
2508    /// [`OlmMachine::decrypt_room_event`], based on the current
2509    /// verification status of the sender, etc.
2510    ///
2511    /// Returns an error if the session can't be found.
2512    ///
2513    /// # Arguments
2514    ///
2515    /// * `room_id` - The ID of the room where the session is being used.
2516    /// * `session_id` - The ID of the session to get information for.
2517    /// * `sender` - The (claimed) sender of the event where the session was
2518    ///   used.
2519    pub async fn get_session_encryption_info(
2520        &self,
2521        room_id: &RoomId,
2522        session_id: &str,
2523        sender: &UserId,
2524    ) -> MegolmResult<Arc<EncryptionInfo>> {
2525        let session = self.get_inbound_group_session_or_error(room_id, session_id).await?;
2526        self.get_encryption_info(&session, sender).await
2527    }
2528
2529    /// Update the list of tracked users.
2530    ///
2531    /// The OlmMachine maintains a list of users whose devices we are keeping
2532    /// track of: these are known as "tracked users". These must be users
2533    /// that we share a room with, so that the server sends us updates for
2534    /// their device lists.
2535    ///
2536    /// # Arguments
2537    ///
2538    /// * `users` - An iterator over user ids that should be added to the list
2539    ///   of tracked users
2540    ///
2541    /// Any users that hadn't been seen before will be flagged for a key query
2542    /// immediately, and whenever [`OlmMachine::receive_sync_changes()`]
2543    /// receives a "changed" notification for that user in the future.
2544    ///
2545    /// Users that were already in the list are unaffected.
2546    pub async fn update_tracked_users(
2547        &self,
2548        users: impl IntoIterator<Item = &UserId>,
2549    ) -> StoreResult<()> {
2550        self.inner.identity_manager.update_tracked_users(users).await
2551    }
2552
2553    /// Mark all tracked users as dirty.
2554    ///
2555    /// All users *whose device lists we are tracking* are flagged as needing a
2556    /// key query. Users whose devices we are not tracking are ignored.
2557    pub async fn mark_all_tracked_users_as_dirty(&self) -> StoreResult<()> {
2558        self.inner
2559            .identity_manager
2560            .mark_all_tracked_users_as_dirty(self.inner.store.cache().await?)
2561            .await
2562    }
2563
2564    async fn wait_if_user_pending(
2565        &self,
2566        user_id: &UserId,
2567        timeout: Option<Duration>,
2568    ) -> StoreResult<()> {
2569        if let Some(timeout) = timeout {
2570            let cache = self.store().cache().await?;
2571            self.inner
2572                .identity_manager
2573                .key_query_manager
2574                .wait_if_user_key_query_pending(cache, timeout, user_id)
2575                .await?;
2576        }
2577        Ok(())
2578    }
2579
2580    /// Get a specific device of a user.
2581    ///
2582    /// # Arguments
2583    ///
2584    /// * `user_id` - The unique id of the user that the device belongs to.
2585    ///
2586    /// * `device_id` - The unique id of the device.
2587    ///
2588    /// * `timeout` - The amount of time we should wait before returning if the
2589    /// user's device list has been marked as stale. **Note**, this assumes that
2590    /// the requests from [`OlmMachine::outgoing_requests`] are being
2591    /// processed and sent out.
2592    ///
2593    /// Returns a `Device` if one is found and the crypto store didn't throw an
2594    /// error.
2595    ///
2596    /// # Examples
2597    ///
2598    /// ```
2599    /// # use matrix_sdk_crypto::OlmMachine;
2600    /// # use ruma::{device_id, user_id};
2601    /// # let alice = user_id!("@alice:example.org").to_owned();
2602    /// # futures_executor::block_on(async {
2603    /// # let machine = OlmMachine::new(&alice, device_id!("DEVICEID")).await;
2604    /// let device = machine.get_device(&alice, device_id!("DEVICEID"), None).await;
2605    ///
2606    /// println!("{:?}", device);
2607    /// # });
2608    /// ```
2609    #[instrument(skip(self))]
2610    pub async fn get_device(
2611        &self,
2612        user_id: &UserId,
2613        device_id: &DeviceId,
2614        timeout: Option<Duration>,
2615    ) -> StoreResult<Option<Device>> {
2616        self.wait_if_user_pending(user_id, timeout).await?;
2617        self.store().get_device(user_id, device_id).await
2618    }
2619
2620    /// Get the cross signing user identity of a user.
2621    ///
2622    /// # Arguments
2623    ///
2624    /// * `user_id` - The unique id of the user that the identity belongs to
2625    ///
2626    /// * `timeout` - The amount of time we should wait before returning if the
2627    /// user's device list has been marked as stale. **Note**, this assumes that
2628    /// the requests from [`OlmMachine::outgoing_requests`] are being
2629    /// processed and sent out.
2630    ///
2631    /// Returns a [`UserIdentity`] enum if one is found and the crypto store
2632    /// didn't throw an error.
2633    #[instrument(skip(self))]
2634    pub async fn get_identity(
2635        &self,
2636        user_id: &UserId,
2637        timeout: Option<Duration>,
2638    ) -> StoreResult<Option<UserIdentity>> {
2639        self.wait_if_user_pending(user_id, timeout).await?;
2640        self.store().get_identity(user_id).await
2641    }
2642
2643    /// Get a map holding all the devices of an user.
2644    ///
2645    /// # Arguments
2646    ///
2647    /// * `user_id` - The unique id of the user that the devices belong to.
2648    ///
2649    /// * `timeout` - The amount of time we should wait before returning if the
2650    /// user's device list has been marked as stale. **Note**, this assumes that
2651    /// the requests from [`OlmMachine::outgoing_requests`] are being
2652    /// processed and sent out.
2653    ///
2654    /// # Examples
2655    ///
2656    /// ```
2657    /// # use matrix_sdk_crypto::OlmMachine;
2658    /// # use ruma::{device_id, user_id};
2659    /// # let alice = user_id!("@alice:example.org").to_owned();
2660    /// # futures_executor::block_on(async {
2661    /// # let machine = OlmMachine::new(&alice, device_id!("DEVICEID")).await;
2662    /// let devices = machine.get_user_devices(&alice, None).await.unwrap();
2663    ///
2664    /// for device in devices.devices() {
2665    ///     println!("{:?}", device);
2666    /// }
2667    /// # });
2668    /// ```
2669    #[instrument(skip(self))]
2670    pub async fn get_user_devices(
2671        &self,
2672        user_id: &UserId,
2673        timeout: Option<Duration>,
2674    ) -> StoreResult<UserDevices> {
2675        self.wait_if_user_pending(user_id, timeout).await?;
2676        self.store().get_user_devices(user_id).await
2677    }
2678
2679    /// Get the status of the private cross signing keys.
2680    ///
2681    /// This can be used to check which private cross signing keys we have
2682    /// stored locally.
2683    pub async fn cross_signing_status(&self) -> CrossSigningStatus {
2684        self.inner.user_identity.lock().await.status().await
2685    }
2686
2687    /// Export all the private cross signing keys we have.
2688    ///
2689    /// The export will contain the seed for the ed25519 keys as a unpadded
2690    /// base64 encoded string.
2691    ///
2692    /// This method returns `None` if we don't have any private cross signing
2693    /// keys.
2694    pub async fn export_cross_signing_keys(&self) -> StoreResult<Option<CrossSigningKeyExport>> {
2695        let master_key = self.store().export_secret(&SecretName::CrossSigningMasterKey).await?;
2696        let self_signing_key =
2697            self.store().export_secret(&SecretName::CrossSigningSelfSigningKey).await?;
2698        let user_signing_key =
2699            self.store().export_secret(&SecretName::CrossSigningUserSigningKey).await?;
2700
2701        Ok(if master_key.is_none() && self_signing_key.is_none() && user_signing_key.is_none() {
2702            None
2703        } else {
2704            Some(CrossSigningKeyExport { master_key, self_signing_key, user_signing_key })
2705        })
2706    }
2707
2708    /// Import our private cross signing keys.
2709    ///
2710    /// The export needs to contain the seed for the ed25519 keys as an unpadded
2711    /// base64 encoded string.
2712    pub async fn import_cross_signing_keys(
2713        &self,
2714        export: CrossSigningKeyExport,
2715    ) -> Result<CrossSigningStatus, SecretImportError> {
2716        self.store().import_cross_signing_keys(export).await
2717    }
2718
2719    async fn sign_with_master_key(
2720        &self,
2721        message: &str,
2722    ) -> Result<(OwnedDeviceKeyId, Ed25519Signature), SignatureError> {
2723        let identity = &*self.inner.user_identity.lock().await;
2724        let key_id = identity.master_key_id().await.ok_or(SignatureError::MissingSigningKey)?;
2725
2726        let signature = identity.sign(message).await?;
2727
2728        Ok((key_id, signature))
2729    }
2730
2731    /// Sign the given message using our device key and if available cross
2732    /// signing master key.
2733    ///
2734    /// Presently, this should only be used for signing the server-side room
2735    /// key backups.
2736    pub async fn sign(&self, message: &str) -> Result<Signatures, CryptoStoreError> {
2737        let mut signatures = Signatures::new();
2738
2739        {
2740            let cache = self.inner.store.cache().await?;
2741            let account = cache.account().await?;
2742            let key_id = account.signing_key_id();
2743            let signature = account.sign(message);
2744            signatures.add_signature(self.user_id().to_owned(), key_id, signature);
2745        }
2746
2747        match self.sign_with_master_key(message).await {
2748            Ok((key_id, signature)) => {
2749                signatures.add_signature(self.user_id().to_owned(), key_id, signature);
2750            }
2751            Err(e) => {
2752                warn!(error = ?e, "Couldn't sign the message using the cross signing master key")
2753            }
2754        }
2755
2756        Ok(signatures)
2757    }
2758
2759    /// Get a reference to the backup related state machine.
2760    ///
2761    /// This state machine can be used to incrementally backup all room keys to
2762    /// the server.
2763    pub fn backup_machine(&self) -> &BackupMachine {
2764        &self.inner.backup_machine
2765    }
2766
2767    /// Syncs the database and in-memory generation counter.
2768    ///
2769    /// This requires that the crypto store lock has been acquired already.
2770    pub async fn initialize_crypto_store_generation(
2771        &self,
2772        generation: &Mutex<Option<u64>>,
2773    ) -> StoreResult<()> {
2774        // Avoid reentrant initialization by taking the lock for the entire's function
2775        // scope.
2776        let mut gen_guard = generation.lock().await;
2777
2778        let prev_generation =
2779            self.inner.store.get_custom_value(Self::CURRENT_GENERATION_STORE_KEY).await?;
2780
2781        let gen = match prev_generation {
2782            Some(val) => {
2783                // There was a value in the store. We need to signal that we're a different
2784                // process, so we don't just reuse the value but increment it.
2785                u64::from_le_bytes(val.try_into().map_err(|_| {
2786                    CryptoStoreError::InvalidLockGeneration("invalid format".to_owned())
2787                })?)
2788                .wrapping_add(1)
2789            }
2790            None => 0,
2791        };
2792
2793        tracing::debug!("Initialising crypto store generation at {}", gen);
2794
2795        self.inner
2796            .store
2797            .set_custom_value(Self::CURRENT_GENERATION_STORE_KEY, gen.to_le_bytes().to_vec())
2798            .await?;
2799
2800        *gen_guard = Some(gen);
2801
2802        Ok(())
2803    }
2804
2805    /// If needs be, update the local and on-disk crypto store generation.
2806    ///
2807    /// ## Requirements
2808    ///
2809    /// - This assumes that `initialize_crypto_store_generation` has been called
2810    ///   beforehand.
2811    /// - This requires that the crypto store lock has been acquired.
2812    ///
2813    /// # Arguments
2814    ///
2815    /// * `generation` - The in-memory generation counter (or rather, the
2816    ///   `Mutex` wrapping it). This defines the "expected" generation on entry,
2817    ///   and, if we determine an update is needed, is updated to hold the "new"
2818    ///   generation.
2819    ///
2820    /// # Returns
2821    ///
2822    /// A tuple containing:
2823    ///
2824    /// * A `bool`, set to `true` if another process has updated the generation
2825    ///   number in the `Store` since our expected value, and as such we've
2826    ///   incremented and updated it in the database. Otherwise, `false`.
2827    ///
2828    /// * The (possibly updated) generation counter.
2829    pub async fn maintain_crypto_store_generation(
2830        &'_ self,
2831        generation: &Mutex<Option<u64>>,
2832    ) -> StoreResult<(bool, u64)> {
2833        let mut gen_guard = generation.lock().await;
2834
2835        // The database value must be there:
2836        // - either we could initialize beforehand, thus write into the database,
2837        // - or we couldn't, and then another process was holding onto the database's
2838        //   lock, thus
2839        // has written a generation counter in there.
2840        let actual_gen = self
2841            .inner
2842            .store
2843            .get_custom_value(Self::CURRENT_GENERATION_STORE_KEY)
2844            .await?
2845            .ok_or_else(|| {
2846                CryptoStoreError::InvalidLockGeneration("counter missing in store".to_owned())
2847            })?;
2848
2849        let actual_gen =
2850            u64::from_le_bytes(actual_gen.try_into().map_err(|_| {
2851                CryptoStoreError::InvalidLockGeneration("invalid format".to_owned())
2852            })?);
2853
2854        let new_gen = match gen_guard.as_ref() {
2855            Some(expected_gen) => {
2856                if actual_gen == *expected_gen {
2857                    return Ok((false, actual_gen));
2858                }
2859                // Increment the biggest, and store it everywhere.
2860                actual_gen.max(*expected_gen).wrapping_add(1)
2861            }
2862            None => {
2863                // Some other process hold onto the lock when initializing, so we must reload.
2864                // Increment database value, and store it everywhere.
2865                actual_gen.wrapping_add(1)
2866            }
2867        };
2868
2869        tracing::debug!(
2870            "Crypto store generation mismatch: previously known was {:?}, actual is {:?}, next is {}",
2871            *gen_guard,
2872            actual_gen,
2873            new_gen
2874        );
2875
2876        // Update known value.
2877        *gen_guard = Some(new_gen);
2878
2879        // Update value in database.
2880        self.inner
2881            .store
2882            .set_custom_value(Self::CURRENT_GENERATION_STORE_KEY, new_gen.to_le_bytes().to_vec())
2883            .await?;
2884
2885        Ok((true, new_gen))
2886    }
2887
2888    /// Manage dehydrated devices.
2889    pub fn dehydrated_devices(&self) -> DehydratedDevices {
2890        DehydratedDevices { inner: self.to_owned() }
2891    }
2892
2893    /// Get the stored encryption settings for the given room, such as the
2894    /// encryption algorithm or whether to encrypt only for trusted devices.
2895    ///
2896    /// These settings can be modified via [`OlmMachine::set_room_settings`].
2897    pub async fn room_settings(&self, room_id: &RoomId) -> StoreResult<Option<RoomSettings>> {
2898        // There's not much to do here: it's just exposed for symmetry with
2899        // `set_room_settings`.
2900        self.inner.store.get_room_settings(room_id).await
2901    }
2902
2903    /// Store encryption settings for the given room.
2904    ///
2905    /// This method checks if the new settings are "safe" -- ie, that they do
2906    /// not represent a downgrade in encryption security from any previous
2907    /// settings. Attempts to downgrade security will result in a
2908    /// [`SetRoomSettingsError::EncryptionDowngrade`].
2909    ///
2910    /// If the settings are valid, they will be persisted to the crypto store.
2911    /// These settings are not used directly by this library, but the saved
2912    /// settings can be retrieved via [`OlmMachine::room_settings`].
2913    pub async fn set_room_settings(
2914        &self,
2915        room_id: &RoomId,
2916        new_settings: &RoomSettings,
2917    ) -> Result<(), SetRoomSettingsError> {
2918        let store = &self.inner.store;
2919
2920        // We want to make sure that we do not race against a second concurrent call to
2921        // `set_room_settings`. By way of an easy way to do so, we start a
2922        // StoreTransaction. There's no need to commit() it: we're just using it as a
2923        // lock guard.
2924        let _store_transaction = store.transaction().await;
2925
2926        let old_settings = store.get_room_settings(room_id).await?;
2927
2928        // We want to make sure that the change to the room settings does not represent
2929        // a downgrade in security. The [E2EE implementation guide] recommends:
2930        //
2931        //  > This flag should **not** be cleared if a later `m.room.encryption` event
2932        //  > changes the configuration.
2933        //
2934        // (However, it doesn't really address how to handle changes to the rotation
2935        // parameters, etc.) For now at least, we are very conservative here:
2936        // any new settings are rejected if they differ from the existing settings.
2937        // merit improvement (cf https://github.com/element-hq/element-meta/issues/69).
2938        //
2939        // [E2EE implementation guide]: https://matrix.org/docs/matrix-concepts/end-to-end-encryption/#handling-an-m-room-encryption-state-event
2940        if let Some(old_settings) = old_settings {
2941            if old_settings != *new_settings {
2942                return Err(SetRoomSettingsError::EncryptionDowngrade);
2943            } else {
2944                // nothing to do here
2945                return Ok(());
2946            }
2947        }
2948
2949        // Make sure that the new settings are valid
2950        match new_settings.algorithm {
2951            EventEncryptionAlgorithm::MegolmV1AesSha2 => (),
2952
2953            #[cfg(feature = "experimental-algorithms")]
2954            EventEncryptionAlgorithm::MegolmV2AesSha2 => (),
2955
2956            _ => {
2957                warn!(
2958                    ?room_id,
2959                    "Rejecting invalid encryption algorithm {}", new_settings.algorithm
2960                );
2961                return Err(SetRoomSettingsError::InvalidSettings);
2962            }
2963        }
2964
2965        // The new settings are acceptable, so let's save them.
2966        store
2967            .save_changes(Changes {
2968                room_settings: HashMap::from([(room_id.to_owned(), new_settings.clone())]),
2969                ..Default::default()
2970            })
2971            .await?;
2972
2973        Ok(())
2974    }
2975
2976    /// Returns whether this `OlmMachine` is the same another one.
2977    ///
2978    /// Useful for testing purposes only.
2979    #[cfg(any(feature = "testing", test))]
2980    pub fn same_as(&self, other: &OlmMachine) -> bool {
2981        Arc::ptr_eq(&self.inner, &other.inner)
2982    }
2983
2984    /// Testing purposes only.
2985    #[cfg(any(feature = "testing", test))]
2986    pub async fn uploaded_key_count(&self) -> Result<u64, CryptoStoreError> {
2987        let cache = self.inner.store.cache().await?;
2988        let account = cache.account().await?;
2989        Ok(account.uploaded_key_count())
2990    }
2991
2992    /// Returns the identity manager.
2993    #[cfg(test)]
2994    pub(crate) fn identity_manager(&self) -> &IdentityManager {
2995        &self.inner.identity_manager
2996    }
2997
2998    /// Returns a store key, only useful for testing purposes.
2999    #[cfg(test)]
3000    pub(crate) fn key_for_has_migrated_verification_latch() -> &'static str {
3001        Self::HAS_MIGRATED_VERIFICATION_LATCH
3002    }
3003}
3004
3005fn sender_data_to_verification_state(
3006    sender_data: SenderData,
3007    session_has_been_imported: bool,
3008) -> (VerificationState, Option<OwnedDeviceId>) {
3009    match sender_data {
3010        SenderData::UnknownDevice { owner_check_failed: false, .. } => {
3011            let device_link_problem = if session_has_been_imported {
3012                DeviceLinkProblem::InsecureSource
3013            } else {
3014                DeviceLinkProblem::MissingDevice
3015            };
3016
3017            (VerificationState::Unverified(VerificationLevel::None(device_link_problem)), None)
3018        }
3019        SenderData::UnknownDevice { owner_check_failed: true, .. } => (
3020            VerificationState::Unverified(VerificationLevel::None(
3021                DeviceLinkProblem::InsecureSource,
3022            )),
3023            None,
3024        ),
3025        SenderData::DeviceInfo { device_keys, .. } => (
3026            VerificationState::Unverified(VerificationLevel::UnsignedDevice),
3027            Some(device_keys.device_id),
3028        ),
3029        SenderData::VerificationViolation(KnownSenderData { device_id, .. }) => {
3030            (VerificationState::Unverified(VerificationLevel::VerificationViolation), device_id)
3031        }
3032        SenderData::SenderUnverified(KnownSenderData { device_id, .. }) => {
3033            (VerificationState::Unverified(VerificationLevel::UnverifiedIdentity), device_id)
3034        }
3035        SenderData::SenderVerified(KnownSenderData { device_id, .. }) => {
3036            (VerificationState::Verified, device_id)
3037        }
3038    }
3039}
3040
3041/// A set of requests to be executed when bootstrapping cross-signing using
3042/// [`OlmMachine::bootstrap_cross_signing`].
3043#[derive(Debug, Clone)]
3044pub struct CrossSigningBootstrapRequests {
3045    /// An optional request to upload a device key.
3046    ///
3047    /// Should be sent first, if present.
3048    ///
3049    /// If present, its result must be processed back with
3050    /// `OlmMachine::mark_request_as_sent`.
3051    pub upload_keys_req: Option<OutgoingRequest>,
3052
3053    /// Request to upload the cross-signing keys.
3054    ///
3055    /// Should be sent second.
3056    pub upload_signing_keys_req: UploadSigningKeysRequest,
3057
3058    /// Request to upload key signatures, including those for the cross-signing
3059    /// keys, and maybe some for the optional uploaded key too.
3060    ///
3061    /// Should be sent last.
3062    pub upload_signatures_req: UploadSignaturesRequest,
3063}
3064
3065/// Data contained from a sync response and that needs to be processed by the
3066/// OlmMachine.
3067#[derive(Debug)]
3068pub struct EncryptionSyncChanges<'a> {
3069    /// The list of to-device events received in the sync.
3070    pub to_device_events: Vec<Raw<AnyToDeviceEvent>>,
3071    /// The mapping of changed and left devices, per user, as returned in the
3072    /// sync response.
3073    pub changed_devices: &'a DeviceLists,
3074    /// The number of one time keys, as returned in the sync response.
3075    pub one_time_keys_counts: &'a BTreeMap<OneTimeKeyAlgorithm, UInt>,
3076    /// An optional list of fallback keys.
3077    pub unused_fallback_keys: Option<&'a [OneTimeKeyAlgorithm]>,
3078    /// A next-batch token obtained from a to-device sync query.
3079    pub next_batch_token: Option<String>,
3080}
3081
3082/// Convert a [`MegolmError`] into an [`UnableToDecryptInfo`] or a
3083/// [`CryptoStoreError`].
3084///
3085/// Most `MegolmError` codes are converted into a suitable
3086/// `UnableToDecryptInfo`. The exception is [`MegolmError::Store`], which
3087/// represents a problem with our datastore rather than with the message itself,
3088/// and is therefore returned as a `CryptoStoreError`.
3089fn megolm_error_to_utd_info(
3090    raw_event: &Raw<EncryptedEvent>,
3091    error: MegolmError,
3092) -> Result<UnableToDecryptInfo, CryptoStoreError> {
3093    use MegolmError::*;
3094    let reason = match error {
3095        EventError(_) => UnableToDecryptReason::MalformedEncryptedEvent,
3096        Decode(_) => UnableToDecryptReason::MalformedEncryptedEvent,
3097        MissingRoomKey(maybe_withheld) => {
3098            UnableToDecryptReason::MissingMegolmSession { withheld_code: maybe_withheld }
3099        }
3100        Decryption(DecryptionError::UnknownMessageIndex(_, _)) => {
3101            UnableToDecryptReason::UnknownMegolmMessageIndex
3102        }
3103        Decryption(_) => UnableToDecryptReason::MegolmDecryptionFailure,
3104        JsonError(_) => UnableToDecryptReason::PayloadDeserializationFailure,
3105        MismatchedIdentityKeys(_) => UnableToDecryptReason::MismatchedIdentityKeys,
3106        SenderIdentityNotTrusted(level) => UnableToDecryptReason::SenderIdentityNotTrusted(level),
3107        #[cfg(feature = "experimental-encrypted-state-events")]
3108        StateKeyVerificationFailed => UnableToDecryptReason::StateKeyVerificationFailed,
3109
3110        // Pass through crypto store errors, which indicate a problem with our
3111        // application, rather than a UTD.
3112        Store(error) => Err(error)?,
3113    };
3114
3115    let session_id = raw_event.deserialize().ok().and_then(|ev| match ev.content.scheme {
3116        RoomEventEncryptionScheme::MegolmV1AesSha2(s) => Some(s.session_id),
3117        #[cfg(feature = "experimental-algorithms")]
3118        RoomEventEncryptionScheme::MegolmV2AesSha2(s) => Some(s.session_id),
3119        RoomEventEncryptionScheme::Unknown(_) => None,
3120    });
3121
3122    Ok(UnableToDecryptInfo { session_id, reason })
3123}
3124
3125/// An error that can occur during [`OlmMachine::decrypt_to_device_event`]:
3126///
3127/// * because decryption failed, or
3128///
3129/// * because the sender device was not verified when we are in strict "exclude
3130///   insecure devices" mode, or
3131///
3132/// * because the sender device was a dehydrated device, which should never send
3133///   any to-device messages.
3134#[derive(Debug, thiserror::Error)]
3135pub(crate) enum DecryptToDeviceError {
3136    #[error("An Olm error occurred meaning we failed to decrypt the event")]
3137    OlmError(#[from] OlmError),
3138
3139    #[error("The event was sent from a dehydrated device")]
3140    FromDehydratedDevice,
3141}
3142
3143impl From<CryptoStoreError> for DecryptToDeviceError {
3144    fn from(value: CryptoStoreError) -> Self {
3145        Self::OlmError(value.into())
3146    }
3147}
3148
3149#[cfg(test)]
3150impl From<DecryptToDeviceError> for OlmError {
3151    /// Unwrap the `OlmError` inside this error, or panic if this does not
3152    /// contain an `OlmError`.
3153    fn from(value: DecryptToDeviceError) -> Self {
3154        match value {
3155            DecryptToDeviceError::OlmError(olm_error) => olm_error,
3156            DecryptToDeviceError::FromDehydratedDevice => {
3157                panic!("Expected an OlmError but found FromDehydratedDevice")
3158            }
3159        }
3160    }
3161}
3162
3163#[cfg(test)]
3164pub(crate) mod test_helpers;
3165
3166#[cfg(test)]
3167pub(crate) mod tests;