[host/mem] added 'init data' region to store additional guest blob

danbugs · danbugs · commit dd654f5a1d47 · 2025-06-13T23:58:47.000Z
+ if guest blob is provided, we now write it to shared mem when creating a sandbox

Signed-off-by: danbugs &lt;danilochiarlone@gmail.com&gt;
diff --git a/src/hyperlight_host/src/mem/layout.rs b/src/hyperlight_host/src/mem/layout.rs
@@ -21,15 +21,20 @@ use rand::{RngCore, rng};
 use tracing::{Span, instrument};
 
 use super::memory_region::MemoryRegionType::{
-    Code, GuardPage, Heap, HostFunctionDefinitions, InputData, OutputData, PageTables, Peb, Stack,
+    Code, GuardPage, Heap, HostFunctionDefinitions, InitData, InputData, OutputData, PageTables,
+    Peb, Stack,
+};
+use super::memory_region::{
+    DEFAULT_GUEST_BLOB_MEM_FLAGS, MemoryRegion, MemoryRegionFlags, MemoryRegionVecBuilder,
 };
-use super::memory_region::{MemoryRegion, MemoryRegionFlags, MemoryRegionVecBuilder};
 use super::mgr::AMOUNT_OF_MEMORY_PER_PT;
 use super::shared_mem::{ExclusiveSharedMemory, GuestSharedMemory, SharedMemory};
 use crate::error::HyperlightError::{GuestOffsetIsInvalid, MemoryRequestTooBig};
 use crate::sandbox::SandboxConfiguration;
 use crate::{Result, new_error};
 
+// +-------------------------------------------+
+// |              Init Data                    | (GuestBlob size)
 // +-------------------------------------------+
 // |             Guest (User) Stack            |
 // +-------------------------------------------+
@@ -56,6 +61,8 @@ use crate::{Result, new_error};
 // |                   PML4                    |
 // +-------------------------------------------+ 0x0_000
 
+/// - `InitData` - some extra data that can be loaded onto the sandbox during
+///     initialization.
 ///
 /// - `HostDefinitions` - the length of this is the `HostFunctionDefinitionSize`
 ///   field from `SandboxConfiguration`
@@ -82,6 +89,7 @@ pub(crate) struct SandboxMemoryLayout {
     pub(super) stack_size: usize,
     /// The heap size of this sandbox.
     pub(super) heap_size: usize,
+    init_data_size: usize,
 
     /// The following fields are offsets to the actual PEB struct fields.
     /// They are used when writing the PEB struct itself
@@ -103,6 +111,7 @@ pub(crate) struct SandboxMemoryLayout {
     guest_heap_buffer_offset: usize,
     guard_page_offset: usize,
     guest_user_stack_buffer_offset: usize, // the lowest address of the user stack
+    init_data_offset: usize,
 
     // other
     pub(crate) peb_address: usize,
@@ -111,6 +120,7 @@ pub(crate) struct SandboxMemoryLayout {
     total_page_table_size: usize,
     // The offset in the sandbox memory where the code starts
     guest_code_offset: usize,
+    pub(crate) init_data_permissions: Option<MemoryRegionFlags>,
 }
 
 impl Debug for SandboxMemoryLayout {
@@ -122,6 +132,10 @@ impl Debug for SandboxMemoryLayout {
             )
             .field("Stack Size", &format_args!("{:#x}", self.stack_size))
             .field("Heap Size", &format_args!("{:#x}", self.heap_size))
+            .field(
+                "Init Data Size",
+                &format_args!("{:#x}", self.init_data_size),
+            )
             .field("PEB Address", &format_args!("{:#x}", self.peb_address))
             .field("PEB Offset", &format_args!("{:#x}", self.peb_offset))
             .field("Code Size", &format_args!("{:#x}", self.code_size))
@@ -181,6 +195,10 @@ impl Debug for SandboxMemoryLayout {
                 "Guest User Stack Buffer Offset",
                 &format_args!("{:#x}", self.guest_user_stack_buffer_offset),
             )
+            .field(
+                "Init Data Offset",
+                &format_args!("{:#x}", self.init_data_offset),
+            )
             .field(
                 "Page Table Size",
                 &format_args!("{:#x}", self.total_page_table_size),
@@ -231,6 +249,8 @@ impl SandboxMemoryLayout {
         code_size: usize,
         stack_size: usize,
         heap_size: usize,
+        init_data_size: usize,
+        init_data_permissions: Option<MemoryRegionFlags>,
     ) -> Result<Self> {
         let total_page_table_size =
             Self::get_total_page_table_size(cfg, code_size, stack_size, heap_size);
@@ -275,6 +295,7 @@ impl SandboxMemoryLayout {
         let guest_user_stack_buffer_offset = guard_page_offset + PAGE_SIZE_USIZE;
         // round up stack size to page size. This is needed for MemoryRegion
         let stack_size_rounded = round_up_to(stack_size, PAGE_SIZE_USIZE);
+        let init_data_offset = guest_user_stack_buffer_offset + stack_size_rounded;
 
         Ok(Self {
             peb_offset,
@@ -299,6 +320,9 @@ impl SandboxMemoryLayout {
             guard_page_offset,
             total_page_table_size,
             guest_code_offset,
+            init_data_offset,
+            init_data_size,
+            init_data_permissions,
         })
     }
 
@@ -444,7 +468,7 @@ impl SandboxMemoryLayout {
     /// layout.
     #[instrument(skip_all, parent = Span::current(), level= "Trace")]
     fn get_unaligned_memory_size(&self) -> usize {
-        self.get_top_of_user_stack_offset() + self.stack_size
+        self.init_data_offset + self.init_data_size
     }
 
     /// get the code offset
@@ -682,12 +706,31 @@ impl SandboxMemoryLayout {
         }
 
         // stack
-        let final_offset = builder.push_page_aligned(
+        let init_data_offset = builder.push_page_aligned(
             self.get_guest_stack_size(),
             MemoryRegionFlags::READ | MemoryRegionFlags::WRITE,
             Stack,
         );
 
+        let expected_init_data_offset = TryInto::<usize>::try_into(self.init_data_offset)?;
+
+        if init_data_offset != expected_init_data_offset {
+            return Err(new_error!(
+                "Init Data offset does not match expected Init Data offset expected:  {}, actual:  {}",
+                expected_init_data_offset,
+                init_data_offset
+            ));
+        }
+
+        let final_offset = if self.init_data_size > 0 {
+            let mem_flags = self
+                .init_data_permissions
+                .unwrap_or(DEFAULT_GUEST_BLOB_MEM_FLAGS);
+            builder.push_page_aligned(self.init_data_size, mem_flags, InitData)
+        } else {
+            init_data_offset
+        };
+
         let expected_final_offset = TryInto::<usize>::try_into(self.get_memory_size()?)?;
 
         if final_offset != expected_final_offset {
@@ -701,6 +744,16 @@ impl SandboxMemoryLayout {
         Ok(builder.build())
     }
 
+    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
+    pub(crate) fn write_init_data(
+        &self,
+        shared_mem: &mut ExclusiveSharedMemory,
+        bytes: &[u8],
+    ) -> Result<()> {
+        shared_mem.copy_from_slice(bytes, self.init_data_offset)?;
+        Ok(())
+    }
+
     /// Write the finished memory layout to `shared_mem` and return
     /// `Ok` if successful.
     ///
@@ -869,7 +922,8 @@ mod tests {
     #[test]
     fn test_get_memory_size() {
         let sbox_cfg = SandboxConfiguration::default();
-        let sbox_mem_layout = SandboxMemoryLayout::new(sbox_cfg, 4096, 2048, 4096).unwrap();
+        let sbox_mem_layout =
+            SandboxMemoryLayout::new(sbox_cfg, 4096, 2048, 4096, 0, None).unwrap();
         assert_eq!(
             sbox_mem_layout.get_memory_size().unwrap(),
             get_expected_memory_size(&sbox_mem_layout)
diff --git a/src/hyperlight_host/src/mem/memory_region.rs b/src/hyperlight_host/src/mem/memory_region.rs
@@ -43,6 +43,10 @@ use mshv_bindings::{hv_x64_memory_intercept_message, mshv_user_mem_region};
 #[cfg(target_os = "windows")]
 use windows::Win32::System::Hypervisor::{self, WHV_MEMORY_ACCESS_TYPE};
 
+use super::mgr::{PAGE_NX, PAGE_PRESENT, PAGE_RW, PAGE_USER};
+
+pub(crate) const DEFAULT_GUEST_BLOB_MEM_FLAGS: MemoryRegionFlags = MemoryRegionFlags::READ;
+
 bitflags! {
     /// flags representing memory permission for a memory region
     #[derive(Copy, Clone, Debug, PartialEq, Eq)]
@@ -60,6 +64,30 @@ bitflags! {
     }
 }
 
+impl MemoryRegionFlags {
+    pub(crate) fn translate_flags(&self) -> u64 {
+        let mut page_flags = 0;
+
+        page_flags |= PAGE_PRESENT; // Mark page as present
+
+        if self.contains(MemoryRegionFlags::WRITE) {
+            page_flags |= PAGE_RW; // Allow read/write
+        }
+
+        if self.contains(MemoryRegionFlags::STACK_GUARD) {
+            page_flags |= PAGE_RW; // The guard page is marked RW so that if it gets written to we can detect it in the host
+        }
+
+        if self.contains(MemoryRegionFlags::EXECUTE) {
+            page_flags |= PAGE_USER; // Allow user access
+        } else {
+            page_flags |= PAGE_NX; // Mark as non-executable if EXECUTE is not set
+        }
+
+        page_flags
+    }
+}
+
 impl std::fmt::Display for MemoryRegionFlags {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         if self.is_empty() {
@@ -129,6 +157,8 @@ pub enum MemoryRegionType {
     PageTables,
     /// The region contains the guest's code
     Code,
+    /// The region contains the guest's init data
+    InitData,
     /// The region contains the PEB
     Peb,
     /// The region contains the Host Function Definitions
diff --git a/src/hyperlight_host/src/mem/mgr.rs b/src/hyperlight_host/src/mem/mgr.rs
@@ -28,13 +28,14 @@ use tracing::{Span, instrument};
 
 use super::exe::ExeInfo;
 use super::layout::SandboxMemoryLayout;
-use super::memory_region::{MemoryRegion, MemoryRegionType};
+use super::memory_region::{DEFAULT_GUEST_BLOB_MEM_FLAGS, MemoryRegion, MemoryRegionType};
 use super::ptr::{GuestPtr, RawPtr};
 use super::ptr_offset::Offset;
 use super::shared_mem::{ExclusiveSharedMemory, GuestSharedMemory, HostSharedMemory, SharedMemory};
 use super::shared_mem_snapshot::SharedMemorySnapshot;
 use crate::error::HyperlightError::NoMemorySnapshot;
 use crate::sandbox::SandboxConfiguration;
+use crate::sandbox::uninitialized::GuestBlob;
 use crate::{HyperlightError, Result, log_then_return, new_error};
 
 /// Paging Flags
@@ -43,10 +44,10 @@ use crate::{HyperlightError, Result, log_then_return, new_error};
 ///
 /// * Very basic description: https://stackoverflow.com/a/26945892
 /// * More in-depth descriptions: https://wiki.osdev.org/Paging
-const PAGE_PRESENT: u64 = 1; // Page is Present
-const PAGE_RW: u64 = 1 << 1; // Page is Read/Write (if not set page is read only so long as the WP bit in CR0 is set to 1 - which it is in Hyperlight)
-const PAGE_USER: u64 = 1 << 2; // User/Supervisor (if this bit is set then the page is accessible by user mode code)
-const PAGE_NX: u64 = 1 << 63; // Execute Disable (if this bit is set then data in the page cannot be executed)
+pub(crate) const PAGE_PRESENT: u64 = 1; // Page is Present
+pub(crate) const PAGE_RW: u64 = 1 << 1; // Page is Read/Write (if not set page is read only so long as the WP bit in CR0 is set to 1 - which it is in Hyperlight)
+pub(crate) const PAGE_USER: u64 = 1 << 2; // User/Supervisor (if this bit is set then the page is accessible by user mode code)
+pub(crate) const PAGE_NX: u64 = 1 << 63; // Execute Disable (if this bit is set then data in the page cannot be executed)
 
 // The amount of memory that can be mapped per page table
 pub(super) const AMOUNT_OF_MEMORY_PER_PT: usize = 0x200_000;
@@ -158,6 +159,11 @@ where
                             // TODO: We parse and load the exe according to its sections and then
                             // have the correct flags set rather than just marking the entire binary as executable
                             MemoryRegionType::Code => PAGE_PRESENT | PAGE_RW | PAGE_USER,
+                            MemoryRegionType::InitData => self
+                                .layout
+                                .init_data_permissions
+                                .map(|perm| perm.translate_flags())
+                                .unwrap_or(DEFAULT_GUEST_BLOB_MEM_FLAGS.translate_flags()),
                             MemoryRegionType::Stack => PAGE_PRESENT | PAGE_RW | PAGE_USER | PAGE_NX,
                             #[cfg(feature = "executable_heap")]
                             MemoryRegionType::Heap => PAGE_PRESENT | PAGE_RW | PAGE_USER,
@@ -286,12 +292,18 @@ impl SandboxMemoryManager<ExclusiveSharedMemory> {
     pub(crate) fn load_guest_binary_into_memory(
         cfg: SandboxConfiguration,
         exe_info: &mut ExeInfo,
+        guest_blob: Option<&GuestBlob>,
     ) -> Result<Self> {
+        let guest_blob_size = guest_blob.map(|b| b.data.len()).unwrap_or(0);
+        let guest_blob_mem_flags = guest_blob.map(|b| b.permissions);
+
         let layout = SandboxMemoryLayout::new(
             cfg,
             exe_info.loaded_size(),
             usize::try_from(cfg.get_stack_size(exe_info))?,
             usize::try_from(cfg.get_heap_size(exe_info))?,
+            guest_blob_size,
+            guest_blob_mem_flags,
         )?;
         let mut shared_mem = ExclusiveSharedMemory::new(layout.get_memory_size()?)?;
 
diff --git a/src/hyperlight_host/src/sandbox/mem_mgr.rs b/src/hyperlight_host/src/sandbox/mem_mgr.rs
@@ -98,6 +98,15 @@ impl MemMgrWrapper<ExclusiveSharedMemory> {
         let mem_size = shared_mem.mem_size();
         layout.write(shared_mem, SandboxMemoryLayout::BASE_ADDRESS, mem_size)
     }
+
+    #[instrument(err(Debug), skip_all, parent = Span::current(), level= "Trace")]
+    pub(super) fn write_init_data(&mut self, user_memory: &[u8]) -> Result<()> {
+        let mgr = self.unwrap_mgr_mut();
+        let layout = mgr.layout;
+        let shared_mem = mgr.get_shared_mem_mut();
+        layout.write_init_data(shared_mem, user_memory)?;
+        Ok(())
+    }
 }
 
 impl MemMgrWrapper<HostSharedMemory> {
diff --git a/src/hyperlight_host/src/sandbox/outb.rs b/src/hyperlight_host/src/sandbox/outb.rs
@@ -241,9 +241,12 @@ mod tests {
 
         let new_mgr = || {
             let mut exe_info = simple_guest_exe_info().unwrap();
-            let mut mgr =
-                SandboxMemoryManager::load_guest_binary_into_memory(sandbox_cfg, &mut exe_info)
-                    .unwrap();
+            let mut mgr = SandboxMemoryManager::load_guest_binary_into_memory(
+                sandbox_cfg,
+                &mut exe_info,
+                None,
+            )
+            .unwrap();
             let mem_size = mgr.get_shared_mem_mut().mem_size();
             let layout = mgr.layout;
             let shared_mem = mgr.get_shared_mem_mut();
@@ -353,9 +356,12 @@ mod tests {
         tracing::subscriber::with_default(subscriber.clone(), || {
             let new_mgr = || {
                 let mut exe_info = simple_guest_exe_info().unwrap();
-                let mut mgr =
-                    SandboxMemoryManager::load_guest_binary_into_memory(sandbox_cfg, &mut exe_info)
-                        .unwrap();
+                let mut mgr = SandboxMemoryManager::load_guest_binary_into_memory(
+                    sandbox_cfg,
+                    &mut exe_info,
+                    None,
+                )
+                .unwrap();
                 let mem_size = mgr.get_shared_mem_mut().mem_size();
                 let layout = mgr.layout;
                 let shared_mem = mgr.get_shared_mem_mut();
diff --git a/src/hyperlight_host/src/sandbox/uninitialized.rs b/src/hyperlight_host/src/sandbox/uninitialized.rs
