sgx.7: New page with overview of Software Guard eXtensions (SGX)
Jarkko Sakkinen
maintainerPATCH v5 1/1 sgx.7: New page with overview of Software Guard eXtensions (SGX)
---
v5:
* Taking away hardware concepts and focusing more on the interface. 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 | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 man7/sgx.7
man7/sgx.7 new file +121 -0
@@ -0,0 +1,121 @@ +.\" 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 +.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) +and +.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. +.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 +.I Enabled +and +.I Software Enabled +modes for SGX, +choose +.I Enabled. +.PP +SGX is available only if the kernel was configured and built with the +.B CONFIG_X86_SGX +option. +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 create an enclave by using the +.BR ioctl (2) +interface provided and documented by +.IR <asm/sgx.h> +to +.I /dev/sgx_enclave. +.PP +An enclave's base address is fixed during the build time: +it is given to +.B SGX_IOC_ENCLAVE_CREATE, +which initiates the whole enclave build process. +.PP +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 can lead to reserving a large region than required by the payload, +but the address space can be obviously trimmed after the enclave has been +constructed on, +with a sequence of +.BR mmap(MAP_FIXED) +calls. +.PP +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, +encapsulated into +.BR vsgx_enter_enclave +vDSO interface, +provided and documented by +.IR <asm/sgx.h>. +.SS Permissions +In order to build an enclave, a process must be able to call +.IR mmap (2) +with +.IR PROT_EXEC +set. +Like for any other type of executable, +the page permissions must be set appropriately. +For this reason, +.I /dev/sgx_enclave +must reside in a partition, +which is not mounted as no-exec, +in order to be usable, +as +.IR mmap(2) +denies +.IR PROT_EXEC +otherwise. +.SH VERSIONS +The SGX feature was added in Linux 5.11. +.SH SEE ALSO +.BR ioctl (2), +.BR mmap() (2), +.BR mprotect (2)
Signature · 1 line
2.31.1
man7/sgx.7 line 86
Quoted 6 lines · Jarkko Sakkinen
man7/sgx.7 new file +6
-0+This can lead to reserving a large region than required by the payload, +but the address space can be obviously trimmed after the enclave has been +constructed on, +with a sequence of +.BR mmap(MAP_FIXED) +calls.
Sorry if I missed this previously.
But, do we really intend to suggest the use of mmap(MAP_FIXED) for this?
What's the harm in leaving a non-populated piece of address space of
mmap()'d /dev/sgx_enclave?
Jarkko Sakkinen
maintainerQuoted 10 lines · Dave Hansen
man7/sgx.7 line 86
Quoted 6 lines · Jarkko Sakkinen
man7/sgx.7 new file +6
-0+This can lead to reserving a large region than required by the payload, +but the address space can be obviously trimmed after the enclave has been +constructed on, +with a sequence of +.BR mmap(MAP_FIXED) +calls.Sorry if I missed this previously.
Quoted 3 lines
But, do we really intend to suggest the use of
mmap(MAP_FIXED)for this?
What's the harm in leaving a non-populated piece of address space of
mmap()'d/dev/sgx_enclave?
Probably most of the time: not much. Especially since we support 64-bit only.
Maybe it should be relaxed a bit?
/Jarkko
Hi Jarkko,
On 5/10/2021 7:52 AM, Jarkko Sakkinen wrote:
...
man7/sgx.7 line 81
Quoted 3 lines
man7/sgx.7 new file +3
-0+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 can lead to reserving a large region than required by the payload,
a large region than required -> a larger region than required ?
Quoted 1 line
+but the address space can be obviously trimmed after the enclave has been
can be obviously trimmed -> can be trimmed ?
Quoted 1 line
+constructed on,
constructed on -> constructed ?
Quoted 4 lines
man7/sgx.7 new file +4
-0+with a sequence of +.BR mmap(MAP_FIXED) +calls. +.PP
man7/sgx.7 line 97
Quoted 10 lines
man7/sgx.7 new file +10
-0+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, +encapsulated into +.BR vsgx_enter_enclave +vDSO interface, +provided and documented by +.IR <asm/sgx.h>.
This is not clear to me. This is written as though vsgx_enter_enclave is something very specific that is documented in <asm/sgx.h>. Should it perhaps be vdso_sgx_enter_enclave_t instead? Am I missing where vsgx_enter_enclave is defined? I expect a reader of this man page may want to search for the term "vsgx_enter_enclave" after reading the above.
Quoted 13 lines
+.SS Permissions
man7/sgx.7 new file +12
-0+In order to build an enclave, a process must be able to call +.IR mmap (2) +with +.IR PROT_EXEC +set. +Like for any other type of executable, +the page permissions must be set appropriately. +For this reason, +.I /dev/sgx_enclave +must reside in a partition, +which is not mounted as no-exec, +in order to be usable,
man7/sgx.7 line 120
Quoted 10 lines
man7/sgx.7 new file +10
-0+as +.IR mmap(2) +denies +.IR PROT_EXEC +otherwise. +.SH VERSIONS +The SGX feature was added in Linux 5.11. +.SH SEE ALSO +.BR ioctl (2), +.BR mmap() (2),
mmap() (2) -> mmap (2) ?
Quoted 2 lines
+.BR mprotect (2)
Reinette
Jarkko Sakkinen
maintainerQuoted 32 lines · Reinette Chatre
Hi Jarkko,
On 5/10/2021 7:52 AM, Jarkko Sakkinen wrote:
...
man7/sgx.7 line 81
Quoted 3 lines
man7/sgx.7 new file +3
-0+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 can lead to reserving a large region than required by the payload,a large region than required -> a larger region than required ?
Quoted 1 line
+but the address space can be obviously trimmed after the enclave has been
can be obviously trimmed -> can be trimmed ?
Quoted 1 line
+constructed on,
constructed on -> constructed ?
Quoted 12 lines
man7/sgx.7 new file +12
-0+with a sequence of +.BR mmap(MAP_FIXED) +calls. +.PP +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, +encapsulated into +.BR vsgx_enter_enclave +vDSO interface,
Quoted 8 lines
Quoted 2 lines
+provided and documented by
+.IR <asm/sgx.h>.This is not clear to me. This is written as though
vsgx_enter_enclaveis something very specific that is documented in <asm/sgx.h>. Should it perhaps bevdso_sgx_enter_enclave_tinstead? Am I missing wherevsgx_enter_enclaveis defined? I expect a reader of this man page may want to search for the term "vsgx_enter_enclave" after reading the above.
Yeah, it's now incorrect. I'll fix this. Thanks for pointing out.
Quoted 27 lines
Quoted 14 lines
+.SS Permissions
man7/sgx.7 new file +12
-0+In order to build an enclave, a process must be able to call +.IR mmap (2) +with +.IR PROT_EXEC +set. +Like for any other type of executable, +the page permissions must be set appropriately. +For this reason, +.I /dev/sgx_enclave +must reside in a partition, +which is not mounted as no-exec, +in order to be usable,man7/sgx.7 line 120
Quoted 10 lines
man7/sgx.7 new file +10
-0+as +.IR mmap(2) +denies +.IR PROT_EXEC +otherwise. +.SH VERSIONS +The SGX feature was added in Linux 5.11. +.SH SEE ALSO +.BR ioctl (2), +.BR mmap() (2),
mmap()(2) -> mmap (2) ?
Quoted 4 lines
Quoted 2 lines
+.BR mprotect (2)
Reinette
Also, other remarks make sense to me, thanks.
/Jarkko