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 b
11 to get or set a certain aspect of the SEV virt
12 to the following classes:
13
14 - Hypervisor ioctls: These query and set glob
15 whole SEV firmware. These ioctl are used b
16
17 - Guest ioctls: These query and set attribute
18
19 2. API description
20 ==================
21
22 This section describes ioctls that is used for
23 from the SEV firmware. For each ioctl, the fol
24 along with a description:
25
26 Technology:
27 which SEV technology provides this ioctl
28
29 Type:
30 hypervisor or guest. The ioctl can be us
31 hypervisor.
32
33 Parameters:
34 what parameters are accepted by the ioct
35
36 Returns:
37 the return value. General error numbers
38 are not detailed, but errors with specif
39
40 The guest ioctl should be issued on a file des
41 device. The ioctl accepts struct snp_user_gue
42 output structure is specified through the req_
43 respectively. If the ioctl fails to execute du
44 the fw_error code will be set, otherwise fw_er
45
46 The firmware checks that the message sequence
47 the guests message sequence counter. If guest
48 counter (e.g. counter overflow), then -EIO wil
49
50 ::
51
52 struct snp_guest_request_ioctl {
53 /* Message version number */
54 __u32 msg_version;
55
56 /* Request and response struct
57 __u64 req_data;
58 __u64 resp_data;
59
60 /* bits[63:32]: VMM error code
61 union {
62 __u64 exitinfo2;
63 struct {
64 __u32 fw_error
65 __u32 vmm_erro
66 };
67 };
68 };
69
70 The host ioctls are issued to a file descripto
71 The ioctl accepts the command ID/input structu
72
73 ::
74
75 struct sev_issue_cmd {
76 /* Command ID */
77 __u32 cmd;
78
79 /* Command request structure *
80 __u64 data;
81
82 /* Firmware error code on fail
83 __u32 error;
84 };
85
86
87 2.1 SNP_GET_REPORT
88 ------------------
89
90 :Technology: sev-snp
91 :Type: guest ioctl
92 :Parameters (in): struct snp_report_req
93 :Returns (out): struct snp_report_resp on succ
94
95 The SNP_GET_REPORT ioctl can be used to query
96 SEV-SNP firmware. The ioctl uses the SNP_GUEST
97 provided by the SEV-SNP firmware to query the
98
99 On success, the snp_report_resp.data will cont
100 contain the format described in the SEV-SNP sp
101 specification for further details.
102
103 2.2 SNP_GET_DERIVED_KEY
104 -----------------------
105 :Technology: sev-snp
106 :Type: guest ioctl
107 :Parameters (in): struct snp_derived_key_req
108 :Returns (out): struct snp_derived_key_resp on
109
110 The SNP_GET_DERIVED_KEY ioctl can be used to g
111 The derived key can be used by the guest for a
112 or communicating with external entities.
113
114 The ioctl uses the SNP_GUEST_REQUEST (MSG_KEY_
115 SEV-SNP firmware to derive the key. See SEV-SN
116 on the various fields passed in the key deriva
117
118 On success, the snp_derived_key_resp.data cont
119 the SEV-SNP specification for further details.
120
121
122 2.3 SNP_GET_EXT_REPORT
123 ----------------------
124 :Technology: sev-snp
125 :Type: guest ioctl
126 :Parameters (in/out): struct snp_ext_report_re
127 :Returns (out): struct snp_report_resp on succ
128
129 The SNP_GET_EXT_REPORT ioctl is similar to the
130 related to the additional certificate data tha
131 The certificate data returned is being provide
132 SNP_SET_EXT_CONFIG.
133
134 The ioctl uses the SNP_GUEST_REQUEST (MSG_REPO
135 firmware to get the attestation report.
136
137 On success, the snp_ext_report_resp.data will
138 and snp_ext_report_req.certs_address will cont
139 length of the blob is smaller than expected th
140 be updated with the expected value.
141
142 See GHCB specification for further detail on h
143
144 2.4 SNP_PLATFORM_STATUS
145 -----------------------
146 :Technology: sev-snp
147 :Type: hypervisor ioctl cmd
148 :Parameters (out): struct sev_user_data_snp_st
149 :Returns (out): 0 on success, -negative on err
150
151 The SNP_PLATFORM_STATUS command is used to que
152 status includes API major, minor version and m
153 specification for further details.
154
155 2.5 SNP_COMMIT
156 --------------
157 :Technology: sev-snp
158 :Type: hypervisor ioctl cmd
159 :Returns (out): 0 on success, -negative on err
160
161 SNP_COMMIT is used to commit the currently ins
162 SEV-SNP firmware SNP_COMMIT command. This prev
163 committed firmware version. This will also upd
164 that of the currently installed firmware.
165
166 2.6 SNP_SET_CONFIG
167 ------------------
168 :Technology: sev-snp
169 :Type: hypervisor ioctl cmd
170 :Parameters (in): struct sev_user_data_snp_con
171 :Returns (out): 0 on success, -negative on err
172
173 SNP_SET_CONFIG is used to set the system-wide
174 reported TCB version in the attestation report
175 to SNP_CONFIG command defined in the SEV-SNP s
176 the firmware parameters affected by this comma
177 SNP_PLATFORM_STATUS.
178
179 2.7 SNP_VLEK_LOAD
180 -----------------
181 :Technology: sev-snp
182 :Type: hypervisor ioctl cmd
183 :Parameters (in): struct sev_user_data_snp_vle
184 :Returns (out): 0 on success, -negative on err
185
186 When requesting an attestation report a guest
187 it wants SNP firmware to sign the report using
188 Endorsement Key (VCEK), which is derived from
189 Versioned Loaded Endorsement Key (VLEK) which
190 Key Derivation Service (KDS) and derived from
191 enrolled cloud service providers.
192
193 In the case of VLEK keys, the SNP_VLEK_LOAD SN
194 them into the system after obtaining them from
195 closely to the SNP_VLEK_LOAD firmware command
196 spec.
197
198 3. SEV-SNP CPUID Enforcement
199 ============================
200
201 SEV-SNP guests can access a special page that
202 that have been validated by the PSP as part of
203 command. It provides the following assurances
204 values:
205
206 - Its address is obtained via bootloader/firm
207 binaries will be measured as part of the SE
208 - Its initial state will be encrypted/pvalida
209 it during run-time will result in garbage b
210 being generated due to changes in validatio
211 to swap the backing page.
212 - Attempts to bypass PSP checks by the hyperv
213 a non-CPUID encrypted page will change the
214 SEV-SNP attestation report.
215 - The CPUID page contents are *not* measured,
216 expected contents of a CPUID page as part o
217 gated by the PSP CPUID enforcement policy c
218 during SNP_LAUNCH_UPDATE, and noticeable la
219 implements their own checks of the CPUID va
220
221 It is important to note that this last assuran
222 has taken care to make use of the SEV-SNP CPUI
223 Otherwise, guest owner attestation provides no
224 fed incorrect values at some point during boot
225
226 4. SEV Guest Driver Communication Key
227 =====================================
228
229 Communication between an SEV guest and the SEV
230 Processor (ASP, aka PSP) is protected by a VM
231 (VMPCK). By default, the sev-guest driver uses
232 VM Privilege Level (VMPL) at which the guest i
233 wiped by the sev-guest driver (see the driver
234 wiped), a different key can be used by reloadi
235 specifying the desired key using the vmpck_id
236
237
238 Reference
239 ---------
240
241 SEV-SNP and GHCB specification: developer.amd.
242
243 The driver is based on SEV-SNP firmware spec 0
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.