Signed-off-by: Jarkko Sakkinen <jarkko@xxxxxxxxxx> --- v4: * Did a heavy edit trying to streamline the story a bit and focus on stuff important to the user (e.g. lighten up x86 details). v3: * Overhaul based on Michael's comments. Most likely needs to be refined in various places but this is at least a small step forward for sure. v2: * Fixed the semantic newlines convention and various style errors etc. that were reported by Alenjandro and Michael. * SGX was merged to v5. man7/sgx.7 | 196 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 man7/sgx.7 diff --git a/man7/sgx.7 b/man7/sgx.7 new file mode 100644 index 000000000..c0b67020e --- /dev/null +++ b/man7/sgx.7 @@ -0,0 +1,196 @@ +.\" Copyright (C) 2021 Intel Corporation +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SGX 7 2021\-02\-02 "Linux" "Linux Programmer's Manual" +.PP +sgx - overview of Software Guard eXtensions +.SH DESCRIPTION +.PP +Intel Software Guard eXtensions (SGX) allow applications to set +aside private memory regions of code and data. +These memory regions are called enclaves. +.PP +SGX must be enabled in BIOS. +If SGX appears to be unsupported on a system having hardware support, +ensure that SGX is enabled in the BIOS. +If a BIOS presents a choice between \(dqEnabled\(dq and \(dqSoftware +Enabled\(dq modes for SGX, +choose \(dqEnabled\(dq. +.PP +SGX is available only if the kernel was configured and built with the +.B CONFIG_X86_SGX +option. +You can determine whether the hardware supports SGX by checking +whether "sgx" appears in the +.I flags +field in +.IR /proc/cpuinfo . +.SS Overview +.PP +An enclave is a region of address space, +mapping pages from Enclave Page Cache (EPC), +which consists of sections of non-addressable system memory. +They are constructed with sub-functions of the privileged (ring-0) ENCLS x86 +instruction, +and interacted with sub-functions of the unprivileged (ring-3) ENCLU x86 +instruction. +Any other type of memory access gets asserted by the CPU. +Enclaves are represented to the user space as memory-mapped files, +shareable by multiple processes. +.PP +An EPC page can be initialized with ENCLS sub-functions to any of the +following types: +.TP +SECS +SGX Enclave Control Structure (SECS) contains the enclave global properties +such as the base address, +size and SHA256 checksum of its contents. +.TP +REG +Regular (REG) pages are code and data pages of the enclave. +They are mapped to the enclave address space. +.TP +TCS +Thread Control Structure (TCS) pages describe the entry points to an enclave with +an offset from the base address. +They are mapped to the enclave address space. +ENCLU provides EENTER and ERESUME sub-functions, +which take the address of a TCS page, +and jump executing inside an enclave from the given offset. +.PP +An enclave can be entered only at a fixed set of entry points, +each defined by a TCS, +by invoking EENTER and ERESUME. +Any other type of memory access is strictly prohibited by the CPU. +.PP +A thread inside an enclave can read and write memory inside and outside the +enclave, +but any action causing execution outside the enclave is asserted by the CPU +with an exception, +and ultimately exit from the enclave. +A thread can cleanly exit from the enclave with EEXIT sub-function of the ENCLU, +to a given address outside the enclave. +.PP +Although carved out of normal DRAM, +enclave memory is marked in the system memory map as reserved and is not +managed by the Linux memory manager. +There may be several enclave regions spread across the system. +Each contiguous region is called an Enclave Page Cache (EPC) section. +The pages belonging to the EPC sections are encrypted when they leave the +Last Level Cache (LLC). +.SS Construction +.PP +An enclave's life-cycle starts by opening +.I /dev/sgx_enclave, +and ends when all the file descriptors have been closed. +After opening the enclave, +its contents must be populated with the +.BR ioctl (2) +interface provided by +.IR <asm/sgx.h> . +.PP +The are rudimentarily the steps to construct an enclave: +.IP 1. +Invoke +.B SGX_IOC_ENCLAVE_CREATE, +which takes in data for the SECS, +and initializes an EPC page for it. +SECS is used by various ENCLS sub-functions to modify the enclave state. +It is kept internally by the kernel, +and is never made available to the user space. +.IP 2. +Populate regular and TCS pages to the enclave, +by invoking +.B SGX_IOC_ENCLAVE_ADD_PAGES. +.IP 3. +Invoke +.B SGX_IOC_ENCLAVE_INIT, +which makes the enclave executable. +After this new pages can no longer be added. +.SS Access rights +The state of each EPC page is stored to a structure called the +.I Enclave Page Cache Map (EPCM), +which takes a portion of the EPC. +The state consists of page type and access rights, +among the other things. +When a page is accessed by a CPU, +the EPCM permissions are enforced, +in addition to the +.BR mmap(2) +permissions. +EPCM permissions are defined when invoking +.B SGX_IOC_ENCLAVE_ADD_PAGES, +by setting them to the +.B flags +field of +.B struct enclave_add_pages. +.PP +A memory access to an unitialized EPC page causes EPCM fault, +with a new SGX bit set in the error code. +A new power cycle invalidates the whole EPCM, +making all EPC pages unitialized. +E.g. if the system goes to sleep, +and then wakes up, +all the data is gone. +Thus, a user space run-time must be prepared to handle this exception, +at any point of time. +.PP +When the pages are mapped to memory via +.BR mmap (2) +or +.BR mprotect (2), +the EPCM permissions are compared against the declared permissions. +If the declared permissions have bits set that are not part of the EPCM +permissions, +the operation fails with the error +.B EACCES. +.SS Exception handling +These are the exceptions triggered by an enclave: +.IP +Undefined instruction (#UD) exception is triggered when executing inside an enclave, +for any instruction that may cause VMEXIT, +I/O instruction, +or a change in CPU privilege levels. +.IP +Page fault (#PF) with a new SGX bit set, +also known as EPCM fault, +is triggered, +when accessing unitialized EPC page, +or when the memory access surpasses the EPCM permissions. +.PP +In order to assist the run-time, +the kernel provides a vDSO entry point, +.BR vsgx_enter_enclave, +which wraps the code required the enter the enclave. +When an exception occurs, +the vDSO populates +.B struct sgx_enclave_run +with the exception data, +and returns to the caller. +.SH VERSIONS +The SGX feature was added in Linux 5.11. +.SH SEE ALSO +.BR ioctl (2), +.BR mmap() (2), +.BR mprotect (2) -- 2.30.1
