1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======================================
4 Secure Encrypted Virtualization (SEV)
5 ======================================
6
7 Overview
8 ========
9
10 Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
11
12 SEV is an extension to the AMD-V architecture which supports running
13 virtual machines (VMs) under the control of a hypervisor. When enabled,
14 the memory contents of a VM will be transparently encrypted with a key
15 unique to that VM.
16
17 The hypervisor can determine the SEV support through the CPUID
18 instruction. The CPUID function 0x8000001f reports information related
19 to SEV::
20
21 0x8000001f[eax]:
22 Bit[1] indicates support for SEV
23 ...
24 [ecx]:
25 Bits[31:0] Number of encrypted guests supported simultaneously
26
27 If support for SEV is present, MSR 0xc001_0010 (MSR_AMD64_SYSCFG) and MSR 0xc001_0015
28 (MSR_K7_HWCR) can be used to determine if it can be enabled::
29
30 0xc001_0010:
31 Bit[23] 1 = memory encryption can be enabled
32 0 = memory encryption can not be enabled
33
34 0xc001_0015:
35 Bit[0] 1 = memory encryption can be enabled
36 0 = memory encryption can not be enabled
37
38 When SEV support is available, it can be enabled in a specific VM by
39 setting the SEV bit before executing VMRUN.::
40
41 VMCB[0x90]:
42 Bit[1] 1 = SEV is enabled
43 0 = SEV is disabled
44
45 SEV hardware uses ASIDs to associate a memory encryption key with a VM.
46 Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value
47 defined in the CPUID 0x8000001f[ecx] field.
48
49 The KVM_MEMORY_ENCRYPT_OP ioctl
50 ===============================
51
52 The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP, which operates on
53 the VM file descriptor. If the argument to KVM_MEMORY_ENCRYPT_OP is NULL,
54 the ioctl returns 0 if SEV is enabled and ``ENOTTY`` if it is disabled
55 (on some older versions of Linux, the ioctl tries to run normally even
56 with a NULL argument, and therefore will likely return ``EFAULT`` instead
57 of zero if SEV is enabled). If non-NULL, the argument to
58 KVM_MEMORY_ENCRYPT_OP must be a struct kvm_sev_cmd::
59
60 struct kvm_sev_cmd {
61 __u32 id;
62 __u64 data;
63 __u32 error;
64 __u32 sev_fd;
65 };
66
67
68 The ``id`` field contains the subcommand, and the ``data`` field points to
69 another struct containing arguments specific to command. The ``sev_fd``
70 should point to a file descriptor that is opened on the ``/dev/sev``
71 device, if needed (see individual commands).
72
73 On output, ``error`` is zero on success, or an error code. Error codes
74 are defined in ``<linux/psp-dev.h>``.
75
76 KVM implements the following commands to support common lifecycle events of SEV
77 guests, such as launching, running, snapshotting, migrating and decommissioning.
78
79 1. KVM_SEV_INIT2
80 ----------------
81
82 The KVM_SEV_INIT2 command is used by the hypervisor to initialize the SEV platform
83 context. In a typical workflow, this command should be the first command issued.
84
85 For this command to be accepted, either KVM_X86_SEV_VM or KVM_X86_SEV_ES_VM
86 must have been passed to the KVM_CREATE_VM ioctl. A virtual machine created
87 with those machine types in turn cannot be run until KVM_SEV_INIT2 is invoked.
88
89 Parameters: struct kvm_sev_init (in)
90
91 Returns: 0 on success, -negative on error
92
93 ::
94
95 struct kvm_sev_init {
96 __u64 vmsa_features; /* initial value of features field in VMSA */
97 __u32 flags; /* must be 0 */
98 __u16 ghcb_version; /* maximum guest GHCB version allowed */
99 __u16 pad1;
100 __u32 pad2[8];
101 };
102
103 It is an error if the hypervisor does not support any of the bits that
104 are set in ``flags`` or ``vmsa_features``. ``vmsa_features`` must be
105 0 for SEV virtual machines, as they do not have a VMSA.
106
107 ``ghcb_version`` must be 0 for SEV virtual machines, as they do not issue GHCB
108 requests. If ``ghcb_version`` is 0 for any other guest type, then the maximum
109 allowed guest GHCB protocol will default to version 2.
110
111 This command replaces the deprecated KVM_SEV_INIT and KVM_SEV_ES_INIT commands.
112 The commands did not have any parameters (the ```data``` field was unused) and
113 only work for the KVM_X86_DEFAULT_VM machine type (0).
114
115 They behave as if:
116
117 * the VM type is KVM_X86_SEV_VM for KVM_SEV_INIT, or KVM_X86_SEV_ES_VM for
118 KVM_SEV_ES_INIT
119
120 * the ``flags`` and ``vmsa_features`` fields of ``struct kvm_sev_init`` are
121 set to zero, and ``ghcb_version`` is set to 0 for KVM_SEV_INIT and 1 for
122 KVM_SEV_ES_INIT.
123
124 If the ``KVM_X86_SEV_VMSA_FEATURES`` attribute does not exist, the hypervisor only
125 supports KVM_SEV_INIT and KVM_SEV_ES_INIT. In that case, note that KVM_SEV_ES_INIT
126 might set the debug swap VMSA feature (bit 5) depending on the value of the
127 ``debug_swap`` parameter of ``kvm-amd.ko``.
128
129 2. KVM_SEV_LAUNCH_START
130 -----------------------
131
132 The KVM_SEV_LAUNCH_START command is used for creating the memory encryption
133 context. To create the encryption context, user must provide a guest policy,
134 the owner's public Diffie-Hellman (PDH) key and session information.
135
136 Parameters: struct kvm_sev_launch_start (in/out)
137
138 Returns: 0 on success, -negative on error
139
140 ::
141
142 struct kvm_sev_launch_start {
143 __u32 handle; /* if zero then firmware creates a new handle */
144 __u32 policy; /* guest's policy */
145
146 __u64 dh_uaddr; /* userspace address pointing to the guest owner's PDH key */
147 __u32 dh_len;
148
149 __u64 session_addr; /* userspace address which points to the guest session information */
150 __u32 session_len;
151 };
152
153 On success, the 'handle' field contains a new handle and on error, a negative value.
154
155 KVM_SEV_LAUNCH_START requires the ``sev_fd`` field to be valid.
156
157 For more details, see SEV spec Section 6.2.
158
159 3. KVM_SEV_LAUNCH_UPDATE_DATA
160 -----------------------------
161
162 The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also
163 calculates a measurement of the memory contents. The measurement is a signature
164 of the memory contents that can be sent to the guest owner as an attestation
165 that the memory was encrypted correctly by the firmware.
166
167 Parameters (in): struct kvm_sev_launch_update_data
168
169 Returns: 0 on success, -negative on error
170
171 ::
172
173 struct kvm_sev_launch_update {
174 __u64 uaddr; /* userspace address to be encrypted (must be 16-byte aligned) */
175 __u32 len; /* length of the data to be encrypted (must be 16-byte aligned) */
176 };
177
178 For more details, see SEV spec Section 6.3.
179
180 4. KVM_SEV_LAUNCH_MEASURE
181 -------------------------
182
183 The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the
184 data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may
185 wait to provide the guest with confidential information until it can verify the
186 measurement. Since the guest owner knows the initial contents of the guest at
187 boot, the measurement can be verified by comparing it to what the guest owner
188 expects.
189
190 If len is zero on entry, the measurement blob length is written to len and
191 uaddr is unused.
192
193 Parameters (in): struct kvm_sev_launch_measure
194
195 Returns: 0 on success, -negative on error
196
197 ::
198
199 struct kvm_sev_launch_measure {
200 __u64 uaddr; /* where to copy the measurement */
201 __u32 len; /* length of measurement blob */
202 };
203
204 For more details on the measurement verification flow, see SEV spec Section 6.4.
205
206 5. KVM_SEV_LAUNCH_FINISH
207 ------------------------
208
209 After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be
210 issued to make the guest ready for the execution.
211
212 Returns: 0 on success, -negative on error
213
214 6. KVM_SEV_GUEST_STATUS
215 -----------------------
216
217 The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a
218 SEV-enabled guest.
219
220 Parameters (out): struct kvm_sev_guest_status
221
222 Returns: 0 on success, -negative on error
223
224 ::
225
226 struct kvm_sev_guest_status {
227 __u32 handle; /* guest handle */
228 __u32 policy; /* guest policy */
229 __u8 state; /* guest state (see enum below) */
230 };
231
232 SEV guest state:
233
234 ::
235
236 enum {
237 SEV_STATE_INVALID = 0;
238 SEV_STATE_LAUNCHING, /* guest is currently being launched */
239 SEV_STATE_SECRET, /* guest is being launched and ready to accept the ciphertext data */
240 SEV_STATE_RUNNING, /* guest is fully launched and running */
241 SEV_STATE_RECEIVING, /* guest is being migrated in from another SEV machine */
242 SEV_STATE_SENDING /* guest is getting migrated out to another SEV machine */
243 };
244
245 7. KVM_SEV_DBG_DECRYPT
246 ----------------------
247
248 The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the
249 firmware to decrypt the data at the given memory region.
250
251 Parameters (in): struct kvm_sev_dbg
252
253 Returns: 0 on success, -negative on error
254
255 ::
256
257 struct kvm_sev_dbg {
258 __u64 src_uaddr; /* userspace address of data to decrypt */
259 __u64 dst_uaddr; /* userspace address of destination */
260 __u32 len; /* length of memory region to decrypt */
261 };
262
263 The command returns an error if the guest policy does not allow debugging.
264
265 8. KVM_SEV_DBG_ENCRYPT
266 ----------------------
267
268 The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the
269 firmware to encrypt the data at the given memory region.
270
271 Parameters (in): struct kvm_sev_dbg
272
273 Returns: 0 on success, -negative on error
274
275 ::
276
277 struct kvm_sev_dbg {
278 __u64 src_uaddr; /* userspace address of data to encrypt */
279 __u64 dst_uaddr; /* userspace address of destination */
280 __u32 len; /* length of memory region to encrypt */
281 };
282
283 The command returns an error if the guest policy does not allow debugging.
284
285 9. KVM_SEV_LAUNCH_SECRET
286 ------------------------
287
288 The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret
289 data after the measurement has been validated by the guest owner.
290
291 Parameters (in): struct kvm_sev_launch_secret
292
293 Returns: 0 on success, -negative on error
294
295 ::
296
297 struct kvm_sev_launch_secret {
298 __u64 hdr_uaddr; /* userspace address containing the packet header */
299 __u32 hdr_len;
300
301 __u64 guest_uaddr; /* the guest memory region where the secret should be injected */
302 __u32 guest_len;
303
304 __u64 trans_uaddr; /* the hypervisor memory region which contains the secret */
305 __u32 trans_len;
306 };
307
308 10. KVM_SEV_GET_ATTESTATION_REPORT
309 ----------------------------------
310
311 The KVM_SEV_GET_ATTESTATION_REPORT command can be used by the hypervisor to query the attestation
312 report containing the SHA-256 digest of the guest memory and VMSA passed through the KVM_SEV_LAUNCH
313 commands and signed with the PEK. The digest returned by the command should match the digest
314 used by the guest owner with the KVM_SEV_LAUNCH_MEASURE.
315
316 If len is zero on entry, the measurement blob length is written to len and
317 uaddr is unused.
318
319 Parameters (in): struct kvm_sev_attestation
320
321 Returns: 0 on success, -negative on error
322
323 ::
324
325 struct kvm_sev_attestation_report {
326 __u8 mnonce[16]; /* A random mnonce that will be placed in the report */
327
328 __u64 uaddr; /* userspace address where the report should be copied */
329 __u32 len;
330 };
331
332 11. KVM_SEV_SEND_START
333 ----------------------
334
335 The KVM_SEV_SEND_START command can be used by the hypervisor to create an
336 outgoing guest encryption context.
337
338 If session_len is zero on entry, the length of the guest session information is
339 written to session_len and all other fields are not used.
340
341 Parameters (in): struct kvm_sev_send_start
342
343 Returns: 0 on success, -negative on error
344
345 ::
346
347 struct kvm_sev_send_start {
348 __u32 policy; /* guest policy */
349
350 __u64 pdh_cert_uaddr; /* platform Diffie-Hellman certificate */
351 __u32 pdh_cert_len;
352
353 __u64 plat_certs_uaddr; /* platform certificate chain */
354 __u32 plat_certs_len;
355
356 __u64 amd_certs_uaddr; /* AMD certificate */
357 __u32 amd_certs_len;
358
359 __u64 session_uaddr; /* Guest session information */
360 __u32 session_len;
361 };
362
363 12. KVM_SEV_SEND_UPDATE_DATA
364 ----------------------------
365
366 The KVM_SEV_SEND_UPDATE_DATA command can be used by the hypervisor to encrypt the
367 outgoing guest memory region with the encryption context creating using
368 KVM_SEV_SEND_START.
369
370 If hdr_len or trans_len are zero on entry, the length of the packet header and
371 transport region are written to hdr_len and trans_len respectively, and all
372 other fields are not used.
373
374 Parameters (in): struct kvm_sev_send_update_data
375
376 Returns: 0 on success, -negative on error
377
378 ::
379
380 struct kvm_sev_launch_send_update_data {
381 __u64 hdr_uaddr; /* userspace address containing the packet header */
382 __u32 hdr_len;
383
384 __u64 guest_uaddr; /* the source memory region to be encrypted */
385 __u32 guest_len;
386
387 __u64 trans_uaddr; /* the destination memory region */
388 __u32 trans_len;
389 };
390
391 13. KVM_SEV_SEND_FINISH
392 ------------------------
393
394 After completion of the migration flow, the KVM_SEV_SEND_FINISH command can be
395 issued by the hypervisor to delete the encryption context.
396
397 Returns: 0 on success, -negative on error
398
399 14. KVM_SEV_SEND_CANCEL
400 ------------------------
401
402 After completion of SEND_START, but before SEND_FINISH, the source VMM can issue the
403 SEND_CANCEL command to stop a migration. This is necessary so that a cancelled
404 migration can restart with a new target later.
405
406 Returns: 0 on success, -negative on error
407
408 15. KVM_SEV_RECEIVE_START
409 -------------------------
410
411 The KVM_SEV_RECEIVE_START command is used for creating the memory encryption
412 context for an incoming SEV guest. To create the encryption context, the user must
413 provide a guest policy, the platform public Diffie-Hellman (PDH) key and session
414 information.
415
416 Parameters: struct kvm_sev_receive_start (in/out)
417
418 Returns: 0 on success, -negative on error
419
420 ::
421
422 struct kvm_sev_receive_start {
423 __u32 handle; /* if zero then firmware creates a new handle */
424 __u32 policy; /* guest's policy */
425
426 __u64 pdh_uaddr; /* userspace address pointing to the PDH key */
427 __u32 pdh_len;
428
429 __u64 session_uaddr; /* userspace address which points to the guest session information */
430 __u32 session_len;
431 };
432
433 On success, the 'handle' field contains a new handle and on error, a negative value.
434
435 For more details, see SEV spec Section 6.12.
436
437 16. KVM_SEV_RECEIVE_UPDATE_DATA
438 -------------------------------
439
440 The KVM_SEV_RECEIVE_UPDATE_DATA command can be used by the hypervisor to copy
441 the incoming buffers into the guest memory region with encryption context
442 created during the KVM_SEV_RECEIVE_START.
443
444 Parameters (in): struct kvm_sev_receive_update_data
445
446 Returns: 0 on success, -negative on error
447
448 ::
449
450 struct kvm_sev_launch_receive_update_data {
451 __u64 hdr_uaddr; /* userspace address containing the packet header */
452 __u32 hdr_len;
453
454 __u64 guest_uaddr; /* the destination guest memory region */
455 __u32 guest_len;
456
457 __u64 trans_uaddr; /* the incoming buffer memory region */
458 __u32 trans_len;
459 };
460
461 17. KVM_SEV_RECEIVE_FINISH
462 --------------------------
463
464 After completion of the migration flow, the KVM_SEV_RECEIVE_FINISH command can be
465 issued by the hypervisor to make the guest ready for execution.
466
467 Returns: 0 on success, -negative on error
468
469 18. KVM_SEV_SNP_LAUNCH_START
470 ----------------------------
471
472 The KVM_SNP_LAUNCH_START command is used for creating the memory encryption
473 context for the SEV-SNP guest. It must be called prior to issuing
474 KVM_SEV_SNP_LAUNCH_UPDATE or KVM_SEV_SNP_LAUNCH_FINISH;
475
476 Parameters (in): struct kvm_sev_snp_launch_start
477
478 Returns: 0 on success, -negative on error
479
480 ::
481
482 struct kvm_sev_snp_launch_start {
483 __u64 policy; /* Guest policy to use. */
484 __u8 gosvw[16]; /* Guest OS visible workarounds. */
485 __u16 flags; /* Must be zero. */
486 __u8 pad0[6];
487 __u64 pad1[4];
488 };
489
490 See SNP_LAUNCH_START in the SEV-SNP specification [snp-fw-abi]_ for further
491 details on the input parameters in ``struct kvm_sev_snp_launch_start``.
492
493 19. KVM_SEV_SNP_LAUNCH_UPDATE
494 -----------------------------
495
496 The KVM_SEV_SNP_LAUNCH_UPDATE command is used for loading userspace-provided
497 data into a guest GPA range, measuring the contents into the SNP guest context
498 created by KVM_SEV_SNP_LAUNCH_START, and then encrypting/validating that GPA
499 range so that it will be immediately readable using the encryption key
500 associated with the guest context once it is booted, after which point it can
501 attest the measurement associated with its context before unlocking any
502 secrets.
503
504 It is required that the GPA ranges initialized by this command have had the
505 KVM_MEMORY_ATTRIBUTE_PRIVATE attribute set in advance. See the documentation
506 for KVM_SET_MEMORY_ATTRIBUTES for more details on this aspect.
507
508 Upon success, this command is not guaranteed to have processed the entire
509 range requested. Instead, the ``gfn_start``, ``uaddr``, and ``len`` fields of
510 ``struct kvm_sev_snp_launch_update`` will be updated to correspond to the
511 remaining range that has yet to be processed. The caller should continue
512 calling this command until those fields indicate the entire range has been
513 processed, e.g. ``len`` is 0, ``gfn_start`` is equal to the last GFN in the
514 range plus 1, and ``uaddr`` is the last byte of the userspace-provided source
515 buffer address plus 1. In the case where ``type`` is KVM_SEV_SNP_PAGE_TYPE_ZERO,
516 ``uaddr`` will be ignored completely.
517
518 Parameters (in): struct kvm_sev_snp_launch_update
519
520 Returns: 0 on success, < 0 on error, -EAGAIN if caller should retry
521
522 ::
523
524 struct kvm_sev_snp_launch_update {
525 __u64 gfn_start; /* Guest page number to load/encrypt data into. */
526 __u64 uaddr; /* Userspace address of data to be loaded/encrypted. */
527 __u64 len; /* 4k-aligned length in bytes to copy into guest memory.*/
528 __u8 type; /* The type of the guest pages being initialized. */
529 __u8 pad0;
530 __u16 flags; /* Must be zero. */
531 __u32 pad1;
532 __u64 pad2[4];
533
534 };
535
536 where the allowed values for page_type are #define'd as::
537
538 KVM_SEV_SNP_PAGE_TYPE_NORMAL
539 KVM_SEV_SNP_PAGE_TYPE_ZERO
540 KVM_SEV_SNP_PAGE_TYPE_UNMEASURED
541 KVM_SEV_SNP_PAGE_TYPE_SECRETS
542 KVM_SEV_SNP_PAGE_TYPE_CPUID
543
544 See the SEV-SNP spec [snp-fw-abi]_ for further details on how each page type is
545 used/measured.
546
547 20. KVM_SEV_SNP_LAUNCH_FINISH
548 -----------------------------
549
550 After completion of the SNP guest launch flow, the KVM_SEV_SNP_LAUNCH_FINISH
551 command can be issued to make the guest ready for execution.
552
553 Parameters (in): struct kvm_sev_snp_launch_finish
554
555 Returns: 0 on success, -negative on error
556
557 ::
558
559 struct kvm_sev_snp_launch_finish {
560 __u64 id_block_uaddr;
561 __u64 id_auth_uaddr;
562 __u8 id_block_en;
563 __u8 auth_key_en;
564 __u8 vcek_disabled;
565 __u8 host_data[32];
566 __u8 pad0[3];
567 __u16 flags; /* Must be zero */
568 __u64 pad1[4];
569 };
570
571
572 See SNP_LAUNCH_FINISH in the SEV-SNP specification [snp-fw-abi]_ for further
573 details on the input parameters in ``struct kvm_sev_snp_launch_finish``.
574
575 Device attribute API
576 ====================
577
578 Attributes of the SEV implementation can be retrieved through the
579 ``KVM_HAS_DEVICE_ATTR`` and ``KVM_GET_DEVICE_ATTR`` ioctls on the ``/dev/kvm``
580 device node, using group ``KVM_X86_GRP_SEV``.
581
582 Currently only one attribute is implemented:
583
584 * ``KVM_X86_SEV_VMSA_FEATURES``: return the set of all bits that
585 are accepted in the ``vmsa_features`` of ``KVM_SEV_INIT2``.
586
587 Firmware Management
588 ===================
589
590 The SEV guest key management is handled by a separate processor called the AMD
591 Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure
592 key management interface to perform common hypervisor activities such as
593 encrypting bootstrap code, snapshot, migrating and debugging the guest. For more
594 information, see the SEV Key Management spec [api-spec]_
595
596 The AMD-SP firmware can be initialized either by using its own non-volatile
597 storage or the OS can manage the NV storage for the firmware using
598 parameter ``init_ex_path`` of the ``ccp`` module. If the file specified
599 by ``init_ex_path`` does not exist or is invalid, the OS will create or
600 override the file with PSP non-volatile storage.
601
602 References
603 ==========
604
605
606 See [white-paper]_, [api-spec]_, [amd-apm]_, [kvm-forum]_, and [snp-fw-abi]_
607 for more info.
608
609 .. [white-paper] https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
610 .. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf
611 .. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34)
612 .. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf
613 .. [snp-fw-abi] https://www.amd.com/system/files/TechDocs/56860.pdf
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.