|
| 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 device. |
| 41 | +The ioctl accepts struct snp_user_guest_request. The input and output structure is |
| 42 | +specified through the req_data and resp_data field respectively. If the ioctl fails |
| 43 | +to execute due to a firmware error, then fw_err code will be set otherwise the |
| 44 | +fw_err will be set to 0x00000000000000ff. |
| 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 | + /* firmware error code on failure (see psp-sev.h) */ |
| 61 | + __u64 fw_err; |
| 62 | + }; |
| 63 | + |
| 64 | +2.1 SNP_GET_REPORT |
| 65 | +------------------ |
| 66 | + |
| 67 | +:Technology: sev-snp |
| 68 | +:Type: guest ioctl |
| 69 | +:Parameters (in): struct snp_report_req |
| 70 | +:Returns (out): struct snp_report_resp on success, -negative on error |
| 71 | + |
| 72 | +The SNP_GET_REPORT ioctl can be used to query the attestation report from the |
| 73 | +SEV-SNP firmware. The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command |
| 74 | +provided by the SEV-SNP firmware to query the attestation report. |
| 75 | + |
| 76 | +On success, the snp_report_resp.data will contains the report. The report |
| 77 | +contain the format described in the SEV-SNP specification. See the SEV-SNP |
| 78 | +specification for further details. |
| 79 | + |
| 80 | +2.2 SNP_GET_DERIVED_KEY |
| 81 | +----------------------- |
| 82 | +:Technology: sev-snp |
| 83 | +:Type: guest ioctl |
| 84 | +:Parameters (in): struct snp_derived_key_req |
| 85 | +:Returns (out): struct snp_derived_key_resp on success, -negative on error |
| 86 | + |
| 87 | +The SNP_GET_DERIVED_KEY ioctl can be used to get a key derive from a root key. |
| 88 | +The derived key can be used by the guest for any purpose, such as sealing keys |
| 89 | +or communicating with external entities. |
| 90 | + |
| 91 | +The ioctl uses the SNP_GUEST_REQUEST (MSG_KEY_REQ) command provided by the |
| 92 | +SEV-SNP firmware to derive the key. See SEV-SNP specification for further details |
| 93 | +on the various fields passed in the key derivation request. |
| 94 | + |
| 95 | +On success, the snp_derived_key_resp.data contains the derived key value. See |
| 96 | +the SEV-SNP specification for further details. |
| 97 | + |
| 98 | + |
| 99 | +2.3 SNP_GET_EXT_REPORT |
| 100 | +---------------------- |
| 101 | +:Technology: sev-snp |
| 102 | +:Type: guest ioctl |
| 103 | +:Parameters (in/out): struct snp_ext_report_req |
| 104 | +:Returns (out): struct snp_report_resp on success, -negative on error |
| 105 | + |
| 106 | +The SNP_GET_EXT_REPORT ioctl is similar to the SNP_GET_REPORT. The difference is |
| 107 | +related to the additional certificate data that is returned with the report. |
| 108 | +The certificate data returned is being provided by the hypervisor through the |
| 109 | +SNP_SET_EXT_CONFIG. |
| 110 | + |
| 111 | +The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command provided by the SEV-SNP |
| 112 | +firmware to get the attestation report. |
| 113 | + |
| 114 | +On success, the snp_ext_report_resp.data will contain the attestation report |
| 115 | +and snp_ext_report_req.certs_address will contain the certificate blob. If the |
| 116 | +length of the blob is smaller than expected then snp_ext_report_req.certs_len will |
| 117 | +be updated with the expected value. |
| 118 | + |
| 119 | +See GHCB specification for further detail on how to parse the certificate blob. |
| 120 | + |
| 121 | +3. SEV-SNP CPUID Enforcement |
| 122 | +============================ |
| 123 | + |
| 124 | +SEV-SNP guests can access a special page that contains a table of CPUID values |
| 125 | +that have been validated by the PSP as part of the SNP_LAUNCH_UPDATE firmware |
| 126 | +command. It provides the following assurances regarding the validity of CPUID |
| 127 | +values: |
| 128 | + |
| 129 | + - Its address is obtained via bootloader/firmware (via CC blob), and those |
| 130 | + binaries will be measured as part of the SEV-SNP attestation report. |
| 131 | + - Its initial state will be encrypted/pvalidated, so attempts to modify |
| 132 | + it during run-time will result in garbage being written, or #VC exceptions |
| 133 | + being generated due to changes in validation state if the hypervisor tries |
| 134 | + to swap the backing page. |
| 135 | + - Attempts to bypass PSP checks by the hypervisor by using a normal page, or |
| 136 | + a non-CPUID encrypted page will change the measurement provided by the |
| 137 | + SEV-SNP attestation report. |
| 138 | + - The CPUID page contents are *not* measured, but attempts to modify the |
| 139 | + expected contents of a CPUID page as part of guest initialization will be |
| 140 | + gated by the PSP CPUID enforcement policy checks performed on the page |
| 141 | + during SNP_LAUNCH_UPDATE, and noticeable later if the guest owner |
| 142 | + implements their own checks of the CPUID values. |
| 143 | + |
| 144 | +It is important to note that this last assurance is only useful if the kernel |
| 145 | +has taken care to make use of the SEV-SNP CPUID throughout all stages of boot. |
| 146 | +Otherwise, guest owner attestation provides no assurance that the kernel wasn't |
| 147 | +fed incorrect values at some point during boot. |
| 148 | + |
| 149 | + |
| 150 | +Reference |
| 151 | +--------- |
| 152 | + |
| 153 | +SEV-SNP and GHCB specification: developer.amd.com/sev |
| 154 | + |
| 155 | +The driver is based on SEV-SNP firmware spec 0.9 and GHCB spec version 2.0. |
0 commit comments