Skip to main content

hyperlight_host/sandbox/snapshot/file/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2025 The Hyperlight Authors.
3
4//! OCI Image Layout serde for [`Snapshot`]. See
5//! `docs/snapshot-oci-format.md` for the on-disk format.
6
7mod config;
8mod digest;
9mod fsutil;
10mod media_types;
11pub(crate) mod reference;
12mod transport;
13
14use std::path::{Path, PathBuf};
15use std::sync::Arc;
16
17use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
18use oci_spec::image::{
19    Descriptor, DescriptorBuilder, ImageIndex, ImageIndexBuilder, ImageManifest,
20    ImageManifestBuilder, MediaType, SCHEMA_VERSION,
21};
22
23use self::config::{
24    Arch, CpuVendor, HostFunction, Hypervisor, MemoryLayout, OciSnapshotConfig, OciSnapshotLayer,
25};
26use self::digest::{Digest256, oci_digest, parse_oci_digest, verify_blob_bytes, verify_blob_file};
27use self::fsutil::{put_blob, put_blob_if_absent, read_bounded, replace_file_atomic};
28use self::media_types::{
29    ANNOTATION_ARCH, ANNOTATION_CPU, ANNOTATION_HYPERVISOR, ANNOTATION_REF_NAME,
30};
31pub(super) use self::media_types::{
32    MT_CONFIG_CURRENT, MT_CONFIG_V1, MT_CONFIG_V2, MT_CONFIG_V3, MT_CONFIG_V4, MT_CONFIG_V5,
33    MT_SNAPSHOT_CURRENT, MT_SNAPSHOT_V2, MT_TRANSPORT_CURRENT, MT_TRANSPORT_V1,
34    SNAPSHOT_ABI_VERSION,
35};
36use self::reference::{OciDigest, OciReference, OciTag};
37use super::memory::{MAX_SNAPSHOT_LAYERS, host_page_size};
38use super::{NextAction, Snapshot, SnapshotBlob, SnapshotMemory};
39use crate::mem::layout::SandboxMemoryLayout;
40use crate::mem::memory_region::MemoryRegionFlags;
41use crate::mem::shared_mem::{ReadonlySharedMemory, SharedMemory};
42
43pub(super) const OCI_LAYOUT_VERSION: &str = "1.0.0";
44
45/// Short golden-tag token for the host CPU vendor, or `None` if the
46/// goldens do not cover it. Exposed for the snapshot golden tests so
47/// they share the host crate's vendor detection.
48#[doc(hidden)]
49pub fn host_cpu_vendor_golden_tag() -> Option<&'static str> {
50    CpuVendor::current().golden_tag()
51}
52
53/// Maximum size of any JSON blob read from disk during load:
54/// `oci-layout`, `index.json`, the OCI image manifest, and the
55/// Hyperlight config blob. Bounds the allocation done before parsing.
56const MAX_JSON_BLOB_SIZE: u64 = 1024 * 1024;
57
58/// Reject a JSON artifact larger than the cap the loader reads with
59/// [`read_bounded`]. The writer holds to the same cap so every layout
60/// it writes can be read back. `what` names the artifact in the error.
61fn check_json_blob_size(what: &str, len: usize) -> crate::Result<()> {
62    if len as u64 > MAX_JSON_BLOB_SIZE {
63        return Err(crate::new_error!(
64            "{} of {} bytes exceeds the {} byte maximum for a snapshot artifact",
65            what,
66            len,
67            MAX_JSON_BLOB_SIZE
68        ));
69    }
70    Ok(())
71}
72
73/// Select one manifest descriptor from `index` by `reference`.
74///
75/// A tag matches the `org.opencontainers.image.ref.name` annotation
76/// and must be unique. A digest matches the manifest content digest.
77/// Identical manifests shared across tags select the first, since
78/// they are byte-for-byte equal.
79fn select_manifest<'a>(
80    index: &'a ImageIndex,
81    reference: &OciReference,
82    path: &Path,
83) -> crate::Result<&'a Descriptor> {
84    match reference {
85        OciReference::Tag(tag) => {
86            let mut matching = index.manifests().iter().filter(|d| {
87                d.annotations()
88                    .as_ref()
89                    .and_then(|a| a.get(ANNOTATION_REF_NAME))
90                    .map(|s| s.as_str() == tag.as_str())
91                    .unwrap_or(false)
92            });
93            match (matching.next(), matching.next()) {
94                (None, _) => {
95                    let known: Vec<&str> = index
96                        .manifests()
97                        .iter()
98                        .filter_map(|d| {
99                            d.annotations()
100                                .as_ref()
101                                .and_then(|a| a.get(ANNOTATION_REF_NAME))
102                                .map(|s| s.as_str())
103                        })
104                        .collect();
105                    Err(crate::new_error!(
106                        "no manifest tagged {:?} in OCI layout {:?}. Available tags: {:?}",
107                        tag.as_str(),
108                        path,
109                        known
110                    ))
111                }
112                (Some(_), Some(_)) => Err(crate::new_error!(
113                    "OCI layout {:?} has multiple manifests tagged {:?}; tags must be unique",
114                    path,
115                    tag.as_str()
116                )),
117                (Some(d), None) => Ok(d),
118            }
119        }
120        OciReference::Digest(digest) => index
121            .manifests()
122            .iter()
123            .find(|d| d.digest().to_string() == digest.as_str())
124            .ok_or_else(|| {
125                crate::new_error!(
126                    "no manifest with digest {} in OCI layout {:?}",
127                    digest.as_str(),
128                    path
129                )
130            }),
131    }
132}
133
134fn read_layout_marker(path: &Path) -> crate::Result<()> {
135    let layout_bytes = read_bounded(&path.join("oci-layout"), MAX_JSON_BLOB_SIZE)
136        .map_err(|e| crate::new_error!("failed to read oci-layout: {}", e))?;
137    let layout_json: serde_json::Value = serde_json::from_slice(&layout_bytes)
138        .map_err(|e| crate::new_error!("oci-layout is not valid JSON: {}", e))?;
139    let v = layout_json
140        .get("imageLayoutVersion")
141        .and_then(|v| v.as_str())
142        .ok_or_else(|| crate::new_error!("oci-layout missing imageLayoutVersion field"))?;
143    if v != OCI_LAYOUT_VERSION {
144        return Err(crate::new_error!(
145            "unsupported OCI image layout version {:?} (expected {:?})",
146            v,
147            OCI_LAYOUT_VERSION
148        ));
149    }
150    Ok(())
151}
152
153fn load_manifest(
154    path: &Path,
155    blobs_dir: &Path,
156    reference: &OciReference,
157    verify_blobs: bool,
158) -> crate::Result<ImageManifest> {
159    let index_bytes = read_bounded(&path.join("index.json"), MAX_JSON_BLOB_SIZE)
160        .map_err(|e| crate::new_error!("failed to read index.json: {}", e))?;
161    let index: ImageIndex = serde_json::from_slice(&index_bytes)
162        .map_err(|e| crate::new_error!("failed to parse index.json: {}", e))?;
163    if index.schema_version() != SCHEMA_VERSION {
164        return Err(crate::new_error!(
165            "unsupported OCI index schemaVersion {} (expected {})",
166            index.schema_version(),
167            SCHEMA_VERSION
168        ));
169    }
170    if let Some(media_type) = index.media_type()
171        && !matches!(media_type, MediaType::ImageIndex)
172    {
173        return Err(crate::new_error!(
174            "OCI index has unexpected media type {} (expected {})",
175            media_type.to_string(),
176            MediaType::ImageIndex.to_string()
177        ));
178    }
179    let manifest_desc = select_manifest(&index, reference, path)?;
180    if !matches!(manifest_desc.media_type(), MediaType::ImageManifest) {
181        return Err(crate::new_error!(
182            "manifest descriptor for {} has unexpected media type {} (expected {})",
183            reference,
184            manifest_desc.media_type().to_string(),
185            MediaType::ImageManifest.to_string()
186        ));
187    }
188    let manifest_bytes = load_blob(
189        "manifest",
190        blobs_dir,
191        manifest_desc,
192        MAX_JSON_BLOB_SIZE,
193        verify_blobs,
194    )?;
195    let manifest: ImageManifest = serde_json::from_slice(&manifest_bytes)
196        .map_err(|e| crate::new_error!("failed to parse OCI manifest JSON: {}", e))?;
197    if manifest.schema_version() != SCHEMA_VERSION {
198        return Err(crate::new_error!(
199            "unsupported OCI manifest schemaVersion {} (expected {})",
200            manifest.schema_version(),
201            SCHEMA_VERSION
202        ));
203    }
204    if let Some(media_type) = manifest.media_type()
205        && !matches!(media_type, MediaType::ImageManifest)
206    {
207        return Err(crate::new_error!(
208            "OCI manifest has unexpected media type {} (expected {})",
209            media_type.to_string(),
210            MediaType::ImageManifest.to_string()
211        ));
212    }
213    Ok(manifest)
214}
215
216fn load_config(
217    blobs_dir: &Path,
218    cfg_desc: &Descriptor,
219    verify_blobs: bool,
220) -> crate::Result<OciSnapshotConfig> {
221    let cfg_bytes = load_blob(
222        "config",
223        blobs_dir,
224        cfg_desc,
225        MAX_JSON_BLOB_SIZE,
226        verify_blobs,
227    )?;
228    let cfg: OciSnapshotConfig = serde_json::from_slice(&cfg_bytes)
229        .map_err(|e| crate::new_error!("failed to parse Hyperlight config JSON: {}", e))?;
230    cfg.validate_for_load()?;
231    Ok(cfg)
232}
233
234fn open_snapshot_blob(blobs_dir: &Path, snap_desc: &Descriptor) -> crate::Result<std::fs::File> {
235    let snap_hex = parse_oci_digest(snap_desc.digest())?;
236    let snap_path = blobs_dir.join(&snap_hex);
237
238    let snap_file = self::fsutil::open_no_follow(&snap_path)?;
239
240    let snap_file_len = snap_file
241        .metadata()
242        .map_err(|e| crate::new_error!("failed to stat snapshot blob: {}", e))?
243        .len();
244    if snap_file_len != snap_desc.size() {
245        return Err(crate::new_error!(
246            "snapshot blob size {} disagrees with OCI descriptor size {}",
247            snap_file_len,
248            snap_desc.size()
249        ));
250    }
251    Ok(snap_file)
252}
253
254/// The size validation in `open_snapshot_blob` stats the file before
255/// mapping. Nothing prevents the file from being truncated between that
256/// stat and the mmap, which would leave the mapping shorter than the
257/// descriptor claims and make restore read past the end. Compare the mapped
258/// length against the descriptor to reject a file mutated under us.
259fn map_snapshot_blob(
260    snap_file: &std::fs::File,
261    snap_desc: &Descriptor,
262    data_len: usize,
263) -> crate::Result<ReadonlySharedMemory> {
264    let memory = ReadonlySharedMemory::from_file(snap_file, data_len)?;
265    if memory.mem_size() as u64 != snap_desc.size() {
266        return Err(crate::new_error!(
267            "mapped snapshot size ({}) does not match descriptor size ({}); the blob may have changed during loading",
268            memory.mem_size(),
269            snap_desc.size()
270        ));
271    }
272    Ok(memory)
273}
274
275/// Read a bounded OCI blob and check its descriptor size and optional digest.
276fn load_blob(
277    label: &str,
278    blobs_dir: &Path,
279    descriptor: &Descriptor,
280    max_size: u64,
281    verify_blobs: bool,
282) -> crate::Result<Vec<u8>> {
283    let hex = parse_oci_digest(descriptor.digest())?;
284    let bytes = read_bounded(&blobs_dir.join(&hex), max_size)?;
285    if bytes.len() as u64 != descriptor.size() {
286        return Err(crate::new_error!(
287            "{label} blob size mismatch: descriptor says {}, file is {}",
288            descriptor.size(),
289            bytes.len()
290        ));
291    }
292    if verify_blobs {
293        verify_blob_bytes(label, &bytes, &hex)?;
294    }
295    Ok(bytes)
296}
297
298fn blob_descriptor(media_type: &str, digest: &Digest256, size: usize) -> crate::Result<Descriptor> {
299    DescriptorBuilder::default()
300        .media_type(MediaType::Other(media_type.to_string()))
301        .digest(oci_digest(digest)?)
302        .size(size as u64)
303        .build()
304        .map_err(|e| crate::new_error!("failed to build {media_type} descriptor: {e}"))
305}
306
307impl Snapshot {
308    /// Save this snapshot into an OCI Image Layout directory on disk.
309    /// The saved snapshot can be loaded later with
310    /// [`Snapshot::load`].
311    ///
312    /// Returns the [`OciDigest`] of the manifest that was written,
313    /// which [`Snapshot::load`] accepts as a stable handle to
314    /// this exact snapshot.
315    ///
316    /// # `path`
317    ///
318    /// The OCI Image Layout directory to write to. The directory at
319    /// `path` is created if absent. Its parent directory must exist.
320    ///
321    /// If `path` holds no OCI layout, a new one is created. If it
322    /// holds one, this snapshot is added alongside the others. If
323    /// `path` holds something that is not a readable OCI layout, the
324    /// call fails and the directory is left unchanged.
325    ///
326    /// # `tag`
327    ///
328    /// A standard OCI tag that names this snapshot within the layout.
329    /// [`Snapshot::load`] can load the snapshot back by this tag.
330    ///
331    /// A tag points to one snapshot at a time. If the layout has a
332    /// snapshot under this tag, the tag is moved to the new snapshot.
333    /// The old snapshot's data stays on disk, reachable by its
334    /// digest but not by this tag. Snapshots under other tags are
335    /// untouched.
336    ///
337    /// # Portability
338    ///
339    /// Snapshot images are bound to the specific CPU architecture,
340    /// hypervisor, and CPU vendor that the snapshot was created on.
341    /// For example, a snapshot taken on an Intel x86_64 host with KVM
342    /// can only be loaded on an Intel x86_64 host running KVM. Loading
343    /// on any other host is rejected. A future version may relax this
344    /// binding once a wider compatibility set is proven safe.
345    ///
346    /// # Compatibility
347    ///
348    /// While Hyperlight is at version 0.x.y the on-disk format is not
349    /// stable. A snapshot written by one Hyperlight version is not
350    /// guaranteed to load on a different Hyperlight version. An
351    /// incompatible snapshot is always rejected at load time with a
352    /// clear error. It can never load and then misbehave once the
353    /// guest is running. Any release that breaks the format is called
354    /// out in the Hyperlight changelog.
355    ///
356    /// # Examples
357    ///
358    /// ```no_run
359    /// # use hyperlight_host::SandboxBuilder;
360    /// # use hyperlight_host::sandbox::snapshot::OciTag;
361    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
362    /// let mut sandbox = SandboxBuilder::from_file("guest.bin").build()?;
363    ///
364    /// // Capture the initialized state and write it to an OCI layout on disk.
365    /// let snapshot = sandbox.snapshot()?;
366    /// let tag = OciTag::new("latest")?;
367    /// let digest = snapshot.save("./guest_snapshot", &tag)?;
368    /// # Ok(())
369    /// # }
370    /// ```
371    pub fn save(&self, path: impl AsRef<Path>, tag: &OciTag) -> crate::Result<OciDigest> {
372        let path = path.as_ref();
373
374        // Building the config can reject the snapshot. Do it before
375        // writing any file.
376        let cfg = self.build_config()?;
377        let cfg_bytes = serde_json::to_vec_pretty(&cfg)
378            .map_err(|e| crate::new_error!("failed to serialise config JSON: {}", e))?;
379        check_json_blob_size("config blob", cfg_bytes.len())?;
380
381        // The parent directory must already exist. `path` itself is
382        // created if absent. An existing regular file at `path` is
383        // rejected by the underlying `create_dir`.
384        match path.parent() {
385            Some(p) if !p.as_os_str().is_empty() => {
386                let parent_meta = std::fs::metadata(p).map_err(|e| {
387                    crate::new_error!("save: parent directory {:?} not accessible: {}", p, e)
388                })?;
389                if !parent_meta.is_dir() {
390                    return Err(crate::new_error!(
391                        "save: parent of {:?} is not a directory",
392                        path
393                    ));
394                }
395            }
396            _ => {}
397        }
398        match std::fs::create_dir(path) {
399            Ok(()) => {}
400            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
401                let meta = std::fs::metadata(path)
402                    .map_err(|e| crate::new_error!("save: failed to stat {:?}: {}", path, e))?;
403                if !meta.is_dir() {
404                    return Err(crate::new_error!(
405                        "save: {:?} exists and is not a directory",
406                        path
407                    ));
408                }
409            }
410            Err(e) => {
411                return Err(crate::new_error!(
412                    "save: failed to create layout dir {:?}: {}",
413                    path,
414                    e
415                ));
416            }
417        }
418
419        // Validate any pre-existing `oci-layout` marker before
420        // touching anything else, so a foreign layout (future
421        // version, hand-edited file) is reported without altering
422        // the directory.
423        let layout_marker = path.join("oci-layout");
424        let marker_existed = layout_marker
425            .try_exists()
426            .map_err(|e| crate::new_error!("save: failed to stat {:?}: {}", layout_marker, e))?;
427        if marker_existed {
428            let bytes = read_bounded(&layout_marker, MAX_JSON_BLOB_SIZE).map_err(|e| {
429                crate::new_error!("save: failed to read existing oci-layout: {}", e)
430            })?;
431            let v: serde_json::Value = serde_json::from_slice(&bytes).map_err(|e| {
432                crate::new_error!("save: existing oci-layout is not valid JSON: {}", e)
433            })?;
434            match v.get("imageLayoutVersion").and_then(|s| s.as_str()) {
435                Some(s) if s == OCI_LAYOUT_VERSION => {}
436                Some(other) => {
437                    return Err(crate::new_error!(
438                        "save: existing imageLayoutVersion {:?} is unsupported (expected {:?})",
439                        other,
440                        OCI_LAYOUT_VERSION
441                    ));
442                }
443                None => {
444                    return Err(crate::new_error!(
445                        "save: existing oci-layout is missing imageLayoutVersion"
446                    ));
447                }
448            }
449        }
450
451        let index_path = path.join("index.json");
452        let index_existed = index_path
453            .try_exists()
454            .map_err(|e| crate::new_error!("save: failed to stat {:?}: {}", index_path, e))?;
455        let mut manifests: Vec<Descriptor> = if index_existed {
456            let bytes = read_bounded(&index_path, MAX_JSON_BLOB_SIZE).map_err(|e| {
457                crate::new_error!("save: failed to read existing index.json: {}", e)
458            })?;
459            let existing: ImageIndex = serde_json::from_slice(&bytes).map_err(|e| {
460                crate::new_error!(
461                    "save: existing index.json is not a valid OCI image index: {}",
462                    e
463                )
464            })?;
465            existing.manifests().to_vec()
466        } else {
467            Vec::new()
468        };
469
470        let new_desc = self.write_blobs_and_build_descriptor(path, tag, &cfg, &cfg_bytes)?;
471        let written_digest = OciDigest::from_oci_spec_digest(new_desc.digest());
472
473        // Replacement is by tag, not by digest: a new snapshot may
474        // hash to a different value but still claim the same logical
475        // ref. Blobs from the replaced manifest become orphans.
476        manifests.retain(|d| {
477            d.annotations()
478                .as_ref()
479                .and_then(|a| a.get(ANNOTATION_REF_NAME))
480                .map(|s| s.as_str() != tag.as_str())
481                .unwrap_or(true)
482        });
483        manifests.push(new_desc);
484
485        let index = ImageIndexBuilder::default()
486            .schema_version(SCHEMA_VERSION)
487            .media_type(MediaType::ImageIndex)
488            .manifests(manifests)
489            .build()
490            .map_err(|e| crate::new_error!("failed to build OCI index: {}", e))?;
491        let index_bytes = serde_json::to_vec_pretty(&index)
492            .map_err(|e| crate::new_error!("failed to serialise OCI index: {}", e))?;
493        check_json_blob_size("index.json", index_bytes.len())?;
494
495        // Write the marker before the index swap. A loader that sees
496        // the new index requires the marker; ordering them this way
497        // keeps the layout valid at every step.
498        if !marker_existed {
499            let layout_bytes = serde_json::to_vec(&serde_json::json!({
500                "imageLayoutVersion": OCI_LAYOUT_VERSION,
501            }))
502            .map_err(|e| crate::new_error!("failed to serialise oci-layout: {}", e))?;
503            replace_file_atomic(&layout_marker, &layout_bytes)?;
504        }
505
506        // Index swap is the commit point.
507        replace_file_atomic(&index_path, &index_bytes)?;
508
509        Ok(written_digest)
510    }
511
512    fn write_blobs_and_build_descriptor(
513        &self,
514        dir: &Path,
515        tag: &OciTag,
516        cfg: &OciSnapshotConfig,
517        cfg_bytes: &[u8],
518    ) -> crate::Result<Descriptor> {
519        let blobs_dir = dir.join("blobs").join("sha256");
520        std::fs::create_dir_all(&blobs_dir).map_err(|e| {
521            crate::new_error!("failed to create OCI blobs dir {:?}: {}", blobs_dir, e)
522        })?;
523
524        let mut descriptors = self
525            .state
526            .memory
527            .blobs()
528            .map(|blob| {
529                let bytes = blob.memory().as_slice();
530                let digest = Digest256::from_bytes(bytes);
531                put_blob_if_absent(&blobs_dir, &digest, bytes)?;
532                blob_descriptor(MT_SNAPSHOT_CURRENT, &digest, bytes.len())
533            })
534            .collect::<crate::Result<Vec<_>>>()?;
535
536        // Transport blob: the canonical ring image omitted from memory.
537        let transport = self.state.virtq.as_ref().ok_or_else(|| {
538            crate::new_error!("initialized snapshot has no canonical transport state")
539        })?;
540        let transport_bytes = transport::encode(&self.state.layout, transport)?;
541        let transport_digest = Digest256::from_bytes(&transport_bytes);
542        put_blob(&blobs_dir, &transport_digest, &transport_bytes)?;
543        descriptors.push(blob_descriptor(
544            MT_TRANSPORT_CURRENT,
545            &transport_digest,
546            transport_bytes.len(),
547        )?);
548
549        // Config blob.
550        let cfg_digest = Digest256::from_bytes(cfg_bytes);
551        put_blob(&blobs_dir, &cfg_digest, cfg_bytes)?;
552
553        // Manifest blob.
554        let config_descriptor = blob_descriptor(MT_CONFIG_CURRENT, &cfg_digest, cfg_bytes.len())?;
555        // `artifactType` is set equal to `config.mediaType` per OCI
556        // image-spec "Guidelines for Artifact Usage". Registries
557        // surface this on the distribution-spec referrers API. Tools
558        // that read only `config.mediaType` see the same value.
559        let manifest = ImageManifestBuilder::default()
560            .schema_version(SCHEMA_VERSION)
561            .media_type(MediaType::ImageManifest)
562            .artifact_type(MediaType::Other(MT_CONFIG_CURRENT.to_string()))
563            .config(config_descriptor)
564            .layers(descriptors)
565            .build()
566            .map_err(|e| crate::new_error!("failed to build OCI manifest: {}", e))?;
567        let manifest_bytes = serde_json::to_vec_pretty(&manifest)
568            .map_err(|e| crate::new_error!("failed to serialise OCI manifest: {}", e))?;
569        check_json_blob_size("manifest blob", manifest_bytes.len())?;
570        let manifest_digest = Digest256::from_bytes(&manifest_bytes);
571        put_blob(&blobs_dir, &manifest_digest, &manifest_bytes)?;
572
573        let mut anns = std::collections::HashMap::new();
574        anns.insert(ANNOTATION_REF_NAME.to_string(), tag.as_str().to_string());
575        anns.insert(ANNOTATION_ARCH.to_string(), cfg.arch.as_str().to_string());
576        anns.insert(
577            ANNOTATION_HYPERVISOR.to_string(),
578            cfg.hypervisor.as_str().to_string(),
579        );
580        anns.insert(
581            ANNOTATION_CPU.to_string(),
582            cfg.cpu_vendor.as_str().to_string(),
583        );
584        DescriptorBuilder::default()
585            .media_type(MediaType::ImageManifest)
586            .digest(oci_digest(&manifest_digest)?)
587            .size(manifest_bytes.len() as u64)
588            .annotations(anns)
589            .build()
590            .map_err(|e| crate::new_error!("failed to build manifest descriptor: {}", e))
591    }
592
593    fn build_config(&self) -> crate::Result<OciSnapshotConfig> {
594        let (entrypoint_addr, sregs) = match (self.state.next_action, self.state.sregs.as_ref()) {
595            (NextAction::Call(addr), Some(sregs)) => (addr, sregs),
596            (NextAction::Call(_), None) => {
597                return Err(crate::new_error!(
598                    "snapshot inconsistent: Call entrypoint must have sregs"
599                ));
600            }
601            (NextAction::Initialise(_), _) => {
602                return Err(crate::new_error!(
603                    "pre-init snapshots cannot be persisted. Only a snapshot taken after the guest has run can be saved to disk"
604                ));
605            }
606            #[cfg(test)]
607            (NextAction::None, _) => {
608                return Err(crate::new_error!(
609                    "snapshot with NextAction::None cannot be persisted"
610                ));
611            }
612        };
613
614        if self.state.virtq.is_none() {
615            return Err(crate::new_error!(
616                "initialized snapshot has no canonical transport state"
617            ));
618        }
619
620        let host_functions = match &self.state.host_functions.host_functions {
621            Some(v) => v.iter().map(HostFunction::from).collect(),
622            None => Vec::new(),
623        };
624
625        let l = &self.state.layout;
626        Ok(OciSnapshotConfig {
627            hyperlight_version: env!("CARGO_PKG_VERSION").to_string(),
628            arch: Arch::current(),
629            abi_version: SNAPSHOT_ABI_VERSION,
630            hypervisor: Hypervisor::current()
631                .ok_or_else(|| crate::new_error!("no hypervisor available to tag snapshot"))?,
632            cpu_vendor: CpuVendor::current(),
633            layer_alignment: host_page_size(),
634            stack_top_gva: self.state.stack_top_gva,
635            entrypoint_addr,
636            original_entrypoint_addr: self.state.original_entrypoint,
637            sregs: *sregs,
638            #[cfg(target_arch = "x86_64")]
639            msrs: self
640                .state
641                .msrs
642                .as_ref()
643                .ok_or_else(|| crate::new_error!("snapshot has no MSR state"))?
644                .clone(),
645            layout: MemoryLayout {
646                code_size: l.code_size(),
647                code_virt_base: l.get_guest_code_gva() as u64,
648                init_data_size: l.init_data_size(),
649                init_data_permissions: l.init_data_permissions().map(|f| f.bits()),
650                scratch_size: l.get_scratch_size(),
651                g2h_queue_size: l.get_g2h_queue_size(),
652                h2g_queue_size: l.get_h2g_queue_size(),
653                g2h_buffer_size: l.get_g2h_buffer_size(),
654                h2g_buffer_size: l.get_h2g_buffer_size(),
655                g2h_pool_pages: l.get_g2h_pool_pages(),
656                h2g_pool_pages: l.get_h2g_pool_pages(),
657            },
658            layers: self
659                .state
660                .memory
661                .blobs()
662                .map(OciSnapshotLayer::from)
663                .collect(),
664            page_table_layer: self
665                .state
666                .memory
667                .blobs()
668                .position(|blob| Arc::ptr_eq(blob, self.state.memory.page_table_blob()))
669                .ok_or_else(|| crate::new_error!("snapshot page-table blob is missing"))?,
670            host_functions,
671            snapshot_generation: self.state.snapshot_generation,
672            metadata: self.metadata.clone(),
673        })
674    }
675
676    /// Load a snapshot from an OCI Image Layout directory produced by
677    /// [`Snapshot::save`].
678    ///
679    /// # `path`
680    ///
681    /// The OCI Image Layout directory to read from. It must hold a
682    /// readable OCI layout containing at least one Hyperlight
683    /// snapshot.
684    ///
685    /// # `reference`
686    ///
687    /// Determines which snapshot in the layout to load, given as
688    /// either an [`OciTag`] or an [`OciDigest`]. Loading fails if no
689    /// snapshot in the layout has the given tag or digest.
690    ///
691    /// # Portability
692    ///
693    /// Snapshot images are bound to the specific CPU architecture,
694    /// hypervisor, and CPU vendor that the snapshot was created on.
695    /// For example, a snapshot taken on an Intel x86_64 host with KVM
696    /// can only be loaded on an Intel x86_64 host running KVM. Loading
697    /// on any other host is rejected. A future version may relax this
698    /// binding once a wider compatibility set is proven safe.
699    ///
700    /// # Compatibility
701    ///
702    /// While Hyperlight is at version 0.x.y the on-disk format is not
703    /// stable. A snapshot written by one Hyperlight version is not
704    /// guaranteed to load on a different Hyperlight version. An
705    /// incompatible snapshot is always rejected at load time with a
706    /// clear error. It can never load and then misbehave once the
707    /// guest is running. Any release that breaks the format is called
708    /// out in the Hyperlight changelog.
709    ///
710    /// # Verification
711    ///
712    /// This method does not check the manifest, config, memory, or transport
713    /// blobs against their recorded sha256 digests. Load only from a
714    /// layout you trust.
715    ///
716    /// To check the digests on load at the expense of some
717    /// performance, use [`Snapshot::checked_load`].
718    ///
719    /// # File-mutation hazard
720    ///
721    /// The snapshot blob stays memory-mapped while the returned
722    /// `Snapshot` or any sandbox built from it is alive. The existing
723    /// blob files in the layout at `path` must not be overwritten,
724    /// truncated, or deleted while the mapping is live. Doing so can
725    /// corrupt guest memory and can lead to undefined behavior.
726    ///
727    /// # Examples
728    ///
729    /// ```no_run
730    /// # use std::sync::Arc;
731    /// # use hyperlight_host::{HostFunctions, Sandbox};
732    /// # use hyperlight_host::sandbox::snapshot::{OciTag, Snapshot};
733    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
734    /// let tag = OciTag::new("latest")?;
735    /// let snapshot = Arc::new(Snapshot::load("./guest_snapshot", tag)?);
736    /// let mut sandbox = Sandbox::from_snapshot(snapshot, HostFunctions::default(), None)?;
737    /// let result: String = sandbox.call("Echo", "hello".to_string())?;
738    /// # Ok(())
739    /// # }
740    /// ```
741    pub fn load(path: impl AsRef<Path>, reference: impl Into<OciReference>) -> crate::Result<Self> {
742        Self::load_inner(path.as_ref(), &reference.into(), false)
743    }
744
745    /// Loads a snapshot like [`Snapshot::load`]. See its rustdoc for
746    /// `path`, `reference`, portability, and the file-mutation
747    /// hazard. This method additionally checks the manifest, config,
748    /// memory, and transport blobs against their recorded sha256 digests
749    /// before use, at the expense of some performance.
750    ///
751    /// # Trust
752    ///
753    /// A digest check does not prove the bytes are authentic. Anyone
754    /// who edits a blob can recompute its digest to match, so a
755    /// hostile layout passes the check. Load only from a source you
756    /// trust.
757    pub fn checked_load(
758        path: impl AsRef<Path>,
759        reference: impl Into<OciReference>,
760    ) -> crate::Result<Self> {
761        Self::load_inner(path.as_ref(), &reference.into(), true)
762    }
763
764    fn load_inner(
765        path: &Path,
766        reference: &OciReference,
767        verify_blobs: bool,
768    ) -> crate::Result<Self> {
769        let meta = std::fs::metadata(path)
770            .map_err(|e| crate::new_error!("load failed to stat {:?}: {}", path, e))?;
771        if !meta.is_dir() {
772            return Err(crate::new_error!("load path {:?} is not a directory", path));
773        }
774
775        let blobs_dir: PathBuf = path.join("blobs").join("sha256");
776
777        // 1. oci-layout
778        read_layout_marker(path)?;
779
780        // 2. index.json -> manifest descriptor for `reference`.
781        //    Multiple manifests are valid in an OCI Image Layout. A
782        //    tag selects the one whose
783        //    `org.opencontainers.image.ref.name` annotation matches it
784        //    (two manifests sharing a tag is a malformed layout). A
785        //    digest selects the descriptor carrying that manifest
786        //    digest.
787        let manifest = load_manifest(path, &blobs_dir, reference, verify_blobs)?;
788        let cfg_desc = manifest.config();
789        // Loader dispatch on config media type.
790        let cfg_media = cfg_desc.media_type().to_string();
791        match cfg_media.as_str() {
792            MT_CONFIG_V5 => {}
793            MT_CONFIG_V1 | MT_CONFIG_V2 | MT_CONFIG_V3 | MT_CONFIG_V4 => {
794                return Err(crate::new_error!(
795                    "snapshot config media type {:?} is incompatible with snapshot ABI {}",
796                    cfg_media,
797                    SNAPSHOT_ABI_VERSION
798                ));
799            }
800            other => {
801                return Err(crate::new_error!(
802                    "unexpected config media type {:?} (supported: {:?})",
803                    other,
804                    MT_CONFIG_V5
805                ));
806            }
807        }
808        // `artifactType` mirrors `config.mediaType` (manifest.md
809        // "Guidelines for Artifact Usage"). The OCI spec leaves this
810        // field OPTIONAL. A Hyperlight snapshot requires it to be
811        // present and equal to `config.mediaType` so loaders can
812        // distinguish a Hyperlight artifact from an arbitrary
813        // manifest that happens to share blob layout.
814        match manifest.artifact_type() {
815            Some(at) if at.to_string() == cfg_media => {}
816            Some(at) => {
817                return Err(crate::new_error!(
818                    "OCI manifest artifactType {:?} does not match config media type {:?}",
819                    at.to_string(),
820                    cfg_media
821                ));
822            }
823            None => {
824                return Err(crate::new_error!(
825                    "OCI manifest is missing required artifactType (expected {:?})",
826                    cfg_media
827                ));
828            }
829        }
830        let layers = manifest.layers();
831        let (data_descs, tail) = layers.split_at(layers.len().saturating_sub(1));
832        let [transport_desc] = tail else {
833            return Err(crate::new_error!(
834                "expected snapshot layers and one transport layer, found {} layers",
835                layers.len()
836            ));
837        };
838        for snap_desc in data_descs {
839            let snap_media = snap_desc.media_type().to_string();
840            match snap_media.as_str() {
841                MT_SNAPSHOT_V2 => {}
842                other => {
843                    return Err(crate::new_error!(
844                        "unexpected snapshot layer media type {:?} (supported: {:?})",
845                        other,
846                        MT_SNAPSHOT_V2
847                    ));
848                }
849            }
850        }
851        let transport_media = transport_desc.media_type().to_string();
852        match transport_media.as_str() {
853            MT_TRANSPORT_V1 => {}
854            other => {
855                return Err(crate::new_error!(
856                    "unexpected transport layer media type {:?} (supported: {:?})",
857                    other,
858                    MT_TRANSPORT_V1
859                ));
860            }
861        }
862
863        // 4. config blob
864        let cfg = load_config(&blobs_dir, cfg_desc, verify_blobs)?;
865        // A snapshot taken on a host with smaller pages may have a scratch
866        // size this host cannot map: refuse it before reading the blobs.
867        let host_page = crate::mem::layout::SandboxMemoryLayout::host_page_size();
868        if !cfg.layout.scratch_size.is_multiple_of(host_page) {
869            return Err(crate::new_error!(
870                "snapshot scratch size {} is not a multiple of this host's {host_page}-byte pages",
871                cfg.layout.scratch_size
872            ));
873        }
874        // Each data layer has one mapping, and one more blob may hold only page
875        // tables. Reject before opening blobs.
876        if cfg.layers.len() > MAX_SNAPSHOT_LAYERS + 1 {
877            return Err(crate::new_error!(
878                "snapshot has {} data layers, limit is {}",
879                cfg.layers.len(),
880                MAX_SNAPSHOT_LAYERS + 1
881            ));
882        }
883        if data_descs.len() != cfg.layers.len() {
884            return Err(crate::new_error!(
885                "expected {} snapshot layers and one transport layer, found {} layers",
886                cfg.layers.len(),
887                layers.len()
888            ));
889        }
890        if cfg.page_table_layer >= cfg.layers.len() {
891            return Err(crate::new_error!(
892                "snapshot page_table_layer {} is out of range",
893                cfg.page_table_layer
894            ));
895        }
896
897        // Reject blob sizes no valid snapshot has before opening any blob.
898        // Guest data must fit between BASE_ADDRESS and scratch without
899        // overlapping. Page tables must fit in scratch, which is at most
900        // MAX_MEMORY_SIZE.
901        let data_space = hyperlight_common::layout::scratch_base_gpa(cfg.layout.scratch_size)
902            .saturating_sub(SandboxMemoryLayout::BASE_ADDRESS as u64);
903        let mut data_bytes = 0u64;
904        for (index, (layer, desc)) in cfg.layers.iter().zip(data_descs).enumerate() {
905            if layer.data_len == 0 && index != cfg.page_table_layer {
906                return Err(crate::new_error!("snapshot layer {} has no data", index));
907            }
908            let blob_len = layer
909                .data_len
910                .checked_add(layer.page_table_len)
911                .filter(|_| layer.page_table_len <= SandboxMemoryLayout::MAX_MEMORY_SIZE)
912                .and_then(|len| len.checked_next_multiple_of(host_page_size()));
913            if blob_len.is_none_or(|len| len as u64 != desc.size()) {
914                return Err(crate::new_error!(
915                    "snapshot layer {} size {} does not match its data and page-table lengths",
916                    index,
917                    desc.size()
918                ));
919            }
920            data_bytes = data_bytes
921                .checked_add(layer.data_len as u64)
922                .filter(|bytes| *bytes <= data_space)
923                .ok_or_else(|| {
924                    crate::new_error!(
925                        "snapshot data exceeds the {} bytes below scratch",
926                        data_space
927                    )
928                })?;
929        }
930
931        // 5. snapshot blobs: open each once, hash and mmap the same
932        //    handle so an attacker cannot swap the file between
933        //    verification and mapping.
934        let mut snap_files = data_descs
935            .iter()
936            .map(|desc| open_snapshot_blob(&blobs_dir, desc))
937            .collect::<crate::Result<Vec<_>>>()?;
938        let transport_bytes = load_blob(
939            "transport",
940            &blobs_dir,
941            transport_desc,
942            transport::MAX_BLOB_SIZE,
943            verify_blobs,
944        )?;
945
946        // 6. Reconstruct layout.
947        let mut sbox_cfg = crate::sandbox::SandboxConfiguration::default();
948        sbox_cfg.set_scratch_size(cfg.layout.scratch_size);
949        sbox_cfg.set_g2h_queue_size(cfg.layout.g2h_queue_size);
950        sbox_cfg.set_h2g_queue_size(cfg.layout.h2g_queue_size);
951        sbox_cfg.set_g2h_buffer_size(cfg.layout.g2h_buffer_size);
952        sbox_cfg.set_h2g_buffer_size(cfg.layout.h2g_buffer_size);
953        sbox_cfg.set_g2h_pool_pages(cfg.layout.g2h_pool_pages);
954        sbox_cfg.set_h2g_pool_pages(cfg.layout.h2g_pool_pages);
955        let init_data_perms = match cfg.layout.init_data_permissions {
956            None => None,
957            Some(bits) => Some(MemoryRegionFlags::from_bits(bits).ok_or_else(|| {
958                crate::new_error!(
959                    "snapshot init_data_permissions {:#x} contains unknown flag bits",
960                    bits
961                )
962            })?),
963        };
964        let mut layout = SandboxMemoryLayout::new(
965            sbox_cfg,
966            cfg.layout.code_size,
967            cfg.layout.init_data_size,
968            init_data_perms,
969        )?;
970        let code_gva = if cfg.layout.code_virt_base == 0 {
971            layout.get_guest_code_gpa() as u64
972        } else {
973            cfg.layout.code_virt_base
974        };
975        layout.set_code_gva(code_gva)?;
976        layout.ensure_page_tables_fit(cfg.layers[cfg.page_table_layer].page_table_len)?;
977
978        let virtq = transport::decode(&layout, &transport_bytes)?;
979
980        // 7. mmap the snapshot blobs (file-backed CoW). Each blob is
981        //    a raw memory image. `ReadonlySharedMemory::from_file`
982        //    surrounds it with host guard pages. The guest mapping
983        //    of each blob covers only the data prefix (`data_len`)
984        //    at its layer's GPA. The PT tail sits past that prefix
985        //    in the host mapping. Restore copies the tail of the
986        //    page-table layer into the scratch region. Keeping PT
987        //    tails out of the guest mapping avoids overlap with the
988        //    next layer and with `map_file_cow` regions installed
989        //    immediately after the snapshot in guest PA space.
990        let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
991        let blobs = cfg
992            .layers
993            .iter()
994            .zip(data_descs)
995            .zip(&snap_files)
996            .map(|((layer, desc), file)| {
997                Ok(Arc::new(SnapshotBlob::new(
998                    map_snapshot_blob(file, desc, layer.data_len)?,
999                    layer.gpa_start,
1000                    layer.page_table_len,
1001                    scratch_base,
1002                )?))
1003            })
1004            .collect::<crate::Result<Vec<_>>>()?;
1005        let page_tables = blobs[cfg.page_table_layer].clone();
1006        let data_layers = blobs
1007            .into_iter()
1008            .filter(|blob| blob.data_len() > 0)
1009            .collect();
1010        let memory = Arc::new(SnapshotMemory::new(data_layers, page_tables)?);
1011        // Hash after validating the layers so malformed snapshots fail
1012        // cheaply.
1013        if verify_blobs {
1014            for (desc, file) in data_descs.iter().zip(&mut snap_files) {
1015                verify_blob_file("snapshot", file, &parse_oci_digest(desc.digest())?)?;
1016            }
1017        }
1018
1019        // The snapshot GPA span must cover at least the regions the
1020        // layout fields describe (code, PEB, init data),
1021        // otherwise the guest mapping is too short to back them.
1022        let required_memory_size = layout.get_memory_size()?;
1023        if memory.gpa_span_len() < required_memory_size {
1024            return Err(crate::new_error!(
1025                "snapshot GPA span ({}) is smaller than the layout size ({})",
1026                memory.gpa_span_len(),
1027                required_memory_size
1028            ));
1029        }
1030
1031        // 8. Build the next action + sregs back from the config.
1032        let next_action = NextAction::Call(cfg.entrypoint_addr);
1033
1034        // 9. Reconstitute host_functions metadata.
1035        let snapshot_generation = cfg.snapshot_generation;
1036        let host_funcs_vec: Vec<
1037            hyperlight_common::flatbuffer_wrappers::host_function_definition::HostFunctionDefinition,
1038        > = cfg.host_functions.into_iter().map(Into::into).collect();
1039        let host_functions = if host_funcs_vec.is_empty() {
1040            HostFunctionDetails {
1041                host_functions: None,
1042            }
1043        } else {
1044            HostFunctionDetails {
1045                host_functions: Some(host_funcs_vec),
1046            }
1047        };
1048
1049        Ok(Snapshot {
1050            state: std::sync::Arc::new(super::SnapshotState {
1051                layout,
1052                memory,
1053                load_info: crate::mem::exe::LoadInfo::dummy(),
1054                stack_top_gva: cfg.stack_top_gva,
1055                sregs: Some(cfg.sregs),
1056                #[cfg(target_arch = "x86_64")]
1057                msrs: Some(cfg.msrs),
1058                next_action,
1059                original_entrypoint: cfg.original_entrypoint_addr,
1060                snapshot_generation,
1061                host_functions,
1062                virtq: Some(virtq),
1063            }),
1064            metadata: cfg.metadata,
1065        })
1066    }
1067}