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
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
164Debugging
165---------
166
167Since the memory contents of a SEV guest are encrypted, hypervisor access to
168the guest memory will return cipher text. If the guest policy allows debugging,
169then a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access
170the guest memory region for debug purposes.  This is not supported in QEMU yet.
171
172Snapshot/Restore
173----------------
174
175TODO
176
177Live Migration
178---------------
179
180TODO
181
182References
183----------
184
185`AMD Memory Encryption whitepaper
186<https://www.amd.com/content/dam/amd/en/documents/epyc-business-docs/white-papers/memory-encryption-white-paper.pdf>`_
187
188.. [SEVAPI] `Secure Encrypted Virtualization API
189   <https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf>`_
190
191.. [APMVOL2] `AMD64 Architecture Programmer's Manual Volume 2: System Programming
192   <https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf>`_
193
194KVM Forum slides:
195
196* `AMD’s Virtualization Memory Encryption (2016)
197  <http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf>`_
198* `Extending Secure Encrypted Virtualization With SEV-ES (2018)
199  <https://www.linux-kvm.org/images/9/94/Extending-Secure-Encrypted-Virtualization-with-SEV-ES-Thomas-Lendacky-AMD.pdf>`_
200
201`AMD64 Architecture Programmer's Manual:
202<https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf>`_
203
204* SME is section 7.10
205* SEV is section 15.34
206* SEV-ES is section 15.35
207