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}