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

   1 ======================================
   2 Secure Encrypted Virtualization (SEV)
   3 ======================================
   4
   5 Overview
   6 ========
   7
   8 Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
   9
  10 SEV is an extension to the AMD-V architecture which supports running
  11 virtual machines (VMs) under the control of a hypervisor. When enabled,
  12 the memory contents of a VM will be transparently encrypted with a key
  13 unique to that VM.
  14
  15 The hypervisor can determine the SEV support through the CPUID
  16 instruction. The CPUID function 0x8000001f reports information related
  17 to SEV::
  18
  19         0x8000001f[eax]:
  20                         Bit[1]  indicates support for SEV
  21             ...
  22                   [ecx]:
  23                         Bits[31:0]  Number of encrypted guests supported simultaneously
  24
  25 If support for SEV is present, MSR 0xc001_0010 (MSR_K8_SYSCFG) and MSR 0xc001_0015
  26 (MSR_K7_HWCR) can be used to determine if it can be enabled::
  27
  28         0xc001_0010:
  29                 Bit[23]    1 = memory encryption can be enabled
  30                            0 = memory encryption can not be enabled
  31
  32         0xc001_0015:
  33                 Bit[0]     1 = memory encryption can be enabled
  34                            0 = memory encryption can not be enabled
  35
  36 When SEV support is available, it can be enabled in a specific VM by
  37 setting the SEV bit before executing VMRUN.::
  38
  39         VMCB[0x90]:
  40                 Bit[1]      1 = SEV is enabled
  41                             0 = SEV is disabled
  42
  43 SEV hardware uses ASIDs to associate a memory encryption key with a VM.
  44 Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value
  45 defined in the CPUID 0x8000001f[ecx] field.
  46
  47 SEV Key Management
  48 ==================
  49
  50 The SEV guest key management is handled by a separate processor called the AMD
  51 Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure
  52 key management interface to perform common hypervisor activities such as
  53 encrypting bootstrap code, snapshot, migrating and debugging the guest. For more
  54 information, see the SEV Key Management spec [api-spec]_
  55
  56 KVM implements the following commands to support common lifecycle events of SEV
  57 guests, such as launching, running, snapshotting, migrating and decommissioning.
  58
  59 1. KVM_SEV_INIT
  60 ---------------
  61
  62 The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform
  63 context. In a typical workflow, this command should be the first command issued.
  64
  65 Returns: 0 on success, -negative on error
  66
  67 2. KVM_SEV_LAUNCH_START
  68 -----------------------
  69
  70 The KVM_SEV_LAUNCH_START command is used for creating the memory encryption
  71 context. To create the encryption context, user must provide a guest policy,
  72 the owner's public Diffie-Hellman (PDH) key and session information.
  73
  74 Parameters: struct  kvm_sev_launch_start (in/out)
  75
  76 Returns: 0 on success, -negative on error
  77
  78 ::
  79
  80         struct kvm_sev_launch_start {
  81                 __u32 handle;           /* if zero then firmware creates a new handle */
  82                 __u32 policy;           /* guest's policy */
  83
  84                 __u64 dh_uaddr;         /* userspace address pointing to the guest owner's PDH key */
  85                 __u32 dh_len;
  86
  87                 __u64 session_addr;     /* userspace address which points to the guest session information */
  88                 __u32 session_len;
  89         };
  90
  91 On success, the 'handle' field contains a new handle and on error, a negative value.
  92
  93 For more details, see SEV spec Section 6.2.
  94
  95 3. KVM_SEV_LAUNCH_UPDATE_DATA
  96 -----------------------------
  97
  98 The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also
  99 calculates a measurement of the memory contents. The measurement is a signature
 100 of the memory contents that can be sent to the guest owner as an attestation
 101 that the memory was encrypted correctly by the firmware.
 102
 103 Parameters (in): struct  kvm_sev_launch_update_data
 104
 105 Returns: 0 on success, -negative on error
 106
 107 ::
 108
 109         struct kvm_sev_launch_update {
 110                 __u64 uaddr;    /* userspace address to be encrypted (must be 16-byte aligned) */
 111                 __u32 len;      /* length of the data to be encrypted (must be 16-byte aligned) */
 112         };
 113
 114 For more details, see SEV spec Section 6.3.
 115
 116 4. KVM_SEV_LAUNCH_MEASURE
 117 -------------------------
 118
 119 The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the
 120 data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may
 121 wait to provide the guest with confidential information until it can verify the
 122 measurement. Since the guest owner knows the initial contents of the guest at
 123 boot, the measurement can be verified by comparing it to what the guest owner
 124 expects.
 125
 126 Parameters (in): struct  kvm_sev_launch_measure
 127
 128 Returns: 0 on success, -negative on error
 129
 130 ::
 131
 132         struct kvm_sev_launch_measure {
 133                 __u64 uaddr;    /* where to copy the measurement */
 134                 __u32 len;      /* length of measurement blob */
 135         };
 136
 137 For more details on the measurement verification flow, see SEV spec Section 6.4.
 138
 139 5. KVM_SEV_LAUNCH_FINISH
 140 ------------------------
 141
 142 After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be
 143 issued to make the guest ready for the execution.
 144
 145 Returns: 0 on success, -negative on error
 146
 147 6. KVM_SEV_GUEST_STATUS
 148 -----------------------
 149
 150 The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a
 151 SEV-enabled guest.
 152
 153 Parameters (out): struct kvm_sev_guest_status
 154
 155 Returns: 0 on success, -negative on error
 156
 157 ::
 158
 159         struct kvm_sev_guest_status {
 160                 __u32 handle;   /* guest handle */
 161                 __u32 policy;   /* guest policy */
 162                 __u8 state;     /* guest state (see enum below) */
 163         };
 164
 165 SEV guest state:
 166
 167 ::
 168
 169         enum {
 170         SEV_STATE_INVALID = 0;
 171         SEV_STATE_LAUNCHING,    /* guest is currently being launched */
 172         SEV_STATE_SECRET,       /* guest is being launched and ready to accept the ciphertext data */
 173         SEV_STATE_RUNNING,      /* guest is fully launched and running */
 174         SEV_STATE_RECEIVING,    /* guest is being migrated in from another SEV machine */
 175         SEV_STATE_SENDING       /* guest is getting migrated out to another SEV machine */
 176         };
 177
 178 7. KVM_SEV_DBG_DECRYPT
 179 ----------------------
 180
 181 The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the
 182 firmware to decrypt the data at the given memory region.
 183
 184 Parameters (in): struct kvm_sev_dbg
 185
 186 Returns: 0 on success, -negative on error
 187
 188 ::
 189
 190         struct kvm_sev_dbg {
 191                 __u64 src_uaddr;        /* userspace address of data to decrypt */
 192                 __u64 dst_uaddr;        /* userspace address of destination */
 193                 __u32 len;              /* length of memory region to decrypt */
 194         };
 195
 196 The command returns an error if the guest policy does not allow debugging.
 197
 198 8. KVM_SEV_DBG_ENCRYPT
 199 ----------------------
 200
 201 The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the
 202 firmware to encrypt the data at the given memory region.
 203
 204 Parameters (in): struct kvm_sev_dbg
 205
 206 Returns: 0 on success, -negative on error
 207
 208 ::
 209
 210         struct kvm_sev_dbg {
 211                 __u64 src_uaddr;        /* userspace address of data to encrypt */
 212                 __u64 dst_uaddr;        /* userspace address of destination */
 213                 __u32 len;              /* length of memory region to encrypt */
 214         };
 215
 216 The command returns an error if the guest policy does not allow debugging.
 217
 218 9. KVM_SEV_LAUNCH_SECRET
 219 ------------------------
 220
 221 The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret
 222 data after the measurement has been validated by the guest owner.
 223
 224 Parameters (in): struct kvm_sev_launch_secret
 225
 226 Returns: 0 on success, -negative on error
 227
 228 ::
 229
 230         struct kvm_sev_launch_secret {
 231                 __u64 hdr_uaddr;        /* userspace address containing the packet header */
 232                 __u32 hdr_len;
 233
 234                 __u64 guest_uaddr;      /* the guest memory region where the secret should be injected */
 235                 __u32 guest_len;
 236
 237                 __u64 trans_uaddr;      /* the hypervisor memory region which contains the secret */
 238                 __u32 trans_len;
 239         };
 240
 241 References
 242 ==========
 243
 244
 245 See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info.
 246
 247 .. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
 248 .. [api-spec] http://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf
 249 .. [amd-apm] http://support.amd.com/TechDocs/24593.pdf (section 15.34)
 250 .. [kvm-forum]  http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf