lkml.org 
[lkml]   [2017]   [Jul]   [24]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[RFC Part2 PATCH v3 01/26] Documentation/virtual/kvm: Add AMD Secure Encrypted Virtualization (SEV)
Date
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
\
 
 \ /
  Last update: 2017-07-24 22:05    [W:0.460 / U:2.516 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site