[RFC Part2 PATCH v3 01/26] Documentation/virtual/kvm: Add AMD Secure Encrypted Virtualization (SEV)

[Brijesh Singh <brijesh.singh@amd.com>]

Create a Documentation entry to describe the AMD Secure Encrypted
Virtualization (SEV) feature.

Signed-off-by: Brijesh Singh <brijesh.singh@amd.com>
---
 .../virtual/kvm/amd-memory-encryption.txt          | 328 +++++++++++++++++++++
 1 file changed, 328 insertions(+)
 create mode 100644 Documentation/virtual/kvm/amd-memory-encryption.txt

diff --git a/Documentation/virtual/kvm/amd-memory-encryption.txt b/Documentation/virtual/kvm/amd-memory-encryption.txt
new file mode 100644
index 0000000..cffed2d
--- /dev/null
+++ b/Documentation/virtual/kvm/amd-memory-encryption.txt
@@ -0,0 +1,328 @@
+Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
+
+SEV is an extension to the AMD-V architecture which supports running virtual
+machine (VMs) under the control of a hypervisor. When enabled, the memory
+contents of VM will be transparently encrypted with a key unique to the VM.
+
+Hypervisor can determine the SEV support through the CPUID instruction. The CPUID
+function 0x8000001f reports information related to SEV:
+
+	0x8000001f[eax]:
+		Bit[1] 	indicates support for SEV
+
+	0x8000001f[ecx]:
+		Bits[31:0]  Number of encrypted guest supported simultaneously
+
+If support for SEV is present, MSR 0xc00100010 (MSR_K8_SYSCFG) and MSR
+0xc0000015 (MSR_K7_HWCR_SMMLOCK) can be used to determine if it can be enabled:
+
+	0xc00100010:
+		Bit[23]	   0 = memory encryption can be enabled
+			   0 = memory encryption can not be enabled
+
+	0xc00010015:
+		Bit[0]	   0 = memory encryption can not be enabled
+			   1 = memory encryption can be enabled
+
+When SEV support is available, it can be enabled on specific VM during the VMRUN
+instruction by setting SEV bit in VMCB offset 090h:
+
+	VMCB offset 090h:
+		Bit[1]	    1 = Enable SEV
+
+SEV hardware uses ASIDs to associate memory encryption key with the guest VMs.
+Hence the ASID for the SEV-enabled guests must be from 1 to a maximum value
+defined through the CPUID function 0x8000001f[ECX].
+
+
+SEV Key Management
+------------------
+
+The Key management for the SEV guest is handled by a seperate processor known as
+the AMD Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a
+secure key management interface to perform common hypervisor activities such as
+encrypting bootstrap code, snapshotting, migrating and debugging the guest. For
+more informaiton, see SEV Key Management spec:
+
+http://support.amd.com/TechDocs/55766_SEV-KM%20API_Specification.pdf
+
+1. KVM_SEV_LAUNCH_START
+
+Parameters: struct  kvm_sev_launch_start (in/out)
+Returns: 0 on success, -negative on error
+
+LAUNCH_START command is used to bootstrap a guest by encrypting its memory with
+a new VM Encryption Key (VEK). In order to create guest context, hypervisor should
+provide guest policy, owners public diffie-hellman (PDH) key and session parameters.
+
+The guest policy constrains the use and features activated for the lifetime of the
+launched guest, such as disallowing debugging, enabling key sharing, or turning on
+other SEV related features.
+
+The guest owners PDH allows the firmware to establish a cryptographic session with
+the guest owner to negotiate keys used for attestation.
+
+The session parameters contains informations such as guest policy MAC, transport
+integrity key (TIK), transport encryption key (TEK) etc.
+
+struct kvm_sev_launch_start {
+
+	/* Guest Hanldle, if zero then FW creates a new handle */
+	__u32 handle;
+
+	/* Guest policy */
+	__u32 policy;
+
+	/* Address which contains guest owner's PDH certificate blob */
+	__u64 dh_cert_address;
+	__u32 dh_cert_length;
+
+	/* Address which contains guest session information blob */
+	__u64 session_address;
+	__u32 session_length;
+};
+
+On success, the 'handle' field contain a new handle.
+
+2. KVM_SEV_LAUNCH_UPDATE_DATA
+
+Parameters (in): struct  kvm_sev_launch_update
+Returns: 0 on success, -negative on error
+
+LAUNCH_UPDATE_DATA encrypts the memory region using the VEK created during
+LAUNCH_START. It also calculates a measurement of the memory region. This
+measurement can be used as a signature of the memory contents.
+
+struct kvm_sev_launch_update {
+	/* address of the data to be encrypted (must be 16-byte aligned) */
+	__u64 address;
+
+	/* length of the data to be encrypted (must be 16-byte aligned) */
+	__u32 length;
+};
+
+3. KVM_SEV_LAUNCH_MEASURE
+
+Parameters (in): struct  kvm_sev_launch_measure
+Returns: 0 on success, -negative on error
+
+LAUNCH_MEASURE returns the measurement of the memory region encrypted with
+LAUNCH_UPDATE_DATA. The measurement is keyed with the TIK so that the guest
+owner can use the measurement to verify the guest was properly launched without
+tempering.
+
+struct kvm_sev_launch_measure {
+	/* where to copy the measurement blob */
+	__u64 address;
+
+	/* length of memory region containing measurement */
+	__u32 length;
+};
+
+If measurement length is too small, the required length is returned in the
+length field.
+
+On success, the measurement is copied to the address.
+
+4. KVM_SEV_LAUNCH_FINISH
+
+Returns: 0 on success, -negative on error
+
+LAUNCH_FINISH command finalize the SEV guest launch process.
+
+5. KVM_SEV_GUEST_STATUS
+
+Parameters (out): struct kvm_sev_guest_status
+Returns: 0 on success, -negative on error
+
+GUEST_STATUS returns the current SEV state the guest is in.
+
+struct kvm_sev_guest_status {
+
+	/* guest hanldle */
+	__u32 handle;
+
+	/* guest policy */
+	__u32 policy;
+
+	/* guest state  (see below) */
+	__u8 state;
+};
+
+SEV guest state:
+
+enum {
+	/* guest state is not known */
+	SEV_STATE_INVALID = 0;
+	/* guest is currently being launched */
+	SEV_STATE_LAUNCHING.
+	/* guest is being launched and ready to accept the ciphertext data */
+	SEV_STATE_SECRET,
+	/* guest is fully launched and running */
+	SEV_STATE_RUNNING,
+	/* guest is being migrated in from another SEV machine */
+	SEV_STATE_RECEIVING,
+	/* guest is getting migrated out another SEV machine */
+	SEV_STATE_SENDING
+};
+
+6. KVM_SEV_DBG_DECRYPT
+
+DEBUG_DECRYPT command can be used for decrypting a region of guest memory for
+the SEV guest debug purposes. Note that since decrypting protected memory allows
+the hypervisor to gain access to guest memory, the guest policy must explicitly
+allow debugging for this command to work.
+
+Parameters (in): struct kvm_sev_dbg
+Returns: 0 on success, -negative on error
+
+struct kvm_sev_dbg {
+	__u64 src_address;
+	__u64 dst_address;
+
+	/* length of memory region to decrypt */
+	__u32 length;
+};
+
+7. KVM_SEV_DBG_ENCRYPT
+
+DEBUG_ENCRYPT command can be used for injecting the data into guest for the SEV
+guest debug purposes. Note that since injecting the data into protected memory
+allows the hypervisor to modify the guest memory, the guest policy must explicitly
+allow debugging for this command to work.
+
+Parameters (in): struct kvm_sev_dbg
+Returns: 0 on success, -negative on error
+
+struct kvm_sev_dbg {
+	__u64 src_address;
+	__u64 dst_address;
+
+	/* length of memory region to encrypt */
+	__u32 length;
+};
+
+8. KVM_SEV_SEND_START
+
+Parameters (in): struct kvm_sev_send_start
+Returns: 0 on success, -negative on error
+
+SEND_START command is used to export a SEV guest from one platform to another.
+It can be used for saving a guest to disk to be resumed later, or it can be
+used to migrate a guest across the network to a receiving platform.
+
+struct kvm_sev_send_start {
+	/* guest policy */
+	__u32 policy;
+
+	/* address which contains receivers PDH key blob */
+	__u64 pdh_cert_address;
+	__u32 pdh_cert_length;
+
+	/* address which contains platform certificate blob */
+	__u64 plat_cert_address;
+	__u32 plat_cert_length;
+
+	/* address which contains AMD certificate chain */
+	__u64 amd_cert_address;
+	__u32 amd_cert_length;
+
+	/* where to copy the current session information */
+	__u64 session_address;
+	__u32 session_length;
+};
+
+The command uses PDH key to establish a new cryptographic context with the
+remote platform - the new cryptographic context will be used for re-encrypting
+the guest memory before sending it to remote platform.
+
+If length of the certificate blobs are too small, the required length is
+returned in the length field and an error is returned.
+
+9. KVM_SEV_SEND_UPDATE_DATA
+
+Parameters (in): struct kvm_sev_send_update_data
+Returns: 0 on success, -negative on error
+
+SEND_UPDATE_DATA command is used to re-encrypt the guest memory using the
+crytographic context established during SEND_START. A fresh IV is generated
+and written to the packet header field.
+
+struct kvm_sev_send_update_data {
+	/* address which will contain packet header (IV, MAC etc)*/
+	__u64 hdr_data;
+	__u32 hdr_length;
+
+	/* address of guest memory region containg encrypted data */
+	__u64 guest_address;
+	__u32 guest_length;
+
+	/* address of transport buffer */
+	__u64 host_address;
+	__u32 host_length;
+};
+
+If the hdr_length is too small, the required length is returned in the length
+field and an error is returned.
+
+10. KVM_SEV_SEND_FINISH
+
+Returns: 0 on success, -negative on error
+
+SEND_FINISH command finalize the SEV guest sending process.
+
+11. KVM_SEV_RECEIVE_START
+
+Parameters (in): struct kvm_sev_receive_start
+Returns: 0 on success, -negative on error
+
+RECEIVE_START command is used to import a guest from one platform to another.
+It can be used for restoring a guest from disk, or it can be used to migrate
+a guest across the network from a sending platform.
+
+struct kvm_sev_receive_start {
+	/* guest handle (if zero then new handle will be created) */
+	__u32 handle;
+
+	/* guest policy */
+	__u32 policy;
+
+	/* Address containing senders PDH certificate blob */
+	__u64 pdh_cert_address;
+	__u32 pdh_cert_length;
+
+	/* Address containing sender's session information blob */
+	__u64 session_address;
+	__u32 session_length;
+};
+
+The RECEIVE_START command creates a new cryptographic context necessary to
+re-enrypt the guest memory receieved through the RECEIVE_UPDATE command.
+
+12. KVM_SEV_RECEIVE_UPDATE_DATA
+
+Parameters (in): struct kvm_sev_receive_update_data
+Returns: 0 on success, -negative on error
+
+RECEIVE_UPDATE_DATA command is used to re-encrypt the guest memory using the
+crytographic context established during RECEIVE_START.
+
+struct kvm_sev_receive_update_data {
+	/* packet header receieved from the SEND_UPDATE_DATA command */
+	__u64 hdr_data;
+	__u32 hdr_length;
+
+	/* address of guest memory region */
+	__u64 guest_address;
+	__u32 guest_length;
+
+	/* address of transport buffer */
+	__u64 host_address;
+	__u32 host_length;
+};
+
+13. KVM_SEV_RECEIVE_FINISH
+
+Returns: 0 on success, -negative on error
+
+RECEIVE_FINISH command finalize the SEV guest receiving process.
-- 
2.9.4