Struct matrix_sdk::encryption::identities::UserIdentity

source ·
pub struct UserIdentity { /* private fields */ }
Expand description

A struct representing a E2EE capable identity of a user.

The identity is backed by public cross signing keys that users upload. If our own user doesn’t yet have such an identity, a new one can be created and uploaded to the server using Encryption::bootstrap_cross_signing(). The user identity can be also reset using the same method.

The user identity consists of three separate Ed25519 keypairs:

          ┌──────────────────────────────────────────────────────┐
          │                    User Identity                     │
          ├────────────────┬──────────────────┬──────────────────┤
          │   Master Key   │ Self-signing Key │ User-signing key │
          └────────────────┴──────────────────┴──────────────────┘

The identity consists of a Master key and two sub-keys, the Self-signing key and the User-signing key.

Each key has a separate role:

  • Master key, signs only the sub-keys, can be used as a fingerprint of the identity.
  • Self-signing key, signs devices belonging to the user that owns this identity.
  • User-signing key, signs Master keys belonging to other users.

The User-signing key and its signatures of other user’s Master keys are hidden from us by the homeserver. This is done to preserve privacy and not let us know whom the user verified.

Implementations§

source§

impl UserIdentity

source

pub fn user_id(&self) -> &UserId

The ID of the user this identity belongs to.

§Examples
let user = client.encryption().get_user_identity(alice).await?;

if let Some(user) = user {
    println!("This user identity belongs to {}", user.user_id());
}
source

pub async fn request_verification( &self, ) -> Result<VerificationRequest, RequestVerificationError>

Request an interactive verification with this UserIdentity.

Returns a VerificationRequest object that can be used to control the verification flow.

This will send out a m.key.verification.request event. Who such an event will be sent to depends on if we’re verifying our own identity or someone else’s:

  • Our own identity - All our E2EE capable devices will receive the event over to-device messaging.
  • Someone else’s identity - The event will be sent to a DM room we share with the user, if we don’t share a DM with the user, one will be created.

The default methods that are supported are:

  • m.sas.v1 - Short auth string, or emoji based verification
  • m.qr_code.show.v1 - QR code based verification

request_verification_with_methods() method can be used to override this. The m.qr_code.show.v1 method is only available if the qrcode feature is enabled, which it is by default.

Check out the verification module for more info on how to handle interactive verifications.

§Examples
let user = client.encryption().get_user_identity(alice).await?;

if let Some(user) = user {
    let verification = user.request_verification().await?;
}
source

pub async fn request_verification_with_methods( &self, methods: Vec<VerificationMethod>, ) -> Result<VerificationRequest, RequestVerificationError>

Request an interactive verification with this UserIdentity using the selected methods.

Returns a VerificationRequest object that can be used to control the verification flow.

This methods behaves the same way as request_verification(), but the advertised verification methods can be manually selected.

Check out the verification module for more info on how to handle interactive verifications.

§Arguments
  • methods - The verification methods that we want to support. Must be non-empty.
§Panics

This method will panic if methods is empty.

§Examples
let user = client.encryption().get_user_identity(alice).await?;

// We don't want to support showing a QR code, we only support SAS
// verification
let methods = vec![VerificationMethod::SasV1];

if let Some(user) = user {
    let verification =
        user.request_verification_with_methods(methods).await?;
}
source

pub async fn verify(&self) -> Result<(), ManualVerifyError>

Manually verify this UserIdentity.

This method will do different things depending on if the user identity belongs to us, or if the user identity belongs to someone else. Users that chose to manually verify a user identity should make sure that the Master key does match to to the Ed25519 they expect.

The Master key can be inspected using the UserIdentity::master_key() method.

§Manually verifying other users

This method will attempt to sign the user identity using our private parts of the cross signing keys. The method will attempt to sign the Master key of the user using our own User-signing key. This will of course fail if the private part of the User-signing key isn’t available.

The availability of the User-signing key can be checked using the Encryption::cross_signing_status() method.

§Manually verifying our own user

On the other hand, if the user identity belongs to us, it will be marked as verified using a local flag, our own device will also sign the Master key. Manually verifying our own user identity can’t fail.

§Problems of manual verification

Manual verification may be more convenient to use, i.e. both users need to be online and available to interactively verify each other. Despite the convenience, interactive verifications should be generally preferred. Manually verifying a user won’t notify the other user, the one being verified, that they should also verify us. This means that user A will consider user B to be verified, but not the other way around.

§Examples
let user = client.encryption().get_user_identity(alice).await?;

if let Some(user) = user {
    user.verify().await?;
}
source

pub fn is_verified(&self) -> bool

Is the user identity considered to be verified.

A user identity is considered to be verified if:

  • It has been signed by our User-signing key, if the identity belongs to another user
  • If it has been locally marked as verified, if the user identity belongs to us.

If the identity belongs to another user, our own user identity needs to be verified as well for the identity to be considered to be verified.

§Examples
let user = client.encryption().get_user_identity(alice).await?;

if let Some(user) = user {
    if user.is_verified() {
        println!("User {} is verified", user.user_id());
    } else {
        println!("User {} is not verified", user.user_id());
    }
}
source

pub async fn withdraw_verification(&self) -> Result<(), CryptoStoreError>

Remove the requirement for this identity to be verified.

If an identity was previously verified and is not any more it will be reported to the user. In order to remove this notice users have to verify again or to withdraw the verification requirement.

source

pub async fn pin(&self) -> Result<(), CryptoStoreError>

Remember this identity, ensuring it does not result in a pin violation.

When we first see a user, we assume their cryptographic identity has not been tampered with by the homeserver or another entity with man-in-the-middle capabilities. We remember this identity and call this action “pinning”.

If the identity presented for the user changes later on, the newly presented identity is considered to be in “pin violation”. This method explicitly accepts the new identity, allowing it to replace the previously pinned one and bringing it out of pin violation.

UIs should display a warning to the user when encountering an identity which is not verified and is in pin violation.

source

pub fn master_key(&self) -> &MasterPubkey

Get the public part of the Master key of this user identity.

The public part of the Master key is usually used to uniquely identify the identity.

§Examples
let user = client.encryption().get_user_identity(alice).await?;

if let Some(user) = user {
    // Let's verify the user after we confirm that the master key
    // matches what we expect, for this we fetch the first public key we
    // can find, there's currently only a single key allowed so this is
    // fine.
    if user.master_key().get_first_key().map(|k| k.to_base64())
        == Some("MyMasterKey".to_string())
    {
        println!(
            "Master keys match for user {}, marking the user as verified",
            user.user_id(),
        );
        user.verify().await?;
    } else {
        println!("Master keys don't match for user {}", user.user_id());
    }
}

Trait Implementations§

source§

impl Clone for UserIdentity

source§

fn clone(&self) -> UserIdentity

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for UserIdentity

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, W> HasTypeWitness<W> for T
where W: MakeTypeWitness<Arg = T>, T: ?Sized,

source§

const WITNESS: W = W::MAKE

A constant of the type witness
source§

impl<T> Identity for T
where T: ?Sized,

§

type Type = T

The same type as Self, used to emulate type equality bounds (T == U) with associated type equality constraints (T: Identity<Type = U>).
source§

const TYPE_EQ: TypeEq<T, <T as Identity>::Type> = TypeEq::NEW

Proof that Self is the same type as Self::Type, provides methods for casting between Self and Self::Type.
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> Any for T
where T: Any,

source§

impl<T> AsyncTraitDeps for T

source§

impl<T> CloneAny for T
where T: Any + Clone,

source§

impl<T> CloneAnySend for T
where T: Any + Send + Clone,

source§

impl<T> CloneAnySendSync for T
where T: Any + Send + Sync + Clone,

source§

impl<T> CloneAnySync for T
where T: Any + Sync + Clone,

source§

impl<T> SendOutsideWasm for T
where T: Send,

source§

impl<T> SyncOutsideWasm for T
where T: Sync,