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    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)
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
915                let sender_data =
916                    SenderDataFinder::find_using_event(self.store(), sender_key, event, &session)
917                        .await?;
918
919                session.sender_data = sender_data;
920
921                match self.store().compare_group_session(&session).await? {
922                    SessionOrdering::Better => {
923                        info!("Received a new megolm room key");
924
925                        Ok(Some(session))
926                    }
927                    comparison_result => {
928                        warn!(
929                            ?comparison_result,
930                            "Received a megolm room key that we already have a better version \
931                             of, discarding"
932                        );
933
934                        Ok(None)
935                    }
936                }
937            }
938            Err(e) => {
939                Span::current().record("session_id", &content.session_id);
940                warn!("Received a room key event which contained an invalid session key: {e}");
941
942                Ok(None)
943            }
944        }
945    }
946
947    /// Create a group session from a room key and add it to our crypto store.
948    #[instrument(skip_all, fields(algorithm = ?event.content.algorithm()))]
949    async fn add_room_key(
950        &self,
951        sender_key: Curve25519PublicKey,
952        event: &DecryptedRoomKeyEvent,
953    ) -> OlmResult<Option<InboundGroupSession>> {
954        match &event.content {
955            RoomKeyContent::MegolmV1AesSha2(content) => {
956                self.handle_key(sender_key, event, content).await
957            }
958            #[cfg(feature = "experimental-algorithms")]
959            RoomKeyContent::MegolmV2AesSha2(content) => {
960                self.handle_key(sender_key, event, content).await
961            }
962            RoomKeyContent::Unknown(_) => {
963                warn!("Received a room key with an unsupported algorithm");
964                Ok(None)
965            }
966        }
967    }
968
969    /// Handle a received, decrypted, `io.element.msc4268.room_key_bundle`
970    /// to-device event.
971    #[instrument()]
972    async fn receive_room_key_bundle_data(
973        &self,
974        sender_key: Curve25519PublicKey,
975        event: &DecryptedRoomKeyBundleEvent,
976        changes: &mut Changes,
977    ) -> OlmResult<()> {
978        let Some(sender_device_keys) = &event.sender_device_keys else {
979            warn!("Received a room key bundle with no sender device keys: ignoring");
980            return Ok(());
981        };
982
983        // NOTE: We already checked that `sender_device_keys` matches the actual sender
984        // of the message when we decrypted the message, which included doing
985        // `DeviceData::try_from` on it, so it can't fail.
986
987        let sender_device_data =
988            DeviceData::try_from(sender_device_keys).expect("failed to verify sender device keys");
989        let sender_device = self.store().wrap_device_data(sender_device_data).await?;
990
991        changes.received_room_key_bundles.push(StoredRoomKeyBundleData {
992            sender_user: event.sender.clone(),
993            sender_data: SenderData::from_device(&sender_device),
994            sender_key,
995            bundle_data: event.content.clone(),
996        });
997        Ok(())
998    }
999
1000    fn add_withheld_info(&self, changes: &mut Changes, event: &RoomKeyWithheldEvent) {
1001        debug!(?event.content, "Processing `m.room_key.withheld` event");
1002
1003        if let RoomKeyWithheldContent::MegolmV1AesSha2(
1004            MegolmV1AesSha2WithheldContent::BlackListed(c)
1005            | MegolmV1AesSha2WithheldContent::Unverified(c),
1006        ) = &event.content
1007        {
1008            changes
1009                .withheld_session_info
1010                .entry(c.room_id.to_owned())
1011                .or_default()
1012                .insert(c.session_id.to_owned(), event.to_owned());
1013        }
1014    }
1015
1016    #[cfg(test)]
1017    pub(crate) async fn create_outbound_group_session_with_defaults_test_helper(
1018        &self,
1019        room_id: &RoomId,
1020    ) -> OlmResult<()> {
1021        let (_, session) = self
1022            .inner
1023            .group_session_manager
1024            .create_outbound_group_session(
1025                room_id,
1026                EncryptionSettings::default(),
1027                SenderData::unknown(),
1028            )
1029            .await?;
1030
1031        self.store().save_inbound_group_sessions(&[session]).await?;
1032
1033        Ok(())
1034    }
1035
1036    #[cfg(test)]
1037    #[allow(dead_code)]
1038    pub(crate) async fn create_inbound_session_test_helper(
1039        &self,
1040        room_id: &RoomId,
1041    ) -> OlmResult<InboundGroupSession> {
1042        let (_, session) = self
1043            .inner
1044            .group_session_manager
1045            .create_outbound_group_session(
1046                room_id,
1047                EncryptionSettings::default(),
1048                SenderData::unknown(),
1049            )
1050            .await?;
1051
1052        Ok(session)
1053    }
1054
1055    /// Encrypt a room message for the given room.
1056    ///
1057    /// Beware that a room key needs to be shared before this method
1058    /// can be called using the [`OlmMachine::share_room_key`] method.
1059    ///
1060    /// # Arguments
1061    ///
1062    /// * `room_id` - The id of the room for which the message should be
1063    ///   encrypted.
1064    ///
1065    /// * `content` - The plaintext content of the message that should be
1066    ///   encrypted.
1067    ///
1068    /// # Panics
1069    ///
1070    /// Panics if a room key for the given room wasn't shared beforehand.
1071    pub async fn encrypt_room_event(
1072        &self,
1073        room_id: &RoomId,
1074        content: impl MessageLikeEventContent,
1075    ) -> MegolmResult<Raw<RoomEncryptedEventContent>> {
1076        let event_type = content.event_type().to_string();
1077        let content = Raw::new(&content)?.cast_unchecked();
1078        self.encrypt_room_event_raw(room_id, &event_type, &content).await
1079    }
1080
1081    /// Encrypt a raw JSON content for the given room.
1082    ///
1083    /// This method is equivalent to the [`OlmMachine::encrypt_room_event()`]
1084    /// method but operates on an arbitrary JSON value instead of strongly-typed
1085    /// event content struct.
1086    ///
1087    /// # Arguments
1088    ///
1089    /// * `room_id` - The id of the room for which the message should be
1090    ///   encrypted.
1091    ///
1092    /// * `content` - The plaintext content of the message that should be
1093    ///   encrypted as a raw JSON value.
1094    ///
1095    /// * `event_type` - The plaintext type of the event.
1096    ///
1097    /// # Panics
1098    ///
1099    /// Panics if a group session for the given room wasn't shared beforehand.
1100    pub async fn encrypt_room_event_raw(
1101        &self,
1102        room_id: &RoomId,
1103        event_type: &str,
1104        content: &Raw<AnyMessageLikeEventContent>,
1105    ) -> MegolmResult<Raw<RoomEncryptedEventContent>> {
1106        self.inner.group_session_manager.encrypt(room_id, event_type, content).await
1107    }
1108
1109    /// Encrypt a state event for the given room.
1110    ///
1111    /// # Arguments
1112    ///
1113    /// * `room_id` - The id of the room for which the event should be
1114    ///   encrypted.
1115    ///
1116    /// * `content` - The plaintext content of the event that should be
1117    ///   encrypted.
1118    ///
1119    /// * `state_key` - The associated state key of the event.
1120    #[cfg(feature = "experimental-encrypted-state-events")]
1121    pub async fn encrypt_state_event<C, K>(
1122        &self,
1123        room_id: &RoomId,
1124        content: C,
1125        state_key: K,
1126    ) -> MegolmResult<Raw<RoomEncryptedEventContent>>
1127    where
1128        C: StateEventContent,
1129        C::StateKey: Borrow<K>,
1130        K: AsRef<str>,
1131    {
1132        let event_type = content.event_type().to_string();
1133        let content = Raw::new(&content)?.cast_unchecked();
1134        self.encrypt_state_event_raw(room_id, &event_type, state_key.as_ref(), &content).await
1135    }
1136
1137    /// Encrypt a state event for the given state event using its raw JSON
1138    /// content and state key.
1139    ///
1140    /// This method is equivalent to [`OlmMachine::encrypt_state_event`]
1141    /// method but operates on an arbitrary JSON value instead of strongly-typed
1142    /// event content struct.
1143    ///
1144    /// # Arguments
1145    ///
1146    /// * `room_id` - The id of the room for which the message should be
1147    ///   encrypted.
1148    ///
1149    /// * `event_type` - The type of the event.
1150    ///
1151    /// * `state_key` - The associated state key of the event.
1152    ///
1153    /// * `content` - The plaintext content of the event that should be
1154    ///   encrypted as a raw JSON value.
1155    #[cfg(feature = "experimental-encrypted-state-events")]
1156    pub async fn encrypt_state_event_raw(
1157        &self,
1158        room_id: &RoomId,
1159        event_type: &str,
1160        state_key: &str,
1161        content: &Raw<AnyStateEventContent>,
1162    ) -> MegolmResult<Raw<RoomEncryptedEventContent>> {
1163        self.inner
1164            .group_session_manager
1165            .encrypt_state(room_id, event_type, state_key, content)
1166            .await
1167    }
1168
1169    /// Forces the currently active room key, which is used to encrypt messages,
1170    /// to be rotated.
1171    ///
1172    /// A new room key will be crated and shared with all the room members the
1173    /// next time a message will be sent. You don't have to call this method,
1174    /// room keys will be rotated automatically when necessary. This method is
1175    /// still useful for debugging purposes.
1176    ///
1177    /// Returns true if a session was invalidated, false if there was no session
1178    /// to invalidate.
1179    pub async fn discard_room_key(&self, room_id: &RoomId) -> StoreResult<bool> {
1180        self.inner.group_session_manager.invalidate_group_session(room_id).await
1181    }
1182
1183    /// Get to-device requests to share a room key with users in a room.
1184    ///
1185    /// # Arguments
1186    ///
1187    /// `room_id` - The room id of the room where the room key will be
1188    /// used.
1189    ///
1190    /// `users` - The list of users that should receive the room key.
1191    ///
1192    /// `settings` - Encryption settings that affect when are room keys rotated
1193    /// and who are they shared with.
1194    ///
1195    /// # Returns
1196    ///
1197    /// List of the to-device requests that need to be sent out to the server
1198    /// and the responses need to be passed back to the state machine with
1199    /// [`mark_request_as_sent`], using the to-device `txn_id` as `request_id`.
1200    ///
1201    /// [`mark_request_as_sent`]: #method.mark_request_as_sent
1202    pub async fn share_room_key(
1203        &self,
1204        room_id: &RoomId,
1205        users: impl Iterator<Item = &UserId>,
1206        encryption_settings: impl Into<EncryptionSettings>,
1207    ) -> OlmResult<Vec<Arc<ToDeviceRequest>>> {
1208        self.inner.group_session_manager.share_room_key(room_id, users, encryption_settings).await
1209    }
1210
1211    /// Encrypts the given content using Olm for each of the given devices.
1212    ///
1213    /// The 1-to-1 session must be established prior to this
1214    /// call by using the [`OlmMachine::get_missing_sessions`] method or the
1215    /// encryption will fail.
1216    ///
1217    /// The caller is responsible for sending the encrypted
1218    /// event to the target device, and should do it ASAP to avoid out-of-order
1219    /// messages.
1220    ///
1221    /// # Returns
1222    /// A list of `ToDeviceRequest` to send out the event, and the list of
1223    /// devices where encryption did not succeed (device excluded or no olm)
1224    #[cfg(feature = "experimental-send-custom-to-device")]
1225    pub async fn encrypt_content_for_devices(
1226        &self,
1227        devices: Vec<DeviceData>,
1228        event_type: &str,
1229        content: &Value,
1230        share_strategy: CollectStrategy,
1231    ) -> OlmResult<(Vec<ToDeviceRequest>, Vec<(DeviceData, WithheldCode)>)> {
1232        let mut changes = Changes::default();
1233
1234        let (allowed_devices, mut blocked_devices) =
1235            split_devices_for_share_strategy(&self.inner.store, devices, share_strategy).await?;
1236
1237        let result = self
1238            .inner
1239            .group_session_manager
1240            .encrypt_content_for_devices(allowed_devices, event_type, content.clone(), &mut changes)
1241            .await;
1242
1243        // Persist any changes we might have collected.
1244        if !changes.is_empty() {
1245            let session_count = changes.sessions.len();
1246
1247            self.inner.store.save_changes(changes).await?;
1248
1249            trace!(
1250                session_count = session_count,
1251                "Stored the changed sessions after encrypting a custom to-device event"
1252            );
1253        }
1254
1255        result.map(|(to_device_requests, mut withheld)| {
1256            withheld.append(&mut blocked_devices);
1257            (to_device_requests, withheld)
1258        })
1259    }
1260    /// Collect the devices belonging to the given user, and send the details of
1261    /// a room key bundle to those devices.
1262    ///
1263    /// Returns a list of to-device requests which must be sent.
1264    pub async fn share_room_key_bundle_data(
1265        &self,
1266        user_id: &UserId,
1267        collect_strategy: &CollectStrategy,
1268        bundle_data: RoomKeyBundleContent,
1269    ) -> OlmResult<Vec<ToDeviceRequest>> {
1270        self.inner
1271            .group_session_manager
1272            .share_room_key_bundle_data(user_id, collect_strategy, bundle_data)
1273            .await
1274    }
1275
1276    /// Receive an unencrypted verification event.
1277    ///
1278    /// This method can be used to pass verification events that are happening
1279    /// in unencrypted rooms to the `OlmMachine`.
1280    ///
1281    /// **Note**: This does not need to be called for encrypted events since
1282    /// those will get passed to the `OlmMachine` during decryption.
1283    #[deprecated(note = "Use OlmMachine::receive_verification_event instead", since = "0.7.0")]
1284    pub async fn receive_unencrypted_verification_event(
1285        &self,
1286        event: &AnyMessageLikeEvent,
1287    ) -> StoreResult<()> {
1288        self.inner.verification_machine.receive_any_event(event).await
1289    }
1290
1291    /// Receive a verification event.
1292    ///
1293    /// The event should be in the decrypted form.
1294    pub async fn receive_verification_event(&self, event: &AnyMessageLikeEvent) -> StoreResult<()> {
1295        self.inner.verification_machine.receive_any_event(event).await
1296    }
1297
1298    /// Receive and properly handle a decrypted to-device event.
1299    ///
1300    /// # Arguments
1301    ///
1302    /// * `decrypted` - The decrypted event and some associated metadata.
1303    #[instrument(
1304        skip_all,
1305        fields(
1306            sender_key = ?decrypted.result.sender_key,
1307            event_type = decrypted.result.event.event_type(),
1308        ),
1309    )]
1310    async fn handle_decrypted_to_device_event(
1311        &self,
1312        cache: &StoreCache,
1313        decrypted: &mut OlmDecryptionInfo,
1314        changes: &mut Changes,
1315    ) -> OlmResult<()> {
1316        debug!(
1317            sender_device_keys =
1318                ?decrypted.result.event.sender_device_keys().map(|k| (k.curve25519_key(), k.ed25519_key())).unwrap_or((None, None)),
1319            "Received a decrypted to-device event",
1320        );
1321
1322        match &*decrypted.result.event {
1323            AnyDecryptedOlmEvent::RoomKey(e) => {
1324                let session = self.add_room_key(decrypted.result.sender_key, e).await?;
1325                decrypted.inbound_group_session = session;
1326            }
1327            AnyDecryptedOlmEvent::ForwardedRoomKey(e) => {
1328                let session = self
1329                    .inner
1330                    .key_request_machine
1331                    .receive_forwarded_room_key(decrypted.result.sender_key, e)
1332                    .await?;
1333                decrypted.inbound_group_session = session;
1334            }
1335            AnyDecryptedOlmEvent::SecretSend(e) => {
1336                let name = self
1337                    .inner
1338                    .key_request_machine
1339                    .receive_secret_event(cache, decrypted.result.sender_key, e, changes)
1340                    .await?;
1341
1342                // Set the secret name so other consumers of the event know
1343                // what this event is about.
1344                if let Ok(ToDeviceEvents::SecretSend(mut e)) =
1345                    decrypted.result.raw_event.deserialize_as()
1346                {
1347                    e.content.secret_name = name;
1348                    decrypted.result.raw_event = Raw::from_json(to_raw_value(&e)?);
1349                }
1350            }
1351            AnyDecryptedOlmEvent::Dummy(_) => {
1352                debug!("Received an `m.dummy` event");
1353            }
1354            AnyDecryptedOlmEvent::RoomKeyBundle(e) => {
1355                debug!("Received a room key bundle event {:?}", e);
1356                self.receive_room_key_bundle_data(decrypted.result.sender_key, e, changes).await?;
1357            }
1358            AnyDecryptedOlmEvent::Custom(_) => {
1359                warn!("Received an unexpected encrypted to-device event");
1360            }
1361        }
1362
1363        Ok(())
1364    }
1365
1366    async fn handle_verification_event(&self, event: &ToDeviceEvents) {
1367        if let Err(e) = self.inner.verification_machine.receive_any_event(event).await {
1368            error!("Error handling a verification event: {e:?}");
1369        }
1370    }
1371
1372    /// Mark an outgoing to-device requests as sent.
1373    async fn mark_to_device_request_as_sent(&self, request_id: &TransactionId) -> StoreResult<()> {
1374        self.inner.verification_machine.mark_request_as_sent(request_id);
1375        self.inner.key_request_machine.mark_outgoing_request_as_sent(request_id).await?;
1376        self.inner.group_session_manager.mark_request_as_sent(request_id).await?;
1377        self.inner.session_manager.mark_outgoing_request_as_sent(request_id);
1378        Ok(())
1379    }
1380
1381    /// Get a verification object for the given user id with the given flow id.
1382    pub fn get_verification(&self, user_id: &UserId, flow_id: &str) -> Option<Verification> {
1383        self.inner.verification_machine.get_verification(user_id, flow_id)
1384    }
1385
1386    /// Get a verification request object with the given flow id.
1387    pub fn get_verification_request(
1388        &self,
1389        user_id: &UserId,
1390        flow_id: impl AsRef<str>,
1391    ) -> Option<VerificationRequest> {
1392        self.inner.verification_machine.get_request(user_id, flow_id)
1393    }
1394
1395    /// Get all the verification requests of a given user.
1396    pub fn get_verification_requests(&self, user_id: &UserId) -> Vec<VerificationRequest> {
1397        self.inner.verification_machine.get_requests(user_id)
1398    }
1399
1400    /// Given a to-device event that has either been decrypted or arrived in
1401    /// plaintext, handle it.
1402    ///
1403    /// Here, we only process events that are allowed to arrive in plaintext.
1404    async fn handle_to_device_event(&self, changes: &mut Changes, event: &ToDeviceEvents) {
1405        use crate::types::events::ToDeviceEvents::*;
1406
1407        match event {
1408            // These are handled here because we accept them either plaintext or
1409            // encrypted.
1410            //
1411            // Note: this list should match the allowed types in
1412            // check_to_device_is_from_verified_device_or_allowed_type
1413            RoomKeyRequest(e) => self.inner.key_request_machine.receive_incoming_key_request(e),
1414            SecretRequest(e) => self.inner.key_request_machine.receive_incoming_secret_request(e),
1415            RoomKeyWithheld(e) => self.add_withheld_info(changes, e),
1416            KeyVerificationAccept(..)
1417            | KeyVerificationCancel(..)
1418            | KeyVerificationKey(..)
1419            | KeyVerificationMac(..)
1420            | KeyVerificationRequest(..)
1421            | KeyVerificationReady(..)
1422            | KeyVerificationDone(..)
1423            | KeyVerificationStart(..) => {
1424                self.handle_verification_event(event).await;
1425            }
1426
1427            // We don't process custom or dummy events at all
1428            Custom(_) | Dummy(_) => {}
1429
1430            // Encrypted events are handled elsewhere
1431            RoomEncrypted(_) => {}
1432
1433            // These are handled in `handle_decrypted_to_device_event` because we
1434            // only accept them if they arrive encrypted.
1435            SecretSend(_) | RoomKey(_) | ForwardedRoomKey(_) => {}
1436        }
1437    }
1438
1439    fn record_message_id(event: &Raw<AnyToDeviceEvent>) {
1440        use serde::Deserialize;
1441
1442        #[derive(Deserialize)]
1443        struct ContentStub<'a> {
1444            #[serde(borrow, rename = "org.matrix.msgid")]
1445            message_id: Option<&'a str>,
1446        }
1447        #[derive(Deserialize)]
1448        struct ToDeviceStub<'a> {
1449            sender: &'a str,
1450            #[serde(rename = "type")]
1451            event_type: &'a str,
1452            #[serde(borrow)]
1453            content: ContentStub<'a>,
1454        }
1455
1456        if let Ok(event) = event.deserialize_as_unchecked::<ToDeviceStub<'_>>() {
1457            Span::current().record("sender", event.sender);
1458            Span::current().record("event_type", event.event_type);
1459            Span::current().record("message_id", event.content.message_id);
1460        }
1461    }
1462
1463    /// Decrypt the supplied to-device event (if needed, and if we can) and
1464    /// handle it.
1465    ///
1466    /// Return the same event, decrypted if possible and needed.
1467    ///
1468    /// If we can identify that this to-device event came from a dehydrated
1469    /// device, this method does not process it, and returns `None`.
1470    #[instrument(skip_all, fields(sender, event_type, message_id))]
1471    async fn receive_to_device_event(
1472        &self,
1473        transaction: &mut StoreTransaction,
1474        changes: &mut Changes,
1475        raw_event: Raw<AnyToDeviceEvent>,
1476        decryption_settings: &DecryptionSettings,
1477    ) -> Option<ProcessedToDeviceEvent> {
1478        Self::record_message_id(&raw_event);
1479
1480        let event: ToDeviceEvents = match raw_event.deserialize_as() {
1481            Ok(e) => e,
1482            Err(e) => {
1483                // Skip invalid events.
1484                warn!("Received an invalid to-device event: {e}");
1485                return Some(ProcessedToDeviceEvent::Invalid(raw_event));
1486            }
1487        };
1488
1489        debug!("Received a to-device event");
1490
1491        match event {
1492            ToDeviceEvents::RoomEncrypted(e) => {
1493                self.receive_encrypted_to_device_event(
1494                    transaction,
1495                    changes,
1496                    raw_event,
1497                    e,
1498                    decryption_settings,
1499                )
1500                .await
1501            }
1502            e => {
1503                self.handle_to_device_event(changes, &e).await;
1504                Some(ProcessedToDeviceEvent::PlainText(raw_event))
1505            }
1506        }
1507    }
1508
1509    /// Decrypt the supplied encrypted to-device event (if we can) and handle
1510    /// it.
1511    ///
1512    /// Return the same event, decrypted if possible.
1513    ///
1514    /// If we are in strict "exclude insecure devices" mode and the sender
1515    /// device is not verified, and the decrypted event type is not on the
1516    /// allow list, or if this event comes from a dehydrated device, this method
1517    /// does not process it, and returns `None`.
1518    ///
1519    /// (The allow list of types that are processed even if the sender is
1520    /// unverified is: `m.room_key`, `m.room_key.withheld`,
1521    /// `m.room_key_request`, `m.secret.request` and `m.key.verification.*`.)
1522    async fn receive_encrypted_to_device_event(
1523        &self,
1524        transaction: &mut StoreTransaction,
1525        changes: &mut Changes,
1526        mut raw_event: Raw<AnyToDeviceEvent>,
1527        e: ToDeviceEvent<ToDeviceEncryptedEventContent>,
1528        decryption_settings: &DecryptionSettings,
1529    ) -> Option<ProcessedToDeviceEvent> {
1530        let decrypted = match self
1531            .decrypt_to_device_event(transaction, &e, changes, decryption_settings)
1532            .await
1533        {
1534            Ok(decrypted) => decrypted,
1535            Err(DecryptToDeviceError::OlmError(err)) => {
1536                let reason = if let OlmError::UnverifiedSenderDevice = &err {
1537                    ToDeviceUnableToDecryptReason::UnverifiedSenderDevice
1538                } else {
1539                    ToDeviceUnableToDecryptReason::DecryptionFailure
1540                };
1541
1542                if let OlmError::SessionWedged(sender, curve_key) = err {
1543                    if let Err(e) =
1544                        self.inner.session_manager.mark_device_as_wedged(&sender, curve_key).await
1545                    {
1546                        error!(
1547                            error = ?e,
1548                            "Couldn't mark device to be unwedged",
1549                        );
1550                    }
1551                }
1552
1553                return Some(ProcessedToDeviceEvent::UnableToDecrypt {
1554                    encrypted_event: raw_event,
1555                    utd_info: ToDeviceUnableToDecryptInfo { reason },
1556                });
1557            }
1558            Err(DecryptToDeviceError::FromDehydratedDevice) => return None,
1559        };
1560
1561        // New sessions modify the account so we need to save that
1562        // one as well.
1563        match decrypted.session {
1564            SessionType::New(s) | SessionType::Existing(s) => {
1565                changes.sessions.push(s);
1566            }
1567        }
1568
1569        changes.message_hashes.push(decrypted.message_hash);
1570
1571        if let Some(group_session) = decrypted.inbound_group_session {
1572            changes.inbound_group_sessions.push(group_session);
1573        }
1574
1575        match decrypted.result.raw_event.deserialize_as() {
1576            Ok(event) => {
1577                self.handle_to_device_event(changes, &event).await;
1578
1579                raw_event = event
1580                    .serialize_zeroized()
1581                    .expect("Zeroizing and reserializing our events should always work")
1582                    .cast();
1583            }
1584            Err(e) => {
1585                warn!("Received an invalid encrypted to-device event: {e}");
1586                raw_event = decrypted.result.raw_event;
1587            }
1588        }
1589
1590        Some(ProcessedToDeviceEvent::Decrypted {
1591            raw: raw_event,
1592            encryption_info: decrypted.result.encryption_info,
1593        })
1594    }
1595
1596    /// Return an error if the supplied to-device event was sent from a
1597    /// dehydrated device.
1598    async fn check_to_device_event_is_not_from_dehydrated_device(
1599        &self,
1600        decrypted: &OlmDecryptionInfo,
1601        sender_user_id: &UserId,
1602    ) -> Result<(), DecryptToDeviceError> {
1603        if self.to_device_event_is_from_dehydrated_device(decrypted, sender_user_id).await? {
1604            warn!(
1605                sender = ?sender_user_id,
1606                session = ?decrypted.session,
1607                "Received a to-device event from a dehydrated device. This is unexpected: ignoring event"
1608            );
1609            Err(DecryptToDeviceError::FromDehydratedDevice)
1610        } else {
1611            Ok(())
1612        }
1613    }
1614
1615    /// Decide whether a decrypted to-device event was sent from a dehydrated
1616    /// device.
1617    ///
1618    /// This accepts an [`OlmDecryptionInfo`] because it deals with a decrypted
1619    /// event.
1620    async fn to_device_event_is_from_dehydrated_device(
1621        &self,
1622        decrypted: &OlmDecryptionInfo,
1623        sender_user_id: &UserId,
1624    ) -> OlmResult<bool> {
1625        // Does the to-device message include device info?
1626        if let Some(device_keys) = decrypted.result.event.sender_device_keys() {
1627            // There is no need to check whether the device keys are signed correctly - any
1628            // to-device message that claims to be from a dehydrated device is weird, so we
1629            // will drop it.
1630
1631            // Does the included device info say the device is dehydrated?
1632            if device_keys.dehydrated.unwrap_or(false) {
1633                return Ok(true);
1634            }
1635            // If not, fall through and check our existing list of devices
1636            // below, just in case the sender is sending us incorrect
1637            // information embedded in the to-device message, but we know
1638            // better.
1639        }
1640
1641        // Do we already know about this device?
1642        Ok(self
1643            .store()
1644            .get_device_from_curve_key(sender_user_id, decrypted.result.sender_key)
1645            .await?
1646            .is_some_and(|d| d.is_dehydrated()))
1647    }
1648
1649    /// Handle a to-device and one-time key counts from a sync response.
1650    ///
1651    /// This will decrypt and handle to-device events returning the decrypted
1652    /// versions of them.
1653    ///
1654    /// To decrypt an event from the room timeline, call [`decrypt_room_event`].
1655    ///
1656    /// # Arguments
1657    ///
1658    /// * `sync_changes` - an [`EncryptionSyncChanges`] value, constructed from
1659    ///   a sync response.
1660    ///
1661    /// [`decrypt_room_event`]: #method.decrypt_room_event
1662    ///
1663    /// # Returns
1664    ///
1665    /// A tuple of (decrypted to-device events, updated room keys).
1666    #[instrument(skip_all)]
1667    pub async fn receive_sync_changes(
1668        &self,
1669        sync_changes: EncryptionSyncChanges<'_>,
1670        decryption_settings: &DecryptionSettings,
1671    ) -> OlmResult<(Vec<ProcessedToDeviceEvent>, Vec<RoomKeyInfo>)> {
1672        let mut store_transaction = self.inner.store.transaction().await;
1673
1674        let (events, changes) = self
1675            .preprocess_sync_changes(&mut store_transaction, sync_changes, decryption_settings)
1676            .await?;
1677
1678        // Technically save_changes also does the same work, so if it's slow we could
1679        // refactor this to do it only once.
1680        let room_key_updates: Vec<_> =
1681            changes.inbound_group_sessions.iter().map(RoomKeyInfo::from).collect();
1682
1683        self.store().save_changes(changes).await?;
1684        store_transaction.commit().await?;
1685
1686        Ok((events, room_key_updates))
1687    }
1688
1689    /// Initial processing of the changes specified within a sync response.
1690    ///
1691    /// Returns the to-device events (decrypted where needed and where possible)
1692    /// and the processed set of changes.
1693    ///
1694    /// If any of the to-device events in the supplied changes were sent from
1695    /// dehydrated devices, these are not processed, and are omitted from
1696    /// the returned list, as per MSC3814.
1697    ///
1698    /// If we are in strict "exclude insecure devices" mode and the sender
1699    /// device of any event is not verified, and the decrypted event type is not
1700    /// on the allow list, these events are not processed and are omitted from
1701    /// the returned list.
1702    ///
1703    /// (The allow list of types that are processed even if the sender is
1704    /// unverified is: `m.room_key`, `m.room_key.withheld`,
1705    /// `m.room_key_request`, `m.secret.request` and `m.key.verification.*`.)
1706    pub(crate) async fn preprocess_sync_changes(
1707        &self,
1708        transaction: &mut StoreTransaction,
1709        sync_changes: EncryptionSyncChanges<'_>,
1710        decryption_settings: &DecryptionSettings,
1711    ) -> OlmResult<(Vec<ProcessedToDeviceEvent>, Changes)> {
1712        // Remove verification objects that have expired or are done.
1713        let mut events: Vec<ProcessedToDeviceEvent> = self
1714            .inner
1715            .verification_machine
1716            .garbage_collect()
1717            .iter()
1718            // These are `fake` to device events just serving as local echo
1719            // in order that our own client can react quickly to cancelled transaction.
1720            // Just use PlainText for that.
1721            .map(|e| ProcessedToDeviceEvent::PlainText(e.clone()))
1722            .collect();
1723        // The account is automatically saved by the store transaction created by the
1724        // caller.
1725        let mut changes = Default::default();
1726
1727        {
1728            let account = transaction.account().await?;
1729            account.update_key_counts(
1730                sync_changes.one_time_keys_counts,
1731                sync_changes.unused_fallback_keys,
1732            )
1733        }
1734
1735        if let Err(e) = self
1736            .inner
1737            .identity_manager
1738            .receive_device_changes(
1739                transaction.cache(),
1740                sync_changes.changed_devices.changed.iter().map(|u| u.as_ref()),
1741            )
1742            .await
1743        {
1744            error!(error = ?e, "Error marking a tracked user as changed");
1745        }
1746
1747        for raw_event in sync_changes.to_device_events {
1748            let processed_event = Box::pin(self.receive_to_device_event(
1749                transaction,
1750                &mut changes,
1751                raw_event,
1752                decryption_settings,
1753            ))
1754            .await;
1755
1756            if let Some(processed_event) = processed_event {
1757                events.push(processed_event);
1758            }
1759        }
1760
1761        let changed_sessions = self
1762            .inner
1763            .key_request_machine
1764            .collect_incoming_key_requests(transaction.cache())
1765            .await?;
1766
1767        changes.sessions.extend(changed_sessions);
1768        changes.next_batch_token = sync_changes.next_batch_token;
1769
1770        Ok((events, changes))
1771    }
1772
1773    /// Request a room key from our devices.
1774    ///
1775    /// This method will return a request cancellation and a new key request if
1776    /// the key was already requested, otherwise it will return just the key
1777    /// request.
1778    ///
1779    /// The request cancellation *must* be sent out before the request is sent
1780    /// out, otherwise devices will ignore the key request.
1781    ///
1782    /// # Arguments
1783    ///
1784    /// * `room_id` - The id of the room where the key is used in.
1785    ///
1786    /// * `sender_key` - The curve25519 key of the sender that owns the key.
1787    ///
1788    /// * `session_id` - The id that uniquely identifies the session.
1789    pub async fn request_room_key(
1790        &self,
1791        event: &Raw<EncryptedEvent>,
1792        room_id: &RoomId,
1793    ) -> MegolmResult<(Option<OutgoingRequest>, OutgoingRequest)> {
1794        let event = event.deserialize()?;
1795        self.inner.key_request_machine.request_key(room_id, &event).await
1796    }
1797
1798    /// Find whether an event decrypted via the supplied session is verified,
1799    /// and provide explanation of what is missing/wrong if not.
1800    ///
1801    /// Stores the updated [`SenderData`] for the session in the store
1802    /// if we find an updated value for it.
1803    ///
1804    /// # Arguments
1805    ///
1806    /// * `session` - The inbound Megolm session that was used to decrypt the
1807    ///   event.
1808    /// * `sender` - The `sender` of that event (as claimed by the envelope of
1809    ///   the event).
1810    async fn get_room_event_verification_state(
1811        &self,
1812        session: &InboundGroupSession,
1813        sender: &UserId,
1814    ) -> MegolmResult<(VerificationState, Option<OwnedDeviceId>)> {
1815        let sender_data = self.get_or_update_sender_data(session, sender).await?;
1816
1817        // If the user ID in the sender data doesn't match that in the event envelope,
1818        // this event is not from who it appears to be from.
1819        //
1820        // If `sender_data.user_id()` returns `None`, that means we don't have any
1821        // information about the owner of the session (i.e. we have
1822        // `SenderData::UnknownDevice`); in that case we fall through to the
1823        // logic in `sender_data_to_verification_state` which will pick an appropriate
1824        // `DeviceLinkProblem` for `VerificationLevel::None`.
1825        let (verification_state, device_id) = match sender_data.user_id() {
1826            Some(i) if i != sender => {
1827                (VerificationState::Unverified(VerificationLevel::MismatchedSender), None)
1828            }
1829
1830            Some(_) | None => {
1831                sender_data_to_verification_state(sender_data, session.has_been_imported())
1832            }
1833        };
1834
1835        Ok((verification_state, device_id))
1836    }
1837
1838    /// Get an up-to-date [`SenderData`] for the given session, suitable for
1839    /// determining if messages decrypted using that session are verified.
1840    ///
1841    /// Checks both the stored verification state of the session and a
1842    /// recalculated verification state based on our current knowledge, and
1843    /// returns the more trusted of the two.
1844    ///
1845    /// Stores the updated [`SenderData`] for the session in the store
1846    /// if we find an updated value for it.
1847    ///
1848    /// # Arguments
1849    ///
1850    /// * `session` - The Megolm session that was used to decrypt the event.
1851    /// * `sender` - The claimed sender of that event.
1852    async fn get_or_update_sender_data(
1853        &self,
1854        session: &InboundGroupSession,
1855        sender: &UserId,
1856    ) -> MegolmResult<SenderData> {
1857        let sender_data = if session.sender_data.should_recalculate() {
1858            // The session is not sure of the sender yet. Try to find a matching device
1859            // belonging to the claimed sender of the recently-received event.
1860            //
1861            // It's worth noting that this could in theory result in unintuitive changes,
1862            // like a session which initially appears to belong to Alice turning into a
1863            // session which belongs to Bob [1]. This could mean that a session initially
1864            // successfully decrypts events from Alice, but then stops decrypting those same
1865            // events once we get an update.
1866            //
1867            // That's ok though: if we get good evidence that the session belongs to Bob,
1868            // it's correct to update the session even if we previously had weak
1869            // evidence it belonged to Alice.
1870            //
1871            // [1] For example: maybe Alice and Bob both publish devices with the *same*
1872            // keys (presumably because they are colluding). Initially we think
1873            // the session belongs to Alice, but then we do a device lookup for
1874            // Bob, we find a matching device with a cross-signature, so prefer
1875            // that.
1876            let calculated_sender_data = SenderDataFinder::find_using_curve_key(
1877                self.store(),
1878                session.sender_key(),
1879                sender,
1880                session,
1881            )
1882            .await?;
1883
1884            // Is the newly-calculated sender data more trusted?
1885            if calculated_sender_data.compare_trust_level(&session.sender_data).is_gt() {
1886                // Yes - save it to the store
1887                let mut new_session = session.clone();
1888                new_session.sender_data = calculated_sender_data.clone();
1889                self.store().save_inbound_group_sessions(&[new_session]).await?;
1890
1891                // and use it now.
1892                calculated_sender_data
1893            } else {
1894                // No - use the existing data.
1895                session.sender_data.clone()
1896            }
1897        } else {
1898            session.sender_data.clone()
1899        };
1900
1901        Ok(sender_data)
1902    }
1903
1904    /// Request missing local secrets from our devices (cross signing private
1905    /// keys, megolm backup). This will ask the sdk to create outgoing
1906    /// request to get the missing secrets.
1907    ///
1908    /// The requests will be processed as soon as `outgoing_requests()` is
1909    /// called to process them.
1910    ///
1911    /// # Returns
1912    ///
1913    /// A bool result saying if actual secrets were missing and have been
1914    /// requested
1915    ///
1916    /// # Examples
1917    //
1918    /// ```
1919    /// # async {
1920    /// # use matrix_sdk_crypto::OlmMachine;
1921    /// # let machine: OlmMachine = unimplemented!();
1922    /// if machine.query_missing_secrets_from_other_sessions().await.unwrap() {
1923    ///     let to_send = machine.outgoing_requests().await.unwrap();
1924    ///     // send the to device requests
1925    /// };
1926    /// # anyhow::Ok(()) };
1927    /// ```
1928    pub async fn query_missing_secrets_from_other_sessions(&self) -> StoreResult<bool> {
1929        let identity = self.inner.user_identity.lock().await;
1930        let mut secrets = identity.get_missing_secrets().await;
1931
1932        if self.store().load_backup_keys().await?.decryption_key.is_none() {
1933            secrets.push(SecretName::RecoveryKey);
1934        }
1935
1936        if secrets.is_empty() {
1937            debug!("No missing requests to query");
1938            return Ok(false);
1939        }
1940
1941        let secret_requests = GossipMachine::request_missing_secrets(self.user_id(), secrets);
1942
1943        // Check if there are already in-flight requests for these secrets?
1944        let unsent_request = self.store().get_unsent_secret_requests().await?;
1945        let not_yet_requested = secret_requests
1946            .into_iter()
1947            .filter(|request| !unsent_request.iter().any(|unsent| unsent.info == request.info))
1948            .collect_vec();
1949
1950        if not_yet_requested.is_empty() {
1951            debug!("The missing secrets have already been requested");
1952            Ok(false)
1953        } else {
1954            debug!("Requesting missing secrets");
1955
1956            let changes = Changes { key_requests: not_yet_requested, ..Default::default() };
1957
1958            self.store().save_changes(changes).await?;
1959            Ok(true)
1960        }
1961    }
1962
1963    /// Get some metadata pertaining to a given group session.
1964    ///
1965    /// This includes the session owner's Matrix user ID, their device ID, info
1966    /// regarding the cryptographic algorithm and whether the session, and by
1967    /// extension the events decrypted by the session, are trusted.
1968    async fn get_encryption_info(
1969        &self,
1970        session: &InboundGroupSession,
1971        sender: &UserId,
1972    ) -> MegolmResult<Arc<EncryptionInfo>> {
1973        let (verification_state, device_id) =
1974            self.get_room_event_verification_state(session, sender).await?;
1975
1976        let sender = sender.to_owned();
1977
1978        Ok(Arc::new(EncryptionInfo {
1979            sender,
1980            sender_device: device_id,
1981            algorithm_info: AlgorithmInfo::MegolmV1AesSha2 {
1982                curve25519_key: session.sender_key().to_base64(),
1983                sender_claimed_keys: session
1984                    .signing_keys()
1985                    .iter()
1986                    .map(|(k, v)| (k.to_owned(), v.to_base64()))
1987                    .collect(),
1988                session_id: Some(session.session_id().to_owned()),
1989            },
1990            verification_state,
1991        }))
1992    }
1993
1994    async fn decrypt_megolm_events(
1995        &self,
1996        room_id: &RoomId,
1997        event: &EncryptedEvent,
1998        content: &SupportedEventEncryptionSchemes<'_>,
1999        decryption_settings: &DecryptionSettings,
2000    ) -> MegolmResult<(JsonObject, Arc<EncryptionInfo>)> {
2001        let session =
2002            self.get_inbound_group_session_or_error(room_id, content.session_id()).await?;
2003
2004        // This function is only ever called by decrypt_room_event, so
2005        // room_id, sender, algorithm and session_id are recorded already
2006        //
2007        // While we already record the sender key in some cases from the event, the
2008        // sender key in the event is deprecated, so let's record it now.
2009        Span::current().record("sender_key", debug(session.sender_key()));
2010
2011        let result = session.decrypt(event).await;
2012        match result {
2013            Ok((decrypted_event, _)) => {
2014                let encryption_info = self.get_encryption_info(&session, &event.sender).await?;
2015
2016                self.check_sender_trust_requirement(
2017                    &session,
2018                    &encryption_info,
2019                    &decryption_settings.sender_device_trust_requirement,
2020                )?;
2021
2022                Ok((decrypted_event, encryption_info))
2023            }
2024            Err(error) => Err(
2025                if let MegolmError::Decryption(DecryptionError::UnknownMessageIndex(_, _)) = error {
2026                    let withheld_code = self
2027                        .inner
2028                        .store
2029                        .get_withheld_info(room_id, content.session_id())
2030                        .await?
2031                        .map(|e| e.content.withheld_code());
2032
2033                    if withheld_code.is_some() {
2034                        // Partially withheld, report with a withheld code if we have one.
2035                        MegolmError::MissingRoomKey(withheld_code)
2036                    } else {
2037                        error
2038                    }
2039                } else {
2040                    error
2041                },
2042            ),
2043        }
2044    }
2045
2046    /// Check that a Megolm event satisfies the sender trust
2047    /// requirement from the decryption settings.
2048    ///
2049    /// If the requirement is not satisfied, returns
2050    /// [`MegolmError::SenderIdentityNotTrusted`].
2051    fn check_sender_trust_requirement(
2052        &self,
2053        session: &InboundGroupSession,
2054        encryption_info: &EncryptionInfo,
2055        trust_requirement: &TrustRequirement,
2056    ) -> MegolmResult<()> {
2057        trace!(
2058            verification_state = ?encryption_info.verification_state,
2059            ?trust_requirement, "check_sender_trust_requirement",
2060        );
2061
2062        // VerificationState::Verified is acceptable for all TrustRequirement levels, so
2063        // let's get that out of the way
2064        let verification_level = match &encryption_info.verification_state {
2065            VerificationState::Verified => return Ok(()),
2066            VerificationState::Unverified(verification_level) => verification_level,
2067        };
2068
2069        let ok = match trust_requirement {
2070            TrustRequirement::Untrusted => true,
2071
2072            TrustRequirement::CrossSignedOrLegacy => {
2073                // `VerificationLevel::UnsignedDevice` and `VerificationLevel::None` correspond
2074                // to `SenderData::DeviceInfo` and `SenderData::UnknownDevice`
2075                // respectively, and those cases may be acceptable if the reason
2076                // for the lack of data is that the sessions were established
2077                // before we started collecting SenderData.
2078                let legacy_session = match session.sender_data {
2079                    SenderData::DeviceInfo { legacy_session, .. } => legacy_session,
2080                    SenderData::UnknownDevice { legacy_session, .. } => legacy_session,
2081                    _ => false,
2082                };
2083
2084                // In the CrossSignedOrLegacy case the following rules apply:
2085                //
2086                // 1. Identities we have not yet verified can be decrypted regardless of the
2087                //    legacy state of the session.
2088                // 2. Devices that aren't signed by the owning identity of the device can only
2089                //    be decrypted if it's a legacy session.
2090                // 3. If we have no information about the device, we should only decrypt if it's
2091                //    a legacy session.
2092                // 4. Anything else, should throw an error.
2093                match (verification_level, legacy_session) {
2094                    // Case 1
2095                    (VerificationLevel::UnverifiedIdentity, _) => true,
2096
2097                    // Case 2
2098                    (VerificationLevel::UnsignedDevice, true) => true,
2099
2100                    // Case 3
2101                    (VerificationLevel::None(_), true) => true,
2102
2103                    // Case 4
2104                    (VerificationLevel::VerificationViolation, _)
2105                    | (VerificationLevel::MismatchedSender, _)
2106                    | (VerificationLevel::UnsignedDevice, false)
2107                    | (VerificationLevel::None(_), false) => false,
2108                }
2109            }
2110
2111            // If cross-signing of identities is required, the only acceptable unverified case
2112            // is when the identity is signed but not yet verified by us.
2113            TrustRequirement::CrossSigned => match verification_level {
2114                VerificationLevel::UnverifiedIdentity => true,
2115
2116                VerificationLevel::VerificationViolation
2117                | VerificationLevel::MismatchedSender
2118                | VerificationLevel::UnsignedDevice
2119                | VerificationLevel::None(_) => false,
2120            },
2121        };
2122
2123        if ok {
2124            Ok(())
2125        } else {
2126            Err(MegolmError::SenderIdentityNotTrusted(verification_level.clone()))
2127        }
2128    }
2129
2130    /// Attempt to retrieve an inbound group session from the store.
2131    ///
2132    /// If the session is not found, checks for withheld reports, and returns a
2133    /// [`MegolmError::MissingRoomKey`] error.
2134    async fn get_inbound_group_session_or_error(
2135        &self,
2136        room_id: &RoomId,
2137        session_id: &str,
2138    ) -> MegolmResult<InboundGroupSession> {
2139        match self.store().get_inbound_group_session(room_id, session_id).await? {
2140            Some(session) => Ok(session),
2141            None => {
2142                let withheld_code = self
2143                    .inner
2144                    .store
2145                    .get_withheld_info(room_id, session_id)
2146                    .await?
2147                    .map(|e| e.content.withheld_code());
2148                Err(MegolmError::MissingRoomKey(withheld_code))
2149            }
2150        }
2151    }
2152
2153    /// Attempt to decrypt an event from a room timeline, returning information
2154    /// on the failure if it fails.
2155    ///
2156    /// # Arguments
2157    ///
2158    /// * `event` - The event that should be decrypted.
2159    ///
2160    /// * `room_id` - The ID of the room where the event was sent to.
2161    ///
2162    /// # Returns
2163    ///
2164    /// The decrypted event, if it was successfully decrypted. Otherwise,
2165    /// information on the failure, unless the failure was due to an
2166    /// internal error, in which case, an `Err` result.
2167    pub async fn try_decrypt_room_event(
2168        &self,
2169        raw_event: &Raw<EncryptedEvent>,
2170        room_id: &RoomId,
2171        decryption_settings: &DecryptionSettings,
2172    ) -> Result<RoomEventDecryptionResult, CryptoStoreError> {
2173        match self.decrypt_room_event_inner(raw_event, room_id, true, decryption_settings).await {
2174            Ok(decrypted) => Ok(RoomEventDecryptionResult::Decrypted(decrypted)),
2175            Err(err) => Ok(RoomEventDecryptionResult::UnableToDecrypt(megolm_error_to_utd_info(
2176                raw_event, err,
2177            )?)),
2178        }
2179    }
2180
2181    /// Decrypt an event from a room timeline.
2182    ///
2183    /// # Arguments
2184    ///
2185    /// * `event` - The event that should be decrypted.
2186    ///
2187    /// * `room_id` - The ID of the room where the event was sent to.
2188    pub async fn decrypt_room_event(
2189        &self,
2190        event: &Raw<EncryptedEvent>,
2191        room_id: &RoomId,
2192        decryption_settings: &DecryptionSettings,
2193    ) -> MegolmResult<DecryptedRoomEvent> {
2194        self.decrypt_room_event_inner(event, room_id, true, decryption_settings).await
2195    }
2196
2197    #[instrument(name = "decrypt_room_event", skip_all, fields(?room_id, event_id, origin_server_ts, sender, algorithm, session_id, message_index, sender_key))]
2198    async fn decrypt_room_event_inner(
2199        &self,
2200        event: &Raw<EncryptedEvent>,
2201        room_id: &RoomId,
2202        decrypt_unsigned: bool,
2203        decryption_settings: &DecryptionSettings,
2204    ) -> MegolmResult<DecryptedRoomEvent> {
2205        let event = event.deserialize()?;
2206
2207        Span::current()
2208            .record("sender", debug(&event.sender))
2209            .record("event_id", debug(&event.event_id))
2210            .record(
2211                "origin_server_ts",
2212                timestamp_to_iso8601(event.origin_server_ts)
2213                    .unwrap_or_else(|| "<out of range>".to_owned()),
2214            )
2215            .record("algorithm", debug(event.content.algorithm()));
2216
2217        let content: SupportedEventEncryptionSchemes<'_> = match &event.content.scheme {
2218            RoomEventEncryptionScheme::MegolmV1AesSha2(c) => {
2219                Span::current().record("sender_key", debug(c.sender_key));
2220                c.into()
2221            }
2222            #[cfg(feature = "experimental-algorithms")]
2223            RoomEventEncryptionScheme::MegolmV2AesSha2(c) => c.into(),
2224            RoomEventEncryptionScheme::Unknown(_) => {
2225                warn!("Received an encrypted room event with an unsupported algorithm");
2226                return Err(EventError::UnsupportedAlgorithm.into());
2227            }
2228        };
2229
2230        Span::current().record("session_id", content.session_id());
2231        Span::current().record("message_index", content.message_index());
2232
2233        let result =
2234            self.decrypt_megolm_events(room_id, &event, &content, decryption_settings).await;
2235
2236        if let Err(e) = &result {
2237            #[cfg(feature = "automatic-room-key-forwarding")]
2238            match e {
2239                // Optimisation should we request if we received a withheld code?
2240                // Maybe for some code there is no point
2241                MegolmError::MissingRoomKey(_)
2242                | MegolmError::Decryption(DecryptionError::UnknownMessageIndex(_, _)) => {
2243                    self.inner
2244                        .key_request_machine
2245                        .create_outgoing_key_request(room_id, &event)
2246                        .await?;
2247                }
2248                _ => {}
2249            }
2250
2251            warn!("Failed to decrypt a room event: {e}");
2252        }
2253
2254        let (mut decrypted_event, encryption_info) = result?;
2255
2256        let mut unsigned_encryption_info = None;
2257        if decrypt_unsigned {
2258            // Try to decrypt encrypted unsigned events.
2259            unsigned_encryption_info = self
2260                .decrypt_unsigned_events(&mut decrypted_event, room_id, decryption_settings)
2261                .await;
2262        }
2263
2264        let decrypted_event =
2265            serde_json::from_value::<Raw<AnyTimelineEvent>>(decrypted_event.into())?;
2266
2267        #[cfg(feature = "experimental-encrypted-state-events")]
2268        self.verify_packed_state_key(&event, &decrypted_event)?;
2269
2270        Ok(DecryptedRoomEvent { event: decrypted_event, encryption_info, unsigned_encryption_info })
2271    }
2272
2273    /// If the passed event is a state event, verify its outer packed state key
2274    /// matches the inner state key once unpacked.
2275    ///
2276    /// * `original` - The original encrypted event received over the wire.
2277    /// * `decrypted` - The decrypted event.
2278    ///
2279    /// # Errors
2280    ///
2281    /// Returns an error if any of the following are true:
2282    ///
2283    /// * The original event's state key failed to unpack;
2284    /// * The decrypted event could not be deserialised;
2285    /// * The unpacked event type does not match the type of the decrypted
2286    ///   event;
2287    /// * The unpacked event state key does not match the state key of the
2288    ///   decrypted event.
2289    #[cfg(feature = "experimental-encrypted-state-events")]
2290    fn verify_packed_state_key(
2291        &self,
2292        original: &EncryptedEvent,
2293        decrypted: &Raw<AnyTimelineEvent>,
2294    ) -> MegolmResult<()> {
2295        use serde::Deserialize;
2296
2297        // We only need to verify state events.
2298        let Some(raw_state_key) = &original.state_key else { return Ok(()) };
2299
2300        // Unpack event type and state key from the raw state key.
2301        let (outer_event_type, outer_state_key) =
2302            raw_state_key.split_once(":").ok_or(MegolmError::StateKeyVerificationFailed)?;
2303
2304        // Helper for deserializing.
2305        #[derive(Deserialize)]
2306        struct PayloadDeserializationHelper {
2307            state_key: String,
2308            #[serde(rename = "type")]
2309            event_type: String,
2310        }
2311
2312        // Deserialize the decrypted event.
2313        let PayloadDeserializationHelper {
2314            state_key: inner_state_key,
2315            event_type: inner_event_type,
2316        } = decrypted
2317            .deserialize_as_unchecked()
2318            .map_err(|_| MegolmError::StateKeyVerificationFailed)?;
2319
2320        // Check event types match, discard if not.
2321        if outer_event_type != inner_event_type {
2322            return Err(MegolmError::StateKeyVerificationFailed);
2323        }
2324
2325        // Check state keys match, discard if not.
2326        if outer_state_key != inner_state_key {
2327            return Err(MegolmError::StateKeyVerificationFailed);
2328        }
2329        Ok(())
2330    }
2331
2332    /// Try to decrypt the events bundled in the `unsigned` object of the given
2333    /// event.
2334    ///
2335    /// # Arguments
2336    ///
2337    /// * `main_event` - The event that may contain bundled encrypted events in
2338    ///   its `unsigned` object.
2339    ///
2340    /// * `room_id` - The ID of the room where the event was sent to.
2341    async fn decrypt_unsigned_events(
2342        &self,
2343        main_event: &mut JsonObject,
2344        room_id: &RoomId,
2345        decryption_settings: &DecryptionSettings,
2346    ) -> Option<BTreeMap<UnsignedEventLocation, UnsignedDecryptionResult>> {
2347        let unsigned = main_event.get_mut("unsigned")?.as_object_mut()?;
2348        let mut unsigned_encryption_info: Option<
2349            BTreeMap<UnsignedEventLocation, UnsignedDecryptionResult>,
2350        > = None;
2351
2352        // Search for an encrypted event in `m.replace`, an edit.
2353        let location = UnsignedEventLocation::RelationsReplace;
2354        let replace = location.find_mut(unsigned);
2355        if let Some(decryption_result) =
2356            self.decrypt_unsigned_event(replace, room_id, decryption_settings).await
2357        {
2358            unsigned_encryption_info
2359                .get_or_insert_with(Default::default)
2360                .insert(location, decryption_result);
2361        }
2362
2363        // Search for an encrypted event in `latest_event` in `m.thread`, the
2364        // latest event of a thread.
2365        let location = UnsignedEventLocation::RelationsThreadLatestEvent;
2366        let thread_latest_event = location.find_mut(unsigned);
2367        if let Some(decryption_result) =
2368            self.decrypt_unsigned_event(thread_latest_event, room_id, decryption_settings).await
2369        {
2370            unsigned_encryption_info
2371                .get_or_insert_with(Default::default)
2372                .insert(location, decryption_result);
2373        }
2374
2375        unsigned_encryption_info
2376    }
2377
2378    /// Try to decrypt the given bundled event.
2379    ///
2380    /// # Arguments
2381    ///
2382    /// * `event` - The bundled event that may be encrypted
2383    ///
2384    /// * `room_id` - The ID of the room where the event was sent to.
2385    fn decrypt_unsigned_event<'a>(
2386        &'a self,
2387        event: Option<&'a mut Value>,
2388        room_id: &'a RoomId,
2389        decryption_settings: &'a DecryptionSettings,
2390    ) -> BoxFuture<'a, Option<UnsignedDecryptionResult>> {
2391        Box::pin(async move {
2392            let event = event?;
2393
2394            let is_encrypted = event
2395                .get("type")
2396                .and_then(|type_| type_.as_str())
2397                .is_some_and(|s| s == "m.room.encrypted");
2398            if !is_encrypted {
2399                return None;
2400            }
2401
2402            let raw_event = serde_json::from_value(event.clone()).ok()?;
2403            match self
2404                .decrypt_room_event_inner(&raw_event, room_id, false, decryption_settings)
2405                .await
2406            {
2407                Ok(decrypted_event) => {
2408                    // Replace the encrypted event.
2409                    *event = serde_json::to_value(decrypted_event.event).ok()?;
2410                    Some(UnsignedDecryptionResult::Decrypted(decrypted_event.encryption_info))
2411                }
2412                Err(err) => {
2413                    // For now, we throw away crypto store errors and just treat the unsigned event
2414                    // as unencrypted. Crypto store errors represent problems with the application
2415                    // rather than normal UTD errors, so they should probably be propagated
2416                    // rather than swallowed.
2417                    let utd_info = megolm_error_to_utd_info(&raw_event, err).ok()?;
2418                    Some(UnsignedDecryptionResult::UnableToDecrypt(utd_info))
2419                }
2420            }
2421        })
2422    }
2423
2424    /// Check if we have the room key for the given event in the store.
2425    ///
2426    /// # Arguments
2427    ///
2428    /// * `event` - The event to get information for.
2429    /// * `room_id` - The ID of the room where the event was sent to.
2430    pub async fn is_room_key_available(
2431        &self,
2432        event: &Raw<EncryptedEvent>,
2433        room_id: &RoomId,
2434    ) -> Result<bool, CryptoStoreError> {
2435        let event = event.deserialize()?;
2436
2437        let (session_id, message_index) = match &event.content.scheme {
2438            RoomEventEncryptionScheme::MegolmV1AesSha2(c) => {
2439                (&c.session_id, c.ciphertext.message_index())
2440            }
2441            #[cfg(feature = "experimental-algorithms")]
2442            RoomEventEncryptionScheme::MegolmV2AesSha2(c) => {
2443                (&c.session_id, c.ciphertext.message_index())
2444            }
2445            RoomEventEncryptionScheme::Unknown(_) => {
2446                // We don't support this encryption algorithm, so clearly don't have its key.
2447                return Ok(false);
2448            }
2449        };
2450
2451        // Check that we have the session in the store, and that its first known index
2452        // predates the index of our message.
2453        Ok(self
2454            .store()
2455            .get_inbound_group_session(room_id, session_id)
2456            .await?
2457            .filter(|s| s.first_known_index() <= message_index)
2458            .is_some())
2459    }
2460
2461    /// Get encryption info for a decrypted timeline event.
2462    ///
2463    /// This recalculates the [`EncryptionInfo`] data that is returned by
2464    /// [`OlmMachine::decrypt_room_event`], based on the current
2465    /// verification status of the sender, etc.
2466    ///
2467    /// Returns an error for an unencrypted event.
2468    ///
2469    /// # Arguments
2470    ///
2471    /// * `event` - The event to get information for.
2472    /// * `room_id` - The ID of the room where the event was sent to.
2473    #[instrument(skip(self, event), fields(event_id, sender, session_id))]
2474    pub async fn get_room_event_encryption_info(
2475        &self,
2476        event: &Raw<EncryptedEvent>,
2477        room_id: &RoomId,
2478    ) -> MegolmResult<Arc<EncryptionInfo>> {
2479        let event = event.deserialize()?;
2480
2481        let content: SupportedEventEncryptionSchemes<'_> = match &event.content.scheme {
2482            RoomEventEncryptionScheme::MegolmV1AesSha2(c) => c.into(),
2483            #[cfg(feature = "experimental-algorithms")]
2484            RoomEventEncryptionScheme::MegolmV2AesSha2(c) => c.into(),
2485            RoomEventEncryptionScheme::Unknown(_) => {
2486                return Err(EventError::UnsupportedAlgorithm.into());
2487            }
2488        };
2489
2490        Span::current()
2491            .record("sender", debug(&event.sender))
2492            .record("event_id", debug(&event.event_id))
2493            .record("session_id", content.session_id());
2494
2495        self.get_session_encryption_info(room_id, content.session_id(), &event.sender).await
2496    }
2497
2498    /// Get encryption info for an event decrypted with a megolm session.
2499    ///
2500    /// This recalculates the [`EncryptionInfo`] data that is returned by
2501    /// [`OlmMachine::decrypt_room_event`], based on the current
2502    /// verification status of the sender, etc.
2503    ///
2504    /// Returns an error if the session can't be found.
2505    ///
2506    /// # Arguments
2507    ///
2508    /// * `room_id` - The ID of the room where the session is being used.
2509    /// * `session_id` - The ID of the session to get information for.
2510    /// * `sender` - The (claimed) sender of the event where the session was
2511    ///   used.
2512    pub async fn get_session_encryption_info(
2513        &self,
2514        room_id: &RoomId,
2515        session_id: &str,
2516        sender: &UserId,
2517    ) -> MegolmResult<Arc<EncryptionInfo>> {
2518        let session = self.get_inbound_group_session_or_error(room_id, session_id).await?;
2519        self.get_encryption_info(&session, sender).await
2520    }
2521
2522    /// Update the list of tracked users.
2523    ///
2524    /// The OlmMachine maintains a list of users whose devices we are keeping
2525    /// track of: these are known as "tracked users". These must be users
2526    /// that we share a room with, so that the server sends us updates for
2527    /// their device lists.
2528    ///
2529    /// # Arguments
2530    ///
2531    /// * `users` - An iterator over user ids that should be added to the list
2532    ///   of tracked users
2533    ///
2534    /// Any users that hadn't been seen before will be flagged for a key query
2535    /// immediately, and whenever [`OlmMachine::receive_sync_changes()`]
2536    /// receives a "changed" notification for that user in the future.
2537    ///
2538    /// Users that were already in the list are unaffected.
2539    pub async fn update_tracked_users(
2540        &self,
2541        users: impl IntoIterator<Item = &UserId>,
2542    ) -> StoreResult<()> {
2543        self.inner.identity_manager.update_tracked_users(users).await
2544    }
2545
2546    /// Mark all tracked users as dirty.
2547    ///
2548    /// All users *whose device lists we are tracking* are flagged as needing a
2549    /// key query. Users whose devices we are not tracking are ignored.
2550    pub async fn mark_all_tracked_users_as_dirty(&self) -> StoreResult<()> {
2551        self.inner
2552            .identity_manager
2553            .mark_all_tracked_users_as_dirty(self.inner.store.cache().await?)
2554            .await
2555    }
2556
2557    async fn wait_if_user_pending(
2558        &self,
2559        user_id: &UserId,
2560        timeout: Option<Duration>,
2561    ) -> StoreResult<()> {
2562        if let Some(timeout) = timeout {
2563            let cache = self.store().cache().await?;
2564            self.inner
2565                .identity_manager
2566                .key_query_manager
2567                .wait_if_user_key_query_pending(cache, timeout, user_id)
2568                .await?;
2569        }
2570        Ok(())
2571    }
2572
2573    /// Get a specific device of a user.
2574    ///
2575    /// # Arguments
2576    ///
2577    /// * `user_id` - The unique id of the user that the device belongs to.
2578    ///
2579    /// * `device_id` - The unique id of the device.
2580    ///
2581    /// * `timeout` - The amount of time we should wait before returning if the
2582    /// user's device list has been marked as stale. **Note**, this assumes that
2583    /// the requests from [`OlmMachine::outgoing_requests`] are being
2584    /// processed and sent out.
2585    ///
2586    /// Returns a `Device` if one is found and the crypto store didn't throw an
2587    /// error.
2588    ///
2589    /// # Examples
2590    ///
2591    /// ```
2592    /// # use matrix_sdk_crypto::OlmMachine;
2593    /// # use ruma::{device_id, user_id};
2594    /// # let alice = user_id!("@alice:example.org").to_owned();
2595    /// # futures_executor::block_on(async {
2596    /// # let machine = OlmMachine::new(&alice, device_id!("DEVICEID")).await;
2597    /// let device = machine.get_device(&alice, device_id!("DEVICEID"), None).await;
2598    ///
2599    /// println!("{:?}", device);
2600    /// # });
2601    /// ```
2602    #[instrument(skip(self))]
2603    pub async fn get_device(
2604        &self,
2605        user_id: &UserId,
2606        device_id: &DeviceId,
2607        timeout: Option<Duration>,
2608    ) -> StoreResult<Option<Device>> {
2609        self.wait_if_user_pending(user_id, timeout).await?;
2610        self.store().get_device(user_id, device_id).await
2611    }
2612
2613    /// Get the cross signing user identity of a user.
2614    ///
2615    /// # Arguments
2616    ///
2617    /// * `user_id` - The unique id of the user that the identity belongs to
2618    ///
2619    /// * `timeout` - The amount of time we should wait before returning if the
2620    /// user's device list has been marked as stale. **Note**, this assumes that
2621    /// the requests from [`OlmMachine::outgoing_requests`] are being
2622    /// processed and sent out.
2623    ///
2624    /// Returns a [`UserIdentity`] enum if one is found and the crypto store
2625    /// didn't throw an error.
2626    #[instrument(skip(self))]
2627    pub async fn get_identity(
2628        &self,
2629        user_id: &UserId,
2630        timeout: Option<Duration>,
2631    ) -> StoreResult<Option<UserIdentity>> {
2632        self.wait_if_user_pending(user_id, timeout).await?;
2633        self.store().get_identity(user_id).await
2634    }
2635
2636    /// Get a map holding all the devices of an user.
2637    ///
2638    /// # Arguments
2639    ///
2640    /// * `user_id` - The unique id of the user that the devices belong to.
2641    ///
2642    /// * `timeout` - The amount of time we should wait before returning if the
2643    /// user's device list has been marked as stale. **Note**, this assumes that
2644    /// the requests from [`OlmMachine::outgoing_requests`] are being
2645    /// processed and sent out.
2646    ///
2647    /// # Examples
2648    ///
2649    /// ```
2650    /// # use matrix_sdk_crypto::OlmMachine;
2651    /// # use ruma::{device_id, user_id};
2652    /// # let alice = user_id!("@alice:example.org").to_owned();
2653    /// # futures_executor::block_on(async {
2654    /// # let machine = OlmMachine::new(&alice, device_id!("DEVICEID")).await;
2655    /// let devices = machine.get_user_devices(&alice, None).await.unwrap();
2656    ///
2657    /// for device in devices.devices() {
2658    ///     println!("{:?}", device);
2659    /// }
2660    /// # });
2661    /// ```
2662    #[instrument(skip(self))]
2663    pub async fn get_user_devices(
2664        &self,
2665        user_id: &UserId,
2666        timeout: Option<Duration>,
2667    ) -> StoreResult<UserDevices> {
2668        self.wait_if_user_pending(user_id, timeout).await?;
2669        self.store().get_user_devices(user_id).await
2670    }
2671
2672    /// Get the status of the private cross signing keys.
2673    ///
2674    /// This can be used to check which private cross signing keys we have
2675    /// stored locally.
2676    pub async fn cross_signing_status(&self) -> CrossSigningStatus {
2677        self.inner.user_identity.lock().await.status().await
2678    }
2679
2680    /// Export all the private cross signing keys we have.
2681    ///
2682    /// The export will contain the seed for the ed25519 keys as a unpadded
2683    /// base64 encoded string.
2684    ///
2685    /// This method returns `None` if we don't have any private cross signing
2686    /// keys.
2687    pub async fn export_cross_signing_keys(&self) -> StoreResult<Option<CrossSigningKeyExport>> {
2688        let master_key = self.store().export_secret(&SecretName::CrossSigningMasterKey).await?;
2689        let self_signing_key =
2690            self.store().export_secret(&SecretName::CrossSigningSelfSigningKey).await?;
2691        let user_signing_key =
2692            self.store().export_secret(&SecretName::CrossSigningUserSigningKey).await?;
2693
2694        Ok(if master_key.is_none() && self_signing_key.is_none() && user_signing_key.is_none() {
2695            None
2696        } else {
2697            Some(CrossSigningKeyExport { master_key, self_signing_key, user_signing_key })
2698        })
2699    }
2700
2701    /// Import our private cross signing keys.
2702    ///
2703    /// The export needs to contain the seed for the ed25519 keys as an unpadded
2704    /// base64 encoded string.
2705    pub async fn import_cross_signing_keys(
2706        &self,
2707        export: CrossSigningKeyExport,
2708    ) -> Result<CrossSigningStatus, SecretImportError> {
2709        self.store().import_cross_signing_keys(export).await
2710    }
2711
2712    async fn sign_with_master_key(
2713        &self,
2714        message: &str,
2715    ) -> Result<(OwnedDeviceKeyId, Ed25519Signature), SignatureError> {
2716        let identity = &*self.inner.user_identity.lock().await;
2717        let key_id = identity.master_key_id().await.ok_or(SignatureError::MissingSigningKey)?;
2718
2719        let signature = identity.sign(message).await?;
2720
2721        Ok((key_id, signature))
2722    }
2723
2724    /// Sign the given message using our device key and if available cross
2725    /// signing master key.
2726    ///
2727    /// Presently, this should only be used for signing the server-side room
2728    /// key backups.
2729    pub async fn sign(&self, message: &str) -> Result<Signatures, CryptoStoreError> {
2730        let mut signatures = Signatures::new();
2731
2732        {
2733            let cache = self.inner.store.cache().await?;
2734            let account = cache.account().await?;
2735            let key_id = account.signing_key_id();
2736            let signature = account.sign(message);
2737            signatures.add_signature(self.user_id().to_owned(), key_id, signature);
2738        }
2739
2740        match self.sign_with_master_key(message).await {
2741            Ok((key_id, signature)) => {
2742                signatures.add_signature(self.user_id().to_owned(), key_id, signature);
2743            }
2744            Err(e) => {
2745                warn!(error = ?e, "Couldn't sign the message using the cross signing master key")
2746            }
2747        }
2748
2749        Ok(signatures)
2750    }
2751
2752    /// Get a reference to the backup related state machine.
2753    ///
2754    /// This state machine can be used to incrementally backup all room keys to
2755    /// the server.
2756    pub fn backup_machine(&self) -> &BackupMachine {
2757        &self.inner.backup_machine
2758    }
2759
2760    /// Syncs the database and in-memory generation counter.
2761    ///
2762    /// This requires that the crypto store lock has been acquired already.
2763    pub async fn initialize_crypto_store_generation(
2764        &self,
2765        generation: &Mutex<Option<u64>>,
2766    ) -> StoreResult<()> {
2767        // Avoid reentrant initialization by taking the lock for the entire's function
2768        // scope.
2769        let mut gen_guard = generation.lock().await;
2770
2771        let prev_generation =
2772            self.inner.store.get_custom_value(Self::CURRENT_GENERATION_STORE_KEY).await?;
2773
2774        let gen = match prev_generation {
2775            Some(val) => {
2776                // There was a value in the store. We need to signal that we're a different
2777                // process, so we don't just reuse the value but increment it.
2778                u64::from_le_bytes(val.try_into().map_err(|_| {
2779                    CryptoStoreError::InvalidLockGeneration("invalid format".to_owned())
2780                })?)
2781                .wrapping_add(1)
2782            }
2783            None => 0,
2784        };
2785
2786        tracing::debug!("Initialising crypto store generation at {}", gen);
2787
2788        self.inner
2789            .store
2790            .set_custom_value(Self::CURRENT_GENERATION_STORE_KEY, gen.to_le_bytes().to_vec())
2791            .await?;
2792
2793        *gen_guard = Some(gen);
2794
2795        Ok(())
2796    }
2797
2798    /// If needs be, update the local and on-disk crypto store generation.
2799    ///
2800    /// ## Requirements
2801    ///
2802    /// - This assumes that `initialize_crypto_store_generation` has been called
2803    ///   beforehand.
2804    /// - This requires that the crypto store lock has been acquired.
2805    ///
2806    /// # Arguments
2807    ///
2808    /// * `generation` - The in-memory generation counter (or rather, the
2809    ///   `Mutex` wrapping it). This defines the "expected" generation on entry,
2810    ///   and, if we determine an update is needed, is updated to hold the "new"
2811    ///   generation.
2812    ///
2813    /// # Returns
2814    ///
2815    /// A tuple containing:
2816    ///
2817    /// * A `bool`, set to `true` if another process has updated the generation
2818    ///   number in the `Store` since our expected value, and as such we've
2819    ///   incremented and updated it in the database. Otherwise, `false`.
2820    ///
2821    /// * The (possibly updated) generation counter.
2822    pub async fn maintain_crypto_store_generation(
2823        &'_ self,
2824        generation: &Mutex<Option<u64>>,
2825    ) -> StoreResult<(bool, u64)> {
2826        let mut gen_guard = generation.lock().await;
2827
2828        // The database value must be there:
2829        // - either we could initialize beforehand, thus write into the database,
2830        // - or we couldn't, and then another process was holding onto the database's
2831        //   lock, thus
2832        // has written a generation counter in there.
2833        let actual_gen = self
2834            .inner
2835            .store
2836            .get_custom_value(Self::CURRENT_GENERATION_STORE_KEY)
2837            .await?
2838            .ok_or_else(|| {
2839                CryptoStoreError::InvalidLockGeneration("counter missing in store".to_owned())
2840            })?;
2841
2842        let actual_gen =
2843            u64::from_le_bytes(actual_gen.try_into().map_err(|_| {
2844                CryptoStoreError::InvalidLockGeneration("invalid format".to_owned())
2845            })?);
2846
2847        let new_gen = match gen_guard.as_ref() {
2848            Some(expected_gen) => {
2849                if actual_gen == *expected_gen {
2850                    return Ok((false, actual_gen));
2851                }
2852                // Increment the biggest, and store it everywhere.
2853                actual_gen.max(*expected_gen).wrapping_add(1)
2854            }
2855            None => {
2856                // Some other process hold onto the lock when initializing, so we must reload.
2857                // Increment database value, and store it everywhere.
2858                actual_gen.wrapping_add(1)
2859            }
2860        };
2861
2862        tracing::debug!(
2863            "Crypto store generation mismatch: previously known was {:?}, actual is {:?}, next is {}",
2864            *gen_guard,
2865            actual_gen,
2866            new_gen
2867        );
2868
2869        // Update known value.
2870        *gen_guard = Some(new_gen);
2871
2872        // Update value in database.
2873        self.inner
2874            .store
2875            .set_custom_value(Self::CURRENT_GENERATION_STORE_KEY, new_gen.to_le_bytes().to_vec())
2876            .await?;
2877
2878        Ok((true, new_gen))
2879    }
2880
2881    /// Manage dehydrated devices.
2882    pub fn dehydrated_devices(&self) -> DehydratedDevices {
2883        DehydratedDevices { inner: self.to_owned() }
2884    }
2885
2886    /// Get the stored encryption settings for the given room, such as the
2887    /// encryption algorithm or whether to encrypt only for trusted devices.
2888    ///
2889    /// These settings can be modified via [`OlmMachine::set_room_settings`].
2890    pub async fn room_settings(&self, room_id: &RoomId) -> StoreResult<Option<RoomSettings>> {
2891        // There's not much to do here: it's just exposed for symmetry with
2892        // `set_room_settings`.
2893        self.inner.store.get_room_settings(room_id).await
2894    }
2895
2896    /// Store encryption settings for the given room.
2897    ///
2898    /// This method checks if the new settings are "safe" -- ie, that they do
2899    /// not represent a downgrade in encryption security from any previous
2900    /// settings. Attempts to downgrade security will result in a
2901    /// [`SetRoomSettingsError::EncryptionDowngrade`].
2902    ///
2903    /// If the settings are valid, they will be persisted to the crypto store.
2904    /// These settings are not used directly by this library, but the saved
2905    /// settings can be retrieved via [`OlmMachine::room_settings`].
2906    pub async fn set_room_settings(
2907        &self,
2908        room_id: &RoomId,
2909        new_settings: &RoomSettings,
2910    ) -> Result<(), SetRoomSettingsError> {
2911        let store = &self.inner.store;
2912
2913        // We want to make sure that we do not race against a second concurrent call to
2914        // `set_room_settings`. By way of an easy way to do so, we start a
2915        // StoreTransaction. There's no need to commit() it: we're just using it as a
2916        // lock guard.
2917        let _store_transaction = store.transaction().await;
2918
2919        let old_settings = store.get_room_settings(room_id).await?;
2920
2921        // We want to make sure that the change to the room settings does not represent
2922        // a downgrade in security. The [E2EE implementation guide] recommends:
2923        //
2924        //  > This flag should **not** be cleared if a later `m.room.encryption` event
2925        //  > changes the configuration.
2926        //
2927        // (However, it doesn't really address how to handle changes to the rotation
2928        // parameters, etc.) For now at least, we are very conservative here:
2929        // any new settings are rejected if they differ from the existing settings.
2930        // merit improvement (cf https://github.com/element-hq/element-meta/issues/69).
2931        //
2932        // [E2EE implementation guide]: https://matrix.org/docs/matrix-concepts/end-to-end-encryption/#handling-an-m-room-encryption-state-event
2933        if let Some(old_settings) = old_settings {
2934            if old_settings != *new_settings {
2935                return Err(SetRoomSettingsError::EncryptionDowngrade);
2936            } else {
2937                // nothing to do here
2938                return Ok(());
2939            }
2940        }
2941
2942        // Make sure that the new settings are valid
2943        match new_settings.algorithm {
2944            EventEncryptionAlgorithm::MegolmV1AesSha2 => (),
2945
2946            #[cfg(feature = "experimental-algorithms")]
2947            EventEncryptionAlgorithm::MegolmV2AesSha2 => (),
2948
2949            _ => {
2950                warn!(
2951                    ?room_id,
2952                    "Rejecting invalid encryption algorithm {}", new_settings.algorithm
2953                );
2954                return Err(SetRoomSettingsError::InvalidSettings);
2955            }
2956        }
2957
2958        // The new settings are acceptable, so let's save them.
2959        store
2960            .save_changes(Changes {
2961                room_settings: HashMap::from([(room_id.to_owned(), new_settings.clone())]),
2962                ..Default::default()
2963            })
2964            .await?;
2965
2966        Ok(())
2967    }
2968
2969    /// Returns whether this `OlmMachine` is the same another one.
2970    ///
2971    /// Useful for testing purposes only.
2972    #[cfg(any(feature = "testing", test))]
2973    pub fn same_as(&self, other: &OlmMachine) -> bool {
2974        Arc::ptr_eq(&self.inner, &other.inner)
2975    }
2976
2977    /// Testing purposes only.
2978    #[cfg(any(feature = "testing", test))]
2979    pub async fn uploaded_key_count(&self) -> Result<u64, CryptoStoreError> {
2980        let cache = self.inner.store.cache().await?;
2981        let account = cache.account().await?;
2982        Ok(account.uploaded_key_count())
2983    }
2984
2985    /// Returns the identity manager.
2986    #[cfg(test)]
2987    pub(crate) fn identity_manager(&self) -> &IdentityManager {
2988        &self.inner.identity_manager
2989    }
2990
2991    /// Returns a store key, only useful for testing purposes.
2992    #[cfg(test)]
2993    pub(crate) fn key_for_has_migrated_verification_latch() -> &'static str {
2994        Self::HAS_MIGRATED_VERIFICATION_LATCH
2995    }
2996}
2997
2998fn sender_data_to_verification_state(
2999    sender_data: SenderData,
3000    session_has_been_imported: bool,
3001) -> (VerificationState, Option<OwnedDeviceId>) {
3002    match sender_data {
3003        SenderData::UnknownDevice { owner_check_failed: false, .. } => {
3004            let device_link_problem = if session_has_been_imported {
3005                DeviceLinkProblem::InsecureSource
3006            } else {
3007                DeviceLinkProblem::MissingDevice
3008            };
3009
3010            (VerificationState::Unverified(VerificationLevel::None(device_link_problem)), None)
3011        }
3012        SenderData::UnknownDevice { owner_check_failed: true, .. } => (
3013            VerificationState::Unverified(VerificationLevel::None(
3014                DeviceLinkProblem::InsecureSource,
3015            )),
3016            None,
3017        ),
3018        SenderData::DeviceInfo { device_keys, .. } => (
3019            VerificationState::Unverified(VerificationLevel::UnsignedDevice),
3020            Some(device_keys.device_id),
3021        ),
3022        SenderData::VerificationViolation(KnownSenderData { device_id, .. }) => {
3023            (VerificationState::Unverified(VerificationLevel::VerificationViolation), device_id)
3024        }
3025        SenderData::SenderUnverified(KnownSenderData { device_id, .. }) => {
3026            (VerificationState::Unverified(VerificationLevel::UnverifiedIdentity), device_id)
3027        }
3028        SenderData::SenderVerified(KnownSenderData { device_id, .. }) => {
3029            (VerificationState::Verified, device_id)
3030        }
3031    }
3032}
3033
3034/// A set of requests to be executed when bootstrapping cross-signing using
3035/// [`OlmMachine::bootstrap_cross_signing`].
3036#[derive(Debug, Clone)]
3037pub struct CrossSigningBootstrapRequests {
3038    /// An optional request to upload a device key.
3039    ///
3040    /// Should be sent first, if present.
3041    ///
3042    /// If present, its result must be processed back with
3043    /// `OlmMachine::mark_request_as_sent`.
3044    pub upload_keys_req: Option<OutgoingRequest>,
3045
3046    /// Request to upload the cross-signing keys.
3047    ///
3048    /// Should be sent second.
3049    pub upload_signing_keys_req: UploadSigningKeysRequest,
3050
3051    /// Request to upload key signatures, including those for the cross-signing
3052    /// keys, and maybe some for the optional uploaded key too.
3053    ///
3054    /// Should be sent last.
3055    pub upload_signatures_req: UploadSignaturesRequest,
3056}
3057
3058/// Data contained from a sync response and that needs to be processed by the
3059/// OlmMachine.
3060#[derive(Debug)]
3061pub struct EncryptionSyncChanges<'a> {
3062    /// The list of to-device events received in the sync.
3063    pub to_device_events: Vec<Raw<AnyToDeviceEvent>>,
3064    /// The mapping of changed and left devices, per user, as returned in the
3065    /// sync response.
3066    pub changed_devices: &'a DeviceLists,
3067    /// The number of one time keys, as returned in the sync response.
3068    pub one_time_keys_counts: &'a BTreeMap<OneTimeKeyAlgorithm, UInt>,
3069    /// An optional list of fallback keys.
3070    pub unused_fallback_keys: Option<&'a [OneTimeKeyAlgorithm]>,
3071    /// A next-batch token obtained from a to-device sync query.
3072    pub next_batch_token: Option<String>,
3073}
3074
3075/// Convert a [`MegolmError`] into an [`UnableToDecryptInfo`] or a
3076/// [`CryptoStoreError`].
3077///
3078/// Most `MegolmError` codes are converted into a suitable
3079/// `UnableToDecryptInfo`. The exception is [`MegolmError::Store`], which
3080/// represents a problem with our datastore rather than with the message itself,
3081/// and is therefore returned as a `CryptoStoreError`.
3082fn megolm_error_to_utd_info(
3083    raw_event: &Raw<EncryptedEvent>,
3084    error: MegolmError,
3085) -> Result<UnableToDecryptInfo, CryptoStoreError> {
3086    use MegolmError::*;
3087    let reason = match error {
3088        EventError(_) => UnableToDecryptReason::MalformedEncryptedEvent,
3089        Decode(_) => UnableToDecryptReason::MalformedEncryptedEvent,
3090        MissingRoomKey(maybe_withheld) => {
3091            UnableToDecryptReason::MissingMegolmSession { withheld_code: maybe_withheld }
3092        }
3093        Decryption(DecryptionError::UnknownMessageIndex(_, _)) => {
3094            UnableToDecryptReason::UnknownMegolmMessageIndex
3095        }
3096        Decryption(_) => UnableToDecryptReason::MegolmDecryptionFailure,
3097        JsonError(_) => UnableToDecryptReason::PayloadDeserializationFailure,
3098        MismatchedIdentityKeys(_) => UnableToDecryptReason::MismatchedIdentityKeys,
3099        SenderIdentityNotTrusted(level) => UnableToDecryptReason::SenderIdentityNotTrusted(level),
3100        #[cfg(feature = "experimental-encrypted-state-events")]
3101        StateKeyVerificationFailed => UnableToDecryptReason::StateKeyVerificationFailed,
3102
3103        // Pass through crypto store errors, which indicate a problem with our
3104        // application, rather than a UTD.
3105        Store(error) => Err(error)?,
3106    };
3107
3108    let session_id = raw_event.deserialize().ok().and_then(|ev| match ev.content.scheme {
3109        RoomEventEncryptionScheme::MegolmV1AesSha2(s) => Some(s.session_id),
3110        #[cfg(feature = "experimental-algorithms")]
3111        RoomEventEncryptionScheme::MegolmV2AesSha2(s) => Some(s.session_id),
3112        RoomEventEncryptionScheme::Unknown(_) => None,
3113    });
3114
3115    Ok(UnableToDecryptInfo { session_id, reason })
3116}
3117
3118/// An error that can occur during [`OlmMachine::decrypt_to_device_event`]:
3119///
3120/// * because decryption failed, or
3121///
3122/// * because the sender device was not verified when we are in strict "exclude
3123///   insecure devices" mode, or
3124///
3125/// * because the sender device was a dehydrated device, which should never send
3126///   any to-device messages.
3127#[derive(Debug, thiserror::Error)]
3128pub(crate) enum DecryptToDeviceError {
3129    #[error("An Olm error occurred meaning we failed to decrypt the event")]
3130    OlmError(#[from] OlmError),
3131
3132    #[error("The event was sent from a dehydrated device")]
3133    FromDehydratedDevice,
3134}
3135
3136impl From<CryptoStoreError> for DecryptToDeviceError {
3137    fn from(value: CryptoStoreError) -> Self {
3138        Self::OlmError(value.into())
3139    }
3140}
3141
3142#[cfg(test)]
3143impl From<DecryptToDeviceError> for OlmError {
3144    /// Unwrap the `OlmError` inside this error, or panic if this does not
3145    /// contain an `OlmError`.
3146    fn from(value: DecryptToDeviceError) -> Self {
3147        match value {
3148            DecryptToDeviceError::OlmError(olm_error) => olm_error,
3149            DecryptToDeviceError::FromDehydratedDevice => {
3150                panic!("Expected an OlmError but found FromDehydratedDevice")
3151            }
3152        }
3153    }
3154}
3155
3156#[cfg(test)]
3157pub(crate) mod test_helpers;
3158
3159#[cfg(test)]
3160pub(crate) mod tests;