From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id B8FED1FF0C0 for ; Wed, 18 Nov 2026 00:43:57 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 9787A21668; Wed, 18 Nov 2026 00:43:46 +0100 (CET) From: Thomas Lamprecht 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 Message-ID: <20261117234330.801935-2-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261117234330.801935-1-t.lamprecht@proxmox.com> References: <20261117234330.801935-1-t.lamprecht@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794959018198 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.195 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: FAFNLQNB5IVEP23DY262OREXJA7DOZLY X-Message-ID-Hash: FAFNLQNB5IVEP23DY262OREXJA7DOZLY X-MailFrom: t.lamprecht@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 --- 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, + #[serde(skip_serializing_if = "Option::is_none")] + /// Full-disk encryption of the system disks. + pub encryption: Option, } 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 { 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", &"") + .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 { @@ -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; 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, /// 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