2f5947dfca
Renaming docs seems to be en vogue at the moment, so fix on of the
grossly misnamed directories. We usually never use "virtual" as
a shortcut for virtualization in the kernel, but always virt,
as seen in the virt/ top-level directory. Fix up the documentation
to match that.
Fixes: ed16648eb5 ("Move kvm, uml, and lguest subdirectories under a common "virtual" directory, I.E:")
Signed-off-by: Christoph Hellwig <hch@lst.de>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
251 lines
8.3 KiB
ReStructuredText
251 lines
8.3 KiB
ReStructuredText
======================================
|
|
Secure Encrypted Virtualization (SEV)
|
|
======================================
|
|
|
|
Overview
|
|
========
|
|
|
|
Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
|
|
|
|
SEV is an extension to the AMD-V architecture which supports running
|
|
virtual machines (VMs) under the control of a hypervisor. When enabled,
|
|
the memory contents of a VM will be transparently encrypted with a key
|
|
unique to that VM.
|
|
|
|
The 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
|
|
...
|
|
[ecx]:
|
|
Bits[31:0] Number of encrypted guests supported simultaneously
|
|
|
|
If support for SEV is present, MSR 0xc001_0010 (MSR_K8_SYSCFG) and MSR 0xc001_0015
|
|
(MSR_K7_HWCR) can be used to determine if it can be enabled::
|
|
|
|
0xc001_0010:
|
|
Bit[23] 1 = memory encryption can be enabled
|
|
0 = memory encryption can not be enabled
|
|
|
|
0xc001_0015:
|
|
Bit[0] 1 = memory encryption can be enabled
|
|
0 = memory encryption can not be enabled
|
|
|
|
When SEV support is available, it can be enabled in a specific VM by
|
|
setting the SEV bit before executing VMRUN.::
|
|
|
|
VMCB[0x90]:
|
|
Bit[1] 1 = SEV is enabled
|
|
0 = SEV is disabled
|
|
|
|
SEV hardware uses ASIDs to associate a memory encryption key with a VM.
|
|
Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value
|
|
defined in the CPUID 0x8000001f[ecx] field.
|
|
|
|
SEV Key Management
|
|
==================
|
|
|
|
The SEV guest key management is handled by a separate processor called 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, snapshot, migrating and debugging the guest. For more
|
|
information, see the SEV Key Management spec [api-spec]_
|
|
|
|
KVM implements the following commands to support common lifecycle events of SEV
|
|
guests, such as launching, running, snapshotting, migrating and decommissioning.
|
|
|
|
1. KVM_SEV_INIT
|
|
---------------
|
|
|
|
The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform
|
|
context. In a typical workflow, this command should be the first command issued.
|
|
|
|
Returns: 0 on success, -negative on error
|
|
|
|
2. KVM_SEV_LAUNCH_START
|
|
-----------------------
|
|
|
|
The KVM_SEV_LAUNCH_START command is used for creating the memory encryption
|
|
context. To create the encryption context, user must provide a guest policy,
|
|
the owner's public Diffie-Hellman (PDH) key and session information.
|
|
|
|
Parameters: struct kvm_sev_launch_start (in/out)
|
|
|
|
Returns: 0 on success, -negative on error
|
|
|
|
::
|
|
|
|
struct kvm_sev_launch_start {
|
|
__u32 handle; /* if zero then firmware creates a new handle */
|
|
__u32 policy; /* guest's policy */
|
|
|
|
__u64 dh_uaddr; /* userspace address pointing to the guest owner's PDH key */
|
|
__u32 dh_len;
|
|
|
|
__u64 session_addr; /* userspace address which points to the guest session information */
|
|
__u32 session_len;
|
|
};
|
|
|
|
On success, the 'handle' field contains a new handle and on error, a negative value.
|
|
|
|
For more details, see SEV spec Section 6.2.
|
|
|
|
3. KVM_SEV_LAUNCH_UPDATE_DATA
|
|
-----------------------------
|
|
|
|
The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also
|
|
calculates a measurement of the memory contents. The measurement is a signature
|
|
of the memory contents that can be sent to the guest owner as an attestation
|
|
that the memory was encrypted correctly by the firmware.
|
|
|
|
Parameters (in): struct kvm_sev_launch_update_data
|
|
|
|
Returns: 0 on success, -negative on error
|
|
|
|
::
|
|
|
|
struct kvm_sev_launch_update {
|
|
__u64 uaddr; /* userspace address to be encrypted (must be 16-byte aligned) */
|
|
__u32 len; /* length of the data to be encrypted (must be 16-byte aligned) */
|
|
};
|
|
|
|
For more details, see SEV spec Section 6.3.
|
|
|
|
4. KVM_SEV_LAUNCH_MEASURE
|
|
-------------------------
|
|
|
|
The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the
|
|
data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may
|
|
wait to provide the guest with confidential information until it can verify the
|
|
measurement. Since the guest owner knows the initial contents of the guest at
|
|
boot, the measurement can be verified by comparing it to what the guest owner
|
|
expects.
|
|
|
|
Parameters (in): struct kvm_sev_launch_measure
|
|
|
|
Returns: 0 on success, -negative on error
|
|
|
|
::
|
|
|
|
struct kvm_sev_launch_measure {
|
|
__u64 uaddr; /* where to copy the measurement */
|
|
__u32 len; /* length of measurement blob */
|
|
};
|
|
|
|
For more details on the measurement verification flow, see SEV spec Section 6.4.
|
|
|
|
5. KVM_SEV_LAUNCH_FINISH
|
|
------------------------
|
|
|
|
After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be
|
|
issued to make the guest ready for the execution.
|
|
|
|
Returns: 0 on success, -negative on error
|
|
|
|
6. KVM_SEV_GUEST_STATUS
|
|
-----------------------
|
|
|
|
The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a
|
|
SEV-enabled guest.
|
|
|
|
Parameters (out): struct kvm_sev_guest_status
|
|
|
|
Returns: 0 on success, -negative on error
|
|
|
|
::
|
|
|
|
struct kvm_sev_guest_status {
|
|
__u32 handle; /* guest handle */
|
|
__u32 policy; /* guest policy */
|
|
__u8 state; /* guest state (see enum below) */
|
|
};
|
|
|
|
SEV guest state:
|
|
|
|
::
|
|
|
|
enum {
|
|
SEV_STATE_INVALID = 0;
|
|
SEV_STATE_LAUNCHING, /* guest is currently being launched */
|
|
SEV_STATE_SECRET, /* guest is being launched and ready to accept the ciphertext data */
|
|
SEV_STATE_RUNNING, /* guest is fully launched and running */
|
|
SEV_STATE_RECEIVING, /* guest is being migrated in from another SEV machine */
|
|
SEV_STATE_SENDING /* guest is getting migrated out to another SEV machine */
|
|
};
|
|
|
|
7. KVM_SEV_DBG_DECRYPT
|
|
----------------------
|
|
|
|
The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the
|
|
firmware to decrypt the data at the given memory region.
|
|
|
|
Parameters (in): struct kvm_sev_dbg
|
|
|
|
Returns: 0 on success, -negative on error
|
|
|
|
::
|
|
|
|
struct kvm_sev_dbg {
|
|
__u64 src_uaddr; /* userspace address of data to decrypt */
|
|
__u64 dst_uaddr; /* userspace address of destination */
|
|
__u32 len; /* length of memory region to decrypt */
|
|
};
|
|
|
|
The command returns an error if the guest policy does not allow debugging.
|
|
|
|
8. KVM_SEV_DBG_ENCRYPT
|
|
----------------------
|
|
|
|
The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the
|
|
firmware to encrypt the data at the given memory region.
|
|
|
|
Parameters (in): struct kvm_sev_dbg
|
|
|
|
Returns: 0 on success, -negative on error
|
|
|
|
::
|
|
|
|
struct kvm_sev_dbg {
|
|
__u64 src_uaddr; /* userspace address of data to encrypt */
|
|
__u64 dst_uaddr; /* userspace address of destination */
|
|
__u32 len; /* length of memory region to encrypt */
|
|
};
|
|
|
|
The command returns an error if the guest policy does not allow debugging.
|
|
|
|
9. KVM_SEV_LAUNCH_SECRET
|
|
------------------------
|
|
|
|
The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret
|
|
data after the measurement has been validated by the guest owner.
|
|
|
|
Parameters (in): struct kvm_sev_launch_secret
|
|
|
|
Returns: 0 on success, -negative on error
|
|
|
|
::
|
|
|
|
struct kvm_sev_launch_secret {
|
|
__u64 hdr_uaddr; /* userspace address containing the packet header */
|
|
__u32 hdr_len;
|
|
|
|
__u64 guest_uaddr; /* the guest memory region where the secret should be injected */
|
|
__u32 guest_len;
|
|
|
|
__u64 trans_uaddr; /* the hypervisor memory region which contains the secret */
|
|
__u32 trans_len;
|
|
};
|
|
|
|
References
|
|
==========
|
|
|
|
|
|
See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info.
|
|
|
|
.. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
|
|
.. [api-spec] http://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf
|
|
.. [amd-apm] http://support.amd.com/TechDocs/24593.pdf (section 15.34)
|
|
.. [kvm-forum] http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf
|