Hi--
On 6/3/25 5:43 PM, Roman Kisel wrote:
> Define what the confidential VMBus is and describe what advantages
> it offers on the capable hardware.
>
> Signed-off-by: Roman Kisel <rom...@linux.microsoft.com>
> Reviewed-by: Alok Tiwari <alok.a.tiw...@oracle.com>
> ---
> Documentation/virt/hyperv/coco.rst | 125 ++++++++++++++++++++++++++++-
> 1 file changed, 124 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/virt/hyperv/coco.rst
> b/Documentation/virt/hyperv/coco.rst
> index c15d6fe34b4e..b4904b64219d 100644
> --- a/Documentation/virt/hyperv/coco.rst
> +++ b/Documentation/virt/hyperv/coco.rst
> @@ -178,7 +178,7 @@ These Hyper-V and VMBus memory pages are marked as
> decrypted:
>
> * VMBus monitor pages
>
> -* Synthetic interrupt controller (synic) related pages (unless supplied by
> +* Synthetic interrupt controller (SynIC) related pages (unless supplied by
> the paravisor)
>
> * Per-cpu hypercall input and output pages (unless running with a paravisor)
> @@ -258,3 +258,126 @@ normal page fault is generated instead of #VC or #VE,
> and the page-fault-
> based handlers for load_unaligned_zeropad() fixup the reference. When the
> encrypted/decrypted transition is complete, the pages are marked as "present"
> again. See hv_vtom_clear_present() and hv_vtom_set_host_visibility().
> +
> +Confidential VMBus
> +------------------
> +
> +The confidential VMBus enables the confidential guest not to interact with
> the
> +untrusted host partition and the untrusted hypervisor. Instead, the guest
> relies
> +on the trusted paravisor to communicate with the devices processing sensitive
> +data. The hardware (SNP or TDX) encrypts the guest memory and the register
> state
> +while measuring the paravisor image using the platform security processor to
> +ensure trusted and confidential computing.
> +
> +Confidential VMBus provides a secure communication channel between the guest
> and
> +the paravisor, ensuring that sensitive data is protected from
> hypervisor-level
^^
s/ / /
> +access through memory encryption and register state isolation.
> +
> +The unencrypted data never leaves the VM so neither the host partition nor
> the
> +hypervisor can access it at all. In addition to that, the guest only needs to
> +establish a VMBus connection with the paravisor for the channels that process
> +sensitive data, and the paravisor abstracts the details of communicating with
> +the specific devices away.
> +
> +Confidential VMBus is an extension of Confidential Computing (CoCo) VMs
> +(a.k.a. "Isolated" VMs in Hyper-V terminology). Without Confidential VMBus,
> +guest VMBus device drivers (the "VSC"s in VMBus terminology) communicate
> +with VMBus servers (the VSPs) running on the Hyper-V host. The
> +communication must be through memory that has been decrypted so the
> +host can access it. With Confidential VMBus, one or more of the VSPs reside
> +in the trusted paravisor layer in the guest VM. Since the paravisor layer
> also
> +operates in encrypted memory, the memory used for communication with
> +such VSPs does not need to be decrypted and thereby exposed to the
> +Hyper-V host. The paravisor is responsible for communicating securely
> +with the Hyper-V host as necessary. In some cases (e.g. time synchonization,
> +key-value pairs exchange) the unencrypted data doesn't need to be
> communicated
> +with the host at all, and a conventional VMBus connection suffices.
> +
> +Here is the data flow for a conventional VMBus connection and the
> Confidential
> +VMBus connection (C stands for the client or VSC, S for the server or VSP):
> +
> ++---- GUEST ----+ +----- DEVICE ----+ +----- HOST -----+
> +| | | | | |
> +| | | | | |
> +| | | ========== |
> +| | | | | |
> +| | | | | |
> +| | | | | |
> ++----- C -------+ +-----------------+ +------- S ------+
> + || ||
> + || ||
> ++------||------------------ VMBus --------------------------||------+
> +| Interrupts, MMIO |
> ++-------------------------------------------------------------------+
> +
> ++---- GUEST --------------- VTL0 ------+ +-- DEVICE --+
> +| | | |
> +| +- PARAVISOR --------- VTL2 -----+ | | |
> +| | +-- VMBus Relay ------+ ====+================ |
> +| | | Interrupts, MMIO | | | | |
> +| | +-------- S ----------+ | | +------------+
> +| | || | |
> +| +---------+ || | |
> +| | Linux | || OpenHCL | |
> +| | kernel | || | |
> +| +---- C --+-----||---------------+ |
> +| || || |
> ++-------++------- C -------------------+ +------------+
> + || | HOST |
> + || +---- S -----+
> ++-------||----------------- VMBus ---------------------------||-----+
> +| Interrupts, MMIO |
> ++-------------------------------------------------------------------+
> +
> +An implementation of the VMBus relay that offers the Confidential VMBus
> channels
> +is available in the OpenVMM project as a part of the OpenHCL paravisor.
> Please
> +refer to https://openvmm.dev/ and https://github.com/microsoft/openvmm for
> more
> +information about the OpenHCL paravisor.
> +
> +A guest that is running with a paravisor must determine at runtime if
> +Confidential VMBus is supported by the current paravisor. It does so by first
> +trying to establish a Confidential VMBus connection with the paravisor using
> +standard mechanisms where the memory remains encrypted. If this succeeds,
> +then the guest can proceed to use Confidential VMBus. If it fails, then the
> +guest must fallback to establishing a non-Confidential VMBus connection with
> +the Hyper-V host.
> +
> +Confidential VMBus is a characteristic of the VMBus connection as a whole,
> +and of each VMBus channel that is created. When a Confidential VMBus
> +connection is established, the paravisor provides the guest the
> message-passing
> +path that is used for VMBus device creation and deletion, and it provides a
> +per-CPU synthetic interrupt controller (SynIC) just like the SynIC that is
> +offered by the Hyper-V host. Each VMBus device that is offered to the guest
> +indicates the degree to which it participates in Confidential VMBus. The
> offer
> +indicates if the device uses encrypted ring buffers, and if the device uses
> +encrypted memory for DMA that is done outside the ring buffer. These settings
> +may be different for different devices using the same Confidential VMBus
> +connection.
Various lines throughout:
Please try to keep line lengths to <= 80 characters foe people who read
documentation in a terminal window.
> +Although these settings are separate, in practice it'll always be encrypted
> +ring buffer only or both encrypted ring buffer and external data. If a
> channel
> +is offered by the paravisor with confidential VMBus, the ring buffer can
> always
> +be encrypted since it's strictly for communication between the VTL2 paravisor
> +and the VTL0 guest. However, other memory regions are often used for e.g.
> DMA,
> +so they need to be accessible by the underlying hardware, and must be
> unencrypted
> +(unless the device supports encrypted memory). Currently, there are no any
> VSPs
not
> +in OpenHCL that support encrypted external memory, but we will use it in the
> +future.
> +
> +Because some devices on a Confidential VMBus may require decrypted ring
> buffers
> +and DMA transfers, the guest must interact with two SynICs -- the one
> provided
> +by the paravisor and the one provided by the Hyper-V host when Confidential
> +VMBus is not offered. Interrupts are always signaled by the paravisor SynIC,
> but
> +the guest must check for messages and for channel interrupts on both SynICs.
> +
> +In the case of a confidential VM, regular SynIC access by the guest is
> +intercepted by the paravisor (this includes various MSRs such as the SIMP and
> +SIEFP, as well as hypercalls like HvPostMessage and HvSignalEvent). If the
> guest
> +actually wants to communicate with the hypervisor, it has to use special
> mechanisms
> +(GHCB page on SNP, or tdcall on TDX). Messages will always be one or the
> other:
> +with confidential VMBus, all messages use the paravisor SynIC, otherwise
> they all
> +use the hypervisor SynIC. For interrupt signaling, though, some channels may
> be
> +running on the host (non-confidential, using the VMBus relay) and use the
> hypervisor
> +SynIC, and some on the paravisor and use its SynIC. The RelIDs are
> coordinated by
> +the OpenHCL VMBus server and are guaranteed to be unique regardless of
> whether
> +the channel originated on the host or the paravisor.
--
~Randy
