| 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; /* 4k-aligned 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 |
21. KVM_SEV_SNP_ENABLE_REQ_CERTS |
| 576 |
-------------------------------- |
| 577 |
|
| 578 |
The KVM_SEV_SNP_ENABLE_REQ_CERTS command will configure KVM to exit to |
| 579 |
userspace with a ``KVM_EXIT_SNP_REQ_CERTS`` exit type as part of handling |
| 580 |
a guest attestation report, which will to allow userspace to provide a |
| 581 |
certificate corresponding to the endorsement key used by firmware to sign |
| 582 |
that attestation report. |
| 583 |
|
| 584 |
Returns: 0 on success, -negative on error |
| 585 |
|
| 586 |
NOTE: The endorsement key used by firmware may change as a result of |
| 587 |
management activities like updating SEV-SNP firmware or loading new |
| 588 |
endorsement keys, so some care should be taken to keep the returned |
| 589 |
certificate data in sync with the actual endorsement key in use by |
| 590 |
firmware at the time the attestation request is sent to SNP firmware. The |
| 591 |
recommended scheme to do this is to use file locking (e.g. via fcntl()'s |
| 592 |
F_OFD_SETLK) in the following manner: |
| 593 |
|
| 594 |
- Prior to obtaining/providing certificate data as part of servicing an |
| 595 |
exit type of ``KVM_EXIT_SNP_REQ_CERTS``, the VMM should obtain a |
| 596 |
shared/read or exclusive/write lock on the certificate blob file before |
| 597 |
reading it and returning it to KVM, and continue to hold the lock until |
| 598 |
the attestation request is actually sent to firmware. To facilitate |
| 599 |
this, the VMM can set the ``immediate_exit`` flag of kvm_run just after |
| 600 |
supplying the certificate data, and just before resuming the vCPU. |
| 601 |
This will ensure the vCPU will exit again to userspace with ``-EINTR`` |
| 602 |
after it finishes fetching the attestation request from firmware, at |
| 603 |
which point the VMM can safely drop the file lock. |
| 604 |
|
| 605 |
- Tools/libraries that perform updates to SNP firmware TCB values or |
| 606 |
endorsement keys (e.g. via /dev/sev interfaces such as ``SNP_COMMIT``, |
| 607 |
``SNP_SET_CONFIG``, or ``SNP_VLEK_LOAD``, see |
| 608 |
Documentation/virt/coco/sev-guest.rst for more details) in such a way |
| 609 |
that the certificate blob needs to be updated, should similarly take an |
| 610 |
exclusive lock on the certificate blob for the duration of any updates |
| 611 |
to endorsement keys or the certificate blob contents to ensure that |
| 612 |
VMMs using the above scheme will not return certificate blob data that |
| 613 |
is out of sync with the endorsement key used by firmware at the time |
| 614 |
the attestation request is actually issued. |
| 615 |
|
| 616 |
This scheme is recommended so that tools can use a fairly generic/natural |
| 617 |
approach to synchronizing firmware/certificate updates via file-locking, |
| 618 |
which should make it easier to maintain interoperability across |
| 619 |
tools/VMMs/vendors. |
| 620 |
|
| 621 |
Device attribute API |
| 622 |
==================== |
| 623 |
|
| 624 |
Attributes of the SEV implementation can be retrieved through the |
| 625 |
``KVM_HAS_DEVICE_ATTR`` and ``KVM_GET_DEVICE_ATTR`` ioctls on the ``/dev/kvm`` |
| 626 |
device node, using group ``KVM_X86_GRP_SEV``. |
| 627 |
|
| 628 |
The following attributes are currently implemented: |
| 629 |
|
| 630 |
* ``KVM_X86_SEV_VMSA_FEATURES``: return the set of all bits that |
| 631 |
are accepted in the ``vmsa_features`` of ``KVM_SEV_INIT2``. |
| 632 |
|
| 633 |
* ``KVM_X86_SEV_SNP_REQ_CERTS``: return a value of 1 if the kernel supports the |
| 634 |
``KVM_EXIT_SNP_REQ_CERTS`` exit, which allows for fetching endorsement key |
| 635 |
certificates from userspace for each SNP attestation request the guest issues. |
| 636 |
|
| 637 |
Firmware Management |
| 638 |
=================== |
| 639 |
|
| 640 |
The SEV guest key management is handled by a separate processor called the AMD |
| 641 |
Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure |
| 642 |
key management interface to perform common hypervisor activities such as |
| 643 |
encrypting bootstrap code, snapshot, migrating and debugging the guest. For more |
| 644 |
information, see the SEV Key Management spec [api-spec]_ |
| 645 |
|
| 646 |
The AMD-SP firmware can be initialized either by using its own non-volatile |
| 647 |
storage or the OS can manage the NV storage for the firmware using |
| 648 |
parameter ``init_ex_path`` of the ``ccp`` module. If the file specified |
| 649 |
by ``init_ex_path`` does not exist or is invalid, the OS will create or |
| 650 |
override the file with PSP non-volatile storage. |
| 651 |
|
| 652 |
References |
| 653 |
========== |
| 654 |
|
| 655 |
|
| 656 |
See [white-paper]_, [api-spec]_, [amd-apm]_, [kvm-forum]_, and [snp-fw-abi]_ |
| 657 |
for more info. |
| 658 |
|
| 659 |
.. [white-paper] https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf |
| 660 |
.. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf |
| 661 |
.. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34) |
| 662 |
.. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf |
| 663 |
.. [snp-fw-abi] https://www.amd.com/system/files/TechDocs/56860.pdf |