This article describes how PolkaVM integrates with host operating systems, focusing on sandboxing, isolation mechanisms, and system call interfaces. It covers the architecture of the sandboxing system, the communication between the host and sandbox processes, and platform-specific implementations.

For information about how to execute guest programs within PolkaVM, see Execution Flow.

Host and Sandbox Process Architecture

PolkaVM uses a multi-process architecture to provide strong isolation between guest code and the host system. This approach provides stronger security guarantees than in-process isolation techniques.

Sources:

Linux-specific Implementation

PolkaVM provides a specialized Linux sandbox implementation that leverages various Linux-specific features to provide strong isolation and security guarantees.

Zygote Process

The zygote process is a pre-initialized template process that is forked to create new sandbox instances quickly. This approach is similar to what Android uses for launching applications.

Sources:

Sandbox Creation Process

The Linux sandbox implementation uses a multi-step process to create a secure, isolated environment:

  1. Prepare Zygote: The host creates a memory file descriptor (memfd) containing the zygote binary
  2. Clone Process: A new process is created with isolated namespaces
  3. Initialize Child: The child process initializes its environment:
    • Sets up signal handlers
    • Maps shared memory regions
    • Prepares memory protection
    • Configures seccomp filters
  4. Execute Zygote: The child process executes the zygote binary
  5. Load Module: The host loads a module into the sandbox
  6. Execute Code: The sandbox executes the guest code

Sources:

Linux Security Mechanisms

PolkaVM leverages several Linux-specific security mechanisms:

Namespaces Isolation

Sources:

Resource Limits

The sandbox implements tight resource limits:

Resource Limit Purpose
RLIMIT_DATA 8 GB Maximum data segment size
RLIMIT_STACK 16 KB Maximum stack size
RLIMIT_NPROC 1 Prevent process creation
RLIMIT_FSIZE 0 Prevent file creation
RLIMIT_LOCKS 0 Prevent file locks
RLIMIT_MEMLOCK 0 Prevent memory locking
RLIMIT_MSGQUEUE 0 Prevent message queue usage

Sources:

Seccomp Filtering

The sandbox uses Linux’s secure computing (seccomp) mode to restrict which system calls can be executed by the sandboxed process, providing an additional layer of security.

Sources:

Memory Management

Memory management is a critical aspect of system integration in PolkaVM:

Sources:

Communication Channels

PolkaVM uses several mechanisms for communication between the host and sandbox processes:

  1. Shared Memory: Used to transfer data and state between processes
  2. Futexes: Used for synchronization and notification
  3. userfaultfd: Used for dynamic paging and memory management
  4. File Descriptors: Used for various I/O operations

Futexes (Fast User-space Mutexes) are particularly important for signaling between the host and sandbox:

Futex State Meaning
VMCTX_FUTEX_IDLE Sandbox is idle, waiting for commands
VMCTX_FUTEX_BUSY Sandbox is busy executing code
VMCTX_FUTEX_GUEST_TRAP Guest code triggered a trap
VMCTX_FUTEX_GUEST_ECALLI Guest code made a host call
VMCTX_FUTEX_GUEST_NOT_ENOUGH_GAS Guest code ran out of gas
VMCTX_FUTEX_GUEST_PAGEFAULT Guest code triggered a page fault
VMCTX_FUTEX_GUEST_SIGNAL Guest code received a signal

Sources:

Generic Sandbox Implementation

PolkaVM also provides a generic sandbox implementation that works across different platforms, though with fewer security guarantees than the Linux-specific implementation.

The generic sandbox implementation uses standard POSIX APIs for process management, signal handling, and memory protection. It provides a similar interface to the Linux sandbox but with platform-independent mechanisms.

Sources:

IO_URING Integration

On Linux, PolkaVM integrates with io_uring for efficient asynchronous I/O operations:

The io_uring interface provides high-performance asynchronous I/O operations with minimal overhead. PolkaVM wraps this functionality in a safe Rust interface.

Sources:

Raw System Call Interface

PolkaVM provides a raw system call interface for Linux, avoiding dependencies on libc for better control and portability:

This raw system call interface is used throughout the Linux sandbox implementation to interact directly with the kernel without relying on external libraries.

Sources:

Platform Support Matrix

While PolkaVM aims to be cross-platform, the level of support varies by platform:

Feature Linux Other Platforms
Full Sandboxing ✅ (with namespaces, seccomp) ⚠️ (limited isolation)
Dynamic Paging ✅ (with userfaultfd) ❌ (not available)
Memory Protection ✅ ✅
Signal Handling ✅ ✅
IO_URING ✅ (Linux 5.1+) ❌ (not available)
System Call Filtering ✅ (with seccomp) ❌ (not available)
Resource Limits ✅ ⚠️ (platform dependent)

Sources:

Integration Requirements

To fully utilize PolkaVM’s Linux-specific features, certain kernel requirements must be met:

  1. Kernel Version: Linux 6.8+ is recommended for full userfaultfd support
  2. Kernel Configuration:
    • CONFIG_USERFAULTFD enabled
    • vm.unprivileged_userfaultfd=1 sysctl setting
    • Unprivileged user namespaces enabled (kernel.apparmor_restrict_unprivileged_userns=0)

For generic sandbox support, standard POSIX compliance is sufficient.

Sources:

Summary

PolkaVM’s system integration layer provides a robust foundation for secure and efficient execution of WebAssembly modules. The Linux-specific implementation leverages advanced features of the Linux kernel to provide strong isolation and security guarantees, while the generic implementation offers cross-platform compatibility with a more limited security model.

The combination of process isolation, memory protection, signal handling, and efficient I/O operations creates a comprehensive system integration approach that balances security, performance, and flexibility.