Commit | Line | Data |
---|---|---|
b38defdb BS |
1 | ====================================== |
2 | Secure Encrypted Virtualization (SEV) | |
3 | ====================================== | |
4 | ||
5 | Overview | |
6 | ======== | |
7 | ||
8 | Secure Encrypted Virtualization (SEV) is a feature found on AMD processors. | |
9 | ||
10 | SEV is an extension to the AMD-V architecture which supports running | |
11 | virtual machines (VMs) under the control of a hypervisor. When enabled, | |
12 | the memory contents of a VM will be transparently encrypted with a key | |
13 | unique to that VM. | |
14 | ||
15 | The hypervisor can determine the SEV support through the CPUID | |
16 | instruction. The CPUID function 0x8000001f reports information related | |
17 | to SEV:: | |
18 | ||
19 | 0x8000001f[eax]: | |
20 | Bit[1] indicates support for SEV | |
21 | ... | |
22 | [ecx]: | |
23 | Bits[31:0] Number of encrypted guests supported simultaneously | |
24 | ||
25 | If support for SEV is present, MSR 0xc001_0010 (MSR_K8_SYSCFG) and MSR 0xc001_0015 | |
26 | (MSR_K7_HWCR) can be used to determine if it can be enabled:: | |
27 | ||
28 | 0xc001_0010: | |
29 | Bit[23] 1 = memory encryption can be enabled | |
30 | 0 = memory encryption can not be enabled | |
31 | ||
32 | 0xc001_0015: | |
33 | Bit[0] 1 = memory encryption can be enabled | |
34 | 0 = memory encryption can not be enabled | |
35 | ||
36 | When SEV support is available, it can be enabled in a specific VM by | |
37 | setting the SEV bit before executing VMRUN.:: | |
38 | ||
39 | VMCB[0x90]: | |
40 | Bit[1] 1 = SEV is enabled | |
41 | 0 = SEV is disabled | |
42 | ||
43 | SEV hardware uses ASIDs to associate a memory encryption key with a VM. | |
44 | Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value | |
45 | defined in the CPUID 0x8000001f[ecx] field. | |
dc48bae0 BS |
46 | |
47 | SEV Key Management | |
48 | ================== | |
49 | ||
50 | The SEV guest key management is handled by a separate processor called the AMD | |
51 | Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure | |
52 | key management interface to perform common hypervisor activities such as | |
53 | encrypting bootstrap code, snapshot, migrating and debugging the guest. For more | |
54 | information, see the SEV Key Management spec [api-spec]_ | |
55 | ||
46ca9ee5 CK |
56 | The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP. If the argument |
57 | to KVM_MEMORY_ENCRYPT_OP is NULL, the ioctl returns 0 if SEV is enabled | |
2da1ed62 PB |
58 | and ``ENOTTY` if it is disabled (on some older versions of Linux, |
59 | the ioctl runs normally even with a NULL argument, and therefore will | |
46ca9ee5 | 60 | likely return ``EFAULT``). If non-NULL, the argument to KVM_MEMORY_ENCRYPT_OP |
2da1ed62 PB |
61 | must be a struct kvm_sev_cmd:: |
62 | ||
63 | struct kvm_sev_cmd { | |
64 | __u32 id; | |
65 | __u64 data; | |
66 | __u32 error; | |
67 | __u32 sev_fd; | |
68 | }; | |
69 | ||
70 | ||
71 | The ``id`` field contains the subcommand, and the ``data`` field points to | |
72 | another struct containing arguments specific to command. The ``sev_fd`` | |
73 | should point to a file descriptor that is opened on the ``/dev/sev`` | |
74 | device, if needed (see individual commands). | |
75 | ||
76 | On output, ``error`` is zero on success, or an error code. Error codes | |
2ad9a844 | 77 | are defined in ``<linux/psp-dev.h>``. |
2da1ed62 | 78 | |
dc48bae0 BS |
79 | KVM implements the following commands to support common lifecycle events of SEV |
80 | guests, such as launching, running, snapshotting, migrating and decommissioning. | |
81 | ||
82 | 1. KVM_SEV_INIT | |
83 | --------------- | |
84 | ||
85 | The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform | |
86 | context. In a typical workflow, this command should be the first command issued. | |
87 | ||
88 | Returns: 0 on success, -negative on error | |
89 | ||
90 | 2. KVM_SEV_LAUNCH_START | |
91 | ----------------------- | |
92 | ||
93 | The KVM_SEV_LAUNCH_START command is used for creating the memory encryption | |
94 | context. To create the encryption context, user must provide a guest policy, | |
95 | the owner's public Diffie-Hellman (PDH) key and session information. | |
96 | ||
97 | Parameters: struct kvm_sev_launch_start (in/out) | |
98 | ||
99 | Returns: 0 on success, -negative on error | |
100 | ||
101 | :: | |
102 | ||
103 | struct kvm_sev_launch_start { | |
104 | __u32 handle; /* if zero then firmware creates a new handle */ | |
105 | __u32 policy; /* guest's policy */ | |
106 | ||
107 | __u64 dh_uaddr; /* userspace address pointing to the guest owner's PDH key */ | |
108 | __u32 dh_len; | |
109 | ||
110 | __u64 session_addr; /* userspace address which points to the guest session information */ | |
111 | __u32 session_len; | |
112 | }; | |
113 | ||
114 | On success, the 'handle' field contains a new handle and on error, a negative value. | |
115 | ||
2da1ed62 PB |
116 | KVM_SEV_LAUNCH_START requires the ``sev_fd`` field to be valid. |
117 | ||
dc48bae0 BS |
118 | For more details, see SEV spec Section 6.2. |
119 | ||
120 | 3. KVM_SEV_LAUNCH_UPDATE_DATA | |
121 | ----------------------------- | |
122 | ||
123 | The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also | |
124 | calculates a measurement of the memory contents. The measurement is a signature | |
125 | of the memory contents that can be sent to the guest owner as an attestation | |
126 | that the memory was encrypted correctly by the firmware. | |
127 | ||
128 | Parameters (in): struct kvm_sev_launch_update_data | |
129 | ||
130 | Returns: 0 on success, -negative on error | |
131 | ||
132 | :: | |
133 | ||
134 | struct kvm_sev_launch_update { | |
135 | __u64 uaddr; /* userspace address to be encrypted (must be 16-byte aligned) */ | |
136 | __u32 len; /* length of the data to be encrypted (must be 16-byte aligned) */ | |
137 | }; | |
138 | ||
139 | For more details, see SEV spec Section 6.3. | |
140 | ||
141 | 4. KVM_SEV_LAUNCH_MEASURE | |
142 | ------------------------- | |
143 | ||
144 | The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the | |
145 | data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may | |
146 | wait to provide the guest with confidential information until it can verify the | |
147 | measurement. Since the guest owner knows the initial contents of the guest at | |
148 | boot, the measurement can be verified by comparing it to what the guest owner | |
149 | expects. | |
150 | ||
151 | Parameters (in): struct kvm_sev_launch_measure | |
152 | ||
153 | Returns: 0 on success, -negative on error | |
154 | ||
155 | :: | |
156 | ||
157 | struct kvm_sev_launch_measure { | |
158 | __u64 uaddr; /* where to copy the measurement */ | |
159 | __u32 len; /* length of measurement blob */ | |
160 | }; | |
161 | ||
162 | For more details on the measurement verification flow, see SEV spec Section 6.4. | |
163 | ||
164 | 5. KVM_SEV_LAUNCH_FINISH | |
165 | ------------------------ | |
166 | ||
167 | After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be | |
168 | issued to make the guest ready for the execution. | |
169 | ||
170 | Returns: 0 on success, -negative on error | |
171 | ||
172 | 6. KVM_SEV_GUEST_STATUS | |
173 | ----------------------- | |
174 | ||
175 | The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a | |
176 | SEV-enabled guest. | |
177 | ||
178 | Parameters (out): struct kvm_sev_guest_status | |
179 | ||
180 | Returns: 0 on success, -negative on error | |
181 | ||
182 | :: | |
183 | ||
184 | struct kvm_sev_guest_status { | |
185 | __u32 handle; /* guest handle */ | |
186 | __u32 policy; /* guest policy */ | |
187 | __u8 state; /* guest state (see enum below) */ | |
188 | }; | |
189 | ||
190 | SEV guest state: | |
191 | ||
192 | :: | |
193 | ||
194 | enum { | |
195 | SEV_STATE_INVALID = 0; | |
196 | SEV_STATE_LAUNCHING, /* guest is currently being launched */ | |
197 | SEV_STATE_SECRET, /* guest is being launched and ready to accept the ciphertext data */ | |
198 | SEV_STATE_RUNNING, /* guest is fully launched and running */ | |
199 | SEV_STATE_RECEIVING, /* guest is being migrated in from another SEV machine */ | |
200 | SEV_STATE_SENDING /* guest is getting migrated out to another SEV machine */ | |
201 | }; | |
202 | ||
203 | 7. KVM_SEV_DBG_DECRYPT | |
204 | ---------------------- | |
205 | ||
206 | The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the | |
207 | firmware to decrypt the data at the given memory region. | |
208 | ||
209 | Parameters (in): struct kvm_sev_dbg | |
210 | ||
211 | Returns: 0 on success, -negative on error | |
212 | ||
213 | :: | |
214 | ||
215 | struct kvm_sev_dbg { | |
216 | __u64 src_uaddr; /* userspace address of data to decrypt */ | |
217 | __u64 dst_uaddr; /* userspace address of destination */ | |
218 | __u32 len; /* length of memory region to decrypt */ | |
219 | }; | |
220 | ||
221 | The command returns an error if the guest policy does not allow debugging. | |
222 | ||
223 | 8. KVM_SEV_DBG_ENCRYPT | |
224 | ---------------------- | |
225 | ||
226 | The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the | |
227 | firmware to encrypt the data at the given memory region. | |
228 | ||
229 | Parameters (in): struct kvm_sev_dbg | |
230 | ||
231 | Returns: 0 on success, -negative on error | |
232 | ||
233 | :: | |
234 | ||
235 | struct kvm_sev_dbg { | |
236 | __u64 src_uaddr; /* userspace address of data to encrypt */ | |
237 | __u64 dst_uaddr; /* userspace address of destination */ | |
238 | __u32 len; /* length of memory region to encrypt */ | |
239 | }; | |
240 | ||
241 | The command returns an error if the guest policy does not allow debugging. | |
242 | ||
243 | 9. KVM_SEV_LAUNCH_SECRET | |
244 | ------------------------ | |
245 | ||
246 | The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret | |
247 | data after the measurement has been validated by the guest owner. | |
248 | ||
249 | Parameters (in): struct kvm_sev_launch_secret | |
250 | ||
251 | Returns: 0 on success, -negative on error | |
252 | ||
253 | :: | |
254 | ||
255 | struct kvm_sev_launch_secret { | |
256 | __u64 hdr_uaddr; /* userspace address containing the packet header */ | |
257 | __u32 hdr_len; | |
258 | ||
259 | __u64 guest_uaddr; /* the guest memory region where the secret should be injected */ | |
260 | __u32 guest_len; | |
261 | ||
262 | __u64 trans_uaddr; /* the hypervisor memory region which contains the secret */ | |
263 | __u32 trans_len; | |
264 | }; | |
265 | ||
266 | References | |
267 | ========== | |
268 | ||
f672febc MCC |
269 | |
270 | See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info. | |
271 | ||
dc48bae0 | 272 | .. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf |
3c603573 AK |
273 | .. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf |
274 | .. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34) | |
275 | .. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf |