2 BIS protocol are defined in the UEFI specification.
3 The EFI_BIS_PROTOCOL is used to check a digital signature of a data block
4 against a digital certificate for the purpose of an integrity and authorization check.
6 Copyright (c) 2006 - 2008, Intel Corporation
7 All rights reserved. This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
20 #define EFI_BIS_PROTOCOL_GUID \
22 0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \
26 // X-Intel-BIS-ParameterSet
28 // Binary Value of X-Intel-BIS-ParameterSet Attribute.
29 // (Value is Base-64 encoded in actual signed manifest).
31 #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \
33 0xedd35e31, 0x7b9, 0x11d2, { 0x83,0xa3,0x0,0xa0,0xc9,0x1f,0xad,0xcf } \
38 typedef struct _EFI_BIS_PROTOCOL EFI_BIS_PROTOCOL
;
44 typedef VOID
*BIS_APPLICATION_HANDLE
;
45 typedef UINT16 BIS_ALG_ID
;
46 typedef UINT32 BIS_CERT_ID
;
49 /// EFI_BIS_DATA type.
51 /// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).
54 UINT32 Length
; // Length of Data in 8 bit bytes.
55 UINT8
*Data
; // 32 Bit Flat Address of data.
59 /// EFI_BIS_VERSION type.
62 UINT32 Major
; // BIS Interface version number.
63 UINT32 Minor
; // Build number.
67 // ----------------------------------------------------//
68 // Use these values to initialize EFI_BIS_VERSION.Major
69 // and to interpret results of Initialize.
70 // ----------------------------------------------------//
72 #define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1
73 #define BIS_VERSION_1 1
76 /// EFI_BIS_SIGNATURE_INFO type.
79 BIS_CERT_ID CertificateID
; // Truncated hash of platform Boot Object
80 /// authorization certificate.
82 BIS_ALG_ID AlgorithmID
; // A signature algorithm number.
83 UINT16 KeyLength
; // Length of alg. keys in bits.
84 } EFI_BIS_SIGNATURE_INFO
;
87 /// Currently defined values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.
88 /// The exact numeric values come from
89 /// "Common Data Security Architecture (CDSA) Specification".
91 #define BIS_ALG_DSA (41) // CSSM_ALGID_DSA
92 #define BIS_ALG_RSA_MD5 (42) // CSSM_ALGID_MD5_WITH_RSA
93 /// Currently defined values for EFI_BIS_SIGNATURE_INFO.CertificateId.
95 #define BIS_CERT_ID_DSA BIS_ALG_DSA // CSSM_ALGID_DSA
96 #define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA
97 /// The following is a mask value that gets applied to the truncated hash of a
98 /// platform Boot Object Authorization Certificate to create the certificateID.
99 /// A certificateID must not have any bits set to the value 1 other than bits in
102 #define BIS_CERT_ID_MASK (0xFF7F7FFF)
105 /// Macros for dealing with the EFI_BIS_DATA object obtained
106 /// from BIS_GetSignatureInfo()
107 /// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO
108 /// elements are contained in a EFI_BIS_DATA struct pointed to
109 /// by the provided EFI_BIS_DATA*.
111 #define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))
114 /// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*
115 /// from a given EFI_BIS_DATA*.
117 #define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)
120 /// Support old name for backward compatible
122 #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \
123 BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID
126 Initializes the BIS service, checking that it is compatible with the version requested by the caller.
127 After this call, other BIS functions may be invoked.
129 @param This A pointer to the EFI_BIS_PROTOCOL object.
130 @param AppHandle The function writes the new BIS_APPLICATION_HANDLE if
131 successful, otherwise it writes NULL. The caller must eventually
132 destroy this handle by calling Shutdown().
133 @param InterfaceVersion On input, the caller supplies the major version number of the
134 interface version desired.
135 On output, both the major and minor
136 version numbers are updated with the major and minor version
137 numbers of the interface
138 @param TargetAddress Indicates a network or device address of the BIS platform to connect to.
140 @retval EFI_SUCCESS The function completed successfully.
141 @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the
142 caller was not compatible with the interface version of the
143 @retval EFI_UNSUPPORTED This is a local-platform implementation and
144 TargetAddress.Data was not NULL, or
145 TargetAddress.Data was any other value that was not
146 supported by the implementation.
147 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
148 @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure.
149 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
154 (EFIAPI
*EFI_BIS_INITIALIZE
)(
155 IN EFI_BIS_PROTOCOL
*This
,
156 OUT BIS_APPLICATION_HANDLE
*AppHandle
,
157 IN OUT EFI_BIS_VERSION
*InterfaceVersion
,
158 IN EFI_BIS_DATA
*TargetAddress
162 Frees memory structures allocated and returned by other functions in the EFI_BIS protocol.
164 @param AppHandle An opaque handle that identifies the caller's instance of initialization
166 @param ToFree An EFI_BIS_DATA* and associated memory block to be freed.
168 @retval EFI_SUCCESS The function completed successfully.
169 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
170 application instance handle associated with the EFI_BIS protocol.
171 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
172 @retval EFI_INVALID_PARAMETER The ToFree parameter is not or is no longer a memory resource
173 associated with this AppHandle.
178 (EFIAPI
*EFI_BIS_FREE
)(
179 IN BIS_APPLICATION_HANDLE AppHandle
,
180 IN EFI_BIS_DATA
*ToFree
184 Shuts down an application's instance of the BIS service, invalidating the application handle. After
185 this call, other BIS functions may no longer be invoked using the application handle value.
187 @param AppHandle An opaque handle that identifies the caller's instance of initialization
190 @retval EFI_SUCCESS The function completed successfully.
191 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
192 application instance handle associated with the EFI_BIS protocol.
193 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
194 @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure.
199 (EFIAPI
*EFI_BIS_SHUTDOWN
)(
200 IN BIS_APPLICATION_HANDLE AppHandle
204 Retrieves the certificate that has been configured as the identity of the organization designated as
205 the source of authorization for signatures of boot objects.
207 @param AppHandle An opaque handle that identifies the caller's instance of initialization
209 @param Certificate The function writes an allocated EFI_BIS_DATA* containing the Boot
210 Object Authorization Certificate object.
212 @retval EFI_SUCCESS The function completed successfully.
213 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
214 application instance handle associated with the EFI_BIS protocol.
215 @retval EFI_NOT_FOUND There is no Boot Object Authorization Certificate currently installed.
216 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
217 @retval EFI_INVALID_PARAMETER The Certificate parameter supplied by the caller is NULL or
218 an invalid memory reference.
223 (EFIAPI
*EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE
)(
224 IN BIS_APPLICATION_HANDLE AppHandle
,
225 OUT EFI_BIS_DATA
**Certificate
229 Verifies the integrity and authorization of the indicated data object according to the
230 indicated credentials.
232 @param AppHandle An opaque handle that identifies the caller's instance of initialization
234 @param Credentials A Signed Manifest containing verification information for the indicated
236 @param DataObject An in-memory copy of the raw data object to be verified.
237 @param IsVerified The function writes TRUE if the verification succeeded, otherwise
240 @retval EFI_SUCCESS The function completed successfully.
241 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
242 application instance handle associated with the EFI_BIS protocol.
243 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
244 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
245 @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the Credentials parameter
246 was invalid (could not be parsed) or Platform-specific authorization failed, etc.
247 @retval EFI_DEVICE_ERROR An unexpected internal error occurred.
252 (EFIAPI
*EFI_BIS_VERIFY_BOOT_OBJECT
)(
253 IN BIS_APPLICATION_HANDLE AppHandle
,
254 IN EFI_BIS_DATA
*Credentials
,
255 IN EFI_BIS_DATA
*DataObject
,
256 OUT BOOLEAN
*IsVerified
260 Retrieves the current status of the Boot Authorization Check Flag.
262 @param AppHandle An opaque handle that identifies the caller's instance of initialization
264 @param CheckIsRequired The function writes the value TRUE if a Boot Authorization Check is
265 currently required on this platform, otherwise the function writes
268 @retval EFI_SUCCESS The function completed successfully.
269 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
270 application instance handle associated with the EFI_BIS protocol.
271 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
272 @retval EFI_INVALID_PARAMETER The CheckIsRequired parameter supplied by the caller is
273 NULL or an invalid memory reference.
278 (EFIAPI
*EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG
)(
279 IN BIS_APPLICATION_HANDLE AppHandle
,
280 OUT BOOLEAN
*CheckIsRequired
284 Retrieves a unique token value to be included in the request credential for the next update of any
285 parameter in the Boot Object Authorization set
287 @param AppHandle An opaque handle that identifies the caller's instance of initialization
289 @param UpdateToken The function writes an allocated EFI_BIS_DATA* containing the new
290 unique update token value.
292 @retval EFI_SUCCESS The function completed successfully.
293 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
294 application instance handle associated with the EFI_BIS protocol.
295 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
296 @retval EFI_INVALID_PARAMETER The UpdateToken parameter supplied by the caller is NULL or
297 an invalid memory reference.
298 @retval EFI_DEVICE_ERROR An unexpected internal error occurred.
303 (EFIAPI
*EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN
)(
304 IN BIS_APPLICATION_HANDLE AppHandle
,
305 OUT EFI_BIS_DATA
**UpdateToken
309 Updates one of the configurable parameters of the Boot Object Authorization set.
311 @param AppHandle An opaque handle that identifies the caller's instance of initialization
313 @param RequestCredential This is a Signed Manifest with embedded attributes that carry the details
314 of the requested update.
315 @param NewUpdateToken The function writes an allocated EFI_BIS_DATA* containing the new
316 unique update token value.
318 @retval EFI_SUCCESS The function completed successfully.
319 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
320 application instance handle associated with the EFI_BIS protocol.
321 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
322 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
323 @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the RequestCredential parameter
324 was invalid (could not be parsed) or Platform-specific authorization failed, etc.
325 @retval EFI_DEVICE_ERROR An unexpected internal error occurred.
330 (EFIAPI
*EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION
)(
331 IN BIS_APPLICATION_HANDLE AppHandle
,
332 IN EFI_BIS_DATA
*RequestCredential
,
333 OUT EFI_BIS_DATA
**NewUpdateToken
337 Verifies the integrity and authorization of the indicated data object according to the indicated
338 credentials and authority certificate.
340 @param AppHandle An opaque handle that identifies the caller's instance of initialization
342 @param Credentials A Signed Manifest containing verification information for the
343 indicated data object.
344 @param DataObject An in-memory copy of the raw data object to be verified.
345 @param SectionName An ASCII (not Unicode) string giving the section name in the
346 manifest holding the verification information (in other words,
347 hash value) that corresponds to DataObject.
348 @param AuthorityCertificate A digital certificate whose public key must match the signer's
349 public key which is found in the credentials.
350 @param IsVerified The function writes TRUE if the verification was successful.
351 Otherwise, the function writes FALSE.
353 @retval EFI_SUCCESS The function completed successfully.
354 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
355 application instance handle associated with the EFI_BIS protocol.
356 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
357 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
358 @retval EFI_SECURITY_VIOLATION The Credentials.Data supplied by the caller is NULL,
359 or the AuthorityCertificate supplied by the caller was
360 invalid (could not be parsed),
361 or Platform-specific authorization failed, etc.
362 @retval EFI_DEVICE_ERROR An unexpected internal error occurred.
367 (EFIAPI
*EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL
)(
368 IN BIS_APPLICATION_HANDLE AppHandle
,
369 IN EFI_BIS_DATA
*Credentials
,
370 IN EFI_BIS_DATA
*DataObject
,
371 IN EFI_BIS_DATA
*SectionName
,
372 IN EFI_BIS_DATA
*AuthorityCertificate
,
373 OUT BOOLEAN
*IsVerified
377 Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength
378 combinations that the platform supports.
380 @param AppHandle An opaque handle that identifies the caller's instance of initialization
382 @param SignatureInfo The function writes an allocated EFI_BIS_DATA* containing the array
383 of EFI_BIS_SIGNATURE_INFO structures representing the supported
384 digital certificate identifier, algorithm, and key length combinations.
386 @retval EFI_SUCCESS The function completed successfully.
387 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
388 application instance handle associated with the EFI_BIS protocol.
389 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
390 @retval EFI_INVALID_PARAMETER The SignatureInfo parameter supplied by the caller is NULL
391 or an invalid memory reference.
392 @retval EFI_DEVICE_ERROR An unexpected internal error occurred.
397 (EFIAPI
*EFI_BIS_GET_SIGNATURE_INFO
)(
398 IN BIS_APPLICATION_HANDLE AppHandle
,
399 OUT EFI_BIS_DATA
**SignatureInfo
403 @par Protocol Description:
404 The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital
405 certificate for the purpose of an integrity and authorization check.
408 Initializes an application instance of the EFI_BIS protocol,
409 returning a handle for the application instance. Other functions in
410 the EFI_BIS protocol require a valid application instance
411 handle obtained from this function.
414 Ends the lifetime of an application instance of the EFI_BIS
415 protocol, invalidating its application instance handle. The
416 application instance handle may no longer be used in other
417 functions in the EFI_BIS protocol.
420 Frees memory structures allocated and returned by other
421 functions in the EFI_BIS protocol.
423 @param GetBootObjectAuthorizationCertificate
424 Retrieves the current digital certificate (if any) used by the
425 EFI_BIS protocol as the source of authorization for verifying
426 boot objects and altering configuration parameters.
428 @param GetBootObjectAuthorizationCheckFlag
429 Retrieves the current setting of the authorization check flag that
430 indicates whether or not authorization checks are required for
433 @param GetBootObjectAuthorizationUpdateToken
434 Retrieves an uninterpreted token whose value gets included and
435 signed in a subsequent request to alter the configuration
436 parameters, to protect against attempts to replay such a request.
438 @param GetSignatureInfo
439 Retrieves information about the digital signature algorithms
440 supported and the identity of the installed authorization
443 @param UpdateBootObjectAuthorization
444 Requests that the configuration parameters be altered by
445 installing or removing an authorization certificate or changing the
446 setting of the check flag.
448 @param VerifyBootObject
449 Verifies a boot object according to the supplied digital signature
450 and the current authorization certificate and check flag setting.
452 @param VerifyObjectWithCredential
453 Verifies a data object according to a supplied digital signature
454 and a supplied digital certificate.
456 struct _EFI_BIS_PROTOCOL
{
457 EFI_BIS_INITIALIZE Initialize
;
458 EFI_BIS_SHUTDOWN Shutdown
;
460 EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE GetBootObjectAuthorizationCertificate
;
461 EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG GetBootObjectAuthorizationCheckFlag
;
462 EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN GetBootObjectAuthorizationUpdateToken
;
463 EFI_BIS_GET_SIGNATURE_INFO GetSignatureInfo
;
464 EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION UpdateBootObjectAuthorization
;
465 EFI_BIS_VERIFY_BOOT_OBJECT VerifyBootObject
;
466 EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL VerifyObjectWithCredential
;
469 extern EFI_GUID gEfiBisProtocolGuid
;
470 extern EFI_GUID gBootObjectAuthorizationParmsetGuid
;