[PATCH proxmox-backup v2 27/27] sync: pull: decrypt snapshots with matching encryption key fingerprint

Christian Ebner
2026-04-10T16:55:08Z

Decrypt any backup snapshot during pull which was encrypted with a
matching encryption key. Matching of keys is performed by comparing
the fingerprint of the key as stored in the source manifest and the
key configured for the pull sync jobs.

If matching, pass along the key's crypto config to the index and chunk
readers and write the local files unencrypted instead of simply
downloading them. A new manifest file is written instead of the
original one and files registered accordingly.

If the local snapshot already exists (resync), refuse to sync without
decryption if the target snapshot is unencrypted, the source however
encrypted.

To detect file changes for resync, compare the file change
fingerprint calculated on the decrypted files before push sync with
encryption.

Signed-off-by: Christian Ebner <c.ebner@proxmox.com>
---
src/server/pull.rs | 104 ++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 102 insertions(+), 2 deletions(-)

diff --git a/src/server/pull.rs b/src/server/pull.rs
index 40e5353dd..9e95a46c5 100644
--- a/src/server/pull.rs
+++ b/src/server/pull.rs
@@ -3,6 +3,7 @@
use std::collections::hash_map::Entry;
use std::collections::{HashMap, HashSet};
use std::io::{BufReader, Read, Seek, Write};
+use std::os::fd::AsRawFd;
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use std::time::SystemTime;
@@ -10,11 +11,14 @@ use std::time::SystemTime;
use anyhow::{bail, format_err, Context, Error};
use pbs_tools::crypt_config::CryptConfig;
use proxmox_human_byte::HumanByte;
+use serde_json::Value;
+use tokio::fs::OpenOptions;
+use tokio::io::AsyncWriteExt;
use tracing::{info, warn};

use pbs_api_types::{
print_store_and_ns, ArchiveType, Authid, BackupArchiveName, BackupDir, BackupGroup,
- BackupNamespace, GroupFilter, Operation, RateLimitConfig, Remote, SnapshotListItem,
+ BackupNamespace, CryptMode, GroupFilter, Operation, RateLimitConfig, Remote, SnapshotListItem,
VerifyState, CLIENT_LOG_BLOB_NAME, MANIFEST_BLOB_NAME, MAX_NAMESPACE_DEPTH,
PRIV_DATASTORE_AUDIT, PRIV_DATASTORE_BACKUP,
};
@@ -408,6 +412,7 @@ async fn pull_single_archive<'a>(
encountered_chunks: Arc<Mutex<EncounteredChunks>>,
crypt_config: Option<Arc<CryptConfig>>,
backend: &DatastoreBackend,
+ new_manifest: Option<Arc<Mutex<BackupManifest>>>,
) -> Result<SyncStats, Error> {
let archive_name = &archive_info.filename;
let mut path = snapshot.full_path();
@@ -457,6 +462,17 @@ async fn pull_single_archive<'a>(

// Overwrite current tmp file so it will be persisted instead
std::fs::rename(&path, &tmp_path)?;
+
+ if let Some(new_manifest) = new_manifest {
+ let name = archive_name.as_str().try_into()?;
+ // size is identical to original, encrypted index
+ new_manifest.lock().unwrap().add_file(
+ &name,
+ size,
+ csum,
+ CryptMode::None,
+ )?;
+ }
}

sync_stats.add(stats);
@@ -495,6 +511,17 @@ async fn pull_single_archive<'a>(

// Overwrite current tmp file so it will be persisted instead
std::fs::rename(&path, &tmp_path)?;
+
+ if let Some(new_manifest) = new_manifest {
+ let name = archive_name.as_str().try_into()?;
+ // size is identical to original, encrypted index
+ new_manifest.lock().unwrap().add_file(
+ &name,
+ size,
+ csum,
+ CryptMode::None,
+ )?;
+ }
}

sync_stats.add(stats);
@@ -534,6 +561,14 @@ async fn pull_single_archive<'a>(
decrypted_tmpfile.rewind()?;
let (csum, size) = sha256(&mut decrypted_tmpfile)?;

+ if let Some(new_manifest) = new_manifest {
+ let mut new_manifest = new_manifest.lock().unwrap();
+ let name = archive_name.as_str().try_into()?;
+ new_manifest.add_file(&name, size, csum, CryptMode::None)?;
+ }
+
+ nix::unistd::fsync(decrypted_tmpfile.as_raw_fd())?;
+
std::fs::rename(&decrypted_tmp_path, &tmp_path)?;
Ok(())
});
@@ -604,6 +639,8 @@ async fn pull_snapshot<'a>(
return Ok(sync_stats);
}

+ let mut local_manifest_file_fp = None;
+ let mut local_manifest_key_fp = None;
if manifest_name.exists() && !corrupt {
let manifest_blob = proxmox_lang::try_block!({
let mut manifest_file = std::fs::File::open(&manifest_name).map_err(|err| {
@@ -624,12 +661,32 @@ async fn pull_snapshot<'a>(
info!("no data changes");
let _ = std::fs::remove_file(&tmp_manifest_name);
return Ok(sync_stats); // nothing changed
+ } else {
+ let manifest = BackupManifest::try_from(manifest_blob)?;
+ local_manifest_key_fp = manifest.fingerprint()?;
+ if !params.crypt_configs.is_empty() {
+ let fp = manifest.change_detection_fingerprint()?;
+ local_manifest_file_fp = Some(hex::encode(fp));
+ }
}
}

- let manifest_data = tmp_manifest_blob.raw_data().to_vec();
+ let mut manifest_data = tmp_manifest_blob.raw_data().to_vec();
let manifest = BackupManifest::try_from(tmp_manifest_blob)?;

+ if let Value::String(fp) = &manifest.unprotected["change-detection-fingerprint"] {
+ if let Some(local) = local_manifest_file_fp {
+ if *fp == local {
+ if !client_log_name.exists() {
+ reader.try_download_client_log(&client_log_name).await?;
+ };
+ info!("no data changes");
+ let _ = std::fs::remove_file(&tmp_manifest_name);
+ return Ok(sync_stats);
+ }
+ }
+ }
+
if ignore_not_verified_or_encrypted(
&manifest,
snapshot.dir(),
@@ -647,6 +704,22 @@ async fn pull_snapshot<'a>(
}

let mut crypt_config = None;
+ let mut new_manifest = None;
+ if let Ok(Some(source_fingerprint)) = manifest.fingerprint() {
+ for config in &params.crypt_configs {
+ if config.fingerprint() == *source_fingerprint.bytes() {
+ crypt_config = Some(Arc::clone(config));
+ new_manifest = Some(Arc::new(Mutex::new(BackupManifest::new(snapshot.into()))));
+ info!("Found matching key fingerprint {source_fingerprint}, decrypt on pull");
+ break;
+ }
+ }
+ }
+
+ // pre-existing local manifest for unencrypted snapshot, never overwrite with encrypted
+ if local_manifest_key_fp.is_some() && crypt_config.is_none() {
+ bail!("local unencrypted snapshot detected, refuse to sync without source decryption");
+ }

let backend = &params.target.backend;
for item in manifest.files() {
@@ -696,11 +769,38 @@ async fn pull_snapshot<'a>(
encountered_chunks.clone(),
crypt_config.clone(),
backend,
+ new_manifest.clone(),
)
.await?;
sync_stats.add(stats);
}

+ if let Some(new_manifest) = new_manifest {
+ let mut new_manifest = Arc::try_unwrap(new_manifest)
+ .map_err(|_arc| {
+ format_err!("failed to take ownership of still referenced new manifest")
+ })?
+ .into_inner()
+ .unwrap();
+
+ // copy over notes ecc, but drop encryption key fingerprint
+ new_manifest.unprotected = manifest.unprotected.clone();
+ new_manifest.unprotected["key-fingerprint"] = Value::Null;
+
+ let manifest_string = new_manifest.to_string(None)?;
+ let manifest_blob = DataBlob::encode(manifest_string.as_bytes(), None, true)?;
+ // update contents to be uploaded to backend
+ manifest_data = manifest_blob.raw_data().to_vec();
+
+ let mut tmp_manifest_file = OpenOptions::new()
+ .write(true)
+ .truncate(true) // clear pre-existing manifest content
+ .open(&tmp_manifest_name)
+ .await?;
+ tmp_manifest_file.write_all(&manifest_data).await?;
+ tmp_manifest_file.flush().await?;
+ }
+
if let Err(err) = std::fs::rename(&tmp_manifest_name, &manifest_name) {
bail!("Atomic rename file {:?} failed - {}", manifest_name, err);
}
--
2.47.3