Linux-Sgx Archive on lore.kernel.org
 help / color / Atom feed
From: Randy Dunlap <rdunlap@infradead.org>
To: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>,
	linux-kernel@vger.kernel.org, x86@kernel.org,
	linux-sgx@vger.kernel.org
Cc: akpm@linux-foundation.org, dave.hansen@intel.com,
	sean.j.christopherson@intel.com, nhorman@redhat.com,
	npmccallum@redhat.com, haitao.huang@intel.com,
	andriy.shevchenko@linux.intel.com, tglx@linutronix.de,
	kai.svahn@intel.com, bp@alien8.de, josh@joshtriplett.org,
	luto@kernel.org, kai.huang@intel.com, rientjes@google.com,
	cedric.xing@intel.com, puiterwijk@redhat.com,
	linux-doc@vger.kernel.org
Subject: Re: [PATCH v25 21/21] docs: x86/sgx: Document SGX micro architecture and kernel internals
Date: Wed, 5 Feb 2020 09:54:31 -0800
Message-ID: <5ea28632-cd64-bc26-fab6-2868142eb9e4@infradead.org> (raw)
In-Reply-To: <20200204060545.31729-22-jarkko.sakkinen@linux.intel.com>

Hi,
I have some Documentation edits. Please see inline below...


On 2/3/20 10:05 PM, Jarkko Sakkinen wrote:
> Document Intel SGX micro architecture and kernel internals. The motivation
> is to make the core ideas approachable by keeping a fairly high abstraction
> level. Fine-grained micro architecture details can be looked up from Intel
> SDM Volume 3D.
> 
> Cc: Andy Lutomirski <luto@kernel.org>
> Cc: linux-doc@vger.kernel.org
> Co-developed-by: Sean Christopherson <sean.j.christopherson@intel.com>
> Signed-off-by: Sean Christopherson <sean.j.christopherson@intel.com>
> Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
> ---
>  Documentation/x86/index.rst |   1 +
>  Documentation/x86/sgx.rst   | 177 ++++++++++++++++++++++++++++++++++++
>  2 files changed, 178 insertions(+)
>  create mode 100644 Documentation/x86/sgx.rst

> diff --git a/Documentation/x86/sgx.rst b/Documentation/x86/sgx.rst
> new file mode 100644
> index 000000000000..04deaba83981
> --- /dev/null
> +++ b/Documentation/x86/sgx.rst
> @@ -0,0 +1,177 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +============
> +Architecture
> +============
> +
> +Introduction
> +============
> +
> +*Software Guard eXtensions (SGX)* is a set of instructions and that enable

                                                   drop:      and

> +ring-3 applications to set aside private regions of code and data. These regions
> +are called enclaves. Enclave can be entered to a fixed set of entry points. Only

                        An enclave can be entered by a fixed set of entry points.

> +a CPU running inside the enclave can access its code and data.
> +
> +SGX support can be determined by
> +
> +	``cat /proc/cpuinfo | grep sgx``

or just: ``grep sgx /proc/cpuinfo

> +
> +Enclave Page Cache``

> +==================
> +
> +SGX utilizes an *Enclave Page Cache (EPC)* to store pages that are associated
> +with an enclave. It is contained in a BIOS reserved region of physical memory.
> +Unlike pages used for regular memory, pages can only be accessed outside the
> +enclave for different purposes with the instructions **ENCLS**, **ENCLV** and
> +**ENCLU**.
> +
> +Direct memory accesses to an enclave can be only done by a CPU executing inside
> +the enclave. Enclave can be entered with **ENCLU[EENTER]** leaf function to a

                An enclave can be entered with the

> +fixed set of entry points. However, a CPU executing inside the enclave can do
> +outside memory accesses.
> +
> +Page Types
> +----------
> +
> +**SGX Enclave Control Structure (SECS)**
> +   Enclave's address range, attributes and other global data is defined

                                                                are defined
 
> +   by this structure.
> +
> +**Regular (REG)**
> +   Regular EPC pages contain the code and data of an enclave.
> +
> +**Thread Control Structure (TCS)**
> +   Thread Control Structure pages define the entry points to an enclave and
> +   track the execution state of an enclave thread.
> +
> +**Version Array (VA)**
> +   Version Array pages contain 512 slots, each of which can contain a version
> +   number for a page evicted from the EPC.
> +
> +Enclave Page Cache Map
> +----------------------
> +
> +The processor tracks EPC pages via the *Enclave Page Cache Map (EPCM)*.  EPCM
> +contains entry for each EPC page, which describes the owning enclave, access

   contains an entry for each

> +rights and page type among the other things.
> +
> +The permissions from EPCM is consulted if and only if walking the kernel page
> +tables succeeds. The total permissions are thus a conjunction between page table
> +and EPCM permissions.
> +
> +For all intents and purposes the SGX architecture allows the processor to
> +invalidate all EPCM entries at will, i.e. requires that software be prepared to
> +handle an EPCM fault at any time. The contents of EPC are encrypted with an
> +ephemeral key, which is lost on power transitions.
> +
> +EPC management
> +==============
> +
> +EPC pages do not have ``struct page`` instances. They are IO memory from kernel
> +perspective. The consequence is that they are always mapped as shared memory.
> +Kernel defines ``/dev/sgx/enclave`` that can be mapped as ``MAP_SHARED`` to
> +define the address range for an enclave.
> +
> +EPC Over-subscription
> +=====================
> +
> +When the amount of free EPC pages goes below a low watermark the swapping thread
> +starts reclaiming pages. The pages that have no do not have the **A** bit set

                                     drop: have no

> +are selected as victim pages. Each enclave holds an shmem file as a backing
> +storage for reclaimed pages.
> +
> +Launch Control
> +==============
> +
> +SGX provides a launch control mechanism. After all enclave pages have been
> +copied, kernel executes **ENCLS[EINIT]**, which initializes the enclave. Only
> +after this the CPU can execute inside the enclave.
> +
> +This leaf function takes a RSA-3072 signature of the enclave measurement and an

                      takes an

> +optional cryptographic token. Linux does not take advantage of launch tokens.
> +The instruction checks that the signature is signed with the key defined in
> +**IA32_SGXLEPUBKEYHASH?** MSRs and the measurement is correct. If so, the
> +enclave is allowed to be executed.
> +
> +MSRs can be configured by the BIOS to be either readable or writable.  Linux
> +supports only writable configuration in order give full control to the kernel on

                                        in order to give

> +launch control policy. Readable configuration requires the use of previously
> +mentioned launch tokens.
> +
> +The current kernel implementation supports only writable MSRs. The launch is
> +performed by setting the MSRs to the hash of the enclave signer's public key.
> +Alternative would be to have *a launch enclave* that would be signed with the

   The alternative would be

> +key set into MSRs, which would then generate launch tokens for other enclaves.
> +This would only make sense with read-only MSRs, and thus the option has been
> +discluded.

I can't find "discluded" in a dictionary.

> +
> +Attestation
> +===========
> +
> +Local Attestation
> +-----------------
> +
> +In local attestation the source enclave calculates a MAC of itself with

"MAC" can mean a lots of different things.  Which one is this?

> +**ENCLS[EREPORT]**. Then the destination enclave verifies this with
> +**ENCLS[EGETKEY(REPORT)]** key. This mechanism can also be used in addition as a
> +communication channel as the **REPORT** data structure includes 64 byte field

                                                          includes a 64-byte field

> +for passing variable information.
> +
> +Remote Attestation
> +------------------
> +
> +For remote attestation (aka provisioning) there a multiple options available:

                                             there are

> +
> +* An EPID based scheme, which requires the use of Intel managed attestation

Drop: "An " to make it similar to next bullet point.

> +  service.
> +* ECDSA based scheme, which 3rd party to act as an attestation service.

                         which uses a 3rd party
or
                         using a 3rd party

> +
> +Intel provides an open source *quoting enclave (QE)* and *provisioning
> +certification enclave (PCE)* for the ECDSA based scheme. The latter acts as
> +the CA for the local QE's. Intel also a precompiled binary version of the PCE

                                    also provides [??]

> +so that, if required, quotation can be linked to the hardware.
> +
> +The use of remote attestation must be strictly controlled because it allows to
> +get access to the provisioning keys to attest to a remote party that the
> +software is running inside a legitimate enclave on real hardware. This could be
> +potentially used by malware, and thus must be protected.
> +
> +Enclaves can attest their identity when **ATTRIBUTES.PROVISIONKEY** set in SECS.

                                                                       is set in SECS.

> +This attribute authorizes **ENCLS[EGETKEY]** to access provisioning keys.
> +
> +Kernel defines ``/dev/sgx/provision`` and a special ioctl
> +``SGX_IOC_ENCLAVE_SET_ATTRIBUTE`` to accomplish this. A file descriptor pointing
> +to ``/dev/sgx/provision`` is passed to ioctl from which kernel authorizes the
> +use of remote attestation keys. This must be called before
> +``SGX_IOC_ENCL_CREATE`` if remote attestation is required.
> +
> +References
> +----------
> +
> +"Intel® Software Guard Extensions: EPID Provisioning and Attestation Services"
> +   https://software.intel.com/sites/default/files/managed/57/0e/ww10-2016-sgx-provisioning-and-attestation-final.pdf
> +
> +"Supporting Third Party Attestation for Intel® SGX with Intel® Data Center
> +Attestation Primitives"
> +   https://software.intel.com/sites/default/files/managed/f1/b8/intel-sgx-support-for-third-party-attestation.pdf
> +
> +Usage Models
> +============
> +
> +Shared Library
> +--------------
> +
> +Sensitive data and the code that acts on it is partitioned from the application
> +into a separate library. The library is then linked as a DSO which can be loaded
> +into an enclave. The application can then make individual function calls into
> +the enclave through special SGX instructions. A run-time within the enclave is
> +configured to marshall function parameters into and out of the enclave and to

                 marshal

> +call the correct library function.
> +
> +Application Container
> +---------------------
> +
> +An application may be loaded into a container enclave which is specially
> +configured with a library OS and run-time which permits the application to run.
> +The enclave run-time and library OS work together to execute the application
> +when a thread enters the enclave.
> 

cheers.
-- 
~Randy

  reply index

Thread overview: 39+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-02-04  6:05 [PATCH v25 00/21] Intel SGX foundations Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 01/21] x86/cpufeatures: x86/msr: Add Intel SGX hardware bits Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 02/21] x86/cpufeatures: x86/msr: Intel SGX Launch Control " Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 03/21] x86/mm: x86/sgx: Signal SIGSEGV with PF_SGX Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 04/21] x86/sgx: Add SGX microarchitectural data structures Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 05/21] x86/sgx: Add wrappers for ENCLS leaf functions Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 06/21] x86/cpu/intel: Detect SGX supprt Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 07/21] x86/sgx: Enumerate and track EPC sections Jarkko Sakkinen
2020-02-05 19:57   ` Sean Christopherson
2020-02-05 23:11     ` Jarkko Sakkinen
2020-02-06 15:34       ` Jarkko Sakkinen
2020-02-06 15:35     ` Jarkko Sakkinen
2020-02-06 15:55       ` Sean Christopherson
2020-02-04  6:05 ` [PATCH v25 08/21] x86/sgx: Add functions to allocate and free EPC pages Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 09/21] mm: Introduce vm_ops->may_mprotect() Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 10/21] x86/sgx: Linux Enclave Driver Jarkko Sakkinen
2020-02-04  6:18   ` Jarkko Sakkinen
2020-02-05 15:58   ` Haitao Huang
2020-02-07 17:03   ` Haitao Huang
2020-02-04  6:05 ` [PATCH v25 11/21] selftests/x86: Recurse into subdirectories Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 12/21] selftests/x86: Add a selftest for SGX Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 13/21] x86/sgx: Add provisioning Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 14/21] x86/sgx: Add a page reclaimer Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 15/21] x86/sgx: ptrace() support for the SGX driver Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 16/21] x86/vdso: Add support for exception fixup in vDSO functions Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 17/21] x86/fault: Add helper function to sanitize error code Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 18/21] x86/traps: Attempt to fixup exceptions in vDSO before signaling Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 19/21] x86/vdso: Add __vdso_sgx_enter_enclave() to wrap SGX enclave transitions Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 20/21] selftests/x86: Add vDSO selftest for SGX Jarkko Sakkinen
2020-02-04  6:05 ` [PATCH v25 21/21] docs: x86/sgx: Document SGX micro architecture and kernel internals Jarkko Sakkinen
2020-02-05 17:54   ` Randy Dunlap [this message]
2020-02-05 23:07     ` Jarkko Sakkinen
2020-02-05 23:10       ` Randy Dunlap
2020-02-06 14:50         ` Jarkko Sakkinen
2020-02-04 15:11 ` [PATCH v25 00/21] Intel SGX foundations Sean Christopherson
2020-02-05 21:59   ` Jarkko Sakkinen
2020-02-05 23:09     ` Jarkko Sakkinen
2020-02-05 16:01 ` Haitao Huang
2020-02-05 22:01   ` 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=5ea28632-cd64-bc26-fab6-2868142eb9e4@infradead.org \
    --to=rdunlap@infradead.org \
    --cc=akpm@linux-foundation.org \
    --cc=andriy.shevchenko@linux.intel.com \
    --cc=bp@alien8.de \
    --cc=cedric.xing@intel.com \
    --cc=dave.hansen@intel.com \
    --cc=haitao.huang@intel.com \
    --cc=jarkko.sakkinen@linux.intel.com \
    --cc=josh@joshtriplett.org \
    --cc=kai.huang@intel.com \
    --cc=kai.svahn@intel.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-sgx@vger.kernel.org \
    --cc=luto@kernel.org \
    --cc=nhorman@redhat.com \
    --cc=npmccallum@redhat.com \
    --cc=puiterwijk@redhat.com \
    --cc=rientjes@google.com \
    --cc=sean.j.christopherson@intel.com \
    --cc=tglx@linutronix.de \
    --cc=x86@kernel.org \
    /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-Sgx Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-sgx/0 linux-sgx/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-sgx linux-sgx/ https://lore.kernel.org/linux-sgx \
		linux-sgx@vger.kernel.org
	public-inbox-index linux-sgx

Example config snippet for mirrors

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


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