| Message ID | 20210510145235.8056-1-jarkko@kernel.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v5] sgx.7: New page with overview of Software Guard eXtensions (SGX) | expand |
On 5/10/21 7:52 AM, Jarkko Sakkinen wrote: > +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?
On Mon, May 10, 2021 at 07:58:27AM -0700, Dave Hansen wrote: > On 5/10/21 7:52 AM, Jarkko Sakkinen wrote: > > +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? 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: ... > +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 ? > +but the address space can be obviously trimmed after the enclave has been can be obviously trimmed -> can be trimmed ? > +constructed on, constructed on -> constructed ? > +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>. 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. > +.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), mmap() (2) -> mmap (2) ? > +.BR mprotect (2) > Reinette
On Tue, May 11, 2021 at 01:22:10PM -0700, Reinette Chatre wrote: > Hi Jarkko, > > On 5/10/2021 7:52 AM, Jarkko Sakkinen wrote: > > ... > > > +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 ? > > > +but the address space can be obviously trimmed after the enclave has been > > can be obviously trimmed -> can be trimmed ? > > > +constructed on, > > constructed on -> constructed ? > > > +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>. > > 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. Yeah, it's now incorrect. I'll fix this. Thanks for pointing out. > > > +.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), > > mmap() (2) -> mmap (2) ? > > > +.BR mprotect (2) > > > > Reinette Also, other remarks make sense to me, thanks. /Jarkko
diff --git a/man7/sgx.7 b/man7/sgx.7 new file mode 100644 index 000000000..b93b0510e --- /dev/null +++ b/man7/sgx.7 @@ -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)
Signed-off-by: Jarkko Sakkinen <jarkko@kernel.org> --- 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