ruma_common/
encryption.rs

1//! Common types for [encryption] related tasks.
2//!
3//! [encryption]: https://spec.matrix.org/latest/client-server-api/#end-to-end-encryption
4
5use std::collections::BTreeMap;
6
7use serde::{Deserialize, Serialize};
8
9use crate::{
10    serde::{Base64, StringEnum},
11    CrossSigningOrDeviceSignatures, DeviceSignatures, EventEncryptionAlgorithm,
12    OwnedCrossSigningKeyId, OwnedDeviceId, OwnedDeviceKeyId, OwnedUserId, PrivOwnedStr,
13};
14
15/// Identity keys for a device.
16#[derive(Clone, Debug, Deserialize, Serialize)]
17#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
18pub struct DeviceKeys {
19    /// The ID of the user the device belongs to.
20    ///
21    /// Must match the user ID used when logging in.
22    pub user_id: OwnedUserId,
23
24    /// The ID of the device these keys belong to.
25    ///
26    /// Must match the device ID used when logging in.
27    pub device_id: OwnedDeviceId,
28
29    /// The encryption algorithms supported by this device.
30    pub algorithms: Vec<EventEncryptionAlgorithm>,
31
32    /// Public identity keys.
33    pub keys: BTreeMap<OwnedDeviceKeyId, String>,
34
35    /// Signatures for the device key object.
36    pub signatures: CrossSigningOrDeviceSignatures,
37
38    /// Additional data added to the device key information by intermediate servers, and
39    /// not covered by the signatures.
40    #[serde(default, skip_serializing_if = "UnsignedDeviceInfo::is_empty")]
41    pub unsigned: UnsignedDeviceInfo,
42}
43
44impl DeviceKeys {
45    /// Creates a new `DeviceKeys` from the given user id, device id, algorithms, keys and
46    /// signatures.
47    pub fn new(
48        user_id: OwnedUserId,
49        device_id: OwnedDeviceId,
50        algorithms: Vec<EventEncryptionAlgorithm>,
51        keys: BTreeMap<OwnedDeviceKeyId, String>,
52        signatures: CrossSigningOrDeviceSignatures,
53    ) -> Self {
54        Self { user_id, device_id, algorithms, keys, signatures, unsigned: Default::default() }
55    }
56}
57
58/// Additional data added to device key information by intermediate servers.
59#[derive(Clone, Debug, Default, Deserialize, Serialize)]
60#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
61pub struct UnsignedDeviceInfo {
62    /// The display name which the user set on the device.
63    #[serde(skip_serializing_if = "Option::is_none")]
64    pub device_display_name: Option<String>,
65}
66
67impl UnsignedDeviceInfo {
68    /// Creates an empty `UnsignedDeviceInfo`.
69    pub fn new() -> Self {
70        Default::default()
71    }
72
73    /// Checks whether all fields are empty / `None`.
74    pub fn is_empty(&self) -> bool {
75        self.device_display_name.is_none()
76    }
77}
78
79/// A key for the SignedCurve25519 algorithm
80#[derive(Debug, Clone, Serialize, Deserialize)]
81#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
82pub struct SignedKey {
83    /// Base64-encoded 32-byte Curve25519 public key.
84    pub key: Base64,
85
86    /// Signatures for the key object.
87    pub signatures: DeviceSignatures,
88
89    /// Is this key considered to be a fallback key, defaults to false.
90    #[serde(default, skip_serializing_if = "crate::serde::is_default")]
91    pub fallback: bool,
92}
93
94impl SignedKey {
95    /// Creates a new `SignedKey` with the given key and signatures.
96    pub fn new(key: Base64, signatures: DeviceSignatures) -> Self {
97        Self { key, signatures, fallback: false }
98    }
99
100    /// Creates a new fallback `SignedKey` with the given key and signatures.
101    pub fn new_fallback(key: Base64, signatures: DeviceSignatures) -> Self {
102        Self { key, signatures, fallback: true }
103    }
104}
105
106/// A one-time public key for "pre-key" messages.
107#[derive(Debug, Clone, Serialize, Deserialize)]
108#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
109#[serde(untagged)]
110pub enum OneTimeKey {
111    /// A key containing signatures, for the SignedCurve25519 algorithm.
112    SignedKey(SignedKey),
113
114    /// A string-valued key, for the Ed25519 and Curve25519 algorithms.
115    Key(String),
116}
117
118/// A [cross-signing] key.
119///
120/// [cross-signing]: https://spec.matrix.org/latest/client-server-api/#cross-signing
121#[derive(Clone, Debug, Deserialize, Serialize)]
122#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
123pub struct CrossSigningKey {
124    /// The ID of the user the key belongs to.
125    pub user_id: OwnedUserId,
126
127    /// What the key is used for.
128    pub usage: Vec<KeyUsage>,
129
130    /// The public key.
131    ///
132    /// The object must have exactly one property.
133    pub keys: BTreeMap<OwnedCrossSigningKeyId, String>,
134
135    /// Signatures of the key.
136    ///
137    /// The master key should be signed by the device key and can be signed by other users'
138    /// user-signing key. The user-signing and self-signing keys must be signed by the master
139    /// key.
140    ///
141    /// Only optional for the master key.
142    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
143    pub signatures: CrossSigningOrDeviceSignatures,
144}
145
146impl CrossSigningKey {
147    /// Creates a new `CrossSigningKey` with the given user ID, usage, keys and signatures.
148    pub fn new(
149        user_id: OwnedUserId,
150        usage: Vec<KeyUsage>,
151        keys: BTreeMap<OwnedCrossSigningKeyId, String>,
152        signatures: CrossSigningOrDeviceSignatures,
153    ) -> Self {
154        Self { user_id, usage, keys, signatures }
155    }
156}
157
158/// The usage of a cross signing key.
159#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
160#[derive(Clone, PartialEq, Eq, StringEnum)]
161#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
162#[ruma_enum(rename_all = "snake_case")]
163pub enum KeyUsage {
164    /// Master key.
165    Master,
166
167    /// Self-signing key.
168    SelfSigning,
169
170    /// User-signing key.
171    UserSigning,
172
173    #[doc(hidden)]
174    _Custom(PrivOwnedStr),
175}
ruma_common/encryption.rs

ruma_common/
encryption.rs
