[mirror_qemu.git] / docs / amd-memory-encryption.txt

Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.

SEV is an extension to the AMD-V architecture which supports running encrypted
virtual machines (VMs) under the control of KVM. Encrypted VMs have their pages
(code and data) secured such that only the guest itself has access to the
unencrypted version. Each encrypted VM is associated with a unique encryption
key; if its data is accessed by a different entity using a different key the
encrypted guests data will be incorrectly decrypted, leading to unintelligible
data.

Key management for this feature is handled by a separate processor known as the
AMD secure processor (AMD-SP), which is present in AMD SOCs. Firmware running
inside the AMD-SP provides commands to support a common VM lifecycle. This
includes commands for launching, snapshotting, migrating and debugging the
encrypted guest. These SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP
ioctls.

Secure Encrypted Virtualization - Encrypted State (SEV-ES) builds on the SEV
support to additionally protect the guest register state. In order to allow a
hypervisor to perform functions on behalf of a guest, there is architectural
support for notifying a guest's operating system when certain types of VMEXITs
are about to occur. This allows the guest to selectively share information with
the hypervisor to satisfy the requested function.

Launching
---------
Boot images (such as bios) must be encrypted before a guest can be booted. The
MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images: LAUNCH_START,
LAUNCH_UPDATE_DATA, LAUNCH_MEASURE and LAUNCH_FINISH. These four commands
together generate a fresh memory encryption key for the VM, encrypt the boot
images and provide a measurement than can be used as an attestation of a
successful launch.

For a SEV-ES guest, the LAUNCH_UPDATE_VMSA command is also used to encrypt the
guest register state, or VM save area (VMSA), for all of the guest vCPUs.

LAUNCH_START is called first to create a cryptographic launch context within
the firmware. To create this context, guest owner must provide a guest policy,
its public Diffie-Hellman key (PDH) and session parameters. These inputs
should be treated as a binary blob and must be passed as-is to the SEV firmware.

The guest policy is passed as plaintext. A hypervisor may choose to read it,
but should not modify it (any modification of the policy bits will result
in bad measurement). The guest policy is a 4-byte data structure containing
several flags that restricts what can be done on a running SEV guest.
See KM Spec section 3 and 6.2 for more details.

The guest policy can be provided via the 'policy' property (see below)

# ${QEMU} \
   sev-guest,id=sev0,policy=0x1...\

Setting the "SEV-ES required" policy bit (bit 2) will launch the guest as a
SEV-ES guest (see below)

# ${QEMU} \
   sev-guest,id=sev0,policy=0x5...\

The guest owner provided DH certificate and session parameters will be used to
establish a cryptographic session with the guest owner to negotiate keys used
for the attestation.

The DH certificate and session blob can be provided via the 'dh-cert-file' and
'session-file' properties (see below)

# ${QEMU} \
     sev-guest,id=sev0,dh-cert-file=<file1>,session-file=<file2>

LAUNCH_UPDATE_DATA encrypts the memory region using the cryptographic context
created via the LAUNCH_START command. If required, this command can be called
multiple times to encrypt different memory regions. The command also calculates
the measurement of the memory contents as it encrypts.

LAUNCH_UPDATE_VMSA encrypts all the vCPU VMSAs for a SEV-ES guest using the
cryptographic context created via the LAUNCH_START command. The command also
calculates the measurement of the VMSAs as it encrypts them.

LAUNCH_MEASURE can be used to retrieve the measurement of encrypted memory and,
for a SEV-ES guest, encrypted VMSAs. This measurement is a signature of the
memory contents and, for a SEV-ES guest, the VMSA contents, that can be sent
to the guest owner as an attestation that the memory and VMSAs were encrypted
correctly by the firmware. The guest owner may wait to provide the guest
confidential information until it can verify the attestation measurement.
Since the guest owner knows the initial contents of the guest at boot, the
attestation measurement can be verified by comparing it to what the guest owner
expects.

LAUNCH_FINISH finalizes the guest launch and destroys the cryptographic
context.

See SEV KM API Spec [1] 'Launching a guest' usage flow (Appendix A) for the
complete flow chart.

To launch a SEV guest

# ${QEMU} \
    -machine ...,confidential-guest-support=sev0 \
    -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1

To launch a SEV-ES guest

# ${QEMU} \
    -machine ...,confidential-guest-support=sev0 \
    -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1,policy=0x5

An SEV-ES guest has some restrictions as compared to a SEV guest. Because the
guest register state is encrypted and cannot be updated by the VMM/hypervisor,
a SEV-ES guest:
 - Does not support SMM - SMM support requires updating the guest register
   state.
 - Does not support reboot - a system reset requires updating the guest register
   state.
 - Requires in-kernel irqchip - the burden is placed on the hypervisor to
   manage booting APs.

Debugging
-----------
Since the memory contents of a SEV guest are encrypted, hypervisor access to
the guest memory will return cipher text. If the guest policy allows debugging,
then a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access
the guest memory region for debug purposes.  This is not supported in QEMU yet.

Snapshot/Restore
-----------------
TODO

Live Migration
----------------
TODO

References
-----------------

AMD Memory Encryption whitepaper:
https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf

Secure Encrypted Virtualization Key Management:
[1] http://developer.amd.com/wordpress/media/2017/11/55766_SEV-KM-API_Specification.pdf

KVM Forum slides:
http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf
https://www.linux-kvm.org/images/9/94/Extending-Secure-Encrypted-Virtualization-with-SEV-ES-Thomas-Lendacky-AMD.pdf

AMD64 Architecture Programmer's Manual:
   http://support.amd.com/TechDocs/24593.pdf
   SME is section 7.10
   SEV is section 15.34
   SEV-ES is section 15.35
Commit	Line	Data
9b02f7bf BS	1	Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
	2
	3	SEV is an extension to the AMD-V architecture which supports running encrypted
f538adec	4	virtual machines (VMs) under the control of KVM. Encrypted VMs have their pages
9b02f7bf BS	5	(code and data) secured such that only the guest itself has access to the
9b02f7bf BS	6	unencrypted version. Each encrypted VM is associated with a unique encryption
f538adec	7	key; if its data is accessed by a different entity using a different key the
9b02f7bf BS	8	encrypted guests data will be incorrectly decrypted, leading to unintelligible
	9	data.
	10
f538adec TL	11	Key management for this feature is handled by a separate processor known as the
	12	AMD secure processor (AMD-SP), which is present in AMD SOCs. Firmware running
	13	inside the AMD-SP provides commands to support a common VM lifecycle. This
9b02f7bf	14	includes commands for launching, snapshotting, migrating and debugging the
f538adec	15	encrypted guest. These SEV commands can be issued via KVM_MEMORY_ENCRYPT_OP
9b02f7bf BS	16	ioctls.
9b02f7bf BS	17
61b7d709 TL	18	Secure Encrypted Virtualization - Encrypted State (SEV-ES) builds on the SEV
	19	support to additionally protect the guest register state. In order to allow a
	20	hypervisor to perform functions on behalf of a guest, there is architectural
	21	support for notifying a guest's operating system when certain types of VMEXITs
	22	are about to occur. This allows the guest to selectively share information with
	23	the hypervisor to satisfy the requested function.
	24
9b02f7bf BS	25	Launching
9b02f7bf BS	26	---------
f538adec TL	27	Boot images (such as bios) must be encrypted before a guest can be booted. The
f538adec TL	28	MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images: LAUNCH_START,
9b02f7bf BS	29	LAUNCH_UPDATE_DATA, LAUNCH_MEASURE and LAUNCH_FINISH. These four commands
9b02f7bf BS	30	together generate a fresh memory encryption key for the VM, encrypt the boot
f538adec	31	images and provide a measurement than can be used as an attestation of a
9b02f7bf BS	32	successful launch.
9b02f7bf BS	33
61b7d709 TL	34	For a SEV-ES guest, the LAUNCH_UPDATE_VMSA command is also used to encrypt the
	35	guest register state, or VM save area (VMSA), for all of the guest vCPUs.
	36
9b02f7bf	37	LAUNCH_START is called first to create a cryptographic launch context within
f538adec	38	the firmware. To create this context, guest owner must provide a guest policy,
9b02f7bf	39	its public Diffie-Hellman key (PDH) and session parameters. These inputs
f538adec	40	should be treated as a binary blob and must be passed as-is to the SEV firmware.
9b02f7bf	41
f538adec	42	The guest policy is passed as plaintext. A hypervisor may choose to read it,
9b02f7bf BS	43	but should not modify it (any modification of the policy bits will result
9b02f7bf BS	44	in bad measurement). The guest policy is a 4-byte data structure containing
f538adec	45	several flags that restricts what can be done on a running SEV guest.
9b02f7bf BS	46	See KM Spec section 3 and 6.2 for more details.
9b02f7bf BS	47
a9b4942f BS	48	The guest policy can be provided via the 'policy' property (see below)
	49
	50	# ${QEMU} \
	51	sev-guest,id=sev0,policy=0x1...\
	52
61b7d709 TL	53	Setting the "SEV-ES required" policy bit (bit 2) will launch the guest as a
	54	SEV-ES guest (see below)
	55
	56	# ${QEMU} \
	57	sev-guest,id=sev0,policy=0x5...\
	58
f538adec	59	The guest owner provided DH certificate and session parameters will be used to
9b02f7bf BS	60	establish a cryptographic session with the guest owner to negotiate keys used
	61	for the attestation.
	62
f538adec TL	63	The DH certificate and session blob can be provided via the 'dh-cert-file' and
f538adec TL	64	'session-file' properties (see below)
a9b4942f BS	65
	66	# ${QEMU} \
	67	sev-guest,id=sev0,dh-cert-file=<file1>,session-file=<file2>
	68
9b02f7bf	69	LAUNCH_UPDATE_DATA encrypts the memory region using the cryptographic context
f538adec	70	created via the LAUNCH_START command. If required, this command can be called
9b02f7bf BS	71	multiple times to encrypt different memory regions. The command also calculates
	72	the measurement of the memory contents as it encrypts.
	73
61b7d709 TL	74	LAUNCH_UPDATE_VMSA encrypts all the vCPU VMSAs for a SEV-ES guest using the
	75	cryptographic context created via the LAUNCH_START command. The command also
	76	calculates the measurement of the VMSAs as it encrypts them.
	77
	78	LAUNCH_MEASURE can be used to retrieve the measurement of encrypted memory and,
	79	for a SEV-ES guest, encrypted VMSAs. This measurement is a signature of the
	80	memory contents and, for a SEV-ES guest, the VMSA contents, that can be sent
	81	to the guest owner as an attestation that the memory and VMSAs were encrypted
	82	correctly by the firmware. The guest owner may wait to provide the guest
	83	confidential information until it can verify the attestation measurement.
	84	Since the guest owner knows the initial contents of the guest at boot, the
	85	attestation measurement can be verified by comparing it to what the guest owner
	86	expects.
9b02f7bf	87
f538adec	88	LAUNCH_FINISH finalizes the guest launch and destroys the cryptographic
9b02f7bf BS	89	context.
	90
	91	See SEV KM API Spec [1] 'Launching a guest' usage flow (Appendix A) for the
	92	complete flow chart.
	93
a9b4942f BS	94	To launch a SEV guest
	95
	96	# ${QEMU} \
64d19f33	97	-machine ...,confidential-guest-support=sev0 \
a9b4942f BS	98	-object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1
a9b4942f BS	99
61b7d709 TL	100	To launch a SEV-ES guest
	101
	102	# ${QEMU} \
	103	-machine ...,confidential-guest-support=sev0 \
	104	-object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1,policy=0x5
	105
	106	An SEV-ES guest has some restrictions as compared to a SEV guest. Because the
	107	guest register state is encrypted and cannot be updated by the VMM/hypervisor,
	108	a SEV-ES guest:
	109	- Does not support SMM - SMM support requires updating the guest register
	110	state.
	111	- Does not support reboot - a system reset requires updating the guest register
	112	state.
	113	- Requires in-kernel irqchip - the burden is placed on the hypervisor to
	114	manage booting APs.
	115
9b02f7bf BS	116	Debugging
9b02f7bf BS	117	-----------
f538adec TL	118	Since the memory contents of a SEV guest are encrypted, hypervisor access to
	119	the guest memory will return cipher text. If the guest policy allows debugging,
	120	then a hypervisor can use the DEBUG_DECRYPT and DEBUG_ENCRYPT commands to access
	121	the guest memory region for debug purposes. This is not supported in QEMU yet.
9b02f7bf BS	122
	123	Snapshot/Restore
	124	-----------------
	125	TODO
	126
	127	Live Migration
	128	----------------
	129	TODO
	130
	131	References
	132	-----------------
	133
	134	AMD Memory Encryption whitepaper:
4aeae1d4	135	https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
9b02f7bf	136
806be373	137	Secure Encrypted Virtualization Key Management:
4aeae1d4	138	[1] http://developer.amd.com/wordpress/media/2017/11/55766_SEV-KM-API_Specification.pdf
9b02f7bf BS	139
	140	KVM Forum slides:
	141	http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf
61b7d709	142	https://www.linux-kvm.org/images/9/94/Extending-Secure-Encrypted-Virtualization-with-SEV-ES-Thomas-Lendacky-AMD.pdf
9b02f7bf BS	143
	144	AMD64 Architecture Programmer's Manual:
	145	http://support.amd.com/TechDocs/24593.pdf
	146	SME is section 7.10
	147	SEV is section 15.34
61b7d709	148	SEV-ES is section 15.35