matrix_sdk/encryption/identities/
users.rs

1// Copyright 2021 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::collections::BTreeMap;
16
17use matrix_sdk_base::{
18    RoomMemberships,
19    crypto::{CryptoStoreError, UserIdentity as CryptoUserIdentity, types::MasterPubkey},
20};
21use ruma::{
22    OwnedUserId, UserId,
23    events::{key::verification::VerificationMethod, room::message::RoomMessageEventContent},
24};
25
26use super::{ManualVerifyError, RequestVerificationError};
27use crate::{Client, encryption::verification::VerificationRequest};
28
29/// Updates about [`UserIdentity`]s which got received over the `/keys/query`
30/// endpoint.
31#[derive(Clone, Debug, Default)]
32pub struct IdentityUpdates {
33    /// The list of newly discovered user identities .
34    ///
35    /// A identity being in this list does not necessarily mean that the
36    /// identity was just created, it just means that it's the first time
37    /// we're seeing this identity.
38    pub new: BTreeMap<OwnedUserId, UserIdentity>,
39    /// The list of changed identities.
40    pub changed: BTreeMap<OwnedUserId, UserIdentity>,
41}
42
43impl IdentityUpdates {
44    pub(crate) fn new(
45        client: Client,
46        updates: matrix_sdk_base::crypto::store::types::IdentityUpdates,
47    ) -> Self {
48        let new = updates
49            .new
50            .into_iter()
51            .map(|(user_id, identity)| (user_id, UserIdentity::new(client.to_owned(), identity)))
52            .collect();
53
54        let changed = updates
55            .changed
56            .into_iter()
57            .map(|(user_id, identity)| (user_id, UserIdentity::new(client.to_owned(), identity)))
58            .collect();
59
60        Self { new, changed }
61    }
62}
63
64/// A struct representing a E2EE capable identity of a user.
65///
66/// The identity is backed by public [cross signing] keys that users upload. If
67/// our own user doesn't yet have such an identity, a new one can be created and
68/// uploaded to the server using [`Encryption::bootstrap_cross_signing()`]. The
69/// user identity can be also reset using the same method.
70///
71/// The user identity consists of three separate `Ed25519` keypairs:
72///
73/// ```text
74///           ┌──────────────────────────────────────────────────────┐
75///           │                    User Identity                     │
76///           ├────────────────┬──────────────────┬──────────────────┤
77///           │   Master Key   │ Self-signing Key │ User-signing key │
78///           └────────────────┴──────────────────┴──────────────────┘
79/// ```
80///
81/// The identity consists of a Master key and two sub-keys, the Self-signing key
82/// and the User-signing key.
83///
84/// Each key has a separate role:
85/// * Master key, signs only the sub-keys, can be used as a fingerprint of the
86///   identity.
87/// * Self-signing key, signs devices belonging to the user that owns this
88///   identity.
89/// * User-signing key, signs Master keys belonging to other users.
90///
91/// The User-signing key and its signatures of other user's Master keys are
92/// hidden from us by the homeserver. This is done to preserve privacy and not
93/// let us know whom the user verified.
94///
95/// [cross signing]: https://spec.matrix.org/unstable/client-server-api/#cross-signing
96/// [`Encryption::bootstrap_cross_signing()`]: crate::encryption::Encryption::bootstrap_cross_signing
97#[derive(Debug, Clone)]
98pub struct UserIdentity {
99    client: Client,
100    inner: CryptoUserIdentity,
101}
102
103impl UserIdentity {
104    pub(crate) fn new(client: Client, identity: CryptoUserIdentity) -> Self {
105        Self { inner: identity, client }
106    }
107
108    #[cfg(feature = "e2e-encryption")]
109    pub(crate) fn underlying_identity(&self) -> CryptoUserIdentity {
110        self.inner.clone()
111    }
112
113    /// The ID of the user this identity belongs to.
114    ///
115    /// # Examples
116    ///
117    /// ```no_run
118    /// # use matrix_sdk::{Client, ruma::user_id};
119    /// # use url::Url;
120    /// # let alice = user_id!("@alice:example.org");
121    /// # let homeserver = Url::parse("http://example.com").unwrap();
122    /// # async {
123    /// # let client = Client::new(homeserver).await.unwrap();
124    /// let user = client.encryption().get_user_identity(alice).await?;
125    ///
126    /// if let Some(user) = user {
127    ///     println!("This user identity belongs to {}", user.user_id());
128    /// }
129    ///
130    /// # anyhow::Ok(()) };
131    /// ```
132    pub fn user_id(&self) -> &UserId {
133        match &self.inner {
134            CryptoUserIdentity::Own(identity) => identity.user_id(),
135            CryptoUserIdentity::Other(identity) => identity.user_id(),
136        }
137    }
138
139    /// Request an interactive verification with this `UserIdentity`.
140    ///
141    /// Returns a [`VerificationRequest`] object that can be used to control the
142    /// verification flow.
143    ///
144    /// This will send out a `m.key.verification.request` event. Who such an
145    /// event will be sent to depends on if we're verifying our own identity or
146    /// someone else's:
147    ///
148    /// * Our own identity - All our E2EE capable devices will receive the event
149    ///   over to-device messaging.
150    /// * Someone else's identity - The event will be sent to a DM room we share
151    ///   with the user, if we don't share a DM with the user, one will be
152    ///   created.
153    ///
154    /// The default methods that are supported are:
155    ///
156    /// * `m.sas.v1` - Short auth string, or emoji based verification
157    /// * `m.qr_code.show.v1` - QR code based verification
158    ///
159    /// [`request_verification_with_methods()`] method can be
160    /// used to override this. The `m.qr_code.show.v1` method is only available
161    /// if the `qrcode` feature is enabled, which it is by default.
162    ///
163    /// Check out the [`verification`] module for more info on how to handle
164    /// interactive verifications.
165    ///
166    /// # Examples
167    ///
168    /// ```no_run
169    /// # use matrix_sdk::{Client, ruma::user_id};
170    /// # use url::Url;
171    /// # let alice = user_id!("@alice:example.org");
172    /// # let homeserver = Url::parse("http://example.com").unwrap();
173    /// # async {
174    /// # let client = Client::new(homeserver).await.unwrap();
175    /// let user = client.encryption().get_user_identity(alice).await?;
176    ///
177    /// if let Some(user) = user {
178    ///     let verification = user.request_verification().await?;
179    /// }
180    ///
181    /// # anyhow::Ok(()) };
182    /// ```
183    ///
184    /// [`request_verification_with_methods()`]:
185    /// #method.request_verification_with_methods
186    /// [`verification`]: crate::encryption::verification
187    pub async fn request_verification(
188        &self,
189    ) -> Result<VerificationRequest, RequestVerificationError> {
190        self.request_verification_impl(None).await
191    }
192
193    /// Request an interactive verification with this `UserIdentity` using the
194    /// selected methods.
195    ///
196    /// Returns a [`VerificationRequest`] object that can be used to control the
197    /// verification flow.
198    ///
199    /// This methods behaves the same way as [`request_verification()`],
200    /// but the advertised verification methods can be manually selected.
201    ///
202    /// Check out the [`verification`] module for more info on how to handle
203    /// interactive verifications.
204    ///
205    /// # Arguments
206    ///
207    /// * `methods` - The verification methods that we want to support. Must be
208    ///   non-empty.
209    ///
210    /// # Panics
211    ///
212    /// This method will panic if `methods` is empty.
213    ///
214    /// # Examples
215    ///
216    /// ```no_run
217    /// # use matrix_sdk::{
218    /// #    Client,
219    /// #    ruma::{
220    /// #        user_id,
221    /// #        events::key::verification::VerificationMethod,
222    /// #    }
223    /// # };
224    /// # use url::Url;
225    /// # let alice = user_id!("@alice:example.org");
226    /// # let homeserver = Url::parse("http://example.com").unwrap();
227    /// # async {
228    /// # let client = Client::new(homeserver).await.unwrap();
229    /// let user = client.encryption().get_user_identity(alice).await?;
230    ///
231    /// // We don't want to support showing a QR code, we only support SAS
232    /// // verification
233    /// let methods = vec![VerificationMethod::SasV1];
234    ///
235    /// if let Some(user) = user {
236    ///     let verification =
237    ///         user.request_verification_with_methods(methods).await?;
238    /// }
239    /// # anyhow::Ok(()) };
240    /// ```
241    ///
242    /// [`request_verification()`]: #method.request_verification
243    /// [`verification`]: crate::encryption::verification
244    pub async fn request_verification_with_methods(
245        &self,
246        methods: Vec<VerificationMethod>,
247    ) -> Result<VerificationRequest, RequestVerificationError> {
248        assert!(!methods.is_empty(), "The list of verification methods can't be non-empty");
249        self.request_verification_impl(Some(methods)).await
250    }
251
252    async fn request_verification_impl(
253        &self,
254        methods: Option<Vec<VerificationMethod>>,
255    ) -> Result<VerificationRequest, RequestVerificationError> {
256        match &self.inner {
257            CryptoUserIdentity::Own(identity) => {
258                let (verification, request) = if let Some(methods) = methods {
259                    identity
260                        .request_verification_with_methods(methods)
261                        .await
262                        .map_err(crate::Error::from)?
263                } else {
264                    identity.request_verification().await.map_err(crate::Error::from)?
265                };
266
267                self.client.send_verification_request(request).await?;
268
269                Ok(VerificationRequest { inner: verification, client: self.client.clone() })
270            }
271            CryptoUserIdentity::Other(i) => {
272                let content = i.verification_request_content(methods.clone());
273
274                let room = if let Some(room) = self.client.get_dm_room(i.user_id()) {
275                    // Make sure that the user, to be verified, is still in the room
276                    if !room
277                        .members(RoomMemberships::ACTIVE)
278                        .await?
279                        .iter()
280                        .any(|member| member.user_id() == i.user_id())
281                    {
282                        room.invite_user_by_id(i.user_id()).await?;
283                    }
284                    room.clone()
285                } else {
286                    self.client.create_dm(i.user_id()).await?
287                };
288
289                let response = room.send(RoomMessageEventContent::new(content)).await?;
290
291                let verification =
292                    i.request_verification(room.room_id(), &response.event_id, methods);
293
294                Ok(VerificationRequest { inner: verification, client: self.client.clone() })
295            }
296        }
297    }
298
299    /// Manually verify this [`UserIdentity`].
300    ///
301    /// This method will do different things depending on if the user identity
302    /// belongs to us, or if the user identity belongs to someone else. Users
303    /// that chose to manually verify a user identity should make sure that the
304    /// Master key does match to to the `Ed25519` they expect.
305    ///
306    /// The Master key can be inspected using the [`UserIdentity::master_key()`]
307    /// method.
308    ///
309    /// ### Manually verifying other users
310    ///
311    /// This method will attempt to sign the user identity using our private
312    /// parts of the cross signing keys. The method will attempt to sign the
313    /// Master key of the user using our own User-signing key. This will of
314    /// course fail if the private part of the User-signing key isn't available.
315    ///
316    /// The availability of the User-signing key can be checked using the
317    /// [`Encryption::cross_signing_status()`] method.
318    ///
319    /// ### Manually verifying our own user
320    ///
321    /// On the other hand, if the user identity belongs to us, it will be
322    /// marked as verified using a local flag, our own device will also sign the
323    /// Master key. Manually verifying our own user identity can't fail.
324    ///
325    /// ### Problems of manual verification
326    ///
327    /// Manual verification may be more convenient to use, i.e. both users need
328    /// to be online and available to interactively verify each other. Despite
329    /// the convenience, interactive verifications should be generally
330    /// preferred. Manually verifying a user won't notify the other user, the
331    /// one being verified, that they should also verify us. This means that
332    /// user `A` will consider user `B` to be verified, but not the other way
333    /// around.
334    ///
335    /// # Examples
336    ///
337    /// ```no_run
338    /// # use matrix_sdk::{
339    /// #    Client,
340    /// #    ruma::{
341    /// #        user_id,
342    /// #        events::key::verification::VerificationMethod,
343    /// #    }
344    /// # };
345    /// # use url::Url;
346    /// # let alice = user_id!("@alice:example.org");
347    /// # let homeserver = Url::parse("http://example.com").unwrap();
348    /// # async {
349    /// # let client = Client::new(homeserver).await.unwrap();
350    /// let user = client.encryption().get_user_identity(alice).await?;
351    ///
352    /// if let Some(user) = user {
353    ///     user.verify().await?;
354    /// }
355    /// # anyhow::Ok(()) };
356    /// ```
357    /// [`Encryption::cross_signing_status()`]: crate::encryption::Encryption::cross_signing_status
358    pub async fn verify(&self) -> Result<(), ManualVerifyError> {
359        let request = match &self.inner {
360            CryptoUserIdentity::Own(identity) => identity.verify().await?,
361            CryptoUserIdentity::Other(identity) => identity.verify().await?,
362        };
363
364        self.client.send(request).await?;
365
366        Ok(())
367    }
368
369    /// Is the user identity considered to be verified.
370    ///
371    /// A user identity is considered to be verified if:
372    ///
373    /// * It has been signed by our User-signing key, if the identity belongs to
374    ///   another user
375    /// * If it has been locally marked as verified, if the user identity
376    ///   belongs to us.
377    ///
378    /// If the identity belongs to another user, our own user identity needs to
379    /// be verified as well for the identity to be considered to be verified.
380    ///
381    /// # Examples
382    ///
383    /// ```no_run
384    /// # use matrix_sdk::{
385    /// #    Client,
386    /// #    ruma::{
387    /// #        user_id,
388    /// #        events::key::verification::VerificationMethod,
389    /// #    }
390    /// # };
391    /// # use url::Url;
392    /// # let alice = user_id!("@alice:example.org");
393    /// # let homeserver = Url::parse("http://example.com").unwrap();
394    /// # async {
395    /// # let client = Client::new(homeserver).await.unwrap();
396    /// let user = client.encryption().get_user_identity(alice).await?;
397    ///
398    /// if let Some(user) = user {
399    ///     if user.is_verified() {
400    ///         println!("User {} is verified", user.user_id());
401    ///     } else {
402    ///         println!("User {} is not verified", user.user_id());
403    ///     }
404    /// }
405    /// # anyhow::Ok(()) };
406    /// ```
407    pub fn is_verified(&self) -> bool {
408        self.inner.is_verified()
409    }
410
411    /// True if we verified this identity at some point in the past.
412    ///
413    /// To reset this latch back to `false`, one must call
414    /// [`UserIdentity::withdraw_verification()`].
415    pub fn was_previously_verified(&self) -> bool {
416        self.inner.was_previously_verified()
417    }
418
419    /// Remove the requirement for this identity to be verified.
420    ///
421    /// If an identity was previously verified and is not anymore it will be
422    /// reported to the user. In order to remove this notice users have to
423    /// verify again or to withdraw the verification requirement.
424    pub async fn withdraw_verification(&self) -> Result<(), CryptoStoreError> {
425        self.inner.withdraw_verification().await
426    }
427
428    /// Was this identity previously verified, and is no longer?
429    pub fn has_verification_violation(&self) -> bool {
430        self.inner.has_verification_violation()
431    }
432
433    /// Remember this identity, ensuring it does not result in a pin violation.
434    ///
435    /// When we first see a user, we assume their cryptographic identity has not
436    /// been tampered with by the homeserver or another entity with
437    /// man-in-the-middle capabilities. We remember this identity and call this
438    /// action "pinning".
439    ///
440    /// If the identity presented for the user changes later on, the newly
441    /// presented identity is considered to be in "pin violation". This
442    /// method explicitly accepts the new identity, allowing it to replace
443    /// the previously pinned one and bringing it out of pin violation.
444    ///
445    /// UIs should display a warning to the user when encountering an identity
446    /// which is not verified and is in pin violation.
447    pub async fn pin(&self) -> Result<(), CryptoStoreError> {
448        self.inner.pin().await
449    }
450
451    /// Get the public part of the Master key of this user identity.
452    ///
453    /// The public part of the Master key is usually used to uniquely identify
454    /// the identity.
455    ///
456    /// # Examples
457    ///
458    /// ```no_run
459    /// # use matrix_sdk::{
460    /// #    Client,
461    /// #    ruma::{
462    /// #        user_id,
463    /// #        events::key::verification::VerificationMethod,
464    /// #    }
465    /// # };
466    /// # use url::Url;
467    /// # let alice = user_id!("@alice:example.org");
468    /// # let homeserver = Url::parse("http://example.com").unwrap();
469    /// # async {
470    /// # let client = Client::new(homeserver).await.unwrap();
471    /// let user = client.encryption().get_user_identity(alice).await?;
472    ///
473    /// if let Some(user) = user {
474    ///     // Let's verify the user after we confirm that the master key
475    ///     // matches what we expect, for this we fetch the first public key we
476    ///     // can find, there's currently only a single key allowed so this is
477    ///     // fine.
478    ///     if user.master_key().get_first_key().map(|k| k.to_base64())
479    ///         == Some("MyMasterKey".to_string())
480    ///     {
481    ///         println!(
482    ///             "Master keys match for user {}, marking the user as verified",
483    ///             user.user_id(),
484    ///         );
485    ///         user.verify().await?;
486    ///     } else {
487    ///         println!("Master keys don't match for user {}", user.user_id());
488    ///     }
489    /// }
490    /// # anyhow::Ok(()) };
491    /// ```
492    pub fn master_key(&self) -> &MasterPubkey {
493        match &self.inner {
494            CryptoUserIdentity::Own(identity) => identity.master_key(),
495            CryptoUserIdentity::Other(identity) => identity.master_key(),
496        }
497    }
498}