1 .. SPDX-License-Identifier: GPL-2.0
3 ======================================
4 Secure Encrypted Virtualization (SEV)
5 ======================================
10 Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
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
17 The hypervisor can determine the SEV support through the CPUID
18 instruction. The CPUID function 0x8000001f reports information related
22 Bit[1] indicates support for SEV
25 Bits[31:0] Number of encrypted guests supported simultaneously
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::
31 Bit[23] 1 = memory encryption can be enabled
32 0 = memory encryption can not be enabled
35 Bit[0] 1 = memory encryption can be enabled
36 0 = memory encryption can not be enabled
38 When SEV support is available, it can be enabled in a specific VM by
39 setting the SEV bit before executing VMRUN.::
42 Bit[1] 1 = SEV is enabled
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.
52 The SEV guest key management is handled by a separate processor called the AMD
53 Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure
54 key management interface to perform common hypervisor activities such as
55 encrypting bootstrap code, snapshot, migrating and debugging the guest. For more
56 information, see the SEV Key Management spec [api-spec]_
58 The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP. If the argument
59 to KVM_MEMORY_ENCRYPT_OP is NULL, the ioctl returns 0 if SEV is enabled
60 and ``ENOTTY` if it is disabled (on some older versions of Linux,
61 the ioctl runs normally even with a NULL argument, and therefore will
62 likely return ``EFAULT``). If non-NULL, the argument to KVM_MEMORY_ENCRYPT_OP
63 must be a struct kvm_sev_cmd::
73 The ``id`` field contains the subcommand, and the ``data`` field points to
74 another struct containing arguments specific to command. The ``sev_fd``
75 should point to a file descriptor that is opened on the ``/dev/sev``
76 device, if needed (see individual commands).
78 On output, ``error`` is zero on success, or an error code. Error codes
79 are defined in ``<linux/psp-dev.h>``.
81 KVM implements the following commands to support common lifecycle events of SEV
82 guests, such as launching, running, snapshotting, migrating and decommissioning.
87 The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform
88 context. In a typical workflow, this command should be the first command issued.
90 The firmware can be initialized either by using its own non-volatile storage or
91 the OS can manage the NV storage for the firmware using the module parameter
92 ``init_ex_path``. If the file specified by ``init_ex_path`` does not exist or
93 is invalid, the OS will create or override the file with output from PSP.
95 Returns: 0 on success, -negative on error
97 2. KVM_SEV_LAUNCH_START
98 -----------------------
100 The KVM_SEV_LAUNCH_START command is used for creating the memory encryption
101 context. To create the encryption context, user must provide a guest policy,
102 the owner's public Diffie-Hellman (PDH) key and session information.
104 Parameters: struct kvm_sev_launch_start (in/out)
106 Returns: 0 on success, -negative on error
110 struct kvm_sev_launch_start {
111 __u32 handle; /* if zero then firmware creates a new handle */
112 __u32 policy; /* guest's policy */
114 __u64 dh_uaddr; /* userspace address pointing to the guest owner's PDH key */
117 __u64 session_addr; /* userspace address which points to the guest session information */
121 On success, the 'handle' field contains a new handle and on error, a negative value.
123 KVM_SEV_LAUNCH_START requires the ``sev_fd`` field to be valid.
125 For more details, see SEV spec Section 6.2.
127 3. KVM_SEV_LAUNCH_UPDATE_DATA
128 -----------------------------
130 The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also
131 calculates a measurement of the memory contents. The measurement is a signature
132 of the memory contents that can be sent to the guest owner as an attestation
133 that the memory was encrypted correctly by the firmware.
135 Parameters (in): struct kvm_sev_launch_update_data
137 Returns: 0 on success, -negative on error
141 struct kvm_sev_launch_update {
142 __u64 uaddr; /* userspace address to be encrypted (must be 16-byte aligned) */
143 __u32 len; /* length of the data to be encrypted (must be 16-byte aligned) */
146 For more details, see SEV spec Section 6.3.
148 4. KVM_SEV_LAUNCH_MEASURE
149 -------------------------
151 The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the
152 data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may
153 wait to provide the guest with confidential information until it can verify the
154 measurement. Since the guest owner knows the initial contents of the guest at
155 boot, the measurement can be verified by comparing it to what the guest owner
158 If len is zero on entry, the measurement blob length is written to len and
161 Parameters (in): struct kvm_sev_launch_measure
163 Returns: 0 on success, -negative on error
167 struct kvm_sev_launch_measure {
168 __u64 uaddr; /* where to copy the measurement */
169 __u32 len; /* length of measurement blob */
172 For more details on the measurement verification flow, see SEV spec Section 6.4.
174 5. KVM_SEV_LAUNCH_FINISH
175 ------------------------
177 After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be
178 issued to make the guest ready for the execution.
180 Returns: 0 on success, -negative on error
182 6. KVM_SEV_GUEST_STATUS
183 -----------------------
185 The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a
188 Parameters (out): struct kvm_sev_guest_status
190 Returns: 0 on success, -negative on error
194 struct kvm_sev_guest_status {
195 __u32 handle; /* guest handle */
196 __u32 policy; /* guest policy */
197 __u8 state; /* guest state (see enum below) */
205 SEV_STATE_INVALID = 0;
206 SEV_STATE_LAUNCHING, /* guest is currently being launched */
207 SEV_STATE_SECRET, /* guest is being launched and ready to accept the ciphertext data */
208 SEV_STATE_RUNNING, /* guest is fully launched and running */
209 SEV_STATE_RECEIVING, /* guest is being migrated in from another SEV machine */
210 SEV_STATE_SENDING /* guest is getting migrated out to another SEV machine */
213 7. KVM_SEV_DBG_DECRYPT
214 ----------------------
216 The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the
217 firmware to decrypt the data at the given memory region.
219 Parameters (in): struct kvm_sev_dbg
221 Returns: 0 on success, -negative on error
226 __u64 src_uaddr; /* userspace address of data to decrypt */
227 __u64 dst_uaddr; /* userspace address of destination */
228 __u32 len; /* length of memory region to decrypt */
231 The command returns an error if the guest policy does not allow debugging.
233 8. KVM_SEV_DBG_ENCRYPT
234 ----------------------
236 The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the
237 firmware to encrypt the data at the given memory region.
239 Parameters (in): struct kvm_sev_dbg
241 Returns: 0 on success, -negative on error
246 __u64 src_uaddr; /* userspace address of data to encrypt */
247 __u64 dst_uaddr; /* userspace address of destination */
248 __u32 len; /* length of memory region to encrypt */
251 The command returns an error if the guest policy does not allow debugging.
253 9. KVM_SEV_LAUNCH_SECRET
254 ------------------------
256 The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret
257 data after the measurement has been validated by the guest owner.
259 Parameters (in): struct kvm_sev_launch_secret
261 Returns: 0 on success, -negative on error
265 struct kvm_sev_launch_secret {
266 __u64 hdr_uaddr; /* userspace address containing the packet header */
269 __u64 guest_uaddr; /* the guest memory region where the secret should be injected */
272 __u64 trans_uaddr; /* the hypervisor memory region which contains the secret */
276 10. KVM_SEV_GET_ATTESTATION_REPORT
277 ----------------------------------
279 The KVM_SEV_GET_ATTESTATION_REPORT command can be used by the hypervisor to query the attestation
280 report containing the SHA-256 digest of the guest memory and VMSA passed through the KVM_SEV_LAUNCH
281 commands and signed with the PEK. The digest returned by the command should match the digest
282 used by the guest owner with the KVM_SEV_LAUNCH_MEASURE.
284 If len is zero on entry, the measurement blob length is written to len and
287 Parameters (in): struct kvm_sev_attestation
289 Returns: 0 on success, -negative on error
293 struct kvm_sev_attestation_report {
294 __u8 mnonce[16]; /* A random mnonce that will be placed in the report */
296 __u64 uaddr; /* userspace address where the report should be copied */
300 11. KVM_SEV_SEND_START
301 ----------------------
303 The KVM_SEV_SEND_START command can be used by the hypervisor to create an
304 outgoing guest encryption context.
306 If session_len is zero on entry, the length of the guest session information is
307 written to session_len and all other fields are not used.
309 Parameters (in): struct kvm_sev_send_start
311 Returns: 0 on success, -negative on error
315 struct kvm_sev_send_start {
316 __u32 policy; /* guest policy */
318 __u64 pdh_cert_uaddr; /* platform Diffie-Hellman certificate */
321 __u64 plat_certs_uaddr; /* platform certificate chain */
322 __u32 plat_certs_len;
324 __u64 amd_certs_uaddr; /* AMD certificate */
327 __u64 session_uaddr; /* Guest session information */
331 12. KVM_SEV_SEND_UPDATE_DATA
332 ----------------------------
334 The KVM_SEV_SEND_UPDATE_DATA command can be used by the hypervisor to encrypt the
335 outgoing guest memory region with the encryption context creating using
338 If hdr_len or trans_len are zero on entry, the length of the packet header and
339 transport region are written to hdr_len and trans_len respectively, and all
340 other fields are not used.
342 Parameters (in): struct kvm_sev_send_update_data
344 Returns: 0 on success, -negative on error
348 struct kvm_sev_launch_send_update_data {
349 __u64 hdr_uaddr; /* userspace address containing the packet header */
352 __u64 guest_uaddr; /* the source memory region to be encrypted */
355 __u64 trans_uaddr; /* the destination memory region */
359 13. KVM_SEV_SEND_FINISH
360 ------------------------
362 After completion of the migration flow, the KVM_SEV_SEND_FINISH command can be
363 issued by the hypervisor to delete the encryption context.
365 Returns: 0 on success, -negative on error
367 14. KVM_SEV_SEND_CANCEL
368 ------------------------
370 After completion of SEND_START, but before SEND_FINISH, the source VMM can issue the
371 SEND_CANCEL command to stop a migration. This is necessary so that a cancelled
372 migration can restart with a new target later.
374 Returns: 0 on success, -negative on error
376 15. KVM_SEV_RECEIVE_START
377 -------------------------
379 The KVM_SEV_RECEIVE_START command is used for creating the memory encryption
380 context for an incoming SEV guest. To create the encryption context, the user must
381 provide a guest policy, the platform public Diffie-Hellman (PDH) key and session
384 Parameters: struct kvm_sev_receive_start (in/out)
386 Returns: 0 on success, -negative on error
390 struct kvm_sev_receive_start {
391 __u32 handle; /* if zero then firmware creates a new handle */
392 __u32 policy; /* guest's policy */
394 __u64 pdh_uaddr; /* userspace address pointing to the PDH key */
397 __u64 session_uaddr; /* userspace address which points to the guest session information */
401 On success, the 'handle' field contains a new handle and on error, a negative value.
403 For more details, see SEV spec Section 6.12.
405 16. KVM_SEV_RECEIVE_UPDATE_DATA
406 -------------------------------
408 The KVM_SEV_RECEIVE_UPDATE_DATA command can be used by the hypervisor to copy
409 the incoming buffers into the guest memory region with encryption context
410 created during the KVM_SEV_RECEIVE_START.
412 Parameters (in): struct kvm_sev_receive_update_data
414 Returns: 0 on success, -negative on error
418 struct kvm_sev_launch_receive_update_data {
419 __u64 hdr_uaddr; /* userspace address containing the packet header */
422 __u64 guest_uaddr; /* the destination guest memory region */
425 __u64 trans_uaddr; /* the incoming buffer memory region */
429 17. KVM_SEV_RECEIVE_FINISH
430 --------------------------
432 After completion of the migration flow, the KVM_SEV_RECEIVE_FINISH command can be
433 issued by the hypervisor to make the guest ready for execution.
435 Returns: 0 on success, -negative on error
441 See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info.
443 .. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
444 .. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf
445 .. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34)
446 .. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf