[PATCH proxmox-backup 04/20] pbs-config: implement encryption key config handling

Christian Ebner
2026-04-01T07:56:00Z

Implements the handling for encryption key configuration and files.

Individual encryption keys with the secret key material are stored in
individual files, while the config stores duplicate key info, so the
actual key only needs to be loaded when accessed, not for listing.

Key fingerprint is compared when loading the key in order to detect
possible mismatches.

Signed-off-by: Christian Ebner <c.ebner@proxmox.com>
---
pbs-config/Cargo.toml | 1 +
pbs-config/src/encryption_keys.rs | 159 ++++++++++++++++++++++++++++++
pbs-config/src/lib.rs | 1 +
3 files changed, 161 insertions(+)
create mode 100644 pbs-config/src/encryption_keys.rs

diff --git a/pbs-config/Cargo.toml b/pbs-config/Cargo.toml
index eb81ce004..a27964cfd 100644
--- a/pbs-config/Cargo.toml
+++ b/pbs-config/Cargo.toml
@@ -30,3 +30,4 @@ proxmox-uuid.workspace = true

pbs-api-types.workspace = true
pbs-buildcfg.workspace = true
+pbs-key-config.workspace = true
diff --git a/pbs-config/src/encryption_keys.rs b/pbs-config/src/encryption_keys.rs
new file mode 100644
index 000000000..afe16eb1c
--- /dev/null
+++ b/pbs-config/src/encryption_keys.rs
@@ -0,0 +1,159 @@
+use std::collections::HashMap;
+use std::sync::LazyLock;
+
+use anyhow::{bail, format_err, Error};
+use nix::{sys::stat::Mode, unistd::Uid};
+use serde::Deserialize;
+
+use pbs_api_types::{EncryptionKey, KeyInfo, ENCRYPTION_KEY_ID_SCHEMA};
+use proxmox_schema::ApiType;
+use proxmox_section_config::{SectionConfig, SectionConfigData, SectionConfigPlugin};
+use proxmox_sys::fs::CreateOptions;
+
+use pbs_buildcfg::configdir;
+use pbs_key_config::KeyConfig;
+
+use crate::{open_backup_lockfile, replace_backup_config, BackupLockGuard};
+
+pub static CONFIG: LazyLock<SectionConfig> = LazyLock::new(init);
+
+fn init() -> SectionConfig {
+ let obj_schema = EncryptionKey::API_SCHEMA.unwrap_all_of_schema();
+ let plugin = SectionConfigPlugin::new(
+ ENCRYPTION_KEYS_CFG_TYPE_ID.to_string(),
+ Some(String::from("id")),
+ obj_schema,
+ );
+ let mut config = SectionConfig::new(&ENCRYPTION_KEY_ID_SCHEMA);
+ config.register_plugin(plugin);
+
+ config
+}
+
+/// Configuration file location for encryption keys.
+pub const ENCRYPTION_KEYS_CFG_FILENAME: &str = configdir!("/encryption-keys.cfg");
+/// Configuration lock file used to prevent concurrent configuration update operations.
+pub const ENCRYPTION_KEYS_CFG_LOCKFILE: &str = configdir!("/.encryption-keys.lck");
+/// Directory where to store the actual encryption keys
+pub const ENCRYPTION_KEYS_DIR: &str = configdir!("/encryption-keys/");
+
+/// Config type for encryption key config entries
+pub const ENCRYPTION_KEYS_CFG_TYPE_ID: &str = "encryption-key";
+
+/// Get exclusive lock for encryption key configuration update.
+pub fn lock_config() -> Result<BackupLockGuard, Error> {
+ open_backup_lockfile(ENCRYPTION_KEYS_CFG_LOCKFILE, None, true)
+}
+
+/// Load encryption key configuration from file.
+pub fn config() -> Result<(SectionConfigData, [u8; 32]), Error> {
+ let content = proxmox_sys::fs::file_read_optional_string(ENCRYPTION_KEYS_CFG_FILENAME)?;
+ let content = content.unwrap_or_default();
+ let digest = openssl::sha::sha256(content.as_bytes());
+ let data = CONFIG.parse(ENCRYPTION_KEYS_CFG_FILENAME, &content)?;
+ Ok((data, digest))
+}
+
+/// Shell completion helper to complete encryption key id's as found in the config.
+pub fn complete_encryption_key_id(_arg: &str, _param: &HashMap<String, String>) -> Vec<String> {
+ match config() {
+ Ok((data, _digest)) => data.sections.keys().map(|id| id.to_string()).collect(),
+ Err(_) => Vec::new(),
+ }
+}
+
+/// Load the encryption key from file.
+///
+/// Looks up the key in the config and tries to load it from the given file.
+/// Upon loading, the config key fingerprint is compared to the one stored in the key
+/// file.
+pub fn load_key_config(id: &str) -> Result<KeyConfig, Error> {
+ let _lock = lock_config()?;
+ let (config, _digest) = config()?;
+
+ let key: EncryptionKey = config.lookup(ENCRYPTION_KEYS_CFG_TYPE_ID, id)?;
+ let key_config = match &key.info.path {
+ Some(path) => KeyConfig::load(path)?,
+ None => bail!("missing path for encryption key {id}"),
+ };
+
+ let stored_key_info = KeyInfo::from(&key_config);
+
+ if key.info.fingerprint != stored_key_info.fingerprint {
+ bail!("loaded key does not match the config for key {id}");
+ }
+
+ Ok(key_config)
+}
+
+/// Store the encryption key to file.
+///
+/// Inserts the key in the config and stores it to the given file.
+pub fn store_key(id: &str, key: &KeyConfig) -> Result<(), Error> {
+ let _lock = lock_config()?;
+ let (mut config, _digest) = config()?;
+
+ let backup_user = crate::backup_user()?;
+ let keyfile_mode = nix::sys::stat::Mode::from_bits_truncate(0o0640);
+ let dir_options = CreateOptions::new()
+ .perm(Mode::from_bits_truncate(0o0750))
+ .owner(Uid::from_raw(0))
+ .group(backup_user.gid);
+
+ proxmox_sys::fs::ensure_dir_exists(ENCRYPTION_KEYS_DIR, &dir_options, true)?;
+
+ // if the key with given id already exists try to load and store a backup.
+ if config.sections.contains_key(id) {
+ bail!("key with id '{id}' already exists.");
+ }
+
+ let key_path = format!("{ENCRYPTION_KEYS_DIR}{id}.enc");
+ // do not replace existing files
+ key.store_with(
+ &key_path,
+ false,
+ Some(keyfile_mode),
+ Some(Uid::from_raw(0)),
+ Some(backup_user.gid),
+ )?;
+
+ let mut info = KeyInfo::from(key);
+ info.path = Some(key_path);
+
+ let encryption_key = EncryptionKey {
+ id: id.to_string(),
+ info,
+ };
+
+ config.set_data(id, ENCRYPTION_KEYS_CFG_TYPE_ID, encryption_key)?;
+
+ let raw = CONFIG.write(ENCRYPTION_KEYS_CFG_FILENAME, &config)?;
+ replace_backup_config(ENCRYPTION_KEYS_CFG_FILENAME, raw.as_bytes())
+}
+
+/// Delete the encryption key from config.
+///
+/// Deletes the key from the config but keeps a backup of the key file.
+pub fn delete_key(id: &str) -> Result<(), Error> {
+ let _lock = lock_config()?;
+ let (mut config, _digest) = config()?;
+
+ // if the key with given id exists in config, try to remove also file on path.
+ if let Some((section_type, key)) = config.sections.get(id) {
+ if section_type == ENCRYPTION_KEYS_CFG_TYPE_ID {
+ let key = EncryptionKey::deserialize(key)
+ .map_err(|_err| format_err!("failed to parse pre-existing key"))?;
+
+ if let Some(path) = &key.info.path {
+ std::fs::remove_file(path)?;
+ }
+ }
+
+ config.sections.remove(id);
+
+ let raw = CONFIG.write(ENCRYPTION_KEYS_CFG_FILENAME, &config)?;
+ replace_backup_config(ENCRYPTION_KEYS_CFG_FILENAME, raw.as_bytes())
+ } else {
+ bail!("key {id} not found in config");
+ }
+}
diff --git a/pbs-config/src/lib.rs b/pbs-config/src/lib.rs
index 1ed472385..7f7c8c3e1 100644
--- a/pbs-config/src/lib.rs
+++ b/pbs-config/src/lib.rs
@@ -4,6 +4,7 @@ pub use cached_user_info::CachedUserInfo;
pub mod datastore;
pub mod domains;
pub mod drive;
+pub mod encryption_keys;
pub mod media_pool;
pub mod metrics;
pub mod notifications;
--
2.47.3