From patchwork Sun Dec 24 19:56:52 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Jarkko Sakkinen X-Patchwork-Id: 10132211 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 5AFCB605BD for ; Mon, 25 Dec 2017 02:06:07 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 4948428CCC for ; Mon, 25 Dec 2017 02:06:07 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 3E60C28CCF; Mon, 25 Dec 2017 02:06:07 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 Received: from ml01.01.org (ml01.01.org [198.145.21.10]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 07B9928CCE for ; Mon, 25 Dec 2017 02:06:06 +0000 (UTC) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 45E9821CB87C9; Sun, 24 Dec 2017 18:01:08 -0800 (PST) X-Original-To: intel-sgx-kernel-dev@lists.01.org Delivered-To: intel-sgx-kernel-dev@lists.01.org Received-SPF: None (no SPF record) identity=mailfrom; client-ip=134.134.136.31; helo=mga06.intel.com; envelope-from=jarkko.sakkinen@linux.intel.com; receiver=intel-sgx-kernel-dev@lists.01.org Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id B41D622225C16 for ; Sun, 24 Dec 2017 11:58:24 -0800 (PST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga104.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 24 Dec 2017 12:03:16 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.45,451,1508828400"; d="scan'208";a="21028137" Received: from egore-mobl1.ger.corp.intel.com (HELO localhost) ([10.249.254.130]) by orsmga002.jf.intel.com with ESMTP; 24 Dec 2017 12:03:12 -0800 From: Jarkko Sakkinen To: intel-sgx-kernel-dev@lists.01.org, platform-driver-x86@vger.kernel.org, x86@kernel.org Date: Sun, 24 Dec 2017 21:56:52 +0200 Message-Id: <20171224195854.2291-7-jarkko.sakkinen@linux.intel.com> X-Mailer: git-send-email 2.14.1 In-Reply-To: <20171224195854.2291-1-jarkko.sakkinen@linux.intel.com> References: <20171224195854.2291-1-jarkko.sakkinen@linux.intel.com> MIME-Version: 1.0 X-Mailman-Approved-At: Sun, 24 Dec 2017 18:01:07 -0800 Subject: [intel-sgx-kernel-dev] [PATCH v10 6/7] intel_sgx: driver documentation X-BeenThere: intel-sgx-kernel-dev@lists.01.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: =?iso-8859-1?q?Project=3A_Intel=AE_Software_Guard_Extensions_for_Linux*=3A_https=3A//01=2Eorg/intel-software-guard-extensions?= List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "open list:DOCUMENTATION" , Jonathan Corbet , open list , Ingo Molnar , "H. Peter Anvin" , Thomas Gleixner Errors-To: intel-sgx-kernel-dev-bounces@lists.01.org Sender: "intel-sgx-kernel-dev" X-Virus-Scanned: ClamAV using ClamSMTP Signed-off-by: Jarkko Sakkinen Tested-by: Serge Ayoun --- Documentation/index.rst | 1 + Documentation/x86/intel_sgx.rst | 168 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+) create mode 100644 Documentation/x86/intel_sgx.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index cb7f1ba5b3b1..ccfebc260e04 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -86,6 +86,7 @@ implementation. :maxdepth: 2 sh/index + x86/index Korean translations ------------------- diff --git a/Documentation/x86/intel_sgx.rst b/Documentation/x86/intel_sgx.rst new file mode 100644 index 000000000000..3a49415be62b --- /dev/null +++ b/Documentation/x86/intel_sgx.rst @@ -0,0 +1,168 @@ +=================== +Intel(R) SGX driver +=================== + +Introduction +============ + +Intel(R) SGX is a set of CPU instructions that can be used by applications to +set aside private regions of code and data. The code outside the enclave is +disallowed to access the memory inside the enclave by the CPU access control. +In a way you can think that SGX provides inverted sandbox. It protects the +application from a malicious host. + +You can tell if your CPU supports SGX by looking into ``/proc/cpuinfo``: + + ``cat /proc/cpuinfo | grep sgx`` + +Overview of SGX +=============== + +SGX has a set of data structures to maintain information about the enclaves and +their security properties. BIOS reserves a fixed size region of physical memory +for these structures by setting Processor Reserved Memory Range Registers +(PRMRR). + +This memory range is protected from outside access by the CPU and all the data +coming in and out of the CPU package is encrypted by a key that is generated for +each boot cycle. + +Enclaves execute in ring-3 in a special enclave submode using pages from the +reserved memory range. A fixed logical address range for the enclave is reserved +by ENCLS(ECREATE), a leaf instruction used to create enclaves. It is referred in +the documentation commonly as the ELRANGE. + +Every memory access to the ELRANGE is asserted by the CPU. If the CPU is not +executing in the enclave mode inside the enclave, #GP is raised. On the other +hand enclave code can make memory accesses both inside and outside of the +ELRANGE. + +Enclave can only execute code inside the ELRANGE. Instructions that may cause +VMEXIT, IO instructions and instructions that require a privilege change are +prohibited inside the enclave. Interrupts and exceptions always cause enclave +to exit and jump to an address outside the enclave given when the enclave is +entered by using the leaf instruction ENCLS(EENTER). + +Data types +---------- + +The protected memory range contains the following data: + +* **Enclave Page Cache (EPC):** protected pages +* **Enclave Page Cache Map (EPCM):** a database that describes the state of the + pages and link them to an enclave. + +EPC has a number of different types of pages: + +* **SGX Enclave Control Structure (SECS)**: describes the global + properties of an enclave. +* **Regular (REG):** code and data pages in the ELRANGE. +* **Thread Control Structure (TCS):** pages that define entry points inside an + enclave. The enclave can only be entered through these entry points and each + can host a single hardware thread at a time. +* **Version Array (VA)**: 64-bit version numbers for pages that have been + swapped outside the enclave. Each page contains 512 version numbers. + +Launch control +-------------- + +To launch an enclave, two structures must be provided for ENCLS(EINIT): + +1. **SIGSTRUCT:** signed measurement of the enclave binary. +2. **EINITTOKEN:** a cryptographic token CMAC-signed with a AES256-key called + *launch key*, which is re-generated for each boot cycle. + +The CPU holds a SHA256 hash of a 3072-bit RSA public key inside +IA32_SGXLEPUBKEYHASHn MSRs. Enclaves with a SIGSTRUCT that is signed with this +key do not require a valid EINITTOKEN and can be authorized with special +privileges. One of those privileges is ability to acquire the launch key with +ENCLS(EGETKEY). + +**IA32_FEATURE_CONTROL[17]** is used by to BIOS configure whether +IA32_SGXLEPUBKEYHASH MSRs are read-only or read-write before locking the +feature control register and handing over control to the operating system. + +Enclave construction +-------------------- + +The construction is started by filling out the SECS that contains enclave +address range, privileged attributes and measurement of TCS and REG pages (pages +that will be mapped to the address range) among the other things. This structure +is passed out to the ENCLS(ECREATE) together with a physical address of a page +in EPC that will hold the SECS. + +Then pages are added with ENCLS(EADD) and measured with ENCLS(EEXTEND). Finally +enclave is initialized with ENCLS(EINIT). ENCLS(INIT) checks that the SIGSTRUCT +is signed with the contained public key and that the supplied EINITTOKEN is +valid (CMAC'd with the launch key). If these hold, the enclave is successfully +initialized. + +Swapping pages +-------------- + +Enclave pages can be swapped out with ENCLS(EWB) to the unprotected memory. In +addition to the EPC page, ENCLS(EWB) takes in a VA page and address for PCMD +structure (Page Crypto MetaData) as input. The VA page will seal a version +number for the page. PCMD is 128 byte structure that contains tracking +information for the page, most importantly its MAC. With these structures the +enclave is sealed and rollback protected while it resides in the unprotected +memory. + +Before the page can be swapped out it must not have any active TLB references. +By using ENCLS(EBLOCK) instructions no new TLB entries can be created to it. +After this the a counter called *epoch* associated hardware threads inside the +enclave is increased with ENCLS(ETRACK). After all the threads from the previous +epoch have exited the page can be safely swapped out. + +An enclave memory access to a swapped out pages will cause #PF. #PF handler can +fault the page back by using ENCLS(ELDU). + +Driver internals +================ + +Launching enclaves +------------------ + +For privileged enclaves the launch is performed simply by submitting the +SIGSTRUCT for that enclave to ENCLS(EINIT). For unprivileged enclaves the +driver hosts a process in ring-3 that hosts a launch enclave signed with a key +supplied for kbuild. + +The current implementation of the launch enclave generates a token for any +enclave. In the future it could be potentially extended to have ways to +configure policy what can be lauched. + +The driver will fail to initialize if it cannot start its own launch enclave. +A user space application can submit a SIGSTRUCT instance through the ioctl API. +The kernel will take care of the rest. + +This design assures that the Linux kernel has always full control, which +enclaves get to launch and which do not, even if the public key MSRs are +read-only. Having launch intrinsics inside the kernel also enables easy +development of enclaves without necessarily needing any heavy weight SDK. +Having a low-barrier to implement enclaves could make sense for example for +system daemons where amount of dependecies ought to be minimized. + +Swapper +------- + +The driver has a trivial implementation of swapping code in sgx_page_cache.c, +which swaps pages from processes and enclaves in a round-robin fashion. In +future it would probably make sense to find a way to let the Linux swapper to +pick the victim pages but it is not currently doable because EPC pages do not +have associated page structures. + +SGX uapi +======== + +.. kernel-doc:: drivers/platform/x86/intel_sgx/sgx_ioctl.c + :functions: sgx_ioc_enclave_create + sgx_ioc_enclave_add_page + sgx_ioc_enclave_init + +.. kernel-doc:: arch/x86/include/uapi/asm/sgx.h + +References +========== + +* System Programming Manual: 39.1.4 Intel® SGX Launch Control Configuration