196a46defSCornelia HuckAMD Secure Encrypted Virtualization (SEV) 296a46defSCornelia Huck========================================= 396a46defSCornelia Huck 496a46defSCornelia HuckSecure Encrypted Virtualization (SEV) is a feature found on AMD processors. 596a46defSCornelia Huck 696a46defSCornelia HuckSEV is an extension to the AMD-V architecture which supports running encrypted 796a46defSCornelia Huckvirtual machines (VMs) under the control of KVM. Encrypted VMs have their pages 896a46defSCornelia Huck(code and data) secured such that only the guest itself has access to the 996a46defSCornelia Huckunencrypted version. Each encrypted VM is associated with a unique encryption 1096a46defSCornelia Huckkey; if its data is accessed by a different entity using a different key the 1196a46defSCornelia Huckencrypted guests data will be incorrectly decrypted, leading to unintelligible 1296a46defSCornelia Huckdata. 1396a46defSCornelia Huck 1496a46defSCornelia HuckKey management for this feature is handled by a separate processor known as the 1596a46defSCornelia HuckAMD secure processor (AMD-SP), which is present in AMD SOCs. Firmware running 1696a46defSCornelia Huckinside the AMD-SP provides commands to support a common VM lifecycle. This 1796a46defSCornelia Huckincludes commands for launching, snapshotting, migrating and debugging the 1896a46defSCornelia Huckencrypted guest. These SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP 1996a46defSCornelia Huckioctls. 2096a46defSCornelia Huck 2196a46defSCornelia HuckSecure Encrypted Virtualization - Encrypted State (SEV-ES) builds on the SEV 2296a46defSCornelia Hucksupport to additionally protect the guest register state. In order to allow a 2396a46defSCornelia Huckhypervisor to perform functions on behalf of a guest, there is architectural 2496a46defSCornelia Hucksupport for notifying a guest's operating system when certain types of VMEXITs 2596a46defSCornelia Huckare about to occur. This allows the guest to selectively share information with 2696a46defSCornelia Huckthe hypervisor to satisfy the requested function. 2796a46defSCornelia Huck 2896a46defSCornelia HuckLaunching 2996a46defSCornelia Huck--------- 3096a46defSCornelia Huck 3196a46defSCornelia HuckBoot images (such as bios) must be encrypted before a guest can be booted. The 3296a46defSCornelia Huck``MEMORY_ENCRYPT_OP`` ioctl provides commands to encrypt the images: ``LAUNCH_START``, 3396a46defSCornelia Huck``LAUNCH_UPDATE_DATA``, ``LAUNCH_MEASURE`` and ``LAUNCH_FINISH``. These four commands 3496a46defSCornelia Hucktogether generate a fresh memory encryption key for the VM, encrypt the boot 3596a46defSCornelia Huckimages and provide a measurement than can be used as an attestation of a 3696a46defSCornelia Hucksuccessful launch. 3796a46defSCornelia Huck 3896a46defSCornelia HuckFor a SEV-ES guest, the ``LAUNCH_UPDATE_VMSA`` command is also used to encrypt the 3996a46defSCornelia Huckguest register state, or VM save area (VMSA), for all of the guest vCPUs. 4096a46defSCornelia Huck 4196a46defSCornelia Huck``LAUNCH_START`` is called first to create a cryptographic launch context within 4296a46defSCornelia Huckthe firmware. To create this context, guest owner must provide a guest policy, 4396a46defSCornelia Huckits public Diffie-Hellman key (PDH) and session parameters. These inputs 4496a46defSCornelia Huckshould be treated as a binary blob and must be passed as-is to the SEV firmware. 4596a46defSCornelia Huck 4696a46defSCornelia HuckThe guest policy is passed as plaintext. A hypervisor may choose to read it, 4796a46defSCornelia Huckbut should not modify it (any modification of the policy bits will result 4896a46defSCornelia Huckin bad measurement). The guest policy is a 4-byte data structure containing 4996a46defSCornelia Huckseveral flags that restricts what can be done on a running SEV guest. 50776a6a32SDov MurikSee SEV API Spec ([SEVAPI]_) section 3 and 6.2 for more details. 5196a46defSCornelia Huck 5296a46defSCornelia HuckThe guest policy can be provided via the ``policy`` property:: 5396a46defSCornelia Huck 5496a46defSCornelia Huck # ${QEMU} \ 5596a46defSCornelia Huck sev-guest,id=sev0,policy=0x1...\ 5696a46defSCornelia Huck 5796a46defSCornelia HuckSetting the "SEV-ES required" policy bit (bit 2) will launch the guest as a 5896a46defSCornelia HuckSEV-ES guest:: 5996a46defSCornelia Huck 6096a46defSCornelia Huck # ${QEMU} \ 6196a46defSCornelia Huck sev-guest,id=sev0,policy=0x5...\ 6296a46defSCornelia Huck 6396a46defSCornelia HuckThe guest owner provided DH certificate and session parameters will be used to 6496a46defSCornelia Huckestablish a cryptographic session with the guest owner to negotiate keys used 6596a46defSCornelia Huckfor the attestation. 6696a46defSCornelia Huck 6796a46defSCornelia HuckThe DH certificate and session blob can be provided via the ``dh-cert-file`` and 6896a46defSCornelia Huck``session-file`` properties:: 6996a46defSCornelia Huck 7096a46defSCornelia Huck # ${QEMU} \ 7196a46defSCornelia Huck sev-guest,id=sev0,dh-cert-file=<file1>,session-file=<file2> 7296a46defSCornelia Huck 7396a46defSCornelia Huck``LAUNCH_UPDATE_DATA`` encrypts the memory region using the cryptographic context 7496a46defSCornelia Huckcreated via the ``LAUNCH_START`` command. If required, this command can be called 7596a46defSCornelia Huckmultiple times to encrypt different memory regions. The command also calculates 7696a46defSCornelia Huckthe measurement of the memory contents as it encrypts. 7796a46defSCornelia Huck 7896a46defSCornelia Huck``LAUNCH_UPDATE_VMSA`` encrypts all the vCPU VMSAs for a SEV-ES guest using the 7996a46defSCornelia Huckcryptographic context created via the ``LAUNCH_START`` command. The command also 8096a46defSCornelia Huckcalculates the measurement of the VMSAs as it encrypts them. 8196a46defSCornelia Huck 8296a46defSCornelia Huck``LAUNCH_MEASURE`` can be used to retrieve the measurement of encrypted memory and, 8396a46defSCornelia Huckfor a SEV-ES guest, encrypted VMSAs. This measurement is a signature of the 8496a46defSCornelia Huckmemory contents and, for a SEV-ES guest, the VMSA contents, that can be sent 8596a46defSCornelia Huckto the guest owner as an attestation that the memory and VMSAs were encrypted 8696a46defSCornelia Huckcorrectly by the firmware. The guest owner may wait to provide the guest 8796a46defSCornelia Huckconfidential information until it can verify the attestation measurement. 8896a46defSCornelia HuckSince the guest owner knows the initial contents of the guest at boot, the 8996a46defSCornelia Huckattestation measurement can be verified by comparing it to what the guest owner 9096a46defSCornelia Huckexpects. 9196a46defSCornelia Huck 9296a46defSCornelia Huck``LAUNCH_FINISH`` finalizes the guest launch and destroys the cryptographic 9396a46defSCornelia Huckcontext. 9496a46defSCornelia Huck 95776a6a32SDov MurikSee SEV API Spec ([SEVAPI]_) 'Launching a guest' usage flow (Appendix A) for the 9696a46defSCornelia Huckcomplete flow chart. 9796a46defSCornelia Huck 9896a46defSCornelia HuckTo launch a SEV guest:: 9996a46defSCornelia Huck 10096a46defSCornelia Huck # ${QEMU} \ 10196a46defSCornelia Huck -machine ...,confidential-guest-support=sev0 \ 10296a46defSCornelia Huck -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 10396a46defSCornelia Huck 10496a46defSCornelia HuckTo launch a SEV-ES guest:: 10596a46defSCornelia Huck 10696a46defSCornelia Huck # ${QEMU} \ 10796a46defSCornelia Huck -machine ...,confidential-guest-support=sev0 \ 10896a46defSCornelia Huck -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1,policy=0x5 10996a46defSCornelia Huck 11096a46defSCornelia HuckAn SEV-ES guest has some restrictions as compared to a SEV guest. Because the 11196a46defSCornelia Huckguest register state is encrypted and cannot be updated by the VMM/hypervisor, 11296a46defSCornelia Hucka SEV-ES guest: 11396a46defSCornelia Huck 11496a46defSCornelia Huck - Does not support SMM - SMM support requires updating the guest register 11596a46defSCornelia Huck state. 11696a46defSCornelia Huck - Does not support reboot - a system reset requires updating the guest register 11796a46defSCornelia Huck state. 11896a46defSCornelia Huck - Requires in-kernel irqchip - the burden is placed on the hypervisor to 11996a46defSCornelia Huck manage booting APs. 12096a46defSCornelia Huck 121776a6a32SDov MurikCalculating expected guest launch measurement 122776a6a32SDov Murik--------------------------------------------- 123776a6a32SDov Murik 124776a6a32SDov MurikIn order to verify the guest launch measurement, The Guest Owner must compute 125776a6a32SDov Murikit in the exact same way as it is calculated by the AMD-SP. SEV API Spec 126776a6a32SDov Murik([SEVAPI]_) section 6.5.1 describes the AMD-SP operations: 127776a6a32SDov Murik 128776a6a32SDov Murik GCTX.LD is finalized, producing the hash digest of all plaintext data 129776a6a32SDov Murik imported into the guest. 130776a6a32SDov Murik 131776a6a32SDov Murik The launch measurement is calculated as: 132776a6a32SDov Murik 133776a6a32SDov Murik HMAC(0x04 || API_MAJOR || API_MINOR || BUILD || GCTX.POLICY || GCTX.LD || MNONCE; GCTX.TIK) 134776a6a32SDov Murik 135776a6a32SDov Murik where "||" represents concatenation. 136776a6a32SDov Murik 137776a6a32SDov MurikThe values of API_MAJOR, API_MINOR, BUILD, and GCTX.POLICY can be obtained 138776a6a32SDov Murikfrom the ``query-sev`` qmp command. 139776a6a32SDov Murik 140776a6a32SDov MurikThe value of MNONCE is part of the response of ``query-sev-launch-measure``: it 141776a6a32SDov Murikis the last 16 bytes of the base64-decoded data field (see SEV API Spec 142776a6a32SDov Murik([SEVAPI]_) section 6.5.2 Table 52: LAUNCH_MEASURE Measurement Buffer). 143776a6a32SDov Murik 144776a6a32SDov MurikThe value of GCTX.LD is 145776a6a32SDov Murik``SHA256(firmware_blob || kernel_hashes_blob || vmsas_blob)``, where: 146776a6a32SDov Murik 147776a6a32SDov Murik* ``firmware_blob`` is the content of the entire firmware flash file (for 148776a6a32SDov Murik example, ``OVMF.fd``). Note that you must build a stateless firmware file 149776a6a32SDov Murik which doesn't use an NVRAM store, because the NVRAM area is not measured, and 150776a6a32SDov Murik therefore it is not secure to use a firmware which uses state from an NVRAM 151776a6a32SDov Murik store. 152776a6a32SDov Murik* if kernel is used, and ``kernel-hashes=on``, then ``kernel_hashes_blob`` is 153776a6a32SDov Murik the content of PaddedSevHashTable (including the zero padding), which itself 154776a6a32SDov Murik includes the hashes of kernel, initrd, and cmdline that are passed to the 155776a6a32SDov Murik guest. The PaddedSevHashTable struct is defined in ``target/i386/sev.c``. 156776a6a32SDov Murik* if SEV-ES is enabled (``policy & 0x4 != 0``), ``vmsas_blob`` is the 157776a6a32SDov Murik concatenation of all VMSAs of the guest vcpus. Each VMSA is 4096 bytes long; 158776a6a32SDov Murik its content is defined inside Linux kernel code as ``struct vmcb_save_area``, 159776a6a32SDov Murik or in AMD APM Volume 2 ([APMVOL2]_) Table B-2: VMCB Layout, State Save Area. 160776a6a32SDov Murik 161776a6a32SDov MurikIf kernel hashes are not used, or SEV-ES is disabled, use empty blobs for 162776a6a32SDov Murik``kernel_hashes_blob`` and ``vmsas_blob`` as needed. 163776a6a32SDov Murik 16496a46defSCornelia HuckDebugging 16596a46defSCornelia Huck--------- 16696a46defSCornelia Huck 16796a46defSCornelia HuckSince the memory contents of a SEV guest are encrypted, hypervisor access to 16896a46defSCornelia Huckthe guest memory will return cipher text. If the guest policy allows debugging, 16996a46defSCornelia Huckthen a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access 17096a46defSCornelia Huckthe guest memory region for debug purposes. This is not supported in QEMU yet. 17196a46defSCornelia Huck 17296a46defSCornelia HuckSnapshot/Restore 17396a46defSCornelia Huck---------------- 17496a46defSCornelia Huck 17596a46defSCornelia HuckTODO 17696a46defSCornelia Huck 17796a46defSCornelia HuckLive Migration 17896a46defSCornelia Huck--------------- 17996a46defSCornelia Huck 18096a46defSCornelia HuckTODO 18196a46defSCornelia Huck 18296a46defSCornelia HuckReferences 18396a46defSCornelia Huck---------- 18496a46defSCornelia Huck 18596a46defSCornelia Huck`AMD Memory Encryption whitepaper 186*b3175081SJianlin Li<https://www.amd.com/content/dam/amd/en/documents/epyc-business-docs/white-papers/memory-encryption-white-paper.pdf>`_ 18796a46defSCornelia Huck 188776a6a32SDov Murik.. [SEVAPI] `Secure Encrypted Virtualization API 189776a6a32SDov Murik <https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf>`_ 190776a6a32SDov Murik 191776a6a32SDov Murik.. [APMVOL2] `AMD64 Architecture Programmer's Manual Volume 2: System Programming 192*b3175081SJianlin Li <https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf>`_ 19396a46defSCornelia Huck 19496a46defSCornelia HuckKVM Forum slides: 19596a46defSCornelia Huck 19696a46defSCornelia Huck* `AMD’s Virtualization Memory Encryption (2016) 19796a46defSCornelia Huck <http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf>`_ 19896a46defSCornelia Huck* `Extending Secure Encrypted Virtualization With SEV-ES (2018) 19996a46defSCornelia Huck <https://www.linux-kvm.org/images/9/94/Extending-Secure-Encrypted-Virtualization-with-SEV-ES-Thomas-Lendacky-AMD.pdf>`_ 20096a46defSCornelia Huck 20196a46defSCornelia Huck`AMD64 Architecture Programmer's Manual: 202*b3175081SJianlin Li<https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf>`_ 20396a46defSCornelia Huck 20496a46defSCornelia Huck* SME is section 7.10 20596a46defSCornelia Huck* SEV is section 15.34 20696a46defSCornelia Huck* SEV-ES is section 15.35 207