ruma_common/identifiers/
key_id.rs

Help
1use std::{
2    cmp::Ordering,
3    hash::{Hash, Hasher},
4    marker::PhantomData,
5};
6
7use ruma_macros::IdZst;
8
9use super::{
10    crypto_algorithms::SigningKeyAlgorithm, Base64PublicKey, Base64PublicKeyOrDeviceId, DeviceId,
11    DeviceKeyAlgorithm, KeyName, OneTimeKeyAlgorithm, OneTimeKeyName, ServerSigningKeyVersion,
12};
13
14/// A key algorithm and key name delimited by a colon.
15///
16/// Examples of the use of this struct are [`DeviceKeyId`], which identifies a Ed25519 or Curve25519
17/// [device key](https://spec.matrix.org/latest/client-server-api/#device-keys), and
18/// [`CrossSigningKeyId`], which identifies a user's
19/// [cross signing key](https://spec.matrix.org/latest/client-server-api/#cross-signing).
20///
21/// This format of identifier is often used in the `signatures` field of
22/// [signed JSON](https://spec.matrix.org/latest/appendices/#signing-details)
23/// where it is referred to as a "signing key identifier".
24///
25/// This struct is rarely used directly - instead you should expect to use one of the type aliases
26/// that rely on it like [`CrossSigningKeyId`] or [`DeviceSigningKeyId`].
27///
28/// # Examples
29///
30/// To parse a colon-separated identifier:
31///
32/// ```
33/// use ruma_common::DeviceKeyId;
34///
35/// let k = DeviceKeyId::parse("ed25519:1").unwrap();
36/// assert_eq!(k.algorithm().as_str(), "ed25519");
37/// assert_eq!(k.key_name(), "1");
38/// ```
39///
40/// To construct a colon-separated identifier from its parts:
41///
42/// ```
43/// use ruma_common::{DeviceKeyAlgorithm, DeviceKeyId};
44///
45/// let k = DeviceKeyId::from_parts(DeviceKeyAlgorithm::Curve25519, "MYDEVICE".into());
46/// assert_eq!(k.as_str(), "curve25519:MYDEVICE");
47/// ```
48#[repr(transparent)]
49#[derive(IdZst)]
50#[ruma_id(
51    validate = ruma_identifiers_validation::key_id::validate::<K>,
52)]
53pub struct KeyId<A: KeyAlgorithm, K: KeyName + ?Sized>(PhantomData<(A, K)>, str);
54
55impl<A: KeyAlgorithm, K: KeyName + ?Sized> KeyId<A, K> {
56    /// Creates a new `KeyId` from an algorithm and key name.
57    pub fn from_parts(algorithm: A, key_name: &K) -> OwnedKeyId<A, K> {
58        let algorithm = algorithm.as_ref();
59        let key_name = key_name.as_ref();
60
61        let mut res = String::with_capacity(algorithm.len() + 1 + key_name.len());
62        res.push_str(algorithm);
63        res.push(':');
64        res.push_str(key_name);
65
66        Self::from_borrowed(&res).to_owned()
67    }
68
69    /// Returns key algorithm of the key ID - the part that comes before the colon.
70    ///
71    /// # Example
72    ///
73    /// ```
74    /// use ruma_common::{DeviceKeyAlgorithm, DeviceKeyId};
75    ///
76    /// let k = DeviceKeyId::parse("ed25519:1").unwrap();
77    /// assert_eq!(k.algorithm(), DeviceKeyAlgorithm::Ed25519);
78    /// ```
79    pub fn algorithm(&self) -> A {
80        A::from(&self.as_str()[..self.colon_idx()])
81    }
82
83    /// Returns the key name of the key ID - the part that comes after the colon.
84    ///
85    /// # Example
86    ///
87    /// ```
88    /// use ruma_common::{device_id, DeviceKeyId};
89    ///
90    /// let k = DeviceKeyId::parse("ed25519:DEV1").unwrap();
91    /// assert_eq!(k.key_name(), device_id!("DEV1"));
92    /// ```
93    pub fn key_name<'a>(&'a self) -> &'a K
94    where
95        &'a K: TryFrom<&'a str>,
96    {
97        <&'a K>::try_from(&self.as_str()[(self.colon_idx() + 1)..])
98            .unwrap_or_else(|_| unreachable!())
99    }
100
101    fn colon_idx(&self) -> usize {
102        self.as_str().find(':').unwrap()
103    }
104}
105
106/// Algorithm + key name for signing keys.
107pub type SigningKeyId<K> = KeyId<SigningKeyAlgorithm, K>;
108
109/// Algorithm + key name for signing keys.
110pub type OwnedSigningKeyId<K> = OwnedKeyId<SigningKeyAlgorithm, K>;
111
112/// Algorithm + key name for homeserver signing keys.
113pub type ServerSigningKeyId = SigningKeyId<ServerSigningKeyVersion>;
114
115/// Algorithm + key name for homeserver signing keys.
116pub type OwnedServerSigningKeyId = OwnedSigningKeyId<ServerSigningKeyVersion>;
117
118/// Algorithm + key name for [device signing keys].
119///
120/// [device signing keys]: https://spec.matrix.org/latest/client-server-api/#device-keys
121pub type DeviceSigningKeyId = SigningKeyId<DeviceId>;
122
123/// Algorithm + key name for [device signing] keys.
124///
125/// [device signing keys]: https://spec.matrix.org/latest/client-server-api/#device-keys
126pub type OwnedDeviceSigningKeyId = OwnedSigningKeyId<DeviceId>;
127
128/// Algorithm + key name for [cross-signing] keys.
129///
130/// [cross-signing]: https://spec.matrix.org/latest/client-server-api/#cross-signing
131pub type CrossSigningKeyId = SigningKeyId<Base64PublicKey>;
132
133/// Algorithm + key name for [cross-signing] keys.
134///
135/// [cross-signing]: https://spec.matrix.org/latest/client-server-api/#cross-signing
136pub type OwnedCrossSigningKeyId = OwnedSigningKeyId<Base64PublicKey>;
137
138/// Algorithm + key name for [cross-signing] or [device signing] keys.
139///
140/// [cross-signing]: https://spec.matrix.org/latest/client-server-api/#cross-signing
141/// [device signing]: https://spec.matrix.org/latest/client-server-api/#device-keys
142pub type CrossSigningOrDeviceSigningKeyId = SigningKeyId<Base64PublicKeyOrDeviceId>;
143
144/// Algorithm + key name for [cross-signing] or [device signing] keys.
145///
146/// [cross-signing]: https://spec.matrix.org/latest/client-server-api/#cross-signing
147/// [device signing]: https://spec.matrix.org/latest/client-server-api/#device-keys
148pub type OwnedCrossSigningOrDeviceSigningKeyId = OwnedSigningKeyId<Base64PublicKeyOrDeviceId>;
149
150/// Algorithm + key name for [device keys].
151///
152/// [device keys]: https://spec.matrix.org/latest/client-server-api/#device-keys
153pub type DeviceKeyId = KeyId<DeviceKeyAlgorithm, DeviceId>;
154
155/// Algorithm + key name for [device keys].
156///
157/// [device keys]: https://spec.matrix.org/latest/client-server-api/#device-keys
158pub type OwnedDeviceKeyId = OwnedKeyId<DeviceKeyAlgorithm, DeviceId>;
159
160/// Algorithm + key name for [one-time and fallback keys].
161///
162/// [one-time and fallback keys]: https://spec.matrix.org/latest/client-server-api/#one-time-and-fallback-keys
163pub type OneTimeKeyId = KeyId<OneTimeKeyAlgorithm, OneTimeKeyName>;
164
165/// Algorithm + key name for [one-time and fallback keys].
166///
167/// [one-time and fallback keys]: https://spec.matrix.org/latest/client-server-api/#one-time-and-fallback-keys
168pub type OwnedOneTimeKeyId = OwnedKeyId<OneTimeKeyAlgorithm, OneTimeKeyName>;
169
170// The following impls are usually derived using the std macros.
171// They are implemented manually here to avoid unnecessary bounds.
172impl<A: KeyAlgorithm, K: KeyName + ?Sized> PartialEq for KeyId<A, K> {
173    fn eq(&self, other: &Self) -> bool {
174        self.as_str() == other.as_str()
175    }
176}
177
178impl<A: KeyAlgorithm, K: KeyName + ?Sized> Eq for KeyId<A, K> {}
179
180impl<A: KeyAlgorithm, K: KeyName + ?Sized> PartialOrd for KeyId<A, K> {
181    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
182        Some(self.cmp(other))
183    }
184}
185
186impl<A: KeyAlgorithm, K: KeyName + ?Sized> Ord for KeyId<A, K> {
187    fn cmp(&self, other: &Self) -> Ordering {
188        Ord::cmp(self.as_str(), other.as_str())
189    }
190}
191
192impl<A: KeyAlgorithm, K: KeyName + ?Sized> Hash for KeyId<A, K> {
193    fn hash<H: Hasher>(&self, state: &mut H) {
194        self.as_str().hash(state);
195    }
196}
197
198/// The algorithm of a key.
199pub trait KeyAlgorithm: for<'a> From<&'a str> + AsRef<str> {}
200
201impl KeyAlgorithm for SigningKeyAlgorithm {}
202
203impl KeyAlgorithm for DeviceKeyAlgorithm {}
204
205impl KeyAlgorithm for OneTimeKeyAlgorithm {}
206
207/// An opaque identifier type to use with [`KeyId`].
208///
209/// This type has no semantic value and no validation is done. It is meant to be able to use the
210/// [`KeyId`] API without validating the key name.
211#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, IdZst)]
212pub struct AnyKeyName(str);
213
214impl KeyName for AnyKeyName {
215    fn validate(_s: &str) -> Result<(), ruma_common::IdParseError> {
216        Ok(())
217    }
218}
219
220#[cfg(test)]
221mod tests {
222    use assert_matches2::assert_matches;
223    use ruma_identifiers_validation::Error;
224
225    use super::DeviceKeyId;
226
227    #[test]
228    fn algorithm_and_key_name_are_correctly_extracted() {
229        let key_id = DeviceKeyId::parse("ed25519:MYDEVICE").expect("Should parse correctly");
230        assert_eq!(key_id.algorithm().as_str(), "ed25519");
231        assert_eq!(key_id.key_name(), "MYDEVICE");
232    }
233
234    #[test]
235    fn empty_key_name_is_correctly_extracted() {
236        let key_id = DeviceKeyId::parse("ed25519:").expect("Should parse correctly");
237        assert_eq!(key_id.algorithm().as_str(), "ed25519");
238        assert_eq!(key_id.key_name(), "");
239    }
240
241    #[test]
242    fn missing_colon_fails_to_parse() {
243        let error = DeviceKeyId::parse("ed25519_MYDEVICE").expect_err("Should fail to parse");
244        assert_matches!(error, Error::MissingColon);
245    }
246
247    #[test]
248    fn empty_algorithm_fails_to_parse() {
249        let error = DeviceKeyId::parse(":MYDEVICE").expect_err("Should fail to parse");
250        // Weirdly, this also reports MissingColon
251        assert_matches!(error, Error::MissingColon);
252    }
253}
ruma_common/identifiers/key_id.rs

ruma_common/identifiers/
key_id.rs
