Skip to main content

tuwunel_service/users/
keys.rs

1use std::{collections::BTreeMap, mem, ops::Deref, sync::Arc};
2
3use futures::{
4	Stream, StreamExt, TryFutureExt, TryStreamExt,
5	future::{join, try_join3},
6	pin_mut,
7};
8use ruma::{
9	AnyKeyName, DeviceId, KeyId, OneTimeKeyAlgorithm, OneTimeKeyId, OneTimeKeyName,
10	OwnedDeviceId, OwnedKeyId, OwnedOneTimeKeyId, OwnedRoomId, OwnedServerName, RoomId,
11	SigningKeyId, UInt, UserId,
12	encryption::{CrossSigningKey, DeviceKeys, OneTimeKey},
13	serde::{Base64, Raw, base64::Standard},
14	signatures::{
15		VerificationError, to_canonical_json_string_for_signing, verify_canonical_json_bytes,
16	},
17};
18use serde::{Deserialize, Serialize};
19use tuwunel_core::{
20	Err, Error, Result,
21	debug::INFO_SPAN_LEVEL,
22	debug_error, debug_warn, err, implement,
23	itertools::Itertools,
24	smallvec::SmallVec,
25	utils::{
26		BoolExt, IterStream, ReadyExt,
27		result::{LogErr, NotFound},
28		stream::{BroadbandExt, TryIgnore},
29		to_canonical_object,
30	},
31	warn,
32};
33use tuwunel_database::{
34	Deserialized, Ignore, Interfix, Json, Map, Txn, deserialize_from_slice, deserialize_key,
35	serialize_key, serialize_to_vec,
36};
37
38use super::device::DeviceLock;
39
40type Servers = SmallVec<[OwnedServerName; 1]>;
41type Signatures = SmallVec<[(String, String); 1]>;
42type KeyLocks = SmallVec<[DeviceLock; 3]>;
43type ParsedKey<'a> = (&'a Raw<CrossSigningKey>, String, &'a Arc<Map>);
44type ParsedKeys<'a> = SmallVec<[ParsedKey<'a>; 3]>;
45
46/// Mutation announced to clients and federation peers.
47///
48/// Device identifiers are borrowed at mutation sites and owned in stored records.
49#[derive(Clone, Copy, Debug, Eq, PartialEq)]
50pub enum DeviceListChange<D> {
51	/// A device was created or its keys or metadata changed.
52	Device(D),
53
54	/// A device was removed.
55	Deleted(D),
56
57	/// Cross-signing keys or their signatures changed.
58	CrossSigning,
59
60	/// Peers must fetch the user's device-list snapshot.
61	Resync,
62}
63
64/// Durable detail for one local user's device-list notification.
65///
66/// Cross-signing changes retain the current stream position without advancing it.
67#[derive(Debug, Eq, PartialEq)]
68pub struct DeviceListRecord {
69	/// Mutation associated with the notification count.
70	pub change: DeviceListChange<OwnedDeviceId>,
71
72	/// Per-user stream position after the mutation.
73	pub stream_id: u64,
74}
75
76enum DeviceListChangeKind {
77	Resync = 0,
78	Device = 1,
79	Deleted = 2,
80	CrossSigning = 3,
81}
82
83#[derive(Clone, Copy, Debug, Eq, PartialEq)]
84enum KeyRole {
85	Device,
86	CrossSigningRoot,
87	SelfSigning,
88	UserSigning,
89}
90
91#[derive(Clone, Copy, Debug, Eq, PartialEq)]
92enum SignatureWrite {
93	Merge,
94	ReplaceSender,
95}
96
97#[derive(Clone, Copy, Debug, Eq, PartialEq)]
98enum SignatureAction {
99	Ignore,
100	Reject,
101	Write(KeyRole, SignatureWrite),
102}
103
104/// MSC2732: row stored under `(user, device, algorithm)` in
105/// `userdeviceidalgorithm_fallback`. Fallback keys are not deleted on
106/// claim; the row is rewritten with `used = true`.
107#[derive(Debug, Deserialize, Serialize)]
108struct FallbackEntry {
109	key_id: OwnedOneTimeKeyId,
110	key: Raw<OneTimeKey>,
111	used: bool,
112}
113
114/// Row-key shape of `onetimekeyid4225_otk`: per-device pool keyed by
115/// upload-order count for MSC4225 ordering.
116type OtkRowKey<'a> = (&'a UserId, &'a DeviceId, u64, &'a OneTimeKeyId);
117
118#[implement(super::Service)]
119pub async fn add_one_time_keys(
120	&self,
121	user_id: &UserId,
122	device_id: &DeviceId,
123	keys: &BTreeMap<OwnedOneTimeKeyId, Raw<OneTimeKey>>,
124	limit: usize,
125) -> Result {
126	let mut txn = self.services.db.txn();
127	// Hold the oldest permit so the retirement frontier cannot pass this batch
128	// before commit.
129	let mut oldest_count = None;
130	let mut last_count = None;
131
132	for (id, key) in keys.iter().take(limit) {
133		let Ok(Some(count)) = self
134			.add_one_time_key(user_id, device_id, id, key, &mut txn)
135			.await
136		else {
137			continue;
138		};
139
140		last_count = Some(*count);
141		oldest_count = oldest_count.or(Some(count));
142	}
143
144	if let Some(count) = last_count {
145		txn.raw_put(&self.db.userid_lastonetimekeyupdate, user_id, count);
146	}
147
148	txn.execute();
149	drop(oldest_count);
150
151	Ok(())
152}
153
154#[implement(super::Service)]
155pub async fn add_one_time_key(
156	&self,
157	user_id: &UserId,
158	device_id: &DeviceId,
159	one_time_key_key: &KeyId<OneTimeKeyAlgorithm, OneTimeKeyName>,
160	one_time_key_value: &Raw<OneTimeKey>,
161	txn: &mut Txn,
162) -> Result<Option<impl Deref<Target = u64> + Send + use<>>> {
163	let Some(otk) = self.db.onetimekeyid4225_otk.as_ref() else {
164		return Err!(Database("one-time-key column unavailable"));
165	};
166
167	if !self.device_exists(user_id, device_id).await {
168		return Err!(Database(error!(
169			?user_id,
170			?device_id,
171			"User does not exist or device has no metadata."
172		)));
173	}
174
175	if let Err(e) = one_time_key_value
176		.deserialize()
177		.map_err(Into::into)
178	{
179		debug_error!(
180			?one_time_key_key,
181			?one_time_key_value,
182			"Invalid one time key JSON submitted by client, skipping: {e}"
183		);
184
185		return Err(e);
186	}
187
188	// Racy dedup: two concurrent uploads of the same id can both pass this
189	// check and produce duplicate rows that persist until aged out by prune.
190	let prefix = (user_id, device_id, Interfix);
191	let already_present = otk
192		.keys_prefix(&prefix)
193		.ignore_err()
194		.ready_any(|(.., id): OtkRowKey<'_>| id == one_time_key_key)
195		.await;
196
197	if already_present {
198		return Ok(None);
199	}
200
201	let count = self.services.globals.next_count();
202
203	// MSC4225: RocksDB iterates the (user, device) prefix in count_be ascending
204	// order, so /keys/claim issues one-time keys in the order they were uploaded.
205	txn.put(
206		otk,
207		(user_id, device_id, *count, one_time_key_key.as_str()),
208		Json(one_time_key_value),
209	);
210
211	Ok(Some(count))
212}
213
214#[implement(super::Service)]
215pub async fn add_fallback_keys<'a, Keys>(
216	&self,
217	user_id: &UserId,
218	device_id: &DeviceId,
219	keys: Keys,
220) -> Result
221where
222	Keys: Iterator<Item = (&'a OneTimeKeyId, &'a Raw<OneTimeKey>)> + Send + 'a,
223{
224	let mut txn = self.services.db.txn();
225	// Hold the oldest permit so the retirement frontier cannot pass this batch
226	// before commit.
227	let mut oldest_count = None;
228	let mut last_count = None;
229
230	for (id, key) in keys {
231		let Ok(count) = self
232			.add_fallback_key(user_id, device_id, id, key, &mut txn)
233			.await
234		else {
235			continue;
236		};
237
238		last_count = Some(*count);
239		oldest_count = oldest_count.or(Some(count));
240	}
241
242	if let Some(count) = last_count {
243		txn.raw_put(&self.db.userid_lastonetimekeyupdate, user_id, count);
244	}
245
246	txn.execute();
247	drop(oldest_count);
248
249	Ok(())
250}
251
252#[implement(super::Service)]
253pub async fn add_fallback_key(
254	&self,
255	user_id: &UserId,
256	device_id: &DeviceId,
257	one_time_key_key: &KeyId<OneTimeKeyAlgorithm, OneTimeKeyName>,
258	one_time_key_value: &Raw<OneTimeKey>,
259	txn: &mut Txn,
260) -> Result<impl Deref<Target = u64> + Send + use<>> {
261	if !self.device_exists(user_id, device_id).await {
262		return Err!(Database(error!(
263			?user_id,
264			?device_id,
265			"User does not exist or device has no metadata."
266		)));
267	}
268
269	if let Err(e) = one_time_key_value
270		.deserialize()
271		.map_err(Into::into)
272	{
273		debug_error!(
274			?one_time_key_key,
275			?one_time_key_value,
276			"Invalid fallback key JSON submitted by client, skipping: {e}"
277		);
278
279		return Err(e);
280	}
281
282	let entry = FallbackEntry {
283		key_id: one_time_key_key.to_owned(),
284		key: one_time_key_value.clone(),
285		used: false,
286	};
287
288	let key = (user_id, device_id, one_time_key_key.algorithm());
289	let count = self.services.globals.next_count();
290
291	txn.put(&self.db.userdeviceidalgorithm_fallback, key, Json(&entry));
292
293	Ok(count)
294}
295
296#[implement(super::Service)]
297pub async fn take_fallback_key(
298	&self,
299	user_id: &UserId,
300	device_id: &DeviceId,
301	algorithm: &OneTimeKeyAlgorithm,
302) -> Result<(OwnedKeyId<OneTimeKeyAlgorithm, OneTimeKeyName>, Raw<OneTimeKey>)> {
303	let key = (user_id, device_id, algorithm);
304	let entry: FallbackEntry = self
305		.db
306		.userdeviceidalgorithm_fallback
307		.qry(&key)
308		.await
309		.deserialized::<Json<_>>()
310		.map(|Json(entry)| entry)
311		.map_err(|_| err!(Request(NotFound("No fallback key found"))))?;
312
313	let updated = FallbackEntry { used: true, ..entry };
314	self.db
315		.userdeviceidalgorithm_fallback
316		.put(key, Json(&updated));
317
318	Ok((updated.key_id, updated.key))
319}
320
321/// Streams the algorithms of a device's fallback keys that no claim has used.
322///
323/// The scan ends at the device's own rows, so a device whose ID extends this
324/// one's contributes none.
325#[implement(super::Service)]
326pub fn unused_fallback_key_algorithms<'a>(
327	&'a self,
328	user_id: &'a UserId,
329	device_id: &'a DeviceId,
330) -> impl Stream<Item = OneTimeKeyAlgorithm> + Send + 'a {
331	type KeyVal = ((Ignore, Ignore, OneTimeKeyAlgorithm), Json<FallbackEntry>);
332
333	let prefix = (user_id, device_id, Interfix);
334
335	self.db
336		.userdeviceidalgorithm_fallback
337		.stream_prefix(&prefix)
338		.ignore_err()
339		.ready_filter_map(|((_, _, algorithm), Json(entry)): KeyVal| {
340			entry.used.is_false().then_some(algorithm)
341		})
342}
343
344#[implement(super::Service)]
345pub async fn last_one_time_keys_update(&self, user_id: &UserId) -> u64 {
346	self.db
347		.userid_lastonetimekeyupdate
348		.get(user_id)
349		.await
350		.deserialized()
351		.unwrap_or(0)
352}
353
354#[implement(super::Service)]
355pub async fn take_one_time_key(
356	&self,
357	user_id: &UserId,
358	device_id: &DeviceId,
359	key_algorithm: &OneTimeKeyAlgorithm,
360) -> Result<(OwnedKeyId<OneTimeKeyAlgorithm, OneTimeKeyName>, Raw<OneTimeKey>)> {
361	let Some(otk) = self.db.onetimekeyid4225_otk.as_ref() else {
362		return Err!(Request(NotFound("No one-time-key found")));
363	};
364
365	let update_count = self.services.globals.next_count();
366	self.db
367		.userid_lastonetimekeyupdate
368		.insert(user_id, update_count.to_be_bytes());
369
370	let prefix = (user_id, device_id, Interfix);
371	let _guard = self
372		.claiming_one_time_keys
373		.lock(&(user_id.to_owned(), device_id.to_owned()))
374		.await;
375
376	let one_time_keys = otk
377		.stream_prefix(&prefix)
378		.ignore_err()
379		.ready_filter(|(row, _): &(OtkRowKey<'_>, &[u8])| row.3.algorithm() == *key_algorithm);
380
381	pin_mut!(one_time_keys);
382	let ((user_id, device_id, count, id), val) = one_time_keys
383		.next()
384		.await
385		.ok_or_else(|| err!(Request(NotFound("No one-time-key found"))))?;
386
387	otk.del((user_id, device_id, count, id));
388
389	Ok((id.into(), serde_json::from_slice(val)?))
390}
391
392#[implement(super::Service)]
393pub async fn count_one_time_keys(
394	&self,
395	user_id: &UserId,
396	device_id: &DeviceId,
397) -> BTreeMap<OneTimeKeyAlgorithm, UInt> {
398	let Some(otk) = self.db.onetimekeyid4225_otk.as_ref() else {
399		// Without the MSC4225 column this node cannot observe the authoritative
400		// pool, so preserve "unknown" instead of falsely reporting zero keys.
401		return BTreeMap::new();
402	};
403
404	let prefix = (user_id, device_id, Interfix);
405	let algorithm_counts: BTreeMap<OneTimeKeyAlgorithm, UInt> = otk
406		.keys_prefix(&prefix)
407		.ignore_err()
408		.ready_fold(BTreeMap::new(), |mut acc, (.., id): OtkRowKey<'_>| {
409			let count: &mut UInt = acc.entry(id.algorithm()).or_default();
410			*count = count.saturating_add(1_u32.into());
411			acc
412		})
413		.await;
414
415	let total = algorithm_counts
416		.values()
417		.copied()
418		.map(TryInto::try_into)
419		.filter_map(Result::ok)
420		.fold(0_usize, usize::saturating_add);
421
422	let limit = self.services.config.encryption.one_time_key_limit;
423
424	if let Some(excess) = total.checked_sub(limit).filter(|&n| n > 0) {
425		self.prune_one_time_keys(user_id, device_id, excess)
426			.await;
427	}
428
429	complete_one_time_key_counts(algorithm_counts)
430}
431
432/// Keep zero-count algorithms visible to clients after an OTK pool is drained.
433///
434/// An empty map is omitted from `/sync` by ruma. Some clients interpret an
435/// omitted count as "unknown" and therefore do not replenish a
436/// previously-uploaded Olm account. Only `signed_curve25519` is seeded,
437/// matching Synapse; clients do not maintain unsigned curve25519 keys.
438fn complete_one_time_key_counts(
439	mut counts: BTreeMap<OneTimeKeyAlgorithm, UInt>,
440) -> BTreeMap<OneTimeKeyAlgorithm, UInt> {
441	counts
442		.entry(OneTimeKeyAlgorithm::SignedCurve25519)
443		.or_default();
444	counts
445}
446
447/// MSC4225: drop the `excess` oldest rows for this `(user, device)`. Forward
448/// iteration over the prefix runs in count_be ascending order, so
449/// `take(excess)` yields the earliest-uploaded rows.
450#[implement(super::Service)]
451pub async fn prune_one_time_keys(&self, user_id: &UserId, device_id: &DeviceId, excess: usize) {
452	let Some(otk) = self.db.onetimekeyid4225_otk.as_ref() else {
453		return;
454	};
455
456	let prefix = (user_id, device_id, Interfix);
457	otk.keys_prefix(&prefix)
458		.ignore_err()
459		.take(excess)
460		.ready_for_each(|row: OtkRowKey<'_>| {
461			otk.del(row);
462		})
463		.await;
464}
465
466/// Drops every one-time key still outstanding for this `(user, device)`.
467///
468/// Device removal has to reach the pool as well as the MSC2732 fallback key,
469/// or a claim against the deleted device still succeeds from the rows left
470/// behind.
471#[implement(super::Service)]
472pub async fn remove_one_time_keys(&self, user_id: &UserId, device_id: &DeviceId) {
473	let Some(otk) = self.db.onetimekeyid4225_otk.as_ref() else {
474		return;
475	};
476
477	otk.del_prefix(&(user_id, device_id, Interfix))
478		.await;
479}
480
481/// Drops the one-time keys of every local device, or of one user's devices,
482/// and returns how many keys it dropped and from how many devices.
483///
484/// A database restored from an older backup again holds the keys claimed since
485/// the backup was taken, and `/keys/claim` would issue them a second time.
486/// Their devices discarded the private halves on first use, so a session
487/// opened with one of them cannot be decrypted. An empty pool issues none: a
488/// client sees a count of zero at its next sync and uploads new keys, and a
489/// claim before then is served the device's fallback key, which this leaves in
490/// place. A device that never syncs, such as a dehydrated device, keeps only
491/// that fallback key until it is replaced. Removing the fallback key would
492/// leave the device unreachable for new sessions until it uploads again, so it
493/// stays even though a restored one can itself be stale: some clients rotate it
494/// on a timer, and a backup older than the last rotation restores a key the
495/// device no longer holds.
496///
497/// Every row of the pool goes, including one whose device is gone and one that
498/// does not parse as a key. The scan's own errors are returned rather than
499/// skipped, so a clearing that did not see the whole pool is never reported as
500/// done. Each user whose keys went is marked as changed, which wakes their
501/// syncs, in the same atomic batch as the removal; a clearing cut short
502/// therefore leaves the whole pool for a retry rather than an empty one whose
503/// clients were never told.
504#[implement(super::Service)]
505pub async fn clear_one_time_keys(&self, user_id: Option<&UserId>) -> Result<(usize, usize)> {
506	let Some(otk) = self.db.onetimekeyid4225_otk.as_ref() else {
507		return Err!(Database("one-time-key column unavailable"));
508	};
509
510	// An empty prefix spans the whole pool.
511	let prefix = user_id
512		.map(|user_id| serialize_key((user_id, Interfix)))
513		.transpose()?
514		.unwrap_or_default();
515
516	let rows: Vec<Vec<u8>> = otk
517		.raw_keys_prefix(&prefix)
518		.map_ok(<[u8]>::to_vec)
519		.try_collect()
520		.await?;
521
522	// Rows sort by user then device, so each device's rows are adjacent.
523	let devices = || {
524		rows.iter()
525			.filter_map(|row| deserialize_key::<OtkRowKey<'_>>(row).ok())
526			.map(|(user_id, device_id, ..)| (user_id, device_id))
527			.dedup()
528	};
529
530	let users = devices().map(|(user_id, _)| user_id).dedup();
531
532	// Held until the batch commits, as `add_one_time_keys` holds its own, so the
533	// retirement frontier cannot pass it first. Taken after the scan, since the
534	// mark carries no snapshot of the rows and the hold should stay short.
535	let count = self.services.globals.next_count();
536
537	self.clear_txn(otk, &rows, users, *count)
538		.try_execute()?;
539
540	drop(count);
541
542	Ok((rows.len(), devices().count()))
543}
544
545#[implement(super::Service)]
546fn clear_txn<'a, Users>(&self, otk: &Map, rows: &[Vec<u8>], users: Users, count: u64) -> Txn
547where
548	Users: Iterator<Item = &'a UserId>,
549{
550	let mark = &self.db.userid_lastonetimekeyupdate;
551	let mut txn = self.services.db.txn();
552
553	txn.extend(rows.iter().map(|row| (otk, row)));
554	txn.extend(users.map(|user_id| (&**mark, user_id, count.to_be_bytes())));
555
556	txn
557}
558
559/// Stores a device's identity keys in place of any it had.
560///
561/// The write holds the device lock and is skipped for a device already
562/// removed, so it neither races a signature merge on the same row nor writes
563/// back keys the removal deleted. A device that cannot be read fails the call.
564#[implement(super::Service)]
565pub async fn add_device_keys(
566	&self,
567	user_id: &UserId,
568	device_id: &DeviceId,
569	device_keys: &Raw<DeviceKeys>,
570) -> Result {
571	let _lock = self.lock_device(user_id, device_id).await;
572
573	if !self.try_device_exists(user_id, device_id).await? {
574		debug_warn!(%user_id, %device_id, "Not storing keys for a removed device.");
575		return Ok(());
576	}
577
578	let key = (user_id, device_id);
579
580	self.db.keyid_key.put(key, Json(device_keys));
581	self.mark_device_key_update(user_id, DeviceListChange::Device(device_id))
582		.await;
583
584	Ok(())
585}
586
587/// Stores a user's cross-signing keys and points the user at them.
588///
589/// Every key given is parsed before any is written, and a key not given keeps
590/// the one stored. `notify` announces the keys on the device list once written.
591#[implement(super::Service)]
592pub async fn add_cross_signing_keys(
593	&self,
594	user_id: &UserId,
595	master_key: &Option<Raw<CrossSigningKey>>,
596	self_signing_key: &Option<Raw<CrossSigningKey>>,
597	user_signing_key: &Option<Raw<CrossSigningKey>>,
598	notify: bool,
599) -> Result {
600	// TODO: Check signatures
601	let keys: ParsedKeys<'_> = [
602		(master_key, "Master", &self.db.userid_masterkeyid),
603		(self_signing_key, "Self-signing", &self.db.userid_selfsigningkeyid),
604		(user_signing_key, "User-signing", &self.db.userid_usersigningkeyid),
605	]
606	.into_iter()
607	.filter_map(|(key, label, pointers)| Some((key.as_ref()?, label, pointers)))
608	.map(|(key, label, pointers)| {
609		parse_cross_signing_key(key, label)
610			.and_then(|parsed| single_public_key(parsed.keys.into_values(), label))
611			.map(|public_key| (key, public_key, pointers))
612	})
613	.collect::<Result<_>>()?;
614
615	self.store_cross_signing_keys(user_id, &keys)
616		.await;
617
618	if notify {
619		self.mark_device_key_update(user_id, DeviceListChange::CrossSigning)
620			.await;
621	}
622
623	Ok(())
624}
625
626/// Stores a remote user's master key, keeping the signatures our copy carries.
627///
628/// The row stays locked from reading our copy to writing the merged key, so a
629/// signature merged meanwhile is kept, and our copy is read unfiltered, so none
630/// of its signatures is dropped. Nothing is announced, since a notification
631/// would prompt another key query without end.
632#[implement(super::Service)]
633#[tracing::instrument(
634	level = "debug",
635	skip(self, master_key),
636	fields(
637		%user_id,
638	)
639)]
640pub async fn store_remote_master_key(
641	&self,
642	user_id: &UserId,
643	master_key: &Raw<CrossSigningKey>,
644) -> Result {
645	let remote = parse_cross_signing_key(master_key, "Master")?;
646	let public_key = single_public_key(remote.keys.values(), "Master")?.clone();
647	let _lock = self.lock_key(user_id, &public_key).await;
648
649	let ours = self
650		.db
651		.keyid_key
652		.qry(&(user_id, &public_key))
653		.await
654		.optional()?
655		.map(|stored| stored.deserialized())
656		.transpose()
657		.inspect_err(|error| warn!(%user_id, %error, "Replacing an unreadable master key."))
658		.ok()
659		.flatten()
660		.map(|Json(ours): Json<CrossSigningKey>| ours);
661
662	let merged = Raw::new(&with_our_signatures(remote, ours))?;
663
664	self.put_cross_signing_keys(user_id, &[(&merged, public_key, &self.db.userid_masterkeyid)]);
665
666	Ok(())
667}
668
669/// Parses a cross-signing key a client or a server sent.
670///
671/// `label` names the key in errors.
672fn parse_cross_signing_key(key: &Raw<CrossSigningKey>, label: &str) -> Result<CrossSigningKey> {
673	key.deserialize()
674		.map_err(|e| err!(Request(InvalidParam("{label} key is invalid: {e:?}"))))
675}
676
677/// Returns the one public key of a cross-signing key, which names its row.
678///
679/// A key carrying none or several is refused, and `label` names it in errors.
680fn single_public_key<T>(public_keys: impl Iterator<Item = T>, label: &str) -> Result<T> {
681	public_keys
682		.at_most_one()
683		.map_err(|_| err!(Request(InvalidParam("{label} key contained more than one key."))))?
684		.ok_or_else(|| err!(Request(InvalidParam("{label} key contained no key."))))
685}
686
687/// Adds our copy's signatures to a remote key.
688///
689/// Signatures merge per signer and key ID, ours replacing the remote's where
690/// both carry one.
691fn with_our_signatures(
692	mut remote: CrossSigningKey,
693	ours: Option<CrossSigningKey>,
694) -> CrossSigningKey {
695	remote
696		.signatures
697		.extend(ours.into_iter().flat_map(|ours| ours.signatures));
698
699	remote
700}
701
702/// Writes parsed cross-signing keys while their rows are locked.
703///
704/// The rows are locked against signature merges, in public key order, until
705/// the keys are written.
706#[implement(super::Service)]
707async fn store_cross_signing_keys(&self, user_id: &UserId, keys: &[ParsedKey<'_>]) {
708	let public_keys = keys
709		.iter()
710		.map(|(_, public_key, _)| public_key.as_str());
711
712	let _locks = self.lock_keys(user_id, public_keys).await;
713
714	self.put_cross_signing_keys(user_id, keys);
715}
716
717/// Locks one user's cross-signing key rows, named by their public keys.
718///
719/// The rows are taken in one order for every caller, so writers sharing rows
720/// wait for one another instead of deadlocking.
721#[implement(super::Service)]
722async fn lock_keys<'a, PublicKeys>(&self, user_id: &UserId, public_keys: PublicKeys) -> KeyLocks
723where
724	PublicKeys: Iterator<Item = &'a str> + Send,
725{
726	let rows =
727		public_keys.map(|public_key| (user_id.to_owned(), OwnedDeviceId::from(public_key)));
728
729	self.updating_device.lock_all(rows).await
730}
731
732/// Writes cross-signing keys at their rows and points the user at each.
733///
734/// Each row is keyed by user and public key, and the keys and pointers are
735/// written in one transaction.
736#[implement(super::Service)]
737fn put_cross_signing_keys(&self, user_id: &UserId, keys: &[ParsedKey<'_>]) {
738	let mut txn = self.services.db.txn();
739
740	for (key, public_key, pointers) in keys {
741		let row = (user_id, public_key);
742
743		txn.put_raw(&self.db.keyid_key, row, key.json().get().as_bytes());
744		txn.raw_put(pointers, user_id, row);
745	}
746
747	txn.execute();
748}
749
750/// Merges the sender's signatures into a stored key after verifying them.
751///
752/// A signature the signer's and the target's roles do not allow is ignored or
753/// refused, the call fails unless one is accepted, and a merge changing
754/// nothing writes nothing. The read and the write hold the key's row lock, so
755/// concurrent merges keep one another's signatures and never write stale
756/// contents over a key replaced or removed meanwhile.
757#[implement(super::Service)]
758pub async fn sign_key(
759	&self,
760	target_id: &UserId,
761	key_id: &str,
762	signatures: Signatures,
763	sender_id: &UserId,
764) -> Result {
765	let _lock = self.lock_key(target_id, key_id).await;
766	let key = (target_id, key_id);
767
768	let mut target_key: serde_json::Value = self
769		.db
770		.keyid_key
771		.qry(&key)
772		.await
773		.map_err(|error| match error {
774			| error if error.is_not_found() =>
775				err!(Request(NotFound("Tried to sign nonexistent key"))),
776			| error => error,
777		})?
778		.deserialized()
779		.map_err(|e| err!(Database(debug_warn!("key in keyid_key is invalid: {e:?}"))))?;
780
781	let target_role = self
782		.uploaded_key_role(target_id, key_id)
783		.await?
784		.ok_or_else(|| err!(Request(NotFound("Unknown device"))))?;
785
786	if !key_matches_role(&target_key, target_id, key_id, target_role) {
787		return Err!(Request(NotFound("Unknown device")));
788	}
789
790	let same_user = sender_id == target_id;
791	let mut canonical = None;
792	let mut accepted = false;
793	let mut changed = false;
794
795	for (signature_id, signature) in signatures {
796		let signature_key_id = <&SigningKeyId<AnyKeyName>>::try_from(signature_id.as_str())
797			.map_err(|source| VerificationError::ParseIdentifier {
798				identifier_type: "signing key ID",
799				source,
800			})?;
801
802		let signer_role = self
803			.uploaded_key_role(sender_id, signature_key_id.key_name().as_str())
804			.await?;
805
806		let (signer_role, write) = match signature_action(same_user, target_role, signer_role) {
807			| SignatureAction::Ignore => continue,
808			| SignatureAction::Reject => return Err!(Request(NotFound("Unknown device"))),
809			| SignatureAction::Write(signer_role, write) => (signer_role, write),
810		};
811
812		if canonical.is_none() {
813			canonical = Some(canonical_key(&target_key)?);
814		}
815
816		let canonical = canonical
817			.as_deref()
818			.ok_or_else(|| err!(Database("canonical key was not initialized")))?;
819
820		let signature = self
821			.verify_key_signature(
822				sender_id,
823				signature_key_id,
824				signer_role,
825				&signature,
826				canonical.as_bytes(),
827			)
828			.map_ok(|signature| signature.encode())
829			.await?;
830
831		changed |= match write {
832			| SignatureWrite::Merge =>
833				insert_signatures(&mut target_key, sender_id, [(signature_id, signature)])?,
834			| SignatureWrite::ReplaceSender =>
835				replace_signatures(&mut target_key, sender_id, (signature_id, signature))?,
836		};
837
838		accepted = true;
839	}
840
841	if !accepted {
842		return Err!(Request(NotFound("Unknown device")));
843	}
844
845	if !changed {
846		return Ok(());
847	}
848
849	let key = (target_id, key_id);
850	self.db.keyid_key.put(key, Json(target_key));
851
852	if same_user {
853		let change = match target_role {
854			| KeyRole::Device => DeviceListChange::Device(key_id.into()),
855			| _ => DeviceListChange::CrossSigning,
856		};
857
858		self.mark_device_key_update(target_id, change)
859			.await;
860	} else {
861		let count = self.services.globals.next_count();
862
863		self.db
864			.keychangeid_userid
865			.put_raw((sender_id, *count), target_id);
866	}
867
868	Ok(())
869}
870
871/// Locks one key row against its other writers.
872///
873/// Device and cross-signing keys share one row space keyed by user and key ID,
874/// so the device lock serves both, and a device's removal and every write to
875/// its keys contend on that one lock.
876#[implement(super::Service)]
877async fn lock_key(&self, user_id: &UserId, key_id: &str) -> DeviceLock {
878	self.lock_device(user_id, key_id.into()).await
879}
880
881#[implement(super::Service)]
882async fn uploaded_key_role(&self, user_id: &UserId, key_id: &str) -> Result<Option<KeyRole>> {
883	let row_key = serialize_key((user_id, key_id))?;
884	let device_id: &DeviceId = key_id.into();
885
886	let (device, pointers) = join(
887		self.device_exists(user_id, device_id),
888		self.cross_signing_pointers(user_id, row_key.as_slice()),
889	)
890	.await;
891
892	let [root, self_signing, user_signing] = pointers?;
893
894	Ok(key_role([device, root, self_signing, user_signing]))
895}
896
897#[implement(super::Service)]
898pub(super) async fn is_cross_signing_key_id(
899	&self,
900	user_id: &UserId,
901	key_id: &str,
902) -> Result<bool> {
903	// Cross-signing rows share the device key row space under the bare public key.
904	let row_key = serialize_key((user_id, key_id))?;
905
906	self.cross_signing_pointers(user_id, row_key.as_slice())
907		.map_ok(|pointers| pointers.contains(&true))
908		.await
909}
910
911#[implement(super::Service)]
912async fn cross_signing_pointers(&self, user_id: &UserId, row_key: &[u8]) -> Result<[bool; 3]> {
913	try_join3(
914		pointer_matches(&self.db.userid_masterkeyid, user_id, row_key),
915		pointer_matches(&self.db.userid_selfsigningkeyid, user_id, row_key),
916		pointer_matches(&self.db.userid_usersigningkeyid, user_id, row_key),
917	)
918	.map_ok(|(root, self_signing, user_signing)| [root, self_signing, user_signing])
919	.await
920}
921
922#[tracing::instrument(
923	level = "trace",
924	skip_all,
925	fields(
926		user = %user_id,
927	)
928)]
929async fn pointer_matches(map: &Arc<Map>, user_id: &UserId, row_key: &[u8]) -> Result<bool> {
930	match map.get(user_id).await {
931		| Ok(pointer) => Ok(&*pointer == row_key),
932		| Err(error) if error.is_not_found() => Ok(false),
933		| Err(error) => Err(error),
934	}
935}
936
937fn key_role([device, root, self_signing, user_signing]: [bool; 4]) -> Option<KeyRole> {
938	match (device, root, self_signing, user_signing) {
939		| (true, false, false, false) => Some(KeyRole::Device),
940		| (false, true, false, false) => Some(KeyRole::CrossSigningRoot),
941		| (false, false, true, false) => Some(KeyRole::SelfSigning),
942		| (false, false, false, true) => Some(KeyRole::UserSigning),
943		| _ => None,
944	}
945}
946
947fn key_matches_role(
948	key: &serde_json::Value,
949	user_id: &UserId,
950	key_id: &str,
951	role: KeyRole,
952) -> bool {
953	if key
954		.get("user_id")
955		.and_then(serde_json::Value::as_str)
956		!= Some(user_id.as_str())
957	{
958		return false;
959	}
960
961	match role {
962		| KeyRole::Device =>
963			key.get("device_id")
964				.and_then(serde_json::Value::as_str)
965				== Some(key_id),
966		| KeyRole::CrossSigningRoot | KeyRole::SelfSigning | KeyRole::UserSigning =>
967			key.get("device_id").is_none()
968				&& key
969					.get("keys")
970					.and_then(serde_json::Value::as_object)
971					.is_some_and(|keys| {
972						keys.len() == 1
973							&& keys
974								.values()
975								.any(|value| value.as_str() == Some(key_id))
976					}),
977	}
978}
979
980fn signature_action(
981	same_user: bool,
982	target: KeyRole,
983	signer: Option<KeyRole>,
984) -> SignatureAction {
985	match (same_user, target, signer) {
986		| (true, KeyRole::CrossSigningRoot, Some(KeyRole::Device)) =>
987			SignatureAction::Write(KeyRole::Device, SignatureWrite::Merge),
988		| (true, KeyRole::CrossSigningRoot, _) => SignatureAction::Reject,
989		| (true, KeyRole::Device, Some(KeyRole::SelfSigning)) =>
990			SignatureAction::Write(KeyRole::SelfSigning, SignatureWrite::Merge),
991		| (false, KeyRole::CrossSigningRoot, Some(KeyRole::UserSigning)) =>
992			SignatureAction::Write(KeyRole::UserSigning, SignatureWrite::ReplaceSender),
993		| _ => SignatureAction::Ignore,
994	}
995}
996
997fn canonical_key(key: &serde_json::Value) -> Result<String> {
998	let key = to_canonical_object(key)?;
999
1000	Ok(to_canonical_json_string_for_signing(&key)?)
1001}
1002
1003#[implement(super::Service)]
1004#[tracing::instrument(
1005	level = "trace",
1006	skip_all,
1007	fields(
1008		sender = %sender_id,
1009		signing_key_id = %key_id,
1010		?role,
1011	)
1012)]
1013async fn verify_key_signature(
1014	&self,
1015	sender_id: &UserId,
1016	key_id: &SigningKeyId<AnyKeyName>,
1017	role: KeyRole,
1018	signature: &str,
1019	canonical: &[u8],
1020) -> Result<Base64> {
1021	let signing_key: serde_json::Value = self
1022		.db
1023		.keyid_key
1024		.qry(&(sender_id, key_id.key_name().as_str()))
1025		.map_err(|error| match error {
1026			| error if error.is_not_found() =>
1027				VerificationError::NoPublicKeysForEntity(sender_id.to_string()).into(),
1028			| error => error,
1029		})
1030		.await?
1031		.deserialized()
1032		.map_err(|e| err!(Database(debug_warn!("key in keyid_key is invalid: {e:?}"))))?;
1033
1034	if !key_matches_role(&signing_key, sender_id, key_id.key_name().as_str(), role) {
1035		return Err(VerificationError::NoPublicKeysForEntity(sender_id.to_string()).into());
1036	}
1037
1038	let public_key = signing_key
1039		.get("keys")
1040		.and_then(|keys| keys.get(key_id.as_str()))
1041		.and_then(serde_json::Value::as_str)
1042		.ok_or_else(|| {
1043			Error::from(VerificationError::NoPublicKeysForEntity(sender_id.to_string()))
1044		})?;
1045
1046	verify_signature(sender_id, key_id, public_key, signature, canonical)
1047}
1048
1049fn verify_signature(
1050	sender_id: &UserId,
1051	key_id: &SigningKeyId<AnyKeyName>,
1052	public_key: &str,
1053	signature: &str,
1054	canonical: &[u8],
1055) -> Result<Base64> {
1056	let public_key = Base64::<Standard>::parse(public_key)
1057		.map_err(|_| VerificationError::NoPublicKeysForEntity(sender_id.to_string()))?;
1058
1059	let signature = Base64::<Standard>::parse(signature).map_err(|source| {
1060		VerificationError::InvalidBase64Signature {
1061			path: format!("signatures.{sender_id}.{key_id}"),
1062			source,
1063		}
1064	})?;
1065
1066	verify_canonical_json_bytes(
1067		&key_id.algorithm(),
1068		public_key.as_bytes(),
1069		signature.as_bytes(),
1070		canonical,
1071	)?;
1072
1073	Ok(signature)
1074}
1075
1076fn insert_signatures(
1077	key: &mut serde_json::Value,
1078	sender_id: &UserId,
1079	additional: impl IntoIterator<Item = (String, String)>,
1080) -> Result<bool> {
1081	let signatures = signatures_map(key)?;
1082
1083	let signatures = signatures
1084		.entry(sender_id.to_string())
1085		.or_insert_with(|| serde_json::Map::new().into())
1086		.as_object_mut()
1087		.ok_or_else(|| {
1088			err!(Database(debug_warn!("signature data in keyid_key for a user is invalid.")))
1089		})?;
1090
1091	let changed = additional
1092		.into_iter()
1093		.fold(false, |changed, (key_id, signature)| {
1094			let entry_changed = signatures
1095				.get(&key_id)
1096				.and_then(serde_json::Value::as_str)
1097				!= Some(&signature);
1098
1099			if entry_changed {
1100				signatures.insert(key_id, signature.into());
1101			}
1102
1103			changed | entry_changed
1104		});
1105
1106	Ok(changed)
1107}
1108
1109fn signatures_map(
1110	key: &mut serde_json::Value,
1111) -> Result<&mut serde_json::Map<String, serde_json::Value>> {
1112	let key = key
1113		.as_object_mut()
1114		.ok_or_else(|| err!(Database(debug_warn!("key in keyid_key is not an object."))))?;
1115
1116	key.entry("signatures")
1117		.or_insert_with(|| serde_json::Map::new().into())
1118		.as_object_mut()
1119		.ok_or_else(|| {
1120			err!(Database(debug_warn!("key in keyid_key has invalid signatures field.")))
1121		})
1122}
1123
1124fn replace_signatures(
1125	key: &mut serde_json::Value,
1126	sender_id: &UserId,
1127	(key_id, signature): (String, String),
1128) -> Result<bool> {
1129	let signatures = signatures_map(key)?;
1130	let replacement = serde_json::Map::from_iter([(key_id, signature.into())]);
1131
1132	match signatures.get_mut(sender_id.as_str()) {
1133		| Some(signatures)
1134			if signatures
1135				.as_object()
1136				.is_some_and(|signatures| signatures == &replacement) =>
1137			return Ok(false),
1138		| Some(signatures) => *signatures = replacement.into(),
1139		| None => {
1140			signatures.insert(sender_id.to_string(), replacement.into());
1141		},
1142	}
1143
1144	Ok(true)
1145}
1146
1147#[implement(super::Service)]
1148#[inline]
1149pub fn keys_changed<'a>(
1150	&'a self,
1151	user_id: &'a UserId,
1152	from: u64,
1153	to: Option<u64>,
1154) -> impl Stream<Item = &UserId> + Send + 'a {
1155	self.keys_changed_user_or_room(user_id.as_str(), from, to)
1156		.map(|(user_id, ..)| user_id)
1157}
1158
1159#[implement(super::Service)]
1160#[inline]
1161pub fn room_keys_changed<'a>(
1162	&'a self,
1163	room_id: &'a RoomId,
1164	from: u64,
1165	to: Option<u64>,
1166) -> impl Stream<Item = (&UserId, u64)> + Send + 'a {
1167	self.keys_changed_user_or_room(room_id.as_str(), from, to)
1168}
1169
1170#[implement(super::Service)]
1171fn keys_changed_user_or_room<'a>(
1172	&'a self,
1173	user_or_room_id: &'a str,
1174	from: u64,
1175	to: Option<u64>,
1176) -> impl Stream<Item = (&UserId, u64)> + Send + 'a {
1177	type KeyVal<'a> = ((&'a str, u64), &'a UserId);
1178
1179	let to = to.unwrap_or(u64::MAX);
1180	let start = (user_or_room_id, from.saturating_add(1));
1181	self.db
1182		.keychangeid_userid
1183		.stream_from(&start)
1184		.ignore_err()
1185		.ready_take_while(move |((prefix, count), _): &KeyVal<'_>| {
1186			*prefix == user_or_room_id && *count <= to
1187		})
1188		.map(|((_, count), user_id): KeyVal<'_>| (user_id, count))
1189}
1190
1191/// Records a device-list change for a user and pushes it to interested peers.
1192///
1193/// The change is durable before any peer is contacted, and the unbounded sender
1194/// channels refuse only once closed, so a refused flush is a shutdown race
1195/// rather than a fault.
1196#[implement(super::Service)]
1197#[tracing::instrument(
1198	name = "device_key_update"
1199	level = INFO_SPAN_LEVEL,
1200	skip_all,
1201	fields(%user_id),
1202)]
1203pub async fn mark_device_key_update(
1204	&self,
1205	user_id: &UserId,
1206	change: DeviceListChange<&DeviceId>,
1207) {
1208	let update_all_rooms = !self
1209		.services
1210		.config
1211		.encryption
1212		.device_key_update_encrypted_rooms_only;
1213
1214	let all_or_is_encrypted = async |room_id: &RoomId| {
1215		update_all_rooms
1216			|| self
1217				.services
1218				.state_accessor
1219				.is_encrypted_room(room_id)
1220				.await
1221	};
1222
1223	let local = self.services.globals.user_is_local(user_id);
1224	let guard = local
1225		.then_async(async || self.device_list_mutex.lock(user_id).await)
1226		.await;
1227
1228	let count = self.services.globals.next_count();
1229
1230	if local {
1231		let current = self
1232			.get_devicelist_version(user_id)
1233			.await
1234			.unwrap_or(0);
1235
1236		let stream_id = current
1237			.checked_add(u64::from(!matches!(change, DeviceListChange::CrossSigning)))
1238			.expect("device-list stream exhausted");
1239
1240		if !matches!(change, DeviceListChange::CrossSigning) {
1241			self.db
1242				.userid_devicelistversion
1243				.raw_put(user_id, stream_id);
1244		}
1245
1246		let (kind, device_id) = match change {
1247			| DeviceListChange::Resync => (DeviceListChangeKind::Resync, ""),
1248			| DeviceListChange::Device(id) => (DeviceListChangeKind::Device, id.as_str()),
1249			| DeviceListChange::Deleted(id) => (DeviceListChangeKind::Deleted, id.as_str()),
1250			| DeviceListChange::CrossSigning => (DeviceListChangeKind::CrossSigning, ""),
1251		};
1252
1253		// The value layout is (kind: u8, stream_id: u64, device_id: str).
1254		self.db
1255			.keychangeid_devicechange
1256			.put(*count, (u8::from(kind), stream_id, device_id));
1257	}
1258
1259	let user_key = (user_id, *count);
1260
1261	self.db
1262		.keychangeid_userid
1263		.put_raw(user_key, user_id);
1264
1265	self.services
1266		.state_cache
1267		.rooms_joined(user_id)
1268		.filter(|room_id| all_or_is_encrypted(*room_id))
1269		.ready_for_each(|room_id| {
1270			let room_key = (room_id, *count);
1271			self.db
1272				.keychangeid_userid
1273				.put_raw(room_key, user_id);
1274		})
1275		.await;
1276
1277	drop(guard);
1278
1279	self.services
1280		.sending
1281		.send_device_list_appservices(user_id, *count)
1282		.await
1283		.log_err()
1284		.ok();
1285
1286	// Retire this change before discovering and waking federation peers.
1287	drop(count);
1288
1289	if !local {
1290		return;
1291	}
1292
1293	// device_list_update EDUs reach remote servers only on a sender flush.
1294	let mut servers: Servers = self
1295		.services
1296		.state_cache
1297		.rooms_joined(user_id)
1298		.filter(|room_id| all_or_is_encrypted(*room_id))
1299		.map(ToOwned::to_owned)
1300		.broad_then(async |room_id: OwnedRoomId| {
1301			self.services
1302				.state_cache
1303				.remote_room_servers(&room_id)
1304				.map(ToOwned::to_owned)
1305				.collect()
1306				.await
1307		})
1308		.flat_map(|servers: Vec<OwnedServerName>| servers.into_iter().stream())
1309		.collect()
1310		.await;
1311
1312	servers.sort_unstable();
1313	servers.dedup();
1314
1315	self.services
1316		.sending
1317		.flush_servers(servers.iter().map(|server| &**server).stream())
1318		.await
1319		.inspect_err(|e| debug_warn!(%e, "device list flush refused"))
1320		.ok();
1321}
1322
1323/// Reads the mutation recorded for a local device-list notification.
1324///
1325/// Missing records return `NotFound`; unknown kind tags request a snapshot resync.
1326#[implement(super::Service)]
1327#[tracing::instrument(level = "trace", skip(self))]
1328pub async fn device_list_change(&self, count: u64) -> Result<DeviceListRecord> {
1329	let row = self
1330		.db
1331		.keychangeid_devicechange
1332		.qry(&count)
1333		.await?;
1334
1335	let (kind, stream_id, device_id): (u8, u64, &str) = deserialize_from_slice(&row)?;
1336	let change =
1337		match DeviceListChangeKind::try_from(kind).unwrap_or(DeviceListChangeKind::Resync) {
1338			| DeviceListChangeKind::Resync => DeviceListChange::Resync,
1339			| DeviceListChangeKind::Device => DeviceListChange::Device(device_id.into()),
1340			| DeviceListChangeKind::Deleted => DeviceListChange::Deleted(device_id.into()),
1341			| DeviceListChangeKind::CrossSigning => DeviceListChange::CrossSigning,
1342		};
1343
1344	Ok(DeviceListRecord { change, stream_id })
1345}
1346
1347impl From<DeviceListChangeKind> for u8 {
1348	fn from(kind: DeviceListChangeKind) -> Self {
1349		match kind {
1350			| DeviceListChangeKind::Resync => 0,
1351			| DeviceListChangeKind::Device => 1,
1352			| DeviceListChangeKind::Deleted => 2,
1353			| DeviceListChangeKind::CrossSigning => 3,
1354		}
1355	}
1356}
1357
1358impl TryFrom<u8> for DeviceListChangeKind {
1359	type Error = ();
1360
1361	fn try_from(kind: u8) -> Result<Self, Self::Error> {
1362		match kind {
1363			| 0 => Ok(Self::Resync),
1364			| 1 => Ok(Self::Device),
1365			| 2 => Ok(Self::Deleted),
1366			| 3 => Ok(Self::CrossSigning),
1367			| _ => Err(()),
1368		}
1369	}
1370}
1371
1372#[implement(super::Service)]
1373pub async fn get_device_keys<'a>(
1374	&'a self,
1375	user_id: &'a UserId,
1376	device_id: &DeviceId,
1377) -> Result<Raw<DeviceKeys>> {
1378	let key_id = (user_id, device_id);
1379	self.db
1380		.keyid_key
1381		.qry(&key_id)
1382		.await
1383		.deserialized()
1384}
1385
1386/// Reads the cross-signing key stored at one row of the key table.
1387///
1388/// `row_key` is the serialized user ID and public key naming the row, the form
1389/// the user's pointer rows store, never a key ID. The sender sees every
1390/// signature on their own key; anyone else sees only the owner's and those
1391/// `allowed_signatures` accepts.
1392#[implement(super::Service)]
1393pub async fn get_key<F>(
1394	&self,
1395	row_key: &[u8],
1396	sender_user: Option<&UserId>,
1397	user_id: &UserId,
1398	allowed_signatures: &F,
1399) -> Result<Raw<CrossSigningKey>>
1400where
1401	F: Fn(&UserId) -> bool + Send + Sync,
1402{
1403	let key: serde_json::Value = self
1404		.db
1405		.keyid_key
1406		.get(row_key)
1407		.await
1408		.deserialized()?;
1409
1410	let cleaned = clean_signatures(key, sender_user, user_id, allowed_signatures)?;
1411	let raw_value = serde_json::value::to_raw_value(&cleaned)?;
1412
1413	Ok(Raw::from_json(raw_value))
1414}
1415
1416/// Reads a user's master key through its pointer row.
1417///
1418/// An absent pointer errs as not found. Signatures narrow as in `get_key`.
1419#[implement(super::Service)]
1420pub async fn get_master_key<F>(
1421	&self,
1422	sender_user: Option<&UserId>,
1423	user_id: &UserId,
1424	allowed_signatures: &F,
1425) -> Result<Raw<CrossSigningKey>>
1426where
1427	F: Fn(&UserId) -> bool + Send + Sync,
1428{
1429	let row_key = self.db.userid_masterkeyid.get(user_id).await?;
1430
1431	self.get_key(&row_key, sender_user, user_id, allowed_signatures)
1432		.await
1433}
1434
1435/// Reads a user's self-signing key through its pointer row.
1436///
1437/// An absent pointer errs as not found. Signatures narrow as in `get_key`.
1438#[implement(super::Service)]
1439pub async fn get_self_signing_key<F>(
1440	&self,
1441	sender_user: Option<&UserId>,
1442	user_id: &UserId,
1443	allowed_signatures: &F,
1444) -> Result<Raw<CrossSigningKey>>
1445where
1446	F: Fn(&UserId) -> bool + Send + Sync,
1447{
1448	let row_key = self
1449		.db
1450		.userid_selfsigningkeyid
1451		.get(user_id)
1452		.await?;
1453
1454	self.get_key(&row_key, sender_user, user_id, allowed_signatures)
1455		.await
1456}
1457
1458/// Reads a user's user-signing key through its pointer row.
1459///
1460/// An absent pointer errs as not found. The stored signatures come back whole,
1461/// unlike the master and self-signing readers.
1462#[implement(super::Service)]
1463pub async fn get_user_signing_key(&self, user_id: &UserId) -> Result<Raw<CrossSigningKey>> {
1464	self.db
1465		.userid_usersigningkeyid
1466		.get(user_id)
1467		.and_then(|row_key| self.db.keyid_key.get(&*row_key))
1468		.await
1469		.deserialized()
1470}
1471
1472/// Parses a master key, refusing a key carrying no public key or several.
1473///
1474/// Returns the key's row in the key table together with the parsed key.
1475pub fn parse_master_key(
1476	user_id: &UserId,
1477	master_key: &Raw<CrossSigningKey>,
1478) -> Result<(Vec<u8>, CrossSigningKey)> {
1479	let master_key = parse_cross_signing_key(master_key, "Master")?;
1480	let public_key = single_public_key(master_key.keys.values(), "Master")?;
1481	let row = serialize_to_vec((user_id, public_key))?;
1482
1483	Ok((row, master_key))
1484}
1485
1486/// Ensure that a user only sees signatures from themselves and the target user
1487fn clean_signatures<F>(
1488	mut cross_signing_key: serde_json::Value,
1489	sender_user: Option<&UserId>,
1490	user_id: &UserId,
1491	allowed_signatures: &F,
1492) -> Result<serde_json::Value>
1493where
1494	F: Fn(&UserId) -> bool + Send + Sync,
1495{
1496	if let Some(signatures) = cross_signing_key
1497		.get_mut("signatures")
1498		.and_then(|v| v.as_object_mut())
1499	{
1500		// Don't allocate for the full size of the current signatures, but require
1501		// at most one resize if nothing is dropped
1502		let new_capacity = signatures.len() / 2;
1503		for (user, signature) in
1504			mem::replace(signatures, serde_json::Map::with_capacity(new_capacity))
1505		{
1506			let sid = <&UserId>::try_from(user.as_str())
1507				.map_err(|e| err!(Database("Invalid user ID in database: {e}")))?;
1508
1509			if sender_user == Some(user_id) || sid == user_id || allowed_signatures(sid) {
1510				signatures.insert(user, signature);
1511			}
1512		}
1513	}
1514
1515	Ok(cross_signing_key)
1516}
1517
1518#[cfg(test)]
1519mod tests {
1520	use ruma::{
1521		OwnedDeviceKeyId,
1522		signatures::{Ed25519KeyPair, KeyPair},
1523		user_id,
1524	};
1525
1526	use super::*;
1527
1528	#[test]
1529	fn device_list_record_codec() {
1530		for device_id in ["DEVICE", ""] {
1531			let record = (1_u8, 42_u64, device_id);
1532			let bytes = serialize_to_vec(record).expect("serialize device change");
1533
1534			assert_eq!(bytes.len(), 1 + 1 + 8 + 1 + device_id.len());
1535			assert_eq!(bytes[0], 1);
1536			assert_eq!(bytes[1], 0xFF);
1537			assert_eq!(&bytes[2..10], &42_u64.to_be_bytes());
1538			assert_eq!(bytes[10], 0xFF);
1539			assert_eq!(&bytes[11..], device_id.as_bytes());
1540			let decoded: (u8, u64, &str) =
1541				deserialize_from_slice(&bytes).expect("decode device change");
1542
1543			assert_eq!(decoded, record);
1544		}
1545	}
1546
1547	fn signature_fixture() -> (String, String, Vec<u8>) {
1548		let der = Ed25519KeyPair::generate();
1549		let keypair = Ed25519KeyPair::from_der(&der, "DEVICE".to_owned())
1550			.expect("key pair should be generated");
1551
1552		let key = serde_json::json!({
1553			"user_id": "@alice:example.com",
1554			"device_id": "DEVICE",
1555			"keys": { "ed25519:DEVICE": "public-key" },
1556		});
1557
1558		let canonical = canonical_key(&key)
1559			.expect("signing JSON should serialize")
1560			.into_bytes();
1561
1562		let signature = keypair.sign(&canonical).base64();
1563		let public_key = Base64::<Standard, _>::new(keypair.public_key()).encode();
1564
1565		(public_key, signature, canonical)
1566	}
1567
1568	#[test]
1569	fn verifies_canonical_signature_bytes() {
1570		let sender_id = user_id!("@alice:example.com");
1571		let key_id = <&SigningKeyId<AnyKeyName>>::try_from("ed25519:DEVICE")
1572			.expect("signature key ID should parse");
1573
1574		let (public_key, signature, canonical) = signature_fixture();
1575
1576		verify_signature(sender_id, key_id, &public_key, &signature, &canonical)
1577			.expect("signature should verify");
1578	}
1579
1580	#[test]
1581	fn canonicalizes_stored_key_for_verification() {
1582		let sender_id = user_id!("@alice:example.com");
1583		let key_id = <&SigningKeyId<AnyKeyName>>::try_from("ed25519:DEVICE")
1584			.expect("signature key ID should parse");
1585
1586		let der = Ed25519KeyPair::generate();
1587		let keypair = Ed25519KeyPair::from_der(&der, "DEVICE".to_owned())
1588			.expect("key pair should be generated");
1589
1590		let mut stored_key = serde_json::json!({
1591			"user_id": sender_id,
1592			"device_id": "DEVICE",
1593			"keys": { "ed25519:DEVICE": "public-key" },
1594		});
1595
1596		let canonical = canonical_key(&stored_key).expect("stored key should canonicalize");
1597		let signature = keypair.sign(canonical.as_bytes()).base64();
1598		let public_key = Base64::<Standard, _>::new(keypair.public_key()).encode();
1599
1600		stored_key["signatures"] = serde_json::json!({
1601			"@bob:example.com": { "ed25519:BOB": "bob-signature" },
1602		});
1603
1604		stored_key["unsigned"] = serde_json::json!({ "server_data": "ignored" });
1605		let canonical_with_metadata =
1606			canonical_key(&stored_key).expect("stored key with metadata should canonicalize");
1607
1608		assert_eq!(canonical_with_metadata, canonical);
1609		verify_signature(
1610			sender_id,
1611			key_id,
1612			&public_key,
1613			&signature,
1614			canonical_with_metadata.as_bytes(),
1615		)
1616		.expect("signature over the stored key should verify");
1617	}
1618
1619	#[test]
1620	fn rejects_signature_over_different_key() {
1621		let sender_id = user_id!("@alice:example.com");
1622		let key_id = <&SigningKeyId<AnyKeyName>>::try_from("ed25519:DEVICE")
1623			.expect("signature key ID should parse");
1624
1625		let (public_key, signature, _) = signature_fixture();
1626
1627		let error = verify_signature(sender_id, key_id, &public_key, &signature, b"{}")
1628			.expect_err("signature over another object should fail");
1629
1630		assert!(matches!(error, Error::Signatures(_)));
1631	}
1632
1633	#[test]
1634	fn rejects_malformed_signature_base64() {
1635		let sender_id = user_id!("@alice:example.com");
1636		let key_id = <&SigningKeyId<AnyKeyName>>::try_from("ed25519:DEVICE")
1637			.expect("signature key ID should parse");
1638
1639		let (public_key, _, canonical) = signature_fixture();
1640
1641		let error = verify_signature(sender_id, key_id, &public_key, "not base64?", &canonical)
1642			.expect_err("malformed signature base64 should fail");
1643
1644		assert!(matches!(
1645			error,
1646			Error::Signatures(VerificationError::InvalidBase64Signature { .. })
1647		));
1648	}
1649
1650	#[test]
1651	fn classifies_only_unambiguous_key_roles() {
1652		for mask in 0_u8..16 {
1653			let matches = [mask & 1 != 0, mask & 2 != 0, mask & 4 != 0, mask & 8 != 0];
1654			let expected = match mask {
1655				| 1 => Some(KeyRole::Device),
1656				| 2 => Some(KeyRole::CrossSigningRoot),
1657				| 4 => Some(KeyRole::SelfSigning),
1658				| 8 => Some(KeyRole::UserSigning),
1659				| _ => None,
1660			};
1661
1662			assert_eq!(key_role(matches), expected, "role mask {mask:04b}");
1663		}
1664	}
1665
1666	#[test]
1667	fn binds_key_roles_to_owner_and_row_shape() {
1668		let user_id = user_id!("@alice:example.com");
1669		let device = serde_json::json!({
1670			"user_id": user_id,
1671			"device_id": "DEVICE",
1672			"keys": { "ed25519:DEVICE": "device-public-key" },
1673		});
1674
1675		let cross_signing = serde_json::json!({
1676			"user_id": user_id,
1677			"usage": ["untrusted-value"],
1678			"keys": { "ed25519:ROOT": "root-public-key" },
1679		});
1680
1681		let multiple_keys = serde_json::json!({
1682			"user_id": user_id,
1683			"keys": {
1684				"ed25519:ROOT": "root-public-key",
1685				"ed25519:OTHER": "other-public-key",
1686			},
1687		});
1688
1689		assert!(key_matches_role(&device, user_id, "DEVICE", KeyRole::Device));
1690		assert!(!key_matches_role(&device, user_id, "DEVICE", KeyRole::CrossSigningRoot));
1691		assert!(key_matches_role(
1692			&cross_signing,
1693			user_id,
1694			"root-public-key",
1695			KeyRole::CrossSigningRoot
1696		));
1697		assert!(!key_matches_role(
1698			&multiple_keys,
1699			user_id,
1700			"root-public-key",
1701			KeyRole::CrossSigningRoot
1702		));
1703		assert!(!key_matches_role(
1704			&cross_signing,
1705			user_id,
1706			"different-public-key",
1707			KeyRole::CrossSigningRoot
1708		));
1709
1710		assert!(!key_matches_role(
1711			&cross_signing,
1712			user_id!("@bob:example.com"),
1713			"root-public-key",
1714			KeyRole::CrossSigningRoot
1715		));
1716	}
1717
1718	#[test]
1719	fn accepts_only_supported_signature_scopes() {
1720		let roles = [
1721			KeyRole::Device,
1722			KeyRole::CrossSigningRoot,
1723			KeyRole::SelfSigning,
1724			KeyRole::UserSigning,
1725		];
1726		let cases = [false, true].into_iter().flat_map(|same_user| {
1727			roles.into_iter().flat_map(move |target| {
1728				roles
1729					.into_iter()
1730					.map(Some)
1731					.chain([None])
1732					.map(move |signer| (same_user, target, signer))
1733			})
1734		});
1735
1736		for (same_user, target, signer) in cases {
1737			let expected = match (same_user, target, signer) {
1738				| (true, KeyRole::CrossSigningRoot, Some(KeyRole::Device)) =>
1739					SignatureAction::Write(KeyRole::Device, SignatureWrite::Merge),
1740				| (true, KeyRole::CrossSigningRoot, _) => SignatureAction::Reject,
1741				| (true, KeyRole::Device, Some(KeyRole::SelfSigning)) =>
1742					SignatureAction::Write(KeyRole::SelfSigning, SignatureWrite::Merge),
1743				| (false, KeyRole::CrossSigningRoot, Some(KeyRole::UserSigning)) =>
1744					SignatureAction::Write(KeyRole::UserSigning, SignatureWrite::ReplaceSender),
1745				| _ => SignatureAction::Ignore,
1746			};
1747
1748			assert_eq!(
1749				signature_action(same_user, target, signer),
1750				expected,
1751				"same_user={same_user}, target={target:?}, signer={signer:?}"
1752			);
1753		}
1754	}
1755
1756	#[test]
1757	fn replacing_signatures_bounds_key_rotation_history() {
1758		let sender_id = user_id!("@alice:example.com");
1759		let mut key = serde_json::json!({
1760			"signatures": {
1761				"@alice:example.com": { "ed25519:OLD": "old-signature" },
1762				"@bob:example.com": { "ed25519:BOB": "bob-signature" },
1763			},
1764		});
1765
1766		let changed = replace_signatures(
1767			&mut key,
1768			sender_id,
1769			("ed25519:NEW".to_owned(), "new-signature".to_owned()),
1770		)
1771		.expect("signature replacement should succeed");
1772
1773		assert!(changed);
1774
1775		let changed = replace_signatures(
1776			&mut key,
1777			sender_id,
1778			("ed25519:NEW".to_owned(), "new-signature".to_owned()),
1779		)
1780		.expect("idempotent signature replacement should succeed");
1781
1782		assert!(!changed);
1783
1784		let sender_signatures = key["signatures"][sender_id.as_str()]
1785			.as_object()
1786			.expect("sender signatures should remain an object");
1787
1788		assert_eq!(sender_signatures.len(), 1);
1789		assert_eq!(sender_signatures["ed25519:NEW"], "new-signature");
1790		assert_eq!(key["signatures"]["@bob:example.com"]["ed25519:BOB"], "bob-signature");
1791	}
1792
1793	#[test]
1794	fn insert_signatures_creates_missing_map() {
1795		let sender_id = user_id!("@alice:example.com");
1796		let mut key = serde_json::json!({
1797			"user_id": sender_id,
1798			"keys": { "ed25519:ALICE": "ALICE" },
1799		});
1800		let signatures = [("ed25519:ALICE".to_owned(), "alice-signature".to_owned())];
1801
1802		let changed = insert_signatures(&mut key, sender_id, signatures)
1803			.expect("signature insertion should succeed");
1804
1805		assert!(changed);
1806
1807		let signatures = [("ed25519:ALICE".to_owned(), "alice-signature".to_owned())];
1808		let changed = insert_signatures(&mut key, sender_id, signatures)
1809			.expect("idempotent signature insertion should succeed");
1810
1811		assert!(!changed);
1812
1813		assert_eq!(key["signatures"][sender_id.as_str()]["ed25519:ALICE"], "alice-signature");
1814	}
1815
1816	#[test]
1817	fn insert_signatures_preserves_existing_signers() {
1818		let sender_id = user_id!("@alice:example.com");
1819		let mut key = serde_json::json!({
1820			"user_id": sender_id,
1821			"keys": { "ed25519:ROOT": "root-public-key" },
1822			"signatures": {
1823				"@alice:example.com": { "ed25519:OLD": "old-signature" },
1824				"@bob:example.com": { "ed25519:BOB": "bob-signature" },
1825			},
1826		});
1827		let signatures = [
1828			("ed25519:ALICE1".to_owned(), "alice-signature-1".to_owned()),
1829			("ed25519:ALICE2".to_owned(), "alice-signature-2".to_owned()),
1830		];
1831
1832		let changed = insert_signatures(&mut key, sender_id, signatures)
1833			.expect("signature insertion should succeed");
1834
1835		assert!(changed);
1836
1837		let expected = serde_json::json!({
1838			"user_id": sender_id,
1839			"keys": { "ed25519:ROOT": "root-public-key" },
1840			"signatures": {
1841				"@alice:example.com": {
1842					"ed25519:OLD": "old-signature",
1843					"ed25519:ALICE1": "alice-signature-1",
1844					"ed25519:ALICE2": "alice-signature-2",
1845				},
1846				"@bob:example.com": { "ed25519:BOB": "bob-signature" },
1847			},
1848		});
1849
1850		assert_eq!(key, expected);
1851	}
1852
1853	#[test]
1854	fn device_key_id_with_long_multibyte_algorithm_parses() {
1855		let key_id = long_multibyte_key_id();
1856		let device_key_id: OwnedDeviceKeyId = key_id
1857			.parse()
1858			.expect("device key ID should parse");
1859
1860		assert_eq!(device_key_id.algorithm().as_str(), long_multibyte_algorithm());
1861		assert_eq!(device_key_id.key_name().as_str(), "AAAA");
1862
1863		let keys = serde_json::json!({ &key_id: "public-key" }).to_string();
1864		let keys: BTreeMap<OwnedDeviceKeyId, String> =
1865			serde_json::from_str(&keys).expect("device key ID map key should deserialize");
1866
1867		assert!(keys.contains_key(&device_key_id));
1868	}
1869
1870	#[test]
1871	fn master_key_with_long_multibyte_key_id_parses() {
1872		let user_id = user_id!("@alice:example.com");
1873		let key_id = long_multibyte_key_id();
1874		let master_key = serde_json::json!({
1875			"user_id": user_id,
1876			"usage": ["master"],
1877			"keys": { &key_id: "public-key" },
1878		});
1879
1880		let master_key: Raw<CrossSigningKey> = serde_json::from_str(&master_key.to_string())
1881			.expect("master key should be valid JSON");
1882
1883		let (storage_key, master_key) =
1884			parse_master_key(user_id, &master_key).expect("master key should parse");
1885
1886		let (parsed_key_id, _) = master_key
1887			.keys
1888			.first_key_value()
1889			.expect("master key should keep its key");
1890
1891		assert_eq!(parsed_key_id.as_str(), key_id);
1892		assert!(storage_key.ends_with(b"public-key"));
1893	}
1894
1895	fn long_multibyte_key_id() -> String { format!("{}:AAAA", long_multibyte_algorithm()) }
1896
1897	// 129 two-byte characters make a 258-byte algorithm.
1898	fn long_multibyte_algorithm() -> String { "é".repeat(129) }
1899
1900	#[test]
1901	fn empty_one_time_key_counts_include_signed_zero() {
1902		let counts = complete_one_time_key_counts(BTreeMap::new());
1903
1904		assert_eq!(counts.len(), 1);
1905		assert_eq!(counts.get(&OneTimeKeyAlgorithm::SignedCurve25519), Some(&UInt::from(0_u32)));
1906	}
1907
1908	#[test]
1909	fn existing_one_time_key_counts_are_preserved() {
1910		let mut counts = BTreeMap::new();
1911		counts.insert(OneTimeKeyAlgorithm::from("curve25519"), UInt::from(11_u32));
1912		counts.insert(OneTimeKeyAlgorithm::SignedCurve25519, UInt::from(17_u32));
1913
1914		let counts = complete_one_time_key_counts(counts);
1915
1916		assert_eq!(
1917			counts.get(&OneTimeKeyAlgorithm::from("curve25519")),
1918			Some(&UInt::from(11_u32))
1919		);
1920		assert_eq!(counts.get(&OneTimeKeyAlgorithm::SignedCurve25519), Some(&UInt::from(17_u32)));
1921	}
1922}