From: Jarkko Sakkinen <email@example.com>
To: Michael Kerrisk <firstname.lastname@example.org>
Cc: email@example.com, firstname.lastname@example.org,
Dave Hansen <email@example.com>,
Reinette Chatre <firstname.lastname@example.org>,
Jarkko Sakkinen <email@example.com>
Subject: [PATCH v11] sgx.7: New page with overview of Software Guard eXtensions (SGX)
Date: Sat, 11 Dec 2021 17:33:20 +0200 [thread overview]
Message-ID: <firstname.lastname@example.org> (raw)
Signed-off-by: Jarkko Sakkinen <email@example.com>
* Address Reinette's remarks for v10:
* v9 was malformed, essentially a resend.
* Rename "Address Space" section as "Memory mapping", and refine the
* Rename "Ioctls" section as "Construction", and refine the text.
* Fix errors reported for the previous version.
* Added more meat about the address space and API.
* Reorganized the text to have focus more on developer to have a big
picture of kernel provided interfaces.
* 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 | 146 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 146 insertions(+)
create mode 100644 man7/sgx.7
diff --git a/man7/sgx.7 b/man7/sgx.7
new file mode 100644
@@ -0,0 +1,146 @@
+.\" 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
+.\" 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
+.B #include <asm/sgx.h>
+.IB enclave " = open(""/dev/sgx_enclave"", O_RDWR);"
+Intel Software Guard eXtensions (SGX) allow applications to host
+protected executable objects in memory.
+Enclaves are blobs of executable code,
+running inside a CPU enforced container,
+which is mapped to the process address space.
+They are represented as the instances of
+.IR /dev/sgx_enclave .
+They have a fixed set of entry points,
+defined when the enclave is built.
+SGX can only be available if the kernel is configured and built with the
+If CPU, BIOS and kernel have SGX enabled,
+appears in the
+.IR /proc/cpuinfo .
+If SGX appears not to be available,
+ensure that SGX is enabled in the BIOS.
+If a BIOS presents a choice between
+.I Software Enabled
+modes for SGX,
+.IR Enabled .
+.SS Memory mapping
+The file descriptor for an enclave can be shared among multiple processes.
+An enclave is required by the CPU to be placed to an address,
+which is a multiple of its size.
+An address range containing a reasonable base address can be probed with an anonymous
+void *area = mmap(NULL, size * 2, PROT_NONE, MAP_PRIVATE | MAP_ANONYMOUS,
+ -1, 0);
+void *base = ((uint64_t)area + size - 1) & ~(size - 1);
+The enclave file descriptor itself can be then mapped with the
+flag set to the carved out memory.
+An enclave instance is created by opening
+.IR /dev/sgx_enclave .
+Its contents are populated with the
+.BR ioctl (2)
+.IR <asm/sgx.h> :
+Create SGX Enclave Control Structure (SECS) for the enclave.
+SECS is a hardware defined structure,
+which contains the global properties of an enclave.
+is a one-shot call that fixes the enclave's address and
+size for the rest of its life-cycle.
+Fill a range of the enclave's pages with the caller provided data and protection bits.
+Memory mappings of the enclave can only set protection bits that are defined in this ioctl.
+The pages added are either regular pages for code and data,
+or thread control structures (TCS).
+The latter define the entry points to the enclave,
+which can be entered after the initialization.
+Initialize the enclave for the run-time.
+After a successful initialization,
+no new pages can be added to the enclave.
+Thread control structure (TCS) pages are the entry points to the enclave,
+which further define an offset inside the enclave where the execution begins.
+The entry points are invoked with
+.IR __vdso_sgx_enter_enclave .
+The prototype for the vDSO is defined by
+.IR <asm/sgx.h> .
+During the build process each enclave page is assigned protection bits,
+as part of
+These protections are also the maximum protections with which the page can be be mapped.
+.BR mmap (2)
+is called with higher protections than those defined during the build,
+it will return
+is called after
+.BR mmap (2)
+with lower protections,
+the caller receives
+once it accesses the page for the first time.
+The SGX feature was added in Linux 5.11.
+.SH SEE ALSO
+.BR ioctl (2),
+.BR mmap (2),
+.BR mprotect (2)
next reply other threads:[~2021-12-11 15:33 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-12-11 15:33 Jarkko Sakkinen [this message]
2021-12-17 1:50 ` [PATCH v11] sgx.7: New page with overview of Software Guard eXtensions (SGX) Alejandro Colomar (man-pages)
2022-01-28 1:19 ` Jarkko Sakkinen
2022-02-09 20:19 ` Alejandro Colomar (man-pages)
2022-02-20 20:05 ` Jarkko Sakkinen
2023-03-30 22:29 ` Alejandro Colomar
2023-04-21 21:13 ` Jarkko Sakkinen
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).