From: Andra Paraschiv <andraprs@amazon.com>
To: <linux-kernel@vger.kernel.org>
Cc: Anthony Liguori <aliguori@amazon.com>,
Benjamin Herrenschmidt <benh@kernel.crashing.org>,
Colm MacCarthaigh <colmmacc@amazon.com>,
"Bjoern Doebel" <doebel@amazon.de>,
David Woodhouse <dwmw@amazon.co.uk>,
"Frank van der Linden" <fllinden@amazon.com>,
Alexander Graf <graf@amazon.de>,
Greg KH <gregkh@linuxfoundation.org>,
Martin Pohlack <mpohlack@amazon.de>,
"Matt Wilson" <msw@amazon.com>,
Paolo Bonzini <pbonzini@redhat.com>,
Balbir Singh <sblbir@amazon.com>,
Stefano Garzarella <sgarzare@redhat.com>,
"Stefan Hajnoczi" <stefanha@redhat.com>,
Stewart Smith <trawets@amazon.com>,
"Uwe Dannowski" <uwed@amazon.de>, <kvm@vger.kernel.org>,
<ne-devel-upstream@amazon.com>,
Andra Paraschiv <andraprs@amazon.com>
Subject: [PATCH v4 17/18] nitro_enclaves: Add overview documentation
Date: Mon, 22 Jun 2020 23:03:28 +0300 [thread overview]
Message-ID: <20200622200329.52996-18-andraprs@amazon.com> (raw)
In-Reply-To: <20200622200329.52996-1-andraprs@amazon.com>
Signed-off-by: Andra Paraschiv <andraprs@amazon.com>
---
Changelog
v3 -> v4
* Update doc type from .txt to .rst.
* Update documentation based on the changes from v4.
v2 -> v3
* No changes.
v1 -> v2
* New in v2.
---
Documentation/nitro_enclaves/ne_overview.rst | 87 ++++++++++++++++++++
1 file changed, 87 insertions(+)
create mode 100644 Documentation/nitro_enclaves/ne_overview.rst
diff --git a/Documentation/nitro_enclaves/ne_overview.rst b/Documentation/nitro_enclaves/ne_overview.rst
new file mode 100644
index 000000000000..21b4ba932000
--- /dev/null
+++ b/Documentation/nitro_enclaves/ne_overview.rst
@@ -0,0 +1,87 @@
+Nitro Enclaves
+==============
+
+Nitro Enclaves (NE) is a new Amazon Elastic Compute Cloud (EC2) capability
+that allows customers to carve out isolated compute environments within EC2
+instances [1].
+
+For example, an application that processes sensitive data and runs in a VM,
+can be separated from other applications running in the same VM. This
+application then runs in a separate VM than the primary VM, namely an enclave.
+
+An enclave runs alongside the VM that spawned it. This setup matches low latency
+applications needs. The resources that are allocated for the enclave, such as
+memory and CPU, are carved out of the primary VM. Each enclave is mapped to a
+process running in the primary VM, that communicates with the NE driver via an
+ioctl interface.
+
+In this sense, there are two components:
+
+1. An enclave abstraction process - a user space process running in the primary
+VM guest that uses the provided ioctl interface of the NE driver to spawn an
+enclave VM (that's 2 below).
+
+There is a NE emulated PCI device exposed to the primary VM. The driver for this
+new PCI device is included in the NE driver.
+
+The ioctl logic is mapped to PCI device commands e.g. the NE_START_ENCLAVE ioctl
+maps to an enclave start PCI command. The PCI device commands are then
+translated into actions taken on the hypervisor side; that's the Nitro
+hypervisor running on the host where the primary VM is running. The Nitro
+hypervisor is based on core KVM technology.
+
+2. The enclave itself - a VM running on the same host as the primary VM that
+spawned it. Memory and CPUs are carved out of the primary VM and are dedicated
+for the enclave VM. An enclave does not have persistent storage attached.
+
+The memory regions carved out of the primary VM and given to an enclave need to
+be aligned 2 MiB / 1 GiB physically contiguous memory regions (or multiple of
+this size e.g. 8 MiB). The memory can be allocated e.g. by using hugetlbfs from
+user space [2][3]. The memory size for an enclave needs to be at least 64 MiB.
+The enclave memory and CPUs need to be from the same NUMA node.
+
+An enclave runs on dedicated cores. CPU 0 and its CPU siblings need to remain
+available for the primary VM. A CPU pool has to be set for NE purposes by an
+user with admin capability. See the cpu list section from the kernel
+documentation [4] for how a CPU pool format looks.
+
+An enclave communicates with the primary VM via a local communication channel,
+using virtio-vsock [5]. The primary VM has virtio-pci vsock emulated device,
+while the enclave VM has a virtio-mmio vsock emulated device. The vsock device
+uses eventfd for signaling. The enclave VM sees the usual interfaces - local
+APIC and IOAPIC - to get interrupts from virtio-vsock device. The virtio-mmio
+device is placed in memory below the typical 4 GiB.
+
+The application that runs in the enclave needs to be packaged in an enclave
+image together with the OS ( e.g. kernel, ramdisk, init ) that will run in the
+enclave VM. The enclave VM has its own kernel and follows the standard Linux
+boot protocol.
+
+The kernel bzImage, the kernel command line, the ramdisk(s) are part of the
+Enclave Image Format (EIF); plus an EIF header including metadata such as magic
+number, eif version, image size and CRC.
+
+Hash values are computed for the entire enclave image (EIF), the kernel and
+ramdisk(s). That's used, for example, to check that the enclave image that is
+loaded in the enclave VM is the one that was intended to be run.
+
+These crypto measurements are included in a signed attestation document
+generated by the Nitro Hypervisor and further used to prove the identity of the
+enclave; KMS is an example of service that NE is integrated with and that checks
+the attestation doc.
+
+The enclave image (EIF) is loaded in the enclave memory at offset 8 MiB. The
+init process in the enclave connects to the vsock CID of the primary VM and a
+predefined port - 9000 - to send a heartbeat value - 0xb7. This mechanism is
+used to check in the primary VM that the enclave has booted.
+
+If the enclave VM crashes or gracefully exits, an interrupt event is received by
+the NE driver. This event is sent further to the user space enclave process
+running in the primary VM via a poll notification mechanism. Then the user space
+enclave process can exit.
+
+[1] https://aws.amazon.com/ec2/nitro/nitro-enclaves/
+[2] https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt
+[3] https://lwn.net/Articles/807108/
+[4] https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html
+[5] https://man7.org/linux/man-pages/man7/vsock.7.html
--
2.20.1 (Apple Git-117)
Amazon Development Center (Romania) S.R.L. registered office: 27A Sf. Lazar Street, UBC5, floor 2, Iasi, Iasi County, 700045, Romania. Registered in Romania. Registration number J22/2621/2005.
next prev parent reply other threads:[~2020-06-22 20:06 UTC|newest]
Thread overview: 67+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-06-22 20:03 [PATCH v4 00/18] Add support for Nitro Enclaves Andra Paraschiv
2020-06-22 20:03 ` [PATCH v4 01/18] nitro_enclaves: Add ioctl interface definition Andra Paraschiv
2020-06-23 8:56 ` Stefan Hajnoczi
2020-06-24 14:02 ` Paraschiv, Andra-Irina
2020-06-25 13:29 ` Stefan Hajnoczi
2020-06-25 17:42 ` Paraschiv, Andra-Irina
2020-07-02 15:24 ` Alexander Graf
2020-07-04 8:09 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 02/18] nitro_enclaves: Define the PCI device interface Andra Paraschiv
2020-07-02 15:24 ` Alexander Graf
2020-07-04 8:20 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 03/18] nitro_enclaves: Define enclave info for internal bookkeeping Andra Paraschiv
2020-07-02 15:24 ` Alexander Graf
2020-07-04 8:23 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 04/18] nitro_enclaves: Init PCI device driver Andra Paraschiv
2020-07-02 15:09 ` Alexander Graf
2020-07-04 10:00 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 05/18] nitro_enclaves: Handle PCI device command requests Andra Paraschiv
2020-07-02 15:19 ` Alexander Graf
2020-07-04 15:05 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 06/18] nitro_enclaves: Handle out-of-band PCI device events Andra Paraschiv
2020-07-02 15:24 ` Alexander Graf
2020-07-04 15:43 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 07/18] nitro_enclaves: Init misc device providing the ioctl interface Andra Paraschiv
2020-06-29 16:20 ` Greg KH
2020-06-29 17:45 ` Paraschiv, Andra-Irina
2020-06-30 8:05 ` Greg KH
2020-06-30 9:08 ` Paraschiv, Andra-Irina
2020-07-06 7:13 ` Alexander Graf
2020-07-06 7:49 ` Paraschiv, Andra-Irina
2020-07-06 8:01 ` Alexander Graf
2020-07-06 13:09 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 08/18] nitro_enclaves: Add logic for enclave vm creation Andra Paraschiv
2020-07-06 7:53 ` Alexander Graf
2020-07-06 13:12 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 09/18] nitro_enclaves: Add logic for enclave vcpu creation Andra Paraschiv
2020-07-06 10:12 ` Alexander Graf
2020-07-08 12:46 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 10/18] nitro_enclaves: Add logic for enclave image load info Andra Paraschiv
2020-07-06 10:16 ` Alexander Graf
2020-07-06 13:35 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 11/18] nitro_enclaves: Add logic for enclave memory region set Andra Paraschiv
2020-07-06 10:46 ` Alexander Graf
2020-07-09 7:36 ` Paraschiv, Andra-Irina
2020-07-09 8:40 ` Alexander Graf
2020-07-09 9:41 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 12/18] nitro_enclaves: Add logic for enclave start Andra Paraschiv
2020-07-06 11:21 ` Alexander Graf
2020-07-07 18:27 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 13/18] nitro_enclaves: Add logic for enclave termination Andra Paraschiv
2020-07-06 11:26 ` Alexander Graf
2020-07-06 14:15 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 14/18] nitro_enclaves: Add Kconfig for the Nitro Enclaves driver Andra Paraschiv
2020-07-06 11:28 ` Alexander Graf
2020-07-06 13:50 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 15/18] nitro_enclaves: Add Makefile " Andra Paraschiv
2020-07-06 11:30 ` Alexander Graf
2020-07-06 14:00 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 16/18] nitro_enclaves: Add sample for ioctl interface usage Andra Paraschiv
2020-07-06 11:39 ` Alexander Graf
2020-07-07 19:03 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` Andra Paraschiv [this message]
2020-06-23 8:59 ` [PATCH v4 17/18] nitro_enclaves: Add overview documentation Stefan Hajnoczi
2020-06-24 14:39 ` Paraschiv, Andra-Irina
2020-06-25 13:10 ` Stefan Hajnoczi
2020-06-25 17:36 ` Paraschiv, Andra-Irina
2020-06-22 20:03 ` [PATCH v4 18/18] MAINTAINERS: Add entry for the Nitro Enclaves driver Andra Paraschiv
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200622200329.52996-18-andraprs@amazon.com \
--to=andraprs@amazon.com \
--cc=aliguori@amazon.com \
--cc=benh@kernel.crashing.org \
--cc=colmmacc@amazon.com \
--cc=doebel@amazon.de \
--cc=dwmw@amazon.co.uk \
--cc=fllinden@amazon.com \
--cc=graf@amazon.de \
--cc=gregkh@linuxfoundation.org \
--cc=kvm@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mpohlack@amazon.de \
--cc=msw@amazon.com \
--cc=ne-devel-upstream@amazon.com \
--cc=pbonzini@redhat.com \
--cc=sblbir@amazon.com \
--cc=sgarzare@redhat.com \
--cc=stefanha@redhat.com \
--cc=trawets@amazon.com \
--cc=uwed@amazon.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).