diff --git a/Guide/src/dev_guide/snapshot_format.md b/Guide/src/dev_guide/snapshot_format.md index 5d6c4d4d971..9ee923237c6 100644 --- a/Guide/src/dev_guide/snapshot_format.md +++ b/Guide/src/dev_guide/snapshot_format.md @@ -31,17 +31,20 @@ profile record), and a host-driven standard-machine snapshot has no machine contract. Tiered microVM snapshots record capture tier, clone/resume policy, and consumed configuration sections. -The default format is a local machine-state contract, not an authenticated -container. Every snapshot receives the same regular-file, no-follow/no-reparse, -bounded decoding, exact-length, inventory, and machine-contract validation, -but the on-disk format does not authenticate same-length payload changes. -By default, paired capture records SHA-256 and exact length for `scratch.img`, -because guest RAM and a mounted writable filesystem must be restored as one -exact pair. The format also permits an explicit `generation` identity for all -bound sandbox blocks. Generation identity is a caller-authenticated immutable -storage version, not a byte digest; OpenVMM validates role, size, geometry, and -the shared generation without scanning block contents. Export or transport -layers must provide broader integrity and authentication outside this format. +The format is a local machine-state contract, not an authenticated container. +Every snapshot receives the same regular-file, no-follow/no-reparse, bounded +decoding, exact-length, inventory, and machine-contract validation, but the +on-disk format does not authenticate same-length payload changes. A +`workload-start` or `instance-checkpoint` snapshot binds its sandbox blocks, +the read-only layers and the paired `scratch.img`, which guest RAM and a +mounted writable filesystem must restore as one exact pair, to one +`generation` identity: a caller-authenticated immutable storage generation, +not a byte digest. Neither capture nor restore reads a block to identify it: +OpenVMM validates role, size, geometry, and the shared generation, and a +restore requires the generation that the snapshot recorded. Restore rejects +the `sha256` block identity of earlier releases, whose snapshots must be +recaptured. Export or transport layers must provide broader integrity and +authentication outside this format. The optional microVM network contract stores the SHA-256 digest of its bound egress policy in encoding version 1, which covers the static IPv4 and IPv6 @@ -98,10 +101,10 @@ The microVM block contract records every fixed role, access mode, geometry, identity kind, identity, and paired-scratch restore mode. A paired capture copies the exact opened writable scratch handle into the same staging directory after device queues drain and publishes it atomically with VM state. -`sha256` identity verifies bytes before publication and restore. `generation` -identity instead requires every bound block to carry the same nonzero -caller-authenticated storage generation and performs structural and exact-size -validation without whole-file rehashing. +Every bound block carries the same nonzero caller-authenticated storage +generation, and publication and restore check `scratch.img` structurally and +by exact size, without reading it to verify its content. A platform capture +binds no block, so its read-only layers are `unbound`. Paired scratch defaults to `private-copy`, which preserves existing behavior and may use a reflink or sparse copy. `copy-on-write` requires a filesystem diff --git a/Guide/src/reference/openvmm/management/cli.md b/Guide/src/reference/openvmm/management/cli.md index 3acb7eb7014..1dac32f8366 100644 --- a/Guide/src/reference/openvmm/management/cli.md +++ b/Guide/src/reference/openvmm/management/cli.md @@ -495,14 +495,17 @@ describes the source definitions. a snapshot without a tier. For sandbox-block snapshots, restore repeats the read-only `distro` - `--microvm-sandbox-block` argument. Its role, access, geometry, and SHA-256 - must match the manifest, with two exceptions for a platform snapshot: its - `distro` layer is unbound, and it keeps the captured capacity over an image - that may be shorter. Such an image must have the + `--microvm-sandbox-block` argument. Its role, access, and geometry must + match the manifest, and a `workload-start` or `instance-checkpoint` + snapshot, which binds its blocks to a storage generation, also requires that + generation through `--restore-generation-id`; OpenVMM never reads a block to + identify it. A platform snapshot has two exceptions: its `distro` layer is + unbound, and it keeps the captured capacity over an image that may be + shorter. Such an image must have the captured logical and physical block sizes, reads past its end return zeros, and OpenVMM never resizes, pads, or writes it; a longer image is rejected. A paired snapshot supplies scratch internally from - a verified process-private copy of `scratch.img`; passing another scratch is + a process-private copy of `scratch.img`; passing another scratch is rejected. A fresh-scratch snapshot instead requires a writable scratch argument with matching geometry, or `--restore-absent-scratch`. @@ -591,6 +594,14 @@ describes the source definitions. clone from its host, and the guest of a snapshot without a tier from the restore packet, which carries them, and whose restore gates host input until the guest acknowledges that it applied them. +* `--restore-generation-id <32-HEX-DIGITS>`: State the immutable storage + generation of this restore's sandbox blocks. A `workload-start` or + `instance-checkpoint` snapshot binds its read-only layers and paired scratch + to the generation that its capture recorded, and its restore requires the + same one: OpenVMM rejects a missing or different generation before it + materializes scratch or starts a vCPU. A platform snapshot binds no block, so + its restore checks no generation. OpenVMM rejects the option for a cold boot + and for a snapshot without sandbox blocks. * `--restore-gate-timeout-ms `: Bound microVM guest repair and gate acknowledgement after restore. The default is 60000 milliseconds. * `--cpu-profile `: Select the microVM's pinned CPU profile, `auto` @@ -619,12 +630,13 @@ describes the source definitions. * `--snapshot-tier `: Required for snapshot capture with sandbox blocks. Choose `platform`, `workload-start`, or `instance-checkpoint`. The first two are reusable clone policies; instance checkpoints use single-use resume policy. -* `--snapshot-block-identity `: Select `sha256` (the default) or - `generation`. SHA-256 computes and verifies every bound block. Generation - mode requires `--snapshot-generation-id <32-HEX-DIGITS>` and records that - caller-authenticated immutable storage generation instead of scanning block - bytes. The caller must keep the generation bound to the exact immutable - artifacts supplied at restore. +* `--snapshot-generation-id <32-HEX-DIGITS>`: Supply the immutable storage + generation of the capture's sandbox blocks. A `workload-start` or + `instance-checkpoint` capture requires it and records it as the identity of + every read-only layer and of the paired scratch, instead of reading them; a + restore must state it again with `--restore-generation-id`. A platform + capture binds no block and records none. The storage owner must keep the + generation bound to the exact immutable artifacts supplied at restore. * `--snapshot-scratch-restore-mode `: Record `private-copy`, `copy-on-write`, or `direct-claimed` for paired scratch. Private copy is the default and may fall back to sparse copying. Copy-on-write is available only @@ -635,16 +647,17 @@ describes the source definitions. A committed snapshot contains `manifest.bin`, `state.bin`, `memory.bin`, and optionally the manifest-declared `scratch.img`. Restore rejects unknown files, -symlinks, malformed or oversized data, length or applicable scratch-digest -mismatches, and incompatible machine contracts before starting a vCPU. +symlinks, malformed or oversized data, length mismatches, a missing or +different storage generation, the `sha256` block identity of earlier releases, +and incompatible machine contracts before starting a vCPU. `memory.bin` uses a private writable copy-on-write mapping. Paired scratch uses the materialization policy recorded at capture; clone-policy snapshots never attach the source artifact writable, while direct attachment requires an atomic single-use resume claim. -Versions 3 through 6 do not embed or validate checksums for `state.bin` or `memory.bin`; -legacy version 2 checksum fields are accepted without re-hashing their -payloads. This format does not detect same-length payload changes, +The format embeds no checksums of `state.bin`, `memory.bin`, `scratch.img`, or +the read-only layers, and OpenVMM never reads them to verify their contents. +This format does not detect same-length payload changes, authenticate, or encrypt a snapshot. Treat all three artifacts as sensitive guest state and protect the directory with host access controls. * `--memory `: Configure guest RAM. Defaults to `size=1G`. diff --git a/Guide/src/user_guide/openvmm/snapshots.md b/Guide/src/user_guide/openvmm/snapshots.md index eb92b1c6dda..731cbd54d3a 100644 --- a/Guide/src/user_guide/openvmm/snapshots.md +++ b/Guide/src/user_guide/openvmm/snapshots.md @@ -42,14 +42,16 @@ with sandbox blocks additionally requires workload-start snapshots are reusable clones; instance checkpoints are single-use resumes. -Sandbox-block capture defaults to whole-file SHA-256 identity and private -scratch copying. Storage owners may opt into -`--snapshot-block-identity generation --snapshot-generation-id <32-HEX-DIGITS>` -when an authenticated immutable generation already binds the supplied files. -This avoids capture- and restore-time block scans; it does not authenticate -bytes by itself. `--snapshot-scratch-restore-mode` records `private-copy`, -reflink-only `copy-on-write` for workload-start clones, or `direct-claimed` -for instance checkpoints. +A workload-start or instance-checkpoint capture binds its read-only layers and +paired scratch to the storage generation that +`--snapshot-generation-id <32-HEX-DIGITS>` supplies, and each restore of the +snapshot states that generation again with `--restore-generation-id`. OpenVMM +never reads a block to identify it, and the generation does not authenticate +bytes by itself: the storage owner must keep it immutable and bound to the +exact files. A platform capture binds no block and needs no generation. +Paired scratch defaults to private copying; `--snapshot-scratch-restore-mode` +records `private-copy`, reflink-only `copy-on-write` for workload-start clones, +or `direct-claimed` for instance checkpoints. ```admonish warning Automatically allocated microVM RAM and the snapshot destination are on the @@ -197,8 +199,10 @@ repair must not wait for a virtio-fs reply. The acknowledgement is bounded by host can connect while input is gated, but OpenVMM reads its authentication only after the release, so its `--microvm-control-auth-timeout-ms` deadline starts over when the gate releases. Platform manifests -leave read-only layer identities unbound, while later tiers require exact image -identities. A platform restore also presents the captured capacity of its +leave read-only layer identities unbound, while later tiers bind every block +to the storage generation of their capture, which the restore must state with +`--restore-generation-id`. A platform restore also presents the captured +capacity of its `distro` block before any vCPU runs, so one platform snapshot serves images of any length up to that capacity. An image with the captured logical and physical block sizes may be shorter, and reads past its end, including the tail @@ -325,16 +329,16 @@ target. This is not a post-readiness hotplug API and cannot add VPs absent from the saved topology. ```admonish warning -Snapshots do not contain or validate embedded checksums for -`state.bin` or `memory.bin`. Restore still requires regular files, bounded -manifest and state decoding, exact artifact lengths, and a compatible machine -contract, but same-length payload changes are not detected. Paired `scratch.img` always -has an exact length and uses either the default SHA-256 identity or an explicit -caller-authenticated storage generation. Generation mode avoids reading the -file solely for verification and therefore relies on the storage owner to keep -that generation immutable and correctly bound. Protect snapshot directories -with host access controls. Integrity or authentication for export and -transport must be supplied outside the default snapshot format. +Snapshots do not contain or validate checksums of `state.bin`, `memory.bin`, +`scratch.img`, or the read-only layers. Restore still requires regular files, +bounded manifest and state decoding, exact artifact and block lengths, and a +compatible machine contract, but same-length payload changes are not detected. +The layers and paired `scratch.img` that a snapshot binds share one +caller-authenticated storage generation, which OpenVMM never reads a block to +verify, so it relies on the storage owner to keep that generation immutable and +correctly bound. Protect snapshot directories with host access controls. +Integrity or authentication for export and transport must be supplied outside +the snapshot format. ``` ```admonish note diff --git a/openvmm/openvmm_entry/src/cli_args/microvm.rs b/openvmm/openvmm_entry/src/cli_args/microvm.rs index d2f549719ce..57ee6d6a840 100644 --- a/openvmm/openvmm_entry/src/cli_args/microvm.rs +++ b/openvmm/openvmm_entry/src/cli_args/microvm.rs @@ -155,16 +155,6 @@ pub enum SnapshotTierCli { InstanceCheckpoint, } -/// Identity policy for sandbox blocks captured in a microVM snapshot. -#[derive(Debug, Copy, Clone, Default, ValueEnum, PartialEq, Eq)] -pub enum SnapshotBlockIdentityCli { - /// Compute and verify whole-file SHA-256 identities. - #[default] - Sha256, - /// Trust the caller-supplied immutable storage generation. - Generation, -} - /// Restore-time materialization policy for paired scratch. #[derive(Debug, Copy, Clone, Default, ValueEnum, PartialEq, Eq)] pub enum SnapshotScratchRestoreModeCli { @@ -193,7 +183,7 @@ impl SnapshotScratchRestoreModeCli { } } -/// Caller-supplied immutable storage generation. +/// Caller-supplied immutable storage generation of microVM sandbox blocks. #[derive(Debug, Copy, Clone, PartialEq, Eq)] pub struct SnapshotGenerationIdCli(pub(crate) [u8; 16]); @@ -243,6 +233,13 @@ impl SnapshotTierCli { pub(crate) fn requires_paired_scratch(self) -> bool { !matches!(self, Self::Platform) } + + /// Returns whether a snapshot of this tier binds its sandbox blocks to a + /// storage generation: every tier but the platform tier, whose layers are + /// unbound and whose scratch is fresh. + pub(crate) fn binds_blocks(self) -> bool { + !matches!(self, Self::Platform) + } } impl From for MicrovmNetworkProfile { @@ -303,6 +300,14 @@ pub struct MicrovmCli { #[clap(long, requires = "restore_snapshot")] pub restore_network_policy: bool, + /// Immutable storage generation of the sandbox blocks of this restore. + /// + /// Required to restore a `workload-start` or `instance-checkpoint` + /// snapshot, whose recorded generation it must match. A `platform` + /// snapshot binds no block and checks none. + #[clap(long, value_name = "HEX", requires = "restore_snapshot")] + pub restore_generation_id: Option, + /// Maximum time allowed for a microVM guest to complete post-restore repair. #[clap(long, value_name = "MILLISECONDS", default_value_t = 60000)] pub restore_gate_timeout_ms: u64, @@ -324,19 +329,13 @@ pub struct MicrovmCli { )] pub snapshot_tier: Option, - /// Sandbox-block identity policy for this capture. + /// Immutable storage generation of the sandbox blocks of this capture. /// - /// `sha256` is the default. `generation` avoids whole-file hashing and - /// requires an immutable generation supplied by the storage owner. - #[clap( - long, - value_enum, - value_name = "MODE", - requires = "snapshot_destination" - )] - pub snapshot_block_identity: Option, - - /// Immutable storage generation used by `--snapshot-block-identity generation`. + /// Required for a `workload-start` or `instance-checkpoint` capture, + /// which binds its read-only layers and paired scratch to the generation. + /// A `platform` capture binds no block and records none. OpenVMM never + /// reads a block to identify it, so the storage owner must keep the + /// generation bound to the exact files. #[clap(long, value_name = "HEX", requires = "snapshot_destination")] pub snapshot_generation_id: Option, @@ -810,13 +809,13 @@ impl Options { && self.microvm.restore_memory.is_none() && !self.microvm.restore_absent_scratch && !self.microvm.restore_network_policy + && self.microvm.restore_generation_id.is_none() && self.microvm.memory_capacity.is_none() - && self.microvm.snapshot_block_identity.is_none() && self.microvm.snapshot_generation_id.is_none() && self.microvm.snapshot_scratch_restore_mode.is_none() && self.microvm.microvm_control_console.is_none() && !self.microvm.microvm_control_auth_stdin, - "--network-profile, --net-tap, --mount, --mount-aggregate, --microvm-sandbox-block, --microvm-workload-identity, --microvm-lifecycle, --microvm-control-console, --microvm-control-auth-stdin, --restore-processors, --restore-memory, --restore-absent-scratch, --restore-network-policy, --memory-capacity, snapshot block policy, and microVM network policy require a microVM machine" + "--network-profile, --net-tap, --mount, --mount-aggregate, --microvm-sandbox-block, --microvm-workload-identity, --microvm-lifecycle, --microvm-control-console, --microvm-control-auth-stdin, --restore-processors, --restore-memory, --restore-absent-scratch, --restore-network-policy, --restore-generation-id, --memory-capacity, snapshot block policy, and microVM network policy require a microVM machine" ); return Ok(()); } @@ -873,26 +872,20 @@ impl Options { != self.microvm.microvm_sandbox_block.is_empty(), "--snapshot-tier is required exactly for microVM snapshot capture with sandbox blocks" ); - let identity = self - .microvm - .snapshot_block_identity - .unwrap_or(SnapshotBlockIdentityCli::Sha256); anyhow::ensure!( !self.microvm.microvm_sandbox_block.is_empty() - || self.microvm.snapshot_block_identity.is_none(), - "--snapshot-block-identity requires microVM sandbox blocks" - ); - anyhow::ensure!( - matches!( - (identity, self.microvm.snapshot_generation_id), - (SnapshotBlockIdentityCli::Sha256, None) - | ( - SnapshotBlockIdentityCli::Generation, - Some(SnapshotGenerationIdCli(_)) - ) - ), - "--snapshot-generation-id is required exactly for --snapshot-block-identity generation" + || self.microvm.snapshot_generation_id.is_none(), + "--snapshot-generation-id requires microVM sandbox blocks" ); + if let Some(tier) = self.microvm.snapshot_tier + && tier.binds_blocks() + { + anyhow::ensure!( + self.microvm.snapshot_generation_id.is_some(), + "--snapshot-tier {} binds the sandbox blocks and requires --snapshot-generation-id", + tier.manifest_name() + ); + } if let Some(mode) = self.microvm.snapshot_scratch_restore_mode { let tier = self .microvm @@ -946,6 +939,10 @@ impl Options { self.restore_snapshot.is_some() || !self.microvm.restore_network_policy, "--restore-network-policy requires --restore-snapshot" ); + anyhow::ensure!( + self.restore_snapshot.is_some() || self.microvm.restore_generation_id.is_none(), + "--restore-generation-id requires --restore-snapshot" + ); if self.restore_snapshot.is_some() { anyhow::ensure!( self.microvm.microvm_workload_identity.is_none(), @@ -1997,7 +1994,7 @@ mod tests { #[test] fn test_microvm_snapshot_tier_is_explicit() { for tier in ["platform", "workload-start", "instance-checkpoint"] { - let options = Options::try_parse_from([ + let mut args = vec![ "openvmm", "--machine", "microvm", @@ -2009,8 +2006,14 @@ mod tests { "distro:mem:1M,ro", "--microvm-sandbox-block", "scratch:mem:1M", - ]) - .unwrap(); + ]; + if tier != "platform" { + args.extend([ + "--snapshot-generation-id", + "00112233445566778899aabbccddeeff", + ]); + } + let options = Options::try_parse_from(args).unwrap(); assert_eq!(options.microvm.restore_gate_timeout_ms, 60_000); options.validate_microvm_options().unwrap(); } @@ -2067,27 +2070,43 @@ mod tests { #[cfg(guest_arch = "x86_64")] #[test] - fn test_microvm_snapshot_identity_and_scratch_restore_modes_are_explicit() { - let generation = Options::try_parse_from([ - "openvmm", - "--machine", - "microvm", - "--snapshot-destination", - "snapshot", - "--snapshot-tier", + fn test_microvm_snapshot_generation_and_scratch_restore_modes_are_explicit() { + const GENERATION: &str = "00112233445566778899aabbccddeeff"; + fn capture(tier: &'static str, extra: &[&'static str]) -> Vec<&'static str> { + let mut args = vec![ + "openvmm", + "--machine", + "microvm", + "--snapshot-destination", + "snapshot", + "--snapshot-tier", + tier, + "--microvm-sandbox-block", + "distro:mem:1M,ro", + "--microvm-sandbox-block", + "scratch:mem:1M", + ]; + args.extend_from_slice(extra); + args + } + + let generation = Options::try_parse_from(capture( "workload-start", - "--snapshot-block-identity", - "generation", - "--snapshot-generation-id", - "00112233445566778899aabbccddeeff", - "--snapshot-scratch-restore-mode", - "copy-on-write", - "--microvm-sandbox-block", - "distro:mem:1M,ro", - "--microvm-sandbox-block", - "scratch:mem:1M", - ]) + &[ + "--snapshot-generation-id", + GENERATION, + "--snapshot-scratch-restore-mode", + "copy-on-write", + ], + )) .unwrap(); + assert_eq!( + generation.microvm.snapshot_generation_id, + Some(SnapshotGenerationIdCli([ + 0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, + 0xee, 0xff, + ])) + ); #[cfg(target_os = "linux")] generation.validate_microvm_options().unwrap(); #[cfg(not(target_os = "linux"))] @@ -2099,59 +2118,156 @@ mod tests { .contains("copy-on-write is unsupported on this platform") ); - let missing_generation = Options::try_parse_from([ + // A tier that binds the blocks records a storage generation, which only + // the caller can supply: OpenVMM never reads a block to identify it. + for tier in ["workload-start", "instance-checkpoint"] { + let missing_generation = Options::try_parse_from(capture(tier, &[])).unwrap(); + assert_eq!( + missing_generation + .validate_microvm_options() + .unwrap_err() + .to_string(), + format!( + "--snapshot-tier {tier} binds the sandbox blocks and requires --snapshot-generation-id" + ) + ); + } + // A platform capture binds no block, so it needs no generation, and + // records none when the caller supplies one anyway. + for extra in [&[][..], &["--snapshot-generation-id", GENERATION][..]] { + Options::try_parse_from(capture("platform", extra)) + .unwrap() + .validate_microvm_options() + .unwrap(); + } + // A blockless capture has no block to bind. + let blockless = Options::try_parse_from([ "openvmm", "--machine", "microvm", "--snapshot-destination", "snapshot", - "--snapshot-tier", - "workload-start", - "--snapshot-block-identity", - "generation", - "--microvm-sandbox-block", - "distro:mem:1M,ro", - "--microvm-sandbox-block", - "scratch:mem:1M", + "--snapshot-generation-id", + GENERATION, ]) .unwrap(); - assert!(missing_generation.validate_microvm_options().is_err()); + assert_eq!( + blockless + .validate_microvm_options() + .unwrap_err() + .to_string(), + "--snapshot-generation-id requires microVM sandbox blocks" + ); + // Neither a block identity other than the generation, nor a malformed + // or zero generation, parses. + for extra in [ + &["--snapshot-block-identity", "sha256"][..], + &["--snapshot-generation-id", "00112233445566778899aabbccddee"], + &[ + "--snapshot-generation-id", + "00112233445566778899aabbccddeeffaa", + ], + &[ + "--snapshot-generation-id", + "0011223344556677889g9aabbccddeef", + ], + &[ + "--snapshot-generation-id", + "00000000000000000000000000000000", + ], + ] { + assert!( + Options::try_parse_from(capture("workload-start", extra)).is_err(), + "{extra:?}" + ); + } + + let direct_clone = Options::try_parse_from(capture( + "workload-start", + &[ + "--snapshot-generation-id", + GENERATION, + "--snapshot-scratch-restore-mode", + "direct-claimed", + ], + )) + .unwrap(); + assert!(direct_clone.validate_microvm_options().is_err()); + + let resume = Options::try_parse_from(capture( + "instance-checkpoint", + &[ + "--snapshot-generation-id", + GENERATION, + "--snapshot-scratch-restore-mode", + "direct-claimed", + ], + )) + .unwrap(); + resume.validate_microvm_options().unwrap(); + } - let direct_clone = Options::try_parse_from([ + #[cfg(guest_arch = "x86_64")] + #[test] + fn test_microvm_restore_generation_id_requires_a_microvm_restore() { + const GENERATION: &str = "00112233445566778899aabbccddeeff"; + let restore = Options::try_parse_from([ "openvmm", "--machine", "microvm", - "--snapshot-destination", + "--restore-snapshot", "snapshot", - "--snapshot-tier", - "workload-start", - "--snapshot-scratch-restore-mode", - "direct-claimed", - "--microvm-sandbox-block", - "distro:mem:1M,ro", - "--microvm-sandbox-block", - "scratch:mem:1M", + "--restore-generation-id", + GENERATION, ]) .unwrap(); - assert!(direct_clone.validate_microvm_options().is_err()); + restore.validate_microvm_options().unwrap(); + assert_eq!( + restore.microvm.restore_generation_id, + GENERATION.parse::().ok() + ); - let resume = Options::try_parse_from([ + // A cold boot has no snapshot whose generation to check. + assert!( + Options::try_parse_from([ + "openvmm", + "--machine", + "microvm", + "--restore-generation-id", + GENERATION, + ]) + .is_err() + ); + // Clap accepts it when --snapshot-destination, which conflicts with + // --restore-snapshot, lifts the requirement, so the validation refuses + // it. + let cold_boot = Options::try_parse_from([ "openvmm", "--machine", "microvm", "--snapshot-destination", "snapshot", - "--snapshot-tier", - "instance-checkpoint", - "--snapshot-scratch-restore-mode", - "direct-claimed", - "--microvm-sandbox-block", - "distro:mem:1M,ro", - "--microvm-sandbox-block", - "scratch:mem:1M", + "--restore-generation-id", + GENERATION, ]) .unwrap(); - resume.validate_microvm_options().unwrap(); + assert_eq!( + cold_boot + .validate_microvm_options() + .unwrap_err() + .to_string(), + "--restore-generation-id requires --restore-snapshot" + ); + // Nor does a standard machine. + let standard = Options::try_parse_from([ + "openvmm", + "--restore-snapshot", + "snapshot", + "--restore-generation-id", + GENERATION, + ]) + .unwrap(); + assert!(standard.validate_microvm_options().is_err()); } #[test] diff --git a/openvmm/openvmm_entry/src/microvm/launch.rs b/openvmm/openvmm_entry/src/microvm/launch.rs index 2d48e361f82..554ec74592f 100644 --- a/openvmm/openvmm_entry/src/microvm/launch.rs +++ b/openvmm/openvmm_entry/src/microvm/launch.rs @@ -10,7 +10,6 @@ use super::restore::ExpectedRestoreContract; use super::validate_microvm_filesystem_private_storage; use crate::Options; use crate::cli_args::microvm::MachineProfileCli; -use crate::cli_args::microvm::SnapshotBlockIdentityCli; use crate::cli_args::microvm::SnapshotScratchRestoreModeCli; use crate::vm_controller::MicrovmController; use anyhow::Context; @@ -37,7 +36,6 @@ pub(crate) struct MicrovmLaunch { network: Option, filesystems: Vec, snapshot_destination: Option, - snapshot_block_identity: SnapshotBlockIdentityCli, snapshot_generation_id: Option<[u8; 16]>, snapshot_scratch_restore_mode: SnapshotScratchRestoreModeCli, snapshot_memory_file: Option, @@ -142,10 +140,6 @@ impl MicrovmLaunch { network: vm_config.microvm.network.clone(), filesystems: vm_config.microvm.filesystems.clone(), snapshot_destination, - snapshot_block_identity: opt - .microvm - .snapshot_block_identity - .unwrap_or(SnapshotBlockIdentityCli::Sha256), snapshot_generation_id: opt .microvm .snapshot_generation_id @@ -249,6 +243,9 @@ impl MicrovmLaunch { &self.resources.sandbox_block_sources, scratch_policy, saved_blocks, + opt.microvm + .restore_generation_id + .map(|generation| generation.0), )?; let resources = &self.resources; Ok(Some(( @@ -304,7 +301,6 @@ impl MicrovmLaunch { snapshot_requests, snapshot_destination: self.snapshot_destination, snapshot_tier: opt.microvm.snapshot_tier, - snapshot_block_identity: self.snapshot_block_identity, snapshot_generation_id: self.snapshot_generation_id, snapshot_scratch_restore_mode: self.snapshot_scratch_restore_mode, source_hypervisor, diff --git a/openvmm/openvmm_entry/src/microvm/restore.rs b/openvmm/openvmm_entry/src/microvm/restore.rs index 40001e4a089..f9ef23c349e 100644 --- a/openvmm/openvmm_entry/src/microvm/restore.rs +++ b/openvmm/openvmm_entry/src/microvm/restore.rs @@ -292,6 +292,12 @@ pub(crate) fn prepare_restore( "restore-time memory overrides are not allowed" ); opt.memory.size = Some(vmm_cli::MemorySize(restore_memory_size)); + validate_restore_generation( + &contract.microvm_sandbox_blocks, + opt.microvm + .restore_generation_id + .map(|generation| generation.0), + )?; let blocks = plan_sandbox_block_restore( &manifest.snapshot_tier, &contract.microvm_sandbox_blocks, @@ -477,6 +483,47 @@ fn validate_filesystem_aggregate_restore( Ok(()) } +/// Checks `generation`, the storage generation of a restore's sandbox blocks +/// that `--restore-generation-id` states, against `blocks`, the sandbox +/// blocks of the snapshot. +/// +/// A snapshot that binds its blocks, of the `workload-start` or +/// `instance-checkpoint` tier, requires the generation that it recorded, so +/// that a restore of other storage fails before it materializes the paired +/// scratch. A platform snapshot binds none and takes any generation, and a +/// snapshot without sandbox blocks takes none. +fn validate_restore_generation( + blocks: &[SnapshotMicrovmSandboxBlock], + generation: Option<[u8; 16]>, +) -> anyhow::Result<()> { + anyhow::ensure!( + !blocks.is_empty() || generation.is_none(), + "--restore-generation-id requires a snapshot with sandbox blocks" + ); + let Some(recorded) = blocks.iter().find(|block| { + block.identity_kind + == openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_GENERATION + }) else { + return Ok(()); + }; + let generation = generation.context( + "the snapshot binds its sandbox blocks to a storage generation; pass it with --restore-generation-id", + )?; + let hex = |bytes: &[u8]| { + bytes + .iter() + .map(|byte| format!("{byte:02x}")) + .collect::() + }; + anyhow::ensure!( + recorded.identity == generation, + "the snapshot binds its sandbox blocks to storage generation {}, not {}", + hex(&recorded.identity), + hex(&generation) + ); + Ok(()) +} + /// How a restore attaches the sandbox blocks of a snapshot. #[derive(Debug, Default, PartialEq, Eq)] struct SandboxBlockRestore<'a> { @@ -810,6 +857,53 @@ pub(crate) mod tests { } } + #[test] + fn only_a_snapshot_that_binds_its_blocks_checks_the_restore_generation() { + const GENERATION: [u8; 16] = [0x42; 16]; + let bound = |role: &str| SnapshotMicrovmSandboxBlock { + identity_kind: openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_GENERATION + .to_owned(), + identity: GENERATION.to_vec(), + ..sandbox_block(role, 1 << 20) + }; + let paired = [bound("distro"), bound("scratch")]; + validate_restore_generation(&paired, Some(GENERATION)).unwrap(); + assert_eq!( + validate_restore_generation(&paired, Some([0x24; 16])) + .unwrap_err() + .to_string(), + format!( + "the snapshot binds its sandbox blocks to storage generation {}, not {}", + "42".repeat(16), + "24".repeat(16) + ) + ); + assert_eq!( + validate_restore_generation(&paired, None) + .unwrap_err() + .to_string(), + "the snapshot binds its sandbox blocks to a storage generation; pass it with --restore-generation-id" + ); + + // A platform snapshot binds no block, so it takes any generation. + let platform = [ + sandbox_block("distro", 1 << 30), + sandbox_block("scratch", 1 << 20), + ]; + for generation in [None, Some(GENERATION)] { + validate_restore_generation(&platform, generation).unwrap(); + } + + // A snapshot without sandbox blocks has no block to bind. + validate_restore_generation(&[], None).unwrap(); + assert_eq!( + validate_restore_generation(&[], Some(GENERATION)) + .unwrap_err() + .to_string(), + "--restore-generation-id requires a snapshot with sandbox blocks" + ); + } + #[test] fn only_a_platform_restore_presents_the_distro_capacity() { use openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME; diff --git a/openvmm/openvmm_entry/src/storage_builder/microvm.rs b/openvmm/openvmm_entry/src/storage_builder/microvm.rs index 0cd67dbbc46..5053d3fd39a 100644 --- a/openvmm/openvmm_entry/src/storage_builder/microvm.rs +++ b/openvmm/openvmm_entry/src/storage_builder/microvm.rs @@ -7,7 +7,6 @@ use super::StorageBuilder; use super::VirtioBlkDisk; use crate::VmResources; use crate::cli_args::DiskCliKind; -use crate::cli_args::microvm::SnapshotBlockIdentityCli; use crate::disk_open; use anyhow::Context; use mesh::CellUpdater; @@ -111,11 +110,17 @@ fn zero_fill_disk( }) } +/// Returns the block contract that a capture records for `sources`. +/// +/// A capture whose tier binds the blocks passes their storage `generation`, +/// which it records as the identity of each read-only layer and of a paired +/// scratch. A platform capture passes none, and records its layers as +/// unbound. A fresh scratch has no identity. The capture never reads a block +/// to identify it: it only flushes a paired scratch, which publication copies. pub(crate) fn capture_snapshot_block_contract( sources: &[MicrovmSandboxBlockSource], scratch_policy: chipset_resources::microvm::MicrovmSnapshotScratchPolicy, - identity_mode: SnapshotBlockIdentityCli, - generation_id: Option<[u8; 16]>, + generation: Option<[u8; 16]>, scratch_restore_mode: &str, ) -> anyhow::Result> { sources @@ -134,29 +139,23 @@ pub(crate) fn capture_snapshot_block_contract( && scratch_policy == chipset_resources::microvm::MicrovmSnapshotScratchPolicy::Fresh { ("fresh", Vec::new(), String::new()) - } else { - let (identity_kind, identity) = match identity_mode { - SnapshotBlockIdentityCli::Sha256 => ( - openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_SHA256, - openvmm_helpers::snapshot::fs::file_sha256( - source.file()?, - source.length, - &format!("microVM {} block", source.role.as_str()), - )?, - ), - SnapshotBlockIdentityCli::Generation => ( - openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_GENERATION, - generation_id - .context("generation identity requires a snapshot generation ID")? - .to_vec(), - ), - }; + } else if let Some(generation) = generation { let artifact = if source.role == MicrovmSandboxBlockRole::Scratch { openvmm_helpers::snapshot::format::SCRATCH_FILE_NAME.to_owned() } else { String::new() }; - (identity_kind, identity, artifact) + ( + openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_GENERATION, + generation.to_vec(), + artifact, + ) + } else { + anyhow::ensure!( + source.read_only, + "microVM paired scratch requires a storage generation" + ); + ("unbound", Vec::new(), String::new()) }; Ok( openvmm_helpers::snapshot::microvm::SnapshotMicrovmSandboxBlock { @@ -182,10 +181,19 @@ pub(crate) fn capture_snapshot_block_contract( .collect() } +/// Returns the block contract that a restore of `sources` must match, which +/// the restore compares with `saved_blocks`, the snapshot's. +/// +/// The identity of each block that the snapshot binds is `generation`, the +/// storage generation of the restore's blocks, so that a snapshot that binds +/// other storage fails the comparison; a restore of such a snapshot requires +/// it. Unbound layers and fresh scratch have no identity. The restore never +/// reads a block to identify it. pub(crate) fn restore_snapshot_block_contract( sources: &[MicrovmSandboxBlockSource], scratch_policy: chipset_resources::microvm::MicrovmSnapshotScratchPolicy, saved_blocks: &[openvmm_helpers::snapshot::microvm::SnapshotMicrovmSandboxBlock], + generation: Option<[u8; 16]>, ) -> anyhow::Result> { sources .iter() @@ -200,16 +208,15 @@ pub(crate) fn restore_snapshot_block_contract( ) })?; let identity = match saved.identity_kind.as_str() { - openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_SHA256 => { - openvmm_helpers::snapshot::fs::file_sha256( - source.file()?, - source.length, - &format!("microVM {} block", source.role.as_str()), - )? - } - openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_GENERATION - | "unbound" - | "fresh" => saved.identity.clone(), + openvmm_helpers::snapshot::microvm::SNAPSHOT_BLOCK_IDENTITY_GENERATION => generation + .with_context(|| { + format!( + "snapshot binds the microVM {} block to a storage generation, which the restore requires", + source.role.as_str() + ) + })? + .to_vec(), + "unbound" | "fresh" => Vec::new(), other => anyhow::bail!( "snapshot microVM {} block identity kind '{other}' is unsupported", source.role.as_str() @@ -649,20 +656,133 @@ mod tests { sources, chipset_resources::microvm::MicrovmSnapshotScratchPolicy::Fresh, std::slice::from_ref(&saved), + None, ) .unwrap(), [saved] ); // A paired capture, which no restored microVM can take, fails instead - // of reading a file that it does not have. + // of flushing a file that it does not have. let err = capture_snapshot_block_contract( sources, chipset_resources::microvm::MicrovmSnapshotScratchPolicy::Paired, - SnapshotBlockIdentityCli::Sha256, - None, + Some([0x42; 16]), "", ) .unwrap_err(); assert_eq!(err.to_string(), "microVM scratch block has no file"); } + + /// Returns the source of a 1-MiB block of `role` with `file`. + fn block_source( + role: MicrovmSandboxBlockRole, + file: Option, + ) -> MicrovmSandboxBlockSource { + MicrovmSandboxBlockSource { + role, + read_only: role.is_read_only(), + length: MIB, + logical_block_size: 512, + physical_block_size: 4096, + file, + } + } + + #[test] + fn block_contracts_carry_the_storage_generation_without_reading_blocks() { + use chipset_resources::microvm::MicrovmSnapshotScratchPolicy; + const GENERATION: [u8; 16] = [0x42; 16]; + // The layer has no file, so neither contract can read it; the paired + // scratch has one only for its capture to flush. + let directory = tempfile::tempdir().unwrap(); + let scratch = std::fs::File::create_new(directory.path().join("scratch.img")).unwrap(); + scratch.set_len(MIB).unwrap(); + let capture_sources = [ + block_source(MicrovmSandboxBlockRole::Distro, None), + block_source(MicrovmSandboxBlockRole::Scratch, Some(scratch)), + ]; + + // A tier that binds the blocks records the generation as the identity + // of the layer and of the paired scratch. + let bound = capture_snapshot_block_contract( + &capture_sources, + MicrovmSnapshotScratchPolicy::Paired, + Some(GENERATION), + "private-copy", + ) + .unwrap(); + for block in &bound { + assert_eq!(block.identity_kind, "generation"); + assert_eq!(block.identity, GENERATION); + } + assert_eq!( + (bound[0].artifact.as_str(), bound[0].restore_mode.as_str()), + ("", "") + ); + assert_eq!( + (bound[1].artifact.as_str(), bound[1].restore_mode.as_str()), + ("scratch.img", "private-copy") + ); + + // The platform tier binds none: its layer is unbound, and its scratch + // fresh. + let unbound = capture_snapshot_block_contract( + &capture_sources, + MicrovmSnapshotScratchPolicy::Fresh, + None, + "private-copy", + ) + .unwrap(); + assert_eq!( + unbound + .iter() + .map(|block| (block.identity_kind.as_str(), block.identity.as_slice())) + .collect::>(), + [("unbound", &[][..]), ("fresh", &[][..])] + ); + assert!(unbound[1].artifact.is_empty() && unbound[1].restore_mode.is_empty()); + let err = capture_snapshot_block_contract( + &capture_sources, + MicrovmSnapshotScratchPolicy::Paired, + None, + "", + ) + .unwrap_err(); + assert_eq!( + err.to_string(), + "microVM paired scratch requires a storage generation" + ); + + // A restore expects the bound blocks to have its own generation, so a + // snapshot of the same storage matches, and one of other storage does + // not. + let restore_sources = [ + block_source(MicrovmSandboxBlockRole::Distro, None), + block_source(MicrovmSandboxBlockRole::Scratch, None), + ]; + let restore = |generation| { + restore_snapshot_block_contract( + &restore_sources, + MicrovmSnapshotScratchPolicy::Paired, + &bound, + generation, + ) + }; + assert_eq!(restore(Some(GENERATION)).unwrap(), bound); + assert_ne!(restore(Some([0x24; 16])).unwrap(), bound); + assert_eq!( + restore(None).unwrap_err().to_string(), + "snapshot binds the microVM distro block to a storage generation, which the restore requires" + ); + assert_eq!( + restore_snapshot_block_contract( + &restore_sources, + MicrovmSnapshotScratchPolicy::Fresh, + &unbound, + None, + ) + .unwrap(), + unbound + ); + } } diff --git a/openvmm/openvmm_entry/src/ttrpc/microvm.rs b/openvmm/openvmm_entry/src/ttrpc/microvm.rs index b1c1e2ec83c..6f42ac4b265 100644 --- a/openvmm/openvmm_entry/src/ttrpc/microvm.rs +++ b/openvmm/openvmm_entry/src/ttrpc/microvm.rs @@ -1332,7 +1332,6 @@ impl CreateVm { snapshot_requests: self.snapshot_requests, snapshot_destination: self.snapshot_destination, snapshot_tier: None, - snapshot_block_identity: Default::default(), snapshot_generation_id: None, snapshot_scratch_restore_mode: Default::default(), source_hypervisor: self.source_hypervisor, diff --git a/openvmm/openvmm_entry/src/vm_controller/microvm.rs b/openvmm/openvmm_entry/src/vm_controller/microvm.rs index 57f4596ddba..9c88eba5cc5 100644 --- a/openvmm/openvmm_entry/src/vm_controller/microvm.rs +++ b/openvmm/openvmm_entry/src/vm_controller/microvm.rs @@ -28,9 +28,8 @@ pub(crate) struct MicrovmController { pub(crate) snapshot_destination: Option, /// Sandbox capture tier of a guest-requested snapshot. pub(crate) snapshot_tier: Option, - /// Sandbox-block identity policy recorded in a captured snapshot. - pub(crate) snapshot_block_identity: crate::cli_args::microvm::SnapshotBlockIdentityCli, - /// Caller-authenticated immutable storage generation. + /// Caller-supplied immutable storage generation of the sandbox blocks, + /// which a capture of a tier that binds them records. pub(crate) snapshot_generation_id: Option<[u8; 16]>, /// Restore-time materialization policy recorded for paired scratch. pub(crate) snapshot_scratch_restore_mode: @@ -283,21 +282,18 @@ impl VmController { .collect(), } }); - let mut blocks = crate::storage_builder::microvm::capture_snapshot_block_contract( + // A platform capture binds no block, whatever generation it took. + let generation = self + .microvm + .snapshot_tier + .filter(|tier| tier.binds_blocks()) + .and(self.microvm.snapshot_generation_id); + let blocks = crate::storage_builder::microvm::capture_snapshot_block_contract( &self.microvm.resources.sandbox_block_sources, scratch_policy, - self.microvm.snapshot_block_identity, - self.microvm.snapshot_generation_id, + generation, self.microvm.snapshot_scratch_restore_mode.manifest_name(), )?; - if self.microvm.snapshot_tier - == Some(crate::cli_args::microvm::SnapshotTierCli::Platform) - { - for block in blocks.iter_mut().filter(|block| block.read_only) { - block.identity_kind = "unbound".to_owned(); - block.identity.clear(); - } - } let machine_contract = openvmm_helpers::snapshot::microvm::microvm_machine_contract( &self.microvm.source_hypervisor, openvmm_helpers::snapshot::microvm::MICROVM_BOOT_LAYOUT_VERSION, diff --git a/openvmm/openvmm_helpers/src/snapshot/fs.rs b/openvmm/openvmm_helpers/src/snapshot/fs.rs index 03ba222c21a..225366bc81d 100644 --- a/openvmm/openvmm_helpers/src/snapshot/fs.rs +++ b/openvmm/openvmm_helpers/src/snapshot/fs.rs @@ -4,12 +4,10 @@ //! File-system helpers for snapshot artifacts, including their //! platform-specific implementations: private files and directories, //! no-replace renames and directory flushes, directory-relative artifact -//! access and file generations, exact-file hard links, sparse-aware clone and -//! copy with allocation accounting, and SHA-256 over file handles. +//! access and file generations, exact-file hard links, and sparse-aware clone +//! and copy with allocation accounting. -use super::format::validate_sha256; use anyhow::Context; -use sha2::Digest; use std::io::Read; use std::io::Seek; use std::io::SeekFrom; @@ -1122,65 +1120,6 @@ pub(super) fn read_bounded_open_file( Ok(bytes) } -/// Computes SHA-256 over an exact-length regular file handle. -pub fn file_sha256( - file: &std::fs::File, - expected_length: u64, - description: &str, -) -> anyhow::Result> { - let mut file = file - .try_clone() - .with_context(|| format!("failed to duplicate {description} handle"))?; - file.seek(SeekFrom::Start(0)) - .with_context(|| format!("failed to rewind {description}"))?; - let actual_length = file - .metadata() - .with_context(|| format!("failed to inspect {description}"))? - .len(); - anyhow::ensure!( - actual_length == expected_length, - "{description} size ({actual_length} bytes) doesn't match expected ({expected_length} bytes)" - ); - let mut digest = sha2::Sha256::new(); - let mut buffer = vec![0_u8; COPY_BUFFER_SIZE]; - let mut total = 0_u64; - loop { - let count = file - .read(&mut buffer) - .with_context(|| format!("failed to read {description}"))?; - if count == 0 { - break; - } - digest.update(&buffer[..count]); - total = total - .checked_add(count as u64) - .context("file length overflowed u64 while hashing")?; - anyhow::ensure!( - total <= expected_length, - "{description} grew while it was being hashed" - ); - } - anyhow::ensure!( - total == expected_length, - "{description} changed while it was being hashed" - ); - Ok(digest.finalize().to_vec()) -} - -pub(super) fn verify_file_digest( - file: &std::fs::File, - expected_length: u64, - expected_digest: &[u8], - description: &str, -) -> anyhow::Result<()> { - validate_sha256(expected_digest, description)?; - anyhow::ensure!( - file_sha256(file, expected_length, description)? == expected_digest, - "{description} SHA-256 digest mismatch" - ); - Ok(()) -} - pub(super) fn open_file_with_length( path: &Path, expected_length: u64, diff --git a/openvmm/openvmm_helpers/src/snapshot/microvm.rs b/openvmm/openvmm_helpers/src/snapshot/microvm.rs index 0664d1a57c7..7a593c8824e 100644 --- a/openvmm/openvmm_helpers/src/snapshot/microvm.rs +++ b/openvmm/openvmm_helpers/src/snapshot/microvm.rs @@ -5,8 +5,6 @@ use super::SnapshotManifest; use super::format::SCRATCH_FILE_NAME; -#[cfg(test)] -use super::format::SHA256_SIZE; use super::format::SNAPSHOT_CONFIG_ALL; use super::format::SNAPSHOT_CONFIG_INVARIANTS; use super::format::SNAPSHOT_RESTORE_POLICY_CLONE; @@ -35,10 +33,11 @@ pub const MICROVM_MEMORY_BLOCK_SIZE_BYTES: u64 = pub const MICROVM_SHARED_STATUS_INTERRUPT_MODE: &str = "edge-shared-status"; /// Clock policy applied when a snapshot is restored. pub const ADVANCE_BY_HOST_DOWNTIME: &str = "advance_by_host_downtime"; -/// Whole-file SHA-256 sandbox-block identity. -pub const SNAPSHOT_BLOCK_IDENTITY_SHA256: &str = "sha256"; -/// Caller-authenticated immutable storage generation. +/// Identity of a bound sandbox block: the caller-authenticated immutable +/// storage generation that every bound block of a snapshot shares. pub const SNAPSHOT_BLOCK_IDENTITY_GENERATION: &str = "generation"; +/// The retired identity of a bound sandbox block, the SHA-256 of its content. +const RETIRED_BLOCK_IDENTITY_SHA256: &str = "sha256"; /// Independent private scratch materialization. pub const SNAPSHOT_SCRATCH_RESTORE_PRIVATE_COPY: &str = "private-copy"; /// Filesystem copy-on-write scratch materialization. @@ -1956,43 +1955,29 @@ pub(super) fn validate_machine_contract_shape( "snapshot fresh scratch policy is invalid" ); } else { + reject_retired_block_identity(block)?; anyhow::ensure!( - matches!( - block.identity_kind.as_str(), - SNAPSHOT_BLOCK_IDENTITY_SHA256 | SNAPSHOT_BLOCK_IDENTITY_GENERATION - ), + block.identity_kind == SNAPSHOT_BLOCK_IDENTITY_GENERATION, "snapshot paired scratch has an unsupported identity kind" ); - match block.identity_kind.as_str() { - SNAPSHOT_BLOCK_IDENTITY_SHA256 => { - validate_sha256(&block.identity, "scratch block")?; - } - SNAPSHOT_BLOCK_IDENTITY_GENERATION => { - anyhow::ensure!( - block.identity.len() == SNAPSHOT_GENERATION_ID_SIZE - && block.identity.iter().any(|byte| *byte != 0), - "snapshot scratch generation identity is invalid" - ); - } - _ => unreachable!(), - } + anyhow::ensure!( + block.identity.len() == SNAPSHOT_GENERATION_ID_SIZE + && block.identity.iter().any(|byte| *byte != 0), + "snapshot scratch generation identity is invalid" + ); } } else { + reject_retired_block_identity(block)?; anyhow::ensure!( block.artifact.is_empty() && matches!( block.identity_kind.as_str(), - SNAPSHOT_BLOCK_IDENTITY_SHA256 - | SNAPSHOT_BLOCK_IDENTITY_GENERATION - | "unbound" + SNAPSHOT_BLOCK_IDENTITY_GENERATION | "unbound" ), "snapshot read-only layer '{}' has an invalid identity policy", block.role ); match block.identity_kind.as_str() { - SNAPSHOT_BLOCK_IDENTITY_SHA256 => { - validate_sha256(&block.identity, &format!("{} block", block.role))?; - } SNAPSHOT_BLOCK_IDENTITY_GENERATION => { anyhow::ensure!( block.identity.len() == SNAPSHOT_GENERATION_ID_SIZE @@ -2036,31 +2021,16 @@ pub(super) fn validate_machine_contract_shape( previous_role == Some(openvmm_defs::microvm::MicrovmSandboxBlockRole::Scratch), "microVM snapshot is missing its scratch role" ); - let bound_blocks = contract + let mut generations = contract .microvm_sandbox_blocks .iter() - .filter(|block| { - matches!( - block.identity_kind.as_str(), - SNAPSHOT_BLOCK_IDENTITY_SHA256 | SNAPSHOT_BLOCK_IDENTITY_GENERATION - ) - }) - .collect::>(); - if let Some(first) = bound_blocks.first() { + .filter(|block| block.identity_kind == SNAPSHOT_BLOCK_IDENTITY_GENERATION) + .map(|block| &block.identity); + if let Some(first) = generations.next() { anyhow::ensure!( - bound_blocks - .iter() - .all(|block| block.identity_kind == first.identity_kind), - "snapshot sandbox blocks use mixed identity policies" + generations.all(|generation| generation == first), + "snapshot sandbox blocks do not share one storage generation" ); - if first.identity_kind == SNAPSHOT_BLOCK_IDENTITY_GENERATION { - anyhow::ensure!( - bound_blocks - .iter() - .all(|block| block.identity == first.identity), - "snapshot sandbox blocks do not share one storage generation" - ); - } } } @@ -2376,8 +2346,22 @@ where Ok(()) } +/// Rejects `block` when it has the identity that earlier releases recorded by +/// default, the SHA-256 of the block's content, which no restore reads to +/// verify: such a snapshot must be recaptured with a storage generation. +fn reject_retired_block_identity(block: &SnapshotMicrovmSandboxBlock) -> anyhow::Result<()> { + anyhow::ensure!( + block.identity_kind != RETIRED_BLOCK_IDENTITY_SHA256, + "snapshot sandbox block '{}' is identified by the SHA-256 of its content, which OpenVMM no longer verifies; recapture the snapshot with a storage generation", + block.role + ); + Ok(()) +} + +/// The storage generation of the test snapshots that bind their blocks. #[cfg(test)] -const TEST_DISTRO_IDENTITY_BYTE: u8 = 0x11; +const TEST_STORAGE_GENERATION: [u8; SNAPSHOT_GENERATION_ID_SIZE] = + [0x11; SNAPSHOT_GENERATION_ID_SIZE]; #[cfg(test)] pub(super) fn paired_scratch_manifest(scratch: &[u8]) -> SnapshotManifest { @@ -2388,8 +2372,8 @@ pub(super) fn paired_scratch_manifest(scratch: &[u8]) -> SnapshotManifest { role: "distro".to_owned(), read_only: true, length: 512, - identity_kind: "sha256".to_owned(), - identity: vec![TEST_DISTRO_IDENTITY_BYTE; SHA256_SIZE], + identity_kind: SNAPSHOT_BLOCK_IDENTITY_GENERATION.to_owned(), + identity: TEST_STORAGE_GENERATION.to_vec(), artifact: String::new(), logical_block_size: 512, physical_block_size: 4096, @@ -2399,8 +2383,8 @@ pub(super) fn paired_scratch_manifest(scratch: &[u8]) -> SnapshotManifest { role: "scratch".to_owned(), read_only: false, length: scratch.len() as u64, - identity_kind: "sha256".to_owned(), - identity: sha2::Sha256::digest(scratch).to_vec(), + identity_kind: SNAPSHOT_BLOCK_IDENTITY_GENERATION.to_owned(), + identity: TEST_STORAGE_GENERATION.to_vec(), artifact: SCRATCH_FILE_NAME.to_owned(), logical_block_size: 512, physical_block_size: 4096, @@ -2505,8 +2489,6 @@ mod tests { use super::super::tests::test_manifest; use super::*; - const TEST_SCRATCH_IDENTITY_BYTE: u8 = 0x22; - fn virtio_state_unit_name(kind: &str, mmio_base: u64) -> String { format!("{kind}-{mmio_base}") } @@ -2761,8 +2743,8 @@ mod tests { role: "distro".to_owned(), read_only: true, length: 512, - identity_kind: "sha256".to_owned(), - identity: vec![0x11; SHA256_SIZE], + identity_kind: SNAPSHOT_BLOCK_IDENTITY_GENERATION.to_owned(), + identity: TEST_STORAGE_GENERATION.to_vec(), artifact: String::new(), logical_block_size: 512, physical_block_size: 4096, @@ -2772,8 +2754,8 @@ mod tests { role: "scratch".to_owned(), read_only: false, length: 512, - identity_kind: "sha256".to_owned(), - identity: vec![TEST_SCRATCH_IDENTITY_BYTE; SHA256_SIZE], + identity_kind: SNAPSHOT_BLOCK_IDENTITY_GENERATION.to_owned(), + identity: TEST_STORAGE_GENERATION.to_vec(), artifact: SCRATCH_FILE_NAME.to_owned(), logical_block_size: 512, physical_block_size: 4096, @@ -4336,6 +4318,33 @@ mod tests { ); } + #[test] + fn sha256_block_identities_ask_for_a_recapture() { + // An earlier OpenVMM identified the bound blocks of a snapshot by the + // SHA-256 of their content by default; one block is enough. + for (retired, role) in [(&[0, 1][..], "distro"), (&[1][..], "scratch")] { + let mut manifest = paired_scratch_manifest(&[0x5a; 512]); + let contract = manifest.machine_contract.as_mut().unwrap(); + for &index in retired { + let block = &mut contract.microvm_sandbox_blocks[index]; + block.identity_kind = "sha256".to_owned(); + block.identity = vec![0x22; 32]; + } + let error = validate_machine_contract_shape( + manifest.machine_contract.as_ref().unwrap(), + manifest.memory_size_bytes, + manifest.vp_count, + ) + .unwrap_err(); + assert_eq!( + error.to_string(), + format!( + "snapshot sandbox block '{role}' is identified by the SHA-256 of its content, which OpenVMM no longer verifies; recapture the snapshot with a storage generation" + ) + ); + } + } + #[test] fn platform_snapshot_rejects_tenant_command_line() { let scratch = vec![0x5a; 512]; diff --git a/openvmm/openvmm_helpers/src/snapshot/publish.rs b/openvmm/openvmm_helpers/src/snapshot/publish.rs index 3116858e180..56425e514b4 100644 --- a/openvmm/openvmm_helpers/src/snapshot/publish.rs +++ b/openvmm/openvmm_helpers/src/snapshot/publish.rs @@ -22,7 +22,6 @@ use super::fs::create_hard_link_from_handle; use super::fs::create_private_directory; use super::fs::ensure_path_absent; use super::fs::hard_link_is_unsupported; -use super::fs::open_file_with_length; use super::fs::open_regular_file; use super::fs::path_exists; use super::fs::rename_no_replace; @@ -275,11 +274,6 @@ fn stage_snapshot( "scratch backing file", "snapshot scratch", )?; - super::restore::verify_sandbox_block_identity( - &open_file_with_length(&scratch_path, scratch.length, SCRATCH_FILE_NAME)?, - scratch, - "scratch.img", - )?; scratch_publish.complete( "capture", "publication_scratch", @@ -542,8 +536,6 @@ fn publish_owned_memory_file( #[cfg(test)] mod tests { - use super::super::format::SHA256_SIZE; - use super::super::fs::file_sha256; #[cfg(any(target_os = "linux", windows))] use super::super::fs::initialize_snapshot_memory_backing_file; use super::super::microvm::paired_scratch_manifest; @@ -559,7 +551,7 @@ mod tests { use std::io::Write; #[test] - fn paired_scratch_is_published_and_verified() { + fn paired_scratch_is_published_exactly() { let dir = tempfile::tempdir().unwrap(); let snap_dir = dir.path().join("snap"); let memory_path = dir.path().join("memory.bin"); @@ -581,31 +573,22 @@ mod tests { .unwrap(); let read_manifest = read_snapshot_manifest(&snap_dir).unwrap(); - let verified = open_paired_scratch_file(&snap_dir, &read_manifest) + let published = snap_dir.join(SCRATCH_FILE_NAME); + assert_eq!(std::fs::read(&published).unwrap(), scratch); + open_paired_scratch_file(&snap_dir, &read_manifest) .unwrap() .unwrap(); - assert_eq!( - file_sha256(&verified, 1024, SCRATCH_FILE_NAME).unwrap(), - manifest.machine_contract.unwrap().microvm_sandbox_blocks[1].identity - ); - drop(verified); - let published = snap_dir.join(SCRATCH_FILE_NAME); - std::fs::write(&published, vec![0xa5_u8; 1024]).unwrap(); - assert!( - open_paired_scratch_file(&snap_dir, &read_manifest) - .unwrap_err() - .to_string() - .contains("digest mismatch") - ); - - std::fs::write(&published, vec![0_u8; 512]).unwrap(); - assert!( - open_paired_scratch_file(&snap_dir, &read_manifest) - .unwrap_err() - .to_string() - .contains("doesn't match manifest") - ); + // A scratch.img of another length, shorter or longer, is refused. + for length in [512, 1536] { + std::fs::write(&published, vec![0_u8; length]).unwrap(); + assert!( + open_paired_scratch_file(&snap_dir, &read_manifest) + .unwrap_err() + .to_string() + .contains("doesn't match manifest") + ); + } std::fs::remove_file(&published).unwrap(); let error = match read_snapshot_manifest(&snap_dir) { @@ -654,17 +637,12 @@ mod tests { /// whose manifest, state, memory, and paired scratch read back intact. fn check_published(&self, snap_dir: &Path) { let read_manifest = read_snapshot_manifest(snap_dir).unwrap(); - let verified = open_paired_scratch_file(snap_dir, &read_manifest) + open_paired_scratch_file(snap_dir, &read_manifest) .unwrap() .unwrap(); assert_eq!( - file_sha256(&verified, 1024, SCRATCH_FILE_NAME).unwrap(), - self.manifest - .machine_contract - .as_ref() - .unwrap() - .microvm_sandbox_blocks[1] - .identity + std::fs::read(snap_dir.join(SCRATCH_FILE_NAME)).unwrap(), + vec![0x5a_u8; 1024] ); assert_eq!( std::fs::read(snap_dir.join(MEMORY_FILE_NAME)).unwrap(), @@ -730,16 +708,7 @@ mod tests { std::fs::write(&scratch_path, vec![0x5a_u8; 1024]).unwrap(); let memory_file = std::fs::File::open(memory_path).unwrap(); let scratch_file = std::fs::File::open(scratch_path).unwrap(); - let mut manifest = paired_scratch_manifest(&[0x5a; 1024]); - for block in &mut manifest - .machine_contract - .as_mut() - .unwrap() - .microvm_sandbox_blocks - { - block.identity_kind = microvm::SNAPSHOT_BLOCK_IDENTITY_GENERATION.to_owned(); - block.identity = vec![0x42; microvm::SNAPSHOT_GENERATION_ID_SIZE]; - } + let manifest = paired_scratch_manifest(&[0x5a; 1024]); write_snapshot_from_memory_and_scratch_files( &snap_dir, @@ -750,6 +719,9 @@ mod tests { ) .unwrap(); + // The storage generation alone vouches for the content of scratch.img, + // which the restore never reads to verify, so a same-length change goes + // undetected. let read_manifest = read_snapshot_manifest(&snap_dir).unwrap(); std::fs::write(snap_dir.join(SCRATCH_FILE_NAME), vec![0xa5_u8; 1024]).unwrap(); open_paired_scratch_file(&snap_dir, &read_manifest) @@ -758,23 +730,16 @@ mod tests { } #[test] - fn paired_scratch_digest_mismatch_is_not_published() { + fn paired_scratch_of_another_length_is_not_published() { let dir = tempfile::tempdir().unwrap(); let snap_dir = dir.path().join("snap"); let memory_path = dir.path().join("memory.bin"); let scratch_path = dir.path().join("scratch.img"); - let scratch = vec![0x5a_u8; 1024]; std::fs::write(&memory_path, vec![0_u8; 1024]).unwrap(); - std::fs::write(&scratch_path, &scratch).unwrap(); + std::fs::write(&scratch_path, vec![0x5a_u8; 1536]).unwrap(); let memory_file = std::fs::File::open(memory_path).unwrap(); let scratch_file = std::fs::File::open(scratch_path).unwrap(); - let mut manifest = paired_scratch_manifest(&scratch); - manifest - .machine_contract - .as_mut() - .unwrap() - .microvm_sandbox_blocks[1] - .identity = vec![0xff; SHA256_SIZE]; + let manifest = paired_scratch_manifest(&[0x5a; 1024]); let error = write_snapshot_from_memory_and_scratch_files( &snap_dir, @@ -784,7 +749,12 @@ mod tests { Some(&scratch_file), ) .unwrap_err(); - assert!(error.to_string().contains("digest mismatch")); + assert!( + format!("{error:#}").contains( + "scratch backing file size (1536 bytes) doesn't match manifest (1024 bytes)" + ), + "{error:#}" + ); assert!(!snap_dir.exists()); } diff --git a/openvmm/openvmm_helpers/src/snapshot/restore.rs b/openvmm/openvmm_helpers/src/snapshot/restore.rs index 44d2750a3d2..4624ac983b1 100644 --- a/openvmm/openvmm_helpers/src/snapshot/restore.rs +++ b/openvmm/openvmm_helpers/src/snapshot/restore.rs @@ -3,7 +3,7 @@ //! Restore-side snapshot access: opening one published generation through a //! retained directory handle, structural validation against its manifest, -//! paired scratch verification, and single-use resume claims. +//! paired scratch materialization, and single-use resume claims. use super::SnapshotManifest; use super::format::MANIFEST_FILE_NAME; @@ -25,7 +25,6 @@ use super::fs::open_file_with_length; use super::fs::opened_file_generation; use super::fs::read_bounded_open_file; use super::fs::reflink_exact; -use super::fs::verify_file_digest; use super::fs::verify_hard_link_identity; use super::microvm; use anyhow::Context; @@ -248,7 +247,9 @@ pub fn read_snapshot_with_memory( Ok((manifest, state_bytes, memory)) } -/// Opens and verifies the scratch image paired to a snapshot, if present. +/// Opens the scratch image paired to a snapshot, if present, which must have +/// its recorded length. Its storage generation vouches for its content, which +/// the restore never reads to verify. pub fn open_paired_scratch_file( dir: &Path, manifest: &SnapshotManifest, @@ -266,65 +267,22 @@ fn open_paired_scratch_file_in_directory( }; let file = directory.open_file_with_length(SCRATCH_FILE_NAME, scratch.length, SCRATCH_FILE_NAME)?; - verify_sandbox_block_identity(&file, scratch, SCRATCH_FILE_NAME)?; Ok(Some(file)) } -pub(super) fn verify_sandbox_block_identity( - file: &std::fs::File, - block: µvm::SnapshotMicrovmSandboxBlock, - description: &str, -) -> anyhow::Result<()> { - match block.identity_kind.as_str() { - microvm::SNAPSHOT_BLOCK_IDENTITY_SHA256 => { - verify_file_digest(file, block.length, &block.identity, description) - } - microvm::SNAPSHOT_BLOCK_IDENTITY_GENERATION => Ok(()), - other => anyhow::bail!("{description} has unsupported identity kind '{other}'"), - } -} - -/// Copies a verified immutable artifact to a new private path. -pub fn copy_verified_file( - source: &std::fs::File, - destination: &Path, - expected_length: u64, - expected_digest: &[u8], - description: &str, -) -> anyhow::Result<()> { - verify_file_digest(source, expected_length, expected_digest, description)?; - copy_exact( - source, - destination, - expected_length, - description, - "private scratch copy", - )?; - let copy = open_file_with_length(destination, expected_length, "private scratch copy")?; - verify_file_digest( - ©, - expected_length, - expected_digest, - "private scratch copy", - ) -} - /// Materializes paired scratch as an independent private file. pub fn copy_paired_scratch_file( source: &std::fs::File, destination: &Path, block: µvm::SnapshotMicrovmSandboxBlock, ) -> anyhow::Result<()> { - verify_sandbox_block_identity(source, block, SCRATCH_FILE_NAME)?; copy_exact( source, destination, block.length, SCRATCH_FILE_NAME, "private scratch copy", - )?; - let copy = open_file_with_length(destination, block.length, "private scratch copy")?; - verify_sandbox_block_identity(©, block, "private scratch copy") + ) } /// Materializes paired scratch with a required filesystem copy-on-write clone. @@ -333,16 +291,13 @@ pub fn clone_paired_scratch_file( destination: &Path, block: µvm::SnapshotMicrovmSandboxBlock, ) -> anyhow::Result<()> { - verify_sandbox_block_identity(source, block, SCRATCH_FILE_NAME)?; reflink_exact( source, destination, block.length, SCRATCH_FILE_NAME, "copy-on-write scratch clone", - )?; - let clone = open_file_with_length(destination, block.length, "copy-on-write scratch clone")?; - verify_sandbox_block_identity(&clone, block, "copy-on-write scratch clone") + ) } /// Creates a private path to the exact claimed paired-scratch generation. @@ -351,7 +306,6 @@ pub fn link_claimed_paired_scratch_file( destination: &Path, block: µvm::SnapshotMicrovmSandboxBlock, ) -> anyhow::Result<()> { - verify_sandbox_block_identity(source, block, SCRATCH_FILE_NAME)?; let parent = destination .parent() .context("claimed scratch destination has no parent")?; @@ -363,8 +317,7 @@ pub fn link_claimed_paired_scratch_file( create_hard_link_from_handle(source, &directory.file, name) .context("failed to link claimed scratch generation")?; let linked = open_file_with_length(destination, block.length, "claimed scratch link")?; - verify_hard_link_identity(source, &linked, block.length)?; - verify_sandbox_block_identity(&linked, block, "claimed scratch link") + verify_hard_link_identity(source, &linked, block.length) } /// Atomically consumes a single-use resume snapshot. @@ -466,6 +419,38 @@ mod tests { #[cfg(any(target_os = "linux", windows))] use std::io::Write; + #[test] + fn private_scratch_copy_is_exact_and_independent() { + let manifest = paired_scratch_manifest(&[0x5a; 512]); + let block = microvm::paired_scratch_block(&manifest).unwrap(); + let dir = tempfile::tempdir().unwrap(); + let source_path = dir.path().join("source-scratch.img"); + let destination_path = dir.path().join("private-scratch.img"); + // The storage generation vouches for the content, which the copy takes + // as it is, without reading it to verify it. + std::fs::write(&source_path, vec![0xa5; 512]).unwrap(); + let source = std::fs::File::open(&source_path).unwrap(); + + copy_paired_scratch_file(&source, &destination_path, block).unwrap(); + assert_eq!(std::fs::read(&destination_path).unwrap(), vec![0xa5; 512]); + std::fs::write(&destination_path, vec![0x3c; 512]).unwrap(); + assert_eq!(std::fs::read(&source_path).unwrap(), vec![0xa5; 512]); + + // A source of another length is refused. + let longer_path = dir.path().join("longer-scratch.img"); + std::fs::write(&longer_path, vec![0xa5; 1024]).unwrap(); + let error = copy_paired_scratch_file( + &std::fs::File::open(&longer_path).unwrap(), + &dir.path().join("refused-scratch.img"), + block, + ) + .unwrap_err(); + assert!( + error.to_string().contains("doesn't match manifest"), + "{error:#}" + ); + } + #[cfg(target_os = "linux")] #[test] fn copy_on_write_scratch_clone_is_independent() {