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
642.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
72The SNP_GET_REPORT ioctl can be used to query the attestation report from the
73SEV-SNP firmware. The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command
74provided by the SEV-SNP firmware to query the attestation report.
75
76On success, the snp_report_resp.data will contains the report. The report
77contain the format described in the SEV-SNP specification. See the SEV-SNP
78specification for further details.
79
802.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
87The SNP_GET_DERIVED_KEY ioctl can be used to get a key derive from a root key.
88The derived key can be used by the guest for any purpose, such as sealing keys
89or communicating with external entities.
90
91The ioctl uses the SNP_GUEST_REQUEST (MSG_KEY_REQ) command provided by the
92SEV-SNP firmware to derive the key. See SEV-SNP specification for further details
93on the various fields passed in the key derivation request.
94
95On success, the snp_derived_key_resp.data contains the derived key value. See
96the SEV-SNP specification for further details.
97
98
992.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
106The SNP_GET_EXT_REPORT ioctl is similar to the SNP_GET_REPORT. The difference is
107related to the additional certificate data that is returned with the report.
108The certificate data returned is being provided by the hypervisor through the
109SNP_SET_EXT_CONFIG.
110
111The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command provided by the SEV-SNP
112firmware to get the attestation report.
113
114On success, the snp_ext_report_resp.data will contain the attestation report
115and snp_ext_report_req.certs_address will contain the certificate blob. If the
116length of the blob is smaller than expected then snp_ext_report_req.certs_len will
117be updated with the expected value.
118
119See GHCB specification for further detail on how to parse the certificate blob.
120
1213. SEV-SNP CPUID Enforcement
122============================
123
124SEV-SNP guests can access a special page that contains a table of CPUID values
125that have been validated by the PSP as part of the SNP_LAUNCH_UPDATE firmware
126command. It provides the following assurances regarding the validity of CPUID
127values:
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
144It is important to note that this last assurance is only useful if the kernel
145has taken care to make use of the SEV-SNP CPUID throughout all stages of boot.
146Otherwise, guest owner attestation provides no assurance that the kernel wasn't
147fed incorrect values at some point during boot.
148
149
150Reference
151---------
152
153SEV-SNP and GHCB specification: developer.amd.com/sev
154
155The driver is based on SEV-SNP firmware spec 0.9 and GHCB spec version 2.0.
156