From patchwork Mon Nov 13 19:45:28 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Jarkko Sakkinen X-Patchwork-Id: 10056623 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 4F69060365 for ; Mon, 13 Nov 2017 19:46:25 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3D8AA2958A for ; Mon, 13 Nov 2017 19:46:25 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 319E729592; Mon, 13 Nov 2017 19:46:25 +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 B39D929031 for ; Mon, 13 Nov 2017 19:46:24 +0000 (UTC) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 073DD2035A7A4; Mon, 13 Nov 2017 11:42:18 -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 D4E082035A7A2 for ; Mon, 13 Nov 2017 11:42:16 -0800 (PST) Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga104.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 13 Nov 2017 11:46:23 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.44,389,1505804400"; d="scan'208";a="1834775" Received: from patanegi-mobl.ger.corp.intel.com (HELO localhost) ([10.249.254.202]) by orsmga003.jf.intel.com with ESMTP; 13 Nov 2017 11:46:20 -0800 From: Jarkko Sakkinen To: intel-sgx-kernel-dev@lists.01.org Date: Mon, 13 Nov 2017 21:45:28 +0200 Message-Id: <20171113194528.28557-12-jarkko.sakkinen@linux.intel.com> X-Mailer: git-send-email 2.14.1 In-Reply-To: <20171113194528.28557-1-jarkko.sakkinen@linux.intel.com> References: <20171113194528.28557-1-jarkko.sakkinen@linux.intel.com> MIME-Version: 1.0 Subject: [intel-sgx-kernel-dev] [PATCH v5 11/11] intel_sgx: driver documentation X-BeenThere: intel-sgx-kernel-dev@lists.01.org X-Mailman-Version: 2.1.22 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: linux-kernel@vger.kernel.org, platform-driver-x86@vger.kernel.org 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 --- Documentation/index.rst | 1 + Documentation/x86/intel_sgx.rst | 131 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 132 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..34bcf6a2a495 --- /dev/null +++ b/Documentation/x86/intel_sgx.rst @@ -0,0 +1,131 @@ +=================== +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. + +There is a new hardware unit in the processor called Memory Encryption Engine +(MEE) starting from the Skylake microarchitecture. BIOS can define one or many +MEE regions that can hold enclave data by configuring them with PRMRR registers. + +The MEE automatically encrypts the data leaving the processor package to the MEE +regions. The data is encrypted using a random key whose life-time is exactly one +power cycle. + +You can tell if your CPU supports SGX by looking into ``/proc/cpuinfo``: + + ``cat /proc/cpuinfo | grep sgx`` + +Enclave data types +================== + +SGX defines new data types to maintain information about the enclaves and their +security properties. + +The following data structures exist in MEE regions: + +* **Enclave Page Cache (EPC):** memory pages for protected code and data +* **Enclave Page Cache Map (EPCM):** meta-data for each EPC page + +The Enclave Page Cache holds following types of pages: + +* **SGX Enclave Control Structure (SECS)**: meta-data defining the global + properties of an enclave such as range of addresses it can access. +* **Regular (REG):** containing code and data for the enclave. +* **Thread Control Structure (TCS):** defines an entry point for a hardware + thread to enter into the enclave. The enclave can only be entered through + these entry points. +* **Version Array (VA)**: an EPC page receives a unique 8 byte version number + when it is swapped, which is then stored into a VA page. A VA page can hold up + to 512 version numbers. + +Launch control +============== + +For launching an enclave, two structures must be provided for ENCLS(EINIT): + +1. **SIGSTRUCT:** a signed measurement of the enclave binary. +2. **EINITTOKEN:** the measurement, the public key of the signer and various + enclave attributes. This structure contains a MAC of its contents using + hardware derived symmetric key called *launch key*. + +The hardware platform contains a root key pair for signing the SIGTRUCT +for a *launch enclave* that is able to acquire the *launch key* for +creating EINITTOKEN's for other enclaves. For the launch enclave +EINITTOKEN is not needed because it is signed with the private root key. + +There are two feature control bits associate with launch control + +* **IA32_FEATURE_CONTROL[0]**: locks down the feature control register +* **IA32_FEATURE_CONTROL[17]**: allow runtime reconfiguration of + IA32_SGXLEPUBKEYHASHn MSRs that define MRSIGNER hash for the launch + enclave. Essentially they define a signing key that does not require + EINITTOKEN to be let run. + +The BIOS can configure IA32_SGXLEPUBKEYHASHn MSRs before feature control +register is locked. + +It could be tempting to implement launch control by writing the MSRs +every time when an enclave is launched. This does not scale because for +generic case because BIOS might lock down the MSRs before handover to +the OS. + +Debug enclaves +-------------- + +Enclave can be set as a *debug enclave* of which memory can be read or written +by using the ENCLS(EDBGRD) and ENCLS(EDBGWR) opcodes. The Intel provided launch +enclave provides them always a valid EINITTOKEN and therefore they are a low +hanging fruit way to try out SGX. + +Virtualization +============== + +Launch control +-------------- + +The values for IA32_SGXLEPUBKEYHASHn MSRs cannot be emulated for a virtual +machine guest. It would easily seem feasible to hold virtual values for these +MSRs, trap ENCLS(EINIT) and use the host LE to generate a token when a guest LE +is initialized. + +However, looking at the pseudo code of ENCLS(EINIT) from the SDM there is a +constraint that the instruction will fail if ATTRIBUTES.EINITTOKENKEY is set +(the documentation does not tell the reason why the constraint exists but it +exists). + +Thus, only when the MSRs are left unlocked before handover to the OS the +setting of these MSRs can be supported for VM guests. + +Suspend and resume +------------------ + +If the host suspends and resumes, the enclave memory for the VM guest could +become invalid. This can make ENCLS leaf operations suddenly fail. + +The driver has a graceful fallback mechanism to manage this situation. If any of +the ENCLS leaf operations fail, the driver will fallback by kicking threads out +of the enclave, removing the TCS entries and marking enclave as invalid. After +this no new pages can be allocated for the enclave and no entry can be done. + +SGX uapi +======== + +.. kernel-doc:: drivers/platform/x86/intel_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