/** @file\r
- The EFI_BIS_PROTOCOL is used to check a digital signature of a data block \r
+ The EFI_BIS_PROTOCOL is used to check a digital signature of a data block\r
against a digital certificate for the purpose of an integrity and authorization check.\r
\r
-Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>\r
-This program and the accompanying materials are licensed and made available under \r
-the terms and conditions of the BSD License that accompanies this distribution. \r
+Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+This program and the accompanying materials are licensed and made available under\r
+the terms and conditions of the BSD License that accompanies this distribution.\r
The full text of the license may be found at\r
-http://opensource.org/licenses/bsd-license.php. \r
- \r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+http://opensource.org/licenses/bsd-license.php.\r
\r
- @par Revision Reference: \r
- This Protocol is introduced in EFI Specification 1.10. \r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+ @par Revision Reference:\r
+ This Protocol is introduced in EFI Specification 1.10.\r
\r
**/\r
\r
#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \\r
BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID\r
\r
-/** \r
+/**\r
Initializes the BIS service, checking that it is compatible with the version requested by the caller.\r
- After this call, other BIS functions may be invoked. \r
- \r
+ After this call, other BIS functions may be invoked.\r
+\r
@param This A pointer to the EFI_BIS_PROTOCOL object.\r
- @param AppHandle The function writes the new BIS_APPLICATION_HANDLE if \r
+ @param AppHandle The function writes the new BIS_APPLICATION_HANDLE if\r
successful, otherwise it writes NULL. The caller must eventually\r
- destroy this handle by calling Shutdown(). \r
+ destroy this handle by calling Shutdown().\r
@param InterfaceVersion On input, the caller supplies the major version number of the\r
- interface version desired. \r
- On output, both the major and minor \r
+ interface version desired.\r
+ On output, both the major and minor\r
version numbers are updated with the major and minor version\r
numbers of the interface. This update is done whether or not the\r
- initialization was successful. \r
- @param TargetAddress Indicates a network or device address of the BIS platform to connect to. \r
+ initialization was successful.\r
+ @param TargetAddress Indicates a network or device address of the BIS platform to connect to.\r
\r
@retval EFI_SUCCESS The function completed successfully.\r
- @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the \r
+ @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the\r
caller was not compatible with the interface version of the\r
implementation. The InterfaceVersion.Major has\r
been updated with the current interface version.\r
- @retval EFI_UNSUPPORTED This is a local-platform implementation and \r
- TargetAddress.Data was not NULL, or \r
+ @retval EFI_UNSUPPORTED This is a local-platform implementation and\r
+ TargetAddress.Data was not NULL, or\r
TargetAddress.Data was any other value that was not\r
- supported by the implementation. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
+ supported by the implementation.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
@retval EFI_DEVICE_ERROR One of the following device errors:\r
* The function encountered an unexpected internal failure while initializing a cryptographic software module\r
* No cryptographic software module with compatible version was found\r
is NULL or an invalid memory reference. Or,\r
the TargetAddress parameter supplied by the caller is\r
NULL or an invalid memory reference.\r
- \r
-**/ \r
+\r
+**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_INITIALIZE)(\r
- IN EFI_BIS_PROTOCOL *This, \r
- OUT BIS_APPLICATION_HANDLE *AppHandle, \r
- IN OUT EFI_BIS_VERSION *InterfaceVersion, \r
- IN EFI_BIS_DATA *TargetAddress \r
+ IN EFI_BIS_PROTOCOL *This,\r
+ OUT BIS_APPLICATION_HANDLE *AppHandle,\r
+ IN OUT EFI_BIS_VERSION *InterfaceVersion,\r
+ IN EFI_BIS_DATA *TargetAddress\r
);\r
\r
-/** \r
- Frees memory structures allocated and returned by other functions in the EFI_BIS protocol. \r
- \r
+/**\r
+ Frees memory structures allocated and returned by other functions in the EFI_BIS protocol.\r
+\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
- of the BIS service. \r
- @param ToFree An EFI_BIS_DATA* and associated memory block to be freed. \r
+ of the BIS service.\r
+ @param ToFree An EFI_BIS_DATA* and associated memory block to be freed.\r
This EFI_BIS_DATA* must have been allocated by one of the other BIS functions.\r
\r
@retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
- application instance handle associated with the EFI_BIS protocol. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
+ application instance handle associated with the EFI_BIS protocol.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
@retval EFI_INVALID_PARAMETER The ToFree parameter is not or is no longer a memory resource\r
- associated with this AppHandle. \r
- \r
-**/ \r
+ associated with this AppHandle.\r
+\r
+**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_FREE)(\r
- IN BIS_APPLICATION_HANDLE AppHandle, \r
- IN EFI_BIS_DATA *ToFree \r
+ IN BIS_APPLICATION_HANDLE AppHandle,\r
+ IN EFI_BIS_DATA *ToFree\r
);\r
\r
-/** \r
+/**\r
Shuts down an application's instance of the BIS service, invalidating the application handle. After\r
- this call, other BIS functions may no longer be invoked using the application handle value. \r
- \r
+ this call, other BIS functions may no longer be invoked using the application handle value.\r
+\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
- of the BIS service. \r
+ of the BIS service.\r
\r
@retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_NO_MAPPING The AppHandle parameter is not, or is no longer, a valid\r
- application instance handle associated with the EFI_BIS protocol. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
+ application instance handle associated with the EFI_BIS protocol.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
@retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure while\r
returning resources associated with a cryptographic software module, or\r
while trying to shut down a cryptographic software module.\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_SHUTDOWN)(\r
- IN BIS_APPLICATION_HANDLE AppHandle \r
+ IN BIS_APPLICATION_HANDLE AppHandle\r
);\r
\r
-/** \r
+/**\r
Retrieves the certificate that has been configured as the identity of the organization designated as\r
the source of authorization for signatures of boot objects.\r
- \r
+\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
- of the BIS service. \r
+ of the BIS service.\r
@param Certificate The function writes an allocated EFI_BIS_DATA* containing the Boot\r
Object Authorization Certificate object. The caller must\r
eventually free the memory allocated by this function using the function Free().\r
\r
@retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
- application instance handle associated with the EFI_BIS protocol. \r
- @retval EFI_NOT_FOUND There is no Boot Object Authorization Certificate currently installed. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
+ application instance handle associated with the EFI_BIS protocol.\r
+ @retval EFI_NOT_FOUND There is no Boot Object Authorization Certificate currently installed.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
@retval EFI_INVALID_PARAMETER The Certificate parameter supplied by the caller is NULL or\r
- an invalid memory reference. \r
- \r
-**/ \r
+ an invalid memory reference.\r
+\r
+**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE)(\r
- IN BIS_APPLICATION_HANDLE AppHandle, \r
- OUT EFI_BIS_DATA **Certificate \r
+ IN BIS_APPLICATION_HANDLE AppHandle,\r
+ OUT EFI_BIS_DATA **Certificate\r
);\r
\r
-/** \r
+/**\r
Verifies the integrity and authorization of the indicated data object according to the\r
- indicated credentials. \r
- \r
+ indicated credentials.\r
+\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
- of the BIS service. \r
+ of the BIS service.\r
@param Credentials A Signed Manifest containing verification information for the indicated\r
- data object. \r
+ data object.\r
@param DataObject An in-memory copy of the raw data object to be verified.\r
@param IsVerified The function writes TRUE if the verification succeeded, otherwise\r
- FALSE. \r
- \r
+ FALSE.\r
+\r
@retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
- application instance handle associated with the EFI_BIS protocol. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
+ application instance handle associated with the EFI_BIS protocol.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
@retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
@retval EFI_SECURITY_VIOLATION The signed manifest supplied as the Credentials parameter\r
was invalid (could not be parsed) or Platform-specific authorization failed, etc.\r
- @retval EFI_DEVICE_ERROR An unexpected internal error occurred. \r
- \r
-**/ \r
+ @retval EFI_DEVICE_ERROR An unexpected internal error occurred.\r
+\r
+**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT)(\r
- IN BIS_APPLICATION_HANDLE AppHandle, \r
- IN EFI_BIS_DATA *Credentials, \r
- IN EFI_BIS_DATA *DataObject, \r
- OUT BOOLEAN *IsVerified \r
+ IN BIS_APPLICATION_HANDLE AppHandle,\r
+ IN EFI_BIS_DATA *Credentials,\r
+ IN EFI_BIS_DATA *DataObject,\r
+ OUT BOOLEAN *IsVerified\r
);\r
\r
-/** \r
+/**\r
Retrieves the current status of the Boot Authorization Check Flag.\r
- \r
+\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
- of the BIS service. \r
+ of the BIS service.\r
@param CheckIsRequired The function writes the value TRUE if a Boot Authorization Check is\r
- currently required on this platform, otherwise the function writes \r
- FALSE. \r
- \r
+ currently required on this platform, otherwise the function writes\r
+ FALSE.\r
+\r
@retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
- application instance handle associated with the EFI_BIS protocol. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
+ application instance handle associated with the EFI_BIS protocol.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
@retval EFI_INVALID_PARAMETER The CheckIsRequired parameter supplied by the caller is\r
- NULL or an invalid memory reference. \r
- \r
-**/ \r
+ NULL or an invalid memory reference.\r
+\r
+**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG)(\r
- IN BIS_APPLICATION_HANDLE AppHandle, \r
- OUT BOOLEAN *CheckIsRequired \r
+ IN BIS_APPLICATION_HANDLE AppHandle,\r
+ OUT BOOLEAN *CheckIsRequired\r
);\r
\r
-/** \r
+/**\r
Retrieves a unique token value to be included in the request credential for the next update of any\r
- parameter in the Boot Object Authorization set \r
- \r
- @param AppHandle An opaque handle that identifies the caller's \r
- instance of initialization of the BIS service. \r
- @param UpdateToken The function writes an allocated EFI_BIS_DATA* \r
- containing the newunique update token value. \r
- The caller musteventually free the memory allocated \r
+ parameter in the Boot Object Authorization set\r
+\r
+ @param AppHandle An opaque handle that identifies the caller's\r
+ instance of initialization of the BIS service.\r
+ @param UpdateToken The function writes an allocated EFI_BIS_DATA*\r
+ containing the newunique update token value.\r
+ The caller musteventually free the memory allocated\r
by this function using the function Free().\r
- \r
+\r
@retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
- application instance handle associated with the EFI_BIS protocol. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
+ application instance handle associated with the EFI_BIS protocol.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
@retval EFI_INVALID_PARAMETER The UpdateToken parameter supplied by the caller is NULL or\r
- an invalid memory reference. \r
- @retval EFI_DEVICE_ERROR An unexpected internal error occurred. \r
- \r
-**/ \r
+ an invalid memory reference.\r
+ @retval EFI_DEVICE_ERROR An unexpected internal error occurred.\r
+\r
+**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN)(\r
- IN BIS_APPLICATION_HANDLE AppHandle, \r
- OUT EFI_BIS_DATA **UpdateToken \r
+ IN BIS_APPLICATION_HANDLE AppHandle,\r
+ OUT EFI_BIS_DATA **UpdateToken\r
);\r
\r
-/** \r
+/**\r
Updates one of the configurable parameters of the Boot Object Authorization set.\r
- \r
- @param AppHandle An opaque handle that identifies the caller's \r
- instance of initialization of the BIS service. \r
- @param RequestCredential This is a Signed Manifest with embedded attributes \r
- that carry the details of the requested update. \r
- @param NewUpdateToken The function writes an allocated EFI_BIS_DATA* \r
- containing the new unique update token value. \r
- The caller must eventually free the memory allocated \r
+\r
+ @param AppHandle An opaque handle that identifies the caller's\r
+ instance of initialization of the BIS service.\r
+ @param RequestCredential This is a Signed Manifest with embedded attributes\r
+ that carry the details of the requested update.\r
+ @param NewUpdateToken The function writes an allocated EFI_BIS_DATA*\r
+ containing the new unique update token value.\r
+ The caller must eventually free the memory allocated\r
by this function using the function Free().\r
- \r
- @retval EFI_SUCCESS The function completed successfully. \r
- @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid \r
- application instance handle associated with the EFI_BIS protocol. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
- @retval EFI_INVALID_PARAMETER One or more parameters are invalid. \r
- @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the RequestCredential parameter \r
- was invalid (could not be parsed) or Platform-specific authorization failed, etc. \r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
+ application instance handle associated with the EFI_BIS protocol.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
+ @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the RequestCredential parameter\r
+ was invalid (could not be parsed) or Platform-specific authorization failed, etc.\r
@retval EFI_DEVICE_ERROR An unexpected internal error occurred while analyzing the new\r
certificate's key algorithm, or while attempting to retrieve\r
the public key algorithm of the manifest's signer's certificate,\r
- or An unexpected internal error occurred in a cryptographic software module. \r
- \r
-**/ \r
+ or An unexpected internal error occurred in a cryptographic software module.\r
+\r
+**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION)(\r
- IN BIS_APPLICATION_HANDLE AppHandle, \r
- IN EFI_BIS_DATA *RequestCredential, \r
- OUT EFI_BIS_DATA **NewUpdateToken \r
+ IN BIS_APPLICATION_HANDLE AppHandle,\r
+ IN EFI_BIS_DATA *RequestCredential,\r
+ OUT EFI_BIS_DATA **NewUpdateToken\r
);\r
\r
-/** \r
+/**\r
Verifies the integrity and authorization of the indicated data object according to the indicated\r
- credentials and authority certificate. \r
- \r
+ credentials and authority certificate.\r
+\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
- of the BIS service. \r
+ of the BIS service.\r
@param Credentials A Signed Manifest containing verification information for the\r
- indicated data object. \r
+ indicated data object.\r
@param DataObject An in-memory copy of the raw data object to be verified.\r
- @param SectionName An ASCII string giving the section name in the \r
+ @param SectionName An ASCII string giving the section name in the\r
manifest holding the verification information (in other words,\r
- hash value) that corresponds to DataObject. \r
- @param AuthorityCertificate A digital certificate whose public key must match the signer's \r
- public key which is found in the credentials. \r
+ hash value) that corresponds to DataObject.\r
+ @param AuthorityCertificate A digital certificate whose public key must match the signer's\r
+ public key which is found in the credentials.\r
@param IsVerified The function writes TRUE if the verification was successful.\r
- Otherwise, the function writes FALSE. \r
- \r
- @retval EFI_SUCCESS The function completed successfully. \r
- @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid \r
- application instance handle associated with the EFI_BIS protocol. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
- @retval EFI_INVALID_PARAMETER One or more parameters are invalid. \r
+ Otherwise, the function writes FALSE.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
+ application instance handle associated with the EFI_BIS protocol.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
@retval EFI_SECURITY_VIOLATION The Credentials.Data supplied by the caller is NULL,\r
- or the AuthorityCertificate supplied by the caller was \r
- invalid (could not be parsed), \r
- or Platform-specific authorization failed, etc. \r
+ or the AuthorityCertificate supplied by the caller was\r
+ invalid (could not be parsed),\r
+ or Platform-specific authorization failed, etc.\r
@retval EFI_DEVICE_ERROR An unexpected internal error occurred while attempting to retrieve\r
the public key algorithm of the manifest's signer's certificate,\r
- or An unexpected internal error occurred in a cryptographic software module. \r
-**/ \r
+ or An unexpected internal error occurred in a cryptographic software module.\r
+**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL)(\r
- IN BIS_APPLICATION_HANDLE AppHandle, \r
- IN EFI_BIS_DATA *Credentials, \r
- IN EFI_BIS_DATA *DataObject, \r
- IN EFI_BIS_DATA *SectionName, \r
- IN EFI_BIS_DATA *AuthorityCertificate, \r
- OUT BOOLEAN *IsVerified \r
+ IN BIS_APPLICATION_HANDLE AppHandle,\r
+ IN EFI_BIS_DATA *Credentials,\r
+ IN EFI_BIS_DATA *DataObject,\r
+ IN EFI_BIS_DATA *SectionName,\r
+ IN EFI_BIS_DATA *AuthorityCertificate,\r
+ OUT BOOLEAN *IsVerified\r
);\r
\r
-/** \r
+/**\r
Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength\r
- combinations that the platform supports. \r
+ combinations that the platform supports.\r
\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
- of the BIS service. \r
+ of the BIS service.\r
@param SignatureInfo The function writes an allocated EFI_BIS_DATA* containing the array\r
- of EFI_BIS_SIGNATURE_INFO structures representing the supported \r
+ of EFI_BIS_SIGNATURE_INFO structures representing the supported\r
digital certificate identifier, algorithm, and key length combinations.\r
The caller must eventually free the memory allocated by this function using the function Free().\r
\r
- @retval EFI_SUCCESS The function completed successfully. \r
- @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid \r
- application instance handle associated with the EFI_BIS protocol. \r
- @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
+ application instance handle associated with the EFI_BIS protocol.\r
+ @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources.\r
@retval EFI_INVALID_PARAMETER The SignatureInfo parameter supplied by the caller is NULL\r
or an invalid memory reference.\r
@retval EFI_DEVICE_ERROR An unexpected internal error occurred in a\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BIS_GET_SIGNATURE_INFO)(\r
- IN BIS_APPLICATION_HANDLE AppHandle, \r
- OUT EFI_BIS_DATA **SignatureInfo \r
+ IN BIS_APPLICATION_HANDLE AppHandle,\r
+ OUT EFI_BIS_DATA **SignatureInfo\r
);\r
\r
///\r