From: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> To: intel-sgx-kernel-dev@lists.01.org, platform-driver-x86@vger.kernel.org, x86@kernel.org Cc: linux-kernel@vger.kernel.org, Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>, Jonathan Corbet <corbet@lwn.net>, Thomas Gleixner <tglx@linutronix.de>, Ingo Molnar <mingo@redhat.com>, "H. Peter Anvin" <hpa@zytor.com>, linux-doc@vger.kernel.org (open list:DOCUMENTATION) Subject: [PATCH v9 6/7] intel_sgx: driver documentation Date: Sat, 16 Dec 2017 18:19:53 +0200 [thread overview] Message-ID: <20171216162200.20243-7-jarkko.sakkinen@linux.intel.com> (raw) In-Reply-To: <20171216162200.20243-1-jarkko.sakkinen@linux.intel.com> Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> Tested-by: Serge Ayoun <serge.ayoun@intel.com> --- Documentation/index.rst | 1 + Documentation/x86/intel_sgx.rst | 101 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 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..59049a35512f --- /dev/null +++ b/Documentation/x86/intel_sgx.rst @@ -0,0 +1,101 @@ +=================== +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. + +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 -- 2.14.1
WARNING: multiple messages have this Message-ID (diff)
From: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> To: intel-sgx-kernel-dev@lists.01.org, platform-driver-x86@vger.kernel.org, x86@kernel.org Cc: linux-kernel@vger.kernel.org, Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>, Jonathan Corbet <corbet@lwn.net>, Thomas Gleixner <tglx@linutronix.de>, Ingo Molnar <mingo@redhat.com>, "H. Peter Anvin" <hpa@zytor.com>, "open list:DOCUMENTATION" <linux-doc@vger.kernel.org> Subject: [PATCH v9 6/7] intel_sgx: driver documentation Date: Sat, 16 Dec 2017 18:19:53 +0200 [thread overview] Message-ID: <20171216162200.20243-7-jarkko.sakkinen@linux.intel.com> (raw) In-Reply-To: <20171216162200.20243-1-jarkko.sakkinen@linux.intel.com> Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> Tested-by: Serge Ayoun <serge.ayoun@intel.com> --- Documentation/index.rst | 1 + Documentation/x86/intel_sgx.rst | 101 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 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..59049a35512f --- /dev/null +++ b/Documentation/x86/intel_sgx.rst @@ -0,0 +1,101 @@ +=================== +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. + +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 -- 2.14.1
next prev parent reply other threads:[~2017-12-16 16:27 UTC|newest] Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top 2017-12-16 16:19 [PATCH v9 0/7] Intel SGX Driver Jarkko Sakkinen 2017-12-16 16:19 ` Jarkko Sakkinen 2017-12-16 16:19 ` [PATCH v9 1/7] intel_sgx: updated MAINTAINERS Jarkko Sakkinen 2017-12-16 16:19 ` [PATCH v9 2/7] x86: add SGX definitions to cpufeature Jarkko Sakkinen 2017-12-16 16:19 ` [PATCH v9 3/7] x86: add SGX definitions to msr-index.h Jarkko Sakkinen 2017-12-16 16:19 ` [PATCH v9 4/7] intel_sgx: driver for Intel Software Guard Extensions Jarkko Sakkinen 2017-12-16 18:31 ` Philippe Ombredanne 2017-12-17 16:01 ` Jarkko Sakkinen 2017-12-16 16:19 ` [PATCH v9 5/7] intel_sgx: ptrace() support Jarkko Sakkinen 2017-12-16 16:19 ` Jarkko Sakkinen [this message] 2017-12-16 16:19 ` [PATCH v9 6/7] intel_sgx: driver documentation Jarkko Sakkinen 2017-12-16 16:19 ` [PATCH v9 7/7] intel_sgx: in-kernel launch enclave Jarkko Sakkinen 2017-12-19 13:59 ` Jarkko Sakkinen 2017-12-19 13:59 ` Jarkko Sakkinen 2017-12-19 15:36 ` Andy Shevchenko 2017-12-19 23:57 ` 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=20171216162200.20243-7-jarkko.sakkinen@linux.intel.com \ --to=jarkko.sakkinen@linux.intel.com \ --cc=corbet@lwn.net \ --cc=hpa@zytor.com \ --cc=intel-sgx-kernel-dev@lists.01.org \ --cc=linux-doc@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=mingo@redhat.com \ --cc=platform-driver-x86@vger.kernel.org \ --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: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.