Linux-man Archive on lore.kernel.org
 help / color / Atom feed
From: Jarkko Sakkinen <jarkko@kernel.org>
To: mtk.manpages@gmail.com
Cc: linux-man@vger.kernel.org, linux-sgx@vger.kernel.org,
	dave.hansen@linux.intel.com, Jarkko Sakkinen <jarkko@kernel.org>
Subject: [PATCH v5] sgx.7: New page with overview of Software Guard eXtensions (SGX)
Date: Mon, 10 May 2021 17:52:35 +0300
Message-ID: <20210510145235.8056-1-jarkko@kernel.org> (raw)

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


             reply index

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-10 14:52 Jarkko Sakkinen [this message]
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

Reply instructions:

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:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210510145235.8056-1-jarkko@kernel.org \
    --to=jarkko@kernel.org \
    --cc=dave.hansen@linux.intel.com \
    --cc=linux-man@vger.kernel.org \
    --cc=linux-sgx@vger.kernel.org \
    --cc=mtk.manpages@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git