1af105c9cSLike Xu.. SPDX-License-Identifier: GPL-2.0 2af105c9cSLike Xu 3daec8d40SPaolo Bonzini====================================== 4daec8d40SPaolo BonziniSecure Encrypted Virtualization (SEV) 5daec8d40SPaolo Bonzini====================================== 6daec8d40SPaolo Bonzini 7daec8d40SPaolo BonziniOverview 8daec8d40SPaolo Bonzini======== 9daec8d40SPaolo Bonzini 10daec8d40SPaolo BonziniSecure Encrypted Virtualization (SEV) is a feature found on AMD processors. 11daec8d40SPaolo Bonzini 12daec8d40SPaolo BonziniSEV is an extension to the AMD-V architecture which supports running 13daec8d40SPaolo Bonzinivirtual machines (VMs) under the control of a hypervisor. When enabled, 14daec8d40SPaolo Bonzinithe memory contents of a VM will be transparently encrypted with a key 15daec8d40SPaolo Bonziniunique to that VM. 16daec8d40SPaolo Bonzini 17daec8d40SPaolo BonziniThe hypervisor can determine the SEV support through the CPUID 18daec8d40SPaolo Bonziniinstruction. The CPUID function 0x8000001f reports information related 19daec8d40SPaolo Bonzinito SEV:: 20daec8d40SPaolo Bonzini 21daec8d40SPaolo Bonzini 0x8000001f[eax]: 22daec8d40SPaolo Bonzini Bit[1] indicates support for SEV 23daec8d40SPaolo Bonzini ... 24daec8d40SPaolo Bonzini [ecx]: 25daec8d40SPaolo Bonzini Bits[31:0] Number of encrypted guests supported simultaneously 26daec8d40SPaolo Bonzini 27daec8d40SPaolo BonziniIf support for SEV is present, MSR 0xc001_0010 (MSR_AMD64_SYSCFG) and MSR 0xc001_0015 28daec8d40SPaolo Bonzini(MSR_K7_HWCR) can be used to determine if it can be enabled:: 29daec8d40SPaolo Bonzini 30daec8d40SPaolo Bonzini 0xc001_0010: 31daec8d40SPaolo Bonzini Bit[23] 1 = memory encryption can be enabled 32daec8d40SPaolo Bonzini 0 = memory encryption can not be enabled 33daec8d40SPaolo Bonzini 34daec8d40SPaolo Bonzini 0xc001_0015: 35daec8d40SPaolo Bonzini Bit[0] 1 = memory encryption can be enabled 36daec8d40SPaolo Bonzini 0 = memory encryption can not be enabled 37daec8d40SPaolo Bonzini 38daec8d40SPaolo BonziniWhen SEV support is available, it can be enabled in a specific VM by 39daec8d40SPaolo Bonzinisetting the SEV bit before executing VMRUN.:: 40daec8d40SPaolo Bonzini 41daec8d40SPaolo Bonzini VMCB[0x90]: 42daec8d40SPaolo Bonzini Bit[1] 1 = SEV is enabled 43daec8d40SPaolo Bonzini 0 = SEV is disabled 44daec8d40SPaolo Bonzini 45daec8d40SPaolo BonziniSEV hardware uses ASIDs to associate a memory encryption key with a VM. 46daec8d40SPaolo BonziniHence, the ASID for the SEV-enabled guests must be from 1 to a maximum value 47daec8d40SPaolo Bonzinidefined in the CPUID 0x8000001f[ecx] field. 48daec8d40SPaolo Bonzini 4919cebbabSPaolo BonziniThe KVM_MEMORY_ENCRYPT_OP ioctl 5019cebbabSPaolo Bonzini=============================== 51daec8d40SPaolo Bonzini 52c20722c4SPaolo BonziniThe main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP, which operates on 53c20722c4SPaolo Bonzinithe VM file descriptor. If the argument to KVM_MEMORY_ENCRYPT_OP is NULL, 54c20722c4SPaolo Bonzinithe ioctl returns 0 if SEV is enabled and ``ENOTTY`` if it is disabled 55c20722c4SPaolo Bonzini(on some older versions of Linux, the ioctl tries to run normally even 56c20722c4SPaolo Bonziniwith a NULL argument, and therefore will likely return ``EFAULT`` instead 57c20722c4SPaolo Bonziniof zero if SEV is enabled). If non-NULL, the argument to 58c20722c4SPaolo BonziniKVM_MEMORY_ENCRYPT_OP must be a struct kvm_sev_cmd:: 59daec8d40SPaolo Bonzini 60daec8d40SPaolo Bonzini struct kvm_sev_cmd { 61daec8d40SPaolo Bonzini __u32 id; 62daec8d40SPaolo Bonzini __u64 data; 63daec8d40SPaolo Bonzini __u32 error; 64daec8d40SPaolo Bonzini __u32 sev_fd; 65daec8d40SPaolo Bonzini }; 66daec8d40SPaolo Bonzini 67daec8d40SPaolo Bonzini 68daec8d40SPaolo BonziniThe ``id`` field contains the subcommand, and the ``data`` field points to 69daec8d40SPaolo Bonzinianother struct containing arguments specific to command. The ``sev_fd`` 70daec8d40SPaolo Bonzinishould point to a file descriptor that is opened on the ``/dev/sev`` 71daec8d40SPaolo Bonzinidevice, if needed (see individual commands). 72daec8d40SPaolo Bonzini 73daec8d40SPaolo BonziniOn output, ``error`` is zero on success, or an error code. Error codes 74daec8d40SPaolo Bonziniare defined in ``<linux/psp-dev.h>``. 75daec8d40SPaolo Bonzini 76daec8d40SPaolo BonziniKVM implements the following commands to support common lifecycle events of SEV 77daec8d40SPaolo Bonziniguests, such as launching, running, snapshotting, migrating and decommissioning. 78daec8d40SPaolo Bonzini 794f5defaeSPaolo Bonzini1. KVM_SEV_INIT2 804f5defaeSPaolo Bonzini---------------- 81daec8d40SPaolo Bonzini 824f5defaeSPaolo BonziniThe KVM_SEV_INIT2 command is used by the hypervisor to initialize the SEV platform 83daec8d40SPaolo Bonzinicontext. In a typical workflow, this command should be the first command issued. 84daec8d40SPaolo Bonzini 854f5defaeSPaolo BonziniFor this command to be accepted, either KVM_X86_SEV_VM or KVM_X86_SEV_ES_VM 864f5defaeSPaolo Bonzinimust have been passed to the KVM_CREATE_VM ioctl. A virtual machine created 874f5defaeSPaolo Bonziniwith those machine types in turn cannot be run until KVM_SEV_INIT2 is invoked. 884f5defaeSPaolo Bonzini 894f5defaeSPaolo BonziniParameters: struct kvm_sev_init (in) 90daec8d40SPaolo Bonzini 91daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 92daec8d40SPaolo Bonzini 934f5defaeSPaolo Bonzini:: 944f5defaeSPaolo Bonzini 954f5defaeSPaolo Bonzini struct kvm_sev_init { 964f5defaeSPaolo Bonzini __u64 vmsa_features; /* initial value of features field in VMSA */ 974f5defaeSPaolo Bonzini __u32 flags; /* must be 0 */ 98*4af663c2SMichael Roth __u16 ghcb_version; /* maximum guest GHCB version allowed */ 99*4af663c2SMichael Roth __u16 pad1; 100*4af663c2SMichael Roth __u32 pad2[8]; 1014f5defaeSPaolo Bonzini }; 1024f5defaeSPaolo Bonzini 1034f5defaeSPaolo BonziniIt is an error if the hypervisor does not support any of the bits that 1044f5defaeSPaolo Bonziniare set in ``flags`` or ``vmsa_features``. ``vmsa_features`` must be 1054f5defaeSPaolo Bonzini0 for SEV virtual machines, as they do not have a VMSA. 1064f5defaeSPaolo Bonzini 107*4af663c2SMichael Roth``ghcb_version`` must be 0 for SEV virtual machines, as they do not issue GHCB 108*4af663c2SMichael Rothrequests. If ``ghcb_version`` is 0 for any other guest type, then the maximum 109*4af663c2SMichael Rothallowed guest GHCB protocol will default to version 2. 110*4af663c2SMichael Roth 1114f5defaeSPaolo BonziniThis command replaces the deprecated KVM_SEV_INIT and KVM_SEV_ES_INIT commands. 1124f5defaeSPaolo BonziniThe commands did not have any parameters (the ```data``` field was unused) and 1134f5defaeSPaolo Bonzinionly work for the KVM_X86_DEFAULT_VM machine type (0). 1144f5defaeSPaolo Bonzini 1154f5defaeSPaolo BonziniThey behave as if: 1164f5defaeSPaolo Bonzini 1174f5defaeSPaolo Bonzini* the VM type is KVM_X86_SEV_VM for KVM_SEV_INIT, or KVM_X86_SEV_ES_VM for 1184f5defaeSPaolo Bonzini KVM_SEV_ES_INIT 1194f5defaeSPaolo Bonzini 1204f5defaeSPaolo Bonzini* the ``flags`` and ``vmsa_features`` fields of ``struct kvm_sev_init`` are 121*4af663c2SMichael Roth set to zero, and ``ghcb_version`` is set to 0 for KVM_SEV_INIT and 1 for 122*4af663c2SMichael Roth KVM_SEV_ES_INIT. 1234f5defaeSPaolo Bonzini 1244f5defaeSPaolo BonziniIf the ``KVM_X86_SEV_VMSA_FEATURES`` attribute does not exist, the hypervisor only 1254f5defaeSPaolo Bonzinisupports KVM_SEV_INIT and KVM_SEV_ES_INIT. In that case, note that KVM_SEV_ES_INIT 1264f5defaeSPaolo Bonzinimight set the debug swap VMSA feature (bit 5) depending on the value of the 1274f5defaeSPaolo Bonzini``debug_swap`` parameter of ``kvm-amd.ko``. 1284f5defaeSPaolo Bonzini 129daec8d40SPaolo Bonzini2. KVM_SEV_LAUNCH_START 130daec8d40SPaolo Bonzini----------------------- 131daec8d40SPaolo Bonzini 132daec8d40SPaolo BonziniThe KVM_SEV_LAUNCH_START command is used for creating the memory encryption 133daec8d40SPaolo Bonzinicontext. To create the encryption context, user must provide a guest policy, 134daec8d40SPaolo Bonzinithe owner's public Diffie-Hellman (PDH) key and session information. 135daec8d40SPaolo Bonzini 136daec8d40SPaolo BonziniParameters: struct kvm_sev_launch_start (in/out) 137daec8d40SPaolo Bonzini 138daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 139daec8d40SPaolo Bonzini 140daec8d40SPaolo Bonzini:: 141daec8d40SPaolo Bonzini 142daec8d40SPaolo Bonzini struct kvm_sev_launch_start { 143daec8d40SPaolo Bonzini __u32 handle; /* if zero then firmware creates a new handle */ 144daec8d40SPaolo Bonzini __u32 policy; /* guest's policy */ 145daec8d40SPaolo Bonzini 146daec8d40SPaolo Bonzini __u64 dh_uaddr; /* userspace address pointing to the guest owner's PDH key */ 147daec8d40SPaolo Bonzini __u32 dh_len; 148daec8d40SPaolo Bonzini 149daec8d40SPaolo Bonzini __u64 session_addr; /* userspace address which points to the guest session information */ 150daec8d40SPaolo Bonzini __u32 session_len; 151daec8d40SPaolo Bonzini }; 152daec8d40SPaolo Bonzini 153daec8d40SPaolo BonziniOn success, the 'handle' field contains a new handle and on error, a negative value. 154daec8d40SPaolo Bonzini 155daec8d40SPaolo BonziniKVM_SEV_LAUNCH_START requires the ``sev_fd`` field to be valid. 156daec8d40SPaolo Bonzini 157daec8d40SPaolo BonziniFor more details, see SEV spec Section 6.2. 158daec8d40SPaolo Bonzini 159daec8d40SPaolo Bonzini3. KVM_SEV_LAUNCH_UPDATE_DATA 160daec8d40SPaolo Bonzini----------------------------- 161daec8d40SPaolo Bonzini 162daec8d40SPaolo BonziniThe KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also 163daec8d40SPaolo Bonzinicalculates a measurement of the memory contents. The measurement is a signature 164daec8d40SPaolo Bonziniof the memory contents that can be sent to the guest owner as an attestation 165daec8d40SPaolo Bonzinithat the memory was encrypted correctly by the firmware. 166daec8d40SPaolo Bonzini 167daec8d40SPaolo BonziniParameters (in): struct kvm_sev_launch_update_data 168daec8d40SPaolo Bonzini 169daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 170daec8d40SPaolo Bonzini 171daec8d40SPaolo Bonzini:: 172daec8d40SPaolo Bonzini 173daec8d40SPaolo Bonzini struct kvm_sev_launch_update { 174daec8d40SPaolo Bonzini __u64 uaddr; /* userspace address to be encrypted (must be 16-byte aligned) */ 175daec8d40SPaolo Bonzini __u32 len; /* length of the data to be encrypted (must be 16-byte aligned) */ 176daec8d40SPaolo Bonzini }; 177daec8d40SPaolo Bonzini 178daec8d40SPaolo BonziniFor more details, see SEV spec Section 6.3. 179daec8d40SPaolo Bonzini 180daec8d40SPaolo Bonzini4. KVM_SEV_LAUNCH_MEASURE 181daec8d40SPaolo Bonzini------------------------- 182daec8d40SPaolo Bonzini 183daec8d40SPaolo BonziniThe KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the 184daec8d40SPaolo Bonzinidata encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may 185daec8d40SPaolo Bonziniwait to provide the guest with confidential information until it can verify the 186daec8d40SPaolo Bonzinimeasurement. Since the guest owner knows the initial contents of the guest at 187daec8d40SPaolo Bonziniboot, the measurement can be verified by comparing it to what the guest owner 188daec8d40SPaolo Bonziniexpects. 189daec8d40SPaolo Bonzini 190daec8d40SPaolo BonziniIf len is zero on entry, the measurement blob length is written to len and 191daec8d40SPaolo Bonziniuaddr is unused. 192daec8d40SPaolo Bonzini 193daec8d40SPaolo BonziniParameters (in): struct kvm_sev_launch_measure 194daec8d40SPaolo Bonzini 195daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 196daec8d40SPaolo Bonzini 197daec8d40SPaolo Bonzini:: 198daec8d40SPaolo Bonzini 199daec8d40SPaolo Bonzini struct kvm_sev_launch_measure { 200daec8d40SPaolo Bonzini __u64 uaddr; /* where to copy the measurement */ 201daec8d40SPaolo Bonzini __u32 len; /* length of measurement blob */ 202daec8d40SPaolo Bonzini }; 203daec8d40SPaolo Bonzini 204daec8d40SPaolo BonziniFor more details on the measurement verification flow, see SEV spec Section 6.4. 205daec8d40SPaolo Bonzini 206daec8d40SPaolo Bonzini5. KVM_SEV_LAUNCH_FINISH 207daec8d40SPaolo Bonzini------------------------ 208daec8d40SPaolo Bonzini 209daec8d40SPaolo BonziniAfter completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be 210daec8d40SPaolo Bonziniissued to make the guest ready for the execution. 211daec8d40SPaolo Bonzini 212daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 213daec8d40SPaolo Bonzini 214daec8d40SPaolo Bonzini6. KVM_SEV_GUEST_STATUS 215daec8d40SPaolo Bonzini----------------------- 216daec8d40SPaolo Bonzini 217daec8d40SPaolo BonziniThe KVM_SEV_GUEST_STATUS command is used to retrieve status information about a 218daec8d40SPaolo BonziniSEV-enabled guest. 219daec8d40SPaolo Bonzini 220daec8d40SPaolo BonziniParameters (out): struct kvm_sev_guest_status 221daec8d40SPaolo Bonzini 222daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 223daec8d40SPaolo Bonzini 224daec8d40SPaolo Bonzini:: 225daec8d40SPaolo Bonzini 226daec8d40SPaolo Bonzini struct kvm_sev_guest_status { 227daec8d40SPaolo Bonzini __u32 handle; /* guest handle */ 228daec8d40SPaolo Bonzini __u32 policy; /* guest policy */ 229daec8d40SPaolo Bonzini __u8 state; /* guest state (see enum below) */ 230daec8d40SPaolo Bonzini }; 231daec8d40SPaolo Bonzini 232daec8d40SPaolo BonziniSEV guest state: 233daec8d40SPaolo Bonzini 234daec8d40SPaolo Bonzini:: 235daec8d40SPaolo Bonzini 236daec8d40SPaolo Bonzini enum { 237daec8d40SPaolo Bonzini SEV_STATE_INVALID = 0; 238daec8d40SPaolo Bonzini SEV_STATE_LAUNCHING, /* guest is currently being launched */ 239daec8d40SPaolo Bonzini SEV_STATE_SECRET, /* guest is being launched and ready to accept the ciphertext data */ 240daec8d40SPaolo Bonzini SEV_STATE_RUNNING, /* guest is fully launched and running */ 241daec8d40SPaolo Bonzini SEV_STATE_RECEIVING, /* guest is being migrated in from another SEV machine */ 242daec8d40SPaolo Bonzini SEV_STATE_SENDING /* guest is getting migrated out to another SEV machine */ 243daec8d40SPaolo Bonzini }; 244daec8d40SPaolo Bonzini 245daec8d40SPaolo Bonzini7. KVM_SEV_DBG_DECRYPT 246daec8d40SPaolo Bonzini---------------------- 247daec8d40SPaolo Bonzini 248daec8d40SPaolo BonziniThe KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the 249daec8d40SPaolo Bonzinifirmware to decrypt the data at the given memory region. 250daec8d40SPaolo Bonzini 251daec8d40SPaolo BonziniParameters (in): struct kvm_sev_dbg 252daec8d40SPaolo Bonzini 253daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 254daec8d40SPaolo Bonzini 255daec8d40SPaolo Bonzini:: 256daec8d40SPaolo Bonzini 257daec8d40SPaolo Bonzini struct kvm_sev_dbg { 258daec8d40SPaolo Bonzini __u64 src_uaddr; /* userspace address of data to decrypt */ 259daec8d40SPaolo Bonzini __u64 dst_uaddr; /* userspace address of destination */ 260daec8d40SPaolo Bonzini __u32 len; /* length of memory region to decrypt */ 261daec8d40SPaolo Bonzini }; 262daec8d40SPaolo Bonzini 263daec8d40SPaolo BonziniThe command returns an error if the guest policy does not allow debugging. 264daec8d40SPaolo Bonzini 265daec8d40SPaolo Bonzini8. KVM_SEV_DBG_ENCRYPT 266daec8d40SPaolo Bonzini---------------------- 267daec8d40SPaolo Bonzini 268daec8d40SPaolo BonziniThe KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the 269daec8d40SPaolo Bonzinifirmware to encrypt the data at the given memory region. 270daec8d40SPaolo Bonzini 271daec8d40SPaolo BonziniParameters (in): struct kvm_sev_dbg 272daec8d40SPaolo Bonzini 273daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 274daec8d40SPaolo Bonzini 275daec8d40SPaolo Bonzini:: 276daec8d40SPaolo Bonzini 277daec8d40SPaolo Bonzini struct kvm_sev_dbg { 278daec8d40SPaolo Bonzini __u64 src_uaddr; /* userspace address of data to encrypt */ 279daec8d40SPaolo Bonzini __u64 dst_uaddr; /* userspace address of destination */ 280daec8d40SPaolo Bonzini __u32 len; /* length of memory region to encrypt */ 281daec8d40SPaolo Bonzini }; 282daec8d40SPaolo Bonzini 283daec8d40SPaolo BonziniThe command returns an error if the guest policy does not allow debugging. 284daec8d40SPaolo Bonzini 285daec8d40SPaolo Bonzini9. KVM_SEV_LAUNCH_SECRET 286daec8d40SPaolo Bonzini------------------------ 287daec8d40SPaolo Bonzini 288daec8d40SPaolo BonziniThe KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret 289daec8d40SPaolo Bonzinidata after the measurement has been validated by the guest owner. 290daec8d40SPaolo Bonzini 291daec8d40SPaolo BonziniParameters (in): struct kvm_sev_launch_secret 292daec8d40SPaolo Bonzini 293daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 294daec8d40SPaolo Bonzini 295daec8d40SPaolo Bonzini:: 296daec8d40SPaolo Bonzini 297daec8d40SPaolo Bonzini struct kvm_sev_launch_secret { 298daec8d40SPaolo Bonzini __u64 hdr_uaddr; /* userspace address containing the packet header */ 299daec8d40SPaolo Bonzini __u32 hdr_len; 300daec8d40SPaolo Bonzini 301daec8d40SPaolo Bonzini __u64 guest_uaddr; /* the guest memory region where the secret should be injected */ 302daec8d40SPaolo Bonzini __u32 guest_len; 303daec8d40SPaolo Bonzini 304daec8d40SPaolo Bonzini __u64 trans_uaddr; /* the hypervisor memory region which contains the secret */ 305daec8d40SPaolo Bonzini __u32 trans_len; 306daec8d40SPaolo Bonzini }; 307daec8d40SPaolo Bonzini 308daec8d40SPaolo Bonzini10. KVM_SEV_GET_ATTESTATION_REPORT 309daec8d40SPaolo Bonzini---------------------------------- 310daec8d40SPaolo Bonzini 311daec8d40SPaolo BonziniThe KVM_SEV_GET_ATTESTATION_REPORT command can be used by the hypervisor to query the attestation 312daec8d40SPaolo Bonzinireport containing the SHA-256 digest of the guest memory and VMSA passed through the KVM_SEV_LAUNCH 313daec8d40SPaolo Bonzinicommands and signed with the PEK. The digest returned by the command should match the digest 314daec8d40SPaolo Bonziniused by the guest owner with the KVM_SEV_LAUNCH_MEASURE. 315daec8d40SPaolo Bonzini 316daec8d40SPaolo BonziniIf len is zero on entry, the measurement blob length is written to len and 317daec8d40SPaolo Bonziniuaddr is unused. 318daec8d40SPaolo Bonzini 319daec8d40SPaolo BonziniParameters (in): struct kvm_sev_attestation 320daec8d40SPaolo Bonzini 321daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 322daec8d40SPaolo Bonzini 323daec8d40SPaolo Bonzini:: 324daec8d40SPaolo Bonzini 325daec8d40SPaolo Bonzini struct kvm_sev_attestation_report { 326daec8d40SPaolo Bonzini __u8 mnonce[16]; /* A random mnonce that will be placed in the report */ 327daec8d40SPaolo Bonzini 328daec8d40SPaolo Bonzini __u64 uaddr; /* userspace address where the report should be copied */ 329daec8d40SPaolo Bonzini __u32 len; 330daec8d40SPaolo Bonzini }; 331daec8d40SPaolo Bonzini 332daec8d40SPaolo Bonzini11. KVM_SEV_SEND_START 333daec8d40SPaolo Bonzini---------------------- 334daec8d40SPaolo Bonzini 335daec8d40SPaolo BonziniThe KVM_SEV_SEND_START command can be used by the hypervisor to create an 336daec8d40SPaolo Bonzinioutgoing guest encryption context. 337daec8d40SPaolo Bonzini 338daec8d40SPaolo BonziniIf session_len is zero on entry, the length of the guest session information is 339daec8d40SPaolo Bonziniwritten to session_len and all other fields are not used. 340daec8d40SPaolo Bonzini 341daec8d40SPaolo BonziniParameters (in): struct kvm_sev_send_start 342daec8d40SPaolo Bonzini 343daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 344daec8d40SPaolo Bonzini 345daec8d40SPaolo Bonzini:: 346daec8d40SPaolo Bonzini 347daec8d40SPaolo Bonzini struct kvm_sev_send_start { 348daec8d40SPaolo Bonzini __u32 policy; /* guest policy */ 349daec8d40SPaolo Bonzini 350daec8d40SPaolo Bonzini __u64 pdh_cert_uaddr; /* platform Diffie-Hellman certificate */ 351daec8d40SPaolo Bonzini __u32 pdh_cert_len; 352daec8d40SPaolo Bonzini 353daec8d40SPaolo Bonzini __u64 plat_certs_uaddr; /* platform certificate chain */ 354daec8d40SPaolo Bonzini __u32 plat_certs_len; 355daec8d40SPaolo Bonzini 356daec8d40SPaolo Bonzini __u64 amd_certs_uaddr; /* AMD certificate */ 357daec8d40SPaolo Bonzini __u32 amd_certs_len; 358daec8d40SPaolo Bonzini 359daec8d40SPaolo Bonzini __u64 session_uaddr; /* Guest session information */ 360daec8d40SPaolo Bonzini __u32 session_len; 361daec8d40SPaolo Bonzini }; 362daec8d40SPaolo Bonzini 363daec8d40SPaolo Bonzini12. KVM_SEV_SEND_UPDATE_DATA 364daec8d40SPaolo Bonzini---------------------------- 365daec8d40SPaolo Bonzini 366daec8d40SPaolo BonziniThe KVM_SEV_SEND_UPDATE_DATA command can be used by the hypervisor to encrypt the 367daec8d40SPaolo Bonzinioutgoing guest memory region with the encryption context creating using 368daec8d40SPaolo BonziniKVM_SEV_SEND_START. 369daec8d40SPaolo Bonzini 370daec8d40SPaolo BonziniIf hdr_len or trans_len are zero on entry, the length of the packet header and 371daec8d40SPaolo Bonzinitransport region are written to hdr_len and trans_len respectively, and all 372daec8d40SPaolo Bonziniother fields are not used. 373daec8d40SPaolo Bonzini 374daec8d40SPaolo BonziniParameters (in): struct kvm_sev_send_update_data 375daec8d40SPaolo Bonzini 376daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 377daec8d40SPaolo Bonzini 378daec8d40SPaolo Bonzini:: 379daec8d40SPaolo Bonzini 380daec8d40SPaolo Bonzini struct kvm_sev_launch_send_update_data { 381daec8d40SPaolo Bonzini __u64 hdr_uaddr; /* userspace address containing the packet header */ 382daec8d40SPaolo Bonzini __u32 hdr_len; 383daec8d40SPaolo Bonzini 384daec8d40SPaolo Bonzini __u64 guest_uaddr; /* the source memory region to be encrypted */ 385daec8d40SPaolo Bonzini __u32 guest_len; 386daec8d40SPaolo Bonzini 387daec8d40SPaolo Bonzini __u64 trans_uaddr; /* the destination memory region */ 388daec8d40SPaolo Bonzini __u32 trans_len; 389daec8d40SPaolo Bonzini }; 390daec8d40SPaolo Bonzini 391daec8d40SPaolo Bonzini13. KVM_SEV_SEND_FINISH 392daec8d40SPaolo Bonzini------------------------ 393daec8d40SPaolo Bonzini 394daec8d40SPaolo BonziniAfter completion of the migration flow, the KVM_SEV_SEND_FINISH command can be 395daec8d40SPaolo Bonziniissued by the hypervisor to delete the encryption context. 396daec8d40SPaolo Bonzini 397daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 398daec8d40SPaolo Bonzini 399daec8d40SPaolo Bonzini14. KVM_SEV_SEND_CANCEL 400daec8d40SPaolo Bonzini------------------------ 401daec8d40SPaolo Bonzini 402daec8d40SPaolo BonziniAfter completion of SEND_START, but before SEND_FINISH, the source VMM can issue the 403daec8d40SPaolo BonziniSEND_CANCEL command to stop a migration. This is necessary so that a cancelled 404daec8d40SPaolo Bonzinimigration can restart with a new target later. 405daec8d40SPaolo Bonzini 406daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 407daec8d40SPaolo Bonzini 408daec8d40SPaolo Bonzini15. KVM_SEV_RECEIVE_START 409daec8d40SPaolo Bonzini------------------------- 410daec8d40SPaolo Bonzini 411daec8d40SPaolo BonziniThe KVM_SEV_RECEIVE_START command is used for creating the memory encryption 412daec8d40SPaolo Bonzinicontext for an incoming SEV guest. To create the encryption context, the user must 413daec8d40SPaolo Bonziniprovide a guest policy, the platform public Diffie-Hellman (PDH) key and session 414daec8d40SPaolo Bonziniinformation. 415daec8d40SPaolo Bonzini 416daec8d40SPaolo BonziniParameters: struct kvm_sev_receive_start (in/out) 417daec8d40SPaolo Bonzini 418daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 419daec8d40SPaolo Bonzini 420daec8d40SPaolo Bonzini:: 421daec8d40SPaolo Bonzini 422daec8d40SPaolo Bonzini struct kvm_sev_receive_start { 423daec8d40SPaolo Bonzini __u32 handle; /* if zero then firmware creates a new handle */ 424daec8d40SPaolo Bonzini __u32 policy; /* guest's policy */ 425daec8d40SPaolo Bonzini 426daec8d40SPaolo Bonzini __u64 pdh_uaddr; /* userspace address pointing to the PDH key */ 427daec8d40SPaolo Bonzini __u32 pdh_len; 428daec8d40SPaolo Bonzini 429daec8d40SPaolo Bonzini __u64 session_uaddr; /* userspace address which points to the guest session information */ 430daec8d40SPaolo Bonzini __u32 session_len; 431daec8d40SPaolo Bonzini }; 432daec8d40SPaolo Bonzini 433daec8d40SPaolo BonziniOn success, the 'handle' field contains a new handle and on error, a negative value. 434daec8d40SPaolo Bonzini 435daec8d40SPaolo BonziniFor more details, see SEV spec Section 6.12. 436daec8d40SPaolo Bonzini 437daec8d40SPaolo Bonzini16. KVM_SEV_RECEIVE_UPDATE_DATA 438daec8d40SPaolo Bonzini------------------------------- 439daec8d40SPaolo Bonzini 440daec8d40SPaolo BonziniThe KVM_SEV_RECEIVE_UPDATE_DATA command can be used by the hypervisor to copy 441daec8d40SPaolo Bonzinithe incoming buffers into the guest memory region with encryption context 442daec8d40SPaolo Bonzinicreated during the KVM_SEV_RECEIVE_START. 443daec8d40SPaolo Bonzini 444daec8d40SPaolo BonziniParameters (in): struct kvm_sev_receive_update_data 445daec8d40SPaolo Bonzini 446daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 447daec8d40SPaolo Bonzini 448daec8d40SPaolo Bonzini:: 449daec8d40SPaolo Bonzini 450daec8d40SPaolo Bonzini struct kvm_sev_launch_receive_update_data { 451daec8d40SPaolo Bonzini __u64 hdr_uaddr; /* userspace address containing the packet header */ 452daec8d40SPaolo Bonzini __u32 hdr_len; 453daec8d40SPaolo Bonzini 454daec8d40SPaolo Bonzini __u64 guest_uaddr; /* the destination guest memory region */ 455daec8d40SPaolo Bonzini __u32 guest_len; 456daec8d40SPaolo Bonzini 457daec8d40SPaolo Bonzini __u64 trans_uaddr; /* the incoming buffer memory region */ 458daec8d40SPaolo Bonzini __u32 trans_len; 459daec8d40SPaolo Bonzini }; 460daec8d40SPaolo Bonzini 461daec8d40SPaolo Bonzini17. KVM_SEV_RECEIVE_FINISH 462daec8d40SPaolo Bonzini-------------------------- 463daec8d40SPaolo Bonzini 464daec8d40SPaolo BonziniAfter completion of the migration flow, the KVM_SEV_RECEIVE_FINISH command can be 465daec8d40SPaolo Bonziniissued by the hypervisor to make the guest ready for execution. 466daec8d40SPaolo Bonzini 467daec8d40SPaolo BonziniReturns: 0 on success, -negative on error 468daec8d40SPaolo Bonzini 469ac5c4802SPaolo BonziniDevice attribute API 470ac5c4802SPaolo Bonzini==================== 471ac5c4802SPaolo Bonzini 472ac5c4802SPaolo BonziniAttributes of the SEV implementation can be retrieved through the 473ac5c4802SPaolo Bonzini``KVM_HAS_DEVICE_ATTR`` and ``KVM_GET_DEVICE_ATTR`` ioctls on the ``/dev/kvm`` 474ac5c4802SPaolo Bonzinidevice node, using group ``KVM_X86_GRP_SEV``. 475ac5c4802SPaolo Bonzini 476ac5c4802SPaolo BonziniCurrently only one attribute is implemented: 477ac5c4802SPaolo Bonzini 478ac5c4802SPaolo Bonzini* ``KVM_X86_SEV_VMSA_FEATURES``: return the set of all bits that 479ac5c4802SPaolo Bonzini are accepted in the ``vmsa_features`` of ``KVM_SEV_INIT2``. 480ac5c4802SPaolo Bonzini 48119cebbabSPaolo BonziniFirmware Management 48219cebbabSPaolo Bonzini=================== 48319cebbabSPaolo Bonzini 48419cebbabSPaolo BonziniThe SEV guest key management is handled by a separate processor called the AMD 48519cebbabSPaolo BonziniSecure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure 48619cebbabSPaolo Bonzinikey management interface to perform common hypervisor activities such as 48719cebbabSPaolo Bonziniencrypting bootstrap code, snapshot, migrating and debugging the guest. For more 48819cebbabSPaolo Bonziniinformation, see the SEV Key Management spec [api-spec]_ 48919cebbabSPaolo Bonzini 49019cebbabSPaolo BonziniThe AMD-SP firmware can be initialized either by using its own non-volatile 49119cebbabSPaolo Bonzinistorage or the OS can manage the NV storage for the firmware using 49219cebbabSPaolo Bonziniparameter ``init_ex_path`` of the ``ccp`` module. If the file specified 49319cebbabSPaolo Bonziniby ``init_ex_path`` does not exist or is invalid, the OS will create or 49419cebbabSPaolo Bonzinioverride the file with PSP non-volatile storage. 49519cebbabSPaolo Bonzini 496daec8d40SPaolo BonziniReferences 497daec8d40SPaolo Bonzini========== 498daec8d40SPaolo Bonzini 499daec8d40SPaolo Bonzini 500daec8d40SPaolo BonziniSee [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info. 501daec8d40SPaolo Bonzini 502fbabc2eaSWyes Karny.. [white-paper] https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf 503daec8d40SPaolo Bonzini.. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf 504daec8d40SPaolo Bonzini.. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34) 505daec8d40SPaolo Bonzini.. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf 506