KVM: Define SEV key management command id (dc48bae0) · Commits · 戴 / test

Documentation/virtual/kvm/amd-memory-encryption.rst

+202 −0

Original line number	Diff line number	Diff line
		@@ -43,3 +43,205 @@ setting the SEV bit before executing VMRUN.::
		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
		==========

		.. [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%20API_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

include/uapi/linux/kvm.h

+80 −0

Original line number	Diff line number	Diff line
		@@ -1369,6 +1369,86 @@ struct kvm_enc_region {
		#define KVM_MEMORY_ENCRYPT_REG_REGION _IOR(KVMIO, 0xbb, struct kvm_enc_region)
		#define KVM_MEMORY_ENCRYPT_UNREG_REGION _IOR(KVMIO, 0xbc, struct kvm_enc_region)

		/* Secure Encrypted Virtualization command */
		enum sev_cmd_id {
		/* Guest initialization commands */
		KVM_SEV_INIT = 0,
		KVM_SEV_ES_INIT,
		/* Guest launch commands */
		KVM_SEV_LAUNCH_START,
		KVM_SEV_LAUNCH_UPDATE_DATA,
		KVM_SEV_LAUNCH_UPDATE_VMSA,
		KVM_SEV_LAUNCH_SECRET,
		KVM_SEV_LAUNCH_MEASURE,
		KVM_SEV_LAUNCH_FINISH,
		/* Guest migration commands (outgoing) */
		KVM_SEV_SEND_START,
		KVM_SEV_SEND_UPDATE_DATA,
		KVM_SEV_SEND_UPDATE_VMSA,
		KVM_SEV_SEND_FINISH,
		/* Guest migration commands (incoming) */
		KVM_SEV_RECEIVE_START,
		KVM_SEV_RECEIVE_UPDATE_DATA,
		KVM_SEV_RECEIVE_UPDATE_VMSA,
		KVM_SEV_RECEIVE_FINISH,
		/* Guest status and debug commands */
		KVM_SEV_GUEST_STATUS,
		KVM_SEV_DBG_DECRYPT,
		KVM_SEV_DBG_ENCRYPT,
		/* Guest certificates commands */
		KVM_SEV_CERT_EXPORT,

		KVM_SEV_NR_MAX,
		};

		struct kvm_sev_cmd {
		__u32 id;
		__u64 data;
		__u32 error;
		__u32 sev_fd;
		};

		struct kvm_sev_launch_start {
		__u32 handle;
		__u32 policy;
		__u64 dh_uaddr;
		__u32 dh_len;
		__u64 session_uaddr;
		__u32 session_len;
		};

		struct kvm_sev_launch_update_data {
		__u64 uaddr;
		__u32 len;
		};


		struct kvm_sev_launch_secret {
		__u64 hdr_uaddr;
		__u32 hdr_len;
		__u64 guest_uaddr;
		__u32 guest_len;
		__u64 trans_uaddr;
		__u32 trans_len;
		};

		struct kvm_sev_launch_measure {
		__u64 uaddr;
		__u32 len;
		};

		struct kvm_sev_guest_status {
		__u32 handle;
		__u32 policy;
		__u32 state;
		};

		struct kvm_sev_dbg {
		__u64 src_uaddr;
		__u64 dst_uaddr;
		__u32 len;
		};

		#define KVM_DEV_ASSIGN_ENABLE_IOMMU (1 << 0)
		#define KVM_DEV_ASSIGN_PCI_2_3 (1 << 1)
		#define KVM_DEV_ASSIGN_MASK_INTX (1 << 2)

Admin message