arch/x86/sgx.rst

1 .. SPDX-License-Identifier: GPL-2.0
13 * Privileged (ring-0) ENCLS functions orchestrate the construction of the
15 * Unprivileged (ring-3) ENCLU functions allow an application to enter and
34 Enclave Page Cache
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.
48 Enclave Page Types
49 ------------------
64    number for a page evicted from the EPC.
66 Enclave Page Cache Map
67 ----------------------
70 *Enclave Page Cache Map (EPCM)*.  The EPCM contains an entry for each EPC page
71 which describes the owning enclave, access rights and page type among the other
74 EPCM permissions are separate from the normal page tables.  This prevents the
76 remain read-only.  EPCM permissions may only impose additional restrictions on
77 top of normal x86 page permissions.
88 -----------------------
92 executed (entered). The first step in building an enclave is opening the
95 pages and establish enclave page permissions.
97 .. kernel-doc:: arch/x86/kernel/cpu/sgx/ioctl.c
104 --------------------------
107 enclaves: modifying enclave page permissions and type, and dynamically
109 within its address range that does not have a backing page then a new
110 regular page will be dynamically added to the enclave. The enclave is
111 still required to run EACCEPT on the new page before it can be used.
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 ----------------
152 occur after a crash and kexec() cycle, for instance.  At boot, ksgxd
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
160 Page reclaimer
161 --------------
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
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 ---------
234 When EPC page leaks happen, a WARNING like this is shown in dmesg:
236 "EREMOVE returned ... and an EPC page was leaked.  SGX may become unusable..."
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
241 intentionally leaks the page to avoid additional errors in the future.
258 in guests. Unlike the SGX driver, an EPC page allocated by the virtual
262 As a result, the SGX core page reclaimer doesn't support reclaiming EPC
278 1. Page removal will always fail when any thread is running in the
279    enclave to which the page belongs.  In this case the ioctl will
284 2. Page removal will cause a general protection fault if two calls to
293 3. Finally, page removal will fail for SECS metadata pages which still