Documentation/virt/coco/sev-guest.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===================================================================
   4 The Definitive SEV Guest API Documentation
   5 ===================================================================
   6
   7 1. General description
   8 ======================
   9
  10 The SEV API is a set of ioctls that are used by the guest or hypervisor
  11 to get or set a certain aspect of the SEV virtual machine. The ioctls belong
  12 to the following classes:
  13
  14  - Hypervisor ioctls: These query and set global attributes which affect the
  15    whole SEV firmware.  These ioctl are used by platform provisioning tools.
  16
  17  - Guest ioctls: These query and set attributes of the SEV virtual machine.
  18
  19 2. API description
  20 ==================
  21
  22 This section describes ioctls that is used for querying the SEV guest report
  23 from the SEV firmware. For each ioctl, the following information is provided
  24 along with a description:
  25
  26   Technology:
  27       which SEV technology provides this ioctl. SEV, SEV-ES, SEV-SNP or all.
  28
  29   Type:
  30       hypervisor or guest. The ioctl can be used inside the guest or the
  31       hypervisor.
  32
  33   Parameters:
  34       what parameters are accepted by the ioctl.
  35
  36   Returns:
  37       the return value.  General error numbers (-ENOMEM, -EINVAL)
  38       are not detailed, but errors with specific meanings are.
  39
  40 The guest ioctl should be issued on a file descriptor of the /dev/sev-guest
  41 device.  The ioctl accepts struct snp_user_guest_request. The input and
  42 output structure is specified through the req_data and resp_data field
  43 respectively. If the ioctl fails to execute due to a firmware error, then
  44 the fw_error code will be set, otherwise fw_error will be set to -1.
  45
  46 The firmware checks that the message sequence counter is one greater than
  47 the guests message sequence counter. If guest driver fails to increment message
  48 counter (e.g. counter overflow), then -EIO will be returned.
  49
  50 ::
  51
  52         struct snp_guest_request_ioctl {
  53                 /* Message version number */
  54                 __u32 msg_version;
  55
  56                 /* Request and response structure address */
  57                 __u64 req_data;
  58                 __u64 resp_data;
  59
  60                 /* bits[63:32]: VMM error code, bits[31:0] firmware error code (see psp-sev.h) */
  61                 union {
  62                         __u64 exitinfo2;
  63                         struct {
  64                                 __u32 fw_error;
  65                                 __u32 vmm_error;
  66                         };
  67                 };
  68         };
  69
  70 2.1 SNP_GET_REPORT
  71 ------------------
  72
  73 :Technology: sev-snp
  74 :Type: guest ioctl
  75 :Parameters (in): struct snp_report_req
  76 :Returns (out): struct snp_report_resp on success, -negative on error
  77
  78 The SNP_GET_REPORT ioctl can be used to query the attestation report from the
  79 SEV-SNP firmware. The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command
  80 provided by the SEV-SNP firmware to query the attestation report.
  81
  82 On success, the snp_report_resp.data will contains the report. The report
  83 contain the format described in the SEV-SNP specification. See the SEV-SNP
  84 specification for further details.
  85
  86 2.2 SNP_GET_DERIVED_KEY
  87 -----------------------
  88 :Technology: sev-snp
  89 :Type: guest ioctl
  90 :Parameters (in): struct snp_derived_key_req
  91 :Returns (out): struct snp_derived_key_resp on success, -negative on error
  92
  93 The SNP_GET_DERIVED_KEY ioctl can be used to get a key derive from a root key.
  94 The derived key can be used by the guest for any purpose, such as sealing keys
  95 or communicating with external entities.
  96
  97 The ioctl uses the SNP_GUEST_REQUEST (MSG_KEY_REQ) command provided by the
  98 SEV-SNP firmware to derive the key. See SEV-SNP specification for further details
  99 on the various fields passed in the key derivation request.
 100
 101 On success, the snp_derived_key_resp.data contains the derived key value. See
 102 the SEV-SNP specification for further details.
 103
 104
 105 2.3 SNP_GET_EXT_REPORT
 106 ----------------------
 107 :Technology: sev-snp
 108 :Type: guest ioctl
 109 :Parameters (in/out): struct snp_ext_report_req
 110 :Returns (out): struct snp_report_resp on success, -negative on error
 111
 112 The SNP_GET_EXT_REPORT ioctl is similar to the SNP_GET_REPORT. The difference is
 113 related to the additional certificate data that is returned with the report.
 114 The certificate data returned is being provided by the hypervisor through the
 115 SNP_SET_EXT_CONFIG.
 116
 117 The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command provided by the SEV-SNP
 118 firmware to get the attestation report.
 119
 120 On success, the snp_ext_report_resp.data will contain the attestation report
 121 and snp_ext_report_req.certs_address will contain the certificate blob. If the
 122 length of the blob is smaller than expected then snp_ext_report_req.certs_len will
 123 be updated with the expected value.
 124
 125 See GHCB specification for further detail on how to parse the certificate blob.
 126
 127 3. SEV-SNP CPUID Enforcement
 128 ============================
 129
 130 SEV-SNP guests can access a special page that contains a table of CPUID values
 131 that have been validated by the PSP as part of the SNP_LAUNCH_UPDATE firmware
 132 command. It provides the following assurances regarding the validity of CPUID
 133 values:
 134
 135  - Its address is obtained via bootloader/firmware (via CC blob), and those
 136    binaries will be measured as part of the SEV-SNP attestation report.
 137  - Its initial state will be encrypted/pvalidated, so attempts to modify
 138    it during run-time will result in garbage being written, or #VC exceptions
 139    being generated due to changes in validation state if the hypervisor tries
 140    to swap the backing page.
 141  - Attempts to bypass PSP checks by the hypervisor by using a normal page, or
 142    a non-CPUID encrypted page will change the measurement provided by the
 143    SEV-SNP attestation report.
 144  - The CPUID page contents are *not* measured, but attempts to modify the
 145    expected contents of a CPUID page as part of guest initialization will be
 146    gated by the PSP CPUID enforcement policy checks performed on the page
 147    during SNP_LAUNCH_UPDATE, and noticeable later if the guest owner
 148    implements their own checks of the CPUID values.
 149
 150 It is important to note that this last assurance is only useful if the kernel
 151 has taken care to make use of the SEV-SNP CPUID throughout all stages of boot.
 152 Otherwise, guest owner attestation provides no assurance that the kernel wasn't
 153 fed incorrect values at some point during boot.
 154
 155
 156 Reference
 157 ---------
 158
 159 SEV-SNP and GHCB specification: developer.amd.com/sev
 160
 161 The driver is based on SEV-SNP firmware spec 0.9 and GHCB spec version 2.0.