Struct matrix_sdk::encryption::Encryption

pub struct Encryption { /* private fields */ }

Available on crate feature e2e-encryption only.

A high-level API to manage the client’s encryption.

To get this, use Client::encryption().

Implementations

impl Encryption

pub async fn ed25519_key(&self) -> Option<String>

Get the public ed25519 key of our own device. This is usually what is called the fingerprint of the device.

pub async fn cross_signing_status(&self) -> Option<CrossSigningStatus>

Get the status of the private cross signing keys.

This can be used to check which private cross signing keys we have stored locally.

pub async fn tracked_users(&self) -> HashSet<OwnedUserId>

Get all the tracked users we know about

Tracked users are users for which we keep the device list of E2EE capable devices up to date.

pub async fn get_verification(
    &self,
    user_id: &UserId,
    flow_id: &str
) -> Option<Verification>

Get a verification object with the given flow id.

pub async fn get_verification_request(
    &self,
    user_id: &UserId,
    flow_id: impl AsRef<str>
) -> Option<VerificationRequest>

Get a VerificationRequest object for the given user with the given flow id.

pub async fn get_device(
    &self,
    user_id: &UserId,
    device_id: &DeviceId
) -> Result<Option<Device>, CryptoStoreError>

Get a specific device of a user.

Arguments

• user_id - The unique id of the user that the device belongs to.

• device_id - The unique id of the device.

Returns a Device if one is found and the crypto store didn’t throw an error.

This will always return None if the client hasn’t been logged in.

Example

if let Some(device) = client
    .encryption()
    .get_device(alice, device_id!("DEVICEID"))
    .await? {
        println!("{:?}", device.verified());

        if !device.verified() {
            let verification = device.request_verification().await?;
        }
}

pub async fn get_user_devices(
    &self,
    user_id: &UserId
) -> Result<UserDevices, CryptoStoreError>

Get a map holding all the devices of an user.

This will always return an empty map if the client hasn’t been logged in.

Arguments

• user_id - The unique id of the user that the devices belong to.

Example

let devices = client.encryption().get_user_devices(alice).await?;

for device in devices.devices() {
    println!("{:?}", device);
}

pub async fn get_user_identity(
    &self,
    user_id: &UserId
) -> Result<Option<UserIdentity>, CryptoStoreError>

Get a E2EE identity of an user.

Arguments

• user_id - The unique id of the user that the identity belongs to.

Returns a UserIdentity if one is found and the crypto store didn’t throw an error.

This will always return None if the client hasn’t been logged in.

Example

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

if let Some(user) = user {
    println!("{:?}", user.verified());

    let verification = user.request_verification().await?;
}

pub async fn bootstrap_cross_signing(
    &self,
    auth_data: Option<AuthData<'_>>
) -> Result<()>

Create and upload a new cross signing identity.

Arguments

• auth_data - This request requires user interactive auth, the first request needs to set this to None and will always fail with an UiaaResponse. The response will contain information for the interactive auth and the same request needs to be made but this time with some auth_data provided.

Examples

if let Err(e) = client.encryption().bootstrap_cross_signing(None).await {
    if let Some(response) = e.uiaa_response() {
        let auth_data = uiaa::AuthData::Password(assign!(
            uiaa::Password::new(
                uiaa::UserIdentifier::UserIdOrLocalpart("example"),
                "wordpass",
            ), {
                session: response.session.as_deref(),
            }
        ));

        client
            .encryption()
            .bootstrap_cross_signing(Some(auth_data))
            .await
            .expect("Couldn't bootstrap cross signing")
    } else {
        panic!("Error durign cross signing bootstrap {:#?}", e);
    }
}

pub async fn export_keys(
    &self,
    path: PathBuf,
    passphrase: &str,
    predicate: impl FnMut(&InboundGroupSession) -> bool
) -> Result<()>

Available on non-WebAssembly only.

Export E2EE keys that match the given predicate encrypting them with the given passphrase.

Arguments

• path - The file path where the exported key file will be saved.

• passphrase - The passphrase that will be used to encrypt the exported room keys.

• predicate - A closure that will be called for every known InboundGroupSession, which represents a room key. If the closure returns true the InboundGroupSessoin will be included in the export, if the closure returns false it will not be included.

Panics

This method will panic if it isn’t run on a Tokio runtime.

This method will panic if it can’t get enough randomness from the OS to encrypt the exported keys securely.

Examples

let path = PathBuf::from("/home/example/e2e-keys.txt");
// Export all room keys.
client
    .encryption()
    .export_keys(path, "secret-passphrase", |_| true)
    .await?;

// Export only the room keys for a certain room.
let path = PathBuf::from("/home/example/e2e-room-keys.txt");
let room_id = room_id!("!test:localhost");

client
    .encryption()
    .export_keys(path, "secret-passphrase", |s| s.room_id() == room_id)
    .await?;

pub async fn import_keys(
    &self,
    path: PathBuf,
    passphrase: &str
) -> Result<RoomKeyImportResult, RoomKeyImportError>

Available on non-WebAssembly only.

Import E2EE keys from the given file path.

Arguments

• path - The file path where the exported key file will can be found.

• passphrase - The passphrase that should be used to decrypt the exported room keys.

Returns a tuple of numbers that represent the number of sessions that were imported and the total number of sessions that were found in the key export.

Panics

This method will panic if it isn’t run on a Tokio runtime.

let path = PathBuf::from("/home/example/e2e-keys.txt");
let result = client.encryption().import_keys(path, "secret-passphrase").await?;

println!(
    "Imported {} room keys out of {}",
    result.imported_count, result.total_count
);

Trait Implementations

impl Clone for Encryption

fn clone(&self) -> Encryption

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Encryption

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

Formats the value using the given formatter.