1====================================== 2Secure Encrypted Virtualization (SEV) 3====================================== 4 5Overview 6======== 7 8Secure Encrypted Virtualization (SEV) is a feature found on AMD processors. 9 10SEV is an extension to the AMD-V architecture which supports running 11virtual machines (VMs) under the control of a hypervisor. When enabled, 12the memory contents of a VM will be transparently encrypted with a key 13unique to that VM. 14 15The hypervisor can determine the SEV support through the CPUID 16instruction. The CPUID function 0x8000001f reports information related 17to SEV:: 18 19 0x8000001f[eax]: 20 Bit[1] indicates support for SEV 21 ... 22 [ecx]: 23 Bits[31:0] Number of encrypted guests supported simultaneously 24 25If support for SEV is present, MSR 0xc001_0010 (MSR_K8_SYSCFG) and MSR 0xc001_0015 26(MSR_K7_HWCR) can be used to determine if it can be enabled:: 27 28 0xc001_0010: 29 Bit[23] 1 = memory encryption can be enabled 30 0 = memory encryption can not be enabled 31 32 0xc001_0015: 33 Bit[0] 1 = memory encryption can be enabled 34 0 = memory encryption can not be enabled 35 36When SEV support is available, it can be enabled in a specific VM by 37setting the SEV bit before executing VMRUN.:: 38 39 VMCB[0x90]: 40 Bit[1] 1 = SEV is enabled 41 0 = SEV is disabled 42 43SEV hardware uses ASIDs to associate a memory encryption key with a VM. 44Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value 45defined in the CPUID 0x8000001f[ecx] field. 46 47SEV Key Management 48================== 49 50The SEV guest key management is handled by a separate processor called the AMD 51Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure 52key management interface to perform common hypervisor activities such as 53encrypting bootstrap code, snapshot, migrating and debugging the guest. For more 54information, see the SEV Key Management spec [api-spec]_ 55 56The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP. If the argument 57to KVM_MEMORY_ENCRYPT_OP is NULL, the ioctl returns 0 if SEV is enabled 58and ``ENOTTY` if it is disabled (on some older versions of Linux, 59the ioctl runs normally even with a NULL argument, and therefore will 60likely return ``EFAULT``). If non-NULL, the argument to KVM_MEMORY_ENCRYPT_OP 61must be a struct kvm_sev_cmd:: 62 63 struct kvm_sev_cmd { 64 __u32 id; 65 __u64 data; 66 __u32 error; 67 __u32 sev_fd; 68 }; 69 70 71The ``id`` field contains the subcommand, and the ``data`` field points to 72another struct containing arguments specific to command. The ``sev_fd`` 73should point to a file descriptor that is opened on the ``/dev/sev`` 74device, if needed (see individual commands). 75 76On output, ``error`` is zero on success, or an error code. Error codes 77are defined in ``<linux/psp-dev.h>``. 78 79KVM implements the following commands to support common lifecycle events of SEV 80guests, such as launching, running, snapshotting, migrating and decommissioning. 81 821. KVM_SEV_INIT 83--------------- 84 85The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform 86context. In a typical workflow, this command should be the first command issued. 87 88Returns: 0 on success, -negative on error 89 902. KVM_SEV_LAUNCH_START 91----------------------- 92 93The KVM_SEV_LAUNCH_START command is used for creating the memory encryption 94context. To create the encryption context, user must provide a guest policy, 95the owner's public Diffie-Hellman (PDH) key and session information. 96 97Parameters: struct kvm_sev_launch_start (in/out) 98 99Returns: 0 on success, -negative on error 100 101:: 102 103 struct kvm_sev_launch_start { 104 __u32 handle; /* if zero then firmware creates a new handle */ 105 __u32 policy; /* guest's policy */ 106 107 __u64 dh_uaddr; /* userspace address pointing to the guest owner's PDH key */ 108 __u32 dh_len; 109 110 __u64 session_addr; /* userspace address which points to the guest session information */ 111 __u32 session_len; 112 }; 113 114On success, the 'handle' field contains a new handle and on error, a negative value. 115 116KVM_SEV_LAUNCH_START requires the ``sev_fd`` field to be valid. 117 118For more details, see SEV spec Section 6.2. 119 1203. KVM_SEV_LAUNCH_UPDATE_DATA 121----------------------------- 122 123The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also 124calculates a measurement of the memory contents. The measurement is a signature 125of the memory contents that can be sent to the guest owner as an attestation 126that the memory was encrypted correctly by the firmware. 127 128Parameters (in): struct kvm_sev_launch_update_data 129 130Returns: 0 on success, -negative on error 131 132:: 133 134 struct kvm_sev_launch_update { 135 __u64 uaddr; /* userspace address to be encrypted (must be 16-byte aligned) */ 136 __u32 len; /* length of the data to be encrypted (must be 16-byte aligned) */ 137 }; 138 139For more details, see SEV spec Section 6.3. 140 1414. KVM_SEV_LAUNCH_MEASURE 142------------------------- 143 144The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the 145data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may 146wait to provide the guest with confidential information until it can verify the 147measurement. Since the guest owner knows the initial contents of the guest at 148boot, the measurement can be verified by comparing it to what the guest owner 149expects. 150 151Parameters (in): struct kvm_sev_launch_measure 152 153Returns: 0 on success, -negative on error 154 155:: 156 157 struct kvm_sev_launch_measure { 158 __u64 uaddr; /* where to copy the measurement */ 159 __u32 len; /* length of measurement blob */ 160 }; 161 162For more details on the measurement verification flow, see SEV spec Section 6.4. 163 1645. KVM_SEV_LAUNCH_FINISH 165------------------------ 166 167After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be 168issued to make the guest ready for the execution. 169 170Returns: 0 on success, -negative on error 171 1726. KVM_SEV_GUEST_STATUS 173----------------------- 174 175The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a 176SEV-enabled guest. 177 178Parameters (out): struct kvm_sev_guest_status 179 180Returns: 0 on success, -negative on error 181 182:: 183 184 struct kvm_sev_guest_status { 185 __u32 handle; /* guest handle */ 186 __u32 policy; /* guest policy */ 187 __u8 state; /* guest state (see enum below) */ 188 }; 189 190SEV guest state: 191 192:: 193 194 enum { 195 SEV_STATE_INVALID = 0; 196 SEV_STATE_LAUNCHING, /* guest is currently being launched */ 197 SEV_STATE_SECRET, /* guest is being launched and ready to accept the ciphertext data */ 198 SEV_STATE_RUNNING, /* guest is fully launched and running */ 199 SEV_STATE_RECEIVING, /* guest is being migrated in from another SEV machine */ 200 SEV_STATE_SENDING /* guest is getting migrated out to another SEV machine */ 201 }; 202 2037. KVM_SEV_DBG_DECRYPT 204---------------------- 205 206The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the 207firmware to decrypt the data at the given memory region. 208 209Parameters (in): struct kvm_sev_dbg 210 211Returns: 0 on success, -negative on error 212 213:: 214 215 struct kvm_sev_dbg { 216 __u64 src_uaddr; /* userspace address of data to decrypt */ 217 __u64 dst_uaddr; /* userspace address of destination */ 218 __u32 len; /* length of memory region to decrypt */ 219 }; 220 221The command returns an error if the guest policy does not allow debugging. 222 2238. KVM_SEV_DBG_ENCRYPT 224---------------------- 225 226The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the 227firmware to encrypt the data at the given memory region. 228 229Parameters (in): struct kvm_sev_dbg 230 231Returns: 0 on success, -negative on error 232 233:: 234 235 struct kvm_sev_dbg { 236 __u64 src_uaddr; /* userspace address of data to encrypt */ 237 __u64 dst_uaddr; /* userspace address of destination */ 238 __u32 len; /* length of memory region to encrypt */ 239 }; 240 241The command returns an error if the guest policy does not allow debugging. 242 2439. KVM_SEV_LAUNCH_SECRET 244------------------------ 245 246The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret 247data after the measurement has been validated by the guest owner. 248 249Parameters (in): struct kvm_sev_launch_secret 250 251Returns: 0 on success, -negative on error 252 253:: 254 255 struct kvm_sev_launch_secret { 256 __u64 hdr_uaddr; /* userspace address containing the packet header */ 257 __u32 hdr_len; 258 259 __u64 guest_uaddr; /* the guest memory region where the secret should be injected */ 260 __u32 guest_len; 261 262 __u64 trans_uaddr; /* the hypervisor memory region which contains the secret */ 263 __u32 trans_len; 264 }; 265 266References 267========== 268 269 270See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info. 271 272.. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf 273.. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf 274.. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34) 275.. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf 276