1 ======================================
2 Secure Encrypted Virtualization (SEV)
3 ======================================
8 Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
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
15 The hypervisor can determine the SEV support through the CPUID
16 instruction. The CPUID function 0x8000001f reports information related
20 Bit[1] indicates support for SEV
23 Bits[31:0] Number of encrypted guests supported simultaneously
25 If support for SEV is present, MSR 0xc001_0010 (MSR_AMD64_SYSCFG) and MSR 0xc001_0015
26 (MSR_K7_HWCR) can be used to determine if it can be enabled::
29 Bit[23] 1 = memory encryption can be enabled
30 0 = memory encryption can not be enabled
33 Bit[0] 1 = memory encryption can be enabled
34 0 = memory encryption can not be enabled
36 When SEV support is available, it can be enabled in a specific VM by
37 setting the SEV bit before executing VMRUN.::
40 Bit[1] 1 = SEV is enabled
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.
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]_
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
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
60 likely return ``EFAULT``). If non-NULL, the argument to KVM_MEMORY_ENCRYPT_OP
61 must be a struct kvm_sev_cmd::
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).
76 On output, ``error`` is zero on success, or an error code. Error codes
77 are defined in ``<linux/psp-dev.h>``.
79 KVM implements the following commands to support common lifecycle events of SEV
80 guests, such as launching, running, snapshotting, migrating and decommissioning.
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.
88 The firmware can be initialized either by using its own non-volatile storage or
89 the OS can manage the NV storage for the firmware using the module parameter
90 ``init_ex_path``. The file specified by ``init_ex_path`` must exist. To create
91 a new NV storage file allocate the file with 32KB bytes of 0xFF as required by
94 Returns: 0 on success, -negative on error
96 2. KVM_SEV_LAUNCH_START
97 -----------------------
99 The KVM_SEV_LAUNCH_START command is used for creating the memory encryption
100 context. To create the encryption context, user must provide a guest policy,
101 the owner's public Diffie-Hellman (PDH) key and session information.
103 Parameters: struct kvm_sev_launch_start (in/out)
105 Returns: 0 on success, -negative on error
109 struct kvm_sev_launch_start {
110 __u32 handle; /* if zero then firmware creates a new handle */
111 __u32 policy; /* guest's policy */
113 __u64 dh_uaddr; /* userspace address pointing to the guest owner's PDH key */
116 __u64 session_addr; /* userspace address which points to the guest session information */
120 On success, the 'handle' field contains a new handle and on error, a negative value.
122 KVM_SEV_LAUNCH_START requires the ``sev_fd`` field to be valid.
124 For more details, see SEV spec Section 6.2.
126 3. KVM_SEV_LAUNCH_UPDATE_DATA
127 -----------------------------
129 The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also
130 calculates a measurement of the memory contents. The measurement is a signature
131 of the memory contents that can be sent to the guest owner as an attestation
132 that the memory was encrypted correctly by the firmware.
134 Parameters (in): struct kvm_sev_launch_update_data
136 Returns: 0 on success, -negative on error
140 struct kvm_sev_launch_update {
141 __u64 uaddr; /* userspace address to be encrypted (must be 16-byte aligned) */
142 __u32 len; /* length of the data to be encrypted (must be 16-byte aligned) */
145 For more details, see SEV spec Section 6.3.
147 4. KVM_SEV_LAUNCH_MEASURE
148 -------------------------
150 The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the
151 data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may
152 wait to provide the guest with confidential information until it can verify the
153 measurement. Since the guest owner knows the initial contents of the guest at
154 boot, the measurement can be verified by comparing it to what the guest owner
157 If len is zero on entry, the measurement blob length is written to len and
160 Parameters (in): struct kvm_sev_launch_measure
162 Returns: 0 on success, -negative on error
166 struct kvm_sev_launch_measure {
167 __u64 uaddr; /* where to copy the measurement */
168 __u32 len; /* length of measurement blob */
171 For more details on the measurement verification flow, see SEV spec Section 6.4.
173 5. KVM_SEV_LAUNCH_FINISH
174 ------------------------
176 After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be
177 issued to make the guest ready for the execution.
179 Returns: 0 on success, -negative on error
181 6. KVM_SEV_GUEST_STATUS
182 -----------------------
184 The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a
187 Parameters (out): struct kvm_sev_guest_status
189 Returns: 0 on success, -negative on error
193 struct kvm_sev_guest_status {
194 __u32 handle; /* guest handle */
195 __u32 policy; /* guest policy */
196 __u8 state; /* guest state (see enum below) */
204 SEV_STATE_INVALID = 0;
205 SEV_STATE_LAUNCHING, /* guest is currently being launched */
206 SEV_STATE_SECRET, /* guest is being launched and ready to accept the ciphertext data */
207 SEV_STATE_RUNNING, /* guest is fully launched and running */
208 SEV_STATE_RECEIVING, /* guest is being migrated in from another SEV machine */
209 SEV_STATE_SENDING /* guest is getting migrated out to another SEV machine */
212 7. KVM_SEV_DBG_DECRYPT
213 ----------------------
215 The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the
216 firmware to decrypt the data at the given memory region.
218 Parameters (in): struct kvm_sev_dbg
220 Returns: 0 on success, -negative on error
225 __u64 src_uaddr; /* userspace address of data to decrypt */
226 __u64 dst_uaddr; /* userspace address of destination */
227 __u32 len; /* length of memory region to decrypt */
230 The command returns an error if the guest policy does not allow debugging.
232 8. KVM_SEV_DBG_ENCRYPT
233 ----------------------
235 The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the
236 firmware to encrypt the data at the given memory region.
238 Parameters (in): struct kvm_sev_dbg
240 Returns: 0 on success, -negative on error
245 __u64 src_uaddr; /* userspace address of data to encrypt */
246 __u64 dst_uaddr; /* userspace address of destination */
247 __u32 len; /* length of memory region to encrypt */
250 The command returns an error if the guest policy does not allow debugging.
252 9. KVM_SEV_LAUNCH_SECRET
253 ------------------------
255 The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret
256 data after the measurement has been validated by the guest owner.
258 Parameters (in): struct kvm_sev_launch_secret
260 Returns: 0 on success, -negative on error
264 struct kvm_sev_launch_secret {
265 __u64 hdr_uaddr; /* userspace address containing the packet header */
268 __u64 guest_uaddr; /* the guest memory region where the secret should be injected */
271 __u64 trans_uaddr; /* the hypervisor memory region which contains the secret */
275 10. KVM_SEV_GET_ATTESTATION_REPORT
276 ----------------------------------
278 The KVM_SEV_GET_ATTESTATION_REPORT command can be used by the hypervisor to query the attestation
279 report containing the SHA-256 digest of the guest memory and VMSA passed through the KVM_SEV_LAUNCH
280 commands and signed with the PEK. The digest returned by the command should match the digest
281 used by the guest owner with the KVM_SEV_LAUNCH_MEASURE.
283 If len is zero on entry, the measurement blob length is written to len and
286 Parameters (in): struct kvm_sev_attestation
288 Returns: 0 on success, -negative on error
292 struct kvm_sev_attestation_report {
293 __u8 mnonce[16]; /* A random mnonce that will be placed in the report */
295 __u64 uaddr; /* userspace address where the report should be copied */
299 11. KVM_SEV_SEND_START
300 ----------------------
302 The KVM_SEV_SEND_START command can be used by the hypervisor to create an
303 outgoing guest encryption context.
305 If session_len is zero on entry, the length of the guest session information is
306 written to session_len and all other fields are not used.
308 Parameters (in): struct kvm_sev_send_start
310 Returns: 0 on success, -negative on error
314 struct kvm_sev_send_start {
315 __u32 policy; /* guest policy */
317 __u64 pdh_cert_uaddr; /* platform Diffie-Hellman certificate */
320 __u64 plat_certs_uaddr; /* platform certificate chain */
321 __u32 plat_certs_len;
323 __u64 amd_certs_uaddr; /* AMD certificate */
326 __u64 session_uaddr; /* Guest session information */
330 12. KVM_SEV_SEND_UPDATE_DATA
331 ----------------------------
333 The KVM_SEV_SEND_UPDATE_DATA command can be used by the hypervisor to encrypt the
334 outgoing guest memory region with the encryption context creating using
337 If hdr_len or trans_len are zero on entry, the length of the packet header and
338 transport region are written to hdr_len and trans_len respectively, and all
339 other fields are not used.
341 Parameters (in): struct kvm_sev_send_update_data
343 Returns: 0 on success, -negative on error
347 struct kvm_sev_launch_send_update_data {
348 __u64 hdr_uaddr; /* userspace address containing the packet header */
351 __u64 guest_uaddr; /* the source memory region to be encrypted */
354 __u64 trans_uaddr; /* the destination memory region */
358 13. KVM_SEV_SEND_FINISH
359 ------------------------
361 After completion of the migration flow, the KVM_SEV_SEND_FINISH command can be
362 issued by the hypervisor to delete the encryption context.
364 Returns: 0 on success, -negative on error
366 14. KVM_SEV_SEND_CANCEL
367 ------------------------
369 After completion of SEND_START, but before SEND_FINISH, the source VMM can issue the
370 SEND_CANCEL command to stop a migration. This is necessary so that a cancelled
371 migration can restart with a new target later.
373 Returns: 0 on success, -negative on error
375 15. KVM_SEV_RECEIVE_START
376 -------------------------
378 The KVM_SEV_RECEIVE_START command is used for creating the memory encryption
379 context for an incoming SEV guest. To create the encryption context, the user must
380 provide a guest policy, the platform public Diffie-Hellman (PDH) key and session
383 Parameters: struct kvm_sev_receive_start (in/out)
385 Returns: 0 on success, -negative on error
389 struct kvm_sev_receive_start {
390 __u32 handle; /* if zero then firmware creates a new handle */
391 __u32 policy; /* guest's policy */
393 __u64 pdh_uaddr; /* userspace address pointing to the PDH key */
396 __u64 session_uaddr; /* userspace address which points to the guest session information */
400 On success, the 'handle' field contains a new handle and on error, a negative value.
402 For more details, see SEV spec Section 6.12.
404 16. KVM_SEV_RECEIVE_UPDATE_DATA
405 -------------------------------
407 The KVM_SEV_RECEIVE_UPDATE_DATA command can be used by the hypervisor to copy
408 the incoming buffers into the guest memory region with encryption context
409 created during the KVM_SEV_RECEIVE_START.
411 Parameters (in): struct kvm_sev_receive_update_data
413 Returns: 0 on success, -negative on error
417 struct kvm_sev_launch_receive_update_data {
418 __u64 hdr_uaddr; /* userspace address containing the packet header */
421 __u64 guest_uaddr; /* the destination guest memory region */
424 __u64 trans_uaddr; /* the incoming buffer memory region */
428 17. KVM_SEV_RECEIVE_FINISH
429 --------------------------
431 After completion of the migration flow, the KVM_SEV_RECEIVE_FINISH command can be
432 issued by the hypervisor to make the guest ready for execution.
434 Returns: 0 on success, -negative on error
440 See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info.
442 .. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
443 .. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf
444 .. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34)
445 .. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf