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
impl UserIdentity
sourcepub fn user_id(&self) -> &UserId
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());
}
sourcepub async fn request_verification(
&self,
) -> Result<VerificationRequest, RequestVerificationError>
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 verificationm.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?;
}
sourcepub async fn request_verification_with_methods(
&self,
methods: Vec<VerificationMethod>,
) -> Result<VerificationRequest, RequestVerificationError>
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?;
}
sourcepub async fn verify(&self) -> Result<(), ManualVerifyError>
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?;
}
sourcepub fn is_verified(&self) -> bool
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());
}
}
sourcepub async fn withdraw_verification(&self) -> Result<(), CryptoStoreError>
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.
sourcepub async fn pin(&self) -> Result<(), CryptoStoreError>
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.
sourcepub fn master_key(&self) -> &MasterPubkey
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
impl Clone for UserIdentity
source§fn clone(&self) -> UserIdentity
fn clone(&self) -> UserIdentity
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreAuto Trait Implementations§
impl Freeze for UserIdentity
impl !RefUnwindSafe for UserIdentity
impl Send for UserIdentity
impl Sync for UserIdentity
impl Unpin for UserIdentity
impl !UnwindSafe for UserIdentity
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<T, W> HasTypeWitness<W> for Twhere
W: MakeTypeWitness<Arg = T>,
T: ?Sized,
impl<T, W> HasTypeWitness<W> for Twhere
W: MakeTypeWitness<Arg = T>,
T: ?Sized,
source§impl<T> Identity for Twhere
T: ?Sized,
impl<T> Identity for Twhere
T: ?Sized,
source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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