[PATCH v3] sgx.7: New page with overview of Software Guard eXtensions (SGX)

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Signed-off-by: Jarkko Sakkinen <jarkko@xxxxxxxxxx>
---
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 | 248 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 248 insertions(+)
 create mode 100644 man7/sgx.7

diff --git a/man7/sgx.7 b/man7/sgx.7
new file mode 100644
index 000000000..4f6d6136f
--- /dev/null
+++ b/man7/sgx.7
@@ -0,0 +1,248 @@
+.\" 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 2020-12-02 "Linux" "Linux Programmer's Manual"
+.PP
+sgx - overview of Software Guard eXtensions
+.SH DESCRIPTION
+.PP
+Intel Software Guard eXtensions (SGX) allow user space applications to set
+aside private memory regions of code and data.
+These memory regions are called enclaves.
+.PP
+SGX must be enabled by the 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
+An enclave can be entered only at a fixed set of entry points,
+each defined by Thread Control Structure (TCS) architectural structure,
+contained in a single enclave page.
+A hardware thread reserves a TCS by executing EENTER subfunction of the
+ENCLU instruction,
+and the execution continues from the TCS defined entry point.
+ENCLU contains all the SGX user functions.
+Depending on the function, they must be called either inside or outside of
+the enclave.
+Once the thread has completed its task,
+it calls EEXIT subfunction of the ENCLU instruction,
+which releases the TCS and departs the enclave to a given address outside
+the enclave.
+While the enclave is loaded from a regular binary file,
+only the threads inside the enclave can access its memory.
+.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).
+.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 Enclave management
+.PP
+An enclave's life-cycle starts by opening
+.I /dev/sgx_enclave
+and ends when all the file descriptors referring to the opened file have
+been closed.
+After opening the enclave,
+its contents must be populated with the ioctl interface provided by
+.IR <asm/sgx.h> .
+ENCLS is a privileged (ring-0) instruction with the functionality for
+managing enclave memory,
+and the ioctl interface provides a wrapper for it.
+.PP
+Enclave construction starts by calling
+.B SGX_IOC_ENCLAVE_CREATE,
+which copies the initial version of SGX Enclave Control Structure
+(SECS).
+SGX Enclave Control Structure (SECS) contains the description of the
+enclave.
+The ioctl calls the ECREATE subfunction of the ENCLS instruction,
+which will copy the SECS to the SGX reserved memory.
+The SECS is never mapped to the process address space,
+and thus cannot be directly referenced.
+.PP
+Among other things, the SECS contains the base address and size of the enclave,
+meaning that the address space must be carved out before the creation.
+There is also a hardware related invariant that the enclave size must be a
+power of two,
+and the base address must be also naturally aligned relative to the size.
+.PP
+Some of the SECS fields must be initialized to zero because their values
+are determined dynamically after the enclave has been created.
+Most importantly SECS contains two SHA256 hashes: MRENCLAVE and
+MRSIGNER.
+Each ENCLS subfunction,
+which contribute to the enclave construction,
+hashes its key parameters to the MRENCLAVE.
+Arbitrary data can be also hashed into MRENCLAVE via the EEXTEND subfunction
+of the ENCLS instruction.
+MRSIGNER contains the hash of the enclave signer key,
+which is used to sign the SIGSTRUCT structure passed to the
+EINIT subfunction of the ENCLS instruction.
+MRENCLAVE and MRSIGNER define the enclave identity and sealing identity of the
+enclave.
+A thread executing inside the enclave can use them as key material for deriving
+128-bit cryptographic keys.
+This is accomplished by calling the EGETKEY subfunction of the ENCLU
+instruction.
+.PP
+After the enclave has been created,
+a series of
+.B SGX_IOC_ENCLAVE_ADD_PAGES
+calls are issued.
+This ioctl copies the provided data to the enclave memory by invoking
+the EADD subfunction of the ENCLS instruction.
+and optionally hashes it with help of the EEXTEND subfunction of the ENCLS
+instruction.
+Hashing is optional because it is a slow operation and sometimes not
+required.
+For instance, one might only care to measure the code pages.
+.PP
+Finally, when all the data has been copied to the enclave memory,
+.B SGX_IOC_ENCLAVE_INIT
+is called,
+which invokes the EINIT subfunction of the ENCLS instruction.
+This function checks that the accumulated MRENCLAVE matches the
+MRENCLAVE inside the caller provided SIGSTRUCT,
+and locks down the enclave from further build operations.
+After this, the enclave can be invoked.
+.SS Enclave memory mapping
+.PP
+The processor tracks EPC pages in a hardware metadata structure called
+.I Enclave Page Cache Map (EPCM).
+The EPCM contains an entry for each EPC page which describes the owning
+enclave,
+access rights,
+and page type among the other things.
+EPCM permissions are separate from the normal page tables.
+This prevents the kernel from,
+for instance,
+allowing writes to data which an enclave wishes to remain read-only.
+EPCM permissions may only impose additional restrictions on top of
+normal x86 page permissions.
+.PP
+For all intents and purposes,
+the SGX architecture allows the processor to invalidate all EPCM entries
+at will.
+This requires that software be prepared to handle an EPCM fault at any
+time.
+In practice,
+this can happen on events like power transitions when the ephemeral key
+that encrypts enclave memory is lost.
+.PP
+The kernel records EPCM permissions when
+.B SGX_IOC_ENCLAVE_ADD_PAGES
+is called.
+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 Enclave invocation
+.PP
+Enclaves encounter exceptions for many reasons:
+everything from enclave page faults to NULL pointer dereferences,
+to system calls that must be called by a delegate from outside the enclave.
+Finally, a power cycle invalidates the whole EPC,
+which also needs to be addressed by the caller.
+.PP
+This type of exception handling has been traditionally been handled in
+SIGSEGV handlers,
+registered by the library.
+But, being a process-wide state,
+signal handling and code libraries do not mix well.
+.PP
+In order to assist the run-time, kernel provides a vDSO entry point,
+.BR vsgx_enter_enclave ,
+which wraps the ENCLU entry subfunctions EENTER and ERESUME,
+and returns exceptions to the caller at the point they happen.
+The exception information is filled in RDI, RSI and RDX.
+The kernel-provided user space portion of the vDSO handler will place
+this information in a user-provided buffer,
+or optionally trigger a user-provided callback at the time of the
+exception.
+.PP
+The vDSO function calling convention uses the standard RDI, RSI, RDX,
+RCX, R8 and R9 registers.
+This makes it possible to declare the vDSO as a C prototype,
+but other than that there is no specific support for the x86-64 calling
+convention,
+Things like storing XSAVE are the responsibility of the enclave and the
+runtime.
+.SS Page reclaimer
+.PP
+Just like normal RAM,
+there is a limited amount of enclave memory available and over-committing
+it is a very valuable tool to reduce resource use.
+.PP
+In contrast to normal page reclaim,
+the kernel cannot directly access enclave memory.
+To get around this,
+the SGX architecture provides a set of functions to help.
+Among other things,
+these functions copy enclave memory to and from normal memory,
+encrypting it and protecting its integrity in the process.
+.PP
+The kernel provides a page reclaimer by using these functions.
+It picks victim pages in LRU fashion from all the enclaves running in
+the system.
+A new kernel thread (ksgxd) reclaims pages in the background based on
+watermarks,
+similar to normal kswapd.
+.PP
+All enclave pages can be reclaimed, architecturally.
+But, there are some limits to this,
+such as the SECS page,
+which must be reclaimed last.
+The page version array (used to mitigate replaying old reclaimed pages)
+is also architecturally reclaimable,
+but support for reclaiming the page version array is not yet implemented,
+The end result is that the vast majority of enclave pages are currently
+reclaimable.
+.SH VERSIONS
+The SGX feature was added in Linux 5.11.
+.SH SEE ALSO
+.BR ioctl (2),
+.BR mmap() (2),
+.BR mprotect (2),
-- 
2.29.2




[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux