Merge remote-tracking branch 'remotes/alistair23/tags/pull-riscv-to-apply-20211022...
[qemu.git] / docs / amd-memory-encryption.txt
1 Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
2
3 SEV is an extension to the AMD-V architecture which supports running encrypted
4 virtual machines (VMs) under the control of KVM. Encrypted VMs have their pages
5 (code and data) secured such that only the guest itself has access to the
6 unencrypted version. Each encrypted VM is associated with a unique encryption
7 key; if its data is accessed by a different entity using a different key the
8 encrypted guests data will be incorrectly decrypted, leading to unintelligible
9 data.
10
11 Key management for this feature is handled by a separate processor known as the
12 AMD secure processor (AMD-SP), which is present in AMD SOCs. Firmware running
13 inside the AMD-SP provides commands to support a common VM lifecycle. This
14 includes commands for launching, snapshotting, migrating and debugging the
15 encrypted guest. These SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP
16 ioctls.
17
18 Secure Encrypted Virtualization - Encrypted State (SEV-ES) builds on the SEV
19 support to additionally protect the guest register state. In order to allow a
20 hypervisor to perform functions on behalf of a guest, there is architectural
21 support for notifying a guest's operating system when certain types of VMEXITs
22 are about to occur. This allows the guest to selectively share information with
23 the hypervisor to satisfy the requested function.
24
25 Launching
26 ---------
27 Boot images (such as bios) must be encrypted before a guest can be booted. The
28 MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images: LAUNCH_START,
29 LAUNCH_UPDATE_DATA, LAUNCH_MEASURE and LAUNCH_FINISH. These four commands
30 together generate a fresh memory encryption key for the VM, encrypt the boot
31 images and provide a measurement than can be used as an attestation of a
32 successful launch.
33
34 For a SEV-ES guest, the LAUNCH_UPDATE_VMSA command is also used to encrypt the
35 guest register state, or VM save area (VMSA), for all of the guest vCPUs.
36
37 LAUNCH_START is called first to create a cryptographic launch context within
38 the firmware. To create this context, guest owner must provide a guest policy,
39 its public Diffie-Hellman key (PDH) and session parameters. These inputs
40 should be treated as a binary blob and must be passed as-is to the SEV firmware.
41
42 The guest policy is passed as plaintext. A hypervisor may choose to read it,
43 but should not modify it (any modification of the policy bits will result
44 in bad measurement). The guest policy is a 4-byte data structure containing
45 several flags that restricts what can be done on a running SEV guest.
46 See KM Spec section 3 and 6.2 for more details.
47
48 The guest policy can be provided via the 'policy' property (see below)
49
50 # ${QEMU} \
51    sev-guest,id=sev0,policy=0x1...\
52
53 Setting the "SEV-ES required" policy bit (bit 2) will launch the guest as a
54 SEV-ES guest (see below)
55
56 # ${QEMU} \
57    sev-guest,id=sev0,policy=0x5...\
58
59 The guest owner provided DH certificate and session parameters will be used to
60 establish a cryptographic session with the guest owner to negotiate keys used
61 for the attestation.
62
63 The DH certificate and session blob can be provided via the 'dh-cert-file' and
64 'session-file' properties (see below)
65
66 # ${QEMU} \
67      sev-guest,id=sev0,dh-cert-file=<file1>,session-file=<file2>
68
69 LAUNCH_UPDATE_DATA encrypts the memory region using the cryptographic context
70 created via the LAUNCH_START command. If required, this command can be called
71 multiple times to encrypt different memory regions. The command also calculates
72 the measurement of the memory contents as it encrypts.
73
74 LAUNCH_UPDATE_VMSA encrypts all the vCPU VMSAs for a SEV-ES guest using the
75 cryptographic context created via the LAUNCH_START command. The command also
76 calculates the measurement of the VMSAs as it encrypts them.
77
78 LAUNCH_MEASURE can be used to retrieve the measurement of encrypted memory and,
79 for a SEV-ES guest, encrypted VMSAs. This measurement is a signature of the
80 memory contents and, for a SEV-ES guest, the VMSA contents, that can be sent
81 to the guest owner as an attestation that the memory and VMSAs were encrypted
82 correctly by the firmware. The guest owner may wait to provide the guest
83 confidential information until it can verify the attestation measurement.
84 Since the guest owner knows the initial contents of the guest at boot, the
85 attestation measurement can be verified by comparing it to what the guest owner
86 expects.
87
88 LAUNCH_FINISH finalizes the guest launch and destroys the cryptographic
89 context.
90
91 See SEV KM API Spec [1] 'Launching a guest' usage flow (Appendix A) for the
92 complete flow chart.
93
94 To launch a SEV guest
95
96 # ${QEMU} \
97     -machine ...,confidential-guest-support=sev0 \
98     -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1
99
100 To launch a SEV-ES guest
101
102 # ${QEMU} \
103     -machine ...,confidential-guest-support=sev0 \
104     -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1,policy=0x5
105
106 An SEV-ES guest has some restrictions as compared to a SEV guest. Because the
107 guest register state is encrypted and cannot be updated by the VMM/hypervisor,
108 a SEV-ES guest:
109  - Does not support SMM - SMM support requires updating the guest register
110    state.
111  - Does not support reboot - a system reset requires updating the guest register
112    state.
113  - Requires in-kernel irqchip - the burden is placed on the hypervisor to
114    manage booting APs.
115
116 Debugging
117 -----------
118 Since the memory contents of a SEV guest are encrypted, hypervisor access to
119 the guest memory will return cipher text. If the guest policy allows debugging,
120 then a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access
121 the guest memory region for debug purposes.  This is not supported in QEMU yet.
122
123 Snapshot/Restore
124 -----------------
125 TODO
126
127 Live Migration
128 ----------------
129 TODO
130
131 References
132 -----------------
133
134 AMD Memory Encryption whitepaper:
135 https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
136
137 Secure Encrypted Virtualization Key Management:
138 [1] http://developer.amd.com/wordpress/media/2017/11/55766_SEV-KM-API_Specification.pdf
139
140 KVM Forum slides:
141 http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf
142 https://www.linux-kvm.org/images/9/94/Extending-Secure-Encrypted-Virtualization-with-SEV-ES-Thomas-Lendacky-AMD.pdf
143
144 AMD64 Architecture Programmer's Manual:
145    http://support.amd.com/TechDocs/24593.pdf
146    SME is section 7.10
147    SEV is section 15.34
148    SEV-ES is section 15.35