docs: add AMD Secure Encrypted Virtualization (SEV)

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.  This is not supported in QEMU yet.

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