diff mbox series

[v6,RESEND] sgx.7: New page with overview of Software Guard eXtensions (SGX)

Message ID 20210512211414.416860-1-jarkko@kernel.org (mailing list archive)
State New, archived
Headers show
Series [v6,RESEND] sgx.7: New page with overview of Software Guard eXtensions (SGX) | expand

Commit Message

Jarkko Sakkinen May 12, 2021, 9:14 p.m. UTC
Signed-off-by: Jarkko Sakkinen <jarkko@kernel.org>

* Oops, sorry, forgot to move the log over here. That's the reason for
* Small fixes based on Dave's and Reinette's feedback.
* Extended the "Permissions" section to cover mmap()
* Taking away hardware concepts and focusing more on the interface.
* 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).
* 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.
* 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 | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 man7/sgx.7
diff mbox series


diff --git a/man7/sgx.7 b/man7/sgx.7
new file mode 100644
index 000000000..b5bd1327e
--- /dev/null
+++ b/man7/sgx.7
@@ -0,0 +1,138 @@ 
+.\" Copyright (C) 2021 Intel Corporation
+.\" 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.
+.TH SGX 7 2021\-02\-02 "Linux" "Linux Programmer's Manual"
+sgx - overview of Software Guard eXtensions
+.SS Overview
+Intel Software Guard eXtensions (SGX) allow applications to host
+protected executable objects in memory,
+also known as
+.I enclaves.
+They are constructed with
+.BR mmap (2)
+.BR ioctl (2)
+applied to
+.I /dev/sgx_enclave.
+The details of enclave's memory structure can be found in
+the Intel Software Developers Manual.
+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
+.I Enabled
+.I Software Enabled
+modes for SGX,
+.I Enabled.
+SGX is available only if the kernel was configured and built with the
+You can determine whether both the kernel and hardware together support SGX by
+checking whether "sgx" appears in the
+.I flags
+field in
+.IR /proc/cpuinfo .
+.SS Construction
+A process can build an enclave by applying the
+.BR ioctl (2)
+interface provided by
+.IR <asm/sgx.h>
+.I /dev/sgx_enclave.
+An enclave's base address is fixed during the build time:
+it is given to
+which initiates the whole enclave build process.
+As a consequence,
+.BR mmap (2)
+must be used to reserve a reasonable piece of the process address space,
+before the build process can begin.
+There is a hardware constraint that the enclave size must be a power of two,
+and the base address must be a multiple of the size.
+This often leads to reserving a larger region than required by the payload.
+If the address space size is an issue,
+it can be obviously trimmed with
+.BR mmap(MAP_FIXED)
+after the enclave has been constructed.
+A process can access enclave by entering into its address space through
+a set of entry points,
+which must be defined during the construction process.
+This requires a complex sequence of CPU instructions,
+and kernel assisted exception handling.
+For these reasons,
+it is encapsulated into
+vDSO interface,
+provided by
+.BR vdso_sgx_enter_enclave_t,
+which is located in
+.IR <asm/sgx.h>.
+.SS Permissions
+In order to build an enclave, a process must be able to call
+.IR mmap (2)
+because like for any other type of executable,
+the page table permissions must be set appropriately.
+.I /dev/sgx_enclave
+must reside in a partition,
+which is not mounted with
+.B noexec
+set in the mount options.
+During the build process each enclave page is assigned protection bits,
+as part of
+These permissions are also the maximum permissions to which the page can be be mapped.
+.BR mmap (2)
+is called with surpassing permissions,
+it will return
+is called after
+.BR mmap (2)
+with lower permissions,
+the process will eventually receive a
+once it accesses the page for the first time.
+The SGX feature was added in Linux 5.11.
+.BR ioctl (2),
+.BR mmap (2),
+.BR mprotect (2)