Thank you for adding much needed documentation throughout the tree! On 6/10/2024 1:28 PM, mhkelley58@xxxxxxxxx wrote: > From: Michael Kelley <mhklinux@xxxxxxxxxxx> > > Add documentation topic for Confidential Computing (CoCo) VM support > in Linux guests on Hyper-V. > > Signed-off-by: Michael Kelley <mhklinux@xxxxxxxxxxx> > --- > Documentation/virt/hyperv/coco.rst | 258 ++++++++++++++++++++++++++++ > Documentation/virt/hyperv/index.rst | 1 + > 2 files changed, 259 insertions(+) > create mode 100644 Documentation/virt/hyperv/coco.rst > > diff --git a/Documentation/virt/hyperv/coco.rst b/Documentation/virt/hyperv/coco.rst > new file mode 100644 > index 000000000000..ffd6ba7a1d64 > --- /dev/null > +++ b/Documentation/virt/hyperv/coco.rst > @@ -0,0 +1,258 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Confidential Computing VMs > +========================== > +Hyper-V can create and run Linux guests that are Confidential Computing > +(CoCo) VMs. Such VMs cooperate with the physical processor to better protect > +the confidentiality and integrity of data in the VM's memory, even in the > +face of a hypervisor/VMM that has been compromised and may behave maliciously. > +CoCo VMs on Hyper-V share the generic CoCo VM threat model and security > +objectives described in Documentation/security/snp-tdx-threat-model.rst. Note > +that Hyper-V specific code in Linux refers to CoCo VMs as "isolated VMs" or > +"isolation VMs". Thanks for incorporating the link to the threat model! > + > +A Linux CoCo VM on Hyper-V requires the cooperation and interaction of the > +following: > + > +* Physical hardware with a processor that supports CoCo VMs > + > +* The hardware runs a version of Windows/Hyper-V with support for CoCo VMs > + > +* The VM runs a version of Linux that supports being a CoCo VM > + > +The physical hardware requirements are as follows: > + > +* AMD processor with SEV-SNP. Hyper-V does not run guest VMs with AMD SME, > + SEV, or SEV-ES encryption, and such encryption is not sufficient for a CoCo > + VM on Hyper-V. > + > +* Intel processor with TDX > + > +To create a CoCo VM, the "Isolated VM" attribute must be specified to Hyper-V > +when the VM is created. A VM cannot be changed from a CoCo VM to a normal VM, > +or vice versa, after it is created. > + > +Operational Modes > +----------------- > +Hyper-V CoCo VMs can run in two modes. The mode is selected when the VM is > +created and cannot be changed during the life of the VM. > + > +* Fully-enlightened mode. In this mode, the guest operating system is > + enlightened to understand and manage all aspects of running as a CoCo VM. > + > +* Paravisor mode. In this mode, a paravisor layer between the guest and the > + host provides some operations needed to run as a CoCo VM. The guest operating > + system can have fewer CoCo enlightenments than is required in the > + fully-enlightened case. > + > +Conceptually, fully-enlightened mode and paravisor mode may be treated as > +points on a spectrum spanning the degree of guest enlightenment needed to run > +as a CoCo VM. Fully-enlightened mode is one end of the spectrum. A full > +implementation of paravisor mode is the other end of the spectrum, where all > +aspects of running as a CoCo VM are handled by the paravisor, and a normal > +guest OS with no knowledge of memory encryption or other aspects of CoCo VMs > +can run successfully. However, the Hyper-V implementation of paravisor mode > +does not go this far, and is somewhere in the middle of the spectrum. Some > +aspects of CoCo VMs are handled by the Hyper-V paravisor while the guest OS > +must be enlightened for other aspects. Unfortunately, there is no > +standardized enumeration of feature/functions that might be provided in the > +paravisor, and there is no standardized mechanism for a guest OS to query the > +paravisor for the feature/functions it provides. The understanding of what > +the paravisor provides is hard-coded in the guest OS. > + > +Paravisor mode has similarities to the Coconut project, which aims to provide > +a limited paravisor to provide services to the guest such as a virtual TPM. Would it be useful to add an external link to the Coconut project here? https://github.com/coconut-svsm/svsm > +However, the Hyper-V paravisor generally handles more aspects of CoCo VMs > +than is currently envisioned for Coconut, and so is further toward the "no > +guest enlightenments required" end of the spectrum. > + > +In the CoCo VM threat model, the paravisor is in the guest security domain > +and must be trusted by the guest OS. By implication, the hypervisor/VMM must > +protect itself against a potentially malicious paravisor just like it > +protects against a potentially malicious guest. Tangential to this patch, can the guest provide its own paravisor since it needs to be trusted and apparently the only way to find out if a paravisor will be used is to rely on the (possibly) malicious hypervisor/VMM to provide a synthetic MSR? > + > +The hardware architectural approach to fully-enlightened vs. paravisor mode > +varies depending on the underlying processor. > + > +* With AMD SEV-SNP processors, in fully-enlightened mode the guest OS runs in > + VMPL 0 and has full control of the guest context. In paravisor mode, the > + guest OS runs in VMPL 2 and the paravisor runs in VMPL 0. The paravisor > + running in VMPL 0 has privileges that the guest OS in VMPL 2 does not have. > + Certain operations require the guest to invoke the paravisor. Furthermore, in > + paravisor mode the guest OS operates in "virtual Top Of Memory" (vTOM) mode > + as defined by the SEV-SNP architecture. This mode simplifies guest management > + of memory encryption when a paravisor is used. > + > +* With Intel TDX processor, in fully-enlightened mode the guest OS runs in an > + L1 VM. In paravisor mode, TD partitioning is used. The paravisor runs in the > + L1 VM, and the guest OS runs in a nested L2 VM. > + > +Hyper-V exposes a synthetic MSR to guests that describes the CoCo mode. This > +MSR indicates if the underlying processor uses AMD SEV-SNP or Intel TDX, and > +whether a paravisor is being used. It is straightforward to build a single > +kernel image that can boot and run properly on either architecture, and in > +either mode. > +
