docs/system/i386/amd-memory-encryption.rst

   1 AMD Secure Encrypted Virtualization (SEV)
   2 =========================================
   3
   4 Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
   5
   6 SEV is an extension to the AMD-V architecture which supports running encrypted
   7 virtual 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
   9 unencrypted version. Each encrypted VM is associated with a unique encryption
  10 key; if its data is accessed by a different entity using a different key the
  11 encrypted guests data will be incorrectly decrypted, leading to unintelligible
  12 data.
  13
  14 Key management for this feature is handled by a separate processor known as the
  15 AMD secure processor (AMD-SP), which is present in AMD SOCs. Firmware running
  16 inside the AMD-SP provides commands to support a common VM lifecycle. This
  17 includes commands for launching, snapshotting, migrating and debugging the
  18 encrypted guest. These SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP
  19 ioctls.
  20
  21 Secure Encrypted Virtualization - Encrypted State (SEV-ES) builds on the SEV
  22 support to additionally protect the guest register state. In order to allow a
  23 hypervisor to perform functions on behalf of a guest, there is architectural
  24 support for notifying a guest's operating system when certain types of VMEXITs
  25 are about to occur. This allows the guest to selectively share information with
  26 the hypervisor to satisfy the requested function.
  27
  28 Launching (SEV and SEV-ES)
  29 --------------------------
  30
  31 Boot 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
  34 together generate a fresh memory encryption key for the VM, encrypt the boot
  35 images and provide a measurement than can be used as an attestation of a
  36 successful launch.
  37
  38 For a SEV-ES guest, the ``LAUNCH_UPDATE_VMSA`` command is also used to encrypt the
  39 guest 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
  42 the firmware. To create this context, guest owner must provide a guest policy,
  43 its public Diffie-Hellman key (PDH) and session parameters. These inputs
  44 should be treated as a binary blob and must be passed as-is to the SEV firmware.
  45
  46 The guest policy is passed as plaintext. A hypervisor may choose to read it,
  47 but should not modify it (any modification of the policy bits will result
  48 in bad measurement). The guest policy is a 4-byte data structure containing
  49 several flags that restricts what can be done on a running SEV guest.
  50 See SEV API Spec ([SEVAPI]_) section 3 and 6.2 for more details.
  51
  52 The guest policy can be provided via the ``policy`` property::
  53
  54   # ${QEMU} \
  55      sev-guest,id=sev0,policy=0x1...\
  56
  57 Setting the "SEV-ES required" policy bit (bit 2) will launch the guest as a
  58 SEV-ES guest::
  59
  60   # ${QEMU} \
  61      sev-guest,id=sev0,policy=0x5...\
  62
  63 The guest owner provided DH certificate and session parameters will be used to
  64 establish a cryptographic session with the guest owner to negotiate keys used
  65 for the attestation.
  66
  67 The 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
  74 created via the ``LAUNCH_START`` command. If required, this command can be called
  75 multiple times to encrypt different memory regions. The command also calculates
  76 the 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
  79 cryptographic context created via the ``LAUNCH_START`` command. The command also
  80 calculates the measurement of the VMSAs as it encrypts them.
  81
  82 ``LAUNCH_MEASURE`` can be used to retrieve the measurement of encrypted memory and,
  83 for a SEV-ES guest, encrypted VMSAs. This measurement is a signature of the
  84 memory contents and, for a SEV-ES guest, the VMSA contents, that can be sent
  85 to the guest owner as an attestation that the memory and VMSAs were encrypted
  86 correctly by the firmware. The guest owner may wait to provide the guest
  87 confidential information until it can verify the attestation measurement.
  88 Since the guest owner knows the initial contents of the guest at boot, the
  89 attestation measurement can be verified by comparing it to what the guest owner
  90 expects.
  91
  92 ``LAUNCH_FINISH`` finalizes the guest launch and destroys the cryptographic
  93 context.
  94
  95 See SEV API Spec ([SEVAPI]_) 'Launching a guest' usage flow (Appendix A) for the
  96 complete flow chart.
  97
  98 To 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
 104 To 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
 110 An SEV-ES guest has some restrictions as compared to a SEV guest. Because the
 111 guest register state is encrypted and cannot be updated by the VMM/hypervisor,
 112 a 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
 121 Calculating expected guest launch measurement
 122 ---------------------------------------------
 123
 124 In order to verify the guest launch measurement, The Guest Owner must compute
 125 it 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
 137 The values of API_MAJOR, API_MINOR, BUILD, and GCTX.POLICY can be obtained
 138 from the ``query-sev`` qmp command.
 139
 140 The value of MNONCE is part of the response of ``query-sev-launch-measure``: it
 141 is 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
 144 The 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
 161 If kernel hashes are not used, or SEV-ES is disabled, use empty blobs for
 162 ``kernel_hashes_blob`` and ``vmsas_blob`` as needed.
 163
 164 Launching (SEV-SNP)
 165 -------------------
 166 Boot 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
 169 three commands communicate with SEV-SNP firmware to generate a fresh memory
 170 encryption key for the VM, encrypt the boot images for a successful launch. For
 171 more details on the SEV-SNP firmware interfaces used by these commands please
 172 see the SEV-SNP Firmware ABI.
 173
 174 ``SNP_LAUNCH_START`` is called first to create a cryptographic launch context
 175 within the firmware. To create this context, the guest owner must provide a
 176 guest policy and other parameters as described in the SEV-SNP firmware
 177 specification. The launch parameters should be specified as described in the
 178 QAPI schema for the sev-snp-guest object.
 179
 180 The ``SNP_LAUNCH_START`` uses the following parameters, which can be configured
 181 by 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
 195 created via the ``SNP_LAUNCH_START`` command. If required, this command can be
 196 called multiple times to encrypt different memory regions. The command also
 197 calculates the measurement of the memory contents as it encrypts.
 198
 199 ``SNP_LAUNCH_FINISH`` finalizes the guest launch flow. Optionally, while
 200 finalizing the launch the firmware can perform checks on the launch digest
 201 computing through the ``SNP_LAUNCH_UPDATE``. To perform the check the user must
 202 supply the id block, authentication blob and host data that should be included
 203 in the attestation report. See the SEV-SNP spec for further details.
 204
 205 The ``SNP_LAUNCH_FINISH`` uses the following parameters, which can be configured
 206 by 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
 222 To launch a SEV-SNP guest (additional parameters are documented in the QAPI
 223 schema 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
 230 Debugging
 231 ---------
 232
 233 Since the memory contents of a SEV guest are encrypted, hypervisor access to
 234 the guest memory will return cipher text. If the guest policy allows debugging,
 235 then a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access
 236 the guest memory region for debug purposes.  This is not supported in QEMU yet.
 237
 238 Snapshot/Restore
 239 ----------------
 240
 241 TODO
 242
 243 Live Migration
 244 ---------------
 245
 246 TODO
 247
 248 References
 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
 260 KVM 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