1d63670d2STom Lendacky.. SPDX-License-Identifier: GPL-2.0 2d63670d2STom Lendacky 3d63670d2STom Lendacky=================================================================== 4d63670d2STom LendackyThe Definitive SEV Guest API Documentation 5d63670d2STom Lendacky=================================================================== 6d63670d2STom Lendacky 7d63670d2STom Lendacky1. General description 8d63670d2STom Lendacky====================== 9d63670d2STom Lendacky 10d63670d2STom LendackyThe SEV API is a set of ioctls that are used by the guest or hypervisor 11d63670d2STom Lendackyto get or set a certain aspect of the SEV virtual machine. The ioctls belong 12d63670d2STom Lendackyto the following classes: 13d63670d2STom Lendacky 14d63670d2STom Lendacky - Hypervisor ioctls: These query and set global attributes which affect the 15d63670d2STom Lendacky whole SEV firmware. These ioctl are used by platform provisioning tools. 16d63670d2STom Lendacky 17d63670d2STom Lendacky - Guest ioctls: These query and set attributes of the SEV virtual machine. 18d63670d2STom Lendacky 19d63670d2STom Lendacky2. API description 20d63670d2STom Lendacky================== 21d63670d2STom Lendacky 22d63670d2STom LendackyThis section describes ioctls that is used for querying the SEV guest report 23d63670d2STom Lendackyfrom the SEV firmware. For each ioctl, the following information is provided 24d63670d2STom Lendackyalong with a description: 25d63670d2STom Lendacky 26d63670d2STom Lendacky Technology: 27d63670d2STom Lendacky which SEV technology provides this ioctl. SEV, SEV-ES, SEV-SNP or all. 28d63670d2STom Lendacky 29d63670d2STom Lendacky Type: 30d63670d2STom Lendacky hypervisor or guest. The ioctl can be used inside the guest or the 31d63670d2STom Lendacky hypervisor. 32d63670d2STom Lendacky 33d63670d2STom Lendacky Parameters: 34d63670d2STom Lendacky what parameters are accepted by the ioctl. 35d63670d2STom Lendacky 36d63670d2STom Lendacky Returns: 37d63670d2STom Lendacky the return value. General error numbers (-ENOMEM, -EINVAL) 38d63670d2STom Lendacky are not detailed, but errors with specific meanings are. 39d63670d2STom Lendacky 400144e3b8SDionna GlazeThe guest ioctl should be issued on a file descriptor of the /dev/sev-guest 410144e3b8SDionna Glazedevice. The ioctl accepts struct snp_user_guest_request. The input and 420144e3b8SDionna Glazeoutput structure is specified through the req_data and resp_data field 430144e3b8SDionna Glazerespectively. If the ioctl fails to execute due to a firmware error, then 440144e3b8SDionna Glazethe fw_error code will be set, otherwise fw_error will be set to -1. 45d63670d2STom Lendacky 46d63670d2STom LendackyThe firmware checks that the message sequence counter is one greater than 47d63670d2STom Lendackythe guests message sequence counter. If guest driver fails to increment message 48d63670d2STom Lendackycounter (e.g. counter overflow), then -EIO will be returned. 49d63670d2STom Lendacky 50d63670d2STom Lendacky:: 51d63670d2STom Lendacky 52d63670d2STom Lendacky struct snp_guest_request_ioctl { 53d63670d2STom Lendacky /* Message version number */ 54d63670d2STom Lendacky __u32 msg_version; 55d63670d2STom Lendacky 56d63670d2STom Lendacky /* Request and response structure address */ 57d63670d2STom Lendacky __u64 req_data; 58d63670d2STom Lendacky __u64 resp_data; 59d63670d2STom Lendacky 600144e3b8SDionna Glaze /* bits[63:32]: VMM error code, bits[31:0] firmware error code (see psp-sev.h) */ 610144e3b8SDionna Glaze union { 620144e3b8SDionna Glaze __u64 exitinfo2; 630144e3b8SDionna Glaze struct { 640144e3b8SDionna Glaze __u32 fw_error; 650144e3b8SDionna Glaze __u32 vmm_error; 660144e3b8SDionna Glaze }; 670144e3b8SDionna Glaze }; 68d63670d2STom Lendacky }; 69d63670d2STom Lendacky 70f5db8841SBrijesh SinghThe host ioctls are issued to a file descriptor of the /dev/sev device. 71f5db8841SBrijesh SinghThe ioctl accepts the command ID/input structure documented below. 72f5db8841SBrijesh Singh 73f5db8841SBrijesh Singh:: 74*1bfca8d2SMichael Roth 75f5db8841SBrijesh Singh struct sev_issue_cmd { 76f5db8841SBrijesh Singh /* Command ID */ 77f5db8841SBrijesh Singh __u32 cmd; 78f5db8841SBrijesh Singh 79f5db8841SBrijesh Singh /* Command request structure */ 80f5db8841SBrijesh Singh __u64 data; 81f5db8841SBrijesh Singh 82f5db8841SBrijesh Singh /* Firmware error code on failure (see psp-sev.h) */ 83f5db8841SBrijesh Singh __u32 error; 84f5db8841SBrijesh Singh }; 85f5db8841SBrijesh Singh 86f5db8841SBrijesh Singh 87d63670d2STom Lendacky2.1 SNP_GET_REPORT 88d63670d2STom Lendacky------------------ 89d63670d2STom Lendacky 90d63670d2STom Lendacky:Technology: sev-snp 91d63670d2STom Lendacky:Type: guest ioctl 92d63670d2STom Lendacky:Parameters (in): struct snp_report_req 93d63670d2STom Lendacky:Returns (out): struct snp_report_resp on success, -negative on error 94d63670d2STom Lendacky 95d63670d2STom LendackyThe SNP_GET_REPORT ioctl can be used to query the attestation report from the 96d63670d2STom LendackySEV-SNP firmware. The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command 97d63670d2STom Lendackyprovided by the SEV-SNP firmware to query the attestation report. 98d63670d2STom Lendacky 99d63670d2STom LendackyOn success, the snp_report_resp.data will contains the report. The report 100d63670d2STom Lendackycontain the format described in the SEV-SNP specification. See the SEV-SNP 101d63670d2STom Lendackyspecification for further details. 102d63670d2STom Lendacky 103d63670d2STom Lendacky2.2 SNP_GET_DERIVED_KEY 104d63670d2STom Lendacky----------------------- 105d63670d2STom Lendacky:Technology: sev-snp 106d63670d2STom Lendacky:Type: guest ioctl 107d63670d2STom Lendacky:Parameters (in): struct snp_derived_key_req 108d63670d2STom Lendacky:Returns (out): struct snp_derived_key_resp on success, -negative on error 109d63670d2STom Lendacky 110d63670d2STom LendackyThe SNP_GET_DERIVED_KEY ioctl can be used to get a key derive from a root key. 111d63670d2STom LendackyThe derived key can be used by the guest for any purpose, such as sealing keys 112d63670d2STom Lendackyor communicating with external entities. 113d63670d2STom Lendacky 114d63670d2STom LendackyThe ioctl uses the SNP_GUEST_REQUEST (MSG_KEY_REQ) command provided by the 115d63670d2STom LendackySEV-SNP firmware to derive the key. See SEV-SNP specification for further details 116d63670d2STom Lendackyon the various fields passed in the key derivation request. 117d63670d2STom Lendacky 118d63670d2STom LendackyOn success, the snp_derived_key_resp.data contains the derived key value. See 119d63670d2STom Lendackythe SEV-SNP specification for further details. 120d63670d2STom Lendacky 121d63670d2STom Lendacky 122d63670d2STom Lendacky2.3 SNP_GET_EXT_REPORT 123d63670d2STom Lendacky---------------------- 124d63670d2STom Lendacky:Technology: sev-snp 125d63670d2STom Lendacky:Type: guest ioctl 126d63670d2STom Lendacky:Parameters (in/out): struct snp_ext_report_req 127d63670d2STom Lendacky:Returns (out): struct snp_report_resp on success, -negative on error 128d63670d2STom Lendacky 129d63670d2STom LendackyThe SNP_GET_EXT_REPORT ioctl is similar to the SNP_GET_REPORT. The difference is 130d63670d2STom Lendackyrelated to the additional certificate data that is returned with the report. 131d63670d2STom LendackyThe certificate data returned is being provided by the hypervisor through the 132d63670d2STom LendackySNP_SET_EXT_CONFIG. 133d63670d2STom Lendacky 134d63670d2STom LendackyThe ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command provided by the SEV-SNP 135d63670d2STom Lendackyfirmware to get the attestation report. 136d63670d2STom Lendacky 137d63670d2STom LendackyOn success, the snp_ext_report_resp.data will contain the attestation report 138d63670d2STom Lendackyand snp_ext_report_req.certs_address will contain the certificate blob. If the 139d63670d2STom Lendackylength of the blob is smaller than expected then snp_ext_report_req.certs_len will 140d63670d2STom Lendackybe updated with the expected value. 141d63670d2STom Lendacky 142d63670d2STom LendackySee GHCB specification for further detail on how to parse the certificate blob. 143d63670d2STom Lendacky 144f5db8841SBrijesh Singh2.4 SNP_PLATFORM_STATUS 145f5db8841SBrijesh Singh----------------------- 146f5db8841SBrijesh Singh:Technology: sev-snp 147f5db8841SBrijesh Singh:Type: hypervisor ioctl cmd 148f5db8841SBrijesh Singh:Parameters (out): struct sev_user_data_snp_status 149f5db8841SBrijesh Singh:Returns (out): 0 on success, -negative on error 150f5db8841SBrijesh Singh 151f5db8841SBrijesh SinghThe SNP_PLATFORM_STATUS command is used to query the SNP platform status. The 152f5db8841SBrijesh Singhstatus includes API major, minor version and more. See the SEV-SNP 153f5db8841SBrijesh Singhspecification for further details. 154f5db8841SBrijesh Singh 155fad133c7STom Lendacky2.5 SNP_COMMIT 156fad133c7STom Lendacky-------------- 157fad133c7STom Lendacky:Technology: sev-snp 158fad133c7STom Lendacky:Type: hypervisor ioctl cmd 159fad133c7STom Lendacky:Returns (out): 0 on success, -negative on error 160fad133c7STom Lendacky 161fad133c7STom LendackySNP_COMMIT is used to commit the currently installed firmware using the 162fad133c7STom LendackySEV-SNP firmware SNP_COMMIT command. This prevents roll-back to a previously 163fad133c7STom Lendackycommitted firmware version. This will also update the reported TCB to match 164fad133c7STom Lendackythat of the currently installed firmware. 165fad133c7STom Lendacky 166cb645fe4SBrijesh Singh2.6 SNP_SET_CONFIG 167cb645fe4SBrijesh Singh------------------ 168cb645fe4SBrijesh Singh:Technology: sev-snp 169cb645fe4SBrijesh Singh:Type: hypervisor ioctl cmd 170cb645fe4SBrijesh Singh:Parameters (in): struct sev_user_data_snp_config 171cb645fe4SBrijesh Singh:Returns (out): 0 on success, -negative on error 172cb645fe4SBrijesh Singh 173cb645fe4SBrijesh SinghSNP_SET_CONFIG is used to set the system-wide configuration such as 174cb645fe4SBrijesh Singhreported TCB version in the attestation report. The command is similar 175cb645fe4SBrijesh Singhto SNP_CONFIG command defined in the SEV-SNP spec. The current values of 176cb645fe4SBrijesh Singhthe firmware parameters affected by this command can be queried via 177cb645fe4SBrijesh SinghSNP_PLATFORM_STATUS. 178cb645fe4SBrijesh Singh 179d63670d2STom Lendacky3. SEV-SNP CPUID Enforcement 180d63670d2STom Lendacky============================ 181d63670d2STom Lendacky 182d63670d2STom LendackySEV-SNP guests can access a special page that contains a table of CPUID values 183d63670d2STom Lendackythat have been validated by the PSP as part of the SNP_LAUNCH_UPDATE firmware 184d63670d2STom Lendackycommand. It provides the following assurances regarding the validity of CPUID 185d63670d2STom Lendackyvalues: 186d63670d2STom Lendacky 187d63670d2STom Lendacky - Its address is obtained via bootloader/firmware (via CC blob), and those 188d63670d2STom Lendacky binaries will be measured as part of the SEV-SNP attestation report. 189d63670d2STom Lendacky - Its initial state will be encrypted/pvalidated, so attempts to modify 190d63670d2STom Lendacky it during run-time will result in garbage being written, or #VC exceptions 191d63670d2STom Lendacky being generated due to changes in validation state if the hypervisor tries 192d63670d2STom Lendacky to swap the backing page. 193d63670d2STom Lendacky - Attempts to bypass PSP checks by the hypervisor by using a normal page, or 194d63670d2STom Lendacky a non-CPUID encrypted page will change the measurement provided by the 195d63670d2STom Lendacky SEV-SNP attestation report. 196d63670d2STom Lendacky - The CPUID page contents are *not* measured, but attempts to modify the 197d63670d2STom Lendacky expected contents of a CPUID page as part of guest initialization will be 198d63670d2STom Lendacky gated by the PSP CPUID enforcement policy checks performed on the page 199d63670d2STom Lendacky during SNP_LAUNCH_UPDATE, and noticeable later if the guest owner 200d63670d2STom Lendacky implements their own checks of the CPUID values. 201d63670d2STom Lendacky 202d63670d2STom LendackyIt is important to note that this last assurance is only useful if the kernel 203d63670d2STom Lendackyhas taken care to make use of the SEV-SNP CPUID throughout all stages of boot. 204d63670d2STom LendackyOtherwise, guest owner attestation provides no assurance that the kernel wasn't 205d63670d2STom Lendackyfed incorrect values at some point during boot. 206d63670d2STom Lendacky 207d63670d2STom Lendacky 208d63670d2STom LendackyReference 209d63670d2STom Lendacky--------- 210d63670d2STom Lendacky 211d63670d2STom LendackySEV-SNP and GHCB specification: developer.amd.com/sev 212d63670d2STom Lendacky 213d63670d2STom LendackyThe driver is based on SEV-SNP firmware spec 0.9 and GHCB spec version 2.0. 214