arch/x86/sgx.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 Software Guard eXtensions (SGX)
10 Software Guard eXtensions (SGX) hardware enables for user space applications
13 * Privileged (ring-0) ENCLS functions orchestrate the construction of the
15 * Unprivileged (ring-3) ENCLU functions allow an application to enter and
37 SGX utilizes an *Enclave Page Cache (EPC)* to store pages that are associated
38 with an enclave. It is contained in a BIOS-reserved region of physical memory.
39 Unlike pages used for regular memory, pages can only be accessed from outside of
49 ------------------
56    Regular EPC pages contain the code and data of an enclave.
59    Thread Control Structure pages define the entry points to an enclave and
63    Version Array pages contain 512 slots, each of which can contain a version
67 ----------------------
69 The processor tracks EPC pages in a hardware metadata structure called the
76 remain read-only.  EPCM permissions may only impose additional restrictions on
88 -----------------------
95 pages and establish enclave page permissions.
97 .. kernel-doc:: arch/x86/kernel/cpu/sgx/ioctl.c
104 --------------------------
108 adding and removing of enclave pages. When an enclave accesses an address
113 .. kernel-doc:: arch/x86/kernel/cpu/sgx/ioctl.c
119 ------------
121 Entering an enclave can only be done through SGX-specific EENTER and ERESUME
122 functions, and is a non-trivial process.  Because of the complexity of
132 can leverage special exception fixup provided by the vDSO.  The kernel-provided
133 vDSO function wraps low-level transitions to/from the enclave like EENTER and
138 .. kernel-doc:: arch/x86/include/uapi/asm/sgx.h
147 ----------------
150 for use when the processor powers on or resets.  However, if SGX has been in
151 use since the reset, enclave pages may be in an inconsistent state.  This might
153 reinitializes all enclave pages so that they can be allocated and re-used.
156 EREMOVE function to each physical page. Some enclave pages like SECS pages have
157 hardware dependencies on other pages which prevents EREMOVE from functioning.
161 --------------
170 SGX provides a launch control mechanism. After all enclave pages have been
174 EINIT function takes an RSA-3072 signature of the enclave measurement.  The function
192 encrypt pages leaving the CPU caches. MEE uses a n-ary Merkle tree with root in
194 anti-replay protection but does not scale to large memory sizes because the time
198 CPUs starting from Icelake use Total Memory Encryption (TME) in the place of
199 MEE. TME-based SGX implementations do not have an integrity Merkle tree, which
200 means integrity and replay-attacks are not mitigated.  B, it includes
211 --------------
216 the enclave through special SGX instructions. A run-time within the enclave is
221 ---------------------
224 configured with a library OS and run-time which permits the application to run.
225 The enclave run-time and library OS work together to execute the application
232 ---------
238 This is effectively a kernel use-after-free of an EPC page, and due
240 adding the page back to the pool of available EPC pages, the kernel
243 When this happens, the kernel will likely soon leak more EPC pages, and
260 because KVM doesn't track how a guest uses EPC pages.
263 pages allocated to KVM guests through the virtual EPC driver. If the
269 Architectural behavior is to restore all EPC pages to an uninitialized
273 on all pages in the virtual EPC.
281    some pages; userspace can avoid these failures by preventing execution
285    ``EREMOVE`` happen concurrently for pages that refer to the same
286    "SECS" metadata pages.  This can happen if there are concurrent
293 3. Finally, page removal will fail for SECS metadata pages which still
294    have child pages.  Child pages can be removed by executing
297    twice: an initial set of calls to remove child pages and a subsequent
298    set of calls to remove SECS pages.  The second set of calls is only