macltok

public

Star0

Fork 0

Watch0

106 commits 3 branches 0 tags 0 releases3.0 MiB

Commit `743123167e29`

tarball

atagen <boss@atagen.co>2026-10-26 05:03 UTC

7 files changed+193-29

encryption: set up recovery and hand back its key

create_key_backup alone leaves the backup key in this device's crypto store, so a wiped store or a fresh iOS Home Screen install can't restore anything. enable_recovery wraps Recovery::enable, which puts the cross-signing and backup keys into secret storage, and returns the key in the command reply only. Debug hides it. KeyBackupExists separates an account whose backup this device can't open from a rejected key.

Modified file: src/engine/commands.rs+67 additions−16 deletions@@ -16,11 +16,11 @@ use matrix_sdk::{
     },
     send_queue::{LocalEchoContent, SendHandle},
 };
-use tokio::sync::mpsc;
+use tokio::sync::{mpsc, watch};
 
 use crate::{
-    EncryptionCommand, Error, ErrorKind, InteractiveAuth, InteractiveAuthChallenge,
-    NotificationCommand, RoomNotificationMode, TimelineId,
+    CommandOutput, EncryptionCommand, Error, ErrorKind, InteractiveAuth, InteractiveAuthChallenge,
+    NotificationCommand, RecoveryKey, RoomNotificationMode, TimelineId,
     encryption::VerificationController,
     transport::{EventSender, Responder},
 };
@@ -55,14 +55,15 @@ pub(super) async fn run_encryption(
     events: EventSender,
     mut jobs: mpsc::Receiver<Job<EncryptionCommand>>,
     mut incoming: mpsc::UnboundedReceiver<VerificationRequest>,
+    enabling: watch::Sender<bool>,
 ) {
     let mut verification = VerificationController::default();
     loop {
         tokio::select! {
             job = jobs.recv() => {
                 let Some(Job { command, reply }) = job else { return };
-                let work = encryption(&client, &events, &mut verification, command);
-                reply.done(guarded("encryption command", work).await);
+                let work = encryption(&client, &events, &mut verification, &enabling, command);
+                reply.send(guarded("encryption command", work).await);
             }
             Some(request) = incoming.recv() => {
                 verification.adopt_incoming(events.clone(), request).await;
@@ -75,29 +76,58 @@ async fn encryption(
     client: &Client,
     events: &EventSender,
     verification: &mut VerificationController,
+    enabling: &watch::Sender<bool>,
     command: EncryptionCommand,
-) -> Result<(), Error> {
+) -> Result<CommandOutput, Error> {
     let encryption = client.encryption();
+    let recovery = encryption.recovery();
+    let key = |key: String| CommandOutput::RecoveryKey(RecoveryKey::new(key));
+    let done = CommandOutput::Done;
     match command {
-        EncryptionCommand::Recover(key) => encryption
-            .recovery()
+        EncryptionCommand::EnableRecovery { passphrase } => {
+            let _enabling = Enabling::start(enabling);
+            let enable = recovery.enable();
+            match passphrase.as_deref() {
+                Some(passphrase) => enable.with_passphrase(passphrase).await,
+                None => enable.await,
+            }
+            .map(key)
+            .map_err(|source| Error::from_recovery("enabling recovery failed", source))
+        }
+        EncryptionCommand::ResetRecoveryKey { passphrase } => {
+            let reset = recovery.reset_key();
+            match passphrase.as_deref() {
+                Some(passphrase) => reset.with_passphrase(passphrase).await,
+                None => reset.await,
+            }
+            .map(key)
+            .map_err(|source| Error::from_recovery("resetting the recovery key failed", source))
+        }
+        EncryptionCommand::DisableRecovery => recovery
+            .disable()
+            .await
+            .map(|()| done)
+            .map_err(|source| Error::from_recovery("disabling recovery failed", source)),
+        EncryptionCommand::Recover(key) => recovery
             .recover(&key)
             .await
+            .map(|()| done)
             .map_err(|source| Error::from_recovery("account recovery failed", source)),
-        EncryptionCommand::RecoverKeyBackup(key) => encryption
-            .recovery()
+        EncryptionCommand::RecoverKeyBackup(key) => recovery
             .recover_and_fix_backup(&key)
             .await
+            .map(|()| done)
             .map_err(|source| Error::from_recovery("recovering key backup failed", source)),
         EncryptionCommand::CreateKeyBackup => encryption
             .backups()
             .create()
             .await
+            .map(|()| done)
             .map_err(|source| Error::from_sdk("creating key backup failed", source)),
-        EncryptionCommand::EnableKeyBackup => encryption
-            .recovery()
+        EncryptionCommand::EnableKeyBackup => recovery
             .enable_backup()
             .await
+            .map(|()| done)
             .map_err(|source| Error::from_recovery("enabling key backup failed", source)),
         EncryptionCommand::DisableKeyBackup { delete_from_server } => {
             let backups = encryption.backups();
@@ -106,12 +136,33 @@ async fn encryption(
             } else {
                 backups.disable().await
             }
+            .map(|()| done)
             .map_err(|source| Error::from_sdk("disabling key backup failed", source))
         }
-        EncryptionCommand::StartVerification(target) => {
-            verification.start(client, events.clone(), target).await
-        }
-        EncryptionCommand::Verify(action) => verification.apply(events.clone(), action).await,
+        EncryptionCommand::StartVerification(target) => verification
+            .start(client, events.clone(), target)
+            .await
+            .map(|()| done),
+        EncryptionCommand::Verify(action) => verification
+            .apply(events.clone(), action)
+            .await
+            .map(|()| done),
+    }
+}
+
+/// a panicking enable must not leave the state saying it is still running
+struct Enabling<'a>(&'a watch::Sender<bool>);
+
+impl<'a> Enabling<'a> {
+    fn start(sender: &'a watch::Sender<bool>) -> Self {
+        sender.send_replace(true);
+        Self(sender)
+    }
+}
+
+impl Drop for Enabling<'_> {
+    fn drop(&mut self) {
+        self.0.send_replace(false);
     }
 }
 

Modified file: src/engine/mod.rs+7 additions−1 deletions@@ -600,6 +600,7 @@ impl Engine {
         let client = &self.client;
         let events = || self.port.event_sender();
         let (notices, notice_queue) = mpsc::unbounded_channel();
+        let (enabling_recovery, recovery_enabling) = watch::channel(false);
         let watchers: [(&'static str, EngineBoxFuture<'static, ()>); 15] = [
             (
                 "upload tracker",
@@ -658,7 +659,11 @@ impl Engine {
             ),
             (
                 "encryption state watcher",
-                Box::pin(watchers::encryption(client.clone(), events())),
+                Box::pin(watchers::encryption(
+                    client.clone(),
+                    events(),
+                    recovery_enabling,
+                )),
             ),
             (
                 "room list watcher",
@@ -702,6 +707,7 @@ impl Engine {
                     events(),
                     queues.encryption,
                     incoming_verifications,
+                    enabling_recovery,
                 )),
             ),
             (

Modified file: src/engine/watchers.rs+10 additions−2 deletions@@ -376,7 +376,11 @@ fn is_attachment_echo(content: &LocalEchoContent) -> bool {
     )
 }
 
-pub(super) async fn encryption(client: Client, events: EventSender) {
+pub(super) async fn encryption(
+    client: Client,
+    events: EventSender,
+    mut enabling: watch::Receiver<bool>,
+) {
     let Some(device_id) = client.device_id().map(ToOwned::to_owned) else {
         tracing::warn!("encryption watcher stopped because the client has no device id");
         return;
@@ -390,17 +394,21 @@ pub(super) async fn encryption(client: Client, events: EventSender) {
     let mut backup_state = backups.state();
     let mut verification_state = verification_stream.get();
     loop {
-        let state = encryption_state(
+        let mut state = encryption_state(
             device_id.clone(),
             recovery_state,
             verification_state,
             backup_state,
         );
+        if *enabling.borrow_and_update() {
+            state.recovery = crate::RecoveryState::Enabling;
+        }
         if events.send(Event::EncryptionChanged(state)).await.is_err() {
             return;
         }
         tokio::select! {
             Some(update) = recovery_stream.next() => recovery_state = update,
+            Ok(()) = enabling.changed() => {}
             Some(update) = verification_stream.next() => verification_state = update,
             Some(update) = backup_stream.next() => {
                 backup_state = update.unwrap_or_else(|_| backups.state());

Modified file: src/error.rs+4 additions−3 deletions@@ -66,6 +66,8 @@ pub enum ErrorKind {
     VerificationUnsupported,
     NoCrossSigningIdentity,
     RecoveryRejected,
+    /// the server already holds a key backup, which recovery has to open or replace first
+    KeyBackupExists,
     Network,
     /// the homeserver wants us to slow down. try again later
     RateLimited,
@@ -223,9 +225,8 @@ impl Error {
                 ErrorKind::RecoveryRejected
             }
             RecoveryError::SecretStorage(SecretStorageError::Storage(_)) => ErrorKind::Store,
-            RecoveryError::BackupExistsOnServer | RecoveryError::SecretStorage(_) => {
-                ErrorKind::RecoveryRejected
-            }
+            RecoveryError::BackupExistsOnServer => ErrorKind::KeyBackupExists,
+            RecoveryError::SecretStorage(_) => ErrorKind::RecoveryRejected,
         };
         Self::with_source(kind, message, source)
     }

Modified file: src/lib.rs+2 additions−2 deletions@@ -67,8 +67,8 @@ pub use model::{
     MessageEditContent, MessageKind, MessageMentions, NotificationCommand, OwnDevice, PackCommand,
     PackImage, PackImageInfo, PackUsage, Patch, PowerLevelChanges, Profile, PushNotification,
     PushNotificationEvent, PushNotificationRoom, PushNotificationSender, PushNotificationStatus,
-    Reaction, RecentHistoryState, RecoveryState, ReplyDetails, ReplyReference, Retain, RichText,
-    RoomCategory, RoomCommand, RoomHero, RoomListFilter, RoomMatcher, RoomMembership,
+    Reaction, RecentHistoryState, RecoveryKey, RecoveryState, ReplyDetails, ReplyReference, Retain,
+    RichText, RoomCategory, RoomCommand, RoomHero, RoomListFilter, RoomMatcher, RoomMembership,
     RoomNotificationMode, RoomNotificationSettings, RoomPowerLevels, RoomPreset, RoomSummary,
     RoomVisibility, SendState, Sender, SpaceChild, Termination, ThreadListCloseReason,
     ThreadListCommand, ThreadListEntry, ThreadSummary, ThreadUnread, TimelineCommand,

Modified file: src/model.rs+51 additions−1 deletions@@ -629,8 +629,19 @@ pub enum EncryptionCommand {
     Recover(String),
     CreateKeyBackup,
     EnableKeyBackup,
-    DisableKeyBackup { delete_from_server: bool },
+    DisableKeyBackup {
+        delete_from_server: bool,
+    },
     RecoverKeyBackup(String),
+    /// creates secret storage holding the cross-signing and backup keys, turns key backup on,
+    /// and answers with the recovery key. refused while a backup this device can't open exists
+    EnableRecovery {
+        passphrase: Option<String>,
+    },
+    ResetRecoveryKey {
+        passphrase: Option<String>,
+    },
+    DisableRecovery,
     StartVerification(VerificationTarget),
     Verify(VerificationAction),
 }
@@ -649,6 +660,15 @@ impl fmt::Debug for EncryptionCommand {
                 .debug_tuple("RecoverKeyBackup")
                 .field(&"...")
                 .finish(),
+            Self::EnableRecovery { passphrase } => formatter
+                .debug_struct("EnableRecovery")
+                .field("passphrase", &passphrase.as_ref().map(|_| "..."))
+                .finish(),
+            Self::ResetRecoveryKey { passphrase } => formatter
+                .debug_struct("ResetRecoveryKey")
+                .field("passphrase", &passphrase.as_ref().map(|_| "..."))
+                .finish(),
+            Self::DisableRecovery => formatter.write_str("DisableRecovery"),
             Self::StartVerification(target) => formatter
                 .debug_tuple("StartVerification")
                 .field(target)
@@ -701,6 +721,7 @@ pub enum CommandOutput {
     SearchSession(crate::SearchSession),
     SearchPage(crate::SearchPage),
     SearchCoverage(crate::SearchCoverage),
+    RecoveryKey(RecoveryKey),
 }
 
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -2296,10 +2317,39 @@ pub enum KeyBackupState {
 pub enum RecoveryState {
     Unknown,
     Disabled,
+    /// `enable_recovery` is running
+    Enabling,
     Incomplete,
     Enabled,
 }
 
+/// shown to a person once. macltok never stores or logs it, and Debug hides it
+#[derive(Clone, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize), serde(transparent))]
+pub struct RecoveryKey(String);
+
+impl RecoveryKey {
+    pub(crate) fn new(key: String) -> Self {
+        Self(key)
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for RecoveryKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("RecoveryKey(...)")
+    }
+}
+
+impl fmt::Display for RecoveryKey {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&self.0)
+    }
+}
+
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[non_exhaustive]

Modified file: src/transport.rs+52 additions−4 deletions@@ -35,10 +35,10 @@ use crate::{
     MentionsBoundary, MentionsCommand, MentionsPage, MessageContent, MessageEditContent,
     NotificationCommand, OwnDevice, PackCommand, PackImageInfo, PackUsage, Patch,
     PowerLevelChanges, Profile, PushNotification, PushNotificationEvent, PushNotificationStatus,
-    RoomCommand, RoomListFilter, RoomNotificationMode, RoomNotificationSettings, RoomPowerLevels,
-    RoomSummary, SavedMentionContext, SearchCommand, SearchCoverage, SearchPage, SearchScope,
-    SearchSession, SpaceChild, ThreadListCommand, TimelineCommand, TimelineId, VerificationAction,
-    VerificationTarget,
+    RecoveryKey, RoomCommand, RoomListFilter, RoomNotificationMode, RoomNotificationSettings,
+    RoomPowerLevels, RoomSummary, SavedMentionContext, SearchCommand, SearchCoverage, SearchPage,
+    SearchScope, SearchSession, SpaceChild, ThreadListCommand, TimelineCommand, TimelineId,
+    VerificationAction, VerificationTarget,
     encryption::encryption_state,
     engine::{MediaService, StoreLock},
     model::{PushNotificationRoom, PushNotificationSender},
@@ -800,6 +800,54 @@ impl ClientHandle {
         .await
     }
 
+    /// the key is in the answer and nowhere else, so show it before dropping it
+    pub async fn enable_recovery(&self, passphrase: Option<String>) -> Result<RecoveryKey, Error> {
+        self.recovery_key(EncryptionCommand::EnableRecovery { passphrase })
+            .await
+    }
+
+    pub async fn reset_recovery_key(
+        &self,
+        passphrase: Option<String>,
+    ) -> Result<RecoveryKey, Error> {
+        self.recovery_key(EncryptionCommand::ResetRecoveryKey { passphrase })
+            .await
+    }
+
+    async fn recovery_key(&self, command: EncryptionCommand) -> Result<RecoveryKey, Error> {
+        match self.execute(Command::Encryption(command)).await? {
+            CommandOutput::RecoveryKey(key) => Ok(key),
+            output => Err(unexpected("recovery key", &output)),
+        }
+    }
+
+    pub async fn disable_recovery(&self) -> Result<(), Error> {
+        self.run(Command::Encryption(EncryptionCommand::DisableRecovery))
+            .await
+    }
+
+    /// checks a typed key or passphrase against secret storage without importing anything
+    pub async fn verify_recovery_key(&self, recovery_key: &str) -> Result<bool, Error> {
+        use matrix_sdk::encryption::secret_storage::SecretStorageError;
+        match self
+            .client
+            .encryption()
+            .secret_storage()
+            .open_secret_store(recovery_key)
+            .await
+        {
+            Ok(_) => Ok(true),
+            Err(SecretStorageError::SecretStorageKey(_)) => Ok(false),
+            Err(SecretStorageError::MissingKeyInfo { .. }) => {
+                Err(Error::new(ErrorKind::Invalid, "recovery is not set up"))
+            }
+            Err(source) => Err(Error::from_recovery(
+                "checking the recovery key failed",
+                source.into(),
+            )),
+        }
+    }
+
     pub async fn create_key_backup(&self) -> Result<(), Error> {
         self.run(Command::Encryption(EncryptionCommand::CreateKeyBackup))
             .await

macltok

Commit 743123167e29

Commit `743123167e29`