]> git.proxmox.com Git - mirror_edk2.git/blame - MdePkg/Include/Protocol/Bis.h
add a error macro to prevent this file from included for now #error "UEFI 2.1 HII...
[mirror_edk2.git] / MdePkg / Include / Protocol / Bis.h
CommitLineData
d1f95000 1/** @file\r
2 This file defines the BIS protocol.\r
3\r
4 Copyright (c) 2006, Intel Corporation \r
5 All rights reserved. This program and the accompanying materials \r
6 are licensed and made available under the terms and conditions of the BSD License \r
7 which accompanies this distribution. The full text of the license may be found at \r
8 http://opensource.org/licenses/bsd-license.php \r
9\r
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
12\r
d1f95000 13**/\r
14\r
15#ifndef __BIS_H__\r
16#define __BIS_H__\r
17\r
18#define EFI_BIS_PROTOCOL_GUID \\r
19 { \\r
20 0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \\r
21 }\r
22\r
23typedef struct _EFI_BIS_PROTOCOL EFI_BIS_PROTOCOL;\r
24\r
25\r
26//\r
27// Basic types\r
28//\r
29typedef VOID *BIS_APPLICATION_HANDLE;\r
30typedef UINT16 BIS_ALG_ID;\r
31typedef UINT32 BIS_CERT_ID;\r
32\r
33//\r
34// EFI_BIS_DATA type.\r
35//\r
36// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).\r
37//\r
38typedef struct {\r
39 UINT32 Length; // Length of Data in 8 bit bytes.\r
40 UINT8 *Data; // 32 Bit Flat Address of data.\r
41} EFI_BIS_DATA;\r
42\r
43//\r
44// EFI_BIS_VERSION type.\r
45//\r
46typedef struct {\r
47 UINT32 Major; // BIS Interface version number.\r
48 UINT32 Minor; // Build number.\r
49} EFI_BIS_VERSION;\r
50\r
51//\r
52// ----------------------------------------------------//\r
53// Use these values to initialize EFI_BIS_VERSION.Major\r
54// and to interpret results of Initialize.\r
55// ----------------------------------------------------//\r
56//\r
57#define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1\r
58#define BIS_VERSION_1 1\r
59\r
60//\r
61// EFI_BIS_SIGNATURE_INFO type.\r
62//\r
63typedef struct {\r
64 BIS_CERT_ID CertificateID; // Truncated hash of platform Boot Object\r
65 // authorization certificate.\r
66 //\r
67 BIS_ALG_ID AlgorithmID; // A signature algorithm number.\r
68 UINT16 KeyLength; // Length of alg. keys in bits.\r
69} EFI_BIS_SIGNATURE_INFO;\r
70\r
71//\r
72// Currently defined values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.\r
73// The exact numeric values come from\r
74// "Common Data Security Architecture (CDSA) Specification".\r
75//\r
76#define BIS_ALG_DSA (41) // CSSM_ALGID_DSA\r
77#define BIS_ALG_RSA_MD5 (42) // CSSM_ALGID_MD5_WITH_RSA\r
78// Currently defined values for EFI_BIS_SIGNATURE_INFO.CertificateId.\r
79//\r
80#define BIS_CERT_ID_DSA BIS_ALG_DSA // CSSM_ALGID_DSA\r
81#define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA\r
82// The following is a mask value that gets applied to the truncated hash of a\r
83// platform Boot Object Authorization Certificate to create the certificateID.\r
84// A certificateID must not have any bits set to the value 1 other than bits in\r
85// this mask.\r
86//\r
87#define BIS_CERT_ID_MASK (0xFF7F7FFF)\r
88\r
89//\r
90// Macros for dealing with the EFI_BIS_DATA object obtained\r
91// from BIS_GetSignatureInfo()\r
92// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO\r
93// elements are contained in a EFI_BIS_DATA struct pointed to\r
94// by the provided EFI_BIS_DATA*.\r
95//\r
96#define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))\r
97\r
98//\r
99// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*\r
100// from a given EFI_BIS_DATA*.\r
101//\r
102#define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)\r
103\r
104//\r
105// Binary Value of "X-Intel-BIS-ParameterSet" Attribute.\r
106// (Value is Base64 encoded in actual signed manifest).\r
107// {EDD35E31-07B9-11d2-83A3-00A0C91FADCF}\r
108//\r
109#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \\r
110 { \\r
111 0xedd35e31, 0x7b9, 0x11d2, \\r
112 { \\r
113 0x83, 0xa3, 0x0, 0xa0, 0xc9, 0x1f, 0xad, 0xcf \\r
114 } \\r
115 }\r
116\r
117//\r
118// Support old name for backward compatible\r
119//\r
120#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \\r
121 BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID\r
122\r
123/** \r
124 Initializes the BIS service, checking that it is compatible with the version requested by the caller.\r
125 After this call, other BIS functions may be invoked. \r
126 \r
127 @param This A pointer to the EFI_BIS_PROTOCOL object.\r
128 @param AppHandle The function writes the new BIS_APPLICATION_HANDLE if \r
129 successful, otherwise it writes NULL. The caller must eventually\r
130 destroy this handle by calling Shutdown(). \r
131 @param InterfaceVersion On input, the caller supplies the major version number of the\r
132 interface version desired. \r
133 On output, both the major and minor \r
134 version numbers are updated with the major and minor version\r
135 numbers of the interface \r
136 @param TargetAddress Indicates a network or device address of the BIS platform to connect to. \r
137\r
138 @retval EFI_SUCCESS The function completed successfully.\r
139 @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the \r
140 caller was not compatible with the interface version of the\r
141 @retval EFI_UNSUPPORTED This is a local-platform implementation and \r
142 TargetAddress.Data was not NULL, or \r
143 TargetAddress.Data was any other value that was not\r
144 supported by the implementation. \r
145 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
146 @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure.\r
147 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
148 \r
149**/ \r
150typedef\r
151EFI_STATUS\r
152(EFIAPI *EFI_BIS_INITIALIZE) (\r
153 IN EFI_BIS_PROTOCOL *This, \r
154 OUT BIS_APPLICATION_HANDLE *AppHandle, \r
155 IN OUT EFI_BIS_VERSION *InterfaceVersion, \r
156 IN EFI_BIS_DATA *TargetAddress \r
157 );\r
158\r
159/** \r
160 Frees memory structures allocated and returned by other functions in the EFI_BIS protocol. \r
161 \r
162 @param AppHandle An opaque handle that identifies the caller's instance of initialization\r
163 of the BIS service. \r
164 @param ToFree An EFI_BIS_DATA* and associated memory block to be freed.\r
165\r
166 @retval EFI_SUCCESS The function completed successfully.\r
167 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
168 application instance handle associated with the EFI_BIS protocol. \r
169 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
170 @retval EFI_INVALID_PARAMETER The ToFree parameter is not or is no longer a memory resource\r
171 associated with this AppHandle. \r
172 \r
173**/ \r
174typedef\r
175EFI_STATUS\r
176(EFIAPI *EFI_BIS_FREE) (\r
177 IN BIS_APPLICATION_HANDLE AppHandle, \r
178 IN EFI_BIS_DATA *ToFree \r
179 );\r
180\r
181/** \r
182 Shuts down an application's instance of the BIS service, invalidating the application handle. After\r
183 this call, other BIS functions may no longer be invoked using the application handle value. \r
184 \r
185 @param AppHandle An opaque handle that identifies the caller's instance of initialization\r
186 of the BIS service. \r
187\r
188 @retval EFI_SUCCESS The function completed successfully.\r
189 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
190 application instance handle associated with the EFI_BIS protocol. \r
191 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
192 @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure. \r
193 \r
194**/ \r
195typedef\r
196EFI_STATUS\r
197(EFIAPI *EFI_BIS_SHUTDOWN) (\r
198 IN BIS_APPLICATION_HANDLE AppHandle \r
199 );\r
200\r
201/** \r
202 Retrieves the certificate that has been configured as the identity of the organization designated as\r
203 the source of authorization for signatures of boot objects.\r
204 \r
205 @param AppHandle An opaque handle that identifies the caller's instance of initialization\r
206 of the BIS service. \r
207 @param Certificate The function writes an allocated EFI_BIS_DATA* containing the Boot\r
208 Object Authorization Certificate object. \r
209\r
210 @retval EFI_SUCCESS The function completed successfully.\r
211 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
212 application instance handle associated with the EFI_BIS protocol. \r
213 @retval EFI_NOT_FOUND There is no Boot Object Authorization Certificate currently installed. \r
214 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
215 @retval EFI_INVALID_PARAMETER The Certificate parameter supplied by the caller is NULL or\r
216 an invalid memory reference. \r
217 \r
218**/ \r
219typedef\r
220EFI_STATUS\r
221(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE) (\r
222 IN BIS_APPLICATION_HANDLE AppHandle, \r
223 OUT EFI_BIS_DATA **Certificate \r
224 );\r
225\r
226/** \r
227 Verifies the integrity and authorization of the indicated data object according to the\r
228 indicated credentials. \r
229 \r
230 @param AppHandle An opaque handle that identifies the caller's instance of initialization\r
231 of the BIS service. \r
232 @param Credentials A Signed Manifest containing verification information for the indicated\r
233 data object. \r
234 @param DataObject An in-memory copy of the raw data object to be verified.\r
235 @param IsVerified The function writes TRUE if the verification succeeded, otherwise\r
236 FALSE. \r
237 \r
238 @retval EFI_SUCCESS The function completed successfully.\r
239 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
240 application instance handle associated with the EFI_BIS protocol. \r
241 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
242 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
243 @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the Credentials parameter\r
244 was invalid (could not be parsed) or Platform-specific authorization failed, etc.\r
245 @retval EFI_DEVICE_ERROR An unexpected internal error occurred. \r
246 \r
247**/ \r
248typedef\r
249EFI_STATUS\r
250(EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT) (\r
251 IN BIS_APPLICATION_HANDLE AppHandle, \r
252 IN EFI_BIS_DATA *Credentials, \r
253 IN EFI_BIS_DATA *DataObject, \r
254 OUT BOOLEAN *IsVerified \r
255 );\r
256\r
257/** \r
258 Retrieves the current status of the Boot Authorization Check Flag.\r
259 \r
260 @param AppHandle An opaque handle that identifies the caller's instance of initialization\r
261 of the BIS service. \r
262 @param CheckIsRequired The function writes the value TRUE if a Boot Authorization Check is\r
263 currently required on this platform, otherwise the function writes \r
264 FALSE. \r
265 \r
266 @retval EFI_SUCCESS The function completed successfully.\r
267 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
268 application instance handle associated with the EFI_BIS protocol. \r
269 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
270 @retval EFI_INVALID_PARAMETER The CheckIsRequired parameter supplied by the caller is\r
271 NULL or an invalid memory reference. \r
272 \r
273**/ \r
274typedef\r
275EFI_STATUS\r
276(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG) (\r
277 IN BIS_APPLICATION_HANDLE AppHandle, \r
278 OUT BOOLEAN *CheckIsRequired \r
279 );\r
280\r
281/** \r
282 Retrieves a unique token value to be included in the request credential for the next update of any\r
283 parameter in the Boot Object Authorization set \r
284 \r
285 @param AppHandle An opaque handle that identifies the caller's instance of initialization\r
286 of the BIS service. \r
287 @param UpdateToken The function writes an allocated EFI_BIS_DATA* containing the new\r
288 unique update token value. \r
289 \r
290 @retval EFI_SUCCESS The function completed successfully.\r
291 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
292 application instance handle associated with the EFI_BIS protocol. \r
293 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
294 @retval EFI_INVALID_PARAMETER The UpdateToken parameter supplied by the caller is NULL or\r
295 an invalid memory reference. \r
296 @retval EFI_DEVICE_ERROR An unexpected internal error occurred. \r
297 \r
298**/ \r
299typedef\r
300EFI_STATUS\r
301(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN) (\r
302 IN BIS_APPLICATION_HANDLE AppHandle, \r
303 OUT EFI_BIS_DATA **UpdateToken \r
304 );\r
305\r
306/** \r
307 Updates one of the configurable parameters of the Boot Object Authorization set.\r
308 \r
309 @param AppHandle An opaque handle that identifies the caller's instance of initialization\r
310 of the BIS service. \r
311 @param RequestCredential This is a Signed Manifest with embedded attributes that carry the details\r
312 of the requested update. \r
313 @param NewUpdateToken The function writes an allocated EFI_BIS_DATA* containing the new \r
314 unique update token value. \r
315 \r
316 @retval EFI_SUCCESS The function completed successfully. \r
317 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid \r
318 application instance handle associated with the EFI_BIS protocol. \r
319 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
320 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. \r
321 @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the RequestCredential parameter \r
322 was invalid (could not be parsed) or Platform-specific authorization failed, etc. \r
323 @retval EFI_DEVICE_ERROR An unexpected internal error occurred. \r
324 \r
325**/ \r
326typedef\r
327EFI_STATUS\r
328(EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION) (\r
329 IN BIS_APPLICATION_HANDLE AppHandle, \r
330 IN EFI_BIS_DATA *RequestCredential, \r
331 OUT EFI_BIS_DATA **NewUpdateToken \r
332 );\r
333\r
334/** \r
335 Verifies the integrity and authorization of the indicated data object according to the indicated\r
336 credentials and authority certificate. \r
337 \r
338 @param AppHandle An opaque handle that identifies the caller's instance of initialization\r
339 of the BIS service. \r
340 @param Credentials A Signed Manifest containing verification information for the\r
341 indicated data object. \r
342 @param DataObject An in-memory copy of the raw data object to be verified.\r
343 @param SectionName An ASCII (not Unicode) string giving the section name in the \r
344 manifest holding the verification information (in other words,\r
345 hash value) that corresponds to DataObject. \r
346 @param AuthorityCertificate A digital certificate whose public key must match the signer's \r
347 public key which is found in the credentials. \r
348 @param IsVerified The function writes TRUE if the verification was successful.\r
349 Otherwise, the function writes FALSE. \r
350 \r
351 @retval EFI_SUCCESS The function completed successfully. \r
352 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid \r
353 application instance handle associated with the EFI_BIS protocol. \r
354 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
355 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. \r
356 @retval EFI_SECURITY_VIOLATION The Credentials.Data supplied by the caller is NULL,\r
357 or the AuthorityCertificate supplied by the caller was \r
358 invalid (could not be parsed), \r
359 or Platform-specific authorization failed, etc. \r
360 @retval EFI_DEVICE_ERROR An unexpected internal error occurred. \r
361 \r
362**/ \r
363typedef\r
364EFI_STATUS\r
365(EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL) (\r
366 IN BIS_APPLICATION_HANDLE AppHandle, \r
367 IN EFI_BIS_DATA *Credentials, \r
368 IN EFI_BIS_DATA *DataObject, \r
369 IN EFI_BIS_DATA *SectionName, \r
370 IN EFI_BIS_DATA *AuthorityCertificate, \r
371 OUT BOOLEAN *IsVerified \r
372 );\r
373\r
374/** \r
375 Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength\r
376 combinations that the platform supports. \r
377 \r
378 @param AppHandle An opaque handle that identifies the caller's instance of initialization\r
379 of the BIS service. \r
380 @param SignatureInfo The function writes an allocated EFI_BIS_DATA* containing the array\r
381 of EFI_BIS_SIGNATURE_INFO structures representing the supported \r
382 digital certificate identifier, algorithm, and key length combinations. \r
383 \r
384 @retval EFI_SUCCESS The function completed successfully. \r
385 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid \r
386 application instance handle associated with the EFI_BIS protocol. \r
387 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
388 @retval EFI_INVALID_PARAMETER The SignatureInfo parameter supplied by the caller is NULL\r
389 or an invalid memory reference. \r
390 @retval EFI_DEVICE_ERROR An unexpected internal error occurred. \r
391 \r
392**/\r
393typedef\r
394EFI_STATUS\r
395(EFIAPI *EFI_BIS_GET_SIGNATURE_INFO) (\r
396 IN BIS_APPLICATION_HANDLE AppHandle, \r
397 OUT EFI_BIS_DATA **SignatureInfo \r
398 );\r
399\r
400struct _EFI_BIS_PROTOCOL {\r
401 EFI_BIS_INITIALIZE Initialize;\r
402 EFI_BIS_SHUTDOWN Shutdown;\r
403 EFI_BIS_FREE Free;\r
404 EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE GetBootObjectAuthorizationCertificate;\r
405 EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG GetBootObjectAuthorizationCheckFlag;\r
406 EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN GetBootObjectAuthorizationUpdateToken;\r
407 EFI_BIS_GET_SIGNATURE_INFO GetSignatureInfo;\r
408 EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION UpdateBootObjectAuthorization;\r
409 EFI_BIS_VERIFY_BOOT_OBJECT VerifyBootObject;\r
410 EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL VerifyObjectWithCredential;\r
411};\r
412\r
413extern EFI_GUID gEfiBisProtocolGuid;\r
414extern EFI_GUID gBootObjectAuthorizationParmsetGuid;\r
415\r
416#endif\r