Struct Recovery

pub struct Recovery { /* private fields */ }

Available on crate feature e2e-encryption only.

The recovery manager for the Client.

Implementations

impl Recovery

pub fn state(&self) -> RecoveryState

Get the current RecoveryState for this Client.

pub fn state_stream(&self) -> impl Stream<Item = RecoveryState>

Get a stream of updates to the RecoveryState.

This method will send out the current state as the first update.

Examples

use futures_util::StreamExt;

let recovery = client.encryption().recovery();

let mut state_stream = recovery.state_stream();

while let Some(update) = state_stream.next().await {
    match update {
        RecoveryState::Enabled => {
            println!("Recovery has been enabled");
        }
        _ => (),
    }
}

pub fn enable(&self) -> Enable<'_>

Enable secret storage and backups.

This method will create a new secret storage key and a new backup if one doesn’t already exist. It will then upload all the locally cached secrets, including the backup recovery key, to the new secret store.

This method will throw an error if a backup already exists on the homeserver but this Client isn’t connected to the existing backup.

Examples

use futures_util::StreamExt;

let recovery = client.encryption().recovery();

let enable = recovery
    .enable()
    .wait_for_backups_to_upload()
    .with_passphrase("my passphrase");

let mut progress_stream = enable.subscribe_to_progress();

tokio::spawn(async move {
    while let Some(update) = progress_stream.next().await {
        let Ok(update) = update else {
            panic!("Update to the enable progress lagged")
        };

        match update {
            EnableProgress::CreatingBackup => {
                println!("Creating a new backup");
            }
            EnableProgress::CreatingRecoveryKey => {
                println!("Creating a new recovery key");
            }
            EnableProgress::Done { .. } => {
                println!("Recovery has been enabled");
                break;
            }
            _ => (),
        }
    }
});

let recovery_key = enable.await?;

pub async fn enable_backup(&self) -> Result<()>

Create a new backup if one does not exist yet.

This method will throw an error if a backup already exists on the homeserver but this Client isn’t connected to the existing backup.

Examples

let recovery = client.encryption().recovery();

recovery.enable_backup().await?;

assert_eq!(client.encryption().backups().state(), BackupState::Enabled);

pub async fn disable(&self) -> Result<()>

Disable recovery completely.

This method will do the following steps:

1. Disable the uploading of room keys to a currently active backup.
2. Delete the currently active backup.
3. Set the m.secret_storage.default_key global account data event to an empty JSON content.
4. Set a global account data event so clients won’t attempt to automatically re-enable a backup.

Examples

let recovery = client.encryption().recovery();

recovery.disable().await?;

assert_eq!(recovery.state(), RecoveryState::Disabled);

pub fn reset_key(&self) -> Reset<'_>

Reset the recovery key.

This will rotate the secret storage key and re-upload all the secrets to the SecretStore.

Examples

let recovery = client.encryption().recovery();

let new_recovery_key =
    recovery.reset_key().with_passphrase("my passphrase").await;

pub fn recover_and_reset<'a>(&'a self, old_key: &'a str) -> RecoverAndReset<'a>

Reset the recovery key but first import all the secrets from secret storage.

Examples

let recovery = client.encryption().recovery();

let new_recovery_key = recovery
    .recover_and_reset("my old passphrase or key")
    .with_passphrase("my new passphrase")
    .await?;

pub async fn reset_identity(&self) -> Result<Option<IdentityResetHandle>>

Completely reset the current user’s crypto identity. This method will go through the following steps:

1. Disable backing up room keys and delete the active backup
2. Disable recovery and delete secret storage
3. Go through the cross-signing key reset flow
4. Finally, re-enable key backups (only if they were already enabled)

Disclaimer: failures in this flow will potentially leave the user in an inconsistent state but they’re expected to just run the reset flow again as presumably the reason they started it to begin with was that they no longer had access to any of their data.

Examples

    encryption::recovery, encryption::CrossSigningResetAuthType, ruma::api::client::uiaa,
    Client,
  };
let encryption = client.encryption();
       
if let Some(handle) = encryption.recovery().reset_identity().await? {
    match handle.auth_type() {
        CrossSigningResetAuthType::Uiaa(uiaa) => {
            let password = "1234".to_owned();
            let mut password = uiaa::Password::new(user_id, password);
            password.session = uiaa.session;

            handle.reset(Some(uiaa::AuthData::Password(password))).await?;
        }
        CrossSigningResetAuthType::Oidc(o) => {
            println!(
                "To reset your end-to-end encryption cross-signing identity, \
                you first need to approve it at {}",
                o.approval_url
            );
            handle.reset(None).await?;
        }
    }
}

pub async fn recover(&self, recovery_key: &str) -> Result<()>

Recover all the secrets from the homeserver.

This method is a convenience method around the SecretStore::import_secrets() method, please read the documentation of this method for more information about what happens if you call this method.

In short, this method will turn a newly created Client into a fully end-to-end encryption enabled client.

Examples

let recovery = client.encryption().recovery();

recovery.recover("my recovery key or passphrase").await;

assert_eq!(recovery.state(), RecoveryState::Enabled);

pub async fn are_we_the_last_man_standing(&self) -> Result<bool>

Is this device the last device the user has?

This method is useful to check if we should recommend to the user that they should enable recovery, typically done before logging out.

If the user does not enable recovery before logging out of their last device, they will not be able to decrypt historic messages once they create a new device.

Trait Implementations

impl Debug for Recovery

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

Formats the value using the given formatter.