arminius_server_client/handlers/

cross_signing.rs

// SPDX-FileCopyrightText: 2025 BWI GmbH
//
// SPDX-License-Identifier: Apache-2.0

//! Implements APIs for device verification.
//!
//! Useful specs:
//! - Device verification section: <https://spec.matrix.org/v1.15/client-server-api/#device-verification>
//! - Cross-signing: <https://spec.matrix.org/v1.15/client-server-api/#cross-signing>

#![allow(
	clippy::allow_attributes,
	reason = "This source file contains enums which allow `clippy::missing_docs_in_private_items`. But an exception to this lint will mistakenly report that it's unfulfilled when used with expect, even though it is not."
)]

use std::collections::BTreeMap;

use arminius_lib_authentication::SessionInfo;
use arminius_lib_component::{
	Component, ServerState,
	error::{
		BadJson, InputJsonError, InternalServerError, MatrixApiError, ResultExt as _,
		create_custom_matrix_error,
	},
	ruma_requests::ArminiusResponse,
};
use arminius_lib_db::{Database as _, TransactedDb};
use arminius_lib_db_devices::{Device, DeviceQueries as _};
use arminius_lib_db_keys::UserKeysQueries as _;
use arminius_lib_db_signatures::LocalSignatureQueries as _;
use arminius_lib_macros::{FromDbError, FromNatsError};
use arminius_lib_model::user_keys::DbKeyType;
use arminius_lib_user_keys::{
	signatures::{SignatureVerificationError, verify_signatures},
	traits::SigningKey as _,
};
use axum::{Router, extract::State, http::StatusCode, routing::post};
use ruma::{
	UserId,
	api::{
		client::keys::upload_signing_keys,
		error::{Error as MatrixError, ErrorKind},
	},
	encryption::{CrossSigningKey, KeyUsage},
	serde::{Base64, base64::Standard},
};

use crate::client_request::AuthenticatedClientRequest;

/// Thrown when signature verification fails.
#[derive(Debug, thiserror::Error)]
#[error("Invalid signature: {0}")]
pub struct SignatureError(String);

// Manually implemented, because `ErrorKind` does not agree with custom error
// codes.
impl MatrixApiError for SignatureError {
	fn create_matrix_error(&self) -> MatrixError {
		create_custom_matrix_error(
			StatusCode::BAD_REQUEST,
			"M_INVALID_SIGNATURE",
			&self.to_string(),
		)
	}
}

/// Converts a [`SignatureVerificationError`] into a [`CrossSigningKeysError`]
/// so that it can be returned as Matrix error.
impl From<SignatureVerificationError> for CrossSigningKeysError {
	fn from(signature_error: SignatureVerificationError) -> Self {
		match signature_error {
			SignatureVerificationError::BadJson(bad_json) => {
				Self::InputJsonError(InputJsonError::BadJson(bad_json))
			}
			other_error => Self::SignatureVerification(SignatureError(other_error.to_string())),
		}
	}
}

#[allow(
	missing_docs,
	clippy::missing_docs_in_private_items,
	reason = "TODO(#2003): This exception predates us enabling `clippy::allow_attributes_without_reason`, so we don't know why it was enabled"
)]
#[derive(Debug, thiserror::Error, MatrixApiError, FromDbError, FromNatsError)]
enum CrossSigningKeysError {
	#[error(transparent)]
	InternalServerError(#[from] InternalServerError),

	#[error(transparent)]
	InputJsonError(#[from] InputJsonError),

	#[error(transparent)]
	SignatureVerification(#[from] SignatureError),

	/// The public key of one of the keys is the same as one of the user's
	/// device IDs.
	#[error("Key ID in use")]
	#[matrix_api_error(status_code = StatusCode::FORBIDDEN, error_kind = ErrorKind::Forbidden)]
	SameIdAsDevice,

	/// The requested action was impossible because we do not know any master
	/// key for that user.
	#[error("Missing Master key")]
	#[matrix_api_error(status_code = StatusCode::BAD_REQUEST, error_kind = ErrorKind::MissingParam)]
	MissingMasterKey,
}

/// Performs various checks on a [`CrossSigningKey`].
///
/// # Errors
///
/// This function returns a [`InputJsonError`] error for any of the
/// following cases:
/// - The key is malformed in some way (e.g missing a field, does not have exactly one entry in its
///   `keys` field, etc).
/// - The cross-signing key's id is the same as one of the user's `device_ids` (See <https://spec.matrix.org/v1.16/client-server-api/#key-and-signature-security>).
/// - The user ID of the key does not match that of the authenticated user making the request.
fn check_cross_signing_key(
	expected_user_id: &UserId,
	expected_usage: &KeyUsage,
	user_devices: &[Device],
	key: &CrossSigningKey,
) -> Result<(), CrossSigningKeysError> {
	if key.user_id != expected_user_id {
		return Err(InputJsonError::BadJson(BadJson(
			"Cross-signing key's `user_id` mismatch".to_owned(),
		))
		.into());
	}

	if !key.usage.contains(expected_usage) {
		return Err(InputJsonError::BadJson(BadJson(format!(
			"Missing {expected_usage} in cross-signing key's `usage` field"
		)))
		.into());
	}

	// Make sure the key's ID isn't the same as one of the user's devices ID
	let key_id = key.key_id().map_err(InputJsonError::BadJson)?;
	if user_devices.iter().any(|device| device.device_id.as_str() == key_id.as_str()) {
		return Err(CrossSigningKeysError::SameIdAsDevice);
	}

	Ok(())
}

/// Handles a new Master Key upload by:
/// - Checking its correctness using [`check_cross_signing_key`]
/// - Verify its optional device key signature
/// - Store it in the database
async fn handle_new_master_key(
	transaction: &mut TransactedDb<'_>,
	session: &SessionInfo,
	user_devices: &[Device],
	key: &mut CrossSigningKey,
) -> Result<(), CrossSigningKeysError> {
	check_cross_signing_key(&session.user_id, &KeyUsage::Master, user_devices, key)?;

	// If the master key is not signed, just store it in the database now and
	// return early
	if key.signatures.is_empty() {
		transaction
			.upsert_cross_signing_key(&session.user_id, DbKeyType::Master, key)
			.await
			.unrecoverable_error("Inserting cross-signing key")?;

		return Ok(());
	}

	// If we have device keys, try checking the master key's signature with it
	if let Some(device_key) = transaction
		.fetch_device_keys_for_users(&BTreeMap::from([(
			session.user_id.clone(),
			vec![session.device_id.clone()],
		)]))
		.await?
		.get(&session.user_id)
		.and_then(|user_keys| user_keys.get(&session.device_id))
	{
		verify_signatures(
			vec![
				&device_key
					.key
					.keymap()
					.unrecoverable_error("Failed to get keymap of stored device keys")?,
				&key.keymap().map_err(InputJsonError::BadJson)?,
			],
			key,
			None,
		)?;
	}

	let signatures = key.signatures.remove(&session.user_id);

	let master_key_id = key.key_id().map_err(InputJsonError::BadJson)?;

	let master_key_nid =
		transaction.upsert_cross_signing_key(&session.user_id, DbKeyType::Master, key).await?;

	if let Some(signatures) = signatures {
		for (signing_key_id, signature) in signatures {
			transaction
				.upsert_local_signature(
					&session.user_id,
					if signing_key_id == master_key_id {
						DbKeyType::Master
					} else {
						DbKeyType::Device
					},
					&signing_key_id,
					master_key_nid,
					Base64::<Standard>::parse(signature)
						.unrecoverable_error("Failed to deserialize base64")?
						.as_bytes(),
				)
				.await
				.unrecoverable_error("Failed to insert signature")?;
		}
	}

	Ok(())
}

/// Handler for `POST /_matrix/client/v3/keys/device_signing/upload` (See
/// <https://spec.matrix.org/v1.15/client-server-api/#post_matrixclientv3keysdevice_signingupload>).
#[expect(
	clippy::too_many_lines,
	reason = "TODO(#2003): This exception predates us enabling `clippy::allow_attributes_without_reason`, so we don't know why it was enabled"
)]
async fn upload_signing_keys_handler(
	mut state: State<ServerState>,
	AuthenticatedClientRequest(claims, request): AuthenticatedClientRequest<
		upload_signing_keys::v3::Request,
	>,
) -> Result<ArminiusResponse<upload_signing_keys::v3::Response>, CrossSigningKeysError> {
	let mut transaction = state.database.begin_transaction().await?;

	// Uploaded cross-signing keys appear in the `device_lists.changed` field of
	// `/sync` responses of other users, so we need to notify the sync endpoint
	// about them after committing.
	let uploaded_cross_signing_keys = request.master_key.is_some()
		|| request.self_signing_key.is_some()
		|| request.user_signing_key.is_some();

	// Get the user devices to check their IDs against the cross-signing keys
	// ones
	let user_devices = transaction.fetch_devices_for_user(&claims.user_id).await?;

	let master_key = match request.master_key {
		Some(new_master_key) => {
			let mut new_master_key = new_master_key.deserialize().map_err(InputJsonError::from)?;

			handle_new_master_key(&mut transaction, &claims, &user_devices, &mut new_master_key)
				.await?;

			new_master_key
		}
		None => transaction
			.fetch_single_cross_signing_key_for_user(&claims.user_id, DbKeyType::Master)
			.await?
			.ok_or(CrossSigningKeysError::MissingMasterKey)?,
	};

	// The master key **MUST** have signed the other cross-signing keys.
	let master_key_id =
		master_key.key_id().unrecoverable_error("Failed to get key ID from master key")?;
	let keymap = master_key.keymap().unrecoverable_error("Failed to get keymap")?;
	let required_signers = BTreeMap::from([(claims.user_id.clone(), vec![master_key_id.clone()])]);

	if let Some(self_signing_key) = request.self_signing_key {
		let mut self_signing_key = self_signing_key.deserialize().map_err(InputJsonError::from)?;

		// Make sure the self-signing key has a valid signature from the master
		// key.
		check_cross_signing_key(
			&claims.user_id,
			&KeyUsage::SelfSigning,
			&user_devices,
			&self_signing_key,
		)?;

		verify_signatures(vec![&keymap], &self_signing_key, Some(&required_signers))?;

		let signatures = self_signing_key
			.signatures
			.remove(&claims.user_id)
			.unrecoverable_error("Self-signing keys MUST be signed at least by themselves")?;

		let self_signing_key_id = self_signing_key.key_id().map_err(InputJsonError::BadJson)?;
		let self_signing_key_nid = transaction
			.upsert_cross_signing_key(&claims.user_id, DbKeyType::SelfSigning, &self_signing_key)
			.await?;

		for (signing_key_id, signature) in signatures {
			// The signature is either from the key itself or from the Master
			// key
			let signing_key_type = match &signing_key_id {
				key_id if *key_id == master_key_id => DbKeyType::Master,
				key_id if key_id == &self_signing_key_id => DbKeyType::SelfSigning,
				other_key_id => {
					tracing::warn!("Ignoring signature on user-signing key from {other_key_id}");
					continue;
				}
			};

			transaction
				.upsert_local_signature(
					&claims.user_id,
					signing_key_type,
					&signing_key_id,
					self_signing_key_nid,
					Base64::<Standard>::parse(signature)
						.unrecoverable_error("Failed to parse base64")?
						.as_bytes(),
				)
				.await?;
		}
	}

	if let Some(user_signing_key) = request.user_signing_key {
		let mut user_signing_key = user_signing_key.deserialize().map_err(InputJsonError::from)?;

		// Make sure the user-signing key has a valid signature from the master
		// key.
		check_cross_signing_key(
			&claims.user_id,
			&KeyUsage::UserSigning,
			&user_devices,
			&user_signing_key,
		)?;

		verify_signatures(vec![&keymap], &user_signing_key, Some(&required_signers))?;

		let signatures = user_signing_key
			.signatures
			.remove(&claims.user_id)
			.unrecoverable_error("User signing keys MUST be signed at least by the Master key")?;

		let user_signing_key_id = user_signing_key.key_id().map_err(InputJsonError::BadJson)?;
		let user_signing_key_nid = transaction
			.upsert_cross_signing_key(&claims.user_id, DbKeyType::UserSigning, &user_signing_key)
			.await?;

		for (signing_key_id, signature) in signatures {
			// The signature is either from the key itself or from the Master
			// key
			let signing_key_type = match &signing_key_id {
				key_id if *key_id == master_key_id => DbKeyType::Master,
				key_id if key_id == &user_signing_key_id => DbKeyType::UserSigning,
				other_key_id => {
					tracing::warn!("Ignoring signature on user-signing key from {other_key_id}");
					continue;
				}
			};

			transaction
				.upsert_local_signature(
					&claims.user_id,
					signing_key_type,
					&signing_key_id,
					user_signing_key_nid,
					Base64::<Standard>::parse(signature)
						.unrecoverable_error("Failed to parse base64")?
						.as_bytes(),
				)
				.await?;
		}
	}

	transaction.commit().await?;

	if uploaded_cross_signing_keys {
		// Notify possibly listening clients that a user updated their
		// cross-signing keys
		state.nats_connection.notify_new_sync_data().await?;
	}

	Ok(upload_signing_keys::v3::Response::new().into())
}

/// Component implementing endpoints for user keys
#[derive(Debug)]
pub struct CrossSigningKeysComponent;

impl Component for CrossSigningKeysComponent {
	fn router() -> Router<ServerState> {
		Router::new().route(
			"/_matrix/client/v3/keys/device_signing/upload",
			post(upload_signing_keys_handler),
		)
	}
}