* [PATCH v5] sgx.7: New page with overview of Software Guard eXtensions (SGX)
@ 2021-05-10 14:52 Jarkko Sakkinen
2021-05-10 14:58 ` Dave Hansen
2021-05-11 20:22 ` Reinette Chatre
0 siblings, 2 replies; 5+ messages in thread
From: Jarkko Sakkinen @ 2021-05-10 14:52 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, linux-sgx, dave.hansen, Jarkko Sakkinen
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
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)
--
2.31.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH v5] sgx.7: New page with overview of Software Guard eXtensions (SGX)
2021-05-10 14:52 [PATCH v5] sgx.7: New page with overview of Software Guard eXtensions (SGX) Jarkko Sakkinen
@ 2021-05-10 14:58 ` Dave Hansen
2021-05-10 17:33 ` Jarkko Sakkinen
2021-05-11 20:22 ` Reinette Chatre
1 sibling, 1 reply; 5+ messages in thread
From: Dave Hansen @ 2021-05-10 14:58 UTC (permalink / raw)
To: Jarkko Sakkinen, mtk.manpages; +Cc: linux-man, linux-sgx, dave.hansen
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?
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v5] sgx.7: New page with overview of Software Guard eXtensions (SGX)
2021-05-10 14:58 ` Dave Hansen
@ 2021-05-10 17:33 ` Jarkko Sakkinen
0 siblings, 0 replies; 5+ messages in thread
From: Jarkko Sakkinen @ 2021-05-10 17:33 UTC (permalink / raw)
To: Dave Hansen; +Cc: mtk.manpages, linux-man, linux-sgx, dave.hansen
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v5] sgx.7: New page with overview of Software Guard eXtensions (SGX)
2021-05-10 14:52 [PATCH v5] sgx.7: New page with overview of Software Guard eXtensions (SGX) Jarkko Sakkinen
2021-05-10 14:58 ` Dave Hansen
@ 2021-05-11 20:22 ` Reinette Chatre
2021-05-12 1:16 ` Jarkko Sakkinen
1 sibling, 1 reply; 5+ messages in thread
From: Reinette Chatre @ 2021-05-11 20:22 UTC (permalink / raw)
To: Jarkko Sakkinen, mtk.manpages; +Cc: linux-man, linux-sgx, dave.hansen
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v5] sgx.7: New page with overview of Software Guard eXtensions (SGX)
2021-05-11 20:22 ` Reinette Chatre
@ 2021-05-12 1:16 ` Jarkko Sakkinen
0 siblings, 0 replies; 5+ messages in thread
From: Jarkko Sakkinen @ 2021-05-12 1:16 UTC (permalink / raw)
To: Reinette Chatre; +Cc: mtk.manpages, linux-man, linux-sgx, dave.hansen
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
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2021-05-12 1:16 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-10 14:52 [PATCH v5] sgx.7: New page with overview of Software Guard eXtensions (SGX) Jarkko Sakkinen
2021-05-10 14:58 ` Dave Hansen
2021-05-10 17:33 ` Jarkko Sakkinen
2021-05-11 20:22 ` Reinette Chatre
2021-05-12 1:16 ` Jarkko Sakkinen
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.