0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===================================================================
0004 The Definitive SEV Guest API Documentation
0005 ===================================================================
0006
0007 1. General description
0008 ======================
0009
0010 The SEV API is a set of ioctls that are used by the guest or hypervisor
0011 to get or set a certain aspect of the SEV virtual machine. The ioctls belong
0012 to the following classes:
0013
0014 - Hypervisor ioctls: These query and set global attributes which affect the
0015 whole SEV firmware. These ioctl are used by platform provisioning tools.
0016
0017 - Guest ioctls: These query and set attributes of the SEV virtual machine.
0018
0019 2. API description
0020 ==================
0021
0022 This section describes ioctls that is used for querying the SEV guest report
0023 from the SEV firmware. For each ioctl, the following information is provided
0024 along with a description:
0025
0026 Technology:
0027 which SEV technology provides this ioctl. SEV, SEV-ES, SEV-SNP or all.
0028
0029 Type:
0030 hypervisor or guest. The ioctl can be used inside the guest or the
0031 hypervisor.
0032
0033 Parameters:
0034 what parameters are accepted by the ioctl.
0035
0036 Returns:
0037 the return value. General error numbers (-ENOMEM, -EINVAL)
0038 are not detailed, but errors with specific meanings are.
0039
0040 The guest ioctl should be issued on a file descriptor of the /dev/sev-guest device.
0041 The ioctl accepts struct snp_user_guest_request. The input and output structure is
0042 specified through the req_data and resp_data field respectively. If the ioctl fails
0043 to execute due to a firmware error, then fw_err code will be set otherwise the
0044 fw_err will be set to 0x00000000000000ff.
0045
0046 The firmware checks that the message sequence counter is one greater than
0047 the guests message sequence counter. If guest driver fails to increment message
0048 counter (e.g. counter overflow), then -EIO will be returned.
0049
0050 ::
0051
0052 struct snp_guest_request_ioctl {
0053 /* Message version number */
0054 __u32 msg_version;
0055
0056 /* Request and response structure address */
0057 __u64 req_data;
0058 __u64 resp_data;
0059
0060 /* firmware error code on failure (see psp-sev.h) */
0061 __u64 fw_err;
0062 };
0063
0064 2.1 SNP_GET_REPORT
0065 ------------------
0066
0067 :Technology: sev-snp
0068 :Type: guest ioctl
0069 :Parameters (in): struct snp_report_req
0070 :Returns (out): struct snp_report_resp on success, -negative on error
0071
0072 The SNP_GET_REPORT ioctl can be used to query the attestation report from the
0073 SEV-SNP firmware. The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command
0074 provided by the SEV-SNP firmware to query the attestation report.
0075
0076 On success, the snp_report_resp.data will contains the report. The report
0077 contain the format described in the SEV-SNP specification. See the SEV-SNP
0078 specification for further details.
0079
0080 2.2 SNP_GET_DERIVED_KEY
0081 -----------------------
0082 :Technology: sev-snp
0083 :Type: guest ioctl
0084 :Parameters (in): struct snp_derived_key_req
0085 :Returns (out): struct snp_derived_key_resp on success, -negative on error
0086
0087 The SNP_GET_DERIVED_KEY ioctl can be used to get a key derive from a root key.
0088 The derived key can be used by the guest for any purpose, such as sealing keys
0089 or communicating with external entities.
0090
0091 The ioctl uses the SNP_GUEST_REQUEST (MSG_KEY_REQ) command provided by the
0092 SEV-SNP firmware to derive the key. See SEV-SNP specification for further details
0093 on the various fields passed in the key derivation request.
0094
0095 On success, the snp_derived_key_resp.data contains the derived key value. See
0096 the SEV-SNP specification for further details.
0097
0098
0099 2.3 SNP_GET_EXT_REPORT
0100 ----------------------
0101 :Technology: sev-snp
0102 :Type: guest ioctl
0103 :Parameters (in/out): struct snp_ext_report_req
0104 :Returns (out): struct snp_report_resp on success, -negative on error
0105
0106 The SNP_GET_EXT_REPORT ioctl is similar to the SNP_GET_REPORT. The difference is
0107 related to the additional certificate data that is returned with the report.
0108 The certificate data returned is being provided by the hypervisor through the
0109 SNP_SET_EXT_CONFIG.
0110
0111 The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command provided by the SEV-SNP
0112 firmware to get the attestation report.
0113
0114 On success, the snp_ext_report_resp.data will contain the attestation report
0115 and snp_ext_report_req.certs_address will contain the certificate blob. If the
0116 length of the blob is smaller than expected then snp_ext_report_req.certs_len will
0117 be updated with the expected value.
0118
0119 See GHCB specification for further detail on how to parse the certificate blob.
0120
0121 3. SEV-SNP CPUID Enforcement
0122 ============================
0123
0124 SEV-SNP guests can access a special page that contains a table of CPUID values
0125 that have been validated by the PSP as part of the SNP_LAUNCH_UPDATE firmware
0126 command. It provides the following assurances regarding the validity of CPUID
0127 values:
0128
0129 - Its address is obtained via bootloader/firmware (via CC blob), and those
0130 binaries will be measured as part of the SEV-SNP attestation report.
0131 - Its initial state will be encrypted/pvalidated, so attempts to modify
0132 it during run-time will result in garbage being written, or #VC exceptions
0133 being generated due to changes in validation state if the hypervisor tries
0134 to swap the backing page.
0135 - Attempts to bypass PSP checks by the hypervisor by using a normal page, or
0136 a non-CPUID encrypted page will change the measurement provided by the
0137 SEV-SNP attestation report.
0138 - The CPUID page contents are *not* measured, but attempts to modify the
0139 expected contents of a CPUID page as part of guest initialization will be
0140 gated by the PSP CPUID enforcement policy checks performed on the page
0141 during SNP_LAUNCH_UPDATE, and noticeable later if the guest owner
0142 implements their own checks of the CPUID values.
0143
0144 It is important to note that this last assurance is only useful if the kernel
0145 has taken care to make use of the SEV-SNP CPUID throughout all stages of boot.
0146 Otherwise, guest owner attestation provides no assurance that the kernel wasn't
0147 fed incorrect values at some point during boot.
0148
0149
0150 Reference
0151 ---------
0152
0153 SEV-SNP and GHCB specification: developer.amd.com/sev
0154
0155 The driver is based on SEV-SNP firmware spec 0.9 and GHCB spec version 2.0.
