A new sysfs file /sys/devices/system/cpu/microcode/svnupdate is
provided, it allows system admin to echo 1 to trigger the CPUSVN
update process.
Document the new sysfs ABI.
Signed-off-by: Cathy Zhang <cathy.zhang@xxxxxxxxx>
---
.../ABI/testing/sysfs-devices-system-cpu | 14 ++++++
Documentation/x86/sgx.rst | 43 +++++++++++++++++++
2 files changed, 57 insertions(+)
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 74962c200790..785709c53325 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -687,3 +687,17 @@ Description:
(RO) the list of CPUs that are isolated and don't
participate in load balancing. These CPUs are set by
boot parameter "isolcpus=".
+
+What: /sys/devices/system/cpu/microcode/svnupdate
+Date: Feb 2022
+Contact: linux-sgx@xxxxxxxxxxxxxxx
+Description: Applying SGX Runtime Microcode Updates to Enclaves
+
+ Whenever a microcode update affects SGX, ENCLS[EUPDATESVN]
+ should be taken to update the attestation metric (called
+ CPUSVN) and generate new cryptographic assets without a
+ reboot. EUPDATESVN success requires that all SGX memory
+ be marked as "unused" and its contents destroyed.
+
+ This sysfs interface is only exposed to userspace on host,
+ to trigger enclave destruction and the EUPDATESVN operation.
diff --git a/Documentation/x86/sgx.rst b/Documentation/x86/sgx.rst
index 4059efbb4d2e..68f82a3683d6 100644
--- a/Documentation/x86/sgx.rst
+++ b/Documentation/x86/sgx.rst
@@ -339,3 +339,46 @@ to expected failures and handle them as follows:
first call. It indicates a bug in the kernel or the userspace client
if any of the second round of ``SGX_IOC_VEPC_REMOVE_ALL`` calls has
a return code other than 0.
+
+
+Applying Runtime Microcode Updates to Enclaves
+==============================================
+
+SGX enclaves have an attestation mechanism. An enclave might, for
+instance, need to attest to its state before it is given a special
+decryption key. Since SGX must trust the CPU microcode, attestation
+incorporates the microcode versions of all processors on the system
+and is affected by microcode updates. This enables deployment
+decisions based on the microcode version. For example, an enclave
+might be denied a decryption key if it runs on a system that has
+old microcode without a specific mitigation.
+
+Unfortunately, this attestation metric (called CPUSVN) is only a
+snapshot. When the kernel first uses SGX (successfully executes any
+ENCLS instruction), SGX inspects all CPUs in the system and incorporates
+a record of their microcode versions into CPUSVN. CPUSVN is only
+automatically updated at reboot. This means that, although the
+microcode has been updated, enclaves can never attest to this fact.
+Enclaves are stuck attesting to the old version until a reboot.
+
+The SGX architecture has an alternative to these reboots: the
+ENCLS[EUPDATESVN] instruction. It allows another snapshot to be
+taken to update CPUSVN after a runtime microcode update without a
+reboot.
+
+Whenever a microcode update affects SGX, the SGX attestation
+architecture assumes that all running enclaves and cryptographic
+assets (like internal SGX encryption keys) have been compromised.
+To mitigate the impact of this presumed compromise, ENCLS[EUPDATESVN]
+success requires that all SGX memory be marked as "unused" and
+its contents destroyed. This requirement ensures that no compromised
+enclaves can survive the procedure to run ENCLS[EUPDATESVN] and
+provides an opportunity to generate new cryptographic assets.
+
+The procedure to run ENCLS[EUPDATESVN] was designed to be separate
+from the microcode update to provide flexibility to administrators.
+They can immediately update the microcode and then schedule enclave
+destruction and run ENCLS[EUPDATESVN] for a later more convenient time.
+
+Write 1 to the sysfs file: **/sys/devices/system/cpu/microcode/svnupdate**
+triggers enclave destruction and the EUPDATESVN operation.
--
2.17.1
