[RFC PATCH 11/11] Documentation/x86/sgx: Document EUPDATESVN sysfs file

[Cathy Zhang <cathy.zhang@intel.com>]

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@intel.com>
---
 .../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@vger.kernel.org
+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