add "secret_free" parameter to /machine-config endpoint

roypat · roypat · commit 65d1382f3442 · 2025-04-09T11:26:36.000+01:00
This will later indicate to Firecracker that guest memory should be
backed by guest_memfd.

Signed-off-by: Patrick Roy &lt;roypat@amazon.co.uk&gt;
diff --git a/src/firecracker/swagger/firecracker.yaml b/src/firecracker/swagger/firecracker.yaml
@@ -1076,6 +1076,11 @@ definitions:
         description:
           Aarch64 only. If non-zero, causes Firecracker to allocate a specific memory area of this size (in MiB)
           which the guest will use as swiotlb region for all I/O.
+      secret_free:
+        type: boolean
+        description:
+          If enabled, guest memory will be unmapped from the host kernel's address space, providing additional
+          protection against transitive execution issues. All I/O must then go through a swiotlb region.
 
   MemoryBackend:
     type: object
diff --git a/src/vmm/src/resources.rs b/src/vmm/src/resources.rs
@@ -110,6 +110,14 @@ pub struct VmResources {
 }
 
 impl VmResources {
+    /// Whether this [`VmResources`] object contains any devices that require host kernel access
+    /// into guest memory.
+    pub fn has_any_io_devices(&self) -> bool {
+        !self.block.devices.is_empty()
+            || self.vsock.get().is_some()
+            || self.net_builder.iter().next().is_some()
+    }
+
     /// Configures Vmm resources as described by the `config_json` param.
     pub fn from_json(
         config_json: &str,
@@ -217,6 +225,11 @@ impl VmResources {
                         BalloonConfigError::IncompatibleWith("huge pages"),
                     ));
                 }
+                if self.machine_config.mem_config.secret_free {
+                    return Err(ResourcesError::BalloonDevice(
+                        BalloonConfigError::IncompatibleWith("secret freedom"),
+                    ));
+                }
             }
 
             SharedDeviceType::Vsock(vsock) => {
@@ -256,12 +269,28 @@ impl VmResources {
             return Err(MachineConfigError::IncompatibleBalloonSize);
         }
 
+        if self.has_any_io_devices()
+            && self.machine_config.mem_config.secret_free
+            && !self.swiotlb_used()
+        {
+            return Err(MachineConfigError::Incompatible(
+                "secret freedom",
+                "I/O without swiotlb",
+            ));
+        }
+
         if self.balloon.get().is_some() && updated.huge_pages != HugePageConfig::None {
             return Err(MachineConfigError::Incompatible(
                 "balloon device",
                 "huge pages",
             ));
         }
+        if self.balloon.get().is_some() && updated.mem_config.secret_free {
+            return Err(MachineConfigError::Incompatible(
+                "balloon device",
+                "secret freedom",
+            ));
+        }
         self.machine_config = updated;
 
         Ok(())
@@ -320,6 +349,10 @@ impl VmResources {
             return Err(BalloonConfigError::IncompatibleWith("huge pages"));
         }
 
+        if self.machine_config.mem_config.secret_free {
+            return Err(BalloonConfigError::IncompatibleWith("secret freedom"));
+        }
+
         self.balloon.set(config)
     }
 
@@ -343,6 +376,13 @@ impl VmResources {
         &mut self,
         block_device_config: BlockDeviceConfig,
     ) -> Result<(), DriveError> {
+        if self.has_any_io_devices()
+            && self.machine_config.mem_config.secret_free
+            && !self.swiotlb_used()
+        {
+            return Err(DriveError::SecretFreeWithoutSwiotlb);
+        }
+
         self.block.insert(block_device_config)
     }
 
@@ -351,12 +391,26 @@ impl VmResources {
         &mut self,
         body: NetworkInterfaceConfig,
     ) -> Result<(), NetworkInterfaceError> {
+        if self.has_any_io_devices()
+            && self.machine_config.mem_config.secret_free
+            && !self.swiotlb_used()
+        {
+            return Err(NetworkInterfaceError::SecretFreeWithoutSwiotlb);
+        }
+
         let _ = self.net_builder.build(body)?;
         Ok(())
     }
 
     /// Sets a vsock device to be attached when the VM starts.
     pub fn set_vsock_device(&mut self, config: VsockDeviceConfig) -> Result<(), VsockConfigError> {
+        if self.has_any_io_devices()
+            && self.machine_config.mem_config.secret_free
+            && !self.swiotlb_used()
+        {
+            return Err(VsockConfigError::SecretFreeWithoutSwiotlb);
+        }
+
         self.vsock.insert(config)
     }
 
diff --git a/src/vmm/src/vmm_config/drive.rs b/src/vmm/src/vmm_config/drive.rs
@@ -24,6 +24,8 @@ pub enum DriveError {
     DeviceUpdate(VmmError),
     /// A root block device already exists!
     RootBlockDeviceAlreadyAdded,
+    /// A block device was added to a secret free VM that doesnt have a swiotlb region.
+    SecretFreeWithoutSwiotlb,
 }
 
 /// Use this structure to set up the Block Device before booting the kernel.
diff --git a/src/vmm/src/vmm_config/machine_config.rs b/src/vmm/src/vmm_config/machine_config.rs
@@ -99,6 +99,11 @@ pub struct MemoryConfig {
     #[cfg(target_arch = "aarch64")]
     #[serde(default)]
     pub initial_swiotlb_size: usize,
+    /// Whether guest_memfd should be used to back normal guest memory. If this is enabled
+    /// and any devices are attached to the VM, then initial_swiotlb_size must be non-zero,
+    /// as I/O into secret free memory is not possible.
+    #[serde(default)]
+    pub secret_free: bool,
 }
 
 /// Struct used in PUT `/machine-config` API call.
@@ -289,6 +294,7 @@ impl MachineConfig {
         let mem_size_mib = update.mem_size_mib.unwrap_or(self.mem_size_mib);
         let page_config = update.huge_pages.unwrap_or(self.huge_pages);
         let mem_config = update.mem_config.unwrap_or(self.mem_config);
+        let track_dirty_pages = update.track_dirty_pages.unwrap_or(self.track_dirty_pages);
 
         if mem_size_mib == 0 || !page_config.is_valid_mem_size(mem_size_mib) {
             return Err(MachineConfigError::InvalidMemorySize);
@@ -301,6 +307,20 @@ impl MachineConfig {
             return Err(MachineConfigError::InvalidSwiotlbRegionSize);
         }
 
+        if mem_config.secret_free && page_config != HugePageConfig::None {
+            return Err(MachineConfigError::Incompatible(
+                "secret freedom",
+                "huge pages",
+            ));
+        }
+
+        if mem_config.secret_free && track_dirty_pages {
+            return Err(MachineConfigError::Incompatible(
+                "secret freedom",
+                "diff snapshots",
+            ));
+        }
+
         let cpu_template = match update.cpu_template {
             None => self.cpu_template.clone(),
             Some(StaticCpuTemplate::None) => None,
@@ -313,7 +333,7 @@ impl MachineConfig {
             mem_config,
             smt,
             cpu_template,
-            track_dirty_pages: update.track_dirty_pages.unwrap_or(self.track_dirty_pages),
+            track_dirty_pages,
             huge_pages: page_config,
             #[cfg(feature = "gdb")]
             gdb_socket_path: update.gdb_socket_path.clone(),
@@ -325,7 +345,7 @@ impl MachineConfig {
 mod tests {
     use crate::cpu_config::templates::{CpuTemplateType, CustomCpuTemplate, StaticCpuTemplate};
     use crate::vmm_config::machine_config::{
-        HugePageConfig, MachineConfig, MachineConfigError, MachineConfigUpdate,
+        HugePageConfig, MachineConfig, MachineConfigError, MachineConfigUpdate, MemoryConfig,
     };
 
     #[test]
@@ -379,6 +399,38 @@ mod tests {
             .unwrap();
         assert_eq!(updated.huge_pages, HugePageConfig::Hugetlbfs2M);
         assert_eq!(updated.mem_size_mib, 32);
+
+        let res = mconf.update(&MachineConfigUpdate {
+            huge_pages: Some(HugePageConfig::Hugetlbfs2M),
+            mem_config: Some(MemoryConfig {
+                secret_free: true,
+                ..Default::default()
+            }),
+            ..Default::default()
+        });
+        assert_eq!(
+            res,
+            Err(MachineConfigError::Incompatible(
+                "secret freedom",
+                "huge pages"
+            ))
+        );
+
+        let res = mconf.update(&MachineConfigUpdate {
+            track_dirty_pages: Some(true),
+            mem_config: Some(MemoryConfig {
+                secret_free: true,
+                ..Default::default()
+            }),
+            ..Default::default()
+        });
+        assert_eq!(
+            res,
+            Err(MachineConfigError::Incompatible(
+                "secret freedom",
+                "diff snapshots"
+            ))
+        );
     }
 
     #[test]
diff --git a/src/vmm/src/vmm_config/net.rs b/src/vmm/src/vmm_config/net.rs
@@ -71,6 +71,8 @@ pub enum NetworkInterfaceError {
     GuestMacAddressInUse(String),
     /// Cannot open/create the tap device: {0}
     OpenTap(#[from] TapError),
+    /// A net device was added to a secret free VM that doesnt have a swiotlb region.
+    SecretFreeWithoutSwiotlb,
 }
 
 /// Builder for a list of network devices.
diff --git a/src/vmm/src/vmm_config/vsock.rs b/src/vmm/src/vmm_config/vsock.rs
@@ -17,6 +17,8 @@ pub enum VsockConfigError {
     CreateVsockBackend(VsockUnixBackendError),
     /// Cannot create vsock device: {0}
     CreateVsockDevice(VsockError),
+    /// A vsock device was added to a secret free VM that doesnt have a swiotlb region.
+    SecretFreeWithoutSwiotlb,
 }
 
 /// This struct represents the strongly typed equivalent of the json body

Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,8 @@ pub enum DriveError {`
`24`	`24`	`DeviceUpdate(VmmError),`
`25`	`25`	`/// A root block device already exists!`
`26`	`26`	`RootBlockDeviceAlreadyAdded,`
	`27`	`+ /// A block device was added to a secret free VM that doesnt have a swiotlb region.`
	`28`	`+ SecretFreeWithoutSwiotlb,`
`27`	`29`	`}`
`28`	`30`
`29`	`31`	`/// Use this structure to set up the Block Device before booting the kernel.`
Original file line number	Diff line number	Diff line change
`@@ -71,6 +71,8 @@ pub enum NetworkInterfaceError {`
`71`	`71`	`GuestMacAddressInUse(String),`
`72`	`72`	`/// Cannot open/create the tap device: {0}`
`73`	`73`	`OpenTap(#[from] TapError),`
	`74`	`+ /// A net device was added to a secret free VM that doesnt have a swiotlb region.`
	`75`	`+ SecretFreeWithoutSwiotlb,`
`74`	`76`	`}`
`75`	`77`
`76`	`78`	`/// Builder for a list of network devices.`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,8 @@ pub enum VsockConfigError {`
`17`	`17`	`CreateVsockBackend(VsockUnixBackendError),`
`18`	`18`	`/// Cannot create vsock device: {0}`
`19`	`19`	`CreateVsockDevice(VsockError),`
	`20`	`+ /// A vsock device was added to a secret free VM that doesnt have a swiotlb region.`
	`21`	`+ SecretFreeWithoutSwiotlb,`
`20`	`22`	`}`
`21`	`23`
`22`	`24`	`/// This struct represents the strongly typed equivalent of the json body`