ContextQMD
Back to Qemu

AWS Nitro Enclaves

docs/system/nitro.rst

11.0.04.8 KB
Original Source

AWS Nitro Enclaves

AWS Nitro Enclaves <https://aws.amazon.com/ec2/nitro/nitro-enclaves/>_ are isolated compute environments that run alongside EC2 instances. They are created by partitioning CPU and memory resources from a parent instance and launching a signed Enclave Image Format (EIF) file inside a confidential VM managed by the Nitro Hypervisor.

QEMU supports launching Nitro Enclaves on EC2 instances that have enclave support enabled, using the nitro accelerator and the nitro machine type.

Prerequisites

  • An EC2 instance with Nitro Enclaves enabled
  • The nitro_enclaves kernel module loaded (provides /dev/nitro_enclaves)
  • CPU cores allocated to the Nitro Enclaves pool via nitro-enclaves-allocator
  • Huge pages allocated for Nitro Enclaves via nitro-enclaves-allocator

Quick Start

Launch a Nitro Enclave from a pre-built EIF file::

$ qemu-system-x86_64 -accel nitro,debug-mode=on -M nitro -nographic \
    -smp 2 -m 512M -kernel enclave.eif

Launch an enclave from individual kernel and initrd files::

$ qemu-system-x86_64 -accel nitro,debug-mode=on -M nitro -nographic \
    -smp 2 -m 512M -kernel vmlinuz -initrd initrd.cpio \
    -append "console=ttyS0"

The same commands work with qemu-system-aarch64 on Graviton based EC2 instances.

Accelerator

The nitro accelerator (-accel nitro) drives the /dev/nitro_enclaves device to create and manage a Nitro Enclave. It handles:

  • Creating the enclave VM slot
  • Donating memory regions (must be huge page backed)
  • Adding vCPUs (must be full physical cores)
  • Starting the enclave
  • Notifying vsock bus devices of the enclave CID

Accelerator options:

debug-mode=on|off Enable debug mode. When enabled, the Nitro Hypervisor exposes the enclave's serial console output via a vsock port that the machine model automatically connects to. In debug mode, PCR values are zero. Default is off.

Machine

The nitro machine (-M nitro) is a minimal, architecture-independent machine that provides only what a Nitro Enclave needs:

  • RAM (huge page backed via memfd)

  • vCPUs (defaults to host CPU type)

  • A Nitro vsock bus with:

    • A heartbeat device (vsock server on port 9000)
    • A serial console bridge (vsock client, debug mode only)

Communication to the Nitro Enclave is limited to virtio-vsock. The Enclave is allocated a CID at launch at which it is reachable. A specific CID can be requested with -accel nitro,enclave-cid=<N> (0 lets the hypervisor choose). The assigned CID is readable from the vsock bridge device::

(qemu) qom-get /machine/peripheral/nitro-vsock enclave-cid

EIF Image Format ^^^^^^^^^^^^^^^^

Nitro Enclaves boot from EIF (Enclave Image Format) files. When -kernel points to an EIF file (detected by the .eif magic bytes), it is loaded directly into guest memory.

When -kernel points to a regular kernel image (e.g. a bzImage or Image), the machine automatically assembles a minimal EIF on the fly from -kernel, -initrd, and -append. This allows standard direct kernel boot without external EIF tooling.

CPU Requirements ^^^^^^^^^^^^^^^^

Nitro Enclaves require full physical CPU cores. On hyperthreaded systems, this means -smp must be a multiple of the threads per core (typically 2).

Nitro Enclaves can only consume cores that are donated to the Nitro Enclave CPU pool. You can configure the CPU pool using the nitro-enclaves-allocator tool or manually by writing to the nitro_enclaves cpu pool parameter. To allocate vCPUs 1, 2 and 3, you can call::

$ echo 1,2,3 | sudo tee /sys/module/nitro_enclaves/parameters/ne_cpus

Beware that on x86-64 systems, hyperthread siblings are not consecutive and must be added in pairs to the pool. Consult tools like lstopo or lscpu for details about your instance's CPU topology.

Memory Requirements ^^^^^^^^^^^^^^^^^^^

Enclave memory must be huge page backed. The machine automatically creates a memfd memory backend with huge pages enabled. To make the huge page allocation work, ensure that huge pages are reserved in the system. To reserve 1 GiB of memory on a 4 KiB PAGE_SIZE system, you can call::

$ echo 512 | sudo tee /proc/sys/vm/nr_hugepages

Emulated Nitro Enclaves

In addition to the native Nitro Enclaves invocation, you can also use the emulated nitro-enclave machine target (see :doc:i386/nitro-enclave) which implements the x86 Nitro Enclave device model. While -M nitro delegates virtual machine device emulation to the Nitro Hypervisor, -M nitro-enclave implements all devices itself, which means it also works on non-EC2 instances.

If you require NSM based attestation backed by valid AWS certificates, you must use -M nitro. The -M nitro-enclave model does not provide you with an AWS signed attestation document.