From c79481c6fa5be1396f48305e9f853584a4e93100 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Tue, 2 Nov 2021 10:43:27 +0100 Subject: [PATCH] docs(sdk): Clarify what it means for a device to be verified --- .../src/encryption/identities/devices.rs | 30 +++++++++++-------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/crates/matrix-sdk/src/encryption/identities/devices.rs b/crates/matrix-sdk/src/encryption/identities/devices.rs index df734e59a..4376b6778 100644 --- a/crates/matrix-sdk/src/encryption/identities/devices.rs +++ b/crates/matrix-sdk/src/encryption/identities/devices.rs @@ -278,16 +278,20 @@ impl Device { /// [`Device::request_verification()`] method. /// /// A [`Device`] can also be manually signed using the [`Device::verify()`] - /// method, this works only for devices belonging to our own user. Do note - /// that the device that is being manually signed will not trust our own - /// user identity like it would if we interactively verify the device. Such - /// a device can mark our own user as verified using the + /// method, this works only for devices belonging to our own user. + /// + /// Do note that the device that is being manually signed will not trust our + /// own user identity like it would if we interactively verify the device. + /// Such a device can mark our own user as verified using the /// [`UserIdentity::verify()`] method. /// /// ### Verification of devices belonging to our own user. /// - /// If the device belongs to our own user, the device needs to be signed by - /// our self-signing key and our own user identity needs to be verified. + /// If the device belongs to our own user, the device will be considered to + /// be verified if: + /// + /// * The device has been signed by our self-signing key + /// * Our own user identity is considered to be [verified] /// /// In other words we need to find a valid signature chain from our user /// identity to the device: @@ -302,14 +306,13 @@ impl Device { /// /// ### Verification of devices belonging to other users. /// - /// If the device belongs to some other user, the device needs to be signed - /// by the user's user-signing key and the user identity, the user's - /// identity needs to be signed by our own identity, and our own identity - /// needs to be verified. + /// If the device belongs to some other user it will be considered to be + /// verified if: /// - /// In other words we need to find a valid signature chain from our user - /// identity to the identity of the other user and finally to the user's - /// device. + /// * The device has been signed by the user's self-signing key + /// * The user's master-signing key has been signed by our own user-signing + /// key, i.e. our own identity trusts the other users identity. + /// * Our own user identity is considered to be [verified] /// /// ```text /// ┌─────────────────────────────────────┐ @@ -365,6 +368,7 @@ impl Device { /// /// [`UserIdentity::verify()`]: /// crate::encryption::identities::UserIdentity::verify + /// [verified]: crate::encryption::identities::UserIdentity::verified pub fn verified(&self) -> bool { self.inner.verified() }