OrgACRN
/
acrn-hypervisor
mirror of https://github.com/projectacrn/acrn-hypervisor.git
1
0
Fork 0
Code Issues Releases Wiki Activity

edits from David review 

Signed-off-by: Deb Taylor <deb.taylor@intel.com>
This commit is contained in:
Deb Taylor 2019-07-24 19:35:44 -04:00 committed by David Kinder
parent 7ee02d8eb0
commit cc2714eee9
1 changed files with 118 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

180
doc/tutorials/sgx_ virtualization.rst → doc/tutorials/sgx_virtualization.rst
View File

@ -1,8 +1,11 @@
SGX Virtualization .. _sgx_virt:
SGX Virtualization
################## ##################
SGX refers to Intel® Software Guard Extensions (Intel® SGX). This is a set of SGX refers to Intel® Software Guard Extensions (Intel® SGX). This is a set of
instructions that can be used by applications to set aside protected areas for select code and data in order to prevent direct attacks on executing code or instructions that can be used by applications to set aside protected areas for
select code and data in order to prevent direct attacks on executing code or
data stored in memory. SGX allows an application to instantiate a protected data stored in memory. SGX allows an application to instantiate a protected
container, referred to as an enclave, which is protected against external container, referred to as an enclave, which is protected against external
software access, including privileged malware. software access, including privileged malware.
@ -11,86 +14,97 @@ software access, including privileged malware.
High Level ACRN SGX Virtualization Design High Level ACRN SGX Virtualization Design
***************************************** *****************************************
ACRN SGX virtualization support can be divided into three parts: ACRN SGX virtualization support can be divided into three parts:
* SGX capability exposed to Guest EPC (Enclave Page Cache) management Enclave * SGX capability exposed to Guest EPC (Enclave Page Cache) management Enclave
* System function handing * System function handing
* Enclave System function handling
The image below shows the high-level design of SGX virtualization in ACRN. The image below shows the high-level design of SGX virtualization in ACRN.
.. figure:: images/sgx-1.png .. figure:: images/sgx-1.png
:width: 500px :width: 500px
:align: left :align: center
Figure 1: SGX Virtualization in ACRN SGX Virtualization in ACRN
Enable SGX support for Guest Enable SGX support for Guest
**************************** ****************************
Presumptions Presumptions
============ ============
No Enclave in a Hypervisor No Enclave in a Hypervisor
-------------------------- --------------------------
ACRN does not support running an enclave in a hypervisor since currently the ACRN does not support running an enclave in a hypervisor since the whole
whole hypervisor is running in vmx root mode, ring 0, and an enclave must run hypervisor is currently unning in VMX root mode, ring 0, and an enclave must
in ring 3. SGX virtualization in ACRN provides the SGX capability to (non-SOS) run in ring 3. SGX virtualization in ACRN provides the SGX capability to (non-
VMs. SOS) VMs.
Enable SGX on Host Enable SGX on Host
------------------ ------------------
In order to enable SGX virtualization support in ACRN, the SGX feature must be For SGX virtualization support in ACRN, you must manually enable the SGX
enabled and the Processor Reserved Memory (PRM) must be configured in the feature and configure the Processor Reserved Memory (PRM) in the platform
platform BIOS. Note that ACRN does not support the "Software Control" option; BIOS. (ACRN does not support the "Software Control" option to enable SGX at
SGX must be enabled manually in the BIOS. If the hardware platform does not run time.) If SGX is not enabled or the hardware platform does not support
support SGX or if SGX is not enabled in the BIOS, the SGX virtualization is SGX, ACRN SGX virtualization will not be enabled.
not enabled.
EPC Page Swapping in Guest EPC Page Swapping in Guest
-------------------------- --------------------------
ACRN only partitions the physical EPC resources for VMs. The Guest OS kernel ACRN only partitions the physical EPC resources for VMs. The Guest OS kernel
handles EPC Page Swapping inside Guest. handles EPC page swapping inside Guest.
Instructions Instructions
============ ============
By default, SGX support for Guest is not enabled on the Master branch. Thus, SGX support for a Guest OS is not enabled by default. Follow these steps to
you must perform the following: enable SGX support in the BIOS and in ACRN:
#. Make sure SGX is supported on the platform (CPUID.07H.EBX[2] should be 1). #. Check the system BIOS on your target platform to see if Intel SGX is
#. Opt-in to the SGX feature in the BIOS. Follow these instructions: supported (CPUID.07H.EBX[2] should be 1).
#. Enable the SGX feature in the BIOS setup screens. Follow these instructions:
a) Go to the Security page: a) Go to the Security page:
.. figure:: images/sgx-2.jpg .. figure:: images/sgx-2.jpg
:width: 500px :width: 500px
:align: left :align: center
#) Enable SGX and configure the SGX Reserved Memory size as below: #) Enable SGX and configure the SGX Reserved Memory size as below:
* Intel Software Guard Extension (SGX) -> Enabled * Intel Software Guard Extension (SGX) -> Enabled
* SGX Reserved Memory Size -> 128MB * SGX Reserved Memory Size -> 128MB
.. figure:: images/sgx-3.jpg .. figure:: images/sgx-3.jpg
:width: 500px :width: 500px
:align: left :align: center
.. note::
.. note::
Not all SGX Reserved Memory can be used as EPC. On KBL-NUC-i7, Not all SGX Reserved Memory can be used as EPC. On KBL-NUC-i7,
the SGX EPC size is 0x5d80000 (93.5MB) when the SGX Reserved Memory Size is set to 128MB. the SGX EPC size is 0x5d80000 (93.5MB) when the SGX Reserved Memory
Size is set to 128MB.
#. Add the EPC config in the VM configuration: #. Add the EPC config in the VM configuration:
Apply the patch to enable SGX support in UOS in the SDC scenario: Apply the patch to enable SGX support in UOS in the SDC scenario:
https://github.com/binbinwu1/acrn-hypervisor/commit/0153b2b9b9920b61780163f19c6f5318562215ef.patch
.. code-block:: bash
$ cd <projectacrn base folder>
$ curl https://github.com/binbinwu1/acrn-hypervisor/commit/
0153b2b9b9920b61780163f19c6f5318562215ef.patch | git apply
#. Enable SGX in Guest: #. Enable SGX in Guest:
* Refer to https://github.com/intel/linux-sgx on how to enable SGX in Linux Guest. * Refer to https://github.com/intel/linux-sgx on how to enable SGX in Linux
* Refer to https://software.intel.com/en-us/articles/getting-started-with-sgx-sdk-for-windows on how to enable SGX in Windows Guest. Guest.
* Refer to https://software.intel.com/en-us/articles/
getting-started-with-sgx-sdk-for-windows on how to enable SGX in Windows
Guest.
SGX Capability Exposure SGX Capability Exposure
*********************** ***********************
@ -101,29 +115,41 @@ CPUID Virtualization
CPUID Leaf 07H CPUID Leaf 07H
-------------- --------------
* CPUID_07H.EAX[2] SGX: Supports Intel Software Guard Extensions if 1. If SGX is supported in Guest, this bit will be set. * CPUID_07H.EAX[2] SGX: Supports Intel Software Guard Extensions if 1. If SGX
* CPUID_07H.ECX[30] SGX_LC: Supports SGX Launch Configuration if 1. Currently, ACRN does not support the SGX Launch Configuration. This bit will not be set. Thus, the Launch Enclave must be signed by the Intel SGX Launch Enclave Key. is supported in Guest, this bit will be set.
* CPUID_07H.ECX[30] SGX_LC: Supports SGX Launch Configuration if 1. Currently,
ACRN does not support the SGX Launch Configuration. This bit will not be
set. Thus, the Launch Enclave must be signed by the Intel SGX Launch Enclave
Key.
CPUID Leaf 12H CPUID Leaf 12H
-------------- --------------
**Intel SGX Capability Enumeration** **Intel SGX Capability Enumeration**
* CPUID_12H.0.EAX[0] SGX1: If 1, indicates that Intel SGX supports the collection of SGX1 leaf functions.If is_sgx_supported and the section count is initialized for the VM, this bit will be set. * CPUID_12H.0.EAX[0] SGX1: If 1, indicates that Intel SGX supports the
* CPUID_12H.0.EAX[1] SGX2: If 1, indicates that Intel SGX supports the collection of SGX2 leaf functions. If hardware supports it and SGX enabled for the VM, this bit will be set. collection of SGX1 leaf functions.If is_sgx_supported and the section count
is initialized for the VM, this bit will be set.
* CPUID_12H.0.EAX[1] SGX2: If 1, indicates that Intel SGX supports the
collection of SGX2 leaf functions. If hardware supports it and SGX enabled
for the VM, this bit will be set.
* Other fields of CPUID_12H.0.EAX aligns with the physical CPUID. * Other fields of CPUID_12H.0.EAX aligns with the physical CPUID.
**Intel SGX Attributes Enumeration** **Intel SGX Attributes Enumeration**
* CPUID_12H.1.EAX & CPUID_12H.1.EBX aligns with the physical CPUID. * CPUID_12H.1.EAX & CPUID_12H.1.EBX aligns with the physical CPUID.
* CPUID_12H.1.ECX & CPUID_12H.1.EDX reflects the allow-1 setting in the Extended feature (same structure as XCR0). * CPUID_12H.1.ECX & CPUID_12H.1.EDX reflects the allow-1 setting in the
Extended feature (same structure as XCR0).
The hypervisor may change the allow-1 setting of XFRM in ATTRIBUTES for VM. The hypervisor may change the allow-1 setting of XFRM in ATTRIBUTES for VM.
If some feature is disabled for the VM, the bit is also cleared, eg. MPX. If some feature is disabled for the VM, the bit is also cleared, eg. MPX.
**Intel SGX EPC Enumeration** **Intel SGX EPC Enumeration**
* CPUID_12H.2: The hypervisor presents only one EPC section to Guest. This vcpuid value will be constructed according to the EPC resource allocated to Guest. * CPUID_12H.2: The hypervisor presents only one EPC section to Guest. This
vcpuid value will be constructed according to the EPC resource allocated to
Guest.
MSR Virtualization MSR Virtualization
================== ==================
@ -151,30 +177,51 @@ SGXOWNEREPOCH[0-1]
EPC Virtualization EPC Virtualization
================== ==================
* EPC resource is statically partitioned according to the configuration of the EPC size of VMs. * EPC resource is statically partitioned according to the configuration of the
* During platform initialization, the physical EPC section information is collected via CPUID. SGX initialization function allocates EPC resource to VMs according to the EPC config in VM configurations. EPC size of VMs.
* If enough EPC resource is allocated for the VM, assign the GPA of the EPC section. * During platform initialization, the physical EPC section information is
* EPC resource is allocated to the Non-SOS VM; the EPC base GPA is specified by the EPC config in the VM configuration. collected via CPUID. SGX initialization function allocates EPC resource to
VMs according to the EPC config in VM configurations.
* If enough EPC resource is allocated for the VM, assign the GPA of the EPC
section.
* EPC resource is allocated to the Non-SOS VM; the EPC base GPA is specified
by the EPC config in the VM configuration.
* The corresponding range of memory space should be marked as reserved in E820. * The corresponding range of memory space should be marked as reserved in E820.
* During initialization, the mapping relationship of EPC HPA and GPA is saved for building the EPT table later when the VM is created. * During initialization, the mapping relationship of EPC HPA and GPA is saved
for building the EPT table later when the VM is created.
Enclave System Function Handling Enclave System Function Handling
******************************** ********************************
A new "Enable ENCLS exiting" control bit (bit 15) is defined in the secondary processor-based VM execution control. A new "Enable ENCLS exiting" control bit (bit 15) is defined in the secondary
processor-based VM execution control.
* 1-Setting of "Enable ENCLS exiting" enables ENCLS-exiting bitmap control, which is a new 64-bit ENCLS-exiting bitmap control field added to VMX VMCS (0202EH) to control VMEXIT on ENCLS leaf functions. * 1-Setting of "Enable ENCLS exiting" enables ENCLS-exiting bitmap control,
which is a new 64-bit ENCLS-exiting bitmap control field added to VMX VMCS (
0202EH) to control VMEXIT on ENCLS leaf functions.
* ACRN does not emulate ENCLS leaf functions and will not enable ENCLS exiting. * ACRN does not emulate ENCLS leaf functions and will not enable ENCLS exiting.
ENCLS[ECREATE] ENCLS[ECREATE]
============== ==============
* The enclave execution environment is heavily influenced by the value of ATTRIBUTES in the enclave's SECS. * The enclave execution environment is heavily influenced by the value of
* When ECREATE is executed, the processor will check and verify that the enclave requirements are supported on the platform. If not, ECREATE will generate a #GP. ATTRIBUTES in the enclave's SECS.
* The hypervisor can present the same extended features to Guest as the hardware. However, if the hypervisor hides some extended features that the hardware supports from the VM/guest, then if the hypervisor does not trap ENCLS[ECREATE], ECREATE may succeed even if the ATTRIBUTES the enclave requested is not supported in the VM. * When ECREATE is executed, the processor will check and verify that the
* Fortunately, ENCLU[EENTER] will fault if SECS.ATTRIBUTES.XFRM is not a subset of XCR0 when CR4.OSXSAVE = 1. enclave requirements are supported on the platform. If not, ECREATE will
* XCR0 is controlled by the hypervisor in ACRN; if the hypervisor hides some extended feature from the VM/guest, then ENCLU[EENTER] will fault if the enclave requests a feature that the VM does not support if the hypervisor does not trap/emulate ENCLS[ECREATE]. generate a #GP.
* Above all, the security feature is not compromised if the hypervisor does not trap ENCLS[ECREATE] to check the attributes of the enclave. * The hypervisor can present the same extended features to Guest as the
hardware. However, if the hypervisor hides some extended features that the
hardware supports from the VM/guest, then if the hypervisor does not trap
ENCLS[ECREATE], ECREATE may succeed even if the ATTRIBUTES the enclave
requested is not supported in the VM.
* Fortunately, ENCLU[EENTER] will fault if SECS.ATTRIBUTES.XFRM is not a
subset of XCR0 when CR4.OSXSAVE = 1.
* XCR0 is controlled by the hypervisor in ACRN; if the hypervisor hides some
extended feature from the VM/guest, then ENCLU[EENTER] will fault if the
enclave requests a feature that the VM does not support if the hypervisor
does not trap/emulate ENCLS[ECREATE].
* Above all, the security feature is not compromised if the hypervisor does
not trap ENCLS[ECREATE] to check the attributes of the enclave.
Other VMExit Control Other VMExit Control
******************** ********************
@ -182,7 +229,8 @@ Other VMExit Control
RDRAND exiting RDRAND exiting
============== ==============
* ACRN allows Guest to use RDRAND/RDSEED instruction but does not set "RDRAND exiting" to 1. * ACRN allows Guest to use RDRAND/RDSEED instruction but does not set "RDRAND
exiting" to 1.
PAUSE exiting PAUSE exiting
============= =============
@ -199,15 +247,23 @@ When the following two conditions are both satisfied:
* The hardware platform supports the SGX Launch Configuration. * The hardware platform supports the SGX Launch Configuration.
* The platform BIOS must enable the feature in Unlocked mode, so that the ring0 software can configure the Model Specific Register (MSR) IA32_SGXLEPUBKEYHASH[0-3] values. * The platform BIOS must enable the feature in Unlocked mode, so that the
ring0 software can configure the Model Specific Register (MSR)
IA32_SGXLEPUBKEYHASH[0-3] values.
the following statements apply: the following statements apply:
* If CPU sharing is supported, ACRN can emulate MSR IA32_SGXLEPUBKEYHASH[0-3] for VM. ACRN updates MSR IA32_SGXLEPUBKEYHASH[0-3] when the VM context switch happens. * If CPU sharing is supported, ACRN can emulate MSR IA32_SGXLEPUBKEYHASH[0-3]
* If CPU sharing is not supported, ACRN can support SGX LC by passthrough MSR IA32_SGXLEPUBKEYHASH[0-3] to Guest. for VM. ACRN updates MSR IA32_SGXLEPUBKEYHASH[0-3] when the VM context
switch happens.
* If CPU sharing is not supported, ACRN can support SGX LC by passthrough MSR
IA32_SGXLEPUBKEYHASH[0-3] to Guest.
ACPI Virtualization ACPI Virtualization
=================== ===================
* The Intel SGX EPC ACPI device is provided in the ACPI Differentiated System Descriptor Table (DSDT), which contains the details of the Intel SGX existence on the platform as well as memory size and location. * The Intel SGX EPC ACPI device is provided in the ACPI Differentiated System
* Although the EPC can be discovered by the CPUID, several versions of Windows do rely on the ACPI tables to enumerate the address and size of the EPC. Descriptor Table (DSDT), which contains the details of the Intel SGX
existence on the platform as well as memory size and location.
* Although the EPC can be discovered by the CPUID, several versions of Windows
do rely on the ACPI tables to enumerate the address and size of the EPC.