[PATCH docs/manager v2 0/3] ui: docs: add reference to vm options protection/IDX/SEV

[PATCH docs/manager v2 0/3] ui: docs: add reference to vm options protection/IDX/SEV

[Elias Huhsovitz]

This series addresses bug #6211 by improving the documentation and UI
help links for 2 VM options regarding memory security. Specifically, 
it corrects the documentation links for AMD SEV and Intel TDX and
creates a doc entry for Intel TDX.

Because the UI changes require corresponding documentation updates,
this series is split across two repositories:

pve-docs:
- Adds a new documentation section for Intel TDX.
- Fixes dead links in the existing AMD SEV documentation section.

pve-manager:
- Updates the AMD SEV and Intel TDX dialogs to point to the correct
  memory encryption documentation anchors.

This requires first applying patch 2/3 to pve-docs and bumping it, so
pve-manager can pick up the new documentation chapter when being built.

changes v1->v2:
- Remove changes for ambiguous protection field in GUI
  and submit them as a separate patch
- fix typos in TDX documentation
- fix docs for "qm set <vmid>" command in tdx section.
- fix commit message subject (was previously cut off)


pve-docs:

Elias Huhsovitz (2):
  qm_memory: update dead links in qm_memory_encryption_sev section on
    AMD SEV
  qm_memory: expand qm_memory_encryption documentation to include Intel
    TDX

 qm.adoc | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 164 insertions(+), 4 deletions(-)


pve-manager:

Elias Huhsovitz (1):
  fix #6211: ui: vm: options: update amd-sev and intel-tdx help links

 www/manager6/qemu/SevEdit.js | 2 +-
 www/manager6/qemu/TdxEdit.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)


Summary over all repositories:
  3 files changed, 166 insertions(+), 6 deletions(-)

-- 
Generated by murpp 0.12.0

[PATCH docs v2 1/3] qm_memory: update dead links in qm_memory_encryption_sev section on AMD SEV

[Elias Huhsovitz]

The section on AMD SEV included dead links.
Replace dead links with up-to-date working links.

Signed-off-by: Elias Huhsovitz <e.huhsovitz@proxmox.com>
---
 qm.adoc | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/qm.adoc b/qm.adoc
index 96ba68b..8213758 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -922,10 +922,9 @@ Links:
 * https://developer.amd.com/sev/
 * https://github.com/AMDESE/AMDSEV
 * https://www.qemu.org/docs/master/system/i386/amd-memory-encryption.html
-* https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf
-* https://documentation.suse.com/sles/15-SP1/html/SLES-amd-sev/index.html
-* https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56860.pdf[
-SEV Secure Nested Paging Firmware ABI Specification]
+* https://docs.amd.com/v/u/en-US/55766_PUB_3.24_SEV_API
+* https://documentation.suse.com/sles/15-SP7/single-html/SLES-amd-sev/article-amd-sev.html
+* https://www.amd.com/content/dam/amd/en/documents/developer/56860.pdf[SEV Secure Nested Paging Firmware ABI Specification]
 
 [[qm_network_device]]
 Network Device
-- 
2.47.3

[PATCH docs v2 2/3] qm_memory: expand qm_memory_encryption documentation to include Intel TDX

[Elias Huhsovitz]

The pve-manager provides a help-button in the Intel TDX edit window, but
there was no documentation regarding this.

Now includes basic information about Intel Trust Domain Extensions
(TDX).

Signed-off-by: Elias Huhsovitz <e.huhsovitz@proxmox.com>
---
 qm.adoc | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)

diff --git a/qm.adoc b/qm.adoc
index 8213758..0e5c4d2 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -926,6 +926,167 @@ Links:
 * https://documentation.suse.com/sles/15-SP7/single-html/SLES-amd-sev/article-amd-sev.html
 * https://www.amd.com/content/dam/amd/en/documents/developer/56860.pdf[SEV Secure Nested Paging Firmware ABI Specification]
 
+[[qm_memory_encryption_tdx]]
+Intel TDX
+^^^^^^^^^
+
+Intel Trust Domain Extensions (TDX) protect guest VM memory and CPU state
+from the host hypervisor. TDX uses Intel Multi-Key Total Memory Encryption
+(MKTME) to provide per-VM memory encryption and introduces a CPU-isolated
+module that manages the creation and execution of protected VMs (called Trust
+Domains, or TDs).
+
+*Host Requirements*
+
+* 4th Generation Intel Xeon Scalable processor (Codename: Sapphire Rapids)
+  or newer. TDX is a hardware feature introduced with Sapphire Rapids and is
+  not available on earlier Xeon generations.
+  See https://www.intel.com/content/www/us/en/support/articles/000091103/processors/intel-xeon-processors.html[Intel — Xeon processors with TDX support].
+* Enable TDX in the BIOS/UEFI settings. The kernel assumes the TDX module
+  is loaded by the BIOS at boot.
+  See https://docs.kernel.org/arch/x86/tdx.html#tdx-host-kernel-support[TDX host kernel support].
+* A host kernel with TDX support. The kernel detects TDX via TDX
+  private KeyIDs configured by the BIOS during https://docs.kernel.org/arch/x86/tdx.html#tdx-boot-time-detection[early boot].
+
+*Notes*
+
+* Add `nohibernate` to the kernel command line if hibernation support is
+  compiled in. TDX cannot survive S3 (suspend-to-RAM) or S4 (hibernation)
+  power states — the hardware resets and disables TDX completely when the
+  platform enters these states.
+  See https://docs.kernel.org/arch/x86/tdx.html#interaction-vs-s3-and-deeper-states[Interaction vs S3 and deeper states].
+* TDX module initialization
+  https://docs.kernel.org/arch/x86/tdx.html#tdx-module-initialization[consumes approximately 1/256th of system RAM] for
+  the Physical Address Metadata Table (PAMT).
+* The TDX module is initialized https://docs.kernel.org/arch/x86/tdx.html#tdx-module-initialization[on demand] (when the first TDX guest is
+  created), not at boot time.
+
+*Verify Intel TDX is Enabled on Host*
+
+To https://docs.kernel.org/arch/x86/tdx.html#tdx-boot-time-detection[check if TDX is enabled on the host], search for `tdx` in `dmesg`.
+If the BIOS has enabled TDX and the TDX module was successfully initialized,
+the output should look like this:
+
+----
+# dmesg | grep -i tdx
+[...] virt/tdx: BIOS enabled: private KeyID range [64, 128)
+[...] virt/tdx: 1050644 KB allocated for PAMT
+[...] virt/tdx: module initialized
+----
+
+If the TDX module is not loaded by the BIOS, dmesg will show:
+
+----
+[...] virt/tdx: module not loaded
+----
+
+If TDX initialization fails because hibernation is enabled in the kernel:
+
+----
+[...] virt/tdx: initialization failed: Hibernation support is enabled
+----
+
+The current TDX module version can be https://docs.kernel.org/arch/x86/tdx.html#how-to-update-the-tdx-module[checked at runtime]:
+
+----
+# cat /sys/devices/faux/tdx_host/version
+----
++
+(If this path does not exist, the TDX module has not been initialized yet.)
+
+*Guest Requirements*
+
+* https://www.qemu.org/docs/master/system/i386/tdx.html#trust-domain-virtual-firmware-tdvf[Trust Domain Virtual Firmware (TDVF)].
+  TDVF is a TDX-enabled build of OVMF
+  that provides TD services to boot the guest OS. Standard OVMF without TDX
+  support cannot be used. TDVF is loaded via the `-bios` option because TDX
+  does not support readonly memslots, so TDVF cannot be mapped as a pflash
+  device.
+* The guest operating system must contain https://docs.kernel.org/arch/x86/tdx.html#tdx-guest-support[TDX guest support].
+  For Linux, this
+  means a kernel with TDX guest support enabled, which sets up a #VE
+  (Virtualization Exception) handler and shared-memory infrastructure at
+  boot.
+* The `kernel-irqchip` must be set to `split`. QEMU sets this
+  https://www.qemu.org/docs/master/system/i386/tdx.html#restrictions[automatically]
+  when launching a TDX guest if the setting is left on its default `auto`
+  value.
+* * The *q35* machine model is recommended.
+
+*Limitations*
+
+* Windows guests are not supported.
+  See https://pve.proxmox.com/wiki/Roadmap[Proxmox VE Roadmap].
+* Live migration is currently unsupported.
+  See https://www.qemu.org/docs/master/system/i386/tdx.html#live-migration[QEMU — Live Migration] and https://pve.proxmox.com/wiki/Roadmap[PVE Roadmap].
+* PCI passthrough to TDX guests is limited. Device MMIO regions and DMA
+  buffers are mapped as shared memory, which means the hypervisor controls
+  their content. Shared memory must never be used for sensitive data.
+  See https://docs.kernel.org/arch/x86/tdx.html#ve-on-memory-accesses[#VE on Memory Accesses],
+  https://docs.kernel.org/arch/x86/tdx.html#shared-memory-conversions[Shared Memory Conversions],
+  https://intel.github.io/ccc-linux-guest-hardening-docs/security-spec.html[Intel TDX Guest Kernel Security Specification].
+* S3 (suspend-to-RAM) and hibernation (S4) are not supported on the host
+  when TDX is enabled.
+  See https://docs.kernel.org/arch/x86/tdx.html#interaction-vs-s3-and-deeper-states[Interaction vs S3 and deeper states].
+* Physical https://docs.kernel.org/arch/x86/tdx.html#cpu-hotplug[CPU Hotplug (ACPI)] is not supported when TDX is enabled. Logical
+  CPU online/offline is supported.
+* https://www.qemu.org/docs/master/system/i386/tdx.html#restrictions[No SMM support].
+  TDX does not allow the hypervisor to manipulate guest
+  register states, which SMM requires.
+* https://www.qemu.org/docs/master/system/i386/tdx.html#restrictions[No readonly support for private memory].
+
+*Example Configuration*
+
+----
+# qm set <vmid> --intel-tdx type=tdx,attestation=0,vsock-cid=2,vsock-port=4050
+----
+
+The *type* defines the TDX mode. Currently, `tdx` is the only available option.
+
+The *attestation* is used to verify the TDX guest trustworthiness to other entities before provisioning secrets to the guest.
+Note that full TD attestation support is currently a work in progress.
+See the https://www.qemu.org/docs/master/system/i386/tdx.html#td-attestation[QEMU TD attestation documentation].
+
+The *vsock-cid* and *vsock-port* parameters define the vsock connection details to the Quote Generation Service (QGS), which is required for the attestation process.
+
+This enables Intel TDX for the specified VM. Proxmox configures QEMU to create
+a TDX guest by instantiating the `tdx-guest` object and setting the
+`confidential-guest-support` machine property.
+See https://www.qemu.org/docs/master/system/i386/tdx.html#launching-a-td-tdx-vm[Launching a TD].
+
+The VM must also use a TDVF-enabled firmware image.
+See https://www.qemu.org/docs/master/system/i386/tdx.html#trust-domain-virtual-firmware-tdvf[Trust Domain Virtual Firmware].
+
+The QEMU TDX guest object supports configurable attributes via a raw 64-bit
+field. The most relevant bit is `DEBUG` (bit 0), which enables off-TD debug mode
+and allows the hypervisor to inspect TD state. Debug mode should only be
+enabled for development and troubleshooting, as it reduces the security
+guarantees of the TD. See the
+https://www.qemu.org/docs/master/system/i386/tdx.html#td-attributes[TD attributes documentation].
+for details on configurable TDX attributes.
+
+*Verify TDX in the VM*
+
+The `dmesg` output footnote:[Ubuntu TDX guide https://github.com/canonical/tdx/blob/3.3/README.md#7-verify-td] should look similar to this:
+
+----
+# dmesg | grep -i tdx
+[...] tdx: Guest detected
+[...] DMI: QEMU Standard PC (Q35 + ICH9, 2009), BIOS 2023.05-2+tdx1.0~ubuntu23.10.1 10/17/2023
+[...] process: using TDX aware idle routine
+[...] Memory Encryption Features active: Intel TDX
+----
+
+Links:
+
+* https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html[Intel TDX documentation]
+* https://www.qemu.org/docs/master/system/i386/tdx.html[QEMU Intel TDX]
+* https://docs.kernel.org/virt/kvm/x86/intel-tdx.html[Linux Kernel Documentation - KVM Intel TDX]
+* https://docs.kernel.org/arch/x86/tdx.html[Linux Kernel Documentation - x86 TDX]
+* https://intel.github.io/ccc-linux-guest-hardening-docs/security-spec.html[Intel Trust Domain Extension Linux Guest Kernel Security Specification]
+* https://www.intel.com/content/www/us/en/support/articles/000091103/processors/intel-xeon-processors.html[What Intel® Xeon Processors Support for Intel® Trust Domain Extensions (Intel® TDX)?]
+* https://www.intel.com/content/www/us/en/developer/articles/technical/tdx-performance-analysis-reference-documentation.html[Intel Trust Domain Extensions (Intel® TDX) Performance Analysis Reference Documentation]
+
 [[qm_network_device]]
 Network Device
 ~~~~~~~~~~~~~~
-- 
2.47.3

[PATCH manager v2 3/3] fix #6211: ui: vm: options: update amd-sev and intel-tdx help links

[Elias Huhsovitz]

The help buttons in the AMD SEV and Intel TDX dialos were pointing to
the general memory documentation.
Update the links to use the correct documentation anchors

Signed-off-by: Elias Huhsovitz <e.huhsovitz@proxmox.com>
---
 www/manager6/qemu/SevEdit.js | 2 +-
 www/manager6/qemu/TdxEdit.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/www/manager6/qemu/SevEdit.js b/www/manager6/qemu/SevEdit.js
index 44db34bd..c308b3ab 100644
--- a/www/manager6/qemu/SevEdit.js
+++ b/www/manager6/qemu/SevEdit.js
@@ -2,7 +2,7 @@ Ext.define('PVE.qemu.SevInputPanel', {
     extend: 'Proxmox.panel.InputPanel',
     xtype: 'pveSevInputPanel',
 
-    onlineHelp: 'qm_memory', // TODO: change to 'qm_memory_encryption' one available
+    onlineHelp: 'qm_memory_encryption_sev',
 
     viewModel: {
         data: {
diff --git a/www/manager6/qemu/TdxEdit.js b/www/manager6/qemu/TdxEdit.js
index c1f990a9..38948a6c 100644
--- a/www/manager6/qemu/TdxEdit.js
+++ b/www/manager6/qemu/TdxEdit.js
@@ -2,7 +2,7 @@ Ext.define('PVE.qemu.TdxInputPanel', {
     extend: 'Proxmox.panel.InputPanel',
     xtype: 'pveTdxInputPanel',
 
-    onlineHelp: 'qm_memory', // TODO: change to 'qm_memory_encryption' one available
+    onlineHelp: 'qm_memory_encryption_tdx',
 
     viewModel: {
         data: {
-- 
2.47.3