Struct matrix_sdk::encryption::identities::UserIdentity
source · [−]pub struct UserIdentity { /* private fields */ }
e2e-encryption
only.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
sourceimpl 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().as_str());
}
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 veryfing 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 verified(&self) -> bool
pub fn 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.verified() {
println!("User {} is verified", user.user_id().as_str());
} else {
println!("User {} is not verified", user.user_id().as_str());
}
}
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().as_str(),
);
user.verify().await?;
} else {
println!("Master keys don't match for user {}", user.user_id().as_str());
}
}
Trait Implementations
sourceimpl Clone for UserIdentity
impl Clone for UserIdentity
sourcefn clone(&self) -> UserIdentity
fn clone(&self) -> UserIdentity
Returns a copy of the value. Read more
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
Auto Trait Implementations
impl !RefUnwindSafe for UserIdentity
impl Send for UserIdentity
impl Sync for UserIdentity
impl Unpin for UserIdentity
impl !UnwindSafe for UserIdentity
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<T> Pointable for T
impl<T> Pointable for T
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
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
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more