matrix_sdk/encryption/identities/
mod.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
15//! Cryptographic identities used in Matrix.
16//!
17//! There are two types of cryptographic identities in Matrix.
18//!
19//! 1. Devices, which are backed by [device keys], they represent each
20//!    individual log in by an E2EE capable Matrix client. We represent devices
21//!    using the [`Device`] struct.
22//!
23//! 2. User identities, which are backed by [cross signing keys]. The user
24//!    identity represent a unique E2EE capable identity of any given user. This
25//!    identity is generally created and uploaded to the server by the first
26//!    E2EE capable client the user logs in with. We represent user identities
27//!    using the [`UserIdentity`] struct.
28//!
29//! A [`Device`] or an [`UserIdentity`] can be used to inspect the public keys
30//! of the device/identity, or it can be used to initiate a interactive
31//! verification flow. They can also be manually marked as verified.
32//!
33//! # Examples
34//!
35//! Verifying a device is pretty straightforward:
36//!
37//! ```no_run
38//! # use matrix_sdk::{Client, ruma::{device_id, user_id}};
39//! # use url::Url;
40//! # let alice = user_id!("@alice:example.org");
41//! # let homeserver = Url::parse("http://example.com").unwrap();
42//! # async {
43//! # let client = Client::new(homeserver).await.unwrap();
44//! let device =
45//!     client.encryption().get_device(alice, device_id!("DEVICEID")).await?;
46//!
47//! if let Some(device) = device {
48//!     // Let's request the device to be verified.
49//!     let verification = device.request_verification().await?;
50//!
51//!     // Actually this is taking too long.
52//!     verification.cancel().await?;
53//!
54//!     // Let's just mark it as verified.
55//!     device.verify().await?;
56//! }
57//! # anyhow::Ok(()) };
58//! ```
59//!
60//! Verifying a user identity works largely the same:
61//!
62//! ```no_run
63//! # use matrix_sdk::{Client, ruma::user_id};
64//! # use url::Url;
65//! # let alice = user_id!("@alice:example.org");
66//! # let homeserver = Url::parse("http://example.com").unwrap();
67//! # async {
68//! # let client = Client::new(homeserver).await.unwrap();
69//! let user = client.encryption().get_user_identity(alice).await?;
70//!
71//! if let Some(user) = user {
72//!     // Let's request the user to be verified.
73//!     let verification = user.request_verification().await?;
74//!
75//!     // Actually this is taking too long.
76//!     verification.cancel().await?;
77//!
78//!     // Let's just mark it as verified.
79//!     user.verify().await?;
80//! }
81//! # anyhow::Ok(()) };
82//! ```
83//!
84//! [cross signing keys]: https://spec.matrix.org/unstable/client-server-api/#cross-signing
85//! [device keys]: https://spec.matrix.org/unstable/client-server-api/#device-keys
86
87mod devices;
88mod users;
89
90pub use devices::{Device, DeviceUpdates, UserDevices};
91pub use matrix_sdk_base::crypto::types::MasterPubkey;
92pub use users::{IdentityUpdates, UserIdentity};
93
94/// Error for the manual verification step, when we manually sign users or
95/// devices.
96#[derive(thiserror::Error, Debug)]
97pub enum ManualVerifyError {
98    /// Error that happens when we try to upload the user or device signature.
99    #[error(transparent)]
100    Http(#[from] crate::HttpError),
101    /// Error that happens when we try to sign the user or device.
102    #[error(transparent)]
103    Signature(#[from] matrix_sdk_base::crypto::SignatureError),
104}
105
106/// Error when requesting a verification.
107#[derive(thiserror::Error, Debug)]
108pub enum RequestVerificationError {
109    /// An ordinary error coming from the SDK, i.e. when we fail to send out a
110    /// HTTP request or if there's an error with the storage layer.
111    #[error(transparent)]
112    Sdk(#[from] crate::Error),
113    /// Verifying other users requires having a DM open with them, this error
114    /// signals that we didn't have a DM and that we failed to create one.
115    #[error("Couldn't create a DM with user {0} where the verification should take place")]
116    RoomCreation(ruma::OwnedUserId),
117}
matrix_sdk/encryption/identities/mod.rs

matrix_sdk/encryption/identities/
mod.rs
