system/i386/nitro-enclave.rst

1 'nitro-enclave' virtual machine (``nitro-enclave``)
4 ``nitro-enclave`` is a machine type which emulates an *AWS nitro enclave*
8 no persistent storage and no external networking. The enclave VMs are based
9 on Firecracker microvm with a vhost-vsock device for communication with the
15 In QEMU, ``nitro-enclave`` is a machine type based on ``microvm`` similar to how
19 device emulation is done using vhost-user-vsock which means another process that
20 can do the userspace emulation, like `vhost-device-vsock`_ from rust-vmm crate,
21 must be run alongside nitro-enclave for the vsock communication to work.
23 ``libcbor`` and ``gnutls`` are required dependencies for nitro-enclave machine
26 .. _AWS nitro enclaves: https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave.html
27 .. _Enclave Image Format: https://github.com/aws/aws-nitro-enclaves-image-format
28 .. _vhost-device-vsock: https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-vsock
29 .. _Firecracker: https://firecracker-microvm.github.io
31 Using the nitro-enclave machine type
32 ------------------------------------
34 Machine-specific options
37 It supports the following machine-specific options:
39 - nitro-enclave.vsock=string (required) (Id of the chardev from '-chardev' option that vhost-user-v…
40 - nitro-enclave.id=string (optional) (Set enclave identifier)
41 - nitro-enclave.parent-role=string (optional) (Set parent instance IAM role ARN)
42 - nitro-enclave.parent-id=string (optional) (Set parent instance identifier)
45 Running a nitro-enclave VM
48 First, run `vhost-device-vsock`__ (or a similar tool that supports vhost-user-vsock).
49 The forward-cid option below with value 1 forwards all connections from the enclave
50 VM to the host machine and the forward-listen (port numbers separated by '+') is used
53   $ vhost-device-vsock \
54      --vm guest-cid=4,forward-cid=1,forward-listen=9001+9002,socket=/tmp/vhost4.socket
56 __ https://github.com/rust-vmm/vhost-device/tree/main/vhost-device-vsock#using-the-vsock-backend
58 Now run the necessary applications on the host machine so that the nitro-enclave VM
59 applications' vsock communication works. For example, the nitro-enclave VM's init
67 Then run the nitro-enclave VM using the following command where ``hello.eif`` is
70   $ qemu-system-x86_64 -M nitro-enclave,vsock=c,id=hello-world \
71      -kernel hello-world.eif -nographic -m 4G --enable-kvm -cpu host \
72      -chardev socket,id=c,path=/tmp/vhost4.socket
74 In this example, the nitro-enclave VM has CID 4. If there are applications that
77 VM's CID) and use the forward-listen (e.g., 9001+9002) option of vhost-device-vsock