Create a documentation entry to describe the AMD Secure Encrypted Virtualization (SEV) feature.
Cc: Paolo Bonzini <pbonz...@redhat.com> Signed-off-by: Brijesh Singh <brijesh.si...@amd.com> --- docs/amd-memory-encryption.txt | 92 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/amd-memory-encryption.txt diff --git a/docs/amd-memory-encryption.txt b/docs/amd-memory-encryption.txt new file mode 100644 index 000000000000..72a92b6c6353 --- /dev/null +++ b/docs/amd-memory-encryption.txt @@ -0,0 +1,92 @@ +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 machine (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 to a different entity using a different key the +encrypted guests data will be incorrectly decrypted, leading to unintelligible +data. + +The key management of this feature is handled by separate processor known as +AMD secure processor (AMD-SP) which is present in AMD SOCs. Firmware running +inside the AMD-SP provide commands to support common VM lifecycle. This +includes commands for launching, snapshotting, migrating and debugging the +encrypted guest. Those SEV command can be issued via KVM_MEMORY_ENCRYPT_OP +ioctls. + +Launching +--------- +Boot images (such as bios) must be encrypted before guest can be booted. +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 the +successful launch. + +LAUNCH_START is called first to create a cryptographic launch context within +the firmware. To create this context, guest owner must provides guest policy, +its public Diffie-Hellman key (PDH) and session parameters. These inputs +should be treated as binary blob and must be passed as-is to the SEV firmware. + +The guest policy is passed as plaintext and hypervisor may able 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 running SEV guest. +See KM Spec section 3 and 6.2 for more details. + +Guest owners 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. + +LAUNCH_UPDATE_DATA encrypts the memory region using the cryptographic context +created via 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_MEASURE command can be used to retrieve the measurement of encrypted +memory. This 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. 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 command finalizes the guest launch and destroy's the cryptographic +context. + +See SEV KM API Spec [1] 'Launching a guest' usage flow (Appendix A) for the +complete flow chart. + +Debugging +----------- +Since memory contents of SEV guest is encrypted hence hypervisor access to the +guest memory will get a cipher text. If guest policy allows debugging, then +hypervisor can use DEBUG_DECRYPT and DEBUG_ENCRYPT commands access the guest +memory region for debug purposes. + +Snapshot/Restore +----------------- +TODO + +Live Migration +---------------- +TODO + +References +----------------- + +AMD Memory Encryption whitepaper: +http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf + +Secure Encrypted Virutualization Key Management: +[1] http://support.amd.com/TechDocs/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 + +AMD64 Architecture Programmer's Manual: + http://support.amd.com/TechDocs/24593.pdf + SME is section 7.10 + SEV is section 15.34 -- 2.14.3
