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