2 The EFI_BIS_PROTOCOL is used to check a digital signature of a data block
3 against a digital certificate for the purpose of an integrity and authorization check.
5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
8 @par Revision Reference:
9 This Protocol is introduced in EFI Specification 1.10.
16 #define EFI_BIS_PROTOCOL_GUID \
18 0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \
22 // X-Intel-BIS-ParameterSet
24 // Binary Value of X-Intel-BIS-ParameterSet Attribute.
25 // (Value is Base-64 encoded in actual signed manifest).
27 #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \
29 0xedd35e31, 0x7b9, 0x11d2, { 0x83,0xa3,0x0,0xa0,0xc9,0x1f,0xad,0xcf } \
34 typedef struct _EFI_BIS_PROTOCOL EFI_BIS_PROTOCOL
;
40 typedef VOID
*BIS_APPLICATION_HANDLE
;
41 typedef UINT16 BIS_ALG_ID
;
42 typedef UINT32 BIS_CERT_ID
;
45 /// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).
48 UINT32 Length
; ///< The length of Data in 8 bit bytes.
49 UINT8
*Data
; ///< 32 Bit Flat Address of data.
53 /// EFI_BIS_VERSION type.
56 UINT32 Major
; ///< The major BIS version number.
57 UINT32 Minor
; ///< A minor BIS version number.
61 // ----------------------------------------------------//
62 // Use these values to initialize EFI_BIS_VERSION.Major
63 // and to interpret results of Initialize.
64 // ----------------------------------------------------//
66 #define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1
67 #define BIS_VERSION_1 1
70 /// EFI_BIS_SIGNATURE_INFO type.
73 BIS_CERT_ID CertificateID
; ///< Truncated hash of platform Boot Object
74 BIS_ALG_ID AlgorithmID
; ///< A signature algorithm number.
75 UINT16 KeyLength
; ///< The length of alg. keys in bits.
76 } EFI_BIS_SIGNATURE_INFO
;
79 /// values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.
80 /// The exact numeric values come from the
81 /// "Common Data Security Architecture (CDSA) Specification".
83 #define BIS_ALG_DSA (41) // CSSM_ALGID_DSA
84 #define BIS_ALG_RSA_MD5 (42) // CSSM_ALGID_MD5_WITH_RSA
86 /// values for EFI_BIS_SIGNATURE_INFO.CertificateId.
88 #define BIS_CERT_ID_DSA BIS_ALG_DSA // CSSM_ALGID_DSA
89 #define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA
91 /// The mask value that gets applied to the truncated hash of a
92 /// platform Boot Object Authorization Certificate to create the certificateID.
93 /// A certificateID must not have any bits set to the value 1 other than bits in
96 #define BIS_CERT_ID_MASK (0xFF7F7FFF)
99 /// Macros for dealing with the EFI_BIS_DATA object obtained
100 /// from BIS_GetSignatureInfo().
101 /// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO
102 /// elements are contained in a EFI_BIS_DATA struct pointed to
103 /// by the provided EFI_BIS_DATA*.
105 #define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))
108 /// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*
109 /// from a given EFI_BIS_DATA*.
111 #define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)
114 /// Support an old name for backward compatibility.
116 #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \
117 BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID
120 Initializes the BIS service, checking that it is compatible with the version requested by the caller.
121 After this call, other BIS functions may be invoked.
123 @param This A pointer to the EFI_BIS_PROTOCOL object.
124 @param AppHandle The function writes the new BIS_APPLICATION_HANDLE if
125 successful, otherwise it writes NULL. The caller must eventually
126 destroy this handle by calling Shutdown().
127 @param InterfaceVersion On input, the caller supplies the major version number of the
128 interface version desired.
129 On output, both the major and minor
130 version numbers are updated with the major and minor version
131 numbers of the interface. This update is done whether or not the
132 initialization was successful.
133 @param TargetAddress Indicates a network or device address of the BIS platform to connect to.
135 @retval EFI_SUCCESS The function completed successfully.
136 @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the
137 caller was not compatible with the interface version of the
138 implementation. The InterfaceVersion.Major has
139 been updated with the current interface version.
140 @retval EFI_UNSUPPORTED This is a local-platform implementation and
141 TargetAddress.Data was not NULL, or
142 TargetAddress.Data was any other value that was not
143 supported by the implementation.
144 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
145 @retval EFI_DEVICE_ERROR One of the following device errors:
146 * The function encountered an unexpected internal failure while initializing a cryptographic software module
147 * No cryptographic software module with compatible version was found
149 * A resource limitation was encountered while using a cryptographic software module.
150 @retval EFI_INVALID_PARAMETER The This parameter supplied by the caller is NULL or does not
151 reference a valid EFI_BIS_PROTOCOL object. Or,
152 the AppHandle parameter supplied by the caller is NULL or
153 an invalid memory reference. Or,
154 the InterfaceVersion parameter supplied by the caller
155 is NULL or an invalid memory reference. Or,
156 the TargetAddress parameter supplied by the caller is
157 NULL or an invalid memory reference.
162 (EFIAPI
*EFI_BIS_INITIALIZE
)(
163 IN EFI_BIS_PROTOCOL
*This
,
164 OUT BIS_APPLICATION_HANDLE
*AppHandle
,
165 IN OUT EFI_BIS_VERSION
*InterfaceVersion
,
166 IN EFI_BIS_DATA
*TargetAddress
170 Frees memory structures allocated and returned by other functions in the EFI_BIS protocol.
172 @param AppHandle An opaque handle that identifies the caller's instance of initialization
174 @param ToFree An EFI_BIS_DATA* and associated memory block to be freed.
175 This EFI_BIS_DATA* must have been allocated by one of the other BIS functions.
177 @retval EFI_SUCCESS The function completed successfully.
178 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
179 application instance handle associated with the EFI_BIS protocol.
180 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
181 @retval EFI_INVALID_PARAMETER The ToFree parameter is not or is no longer a memory resource
182 associated with this AppHandle.
187 (EFIAPI
*EFI_BIS_FREE
)(
188 IN BIS_APPLICATION_HANDLE AppHandle
,
189 IN EFI_BIS_DATA
*ToFree
193 Shuts down an application's instance of the BIS service, invalidating the application handle. After
194 this call, other BIS functions may no longer be invoked using the application handle value.
196 @param AppHandle An opaque handle that identifies the caller's instance of initialization
199 @retval EFI_SUCCESS The function completed successfully.
200 @retval EFI_NO_MAPPING The AppHandle parameter is not, or is no longer, a valid
201 application instance handle associated with the EFI_BIS protocol.
202 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
203 @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure while
204 returning resources associated with a cryptographic software module, or
205 while trying to shut down a cryptographic software module.
209 (EFIAPI
*EFI_BIS_SHUTDOWN
)(
210 IN BIS_APPLICATION_HANDLE AppHandle
214 Retrieves the certificate that has been configured as the identity of the organization designated as
215 the source of authorization for signatures of boot objects.
217 @param AppHandle An opaque handle that identifies the caller's instance of initialization
219 @param Certificate The function writes an allocated EFI_BIS_DATA* containing the Boot
220 Object Authorization Certificate object. The caller must
221 eventually free the memory allocated by this function using the function Free().
223 @retval EFI_SUCCESS The function completed successfully.
224 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
225 application instance handle associated with the EFI_BIS protocol.
226 @retval EFI_NOT_FOUND There is no Boot Object Authorization Certificate currently installed.
227 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
228 @retval EFI_INVALID_PARAMETER The Certificate parameter supplied by the caller is NULL or
229 an invalid memory reference.
234 (EFIAPI
*EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE
)(
235 IN BIS_APPLICATION_HANDLE AppHandle
,
236 OUT EFI_BIS_DATA
**Certificate
240 Verifies the integrity and authorization of the indicated data object according to the
241 indicated credentials.
243 @param AppHandle An opaque handle that identifies the caller's instance of initialization
245 @param Credentials A Signed Manifest containing verification information for the indicated
247 @param DataObject An in-memory copy of the raw data object to be verified.
248 @param IsVerified The function writes TRUE if the verification succeeded, otherwise
251 @retval EFI_SUCCESS The function completed successfully.
252 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
253 application instance handle associated with the EFI_BIS protocol.
254 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
255 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
256 @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the Credentials parameter
257 was invalid (could not be parsed) or Platform-specific authorization failed, etc.
258 @retval EFI_DEVICE_ERROR An unexpected internal error occurred.
263 (EFIAPI
*EFI_BIS_VERIFY_BOOT_OBJECT
)(
264 IN BIS_APPLICATION_HANDLE AppHandle
,
265 IN EFI_BIS_DATA
*Credentials
,
266 IN EFI_BIS_DATA
*DataObject
,
267 OUT BOOLEAN
*IsVerified
271 Retrieves the current status of the Boot Authorization Check Flag.
273 @param AppHandle An opaque handle that identifies the caller's instance of initialization
275 @param CheckIsRequired The function writes the value TRUE if a Boot Authorization Check is
276 currently required on this platform, otherwise the function writes
279 @retval EFI_SUCCESS The function completed successfully.
280 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
281 application instance handle associated with the EFI_BIS protocol.
282 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
283 @retval EFI_INVALID_PARAMETER The CheckIsRequired parameter supplied by the caller is
284 NULL or an invalid memory reference.
289 (EFIAPI
*EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG
)(
290 IN BIS_APPLICATION_HANDLE AppHandle
,
291 OUT BOOLEAN
*CheckIsRequired
295 Retrieves a unique token value to be included in the request credential for the next update of any
296 parameter in the Boot Object Authorization set
298 @param AppHandle An opaque handle that identifies the caller's
299 instance of initialization of the BIS service.
300 @param UpdateToken The function writes an allocated EFI_BIS_DATA*
301 containing the newunique update token value.
302 The caller musteventually free the memory allocated
303 by this function using the function Free().
305 @retval EFI_SUCCESS The function completed successfully.
306 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
307 application instance handle associated with the EFI_BIS protocol.
308 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
309 @retval EFI_INVALID_PARAMETER The UpdateToken parameter supplied by the caller is NULL or
310 an invalid memory reference.
311 @retval EFI_DEVICE_ERROR An unexpected internal error occurred.
316 (EFIAPI
*EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN
)(
317 IN BIS_APPLICATION_HANDLE AppHandle
,
318 OUT EFI_BIS_DATA
**UpdateToken
322 Updates one of the configurable parameters of the Boot Object Authorization set.
324 @param AppHandle An opaque handle that identifies the caller's
325 instance of initialization of the BIS service.
326 @param RequestCredential This is a Signed Manifest with embedded attributes
327 that carry the details of the requested update.
328 @param NewUpdateToken The function writes an allocated EFI_BIS_DATA*
329 containing the new unique update token value.
330 The caller must eventually free the memory allocated
331 by this function using the function Free().
333 @retval EFI_SUCCESS The function completed successfully.
334 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
335 application instance handle associated with the EFI_BIS protocol.
336 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
337 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
338 @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the RequestCredential parameter
339 was invalid (could not be parsed) or Platform-specific authorization failed, etc.
340 @retval EFI_DEVICE_ERROR An unexpected internal error occurred while analyzing the new
341 certificate's key algorithm, or while attempting to retrieve
342 the public key algorithm of the manifest's signer's certificate,
343 or An unexpected internal error occurred in a cryptographic software module.
348 (EFIAPI
*EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION
)(
349 IN BIS_APPLICATION_HANDLE AppHandle
,
350 IN EFI_BIS_DATA
*RequestCredential
,
351 OUT EFI_BIS_DATA
**NewUpdateToken
355 Verifies the integrity and authorization of the indicated data object according to the indicated
356 credentials and authority certificate.
358 @param AppHandle An opaque handle that identifies the caller's instance of initialization
360 @param Credentials A Signed Manifest containing verification information for the
361 indicated data object.
362 @param DataObject An in-memory copy of the raw data object to be verified.
363 @param SectionName An ASCII string giving the section name in the
364 manifest holding the verification information (in other words,
365 hash value) that corresponds to DataObject.
366 @param AuthorityCertificate A digital certificate whose public key must match the signer's
367 public key which is found in the credentials.
368 @param IsVerified The function writes TRUE if the verification was successful.
369 Otherwise, the function writes FALSE.
371 @retval EFI_SUCCESS The function completed successfully.
372 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
373 application instance handle associated with the EFI_BIS protocol.
374 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
375 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
376 @retval EFI_SECURITY_VIOLATION The Credentials.Data supplied by the caller is NULL,
377 or the AuthorityCertificate supplied by the caller was
378 invalid (could not be parsed),
379 or Platform-specific authorization failed, etc.
380 @retval EFI_DEVICE_ERROR An unexpected internal error occurred while attempting to retrieve
381 the public key algorithm of the manifest's signer's certificate,
382 or An unexpected internal error occurred in a cryptographic software module.
386 (EFIAPI
*EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL
)(
387 IN BIS_APPLICATION_HANDLE AppHandle
,
388 IN EFI_BIS_DATA
*Credentials
,
389 IN EFI_BIS_DATA
*DataObject
,
390 IN EFI_BIS_DATA
*SectionName
,
391 IN EFI_BIS_DATA
*AuthorityCertificate
,
392 OUT BOOLEAN
*IsVerified
396 Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength
397 combinations that the platform supports.
399 @param AppHandle An opaque handle that identifies the caller's instance of initialization
401 @param SignatureInfo The function writes an allocated EFI_BIS_DATA* containing the array
402 of EFI_BIS_SIGNATURE_INFO structures representing the supported
403 digital certificate identifier, algorithm, and key length combinations.
404 The caller must eventually free the memory allocated by this function using the function Free().
406 @retval EFI_SUCCESS The function completed successfully.
407 @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid
408 application instance handle associated with the EFI_BIS protocol.
409 @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.
410 @retval EFI_INVALID_PARAMETER The SignatureInfo parameter supplied by the caller is NULL
411 or an invalid memory reference.
412 @retval EFI_DEVICE_ERROR An unexpected internal error occurred in a
413 cryptographic software module, or
414 The function encountered an unexpected internal consistency check
415 failure (possible corruption of stored Boot Object Authorization Certificate).
420 (EFIAPI
*EFI_BIS_GET_SIGNATURE_INFO
)(
421 IN BIS_APPLICATION_HANDLE AppHandle
,
422 OUT EFI_BIS_DATA
**SignatureInfo
426 /// The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital
427 /// certificate for the purpose of an integrity and authorization check.
429 struct _EFI_BIS_PROTOCOL
{
430 EFI_BIS_INITIALIZE Initialize
;
431 EFI_BIS_SHUTDOWN Shutdown
;
433 EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE GetBootObjectAuthorizationCertificate
;
434 EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG GetBootObjectAuthorizationCheckFlag
;
435 EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN GetBootObjectAuthorizationUpdateToken
;
436 EFI_BIS_GET_SIGNATURE_INFO GetSignatureInfo
;
437 EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION UpdateBootObjectAuthorization
;
438 EFI_BIS_VERIFY_BOOT_OBJECT VerifyBootObject
;
439 EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL VerifyObjectWithCredential
;
442 extern EFI_GUID gEfiBisProtocolGuid
;
443 extern EFI_GUID gBootObjectAuthorizationParmsetGuid
;