cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

sev-guest.rst (7985B)


      1.. SPDX-License-Identifier: GPL-2.0
      2
      3===================================================================
      4The Definitive SEV Guest API Documentation
      5===================================================================
      6
      71. General description
      8======================
      9
     10The SEV API is a set of ioctls that are used by the guest or hypervisor
     11to get or set a certain aspect of the SEV virtual machine. The ioctls belong
     12to 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
     192. API description
     20==================
     21
     22This section describes ioctls that is used for querying the SEV guest report
     23from the SEV firmware. For each ioctl, the following information is provided
     24along 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
     40The guest ioctl should be issued on a file descriptor of the /dev/sev-guest device.
     41The ioctl accepts struct snp_user_guest_request. The input and output structure is
     42specified through the req_data and resp_data field respectively. If the ioctl fails
     43to execute due to a firmware error, then fw_err code will be set otherwise the
     44fw_err will be set to 0x00000000000000ff.
     45
     46The firmware checks that the message sequence counter is one greater than
     47the guests message sequence counter. If guest driver fails to increment message
     48counter (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                /* firmware error code on failure (see psp-sev.h) */
     61                __u64 fw_err;
     62        };
     63
     64The host ioctl should be called to /dev/sev device. The ioctl accepts command
     65id and command input structure.
     66
     67::
     68        struct sev_issue_cmd {
     69                /* Command ID */
     70                __u32 cmd;
     71
     72                /* Command request structure */
     73                __u64 data;
     74
     75                /* firmware error code on failure (see psp-sev.h) */
     76                __u32 error;
     77        };
     78
     79
     802.1 SNP_GET_REPORT
     81------------------
     82
     83:Technology: sev-snp
     84:Type: guest ioctl
     85:Parameters (in): struct snp_report_req
     86:Returns (out): struct snp_report_resp on success, -negative on error
     87
     88The SNP_GET_REPORT ioctl can be used to query the attestation report from the
     89SEV-SNP firmware. The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command
     90provided by the SEV-SNP firmware to query the attestation report.
     91
     92On success, the snp_report_resp.data will contains the report. The report
     93contain the format described in the SEV-SNP specification. See the SEV-SNP
     94specification for further details.
     95
     962.2 SNP_GET_DERIVED_KEY
     97-----------------------
     98:Technology: sev-snp
     99:Type: guest ioctl
    100:Parameters (in): struct snp_derived_key_req
    101:Returns (out): struct snp_derived_key_resp on success, -negative on error
    102
    103The SNP_GET_DERIVED_KEY ioctl can be used to get a key derive from a root key.
    104The derived key can be used by the guest for any purpose, such as sealing keys
    105or communicating with external entities.
    106
    107The ioctl uses the SNP_GUEST_REQUEST (MSG_KEY_REQ) command provided by the
    108SEV-SNP firmware to derive the key. See SEV-SNP specification for further details
    109on the various fields passed in the key derivation request.
    110
    111On success, the snp_derived_key_resp.data contains the derived key value. See
    112the SEV-SNP specification for further details.
    113
    114
    1152.3 SNP_GET_EXT_REPORT
    116----------------------
    117:Technology: sev-snp
    118:Type: guest ioctl
    119:Parameters (in/out): struct snp_ext_report_req
    120:Returns (out): struct snp_report_resp on success, -negative on error
    121
    122The SNP_GET_EXT_REPORT ioctl is similar to the SNP_GET_REPORT. The difference is
    123related to the additional certificate data that is returned with the report.
    124The certificate data returned is being provided by the hypervisor through the
    125SNP_SET_EXT_CONFIG.
    126
    127The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command provided by the SEV-SNP
    128firmware to get the attestation report.
    129
    130On success, the snp_ext_report_resp.data will contain the attestation report
    131and snp_ext_report_req.certs_address will contain the certificate blob. If the
    132length of the blob is smaller than expected then snp_ext_report_req.certs_len will
    133be updated with the expected value.
    134
    135See GHCB specification for further detail on how to parse the certificate blob.
    136
    1372.4 SNP_PLATFORM_STATUS
    138-----------------------
    139:Technology: sev-snp
    140:Type: hypervisor ioctl cmd
    141:Parameters (in): struct sev_data_snp_platform_status
    142:Returns (out): 0 on success, -negative on error
    143
    144The SNP_PLATFORM_STATUS command is used to query the SNP platform status. The
    145status includes API major, minor version and more. See the SEV-SNP
    146specification for further details.
    147
    1482.5 SNP_SET_EXT_CONFIG
    149----------------------
    150:Technology: sev-snp
    151:Type: hypervisor ioctl cmd
    152:Parameters (in): struct sev_data_snp_ext_config
    153:Returns (out): 0 on success, -negative on error
    154
    155The SNP_SET_EXT_CONFIG is used to set the system-wide configuration such as
    156reported TCB version in the attestation report. The command is similar to
    157SNP_CONFIG command defined in the SEV-SNP spec. The main difference is the
    158command also accepts an additional certificate blob defined in the GHCB
    159specification.
    160
    161If the certs_address is zero, then previous certificate blob will deleted.
    162For more information on the certificate blob layout, see the GHCB spec
    163(extended guest request message).
    164
    1652.6 SNP_GET_EXT_CONFIG
    166----------------------
    167:Technology: sev-snp
    168:Type: hypervisor ioctl cmd
    169:Parameters (in): struct sev_data_snp_ext_config
    170:Returns (out): 0 on success, -negative on error
    171
    172The SNP_SET_EXT_CONFIG is used to query the system-wide configuration set
    173through the SNP_SET_EXT_CONFIG.
    174
    1753. SEV-SNP CPUID Enforcement
    176============================
    177
    178SEV-SNP guests can access a special page that contains a table of CPUID values
    179that have been validated by the PSP as part of the SNP_LAUNCH_UPDATE firmware
    180command. It provides the following assurances regarding the validity of CPUID
    181values:
    182
    183 - Its address is obtained via bootloader/firmware (via CC blob), and those
    184   binaries will be measured as part of the SEV-SNP attestation report.
    185 - Its initial state will be encrypted/pvalidated, so attempts to modify
    186   it during run-time will result in garbage being written, or #VC exceptions
    187   being generated due to changes in validation state if the hypervisor tries
    188   to swap the backing page.
    189 - Attempts to bypass PSP checks by the hypervisor by using a normal page, or
    190   a non-CPUID encrypted page will change the measurement provided by the
    191   SEV-SNP attestation report.
    192 - The CPUID page contents are *not* measured, but attempts to modify the
    193   expected contents of a CPUID page as part of guest initialization will be
    194   gated by the PSP CPUID enforcement policy checks performed on the page
    195   during SNP_LAUNCH_UPDATE, and noticeable later if the guest owner
    196   implements their own checks of the CPUID values.
    197
    198It is important to note that this last assurance is only useful if the kernel
    199has taken care to make use of the SEV-SNP CPUID throughout all stages of boot.
    200Otherwise, guest owner attestation provides no assurance that the kernel wasn't
    201fed incorrect values at some point during boot.
    202
    203
    204Reference
    205---------
    206
    207SEV-SNP and GHCB specification: developer.amd.com/sev
    208
    209The driver is based on SEV-SNP firmware spec 0.9 and GHCB spec version 2.0.