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