1.. SPDX-License-Identifier: GPL-2.0 2 3====================================== 4Secure Encrypted Virtualization (SEV) 5====================================== 6 7Overview 8======== 9 10Secure Encrypted Virtualization (SEV) is a feature found on AMD processors. 11 12SEV is an extension to the AMD-V architecture which supports running 13virtual machines (VMs) under the control of a hypervisor. When enabled, 14the memory contents of a VM will be transparently encrypted with a key 15unique to that VM. 16 17The hypervisor can determine the SEV support through the CPUID 18instruction. The CPUID function 0x8000001f reports information related 19to 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 27If 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 38When SEV support is available, it can be enabled in a specific VM by 39setting the SEV bit before executing VMRUN.:: 40 41 VMCB[0x90]: 42 Bit[1] 1 = SEV is enabled 43 0 = SEV is disabled 44 45SEV hardware uses ASIDs to associate a memory encryption key with a VM. 46Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value 47defined in the CPUID 0x8000001f[ecx] field. 48 49The KVM_MEMORY_ENCRYPT_OP ioctl 50=============================== 51 52The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP, which operates on 53the VM file descriptor. If the argument to KVM_MEMORY_ENCRYPT_OP is NULL, 54the 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 56with a NULL argument, and therefore will likely return ``EFAULT`` instead 57of zero if SEV is enabled). If non-NULL, the argument to 58KVM_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 68The ``id`` field contains the subcommand, and the ``data`` field points to 69another struct containing arguments specific to command. The ``sev_fd`` 70should point to a file descriptor that is opened on the ``/dev/sev`` 71device, if needed (see individual commands). 72 73On output, ``error`` is zero on success, or an error code. Error codes 74are defined in ``<linux/psp-dev.h>``. 75 76KVM implements the following commands to support common lifecycle events of SEV 77guests, such as launching, running, snapshotting, migrating and decommissioning. 78 791. KVM_SEV_INIT2 80---------------- 81 82The KVM_SEV_INIT2 command is used by the hypervisor to initialize the SEV platform 83context. In a typical workflow, this command should be the first command issued. 84 85For this command to be accepted, either KVM_X86_SEV_VM or KVM_X86_SEV_ES_VM 86must have been passed to the KVM_CREATE_VM ioctl. A virtual machine created 87with those machine types in turn cannot be run until KVM_SEV_INIT2 is invoked. 88 89Parameters: struct kvm_sev_init (in) 90 91Returns: 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 103It is an error if the hypervisor does not support any of the bits that 104are set in ``flags`` or ``vmsa_features``. ``vmsa_features`` must be 1050 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 108requests. If ``ghcb_version`` is 0 for any other guest type, then the maximum 109allowed guest GHCB protocol will default to version 2. 110 111This command replaces the deprecated KVM_SEV_INIT and KVM_SEV_ES_INIT commands. 112The commands did not have any parameters (the ```data``` field was unused) and 113only work for the KVM_X86_DEFAULT_VM machine type (0). 114 115They 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 124If the ``KVM_X86_SEV_VMSA_FEATURES`` attribute does not exist, the hypervisor only 125supports KVM_SEV_INIT and KVM_SEV_ES_INIT. In that case, note that KVM_SEV_ES_INIT 126might set the debug swap VMSA feature (bit 5) depending on the value of the 127``debug_swap`` parameter of ``kvm-amd.ko``. 128 1292. KVM_SEV_LAUNCH_START 130----------------------- 131 132The KVM_SEV_LAUNCH_START command is used for creating the memory encryption 133context. To create the encryption context, user must provide a guest policy, 134the owner's public Diffie-Hellman (PDH) key and session information. 135 136Parameters: struct kvm_sev_launch_start (in/out) 137 138Returns: 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 153On success, the 'handle' field contains a new handle and on error, a negative value. 154 155KVM_SEV_LAUNCH_START requires the ``sev_fd`` field to be valid. 156 157For more details, see SEV spec Section 6.2. 158 1593. KVM_SEV_LAUNCH_UPDATE_DATA 160----------------------------- 161 162The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also 163calculates a measurement of the memory contents. The measurement is a signature 164of the memory contents that can be sent to the guest owner as an attestation 165that the memory was encrypted correctly by the firmware. 166 167Parameters (in): struct kvm_sev_launch_update_data 168 169Returns: 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 178For more details, see SEV spec Section 6.3. 179 1804. KVM_SEV_LAUNCH_MEASURE 181------------------------- 182 183The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the 184data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may 185wait to provide the guest with confidential information until it can verify the 186measurement. Since the guest owner knows the initial contents of the guest at 187boot, the measurement can be verified by comparing it to what the guest owner 188expects. 189 190If len is zero on entry, the measurement blob length is written to len and 191uaddr is unused. 192 193Parameters (in): struct kvm_sev_launch_measure 194 195Returns: 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 204For more details on the measurement verification flow, see SEV spec Section 6.4. 205 2065. KVM_SEV_LAUNCH_FINISH 207------------------------ 208 209After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be 210issued to make the guest ready for the execution. 211 212Returns: 0 on success, -negative on error 213 2146. KVM_SEV_GUEST_STATUS 215----------------------- 216 217The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a 218SEV-enabled guest. 219 220Parameters (out): struct kvm_sev_guest_status 221 222Returns: 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 232SEV 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 2457. KVM_SEV_DBG_DECRYPT 246---------------------- 247 248The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the 249firmware to decrypt the data at the given memory region. 250 251Parameters (in): struct kvm_sev_dbg 252 253Returns: 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 263The command returns an error if the guest policy does not allow debugging. 264 2658. KVM_SEV_DBG_ENCRYPT 266---------------------- 267 268The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the 269firmware to encrypt the data at the given memory region. 270 271Parameters (in): struct kvm_sev_dbg 272 273Returns: 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 283The command returns an error if the guest policy does not allow debugging. 284 2859. KVM_SEV_LAUNCH_SECRET 286------------------------ 287 288The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret 289data after the measurement has been validated by the guest owner. 290 291Parameters (in): struct kvm_sev_launch_secret 292 293Returns: 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 30810. KVM_SEV_GET_ATTESTATION_REPORT 309---------------------------------- 310 311The KVM_SEV_GET_ATTESTATION_REPORT command can be used by the hypervisor to query the attestation 312report containing the SHA-256 digest of the guest memory and VMSA passed through the KVM_SEV_LAUNCH 313commands and signed with the PEK. The digest returned by the command should match the digest 314used by the guest owner with the KVM_SEV_LAUNCH_MEASURE. 315 316If len is zero on entry, the measurement blob length is written to len and 317uaddr is unused. 318 319Parameters (in): struct kvm_sev_attestation 320 321Returns: 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 33211. KVM_SEV_SEND_START 333---------------------- 334 335The KVM_SEV_SEND_START command can be used by the hypervisor to create an 336outgoing guest encryption context. 337 338If session_len is zero on entry, the length of the guest session information is 339written to session_len and all other fields are not used. 340 341Parameters (in): struct kvm_sev_send_start 342 343Returns: 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 36312. KVM_SEV_SEND_UPDATE_DATA 364---------------------------- 365 366The KVM_SEV_SEND_UPDATE_DATA command can be used by the hypervisor to encrypt the 367outgoing guest memory region with the encryption context creating using 368KVM_SEV_SEND_START. 369 370If hdr_len or trans_len are zero on entry, the length of the packet header and 371transport region are written to hdr_len and trans_len respectively, and all 372other fields are not used. 373 374Parameters (in): struct kvm_sev_send_update_data 375 376Returns: 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 39113. KVM_SEV_SEND_FINISH 392------------------------ 393 394After completion of the migration flow, the KVM_SEV_SEND_FINISH command can be 395issued by the hypervisor to delete the encryption context. 396 397Returns: 0 on success, -negative on error 398 39914. KVM_SEV_SEND_CANCEL 400------------------------ 401 402After completion of SEND_START, but before SEND_FINISH, the source VMM can issue the 403SEND_CANCEL command to stop a migration. This is necessary so that a cancelled 404migration can restart with a new target later. 405 406Returns: 0 on success, -negative on error 407 40815. KVM_SEV_RECEIVE_START 409------------------------- 410 411The KVM_SEV_RECEIVE_START command is used for creating the memory encryption 412context for an incoming SEV guest. To create the encryption context, the user must 413provide a guest policy, the platform public Diffie-Hellman (PDH) key and session 414information. 415 416Parameters: struct kvm_sev_receive_start (in/out) 417 418Returns: 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 433On success, the 'handle' field contains a new handle and on error, a negative value. 434 435For more details, see SEV spec Section 6.12. 436 43716. KVM_SEV_RECEIVE_UPDATE_DATA 438------------------------------- 439 440The KVM_SEV_RECEIVE_UPDATE_DATA command can be used by the hypervisor to copy 441the incoming buffers into the guest memory region with encryption context 442created during the KVM_SEV_RECEIVE_START. 443 444Parameters (in): struct kvm_sev_receive_update_data 445 446Returns: 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 46117. KVM_SEV_RECEIVE_FINISH 462-------------------------- 463 464After completion of the migration flow, the KVM_SEV_RECEIVE_FINISH command can be 465issued by the hypervisor to make the guest ready for execution. 466 467Returns: 0 on success, -negative on error 468 46918. KVM_SEV_SNP_LAUNCH_START 470---------------------------- 471 472The KVM_SNP_LAUNCH_START command is used for creating the memory encryption 473context for the SEV-SNP guest. It must be called prior to issuing 474KVM_SEV_SNP_LAUNCH_UPDATE or KVM_SEV_SNP_LAUNCH_FINISH; 475 476Parameters (in): struct kvm_sev_snp_launch_start 477 478Returns: 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 490See SNP_LAUNCH_START in the SEV-SNP specification [snp-fw-abi]_ for further 491details on the input parameters in ``struct kvm_sev_snp_launch_start``. 492 49319. KVM_SEV_SNP_LAUNCH_UPDATE 494----------------------------- 495 496The KVM_SEV_SNP_LAUNCH_UPDATE command is used for loading userspace-provided 497data into a guest GPA range, measuring the contents into the SNP guest context 498created by KVM_SEV_SNP_LAUNCH_START, and then encrypting/validating that GPA 499range so that it will be immediately readable using the encryption key 500associated with the guest context once it is booted, after which point it can 501attest the measurement associated with its context before unlocking any 502secrets. 503 504It is required that the GPA ranges initialized by this command have had the 505KVM_MEMORY_ATTRIBUTE_PRIVATE attribute set in advance. See the documentation 506for KVM_SET_MEMORY_ATTRIBUTES for more details on this aspect. 507 508Upon success, this command is not guaranteed to have processed the entire 509range requested. Instead, the ``gfn_start``, ``uaddr``, and ``len`` fields of 510``struct kvm_sev_snp_launch_update`` will be updated to correspond to the 511remaining range that has yet to be processed. The caller should continue 512calling this command until those fields indicate the entire range has been 513processed, e.g. ``len`` is 0, ``gfn_start`` is equal to the last GFN in the 514range plus 1, and ``uaddr`` is the last byte of the userspace-provided source 515buffer address plus 1. In the case where ``type`` is KVM_SEV_SNP_PAGE_TYPE_ZERO, 516``uaddr`` will be ignored completely. 517 518Parameters (in): struct kvm_sev_snp_launch_update 519 520Returns: 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 536where 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 544See the SEV-SNP spec [snp-fw-abi]_ for further details on how each page type is 545used/measured. 546 54720. KVM_SEV_SNP_LAUNCH_FINISH 548----------------------------- 549 550After completion of the SNP guest launch flow, the KVM_SEV_SNP_LAUNCH_FINISH 551command can be issued to make the guest ready for execution. 552 553Parameters (in): struct kvm_sev_snp_launch_finish 554 555Returns: 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 572See SNP_LAUNCH_FINISH in the SEV-SNP specification [snp-fw-abi]_ for further 573details on the input parameters in ``struct kvm_sev_snp_launch_finish``. 574 575Device attribute API 576==================== 577 578Attributes of the SEV implementation can be retrieved through the 579``KVM_HAS_DEVICE_ATTR`` and ``KVM_GET_DEVICE_ATTR`` ioctls on the ``/dev/kvm`` 580device node, using group ``KVM_X86_GRP_SEV``. 581 582Currently 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 587Firmware Management 588=================== 589 590The SEV guest key management is handled by a separate processor called the AMD 591Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure 592key management interface to perform common hypervisor activities such as 593encrypting bootstrap code, snapshot, migrating and debugging the guest. For more 594information, see the SEV Key Management spec [api-spec]_ 595 596The AMD-SP firmware can be initialized either by using its own non-volatile 597storage or the OS can manage the NV storage for the firmware using 598parameter ``init_ex_path`` of the ``ccp`` module. If the file specified 599by ``init_ex_path`` does not exist or is invalid, the OS will create or 600override the file with PSP non-volatile storage. 601 602References 603========== 604 605 606See [white-paper]_, [api-spec]_, [amd-apm]_, [kvm-forum]_, and [snp-fw-abi]_ 607for 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 614