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

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======================================
   4 Secure Encrypted Virtualization (SEV)
   5 ======================================
   6
   7 Overview
   8 ========
   9
  10 Secure Encrypted Virtualization (SEV) is a feature found on AMD processors.
  11
  12 SEV is an extension to the AMD-V architecture which supports running
  13 virtual machines (VMs) under the control of a hypervisor. When enabled,
  14 the memory contents of a VM will be transparently encrypted with a key
  15 unique to that VM.
  16
  17 The hypervisor can determine the SEV support through the CPUID
  18 instruction. The CPUID function 0x8000001f reports information related
  19 to SEV::
  20
  21         0x8000001f[eax]:
  22                         Bit[1]  indicates support for SEV
  23             ...
  24                   [ecx]:
  25                         Bits[31:0]  Number of encrypted guests supported simultaneously
  26
  27 If support for SEV is present, MSR 0xc001_0010 (MSR_AMD64_SYSCFG) and MSR 0xc001_0015
  28 (MSR_K7_HWCR) can be used to determine if it can be enabled::
  29
  30         0xc001_0010:
  31                 Bit[23]    1 = memory encryption can be enabled
  32                            0 = memory encryption can not be enabled
  33
  34         0xc001_0015:
  35                 Bit[0]     1 = memory encryption can be enabled
  36                            0 = memory encryption can not be enabled
  37
  38 When SEV support is available, it can be enabled in a specific VM by
  39 setting the SEV bit before executing VMRUN.::
  40
  41         VMCB[0x90]:
  42                 Bit[1]      1 = SEV is enabled
  43                             0 = SEV is disabled
  44
  45 SEV hardware uses ASIDs to associate a memory encryption key with a VM.
  46 Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value
  47 defined in the CPUID 0x8000001f[ecx] field.
  48
  49 SEV Key Management
  50 ==================
  51
  52 The SEV guest key management is handled by a separate processor called the AMD
  53 Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure
  54 key management interface to perform common hypervisor activities such as
  55 encrypting bootstrap code, snapshot, migrating and debugging the guest. For more
  56 information, see the SEV Key Management spec [api-spec]_
  57
  58 The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP.  If the argument
  59 to KVM_MEMORY_ENCRYPT_OP is NULL, the ioctl returns 0 if SEV is enabled
  60 and ``ENOTTY`` if it is disabled (on some older versions of Linux,
  61 the ioctl runs normally even with a NULL argument, and therefore will
  62 likely return ``EFAULT``).  If non-NULL, the argument to KVM_MEMORY_ENCRYPT_OP
  63 must be a struct kvm_sev_cmd::
  64
  65        struct kvm_sev_cmd {
  66                __u32 id;
  67                __u64 data;
  68                __u32 error;
  69                __u32 sev_fd;
  70        };
  71
  72
  73 The ``id`` field contains the subcommand, and the ``data`` field points to
  74 another struct containing arguments specific to command.  The ``sev_fd``
  75 should point to a file descriptor that is opened on the ``/dev/sev``
  76 device, if needed (see individual commands).
  77
  78 On output, ``error`` is zero on success, or an error code.  Error codes
  79 are defined in ``<linux/psp-dev.h>``.
  80
  81 KVM implements the following commands to support common lifecycle events of SEV
  82 guests, such as launching, running, snapshotting, migrating and decommissioning.
  83
  84 1. KVM_SEV_INIT
  85 ---------------
  86
  87 The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform
  88 context. In a typical workflow, this command should be the first command issued.
  89
  90 The firmware can be initialized either by using its own non-volatile storage or
  91 the OS can manage the NV storage for the firmware using the module parameter
  92 ``init_ex_path``. If the file specified by ``init_ex_path`` does not exist or
  93 is invalid, the OS will create or override the file with output from PSP.
  94
  95 Returns: 0 on success, -negative on error
  96
  97 2. KVM_SEV_LAUNCH_START
  98 -----------------------
  99
 100 The KVM_SEV_LAUNCH_START command is used for creating the memory encryption
 101 context. To create the encryption context, user must provide a guest policy,
 102 the owner's public Diffie-Hellman (PDH) key and session information.
 103
 104 Parameters: struct  kvm_sev_launch_start (in/out)
 105
 106 Returns: 0 on success, -negative on error
 107
 108 ::
 109
 110         struct kvm_sev_launch_start {
 111                 __u32 handle;           /* if zero then firmware creates a new handle */
 112                 __u32 policy;           /* guest's policy */
 113
 114                 __u64 dh_uaddr;         /* userspace address pointing to the guest owner's PDH key */
 115                 __u32 dh_len;
 116
 117                 __u64 session_addr;     /* userspace address which points to the guest session information */
 118                 __u32 session_len;
 119         };
 120
 121 On success, the 'handle' field contains a new handle and on error, a negative value.
 122
 123 KVM_SEV_LAUNCH_START requires the ``sev_fd`` field to be valid.
 124
 125 For more details, see SEV spec Section 6.2.
 126
 127 3. KVM_SEV_LAUNCH_UPDATE_DATA
 128 -----------------------------
 129
 130 The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also
 131 calculates a measurement of the memory contents. The measurement is a signature
 132 of the memory contents that can be sent to the guest owner as an attestation
 133 that the memory was encrypted correctly by the firmware.
 134
 135 Parameters (in): struct  kvm_sev_launch_update_data
 136
 137 Returns: 0 on success, -negative on error
 138
 139 ::
 140
 141         struct kvm_sev_launch_update {
 142                 __u64 uaddr;    /* userspace address to be encrypted (must be 16-byte aligned) */
 143                 __u32 len;      /* length of the data to be encrypted (must be 16-byte aligned) */
 144         };
 145
 146 For more details, see SEV spec Section 6.3.
 147
 148 4. KVM_SEV_LAUNCH_MEASURE
 149 -------------------------
 150
 151 The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the
 152 data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may
 153 wait to provide the guest with confidential information until it can verify the
 154 measurement. Since the guest owner knows the initial contents of the guest at
 155 boot, the measurement can be verified by comparing it to what the guest owner
 156 expects.
 157
 158 If len is zero on entry, the measurement blob length is written to len and
 159 uaddr is unused.
 160
 161 Parameters (in): struct  kvm_sev_launch_measure
 162
 163 Returns: 0 on success, -negative on error
 164
 165 ::
 166
 167         struct kvm_sev_launch_measure {
 168                 __u64 uaddr;    /* where to copy the measurement */
 169                 __u32 len;      /* length of measurement blob */
 170         };
 171
 172 For more details on the measurement verification flow, see SEV spec Section 6.4.
 173
 174 5. KVM_SEV_LAUNCH_FINISH
 175 ------------------------
 176
 177 After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be
 178 issued to make the guest ready for the execution.
 179
 180 Returns: 0 on success, -negative on error
 181
 182 6. KVM_SEV_GUEST_STATUS
 183 -----------------------
 184
 185 The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a
 186 SEV-enabled guest.
 187
 188 Parameters (out): struct kvm_sev_guest_status
 189
 190 Returns: 0 on success, -negative on error
 191
 192 ::
 193
 194         struct kvm_sev_guest_status {
 195                 __u32 handle;   /* guest handle */
 196                 __u32 policy;   /* guest policy */
 197                 __u8 state;     /* guest state (see enum below) */
 198         };
 199
 200 SEV guest state:
 201
 202 ::
 203
 204         enum {
 205         SEV_STATE_INVALID = 0;
 206         SEV_STATE_LAUNCHING,    /* guest is currently being launched */
 207         SEV_STATE_SECRET,       /* guest is being launched and ready to accept the ciphertext data */
 208         SEV_STATE_RUNNING,      /* guest is fully launched and running */
 209         SEV_STATE_RECEIVING,    /* guest is being migrated in from another SEV machine */
 210         SEV_STATE_SENDING       /* guest is getting migrated out to another SEV machine */
 211         };
 212
 213 7. KVM_SEV_DBG_DECRYPT
 214 ----------------------
 215
 216 The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the
 217 firmware to decrypt the data at the given memory region.
 218
 219 Parameters (in): struct kvm_sev_dbg
 220
 221 Returns: 0 on success, -negative on error
 222
 223 ::
 224
 225         struct kvm_sev_dbg {
 226                 __u64 src_uaddr;        /* userspace address of data to decrypt */
 227                 __u64 dst_uaddr;        /* userspace address of destination */
 228                 __u32 len;              /* length of memory region to decrypt */
 229         };
 230
 231 The command returns an error if the guest policy does not allow debugging.
 232
 233 8. KVM_SEV_DBG_ENCRYPT
 234 ----------------------
 235
 236 The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the
 237 firmware to encrypt the data at the given memory region.
 238
 239 Parameters (in): struct kvm_sev_dbg
 240
 241 Returns: 0 on success, -negative on error
 242
 243 ::
 244
 245         struct kvm_sev_dbg {
 246                 __u64 src_uaddr;        /* userspace address of data to encrypt */
 247                 __u64 dst_uaddr;        /* userspace address of destination */
 248                 __u32 len;              /* length of memory region to encrypt */
 249         };
 250
 251 The command returns an error if the guest policy does not allow debugging.
 252
 253 9. KVM_SEV_LAUNCH_SECRET
 254 ------------------------
 255
 256 The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret
 257 data after the measurement has been validated by the guest owner.
 258
 259 Parameters (in): struct kvm_sev_launch_secret
 260
 261 Returns: 0 on success, -negative on error
 262
 263 ::
 264
 265         struct kvm_sev_launch_secret {
 266                 __u64 hdr_uaddr;        /* userspace address containing the packet header */
 267                 __u32 hdr_len;
 268
 269                 __u64 guest_uaddr;      /* the guest memory region where the secret should be injected */
 270                 __u32 guest_len;
 271
 272                 __u64 trans_uaddr;      /* the hypervisor memory region which contains the secret */
 273                 __u32 trans_len;
 274         };
 275
 276 10. KVM_SEV_GET_ATTESTATION_REPORT
 277 ----------------------------------
 278
 279 The KVM_SEV_GET_ATTESTATION_REPORT command can be used by the hypervisor to query the attestation
 280 report containing the SHA-256 digest of the guest memory and VMSA passed through the KVM_SEV_LAUNCH
 281 commands and signed with the PEK. The digest returned by the command should match the digest
 282 used by the guest owner with the KVM_SEV_LAUNCH_MEASURE.
 283
 284 If len is zero on entry, the measurement blob length is written to len and
 285 uaddr is unused.
 286
 287 Parameters (in): struct kvm_sev_attestation
 288
 289 Returns: 0 on success, -negative on error
 290
 291 ::
 292
 293         struct kvm_sev_attestation_report {
 294                 __u8 mnonce[16];        /* A random mnonce that will be placed in the report */
 295
 296                 __u64 uaddr;            /* userspace address where the report should be copied */
 297                 __u32 len;
 298         };
 299
 300 11. KVM_SEV_SEND_START
 301 ----------------------
 302
 303 The KVM_SEV_SEND_START command can be used by the hypervisor to create an
 304 outgoing guest encryption context.
 305
 306 If session_len is zero on entry, the length of the guest session information is
 307 written to session_len and all other fields are not used.
 308
 309 Parameters (in): struct kvm_sev_send_start
 310
 311 Returns: 0 on success, -negative on error
 312
 313 ::
 314
 315         struct kvm_sev_send_start {
 316                 __u32 policy;                 /* guest policy */
 317
 318                 __u64 pdh_cert_uaddr;         /* platform Diffie-Hellman certificate */
 319                 __u32 pdh_cert_len;
 320
 321                 __u64 plat_certs_uaddr;        /* platform certificate chain */
 322                 __u32 plat_certs_len;
 323
 324                 __u64 amd_certs_uaddr;        /* AMD certificate */
 325                 __u32 amd_certs_len;
 326
 327                 __u64 session_uaddr;          /* Guest session information */
 328                 __u32 session_len;
 329         };
 330
 331 12. KVM_SEV_SEND_UPDATE_DATA
 332 ----------------------------
 333
 334 The KVM_SEV_SEND_UPDATE_DATA command can be used by the hypervisor to encrypt the
 335 outgoing guest memory region with the encryption context creating using
 336 KVM_SEV_SEND_START.
 337
 338 If hdr_len or trans_len are zero on entry, the length of the packet header and
 339 transport region are written to hdr_len and trans_len respectively, and all
 340 other fields are not used.
 341
 342 Parameters (in): struct kvm_sev_send_update_data
 343
 344 Returns: 0 on success, -negative on error
 345
 346 ::
 347
 348         struct kvm_sev_launch_send_update_data {
 349                 __u64 hdr_uaddr;        /* userspace address containing the packet header */
 350                 __u32 hdr_len;
 351
 352                 __u64 guest_uaddr;      /* the source memory region to be encrypted */
 353                 __u32 guest_len;
 354
 355                 __u64 trans_uaddr;      /* the destination memory region  */
 356                 __u32 trans_len;
 357         };
 358
 359 13. KVM_SEV_SEND_FINISH
 360 ------------------------
 361
 362 After completion of the migration flow, the KVM_SEV_SEND_FINISH command can be
 363 issued by the hypervisor to delete the encryption context.
 364
 365 Returns: 0 on success, -negative on error
 366
 367 14. KVM_SEV_SEND_CANCEL
 368 ------------------------
 369
 370 After completion of SEND_START, but before SEND_FINISH, the source VMM can issue the
 371 SEND_CANCEL command to stop a migration. This is necessary so that a cancelled
 372 migration can restart with a new target later.
 373
 374 Returns: 0 on success, -negative on error
 375
 376 15. KVM_SEV_RECEIVE_START
 377 -------------------------
 378
 379 The KVM_SEV_RECEIVE_START command is used for creating the memory encryption
 380 context for an incoming SEV guest. To create the encryption context, the user must
 381 provide a guest policy, the platform public Diffie-Hellman (PDH) key and session
 382 information.
 383
 384 Parameters: struct  kvm_sev_receive_start (in/out)
 385
 386 Returns: 0 on success, -negative on error
 387
 388 ::
 389
 390         struct kvm_sev_receive_start {
 391                 __u32 handle;           /* if zero then firmware creates a new handle */
 392                 __u32 policy;           /* guest's policy */
 393
 394                 __u64 pdh_uaddr;        /* userspace address pointing to the PDH key */
 395                 __u32 pdh_len;
 396
 397                 __u64 session_uaddr;    /* userspace address which points to the guest session information */
 398                 __u32 session_len;
 399         };
 400
 401 On success, the 'handle' field contains a new handle and on error, a negative value.
 402
 403 For more details, see SEV spec Section 6.12.
 404
 405 16. KVM_SEV_RECEIVE_UPDATE_DATA
 406 -------------------------------
 407
 408 The KVM_SEV_RECEIVE_UPDATE_DATA command can be used by the hypervisor to copy
 409 the incoming buffers into the guest memory region with encryption context
 410 created during the KVM_SEV_RECEIVE_START.
 411
 412 Parameters (in): struct kvm_sev_receive_update_data
 413
 414 Returns: 0 on success, -negative on error
 415
 416 ::
 417
 418         struct kvm_sev_launch_receive_update_data {
 419                 __u64 hdr_uaddr;        /* userspace address containing the packet header */
 420                 __u32 hdr_len;
 421
 422                 __u64 guest_uaddr;      /* the destination guest memory region */
 423                 __u32 guest_len;
 424
 425                 __u64 trans_uaddr;      /* the incoming buffer memory region  */
 426                 __u32 trans_len;
 427         };
 428
 429 17. KVM_SEV_RECEIVE_FINISH
 430 --------------------------
 431
 432 After completion of the migration flow, the KVM_SEV_RECEIVE_FINISH command can be
 433 issued by the hypervisor to make the guest ready for execution.
 434
 435 Returns: 0 on success, -negative on error
 436
 437 References
 438 ==========
 439
 440
 441 See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info.
 442
 443 .. [white-paper] https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf
 444 .. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf
 445 .. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34)
 446 .. [kvm-forum]  https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf