Skip to main content

passalong_core/encryption/
admin_trait.rs

1//! What `passalong encrypt`, `init`, `check`, `list`, and `prune` need from
2//! a store's encryption, whatever holds the store.
3//!
4//! [`FsEncryptionAdmin`] does it on a filesystem, through this module's
5//! siblings: journals, a stop file, and folders renamed into place. A store
6//! behind an API implements [`EncryptionAdmin`] with calls instead, and its
7//! re-encryption with [`Rewrite`], which [`run_rewrite`] drives the same way
8//! for both.
9
10use std::sync::Arc;
11use std::time::{Duration, Instant};
12
13use async_trait::async_trait;
14use chrono::{DateTime, Utc};
15use tokio::io::AsyncReadExt;
16
17use super::{RewriteKind, StoreState, admin, rewrite};
18use crate::clock::Clock;
19use crate::crypto::{DataKey, KdfParams, KeyId, Words};
20use crate::fs::{BoxRead, RemoteFs};
21use crate::model::{ContentHasher, ItemId, ItemMeta};
22use crate::store::{Store, StoreError};
23
24/// How often a long re-encryption tells its store it is still running.
25/// A server's lease lasts ten minutes by default.
26pub const HEARTBEAT_EVERY: Duration = Duration::from_secs(60);
27
28/// Changing a store's encryption.
29#[async_trait]
30pub trait EncryptionAdmin: Send + Sync {
31    /// What the store says about its encryption.
32    async fn inspect(&self) -> Result<StoreState, StoreError>;
33
34    /// Encrypts an empty plaintext store under a new key wrapped with
35    /// `words`, and returns the key.
36    async fn set_up(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError>;
37
38    /// Encrypts a plaintext store under a new key, setting its items aside
39    /// unencrypted, and returns the key.
40    async fn fresh_start(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError>;
41
42    /// The data key of an encrypted store, unwrapped with its `words`.
43    async fn join(&self, words: &Words) -> Result<DataKey, StoreError>;
44
45    /// Wraps the same key with `new` words; no item changes. Returns the
46    /// key's id.
47    async fn change_words(
48        &self,
49        current: &Words,
50        new: &Words,
51        kdf: KdfParams,
52    ) -> Result<KeyId, StoreError>;
53
54    /// Re-encrypts every item of a plaintext store under a new key, and
55    /// returns the key.
56    async fn migrate(
57        &self,
58        words: &Words,
59        kdf: KdfParams,
60        clock: Arc<dyn Clock>,
61    ) -> Result<DataKey, StoreError>;
62
63    /// Moves every item from the `old` key to a new one, and returns the
64    /// new key.
65    async fn rotate(
66        &self,
67        old: &DataKey,
68        words: &Words,
69        kdf: KdfParams,
70        clock: Arc<dyn Clock>,
71    ) -> Result<DataKey, StoreError>;
72
73    /// The plaintext items a fresh start set aside, as a store of their own.
74    fn plain_store(&self) -> Box<dyn Store + '_>;
75
76    /// Removes the place of the plaintext items once it is empty, where the
77    /// store has one; `true` when something was removed.
78    async fn remove_plain_if_empty(&self) -> Result<bool, StoreError>;
79
80    /// The filesystem, for what only a filesystem has: its journals and
81    /// their recovery, the stop file, and the leftovers of v0.2.0. `None`
82    /// for a store behind an API.
83    fn fs(&self) -> Option<&dyn RemoteFs> {
84        None
85    }
86
87    /// The re-encryption a store behind an API holds open, if any. A
88    /// filesystem's is in its journal instead, reached through
89    /// [`EncryptionAdmin::fs`].
90    async fn open_rewrite(&self) -> Result<Option<OpenRewrite>, StoreError> {
91        Ok(None)
92    }
93
94    /// Finishes the open re-encryption, taking it over first when another
95    /// device held it and its lease has ended. `new` unwraps the new key.
96    /// A rotation reads its items with `device`'s key when that is the old
97    /// one, and otherwise with the key `old_words` unwrap. Returns the new
98    /// key.
99    async fn resume_rewrite(
100        &self,
101        _new: &Words,
102        _device: Option<&DataKey>,
103        _old_words: Option<&Words>,
104    ) -> Result<DataKey, StoreError> {
105        Err(StoreError::Backend(
106            "this store keeps no re-encryption session".to_owned(),
107        ))
108    }
109
110    /// Drops the open re-encryption, taking it over first when another
111    /// device held it and its lease has ended; the store is then as it was
112    /// before.
113    async fn abort_rewrite(&self) -> Result<(), StoreError> {
114        Err(StoreError::Backend(
115            "this store keeps no re-encryption session".to_owned(),
116        ))
117    }
118}
119
120/// A re-encryption a server holds open.
121#[derive(Debug, Clone, PartialEq, Eq)]
122pub struct OpenRewrite {
123    /// Migrating or rotating.
124    pub kind: RewriteKind,
125    /// Whether this device's credentials hold it.
126    pub mine: bool,
127    /// Who holds it, as the server names them.
128    pub holder: String,
129    /// When its holder's lease ends; after that another device may take it
130    /// over.
131    pub lease_ends: DateTime<Utc>,
132    /// The key it moves to.
133    pub new_key: KeyId,
134    /// The key the items are under until it is committed; `None` when
135    /// migrating.
136    pub old_key: Option<KeyId>,
137    /// How many items it has copied.
138    pub staged: usize,
139    /// How many items it copies.
140    pub items: usize,
141}
142
143impl OpenRewrite {
144    /// Whether its lease has ended at `now`.
145    pub fn lease_ended(&self, now: DateTime<Utc>) -> bool {
146        self.lease_ends <= now
147    }
148}
149
150/// A re-encryption in progress: items are read from a source under the old
151/// key, or none, and stored again under the new key, then read back, then
152/// the new key takes over at [`Rewrite::commit`].
153#[async_trait]
154pub trait Rewrite: Send + Sync {
155    /// The items to re-encrypt, opened as they are now.
156    fn source(&self) -> &dyn Store;
157
158    /// The id `meta`'s item gets under the new key.
159    ///
160    /// # Errors
161    ///
162    /// When the id cannot be formed from `meta`.
163    fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError>;
164
165    /// Whether the item with the new id `id` is stored already, as it is
166    /// after a resumed run.
167    async fn staged(&self, id: &ItemId) -> Result<bool, StoreError>;
168
169    /// Stores `meta`'s item under the new key, keeping its metadata and
170    /// creation time.
171    async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError>;
172
173    /// Reads a newly stored item back, by its new id.
174    async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError>;
175
176    /// Tells the store the re-encryption is still running.
177    async fn heartbeat(&self) -> Result<(), StoreError>;
178
179    /// How often [`Rewrite::heartbeat`] is due.
180    fn heartbeat_every(&self) -> Duration {
181        HEARTBEAT_EVERY
182    }
183
184    /// Lets the new key take over and drops the source.
185    async fn commit(&self) -> Result<(), StoreError>;
186}
187
188/// Re-encrypts every source item not yet staged, oldest first, reads every
189/// new copy back and compares its SHA-256 and size, then commits. Returns
190/// how many items there are. Run again after an interruption, it repeats
191/// nothing already staged.
192///
193/// # Errors
194///
195/// The store's errors, and [`StoreError::Corrupt`] for a copy that does not
196/// match its source; nothing is committed then.
197pub async fn run_rewrite(rewrite: &dyn Rewrite) -> Result<usize, StoreError> {
198    let mut alive = KeepAlive {
199        last: Instant::now(),
200    };
201    let source = rewrite.source();
202    let mut ids = source.list_ids().await?;
203    ids.reverse();
204    let mut metas = Vec::with_capacity(ids.len());
205    for id in &ids {
206        let meta = source.get_meta(id).await?;
207        if !rewrite.staged(&rewrite.target_id(&meta)?).await? {
208            let (meta, content) = source.get(id).await?;
209            rewrite.import(&meta, content).await?;
210        }
211        metas.push(meta);
212        alive.tick(rewrite).await?;
213    }
214    for meta in &metas {
215        verify(rewrite, meta).await?;
216        alive.tick(rewrite).await?;
217    }
218    rewrite.commit().await?;
219    Ok(metas.len())
220}
221
222/// Sends a heartbeat once [`HEARTBEAT_EVERY`] has passed since the last.
223struct KeepAlive {
224    last: Instant,
225}
226
227impl KeepAlive {
228    async fn tick(&mut self, rewrite: &dyn Rewrite) -> Result<(), StoreError> {
229        if self.last.elapsed() >= rewrite.heartbeat_every() {
230            rewrite.heartbeat().await?;
231            self.last = Instant::now();
232        }
233        Ok(())
234    }
235}
236
237/// Reads back the new copy of `meta`'s item and compares its SHA-256 and
238/// size.
239async fn verify(rewrite: &dyn Rewrite, meta: &ItemMeta) -> Result<(), StoreError> {
240    let id = rewrite.target_id(meta)?;
241    let (_, mut content) = rewrite.read_back(&id).await?;
242    let mut hasher = ContentHasher::new();
243    let mut buf = vec![0_u8; 64 * 1024];
244    loop {
245        let n = content
246            .read(&mut buf)
247            .await
248            .map_err(|err| StoreError::Content(err.to_string()))?;
249        if n == 0 {
250            break;
251        }
252        hasher.update(&buf[..n]);
253    }
254    let digest = hasher.finalize();
255    if digest.sha256_hex() != meta.sha256 || digest.size() != meta.size {
256        return Err(StoreError::Corrupt {
257            id: id.to_string(),
258            reason: format!("its re-encrypted copy does not match {}", meta.id),
259        });
260    }
261    Ok(())
262}
263
264/// [`EncryptionAdmin`] on a filesystem: the `local` and `ssh` backends.
265#[derive(Debug)]
266pub struct FsEncryptionAdmin<F> {
267    fs: F,
268}
269
270impl<F: RemoteFs> FsEncryptionAdmin<F> {
271    /// Changes the encryption of the store on `fs`.
272    pub fn new(fs: F) -> Self {
273        Self { fs }
274    }
275}
276
277#[async_trait]
278impl<F: RemoteFs> EncryptionAdmin for FsEncryptionAdmin<F> {
279    async fn inspect(&self) -> Result<StoreState, StoreError> {
280        admin::inspect(&self.fs).await
281    }
282
283    async fn set_up(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError> {
284        admin::set_up(&self.fs, words, kdf).await
285    }
286
287    async fn fresh_start(&self, words: &Words, kdf: KdfParams) -> Result<DataKey, StoreError> {
288        admin::fresh_start(&self.fs, words, kdf).await
289    }
290
291    async fn join(&self, words: &Words) -> Result<DataKey, StoreError> {
292        admin::join(&self.fs, words).await
293    }
294
295    async fn change_words(
296        &self,
297        current: &Words,
298        new: &Words,
299        kdf: KdfParams,
300    ) -> Result<KeyId, StoreError> {
301        admin::change_words(&self.fs, current, new, kdf).await
302    }
303
304    async fn migrate(
305        &self,
306        words: &Words,
307        kdf: KdfParams,
308        clock: Arc<dyn Clock>,
309    ) -> Result<DataKey, StoreError> {
310        rewrite::migrate(&self.fs, words, kdf, clock).await
311    }
312
313    async fn rotate(
314        &self,
315        old: &DataKey,
316        words: &Words,
317        kdf: KdfParams,
318        clock: Arc<dyn Clock>,
319    ) -> Result<DataKey, StoreError> {
320        rewrite::rotate(&self.fs, old, words, kdf, clock).await
321    }
322
323    fn plain_store(&self) -> Box<dyn Store + '_> {
324        Box::new(admin::plain_store(&self.fs))
325    }
326
327    async fn remove_plain_if_empty(&self) -> Result<bool, StoreError> {
328        admin::remove_plain_if_empty(&self.fs).await
329    }
330
331    fn fs(&self) -> Option<&dyn RemoteFs> {
332        Some(&self.fs)
333    }
334}
335
336#[cfg(test)]
337mod tests {
338    use super::*;
339    use crate::crypto::CryptoError;
340    use crate::fs::LocalFs;
341    use crate::model::NewItem;
342    use crate::testing::ManualClock;
343    use tempfile::TempDir;
344
345    use crate::encryption::rewrite::tests::{W1, W2, quick};
346
347    fn words(text: &str) -> Words {
348        Words::parse(text).unwrap()
349    }
350
351    fn clock() -> Arc<dyn Clock> {
352        Arc::new(ManualClock::at("2026-09-19T15:00:00Z"))
353    }
354
355    async fn put(dir: &TempDir, key: Option<&DataKey>, text: &str) {
356        let store = crate::encryption::open_with_key(
357            LocalFs::new(dir.path()),
358            key.cloned(),
359            clock(),
360            Box::new(crate::random::StdRandom::new()),
361        )
362        .await
363        .unwrap();
364        store
365            .put(
366                NewItem::text("box"),
367                Box::new(std::io::Cursor::new(text.as_bytes().to_vec())),
368            )
369            .await
370            .unwrap();
371    }
372
373    #[tokio::test]
374    async fn the_filesystem_admin_does_what_the_functions_do() {
375        let dir = TempDir::new().unwrap();
376        let admin = FsEncryptionAdmin::new(LocalFs::new(dir.path()));
377        assert!(admin.fs().is_some());
378        assert_eq!(
379            admin.inspect().await.unwrap(),
380            StoreState::Plain { items: 0 }
381        );
382
383        let key = admin.set_up(&words(W1), quick()).await.unwrap();
384        assert_eq!(
385            admin.inspect().await.unwrap(),
386            StoreState::Encrypted {
387                key_id: key.key_id(),
388                plain_left: 0
389            }
390        );
391        assert_eq!(admin.join(&words(W1)).await.unwrap().key_id(), key.key_id());
392        let id = admin
393            .change_words(&words(W1), &words(W2), quick())
394            .await
395            .unwrap();
396        assert_eq!(id, key.key_id());
397        assert!(matches!(
398            admin.join(&words(W1)).await,
399            Err(StoreError::Encryption(
400                crate::encryption::EncryptionError::Crypto(CryptoError::WrongWords)
401            ))
402        ));
403
404        put(&dir, Some(&key), "one").await;
405        put(&dir, Some(&key), "two").await;
406        let new = admin
407            .rotate(&key, &words(W1), quick(), clock())
408            .await
409            .unwrap();
410        assert_ne!(new.key_id(), key.key_id());
411        let store = crate::encryption::open_with_key(
412            LocalFs::new(dir.path()),
413            Some(new),
414            clock(),
415            Box::new(crate::random::StdRandom::new()),
416        )
417        .await
418        .unwrap();
419        assert_eq!(store.list().await.unwrap().len(), 2);
420        assert_eq!(admin.plain_store().list_ids().await.unwrap().len(), 0);
421        assert!(!admin.remove_plain_if_empty().await.unwrap());
422    }
423
424    #[tokio::test]
425    async fn a_migration_and_a_fresh_start_go_through_the_trait() {
426        let migrated = TempDir::new().unwrap();
427        put(&migrated, None, "keep me").await;
428        let admin: Box<dyn EncryptionAdmin> =
429            Box::new(FsEncryptionAdmin::new(LocalFs::new(migrated.path())));
430        let key = admin.migrate(&words(W1), quick(), clock()).await.unwrap();
431        assert!(matches!(
432            admin.inspect().await.unwrap(),
433            StoreState::Encrypted { key_id, plain_left: 0 } if key_id == key.key_id()
434        ));
435
436        let fresh = TempDir::new().unwrap();
437        put(&fresh, None, "set aside").await;
438        let admin = FsEncryptionAdmin::new(LocalFs::new(fresh.path()));
439        admin.fresh_start(&words(W1), quick()).await.unwrap();
440        assert_eq!(admin.plain_store().list_ids().await.unwrap().len(), 1);
441    }
442
443    /// A rewrite whose copies come back altered.
444    struct Lying<'a> {
445        inner: &'a dyn Rewrite,
446    }
447
448    #[async_trait]
449    impl Rewrite for Lying<'_> {
450        fn source(&self) -> &dyn Store {
451            self.inner.source()
452        }
453        fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
454            self.inner.target_id(meta)
455        }
456        async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
457            self.inner.staged(id).await
458        }
459        async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
460            self.inner.import(meta, content).await
461        }
462        async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
463            let (meta, _) = self.inner.read_back(id).await?;
464            Ok((meta, Box::new(std::io::Cursor::new(b"altered".to_vec()))))
465        }
466        async fn heartbeat(&self) -> Result<(), StoreError> {
467            Ok(())
468        }
469        async fn commit(&self) -> Result<(), StoreError> {
470            panic!("a copy that does not match must not be committed")
471        }
472    }
473
474    /// Re-encrypts a plaintext store's items into a sealed one, in memory
475    /// terms: a source store and a target store on two folders.
476    struct Copying {
477        source: crate::store::FsStore<LocalFs>,
478        target: crate::store::FsStore<LocalFs>,
479        committed: std::sync::atomic::AtomicBool,
480    }
481
482    #[async_trait]
483    impl Rewrite for Copying {
484        fn source(&self) -> &dyn Store {
485            &self.source
486        }
487        fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
488            self.target.id_for(meta)
489        }
490        async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
491            self.target.exists(id).await
492        }
493        async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
494            self.target.import(meta, content).await
495        }
496        async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
497            self.target.get(id).await
498        }
499        async fn heartbeat(&self) -> Result<(), StoreError> {
500            Ok(())
501        }
502        async fn commit(&self) -> Result<(), StoreError> {
503            self.committed
504                .store(true, std::sync::atomic::Ordering::SeqCst);
505            Ok(())
506        }
507    }
508
509    #[tokio::test]
510    async fn the_engine_copies_verifies_and_commits_only_matching_copies() {
511        let from = TempDir::new().unwrap();
512        let to = TempDir::new().unwrap();
513        put(&from, None, "a").await;
514        put(&from, None, "b").await;
515        let rng = || Box::new(crate::random::StdRandom::new());
516        let copying = Copying {
517            source: crate::store::FsStore::new(LocalFs::new(from.path()), clock(), rng()),
518            target: crate::store::FsStore::sealed(
519                LocalFs::new(to.path()),
520                clock(),
521                rng(),
522                crate::crypto::Sealer::new(DataKey::generate().unwrap()),
523            ),
524            committed: std::sync::atomic::AtomicBool::new(false),
525        };
526        assert!(matches!(
527            run_rewrite(&Lying { inner: &copying }).await,
528            Err(StoreError::Corrupt { reason, .. }) if reason.contains("does not match")
529        ));
530        assert_eq!(run_rewrite(&copying).await.unwrap(), 2);
531        assert!(copying.committed.load(std::sync::atomic::Ordering::SeqCst));
532        // Run again, it stores nothing twice.
533        assert_eq!(run_rewrite(&copying).await.unwrap(), 2);
534        assert_eq!(copying.target.list_ids().await.unwrap().len(), 2);
535    }
536
537    /// A rewrite whose copies take a while, and whose heartbeat is due
538    /// often.
539    struct Slow<'a> {
540        inner: &'a Copying,
541        beats: std::sync::atomic::AtomicUsize,
542    }
543
544    #[async_trait]
545    impl Rewrite for Slow<'_> {
546        fn source(&self) -> &dyn Store {
547            self.inner.source()
548        }
549        fn target_id(&self, meta: &ItemMeta) -> Result<ItemId, StoreError> {
550            self.inner.target_id(meta)
551        }
552        async fn staged(&self, id: &ItemId) -> Result<bool, StoreError> {
553            self.inner.staged(id).await
554        }
555        async fn import(&self, meta: &ItemMeta, content: BoxRead) -> Result<ItemMeta, StoreError> {
556            tokio::time::sleep(Duration::from_millis(30)).await;
557            self.inner.import(meta, content).await
558        }
559        async fn read_back(&self, id: &ItemId) -> Result<(ItemMeta, BoxRead), StoreError> {
560            self.inner.read_back(id).await
561        }
562        async fn heartbeat(&self) -> Result<(), StoreError> {
563            self.beats.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
564            Ok(())
565        }
566        fn heartbeat_every(&self) -> Duration {
567            Duration::from_millis(10)
568        }
569        async fn commit(&self) -> Result<(), StoreError> {
570            self.inner.commit().await
571        }
572    }
573
574    #[tokio::test]
575    async fn a_slow_rewrite_sends_heartbeats_as_often_as_its_store_asks() {
576        let from = TempDir::new().unwrap();
577        let to = TempDir::new().unwrap();
578        for text in ["a", "b", "c"] {
579            put(&from, None, text).await;
580        }
581        let rng = || Box::new(crate::random::StdRandom::new());
582        let copying = Copying {
583            source: crate::store::FsStore::new(LocalFs::new(from.path()), clock(), rng()),
584            target: crate::store::FsStore::sealed(
585                LocalFs::new(to.path()),
586                clock(),
587                rng(),
588                crate::crypto::Sealer::new(DataKey::generate().unwrap()),
589            ),
590            committed: std::sync::atomic::AtomicBool::new(false),
591        };
592        let slow = Slow {
593            inner: &copying,
594            beats: std::sync::atomic::AtomicUsize::new(0),
595        };
596        assert_eq!(run_rewrite(&slow).await.unwrap(), 3);
597        assert!(slow.beats.load(std::sync::atomic::Ordering::SeqCst) >= 3);
598    }
599}