matrix_sdk_crypto/identities/
device.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
15use std::{
16    collections::{BTreeMap, HashMap},
17    ops::Deref,
18    sync::{
19        atomic::{AtomicBool, Ordering},
20        Arc,
21    },
22};
23
24use matrix_sdk_common::locks::RwLock;
25use ruma::{
26    api::client::keys::upload_signatures::v3::Request as SignatureUploadRequest,
27    events::{key::verification::VerificationMethod, AnyToDeviceEventContent},
28    serde::Raw,
29    DeviceId, DeviceKeyAlgorithm, DeviceKeyId, MilliSecondsSinceUnixEpoch, OwnedDeviceId,
30    OwnedDeviceKeyId, UInt, UserId,
31};
32use serde::{Deserialize, Serialize};
33use serde_json::Value;
34use tracing::{instrument, trace};
35use vodozemac::{olm::SessionConfig, Curve25519PublicKey, Ed25519PublicKey};
36
37use super::{atomic_bool_deserializer, atomic_bool_serializer};
38#[cfg(any(test, feature = "testing", doc))]
39use crate::OlmMachine;
40use crate::{
41    error::{MismatchedIdentityKeysError, OlmError, OlmResult, SignatureError},
42    identities::{OwnUserIdentityData, UserIdentityData},
43    olm::{
44        InboundGroupSession, OutboundGroupSession, Session, ShareInfo, SignedJsonObject, VerifyJson,
45    },
46    session_manager::{withheld_code_for_device_for_share_strategy, CollectStrategy},
47    store::{
48        caches::SequenceNumber,
49        types::{Changes, DeviceChanges},
50        CryptoStoreWrapper, Result as StoreResult,
51    },
52    types::{
53        events::{
54            forwarded_room_key::ForwardedRoomKeyContent,
55            room::encrypted::ToDeviceEncryptedEventContent, EventType,
56        },
57        requests::{OutgoingVerificationRequest, ToDeviceRequest},
58        DeviceKey, DeviceKeys, EventEncryptionAlgorithm, Signatures, SignedKey,
59    },
60    verification::VerificationMachine,
61    Account, Sas, VerificationRequest,
62};
63
64pub enum MaybeEncryptedRoomKey {
65    Encrypted {
66        // `Box` the session to reduce the size of `Encrypted`.
67        used_session: Box<Session>,
68        // `Box` the session to reduce the size of `Encrypted`.
69        share_info: Box<ShareInfo>,
70        message: Raw<AnyToDeviceEventContent>,
71    },
72    /// We could not encrypt a message to this device because there is no active
73    /// Olm session.
74    MissingSession,
75}
76
77/// A read-only version of a `Device`.
78#[derive(Clone, Serialize, Deserialize)]
79pub struct DeviceData {
80    #[serde(alias = "inner")]
81    pub(crate) device_keys: Arc<DeviceKeys>,
82    #[serde(
83        serialize_with = "atomic_bool_serializer",
84        deserialize_with = "atomic_bool_deserializer"
85    )]
86    deleted: Arc<AtomicBool>,
87    trust_state: Arc<RwLock<LocalTrust>>,
88    /// Flag remembering if we successfully sent an `m.no_olm` withheld code to
89    /// this device.
90    #[serde(
91        default,
92        serialize_with = "atomic_bool_serializer",
93        deserialize_with = "atomic_bool_deserializer"
94    )]
95    withheld_code_sent: Arc<AtomicBool>,
96    /// First time this device was seen in milliseconds since epoch.
97    /// Default to epoch for migration purpose.
98    #[serde(default = "default_timestamp")]
99    first_time_seen_ts: MilliSecondsSinceUnixEpoch,
100    /// The number of times the device has tried to unwedge Olm sessions with
101    /// us.
102    #[serde(default)]
103    pub(crate) olm_wedging_index: SequenceNumber,
104}
105
106fn default_timestamp() -> MilliSecondsSinceUnixEpoch {
107    MilliSecondsSinceUnixEpoch(UInt::default())
108}
109
110#[cfg(not(tarpaulin_include))]
111impl std::fmt::Debug for DeviceData {
112    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
113        f.debug_struct("DeviceData")
114            .field("user_id", &self.user_id())
115            .field("device_id", &self.device_id())
116            .field("display_name", &self.display_name())
117            .field("keys", self.keys())
118            .field("deleted", &self.deleted.load(Ordering::SeqCst))
119            .field("trust_state", &self.trust_state)
120            .field("withheld_code_sent", &self.withheld_code_sent)
121            .finish()
122    }
123}
124
125/// A device represents a E2EE capable client of an user.
126#[derive(Clone)]
127pub struct Device {
128    pub(crate) inner: DeviceData,
129    pub(crate) verification_machine: VerificationMachine,
130    pub(crate) own_identity: Option<OwnUserIdentityData>,
131    pub(crate) device_owner_identity: Option<UserIdentityData>,
132}
133
134#[cfg(not(tarpaulin_include))]
135impl std::fmt::Debug for Device {
136    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
137        f.debug_struct("Device").field("device", &self.inner).finish()
138    }
139}
140
141impl Deref for Device {
142    type Target = DeviceData;
143
144    fn deref(&self) -> &Self::Target {
145        &self.inner
146    }
147}
148
149impl Device {
150    /// Start a interactive verification with this `Device`
151    ///
152    /// Returns a `Sas` object and a to-device request that needs to be sent
153    /// out.
154    ///
155    /// This method has been deprecated in the spec and the
156    /// [`request_verification()`] method should be used instead.
157    ///
158    /// [`request_verification()`]: #method.request_verification
159    pub async fn start_verification(&self) -> StoreResult<(Sas, ToDeviceRequest)> {
160        let (sas, request) = self.verification_machine.start_sas(self.inner.clone()).await?;
161
162        if let OutgoingVerificationRequest::ToDevice(r) = request {
163            Ok((sas, r))
164        } else {
165            panic!("Invalid verification request type");
166        }
167    }
168
169    /// Is this our own device?
170    pub fn is_our_own_device(&self) -> bool {
171        let own_ed25519_key = self.verification_machine.store.account.identity_keys.ed25519;
172        let own_curve25519_key = self.verification_machine.store.account.identity_keys.curve25519;
173
174        self.user_id() == self.verification_machine.own_user_id()
175            && self.device_id() == self.verification_machine.own_device_id()
176            && self.ed25519_key().is_some_and(|k| k == own_ed25519_key)
177            && self.curve25519_key().is_some_and(|k| k == own_curve25519_key)
178    }
179
180    /// Does the given `InboundGroupSession` belong to this device?
181    ///
182    /// An `InboundGroupSession` is exchanged between devices as an Olm
183    /// encrypted `m.room_key` event. This method determines if this `Device`
184    /// can be confirmed as the creator and owner of the `m.room_key`.
185    pub fn is_owner_of_session(
186        &self,
187        session: &InboundGroupSession,
188    ) -> Result<bool, MismatchedIdentityKeysError> {
189        if session.has_been_imported() {
190            // An imported room key means that we did not receive the room key as a
191            // `m.room_key` event when the room key was initially exchanged.
192            //
193            // This could mean a couple of things:
194            //      1. We received the room key as a `m.forwarded_room_key`.
195            //      2. We imported the room key through a file export.
196            //      3. We imported the room key through a backup.
197            //
198            // To be certain that a `Device` is the owner of a room key we need to have a
199            // proof that the `Curve25519` key of this `Device` was used to
200            // initially exchange the room key. This proof is provided by the Olm decryption
201            // step, see below for further clarification.
202            //
203            // Each of the above room key methods that receive room keys do not contain this
204            // proof and we received only a claim that the room key is tied to a
205            // `Curve25519` key.
206            //
207            // Since there's no way to verify that the claim is true, we say that we don't
208            // know that the room key belongs to this device.
209            Ok(false)
210        } else if let Some(key) =
211            session.signing_keys().get(&DeviceKeyAlgorithm::Ed25519).and_then(|k| k.ed25519())
212        {
213            // Room keys are received as an `m.room.encrypted` to-device message using the
214            // `m.olm` algorithm. Upon decryption of the `m.room.encrypted` to-device
215            // message, the decrypted content will contain also an `Ed25519` public key[1].
216            //
217            // The inclusion of this key means that the `Curve25519` key of the `Device` and
218            // Olm `Session`, established using the DH authentication of the
219            // double ratchet, "binds" the `Ed25519` key of the `Device`. In other words, it
220            // prevents an attack in which Mallory publishes Bob's public `Curve25519` key
221            // as her own, and subsequently forwards an Olm message she received from Bob to
222            // Alice, claiming that she, Mallory, originated the Olm message (leading Alice
223            // to believe that Mallory also sent the messages in the subsequent Megolm
224            // session).
225            //
226            // On the other hand, the `Ed25519` key binds the `Curve25519` key
227            // using a signature which is uploaded to the server as
228            // `device_keys` and downloaded by us using a `/keys/query` request.
229            //
230            // A `Device` is considered to be the owner of a room key iff:
231            //     1. The `Curve25519` key that was used to establish the Olm `Session` that
232            //        was used to decrypt the to-device message is binding the `Ed25519` key
233            //        of this `Device` via the content of the to-device message, and:
234            //     2. The `Ed25519` key of this device has signed a `device_keys` object
235            //        that contains the `Curve25519` key from step 1.
236            //
237            // We don't need to check the signature of the `Device` here, since we don't
238            // accept a `Device` unless it has a valid `Ed25519` signature.
239            //
240            // We do check that the `Curve25519` that was used to decrypt the event carrying
241            // the `m.room_key` and the `Ed25519` key that was part of the
242            // decrypted content matches the keys found in this `Device`.
243            //
244            // ```text
245            //                                              ┌───────────────────────┐
246            //                                              │ EncryptedToDeviceEvent│
247            //                                              └───────────────────────┘
248            //                                                         │
249            //    ┌──────────────────────────────────┐                 │
250            //    │              Device              │                 ▼
251            //    ├──────────────────────────────────┤        ┌──────────────────┐
252            //    │            Device Keys           │        │      Session     │
253            //    ├────────────────┬─────────────────┤        ├──────────────────┤
254            //    │   Ed25519 Key  │  Curve25519 Key │◄──────►│  Curve25519 Key  │
255            //    └────────────────┴─────────────────┘        └──────────────────┘
256            //            ▲                                            │
257            //            │                                            │
258            //            │                                            │ Decrypt
259            //            │                                            │
260            //            │                                            ▼
261            //            │                                 ┌───────────────────────┐
262            //            │                                 │  DecryptedOlmV1Event  │
263            //            │                                 ├───────────────────────┤
264            //            │                                 │         keys          │
265            //            │                                 ├───────────────────────┤
266            //            └────────────────────────────────►│       Ed25519 Key     │
267            //                                              └───────────────────────┘
268            // ```
269            //
270            // [1]: https://spec.matrix.org/v1.5/client-server-api/#molmv1curve25519-aes-sha2
271            let ed25519_comparison = self.ed25519_key().map(|k| k == key);
272            let curve25519_comparison = self.curve25519_key().map(|k| k == session.sender_key());
273
274            match (ed25519_comparison, curve25519_comparison) {
275                // If we have any of the keys but they don't turn out to match, refuse to decrypt
276                // instead.
277                (_, Some(false)) | (Some(false), _) => Err(MismatchedIdentityKeysError {
278                    key_ed25519: key.into(),
279                    device_ed25519: self.ed25519_key().map(Into::into),
280                    key_curve25519: session.sender_key().into(),
281                    device_curve25519: self.curve25519_key().map(Into::into),
282                }),
283                // If both keys match, we have ourselves an owner.
284                (Some(true), Some(true)) => Ok(true),
285                // In the remaining cases, the device is missing at least one of the required
286                // identity keys, so we default to a negative answer.
287                _ => Ok(false),
288            }
289        } else {
290            Ok(false)
291        }
292    }
293
294    /// Is this device cross signed by its owner?
295    pub fn is_cross_signed_by_owner(&self) -> bool {
296        self.device_owner_identity
297            .as_ref()
298            .is_some_and(|owner_identity| self.inner.is_cross_signed_by_owner(owner_identity))
299    }
300
301    /// Is the device owner verified by us?
302    pub fn is_device_owner_verified(&self) -> bool {
303        self.device_owner_identity.as_ref().is_some_and(|id| match id {
304            UserIdentityData::Own(own_identity) => own_identity.is_verified(),
305            UserIdentityData::Other(other_identity) => {
306                self.own_identity.as_ref().is_some_and(|oi| oi.is_identity_verified(other_identity))
307            }
308        })
309    }
310
311    /// Request an interactive verification with this `Device`.
312    ///
313    /// Returns a `VerificationRequest` object and a to-device request that
314    /// needs to be sent out.
315    pub fn request_verification(&self) -> (VerificationRequest, OutgoingVerificationRequest) {
316        self.request_verification_helper(None)
317    }
318
319    /// Request an interactive verification with this `Device`.
320    ///
321    /// Returns a `VerificationRequest` object and a to-device request that
322    /// needs to be sent out.
323    ///
324    /// # Arguments
325    ///
326    /// * `methods` - The verification methods that we want to support.
327    pub fn request_verification_with_methods(
328        &self,
329        methods: Vec<VerificationMethod>,
330    ) -> (VerificationRequest, OutgoingVerificationRequest) {
331        self.request_verification_helper(Some(methods))
332    }
333
334    fn request_verification_helper(
335        &self,
336        methods: Option<Vec<VerificationMethod>>,
337    ) -> (VerificationRequest, OutgoingVerificationRequest) {
338        self.verification_machine.request_to_device_verification(
339            self.user_id(),
340            vec![self.device_id().to_owned()],
341            methods,
342        )
343    }
344
345    /// Get the most recently created session that belongs to this device.
346    pub(crate) async fn get_most_recent_session(&self) -> OlmResult<Option<Session>> {
347        self.inner.get_most_recent_session(self.verification_machine.store.inner()).await
348    }
349
350    /// Is this device considered to be verified.
351    ///
352    /// This method returns true if either [`is_locally_trusted()`] returns true
353    /// or if [`is_cross_signing_trusted()`] returns true.
354    ///
355    /// [`is_locally_trusted()`]: #method.is_locally_trusted
356    /// [`is_cross_signing_trusted()`]: #method.is_cross_signing_trusted
357    pub fn is_verified(&self) -> bool {
358        self.inner.is_verified(&self.own_identity, &self.device_owner_identity)
359    }
360
361    /// Is this device considered to be verified using cross signing.
362    pub fn is_cross_signing_trusted(&self) -> bool {
363        self.inner.is_cross_signing_trusted(&self.own_identity, &self.device_owner_identity)
364    }
365
366    /// Manually verify this device.
367    ///
368    /// This method will attempt to sign the device using our private cross
369    /// signing key.
370    ///
371    /// This method will always fail if the device belongs to someone else, we
372    /// can only sign our own devices.
373    ///
374    /// It can also fail if we don't have the private part of our self-signing
375    /// key.
376    ///
377    /// Returns a request that needs to be sent out for the device to be marked
378    /// as verified.
379    pub async fn verify(&self) -> Result<SignatureUploadRequest, SignatureError> {
380        if self.user_id() == self.verification_machine.own_user_id() {
381            Ok(self
382                .verification_machine
383                .store
384                .private_identity
385                .lock()
386                .await
387                .sign_device(&self.inner)
388                .await?)
389        } else {
390            Err(SignatureError::UserIdMismatch)
391        }
392    }
393
394    /// Set the local trust state of the device to the given state.
395    ///
396    /// This won't affect any cross signing trust state, this only sets a flag
397    /// marking to have the given trust state.
398    ///
399    /// # Arguments
400    ///
401    /// * `trust_state` - The new trust state that should be set for the device.
402    pub async fn set_local_trust(&self, trust_state: LocalTrust) -> StoreResult<()> {
403        self.inner.set_trust_state(trust_state);
404
405        let changes = Changes {
406            devices: DeviceChanges { changed: vec![self.inner.clone()], ..Default::default() },
407            ..Default::default()
408        };
409
410        self.verification_machine.store.save_changes(changes).await
411    }
412
413    /// Encrypt the given content for this `Device`.
414    ///
415    /// # Arguments
416    ///
417    /// * `content` - The content of the event that should be encrypted.
418    pub(crate) async fn encrypt(
419        &self,
420        event_type: &str,
421        content: impl Serialize,
422    ) -> OlmResult<(Session, Raw<ToDeviceEncryptedEventContent>)> {
423        self.inner.encrypt(self.verification_machine.store.inner(), event_type, content).await
424    }
425
426    /// Encrypt the given inbound group session as a forwarded room key for this
427    /// device.
428    pub async fn encrypt_room_key_for_forwarding(
429        &self,
430        session: InboundGroupSession,
431        message_index: Option<u32>,
432    ) -> OlmResult<(Session, Raw<ToDeviceEncryptedEventContent>)> {
433        let content: ForwardedRoomKeyContent = {
434            let export = if let Some(index) = message_index {
435                session.export_at_index(index).await
436            } else {
437                session.export().await
438            };
439
440            export.try_into()?
441        };
442
443        let event_type = content.event_type().to_owned();
444
445        self.encrypt(&event_type, content).await
446    }
447
448    /// Encrypt an event for this device.
449    ///
450    /// Beware that the 1-to-1 session must be established prior to this
451    /// call by using the [`OlmMachine::get_missing_sessions`] method.
452    ///
453    /// Notable limitation: The caller is responsible for sending the encrypted
454    /// event to the target device, this encryption method supports out-of-order
455    /// messages to a certain extent (2000 messages), if multiple messages are
456    /// encrypted using this method they should be sent in the same order as
457    /// they are encrypted.
458    ///
459    /// *Note*: To instead encrypt an event meant for a room use the
460    /// [`OlmMachine::encrypt_room_event()`] method instead.
461    ///
462    /// # Arguments
463    /// * `event_type` - The type of the event to be sent.
464    /// * `content` - The content of the event to be sent. This should be a type
465    ///   that implements the `Serialize` trait.
466    /// * `share_strategy` - The share strategy to use to determine whether we
467    ///   should encrypt to the device.
468    ///
469    /// # Returns
470    ///
471    /// The encrypted raw content to be shared with your preferred transport
472    /// layer (usually to-device), [`OlmError::MissingSession`] if there is
473    /// no established session with the device.
474    pub async fn encrypt_event_raw(
475        &self,
476        event_type: &str,
477        content: &Value,
478        share_strategy: CollectStrategy,
479    ) -> OlmResult<Raw<ToDeviceEncryptedEventContent>> {
480        if let Some(withheld_code) = withheld_code_for_device_for_share_strategy(
481            &self.inner,
482            share_strategy,
483            &self.own_identity,
484            &self.device_owner_identity,
485        )
486        .await?
487        {
488            return Err(OlmError::Withheld(withheld_code));
489        }
490
491        let (used_session, raw_encrypted) = self.encrypt(event_type, content).await?;
492
493        // Persist the used session
494        self.verification_machine
495            .store
496            .save_changes(Changes { sessions: vec![used_session], ..Default::default() })
497            .await?;
498
499        Ok(raw_encrypted)
500    }
501
502    /// True if this device is an [MSC3814](https://github.com/matrix-org/matrix-spec-proposals/pull/3814) dehydrated device.
503    pub fn is_dehydrated(&self) -> bool {
504        self.inner.is_dehydrated()
505    }
506}
507
508/// A read only view over all devices belonging to a user.
509#[derive(Debug)]
510pub struct UserDevices {
511    pub(crate) inner: HashMap<OwnedDeviceId, DeviceData>,
512    pub(crate) verification_machine: VerificationMachine,
513    pub(crate) own_identity: Option<OwnUserIdentityData>,
514    pub(crate) device_owner_identity: Option<UserIdentityData>,
515}
516
517impl UserDevices {
518    /// Get the specific device with the given device ID.
519    pub fn get(&self, device_id: &DeviceId) -> Option<Device> {
520        self.inner.get(device_id).map(|d| Device {
521            inner: d.clone(),
522            verification_machine: self.verification_machine.clone(),
523            own_identity: self.own_identity.clone(),
524            device_owner_identity: self.device_owner_identity.clone(),
525        })
526    }
527
528    fn own_user_id(&self) -> &UserId {
529        self.verification_machine.own_user_id()
530    }
531
532    fn own_device_id(&self) -> &DeviceId {
533        self.verification_machine.own_device_id()
534    }
535
536    /// Returns true if there is at least one devices of this user that is
537    /// considered to be verified, false otherwise.
538    ///
539    /// This won't consider your own device as verified, as your own device is
540    /// always implicitly verified.
541    pub fn is_any_verified(&self) -> bool {
542        self.inner
543            .values()
544            .filter(|d| {
545                !(d.user_id() == self.own_user_id() && d.device_id() == self.own_device_id())
546            })
547            .any(|d| d.is_verified(&self.own_identity, &self.device_owner_identity))
548    }
549
550    /// Iterator over all the device ids of the user devices.
551    pub fn keys(&self) -> impl Iterator<Item = &DeviceId> {
552        self.inner.keys().map(Deref::deref)
553    }
554
555    /// Iterator over all the devices of the user devices.
556    pub fn devices(&self) -> impl Iterator<Item = Device> + '_ {
557        self.inner.values().map(move |d| Device {
558            inner: d.clone(),
559            verification_machine: self.verification_machine.clone(),
560            own_identity: self.own_identity.clone(),
561            device_owner_identity: self.device_owner_identity.clone(),
562        })
563    }
564}
565
566/// The local trust state of a device.
567#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
568#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
569pub enum LocalTrust {
570    /// The device has been verified and is trusted.
571    Verified = 0,
572    /// The device been blacklisted from communicating.
573    BlackListed = 1,
574    /// The trust state of the device is being ignored.
575    Ignored = 2,
576    /// The trust state is unset.
577    Unset = 3,
578}
579
580impl From<i64> for LocalTrust {
581    fn from(state: i64) -> Self {
582        match state {
583            0 => LocalTrust::Verified,
584            1 => LocalTrust::BlackListed,
585            2 => LocalTrust::Ignored,
586            3 => LocalTrust::Unset,
587            _ => LocalTrust::Unset,
588        }
589    }
590}
591
592impl DeviceData {
593    /// Create a new Device, this constructor skips signature verification of
594    /// the keys, `TryFrom` should be used for completely new devices we
595    /// receive.
596    pub fn new(device_keys: DeviceKeys, trust_state: LocalTrust) -> Self {
597        Self {
598            device_keys: device_keys.into(),
599            trust_state: Arc::new(RwLock::new(trust_state)),
600            deleted: Arc::new(AtomicBool::new(false)),
601            withheld_code_sent: Arc::new(AtomicBool::new(false)),
602            first_time_seen_ts: MilliSecondsSinceUnixEpoch::now(),
603            olm_wedging_index: Default::default(),
604        }
605    }
606
607    /// The user id of the device owner.
608    pub fn user_id(&self) -> &UserId {
609        &self.device_keys.user_id
610    }
611
612    /// The unique ID of the device.
613    pub fn device_id(&self) -> &DeviceId {
614        &self.device_keys.device_id
615    }
616
617    /// Get the human readable name of the device.
618    pub fn display_name(&self) -> Option<&str> {
619        self.device_keys.unsigned.device_display_name.as_deref()
620    }
621
622    /// Get the key of the given key algorithm belonging to this device.
623    pub fn get_key(&self, algorithm: DeviceKeyAlgorithm) -> Option<&DeviceKey> {
624        self.device_keys.get_key(algorithm)
625    }
626
627    /// Get the Curve25519 key of the given device.
628    pub fn curve25519_key(&self) -> Option<Curve25519PublicKey> {
629        self.device_keys.curve25519_key()
630    }
631
632    /// Get the Ed25519 key of the given device.
633    pub fn ed25519_key(&self) -> Option<Ed25519PublicKey> {
634        self.device_keys.ed25519_key()
635    }
636
637    /// Get a map containing all the device keys.
638    pub fn keys(&self) -> &BTreeMap<OwnedDeviceKeyId, DeviceKey> {
639        &self.device_keys.keys
640    }
641
642    /// Get a map containing all the device signatures.
643    pub fn signatures(&self) -> &Signatures {
644        &self.device_keys.signatures
645    }
646
647    /// Get the trust state of the device.
648    pub fn local_trust_state(&self) -> LocalTrust {
649        *self.trust_state.read()
650    }
651
652    /// Is the device locally marked as trusted.
653    pub fn is_locally_trusted(&self) -> bool {
654        self.local_trust_state() == LocalTrust::Verified
655    }
656
657    /// Is the device locally marked as blacklisted.
658    ///
659    /// Blacklisted devices won't receive any group sessions.
660    pub fn is_blacklisted(&self) -> bool {
661        self.local_trust_state() == LocalTrust::BlackListed
662    }
663
664    /// Set the trust state of the device to the given state.
665    ///
666    /// Note: This should only done in the crypto store where the trust state
667    /// can be stored.
668    pub(crate) fn set_trust_state(&self, state: LocalTrust) {
669        *self.trust_state.write() = state;
670    }
671
672    pub(crate) fn mark_withheld_code_as_sent(&self) {
673        self.withheld_code_sent.store(true, Ordering::Relaxed)
674    }
675
676    /// Returns true if the `m.no_olm` withheld code was already sent to this
677    /// device.
678    pub fn was_withheld_code_sent(&self) -> bool {
679        self.withheld_code_sent.load(Ordering::Relaxed)
680    }
681
682    /// Get the list of algorithms this device supports.
683    pub fn algorithms(&self) -> &[EventEncryptionAlgorithm] {
684        &self.device_keys.algorithms
685    }
686
687    /// Does this device support any of our known Olm encryption algorithms.
688    pub fn supports_olm(&self) -> bool {
689        #[cfg(feature = "experimental-algorithms")]
690        {
691            self.algorithms().contains(&EventEncryptionAlgorithm::OlmV1Curve25519AesSha2)
692                || self.algorithms().contains(&EventEncryptionAlgorithm::OlmV2Curve25519AesSha2)
693        }
694
695        #[cfg(not(feature = "experimental-algorithms"))]
696        {
697            self.algorithms().contains(&EventEncryptionAlgorithm::OlmV1Curve25519AesSha2)
698        }
699    }
700
701    /// Find and return the most recently created Olm [`Session`] we are sharing
702    /// with this device.
703    pub(crate) async fn get_most_recent_session(
704        &self,
705        store: &CryptoStoreWrapper,
706    ) -> OlmResult<Option<Session>> {
707        if let Some(sender_key) = self.curve25519_key() {
708            if let Some(sessions) = store.get_sessions(&sender_key.to_base64()).await? {
709                let mut sessions = sessions.lock().await;
710                sessions.sort_by_key(|s| s.creation_time);
711
712                Ok(sessions.last().cloned())
713            } else {
714                Ok(None)
715            }
716        } else {
717            Ok(None)
718        }
719    }
720
721    /// Does this device support the olm.v2.curve25519-aes-sha2 encryption
722    /// algorithm.
723    #[cfg(feature = "experimental-algorithms")]
724    pub fn supports_olm_v2(&self) -> bool {
725        self.algorithms().contains(&EventEncryptionAlgorithm::OlmV2Curve25519AesSha2)
726    }
727
728    /// Get the optimal `SessionConfig` for this device.
729    pub fn olm_session_config(&self) -> SessionConfig {
730        #[cfg(feature = "experimental-algorithms")]
731        if self.supports_olm_v2() {
732            SessionConfig::version_2()
733        } else {
734            SessionConfig::version_1()
735        }
736
737        #[cfg(not(feature = "experimental-algorithms"))]
738        SessionConfig::version_1()
739    }
740
741    /// Is the device deleted.
742    pub fn is_deleted(&self) -> bool {
743        self.deleted.load(Ordering::Relaxed)
744    }
745
746    pub(crate) fn is_verified(
747        &self,
748        own_identity: &Option<OwnUserIdentityData>,
749        device_owner: &Option<UserIdentityData>,
750    ) -> bool {
751        self.is_locally_trusted() || self.is_cross_signing_trusted(own_identity, device_owner)
752    }
753
754    pub(crate) fn is_cross_signing_trusted(
755        &self,
756        own_identity: &Option<OwnUserIdentityData>,
757        device_owner: &Option<UserIdentityData>,
758    ) -> bool {
759        own_identity.as_ref().zip(device_owner.as_ref()).is_some_and(
760            |(own_identity, device_identity)| {
761                match device_identity {
762                    UserIdentityData::Own(_) => {
763                        own_identity.is_verified() && own_identity.is_device_signed(self)
764                    }
765
766                    // If it's a device from someone else, first check
767                    // that our user has verified the other user and then
768                    // check if the other user has signed this device.
769                    UserIdentityData::Other(device_identity) => {
770                        own_identity.is_identity_verified(device_identity)
771                            && device_identity.is_device_signed(self)
772                    }
773                }
774            },
775        )
776    }
777
778    pub(crate) fn is_cross_signed_by_owner(
779        &self,
780        device_owner_identity: &UserIdentityData,
781    ) -> bool {
782        match device_owner_identity {
783            // If it's one of our own devices, just check that
784            // we signed the device.
785            UserIdentityData::Own(identity) => identity.is_device_signed(self),
786            // If it's a device from someone else, check
787            // if the other user has signed this device.
788            UserIdentityData::Other(device_identity) => device_identity.is_device_signed(self),
789        }
790    }
791
792    /// Encrypt the given content for this device.
793    ///
794    /// # Arguments
795    ///
796    /// * `store` - The crypto store. Used to find an established Olm session
797    ///   for this device.
798    /// * `event_type` - The type of the event that should be encrypted.
799    /// * `content` - The content of the event that should be encrypted.
800    ///
801    /// # Returns
802    ///
803    /// On success, a tuple `(session, content)`, where `session` is the Olm
804    /// [`Session`] that was used to encrypt the content, and `content` is
805    /// the content for the `m.room.encrypted` to-device event.
806    ///
807    /// If an Olm session has not already been established with this device,
808    /// returns `Err(OlmError::MissingSession)`.
809    #[instrument(
810        skip_all,
811        fields(
812            recipient = ?self.user_id(),
813            recipient_device = ?self.device_id(),
814            recipient_key = ?self.curve25519_key(),
815            event_type,
816            message_id,
817        ))
818    ]
819    pub(crate) async fn encrypt(
820        &self,
821        store: &CryptoStoreWrapper,
822        event_type: &str,
823        content: impl Serialize,
824    ) -> OlmResult<(Session, Raw<ToDeviceEncryptedEventContent>)> {
825        #[cfg(not(target_family = "wasm"))]
826        let message_id = ulid::Ulid::new().to_string();
827        #[cfg(target_family = "wasm")]
828        let message_id = ruma::TransactionId::new().to_string();
829
830        tracing::Span::current().record("message_id", &message_id);
831
832        let session = self.get_most_recent_session(store).await?;
833
834        if let Some(mut session) = session {
835            let message = session.encrypt(self, event_type, content, Some(message_id)).await?;
836            Ok((session, message))
837        } else {
838            trace!("Trying to encrypt an event for a device, but no Olm session is found.");
839            Err(OlmError::MissingSession)
840        }
841    }
842
843    pub(crate) async fn maybe_encrypt_room_key(
844        &self,
845        store: &CryptoStoreWrapper,
846        session: OutboundGroupSession,
847    ) -> OlmResult<MaybeEncryptedRoomKey> {
848        let content = session.as_content().await;
849        let message_index = session.message_index().await;
850        let event_type = content.event_type().to_owned();
851
852        match self.encrypt(store, &event_type, content).await {
853            Ok((session, encrypted)) => Ok(MaybeEncryptedRoomKey::Encrypted {
854                share_info: Box::new(ShareInfo::new_shared(
855                    session.sender_key().to_owned(),
856                    message_index,
857                    self.olm_wedging_index,
858                )),
859                used_session: Box::new(session),
860                message: encrypted.cast(),
861            }),
862
863            Err(OlmError::MissingSession) => Ok(MaybeEncryptedRoomKey::MissingSession),
864            Err(e) => Err(e),
865        }
866    }
867
868    /// Update a device with a new device keys struct.
869    ///
870    /// Returns `true` if any changes were made to the data.
871    pub(crate) fn update_device(
872        &mut self,
873        device_keys: &DeviceKeys,
874    ) -> Result<bool, SignatureError> {
875        self.verify_device_keys(device_keys)?;
876
877        if self.user_id() != device_keys.user_id || self.device_id() != device_keys.device_id {
878            Err(SignatureError::UserIdMismatch)
879        } else if self.ed25519_key() != device_keys.ed25519_key() {
880            Err(SignatureError::SigningKeyChanged(
881                self.ed25519_key().map(Box::new),
882                device_keys.ed25519_key().map(Box::new),
883            ))
884        } else if self.device_keys.as_ref() != device_keys {
885            trace!(
886                user_id = ?self.user_id(),
887                device_id = ?self.device_id(),
888                keys = ?self.keys(),
889                "Updated a device",
890            );
891
892            self.device_keys = device_keys.clone().into();
893
894            Ok(true)
895        } else {
896            // no changes needed
897            Ok(false)
898        }
899    }
900
901    /// Return the device keys
902    pub fn as_device_keys(&self) -> &DeviceKeys {
903        &self.device_keys
904    }
905
906    /// Check if the given JSON is signed by this device key.
907    ///
908    /// This method should only be used if an object's signature needs to be
909    /// checked multiple times, and you'd like to avoid performing the
910    /// canonicalization step each time.
911    ///
912    /// **Note**: Use this method with caution, the `canonical_json` needs to be
913    /// correctly canonicalized and make sure that the object you are checking
914    /// the signature for is allowed to be signed by a device.
915    pub(crate) fn has_signed_raw(
916        &self,
917        signatures: &Signatures,
918        canonical_json: &str,
919    ) -> Result<(), SignatureError> {
920        let key = self.ed25519_key().ok_or(SignatureError::MissingSigningKey)?;
921        let user_id = self.user_id();
922        let key_id = &DeviceKeyId::from_parts(DeviceKeyAlgorithm::Ed25519, self.device_id());
923
924        key.verify_canonicalized_json(user_id, key_id, signatures, canonical_json)
925    }
926
927    fn has_signed(&self, signed_object: &impl SignedJsonObject) -> Result<(), SignatureError> {
928        let key = self.ed25519_key().ok_or(SignatureError::MissingSigningKey)?;
929        let user_id = self.user_id();
930        let key_id = &DeviceKeyId::from_parts(DeviceKeyAlgorithm::Ed25519, self.device_id());
931
932        key.verify_json(user_id, key_id, signed_object)
933    }
934
935    pub(crate) fn verify_device_keys(
936        &self,
937        device_keys: &DeviceKeys,
938    ) -> Result<(), SignatureError> {
939        self.has_signed(device_keys)
940    }
941
942    pub(crate) fn verify_one_time_key(
943        &self,
944        one_time_key: &SignedKey,
945    ) -> Result<(), SignatureError> {
946        self.has_signed(one_time_key)
947    }
948
949    /// Mark the device as deleted.
950    pub(crate) fn mark_as_deleted(&self) {
951        self.deleted.store(true, Ordering::Relaxed);
952    }
953
954    #[cfg(any(test, feature = "testing"))]
955    #[allow(dead_code)]
956    /// Generate the Device from a reference of an OlmMachine.
957    pub async fn from_machine_test_helper(
958        machine: &OlmMachine,
959    ) -> Result<DeviceData, crate::CryptoStoreError> {
960        Ok(DeviceData::from_account(&*machine.store().cache().await?.account().await?))
961    }
962
963    /// Create [`DeviceData`] from an [`Account`].
964    ///
965    /// We will have our own device data in the store once we receive a
966    /// `/keys/query` response, but this is useful to create it before we
967    /// receive such a response.
968    ///
969    /// It also makes it easier to check that the server doesn't lie about our
970    /// own device.
971    ///
972    /// *Don't* use this after we received a `/keys/query` response, other
973    /// users/devices might add signatures to our own device, which can't be
974    /// replicated locally.
975    pub fn from_account(account: &Account) -> DeviceData {
976        let device_keys = account.device_keys();
977        let mut device = DeviceData::try_from(&device_keys)
978            .expect("Creating a device from our own account should always succeed");
979        device.first_time_seen_ts = account.creation_local_time();
980
981        device
982    }
983
984    /// Get the local timestamp of when this device was first persisted, in
985    /// milliseconds since epoch (client local time).
986    pub fn first_time_seen_ts(&self) -> MilliSecondsSinceUnixEpoch {
987        self.first_time_seen_ts
988    }
989
990    /// True if this device is an [MSC3814](https://github.com/matrix-org/matrix-spec-proposals/pull/3814) dehydrated device.
991    pub fn is_dehydrated(&self) -> bool {
992        self.device_keys.dehydrated.unwrap_or(false)
993    }
994}
995
996impl TryFrom<&DeviceKeys> for DeviceData {
997    type Error = SignatureError;
998
999    fn try_from(device_keys: &DeviceKeys) -> Result<Self, Self::Error> {
1000        let device = Self {
1001            device_keys: device_keys.clone().into(),
1002            deleted: Arc::new(AtomicBool::new(false)),
1003            trust_state: Arc::new(RwLock::new(LocalTrust::Unset)),
1004            withheld_code_sent: Arc::new(AtomicBool::new(false)),
1005            first_time_seen_ts: MilliSecondsSinceUnixEpoch::now(),
1006            olm_wedging_index: Default::default(),
1007        };
1008
1009        device.verify_device_keys(device_keys)?;
1010        Ok(device)
1011    }
1012}
1013
1014impl PartialEq for DeviceData {
1015    fn eq(&self, other: &Self) -> bool {
1016        self.user_id() == other.user_id() && self.device_id() == other.device_id()
1017    }
1018}
1019
1020/// Testing Facilities for Device Management
1021#[cfg(any(test, feature = "testing"))]
1022#[allow(dead_code)]
1023pub(crate) mod testing {
1024    use serde_json::json;
1025
1026    use crate::{identities::DeviceData, types::DeviceKeys};
1027
1028    /// Generate default DeviceKeys for tests
1029    pub fn device_keys() -> DeviceKeys {
1030        let device_keys = json!({
1031          "algorithms": vec![
1032              "m.olm.v1.curve25519-aes-sha2",
1033              "m.megolm.v1.aes-sha2"
1034          ],
1035          "device_id": "BNYQQWUMXO",
1036          "user_id": "@example:localhost",
1037          "keys": {
1038              "curve25519:BNYQQWUMXO": "xfgbLIC5WAl1OIkpOzoxpCe8FsRDT6nch7NQsOb15nc",
1039              "ed25519:BNYQQWUMXO": "2/5LWJMow5zhJqakV88SIc7q/1pa8fmkfgAzx72w9G4"
1040          },
1041          "signatures": {
1042              "@example:localhost": {
1043                  "ed25519:BNYQQWUMXO": "kTwMrbsLJJM/uFGOj/oqlCaRuw7i9p/6eGrTlXjo8UJMCFAetoyWzoMcF35vSe4S6FTx8RJmqX6rM7ep53MHDQ"
1044              }
1045          },
1046          "unsigned": {
1047              "device_display_name": "Alice's mobile phone"
1048          }
1049        });
1050
1051        serde_json::from_value(device_keys).unwrap()
1052    }
1053
1054    /// Generate default [`DeviceData`] for tests
1055    pub fn get_device() -> DeviceData {
1056        let device_keys = device_keys();
1057        DeviceData::try_from(&device_keys).unwrap()
1058    }
1059}
1060
1061#[cfg(test)]
1062pub(crate) mod tests {
1063    use ruma::{user_id, MilliSecondsSinceUnixEpoch};
1064    use serde_json::json;
1065    use vodozemac::{Curve25519PublicKey, Ed25519PublicKey};
1066
1067    use super::testing::{device_keys, get_device};
1068    use crate::{identities::LocalTrust, DeviceData};
1069
1070    #[test]
1071    fn create_a_device() {
1072        let now = MilliSecondsSinceUnixEpoch::now();
1073        let user_id = user_id!("@example:localhost");
1074        let device_id = "BNYQQWUMXO";
1075
1076        let device = get_device();
1077
1078        assert_eq!(user_id, device.user_id());
1079        assert_eq!(device_id, device.device_id());
1080        assert_eq!(device.algorithms().len(), 2);
1081        assert_eq!(LocalTrust::Unset, device.local_trust_state());
1082        assert_eq!("Alice's mobile phone", device.display_name().unwrap());
1083        assert_eq!(
1084            device.curve25519_key().unwrap(),
1085            Curve25519PublicKey::from_base64("xfgbLIC5WAl1OIkpOzoxpCe8FsRDT6nch7NQsOb15nc")
1086                .unwrap(),
1087        );
1088        assert_eq!(
1089            device.ed25519_key().unwrap(),
1090            Ed25519PublicKey::from_base64("2/5LWJMow5zhJqakV88SIc7q/1pa8fmkfgAzx72w9G4").unwrap(),
1091        );
1092
1093        let then = MilliSecondsSinceUnixEpoch::now();
1094
1095        assert!(device.first_time_seen_ts() >= now);
1096        assert!(device.first_time_seen_ts() <= then);
1097    }
1098
1099    #[test]
1100    fn update_a_device() {
1101        let mut device = get_device();
1102
1103        assert_eq!("Alice's mobile phone", device.display_name().unwrap());
1104
1105        let display_name = "Alice's work computer".to_owned();
1106
1107        let mut device_keys = device_keys();
1108        device_keys.unsigned.device_display_name = Some(display_name.clone());
1109        assert!(device.update_device(&device_keys).unwrap());
1110        assert_eq!(&display_name, device.display_name().as_ref().unwrap());
1111
1112        // A second call to `update_device` with the same data should return `false`.
1113        assert!(!device.update_device(&device_keys).unwrap());
1114    }
1115
1116    #[test]
1117    #[allow(clippy::redundant_clone)]
1118    fn delete_a_device() {
1119        let device = get_device();
1120        assert!(!device.is_deleted());
1121
1122        let device_clone = device.clone();
1123
1124        device.mark_as_deleted();
1125        assert!(device.is_deleted());
1126        assert!(device_clone.is_deleted());
1127    }
1128
1129    #[test]
1130    fn deserialize_device() {
1131        let user_id = user_id!("@example:localhost");
1132        let device_id = "BNYQQWUMXO";
1133
1134        let device = json!({
1135            "inner": {
1136                "user_id": user_id,
1137                "device_id": device_id,
1138                "algorithms": ["m.olm.v1.curve25519-aes-sha2","m.megolm.v1.aes-sha2"],
1139                "keys": {
1140                    "curve25519:BNYQQWUMXO": "xfgbLIC5WAl1OIkpOzoxpCe8FsRDT6nch7NQsOb15nc",
1141                    "ed25519:BNYQQWUMXO": "2/5LWJMow5zhJqakV88SIc7q/1pa8fmkfgAzx72w9G4"
1142                },
1143                "signatures": {
1144                    "@example:localhost": {
1145                        "ed25519:BNYQQWUMXO": "kTwMrbsLJJM/uFGOj/oqlCaRuw7i9p/6eGrTlXjo8UJMCFAetoyWzoMcF35vSe4S6FTx8RJmqX6rM7ep53MHDQ"
1146                    }
1147                },
1148                "unsigned": {
1149                    "device_display_name": "Alice's mobile phone"
1150                }
1151            },
1152            "deleted": false,
1153            "trust_state": "Verified",
1154            "withheld_code_sent": false,
1155            "first_time_seen_ts": 1696931068314u64
1156        });
1157
1158        let device: DeviceData =
1159            serde_json::from_value(device).expect("We should be able to deserialize our device");
1160
1161        assert_eq!(user_id, device.user_id());
1162        assert_eq!(device_id, device.device_id());
1163        assert_eq!(device.algorithms().len(), 2);
1164        assert_eq!(LocalTrust::Verified, device.local_trust_state());
1165        assert_eq!("Alice's mobile phone", device.display_name().unwrap());
1166        assert_eq!(
1167            device.curve25519_key().unwrap(),
1168            Curve25519PublicKey::from_base64("xfgbLIC5WAl1OIkpOzoxpCe8FsRDT6nch7NQsOb15nc")
1169                .unwrap(),
1170        );
1171        assert_eq!(
1172            device.ed25519_key().unwrap(),
1173            Ed25519PublicKey::from_base64("2/5LWJMow5zhJqakV88SIc7q/1pa8fmkfgAzx72w9G4").unwrap(),
1174        );
1175    }
1176}