[pve-devel] [PATCH docs v2 2/2] added Memory Encryption documentation

[Matthias Heiserer]

Inline, I have some suggestions regarding wording and spelling

On 11.11.2022 15:27, Markus Frank wrote:
> added AMD SEV documentation for "[PATCH qemu-server] QEMU AMD SEV
> enable"
> 
> Signed-off-by: Markus Frank <m.frank at proxmox.com>
> ---
>   qm.adoc | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 113 insertions(+)
> 
> diff --git a/qm.adoc b/qm.adoc
> index e7d0c07..5ba43a2 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -598,6 +598,119 @@ systems.
>   When allocating RAM to your VMs, a good rule of thumb is always to leave 1GB
>   of RAM available to the host.
>   
> +[[qm_memory_encryption]]
> +Memory Encryption
> +~~~~~~~~~~~~~~~~~
> +
> +[[qm_memory_encryption_sev]]
> +AMD SEV
> +^^^^^^^
> +
> +Memory Encryption per VM using AES-128 Encryption and the AMD Secure Processor.
> +See https://developer.amd.com/sev/[AMD SEV]
> +
> +*Host-Requirements:*
> +
> +* AMD EPYC/Ryzen PRO CPU
> +* configured SEV BIOS settings on Host Machine
> +* add "kvm_amd.sev=1" to kernel parameters if not enabled by default
> +* add "mem_encrypt=on" to kernel parameters if you want encrypt memory on the
"to encrypt" or "encrypted"
> +host (SME)
> +see https://www.kernel.org/doc/Documentation/x86/amd-memory-encryption.txt
> +* maybe increase SWIOTLB see https://github.com/AMDESE/AMDSEV#faq-4
> +
> +To check if SEV is enabled on Host-Machine search for `sev` in dmesg
I think "on the host" would be the best wording
> +and print out the sev kernel parameter of kvm_amd:
> +
> +----
> +# dmesg | grep -i sev
> +[...] ccp 0000:45:00.1: sev enabled
> +[...] ccp 0000:45:00.1: SEV API: <buildversion>
> +[...] SEV supported: <number> ASIDs
> +[...] SEV-ES supported: <number> ASIDs
> +# cat /sys/module/kvm_amd/parameters/sev
> +Y
> +----
> +
> +*Guest-VM-Requirements:*
Also here, we spell guest/host without hyphen. Maybe just drop the VM, 
i.e. "Guest Requirements"
> +
> +* edk2-OVMF
> +* advisable to use Q35
> +* The guest operating system inside the VM must contain SEV-support
> +* if there are problems while booting (stops at blank/splash screen or "Guest has not
> +initialized the display (yet)") try to add virtio-rng and/or set "freeze: 1"
> +so that you wait a few seconds before you click on *Resume* to boot.
There's inconsistent capitalization
> +
> +*Limitations:*
> +
> +* Because the memory is encrypted the memory usage on host is always wrong
> +* Operations that involve saving or restoring memory like snapshots
> +& live migration do not work yet or are attackable
> +https://github.com/PSPReverse/amd-sev-migration-attack
> +* KVM is unsupported when running as an SEV guest
> +* PCI passthrough is not supported
> +
> +Example Configuration:
> +
> +----
> +# qm set <vmid> -memory_encryption type=sev,cbitpos=47,policy=0x0001,reduced-phys-bits=1
> +----
> +
> +*SEV Parameters*
I'd use the same format as e.g. in "10.13.3. Options".
Regarding the following sentences: Consistently end them with a dot or 
without, don't mix.
> +
> +*type* defines the encryption technology ("type=" is not necessary):
> +currently-supported: *sev*
> +and in the future: sev-snp, mktme
> +
> +*reduced-phys-bios*, *cbitpos* and *policy* correspond to the variables with the
> +same name in qemu.
> +
> +*reduced-phys-bios* and *cbitpos* are system specific and can be read out
> +with QMP. If not set, qm starts a dummy-vm to read QMP
> +for these variables out and saves them to config.
> +
> +*policy* can be calculated with
> +https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf[AMD SEV API Specification Chapter 3]
> +
> +To use SEV-ES (CPU register encryption) the *policy* should be set
> +somewhere between 0x4 and 0x7 or 0xC and 0xF, etc.
> +(Bit-2 has to be set 1 (LSB 0 bit numbering))
> +
> +*Check if SEV is working on the Guest*
> +
> +Method 1 - dmesg:
> +
> +Output should look like this.
> +
> +----
> +# dmesg | grep -i sev
> +AMD Memory Encryption Features active: SEV
> +----
> +
> +Method 2 - MSR 0xc0010131 (MSR_AMD64_SEV):
> +
> +Output should be 1.
> +
> +----
> +# apt install msr-tools
> +# modprobe msr
> +# rdmsr -a 0xc0010131
> +1
> +----
> +
> +Links:
> +
> +* 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
In case you haven't done so, you could make a snapshot of these pages 
with archive.org or similarly, so there's a backup if they ever get removed.
> +
> +// Commented because cannot be tested without new EPYC-CPU
> +// AMD SEV-SNP
> +// ^^^^^^^^^^^
> +// * SEV-SNP needs EPYC 7003 "Milan" processors.
> +// * SEV-SNP should in Kernel 5.19:
> +// https://www.phoronix.com/scan.php?page=news_item&px=AMD-SEV-SNP-Arrives-Linux-5.19
>   
>   [[qm_network_device]]
>   Network Device