Migrate legacy snapshot manifests safely

eldryoth · eldryoth · commit 5daa043ef379 · 2026-07-11T20:39:39.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -58,6 +58,10 @@ behavior when the change improves security or project direction.
 - Verify generation freshness through bounded per-snapshot HMAC witnesses rather
   than rereading and hashing every retained config under the store lock, and
   remove the snapshot crate's unused direct logging dependency.
+- Preserve authenticated snapshot manifests created before generation witnesses:
+  legacy manifests remain fully verifiable for current, rollback, and doctor
+  operations and are atomically migrated after verification during the next
+  locked snapshot creation.
 - Make OpenSSL cipher allow-lists deterministic across protocol families:
   omitting all TLS 1.2 or TLS 1.3 suites now disables that protocol version
   instead of retaining Mozilla acceptor defaults. Use the current Mozilla v5
diff --git a/crates/fluxheim-snapshot/src/generation.rs b/crates/fluxheim-snapshot/src/generation.rs
@@ -3,7 +3,8 @@ use std::fs;
 use serde::{Deserialize, Serialize};
 
 use crate::integrity::{
-    GENERATION_MAC_LABEL, MAX_INTEGRITY_MANIFEST_BYTES, SnapshotIntegrityManifest,
+    GENERATION_MAC_LABEL, MAX_INTEGRITY_MANIFEST_BYTES, SnapshotIntegrityKey,
+    SnapshotIntegrityManifest,
 };
 use crate::metadata::{
     MAX_SNAPSHOT_METADATA_BYTES, SnapshotMetadata, validate_snapshot_id, validate_snapshot_metadata,
@@ -26,7 +27,7 @@ struct GenerationState {
 
 impl SnapshotStore {
     pub(crate) fn allocate_generation_unlocked(&self) -> Result<u64, SnapshotError> {
-        let observed_max = self.observed_max_generation()?;
+        let observed_max = self.observed_max_generation(true)?;
         let current = match read_optional_regular_file_to_string_with_limit(
             &self.generation_path(),
             MAX_GENERATION_STATE_BYTES as u64,
@@ -50,7 +51,7 @@ impl SnapshotStore {
     }
 
     pub(crate) fn verify_generation_state(&self) -> Result<(), SnapshotError> {
-        let observed_max = self.observed_max_generation()?;
+        let observed_max = self.observed_max_generation(false)?;
         let Some(raw) = read_optional_regular_file_to_string_with_limit(
             &self.generation_path(),
             MAX_GENERATION_STATE_BYTES as u64,
@@ -121,19 +122,20 @@ impl SnapshotStore {
         self.root().join("generation.toml")
     }
 
-    fn observed_max_generation(&self) -> Result<u64, SnapshotError> {
+    fn observed_max_generation(&self, migrate_legacy: bool) -> Result<u64, SnapshotError> {
         if !self.safe_existing_configs_dir()? {
             return Ok(0);
         }
         if let Some(key) = self.integrity.as_deref() {
-            return self.observed_authenticated_generation(key);
+            return self.observed_authenticated_generation(key, migrate_legacy);
         }
         self.observed_unverified_generation()
     }
 
     fn observed_authenticated_generation(
         &self,
-        key: &crate::integrity::SnapshotIntegrityKey,
+        key: &SnapshotIntegrityKey,
+        migrate_legacy: bool,
     ) -> Result<u64, SnapshotError> {
         let mut maximum = 0;
         for entry in fs::read_dir(self.configs_dir()).map_err(SnapshotError::Io)? {
@@ -157,14 +159,61 @@ impl SnapshotStore {
             )?;
             let manifest: SnapshotIntegrityManifest =
                 toml::from_str(&raw).map_err(|_| SnapshotError::GenerationStateInvalid)?;
-            let generation = key
-                .verify_generation_witness(id, &manifest)
-                .map_err(|_| SnapshotError::GenerationStateInvalid)?;
+            let generation = match &manifest {
+                SnapshotIntegrityManifest::V2(witness) => {
+                    key.verify_generation_witness(id, witness)
+                }
+                SnapshotIntegrityManifest::V1(_) => {
+                    self.verify_legacy_generation(id, key, &manifest, migrate_legacy)
+                }
+            }
+            .map_err(generation_scan_error)?;
             maximum = maximum.max(generation);
         }
         Ok(maximum)
     }
 
+    fn verify_legacy_generation(
+        &self,
+        id: &str,
+        key: &SnapshotIntegrityKey,
+        manifest: &SnapshotIntegrityManifest,
+        migrate: bool,
+    ) -> Result<u64, SnapshotError> {
+        let config = read_regular_file_to_string_with_limit(
+            &self.config_path(id),
+            crate::store_fs::MAX_SNAPSHOT_FILE_BYTES,
+        )?;
+        let metadata_raw = read_regular_file_to_string_with_limit(
+            &self.metadata_path(id),
+            MAX_SNAPSHOT_METADATA_BYTES,
+        )?;
+        let metadata: SnapshotMetadata =
+            toml::from_str(&metadata_raw).map_err(SnapshotError::Decode)?;
+        validate_snapshot_metadata(&metadata, id)?;
+        key.verify(
+            id,
+            config.as_bytes(),
+            metadata_raw.as_bytes(),
+            metadata.generation,
+            manifest,
+        )?;
+        if migrate {
+            let witness = key.manifest(
+                id,
+                config.as_bytes(),
+                metadata_raw.as_bytes(),
+                metadata.generation,
+            )?;
+            let raw = toml::to_string_pretty(&witness).map_err(SnapshotError::Encode)?;
+            if raw.len() as u64 > MAX_INTEGRITY_MANIFEST_BYTES {
+                return Err(SnapshotError::GenerationStateInvalid);
+            }
+            write_atomically(&self.integrity_path(id), raw.as_bytes())?;
+        }
+        Ok(metadata.generation)
+    }
+
     fn observed_unverified_generation(&self) -> Result<u64, SnapshotError> {
         let mut maximum = 0;
         for entry in fs::read_dir(self.configs_dir()).map_err(SnapshotError::Io)? {
@@ -186,3 +235,10 @@ impl SnapshotStore {
         Ok(maximum)
     }
 }
+
+fn generation_scan_error(error: SnapshotError) -> SnapshotError {
+    match error {
+        SnapshotError::CryptoProvider(_) => error,
+        _ => SnapshotError::GenerationStateInvalid,
+    }
+}
diff --git a/crates/fluxheim-snapshot/src/integrity.rs b/crates/fluxheim-snapshot/src/integrity.rs
@@ -33,9 +33,25 @@ pub(crate) struct SnapshotIntegrityKey {
     source_path: std::path::PathBuf,
 }
 
+#[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
+#[serde(untagged)]
+pub(crate) enum SnapshotIntegrityManifest {
+    V2(SnapshotIntegrityManifestV2),
+    V1(SnapshotIntegrityManifestV1),
+}
+
+#[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct SnapshotIntegrityManifestV1 {
+    pub algorithm: String,
+    pub key_id: String,
+    pub config_sha256: String,
+    pub metadata_hmac_sha256: String,
+}
+
 #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
-pub(crate) struct SnapshotIntegrityManifest {
+pub(crate) struct SnapshotIntegrityManifestV2 {
     pub algorithm: String,
     pub key_id: String,
     pub config_sha256: String,
@@ -101,14 +117,14 @@ impl SnapshotIntegrityKey {
             .map_err(SnapshotError::CryptoProvider)?;
         let signature = self.sign_result(id, config, metadata)?;
         let generation_signature = self.sign_generation_witness(id, generation)?;
-        Ok(SnapshotIntegrityManifest {
+        Ok(SnapshotIntegrityManifest::V2(SnapshotIntegrityManifestV2 {
             algorithm: "hmac-sha256".to_owned(),
             key_id: self.key_id.clone(),
             config_sha256: hex(&config_digest),
             metadata_hmac_sha256: hex(&signature),
             generation,
             generation_hmac_sha256: hex(&generation_signature),
-        })
+        }))
     }
 
     pub(crate) fn key_id(&self) -> &str {
@@ -164,22 +180,25 @@ impl SnapshotIntegrityKey {
         generation: u64,
         manifest: &SnapshotIntegrityManifest,
     ) -> Result<(), SnapshotError> {
-        if manifest.algorithm != "hmac-sha256" || manifest.key_id != self.key_id {
+        let common = manifest.common();
+        if common.algorithm != "hmac-sha256" || common.key_id != self.key_id {
             return Err(SnapshotError::IntegrityVerificationFailed { id: id.to_owned() });
         }
         let config_digest = self
             .provider
             .sha256(&[config])
             .map_err(SnapshotError::CryptoProvider)
             .map(|digest| hex(&digest))?;
-        if config_digest != manifest.config_sha256 {
+        if config_digest != common.config_sha256 {
             return Err(SnapshotError::IntegrityVerificationFailed { id: id.to_owned() });
         }
-        if manifest.generation != generation {
-            return Err(SnapshotError::IntegrityVerificationFailed { id: id.to_owned() });
+        if let SnapshotIntegrityManifest::V2(witness) = manifest {
+            if witness.generation != generation {
+                return Err(SnapshotError::IntegrityVerificationFailed { id: id.to_owned() });
+            }
+            self.verify_generation_witness(id, witness)?;
         }
-        self.verify_generation_witness(id, manifest)?;
-        let expected = decode_hex_32(&manifest.metadata_hmac_sha256)
+        let expected = decode_hex_32(common.metadata_hmac_sha256)
             .ok_or_else(|| SnapshotError::IntegrityVerificationFailed { id: id.to_owned() })?;
         if self
             .sign_result(id, config, metadata)?
@@ -195,7 +214,7 @@ impl SnapshotIntegrityKey {
     pub(crate) fn verify_generation_witness(
         &self,
         id: &str,
-        manifest: &SnapshotIntegrityManifest,
+        manifest: &SnapshotIntegrityManifestV2,
     ) -> Result<u64, SnapshotError> {
         crate::metadata::validate_snapshot_id(id)?;
         if manifest.algorithm != "hmac-sha256" || manifest.key_id != self.key_id {
@@ -263,6 +282,32 @@ impl SnapshotIntegrityKey {
     }
 }
 
+impl SnapshotIntegrityManifest {
+    fn common(&self) -> SnapshotIntegrityManifestCommon<'_> {
+        match self {
+            Self::V2(manifest) => SnapshotIntegrityManifestCommon {
+                algorithm: &manifest.algorithm,
+                key_id: &manifest.key_id,
+                config_sha256: &manifest.config_sha256,
+                metadata_hmac_sha256: &manifest.metadata_hmac_sha256,
+            },
+            Self::V1(manifest) => SnapshotIntegrityManifestCommon {
+                algorithm: &manifest.algorithm,
+                key_id: &manifest.key_id,
+                config_sha256: &manifest.config_sha256,
+                metadata_hmac_sha256: &manifest.metadata_hmac_sha256,
+            },
+        }
+    }
+}
+
+struct SnapshotIntegrityManifestCommon<'a> {
+    algorithm: &'a str,
+    key_id: &'a str,
+    config_sha256: &'a str,
+    metadata_hmac_sha256: &'a str,
+}
+
 fn encoded_length(length: usize) -> Result<[u8; 8], SnapshotError> {
     u64::try_from(length)
         .map(u64::to_be_bytes)
diff --git a/crates/fluxheim-snapshot/src/snapshot_hardening_tests.rs b/crates/fluxheim-snapshot/src/snapshot_hardening_tests.rs
@@ -369,6 +369,65 @@ fn unverified_generation_scan_rejects_oversized_metadata() {
     assert_eq!(store.list_entries().unwrap().len(), 1);
 }
 
+#[test]
+fn prior_manifest_format_loads_and_migrates_on_locked_creation() {
+    let dir = TestDir::new("snapshot-manifest-v1-upgrade");
+    let (store, _key) = authenticated_store(&dir);
+    let first = store
+        .snapshot_config(&Config::default(), Some("first"))
+        .unwrap();
+    let second = store
+        .snapshot_config(&Config::default(), Some("second"))
+        .unwrap();
+    for id in [&first.id, &second.id] {
+        rewrite_manifest_as_v1(&store, id);
+    }
+
+    assert_eq!(store.current_snapshot().unwrap().unwrap().id, second.id);
+    assert_eq!(
+        store.rollback_candidate(None).unwrap().snapshot.id,
+        first.id
+    );
+    assert!(store.doctor().unwrap().healthy);
+    assert!(!manifest_raw(&store, &first.id).contains("generation_hmac_sha256"));
+
+    let third = store
+        .snapshot_config(&Config::default(), Some("third"))
+        .unwrap();
+
+    assert_eq!(third.metadata.generation, 3);
+    for id in [&first.id, &second.id, &third.id] {
+        let raw = manifest_raw(&store, id);
+        assert!(raw.contains("generation_hmac_sha256"));
+        assert_eq!(
+            store.verify(id).unwrap(),
+            crate::SnapshotIntegrityStatus::Authenticated
+        );
+    }
+}
+
+fn rewrite_manifest_as_v1(store: &SnapshotStore, id: &str) {
+    let path = store
+        .root()
+        .join("configs")
+        .join(format!("{id}.integrity.toml"));
+    let mut manifest: toml::Table =
+        toml::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+    manifest.remove("generation");
+    manifest.remove("generation_hmac_sha256");
+    std::fs::write(path, toml::to_string_pretty(&manifest).unwrap()).unwrap();
+}
+
+fn manifest_raw(store: &SnapshotStore, id: &str) -> String {
+    std::fs::read_to_string(
+        store
+            .root()
+            .join("configs")
+            .join(format!("{id}.integrity.toml")),
+    )
+    .unwrap()
+}
+
 fn authenticated_store(dir: &TestDir) -> (SnapshotStore, std::path::PathBuf) {
     let store = store_with_provider(dir, Arc::new(TestCryptoProvider));
     (store, dir.child("snapshot.key"))
diff --git a/docs/config-snapshots.md b/docs/config-snapshots.md
@@ -50,6 +50,13 @@ Each authenticated integrity manifest includes a small generation witness, so
 freshness checks scan at most 4 KiB per retained manifest and do not reread or
 hash complete snapshot configurations while holding the store mutation lock.
 Unverified stores scan metadata with a 16 KiB per-file bound.
+Authenticated manifests created before generation witnesses remain readable.
+Fluxheim fully verifies their original config digest and metadata HMAC for
+current, rollback, and doctor operations. The next snapshot creation performs
+that same verification under the store lock and atomically replaces each legacy
+manifest with the witnessed format before publishing the new snapshot. A store
+with many legacy snapshots therefore pays one bounded upgrade scan that may read
+their configs; subsequent mutations use only the small witnesses.
 Fluxheim rejects a missing or lower valid counter when retained snapshot
 metadata proves a higher generation. An HMAC file cannot detect coordinated
 rollback of the complete store after every newer snapshot has been pruned,
