1AMD Secure Encrypted Virtualization (SEV) 2========================================= 3 4Secure Encrypted Virtualization (SEV) is a feature found on AMD processors. 5 6SEV is an extension to the AMD-V architecture which supports running encrypted 7virtual machines (VMs) under the control of KVM. Encrypted VMs have their pages 8(code and data) secured such that only the guest itself has access to the 9unencrypted version. Each encrypted VM is associated with a unique encryption 10key; if its data is accessed by a different entity using a different key the 11encrypted guests data will be incorrectly decrypted, leading to unintelligible 12data. 13 14Key management for this feature is handled by a separate processor known as the 15AMD secure processor (AMD-SP), which is present in AMD SOCs. Firmware running 16inside the AMD-SP provides commands to support a common VM lifecycle. This 17includes commands for launching, snapshotting, migrating and debugging the 18encrypted guest. These SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP 19ioctls. 20 21Secure Encrypted Virtualization - Encrypted State (SEV-ES) builds on the SEV 22support to additionally protect the guest register state. In order to allow a 23hypervisor to perform functions on behalf of a guest, there is architectural 24support for notifying a guest's operating system when certain types of VMEXITs 25are about to occur. This allows the guest to selectively share information with 26the hypervisor to satisfy the requested function. 27 28Launching (SEV and SEV-ES) 29-------------------------- 30 31Boot images (such as bios) must be encrypted before a guest can be booted. The 32``MEMORY_ENCRYPT_OP`` ioctl provides commands to encrypt the images: ``LAUNCH_START``, 33``LAUNCH_UPDATE_DATA``, ``LAUNCH_MEASURE`` and ``LAUNCH_FINISH``. These four commands 34together generate a fresh memory encryption key for the VM, encrypt the boot 35images and provide a measurement than can be used as an attestation of a 36successful launch. 37 38For a SEV-ES guest, the ``LAUNCH_UPDATE_VMSA`` command is also used to encrypt the 39guest register state, or VM save area (VMSA), for all of the guest vCPUs. 40 41``LAUNCH_START`` is called first to create a cryptographic launch context within 42the firmware. To create this context, guest owner must provide a guest policy, 43its public Diffie-Hellman key (PDH) and session parameters. These inputs 44should be treated as a binary blob and must be passed as-is to the SEV firmware. 45 46The guest policy is passed as plaintext. A hypervisor may choose to read it, 47but should not modify it (any modification of the policy bits will result 48in bad measurement). The guest policy is a 4-byte data structure containing 49several flags that restricts what can be done on a running SEV guest. 50See SEV API Spec ([SEVAPI]_) section 3 and 6.2 for more details. 51 52The guest policy can be provided via the ``policy`` property:: 53 54 # ${QEMU} \ 55 sev-guest,id=sev0,policy=0x1...\ 56 57Setting the "SEV-ES required" policy bit (bit 2) will launch the guest as a 58SEV-ES guest:: 59 60 # ${QEMU} \ 61 sev-guest,id=sev0,policy=0x5...\ 62 63The guest owner provided DH certificate and session parameters will be used to 64establish a cryptographic session with the guest owner to negotiate keys used 65for the attestation. 66 67The DH certificate and session blob can be provided via the ``dh-cert-file`` and 68``session-file`` properties:: 69 70 # ${QEMU} \ 71 sev-guest,id=sev0,dh-cert-file=<file1>,session-file=<file2> 72 73``LAUNCH_UPDATE_DATA`` encrypts the memory region using the cryptographic context 74created via the ``LAUNCH_START`` command. If required, this command can be called 75multiple times to encrypt different memory regions. The command also calculates 76the measurement of the memory contents as it encrypts. 77 78``LAUNCH_UPDATE_VMSA`` encrypts all the vCPU VMSAs for a SEV-ES guest using the 79cryptographic context created via the ``LAUNCH_START`` command. The command also 80calculates the measurement of the VMSAs as it encrypts them. 81 82``LAUNCH_MEASURE`` can be used to retrieve the measurement of encrypted memory and, 83for a SEV-ES guest, encrypted VMSAs. This measurement is a signature of the 84memory contents and, for a SEV-ES guest, the VMSA contents, that can be sent 85to the guest owner as an attestation that the memory and VMSAs were encrypted 86correctly by the firmware. The guest owner may wait to provide the guest 87confidential information until it can verify the attestation measurement. 88Since the guest owner knows the initial contents of the guest at boot, the 89attestation measurement can be verified by comparing it to what the guest owner 90expects. 91 92``LAUNCH_FINISH`` finalizes the guest launch and destroys the cryptographic 93context. 94 95See SEV API Spec ([SEVAPI]_) 'Launching a guest' usage flow (Appendix A) for the 96complete flow chart. 97 98To launch a SEV guest:: 99 100 # ${QEMU} \ 101 -machine ...,confidential-guest-support=sev0 \ 102 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 103 104To launch a SEV-ES guest:: 105 106 # ${QEMU} \ 107 -machine ...,confidential-guest-support=sev0 \ 108 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1,policy=0x5 109 110An SEV-ES guest has some restrictions as compared to a SEV guest. Because the 111guest register state is encrypted and cannot be updated by the VMM/hypervisor, 112a SEV-ES guest: 113 114 - Does not support SMM - SMM support requires updating the guest register 115 state. 116 - Does not support reboot - a system reset requires updating the guest register 117 state. 118 - Requires in-kernel irqchip - the burden is placed on the hypervisor to 119 manage booting APs. 120 121Calculating expected guest launch measurement 122--------------------------------------------- 123 124In order to verify the guest launch measurement, The Guest Owner must compute 125it in the exact same way as it is calculated by the AMD-SP. SEV API Spec 126([SEVAPI]_) section 6.5.1 describes the AMD-SP operations: 127 128 GCTX.LD is finalized, producing the hash digest of all plaintext data 129 imported into the guest. 130 131 The launch measurement is calculated as: 132 133 HMAC(0x04 || API_MAJOR || API_MINOR || BUILD || GCTX.POLICY || GCTX.LD || MNONCE; GCTX.TIK) 134 135 where "||" represents concatenation. 136 137The values of API_MAJOR, API_MINOR, BUILD, and GCTX.POLICY can be obtained 138from the ``query-sev`` qmp command. 139 140The value of MNONCE is part of the response of ``query-sev-launch-measure``: it 141is the last 16 bytes of the base64-decoded data field (see SEV API Spec 142([SEVAPI]_) section 6.5.2 Table 52: LAUNCH_MEASURE Measurement Buffer). 143 144The value of GCTX.LD is 145``SHA256(firmware_blob || kernel_hashes_blob || vmsas_blob)``, where: 146 147* ``firmware_blob`` is the content of the entire firmware flash file (for 148 example, ``OVMF.fd``). Note that you must build a stateless firmware file 149 which doesn't use an NVRAM store, because the NVRAM area is not measured, and 150 therefore it is not secure to use a firmware which uses state from an NVRAM 151 store. 152* if kernel is used, and ``kernel-hashes=on``, then ``kernel_hashes_blob`` is 153 the content of PaddedSevHashTable (including the zero padding), which itself 154 includes the hashes of kernel, initrd, and cmdline that are passed to the 155 guest. The PaddedSevHashTable struct is defined in ``target/i386/sev.c``. 156* if SEV-ES is enabled (``policy & 0x4 != 0``), ``vmsas_blob`` is the 157 concatenation of all VMSAs of the guest vcpus. Each VMSA is 4096 bytes long; 158 its content is defined inside Linux kernel code as ``struct vmcb_save_area``, 159 or in AMD APM Volume 2 ([APMVOL2]_) Table B-2: VMCB Layout, State Save Area. 160 161If kernel hashes are not used, or SEV-ES is disabled, use empty blobs for 162``kernel_hashes_blob`` and ``vmsas_blob`` as needed. 163 164Launching (SEV-SNP) 165------------------- 166Boot images (such as bios) must be encrypted before a guest can be booted. The 167``MEMORY_ENCRYPT_OP`` ioctl provides commands to encrypt the images: 168``SNP_LAUNCH_START``, ``SNP_LAUNCH_UPDATE``, and ``SNP_LAUNCH_FINISH``. These 169three commands communicate with SEV-SNP firmware to generate a fresh memory 170encryption key for the VM, encrypt the boot images for a successful launch. For 171more details on the SEV-SNP firmware interfaces used by these commands please 172see the SEV-SNP Firmware ABI. 173 174``SNP_LAUNCH_START`` is called first to create a cryptographic launch context 175within the firmware. To create this context, the guest owner must provide a 176guest policy and other parameters as described in the SEV-SNP firmware 177specification. The launch parameters should be specified as described in the 178QAPI schema for the sev-snp-guest object. 179 180The ``SNP_LAUNCH_START`` uses the following parameters, which can be configured 181by the corresponding parameters documented in the QAPI schema for the 182'sev-snp-guest' object. 183 184+--------+-------+----------+-------------------------------------------------+ 185| key | type | default | meaning | 186+---------------------------+-------------------------------------------------+ 187| policy | hex | 0x30000 | a 64-bit guest policy | 188+---------------------------+-------------------------------------------------+ 189| guest-visible-workarounds | string| 0 | 16-byte base64 encoded string| 190| | | | for guest OS visible | 191| | | | workarounds. | 192+---------------------------+-------------------------------------------------+ 193 194``SNP_LAUNCH_UPDATE`` encrypts the memory region using the cryptographic context 195created via the ``SNP_LAUNCH_START`` command. If required, this command can be 196called multiple times to encrypt different memory regions. The command also 197calculates the measurement of the memory contents as it encrypts. 198 199``SNP_LAUNCH_FINISH`` finalizes the guest launch flow. Optionally, while 200finalizing the launch the firmware can perform checks on the launch digest 201computing through the ``SNP_LAUNCH_UPDATE``. To perform the check the user must 202supply the id block, authentication blob and host data that should be included 203in the attestation report. See the SEV-SNP spec for further details. 204 205The ``SNP_LAUNCH_FINISH`` uses the following parameters, which can be configured 206by the corresponding parameters documented in the QAPI schema for the 207'sev-snp-guest' object. 208 209+--------------------+-------+----------+-------------------------------------+ 210| key | type | default | meaning | 211+--------------------+-------+----------+-------------------------------------+ 212| id-block | string| none | base64 encoded ID block | 213+--------------------+-------+----------+-------------------------------------+ 214| id-auth | string| none | base64 encoded authentication | 215| | | | information | 216+--------------------+-------+----------+-------------------------------------+ 217| author-key-enabled | bool | 0 | auth block contains author key | 218+--------------------+-------+----------+-------------------------------------+ 219| host_data | string| none | host provided data | 220+--------------------+-------+----------+-------------------------------------+ 221 222To launch a SEV-SNP guest (additional parameters are documented in the QAPI 223schema for the 'sev-snp-guest' object):: 224 225 # ${QEMU} \ 226 -machine ...,confidential-guest-support=sev0 \ 227 -object sev-snp-guest,id=sev0,cbitpos=51,reduced-phys-bits=1 228 229 230Debugging 231--------- 232 233Since the memory contents of a SEV guest are encrypted, hypervisor access to 234the guest memory will return cipher text. If the guest policy allows debugging, 235then a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access 236the guest memory region for debug purposes. This is not supported in QEMU yet. 237 238Snapshot/Restore 239---------------- 240 241TODO 242 243Live Migration 244--------------- 245 246TODO 247 248References 249---------- 250 251`AMD Memory Encryption whitepaper 252<https://www.amd.com/content/dam/amd/en/documents/epyc-business-docs/white-papers/memory-encryption-white-paper.pdf>`_ 253 254.. [SEVAPI] `Secure Encrypted Virtualization API 255 <https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf>`_ 256 257.. [APMVOL2] `AMD64 Architecture Programmer's Manual Volume 2: System Programming 258 <https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf>`_ 259 260KVM Forum slides: 261 262* `AMD’s Virtualization Memory Encryption (2016) 263 <http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf>`_ 264* `Extending Secure Encrypted Virtualization With SEV-ES (2018) 265 <https://www.linux-kvm.org/images/9/94/Extending-Secure-Encrypted-Virtualization-with-SEV-ES-Thomas-Lendacky-AMD.pdf>`_ 266 267`AMD64 Architecture Programmer's Manual: 268<https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf>`_ 269 270* SME is section 7.10 271* SEV is section 15.34 272* SEV-ES is section 15.35 273