docs/amd-memory-encryption.txt

   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
   4 virtual machine (VMs) under the control of KVM. Encrypted VMs have their pages
   5 (code and data) secured such that only the guest itself has access to the
   6 unencrypted version. Each encrypted VM is associated with a unique encryption
   7 key; if its data is accessed to a different entity using a different key the
   8 encrypted guests data will be incorrectly decrypted, leading to unintelligible
   9 data.
  10
  11 The key management of this feature is handled by separate processor known as
  12 AMD secure processor (AMD-SP) which is present in AMD SOCs. Firmware running
  13 inside the AMD-SP provide commands to support common VM lifecycle. This
  14 includes commands for launching, snapshotting, migrating and debugging the
  15 encrypted guest. Those SEV command can be issued via KVM_MEMORY_ENCRYPT_OP
  16 ioctls.
  17
  18 Launching
  19 ---------
  20 Boot images (such as bios) must be encrypted before guest can be booted.
  21 MEMORY_ENCRYPT_OP ioctl provides commands to encrypt the images :LAUNCH_START,
  22 LAUNCH_UPDATE_DATA, LAUNCH_MEASURE and LAUNCH_FINISH. These four commands
  23 together generate a fresh memory encryption key for the VM, encrypt the boot
  24 images and provide a measurement than can be used as an attestation of the
  25 successful launch.
  26
  27 LAUNCH_START is called first to create a cryptographic launch context within
  28 the firmware. To create this context, guest owner must provides guest policy,
  29 its public Diffie-Hellman key (PDH) and session parameters. These inputs
  30 should be treated as binary blob and must be passed as-is to the SEV firmware.
  31
  32 The guest policy is passed as plaintext and hypervisor may able to read it
  33 but should not modify it (any modification of the policy bits will result
  34 in bad measurement). The guest policy is a 4-byte data structure containing
  35 several flags that restricts what can be done on running SEV guest.
  36 See KM Spec section 3 and 6.2 for more details.
  37
  38 The guest policy can be provided via the 'policy' property (see below)
  39
  40 # ${QEMU} \
  41    sev-guest,id=sev0,policy=0x1...\
  42
  43 Guest owners provided DH certificate and session parameters will be used to
  44 establish a cryptographic session with the guest owner to negotiate keys used
  45 for the attestation.
  46
  47 The DH certificate and session blob can be provided via 'dh-cert-file' and
  48 'session-file' property (see below
  49
  50 # ${QEMU} \
  51      sev-guest,id=sev0,dh-cert-file=<file1>,session-file=<file2>
  52
  53 LAUNCH_UPDATE_DATA encrypts the memory region using the cryptographic context
  54 created via LAUNCH_START command. If required, this command can be called
  55 multiple times to encrypt different memory regions. The command also calculates
  56 the measurement of the memory contents as it encrypts.
  57
  58 LAUNCH_MEASURE command can be used to retrieve the measurement of encrypted
  59 memory. This measurement is a signature of the memory contents that can be
  60 sent to the guest owner as an attestation that the memory was encrypted
  61 correctly by the firmware. The guest owner may wait to provide the guest
  62 confidential information until it can verify the attestation measurement.
  63 Since the guest owner knows the initial contents of the guest at boot, the
  64 attestation measurement can be verified by comparing it to what the guest owner
  65 expects.
  66
  67 LAUNCH_FINISH command finalizes the guest launch and destroy's the cryptographic
  68 context.
  69
  70 See SEV KM API Spec [1] 'Launching a guest' usage flow (Appendix A) for the
  71 complete flow chart.
  72
  73 To launch a SEV guest
  74
  75 # ${QEMU} \
  76     -machine ...,memory-encryption=sev0 \
  77     -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1
  78
  79 Debugging
  80 -----------
  81 Since memory contents of SEV guest is encrypted hence hypervisor access to the
  82 guest memory will get a cipher text. If guest policy allows debugging, then
  83 hypervisor can use DEBUG_DECRYPT and DEBUG_ENCRYPT commands access the guest
  84 memory region for debug purposes.  This is not supported in QEMU yet.
  85
  86 Snapshot/Restore
  87 -----------------
  88 TODO
  89
  90 Live Migration
  91 ----------------
  92 TODO
  93
  94 References
  95 -----------------
  96
  97 AMD Memory Encryption whitepaper:
  98 https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
  99
 100 Secure Encrypted Virtualization Key Management:
 101 [1] http://developer.amd.com/wordpress/media/2017/11/55766_SEV-KM-API_Specification.pdf
 102
 103 KVM Forum slides:
 104 http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf
 105
 106 AMD64 Architecture Programmer's Manual:
 107    http://support.amd.com/TechDocs/24593.pdf
 108    SME is section 7.10
 109    SEV is section 15.34