all lists on lists.proxmox.com
 help / color / mirror / Atom feed
From: Thomas Lamprecht <t.lamprecht@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH proxmox 1/1] installer-types: add full-disk encryption to the disk setup
Date: Wed, 18 Nov 2026 00:42:24 +0100	[thread overview]
Message-ID: <20261117234330.801935-2-t.lamprecht@proxmox.com> (raw)
In-Reply-To: <20261117234330.801935-1-t.lamprecht@proxmox.com>

Let answer files request full-disk encryption of the system disks with
a `[disk-setup.encryption]` section holding the passphrase that unlocks
the system at boot. The filesystem determines how: LUKS2 for ext4, xfs
and Btrfs, native ZFS encryption for ZFS. Further unlock methods, such
as additional passphrases or a recovery key, can be added to LUKS
containers on the installed system.

verify_encryption() rejects what could only fail after the disks were
wiped or could not be entered when unlocking: passphrases with control
characters or longer than the 512 bytes that cryptsetup and OpenZFS
read, and more than 2 ZFS copies, since OpenZFS stores encryption
metadata where a third copy would go. Like the root password, a
passphrase needs at least 8 characters, which also covers the minimum
of 8 bytes of ZFS. The passphrase rules are available on their own, so
that the interactive installers can check a passphrase where it is
entered.

Installers built against this version report answer fetch schema 1.2,
which answers with encryption require, so answer servers do not send
them to installers that would reject the unknown section.

The post-installation webhook data reports the encryption mode, which
follows from the filesystem.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 proxmox-installer-types/src/answer.rs    | 141 ++++++++++++++++++++++-
 proxmox-installer-types/src/lib.rs       |  22 ++++
 proxmox-installer-types/src/post_hook.rs |   5 +-
 3 files changed, 165 insertions(+), 3 deletions(-)

diff --git a/proxmox-installer-types/src/answer.rs b/proxmox-installer-types/src/answer.rs
index 81b10255..07d49a90 100644
--- a/proxmox-installer-types/src/answer.rs
+++ b/proxmox-installer-types/src/answer.rs
@@ -94,7 +94,7 @@ pub mod fetch {
     }
 
     impl AnswerFetchDataSchema {
-        const SCHEMA_VERSION: &str = "1.1";
+        const SCHEMA_VERSION: &str = "1.2";
 
         /// Returns the version as `(major, minor)` tuple, or `None` if it is malformed.
         ///
@@ -173,6 +173,9 @@ impl AutoInstallerConfig {
     /// this with [`fetch::AnswerFetchDataSchema::version()`] of the request to avoid sending an
     /// answer the installer cannot use.
     pub fn required_fetch_schema_version(&self) -> (u32, u32) {
+        if self.disks.encryption.is_some() {
+            return (1, 2);
+        }
         if self.network.bond().is_some() || self.network.vlan().is_some() {
             return (1, 1);
         }
@@ -936,9 +939,29 @@ pub struct DiskSetup {
     #[serde(skip_serializing_if = "Option::is_none")]
     /// Btrfs-specific filesystem options.
     pub btrfs: Option<BtrfsOptions>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    /// Full-disk encryption of the system disks.
+    pub encryption: Option<DiskEncryption>,
 }
 
 impl DiskSetup {
+    /// Checks the encryption options against what can be set up and unlocked at boot.
+    pub fn verify_encryption(&self) -> Result<()> {
+        let Some(encryption) = &self.encryption else {
+            return Ok(());
+        };
+        if let Err(reason) = DiskEncryption::check_passphrase(&encryption.passphrase) {
+            bail!("'disk-setup.encryption.passphrase' {reason}");
+        }
+        // OpenZFS stores encryption metadata where the third copy of a block would go.
+        let copies = self.zfs.as_ref().and_then(|zfs| zfs.copies).unwrap_or(1);
+        if self.filesystem == Filesystem::Zfs && copies > 2 {
+            bail!("'disk-setup.zfs.copies' must be at most 2 with disk encryption");
+        }
+
+        Ok(())
+    }
+
     /// Returns the concrete disk selection made in the setup.
     pub fn disk_selection(&self) -> Result<DiskSelection> {
         if self.disk_list.is_empty() && self.filter.is_empty() {
@@ -1039,6 +1062,44 @@ impl DiskSetup {
     }
 }
 
+#[cfg_attr(feature = "api-types", api)]
+#[derive(Clone, Deserialize, Serialize, PartialEq)]
+#[serde(rename_all = "kebab-case", deny_unknown_fields)]
+/// Full-disk encryption of the system disks, LUKS2 for ext4, xfs and Btrfs, native encryption for
+/// ZFS.
+pub struct DiskEncryption {
+    /// Passphrase that unlocks the system at boot.
+    pub passphrase: String,
+}
+
+impl DiskEncryption {
+    /// Checks a passphrase against what can be set up and entered at the boot prompt. The error
+    /// completes a sentence about the passphrase, like "must not contain control characters".
+    pub fn check_passphrase(passphrase: &str) -> Result<(), &'static str> {
+        // The minimum of the root password, which also covers the 8 bytes that ZFS requires.
+        if passphrase.chars().count() < 8 {
+            return Err("must be at least 8 characters long");
+        }
+        // Neither can be typed at the boot prompt, and OpenZFS stops reading a key file at a newline.
+        if passphrase.chars().any(char::is_control) {
+            return Err("must not contain control characters");
+        }
+        // cryptsetup's own prompt, as used for unlocking from a rescue system, reads at most 512
+        if passphrase.len() > 512 {
+            return Err("must not be longer than 512 bytes");
+        }
+        Ok(())
+    }
+}
+
+impl fmt::Debug for DiskEncryption {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("DiskEncryption")
+            .field("passphrase", &"<redacted>")
+            .finish()
+    }
+}
+
 #[cfg_attr(feature = "api-types", api)]
 #[derive(Copy, Clone, Deserialize, Serialize, Debug, PartialEq)]
 #[serde(rename_all = "lowercase", deny_unknown_fields)]
@@ -1637,7 +1698,7 @@ mod tests {
 
         assert_eq!(
             fetch::AnswerFetchDataSchema::default().version(),
-            Some((1, 1))
+            Some((1, 2))
         );
         assert_eq!(schema("1.0").version(), Some((1, 0)));
         assert_eq!(schema("2.10").version(), Some((2, 10)));
@@ -1678,6 +1739,18 @@ mod tests {
         "#;
         let answer: AutoInstallerConfig = toml::from_str(&with_network(bond)).unwrap();
         assert_eq!(answer.required_fetch_schema_version(), (1, 1));
+
+        let encryption = r#"
+            [disk-setup.encryption]
+            passphrase = "secret-passphrase"
+        "#;
+        let answer: AutoInstallerConfig =
+            toml::from_str(&format!("{MINIMAL_ANSWER}{encryption}")).unwrap();
+        assert_eq!(answer.required_fetch_schema_version(), (1, 2));
+
+        let answer: AutoInstallerConfig =
+            toml::from_str(&format!("{}{encryption}", with_network(&vlan))).unwrap();
+        assert_eq!(answer.required_fetch_schema_version(), (1, 2));
     }
 
     fn disks(n: usize) -> Vec<String> {
@@ -1696,6 +1769,7 @@ mod tests {
             }),
             lvm: None,
             btrfs: None,
+            encryption: None,
         }
     }
 
@@ -1711,6 +1785,7 @@ mod tests {
                 raid: Some(raid),
                 ..Default::default()
             }),
+            encryption: None,
         }
     }
 
@@ -1774,10 +1849,72 @@ mod tests {
             }),
             lvm: None,
             btrfs: None,
+            encryption: None,
         };
         assert!(setup.filesystem_details().is_ok());
     }
 
+    #[test]
+    fn encryption_passphrase_rules() {
+        let check = |filesystem, passphrase: &str| {
+            let mut setup = zfs(ZfsRaidLevel::Raid0, 1);
+            setup.filesystem = filesystem;
+            setup.encryption = Some(DiskEncryption {
+                passphrase: passphrase.to_string(),
+            });
+            setup.verify_encryption().map_err(|err| err.to_string())
+        };
+
+        assert!(zfs(ZfsRaidLevel::Raid0, 1).verify_encryption().is_ok());
+        assert!(check(Filesystem::Ext4, "password").is_ok());
+        assert!(check(Filesystem::Zfs, &"\u{e4}".repeat(8)).is_ok());
+        assert!(check(Filesystem::Zfs, &"x".repeat(512)).is_ok());
+
+        for filesystem in [Filesystem::Ext4, Filesystem::Zfs] {
+            for short in ["", "passwor", "\u{e4}\u{e4}\u{e4}\u{e4}\u{e4}\u{e4}\u{e4}"] {
+                let err = check(filesystem, short).unwrap_err();
+                assert!(err.contains("at least 8 characters"), "{err}");
+            }
+        }
+        for control in ["\n", "\t", "\0", "\u{7f}", "\u{85}"] {
+            let err = check(Filesystem::Btrfs, &format!("pass{control}word")).unwrap_err();
+            assert!(err.contains("control characters"));
+        }
+        assert!(
+            check(Filesystem::Zfs, &"x".repeat(513))
+                .unwrap_err()
+                .contains("512 bytes")
+        );
+        assert!(check(Filesystem::Ext4, &"x".repeat(512)).is_ok());
+        assert!(
+            check(Filesystem::Ext4, &"x".repeat(513))
+                .unwrap_err()
+                .contains("512 bytes")
+        );
+
+        let copies = |filesystem, copies| {
+            let mut setup = zfs(ZfsRaidLevel::Raid0, 1);
+            setup.filesystem = filesystem;
+            setup.zfs.as_mut().unwrap().copies = Some(copies);
+            setup.encryption = Some(DiskEncryption {
+                passphrase: "password".to_string(),
+            });
+            setup.verify_encryption().map_err(|err| err.to_string())
+        };
+        assert!(copies(Filesystem::Zfs, 2).is_ok());
+        assert!(
+            copies(Filesystem::Zfs, 3)
+                .unwrap_err()
+                .contains("at most 2")
+        );
+        assert!(copies(Filesystem::Ext4, 3).is_ok());
+
+        let encryption = DiskEncryption {
+            passphrase: "secret".to_string(),
+        };
+        assert!(!format!("{encryption:?}").contains("secret"));
+    }
+
     #[test]
     fn network_bond_requires_at_least_two_members() {
         let mut bond = NetworkBondOptions::default();
diff --git a/proxmox-installer-types/src/lib.rs b/proxmox-installer-types/src/lib.rs
index df1f7944..e0822f6d 100644
--- a/proxmox-installer-types/src/lib.rs
+++ b/proxmox-installer-types/src/lib.rs
@@ -32,6 +32,28 @@ pub enum BootType {
     Efi,
 }
 
+#[cfg_attr(feature = "api-types", api)]
+#[derive(Copy, Clone, Debug, Eq, Deserialize, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+/// How the system disks of an installation are encrypted.
+pub enum EncryptionMode {
+    /// LUKS2, for ext4, xfs and Btrfs installations.
+    Luks,
+    /// Native ZFS encryption, for ZFS installations.
+    ZfsNative,
+}
+
+impl EncryptionMode {
+    /// Returns how an installation with the given filesystem gets encrypted.
+    pub fn for_filesystem(filesystem: answer::FilesystemType) -> Self {
+        use answer::FilesystemType::*;
+        match filesystem {
+            Ext4 | Xfs | Btrfs(_) => Self::Luks,
+            Zfs(_) => Self::ZfsNative,
+        }
+    }
+}
+
 /// Uses a BTreeMap to have the keys sorted
 pub type UdevProperties = BTreeMap<String, String>;
 
diff --git a/proxmox-installer-types/src/post_hook.rs b/proxmox-installer-types/src/post_hook.rs
index 8047a7f8..325ca830 100644
--- a/proxmox-installer-types/src/post_hook.rs
+++ b/proxmox-installer-types/src/post_hook.rs
@@ -7,7 +7,7 @@ use proxmox_network_types::{MacAddress, ip_address::Cidr};
 use proxmox_schema::api;
 
 use crate::{
-    BootType, IsoInfo, ProxmoxProduct, SystemDMI, UdevProperties,
+    BootType, EncryptionMode, IsoInfo, ProxmoxProduct, SystemDMI, UdevProperties,
     answer::{FilesystemType, RebootMode},
 };
 
@@ -197,6 +197,9 @@ pub struct PostHookInfo {
     pub dmi: SystemDMI,
     /// Filesystem used for boot disk(s)
     pub filesystem: FilesystemType,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    /// Encryption of the boot disk(s), if any.
+    pub encryption: Option<EncryptionMode>,
     /// Fully qualified domain name of the installed system
     pub fqdn: String,
     /// Unique systemd-id128 identifier of the installed system (128-bit, 16 bytes)
-- 
2.47.3





  reply	other threads:[~2026-11-17 23:43 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-17 23:42 [PATCH proxmox/installer/docs 0/8] installer: add full-disk encryption of the system disks Thomas Lamprecht
2026-11-17 23:42 ` Thomas Lamprecht [this message]
2026-11-17 23:42 ` [PATCH installer 1/5] install: encrypt the system disks with LUKS2 or native ZFS encryption Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 2/5] auto: support full-disk encryption in answer files Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 3/5] chroot enter: unlock the LUKS containers of an encrypted installation Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 4/5] ui: offer full-disk encryption in the graphical and terminal installer Thomas Lamprecht
2026-11-17 23:42 ` [PATCH installer 5/5] assistant: keep the disk passphrase out of prepared ISOs Thomas Lamprecht
2026-11-17 23:42 ` [PATCH docs 1/2] installation: describe full-disk encryption Thomas Lamprecht
2026-11-17 23:42 ` [PATCH docs 2/2] local-zfs: update the limitations of native encryption Thomas Lamprecht

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261117234330.801935-2-t.lamprecht@proxmox.com \
    --to=t.lamprecht@proxmox.com \
    --cc=pve-devel@lists.proxmox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal