| /** @file |
| The EFI_BIS_PROTOCOL is used to check a digital signature of a data block |
| against a digital certificate for the purpose of an integrity and authorization check. |
| |
| Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> |
| SPDX-License-Identifier: BSD-2-Clause-Patent |
| |
| @par Revision Reference: |
| This Protocol is introduced in EFI Specification 1.10. |
| |
| **/ |
| |
| #ifndef __BIS_H__ |
| #define __BIS_H__ |
| |
| #define EFI_BIS_PROTOCOL_GUID \ |
| { \ |
| 0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \ |
| } |
| |
| // |
| // X-Intel-BIS-ParameterSet |
| // Attribute value |
| // Binary Value of X-Intel-BIS-ParameterSet Attribute. |
| // (Value is Base-64 encoded in actual signed manifest). |
| // |
| #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \ |
| { \ |
| 0xedd35e31, 0x7b9, 0x11d2, { 0x83,0xa3,0x0,0xa0,0xc9,0x1f,0xad,0xcf } \ |
| } |
| |
| |
| |
| typedef struct _EFI_BIS_PROTOCOL EFI_BIS_PROTOCOL; |
| |
| |
| // |
| // Basic types |
| // |
| typedef VOID *BIS_APPLICATION_HANDLE; |
| typedef UINT16 BIS_ALG_ID; |
| typedef UINT32 BIS_CERT_ID; |
| |
| /// |
| /// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ). |
| /// |
| typedef struct { |
| UINT32 Length; ///< The length of Data in 8 bit bytes. |
| UINT8 *Data; ///< 32 Bit Flat Address of data. |
| } EFI_BIS_DATA; |
| |
| /// |
| /// EFI_BIS_VERSION type. |
| /// |
| typedef struct { |
| UINT32 Major; ///< The major BIS version number. |
| UINT32 Minor; ///< A minor BIS version number. |
| } EFI_BIS_VERSION; |
| |
| // |
| // ----------------------------------------------------// |
| // Use these values to initialize EFI_BIS_VERSION.Major |
| // and to interpret results of Initialize. |
| // ----------------------------------------------------// |
| // |
| #define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1 |
| #define BIS_VERSION_1 1 |
| |
| /// |
| /// EFI_BIS_SIGNATURE_INFO type. |
| /// |
| typedef struct { |
| BIS_CERT_ID CertificateID; ///< Truncated hash of platform Boot Object |
| BIS_ALG_ID AlgorithmID; ///< A signature algorithm number. |
| UINT16 KeyLength; ///< The length of alg. keys in bits. |
| } EFI_BIS_SIGNATURE_INFO; |
| |
| /// |
| /// values for EFI_BIS_SIGNATURE_INFO.AlgorithmID. |
| /// The exact numeric values come from the |
| /// "Common Data Security Architecture (CDSA) Specification". |
| /// |
| #define BIS_ALG_DSA (41) // CSSM_ALGID_DSA |
| #define BIS_ALG_RSA_MD5 (42) // CSSM_ALGID_MD5_WITH_RSA |
| /// |
| /// values for EFI_BIS_SIGNATURE_INFO.CertificateId. |
| /// |
| #define BIS_CERT_ID_DSA BIS_ALG_DSA // CSSM_ALGID_DSA |
| #define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA |
| /// |
| /// The mask value that gets applied to the truncated hash of a |
| /// platform Boot Object Authorization Certificate to create the certificateID. |
| /// A certificateID must not have any bits set to the value 1 other than bits in |
| /// this mask. |
| /// |
| #define BIS_CERT_ID_MASK (0xFF7F7FFF) |
| |
| /// |
| /// Macros for dealing with the EFI_BIS_DATA object obtained |
| /// from BIS_GetSignatureInfo(). |
| /// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO |
| /// elements are contained in a EFI_BIS_DATA struct pointed to |
| /// by the provided EFI_BIS_DATA*. |
| /// |
| #define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO)) |
| |
| /// |
| /// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO* |
| /// from a given EFI_BIS_DATA*. |
| /// |
| #define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data) |
| |
| /// |
| /// Support an old name for backward compatibility. |
| /// |
| #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \ |
| BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID |
| |
| /** |
| Initializes the BIS service, checking that it is compatible with the version requested by the caller. |
| After this call, other BIS functions may be invoked. |
| |
| @param This A pointer to the EFI_BIS_PROTOCOL object. |
| @param AppHandle The function writes the new BIS_APPLICATION_HANDLE if |
| successful, otherwise it writes NULL. The caller must eventually |
| destroy this handle by calling Shutdown(). |
| @param InterfaceVersion On input, the caller supplies the major version number of the |
| interface version desired. |
| On output, both the major and minor |
| version numbers are updated with the major and minor version |
| numbers of the interface. This update is done whether or not the |
| initialization was successful. |
| @param TargetAddress Indicates a network or device address of the BIS platform to connect to. |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the |
| caller was not compatible with the interface version of the |
| implementation. The InterfaceVersion.Major has |
| been updated with the current interface version. |
| @retval EFI_UNSUPPORTED This is a local-platform implementation and |
| TargetAddress.Data was not NULL, or |
| TargetAddress.Data was any other value that was not |
| supported by the implementation. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_DEVICE_ERROR One of the following device errors: |
| * The function encountered an unexpected internal failure while initializing a cryptographic software module |
| * No cryptographic software module with compatible version was found |
| found |
| * A resource limitation was encountered while using a cryptographic software module. |
| @retval EFI_INVALID_PARAMETER The This parameter supplied by the caller is NULL or does not |
| reference a valid EFI_BIS_PROTOCOL object. Or, |
| the AppHandle parameter supplied by the caller is NULL or |
| an invalid memory reference. Or, |
| the InterfaceVersion parameter supplied by the caller |
| is NULL or an invalid memory reference. Or, |
| the TargetAddress parameter supplied by the caller is |
| NULL or an invalid memory reference. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_INITIALIZE)( |
| IN EFI_BIS_PROTOCOL *This, |
| OUT BIS_APPLICATION_HANDLE *AppHandle, |
| IN OUT EFI_BIS_VERSION *InterfaceVersion, |
| IN EFI_BIS_DATA *TargetAddress |
| ); |
| |
| /** |
| Frees memory structures allocated and returned by other functions in the EFI_BIS protocol. |
| |
| @param AppHandle An opaque handle that identifies the caller's instance of initialization |
| of the BIS service. |
| @param ToFree An EFI_BIS_DATA* and associated memory block to be freed. |
| This EFI_BIS_DATA* must have been allocated by one of the other BIS functions. |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid |
| application instance handle associated with the EFI_BIS protocol. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_INVALID_PARAMETER The ToFree parameter is not or is no longer a memory resource |
| associated with this AppHandle. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_FREE)( |
| IN BIS_APPLICATION_HANDLE AppHandle, |
| IN EFI_BIS_DATA *ToFree |
| ); |
| |
| /** |
| Shuts down an application's instance of the BIS service, invalidating the application handle. After |
| this call, other BIS functions may no longer be invoked using the application handle value. |
| |
| @param AppHandle An opaque handle that identifies the caller's instance of initialization |
| of the BIS service. |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_NO_MAPPING The AppHandle parameter is not, or is no longer, a valid |
| application instance handle associated with the EFI_BIS protocol. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure while |
| returning resources associated with a cryptographic software module, or |
| while trying to shut down a cryptographic software module. |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_SHUTDOWN)( |
| IN BIS_APPLICATION_HANDLE AppHandle |
| ); |
| |
| /** |
| Retrieves the certificate that has been configured as the identity of the organization designated as |
| the source of authorization for signatures of boot objects. |
| |
| @param AppHandle An opaque handle that identifies the caller's instance of initialization |
| of the BIS service. |
| @param Certificate The function writes an allocated EFI_BIS_DATA* containing the Boot |
| Object Authorization Certificate object. The caller must |
| eventually free the memory allocated by this function using the function Free(). |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid |
| application instance handle associated with the EFI_BIS protocol. |
| @retval EFI_NOT_FOUND There is no Boot Object Authorization Certificate currently installed. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_INVALID_PARAMETER The Certificate parameter supplied by the caller is NULL or |
| an invalid memory reference. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE)( |
| IN BIS_APPLICATION_HANDLE AppHandle, |
| OUT EFI_BIS_DATA **Certificate |
| ); |
| |
| /** |
| Verifies the integrity and authorization of the indicated data object according to the |
| indicated credentials. |
| |
| @param AppHandle An opaque handle that identifies the caller's instance of initialization |
| of the BIS service. |
| @param Credentials A Signed Manifest containing verification information for the indicated |
| data object. |
| @param DataObject An in-memory copy of the raw data object to be verified. |
| @param IsVerified The function writes TRUE if the verification succeeded, otherwise |
| FALSE. |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid |
| application instance handle associated with the EFI_BIS protocol. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_INVALID_PARAMETER One or more parameters are invalid. |
| @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the Credentials parameter |
| was invalid (could not be parsed) or Platform-specific authorization failed, etc. |
| @retval EFI_DEVICE_ERROR An unexpected internal error occurred. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT)( |
| IN BIS_APPLICATION_HANDLE AppHandle, |
| IN EFI_BIS_DATA *Credentials, |
| IN EFI_BIS_DATA *DataObject, |
| OUT BOOLEAN *IsVerified |
| ); |
| |
| /** |
| Retrieves the current status of the Boot Authorization Check Flag. |
| |
| @param AppHandle An opaque handle that identifies the caller's instance of initialization |
| of the BIS service. |
| @param CheckIsRequired The function writes the value TRUE if a Boot Authorization Check is |
| currently required on this platform, otherwise the function writes |
| FALSE. |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid |
| application instance handle associated with the EFI_BIS protocol. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_INVALID_PARAMETER The CheckIsRequired parameter supplied by the caller is |
| NULL or an invalid memory reference. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG)( |
| IN BIS_APPLICATION_HANDLE AppHandle, |
| OUT BOOLEAN *CheckIsRequired |
| ); |
| |
| /** |
| Retrieves a unique token value to be included in the request credential for the next update of any |
| parameter in the Boot Object Authorization set |
| |
| @param AppHandle An opaque handle that identifies the caller's |
| instance of initialization of the BIS service. |
| @param UpdateToken The function writes an allocated EFI_BIS_DATA* |
| containing the newunique update token value. |
| The caller musteventually free the memory allocated |
| by this function using the function Free(). |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid |
| application instance handle associated with the EFI_BIS protocol. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_INVALID_PARAMETER The UpdateToken parameter supplied by the caller is NULL or |
| an invalid memory reference. |
| @retval EFI_DEVICE_ERROR An unexpected internal error occurred. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN)( |
| IN BIS_APPLICATION_HANDLE AppHandle, |
| OUT EFI_BIS_DATA **UpdateToken |
| ); |
| |
| /** |
| Updates one of the configurable parameters of the Boot Object Authorization set. |
| |
| @param AppHandle An opaque handle that identifies the caller's |
| instance of initialization of the BIS service. |
| @param RequestCredential This is a Signed Manifest with embedded attributes |
| that carry the details of the requested update. |
| @param NewUpdateToken The function writes an allocated EFI_BIS_DATA* |
| containing the new unique update token value. |
| The caller must eventually free the memory allocated |
| by this function using the function Free(). |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid |
| application instance handle associated with the EFI_BIS protocol. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_INVALID_PARAMETER One or more parameters are invalid. |
| @retval EFI_SECURITY_VIOLATION The signed manifest supplied as the RequestCredential parameter |
| was invalid (could not be parsed) or Platform-specific authorization failed, etc. |
| @retval EFI_DEVICE_ERROR An unexpected internal error occurred while analyzing the new |
| certificate's key algorithm, or while attempting to retrieve |
| the public key algorithm of the manifest's signer's certificate, |
| or An unexpected internal error occurred in a cryptographic software module. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION)( |
| IN BIS_APPLICATION_HANDLE AppHandle, |
| IN EFI_BIS_DATA *RequestCredential, |
| OUT EFI_BIS_DATA **NewUpdateToken |
| ); |
| |
| /** |
| Verifies the integrity and authorization of the indicated data object according to the indicated |
| credentials and authority certificate. |
| |
| @param AppHandle An opaque handle that identifies the caller's instance of initialization |
| of the BIS service. |
| @param Credentials A Signed Manifest containing verification information for the |
| indicated data object. |
| @param DataObject An in-memory copy of the raw data object to be verified. |
| @param SectionName An ASCII string giving the section name in the |
| manifest holding the verification information (in other words, |
| hash value) that corresponds to DataObject. |
| @param AuthorityCertificate A digital certificate whose public key must match the signer's |
| public key which is found in the credentials. |
| @param IsVerified The function writes TRUE if the verification was successful. |
| Otherwise, the function writes FALSE. |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid |
| application instance handle associated with the EFI_BIS protocol. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_INVALID_PARAMETER One or more parameters are invalid. |
| @retval EFI_SECURITY_VIOLATION The Credentials.Data supplied by the caller is NULL, |
| or the AuthorityCertificate supplied by the caller was |
| invalid (could not be parsed), |
| or Platform-specific authorization failed, etc. |
| @retval EFI_DEVICE_ERROR An unexpected internal error occurred while attempting to retrieve |
| the public key algorithm of the manifest's signer's certificate, |
| or An unexpected internal error occurred in a cryptographic software module. |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL)( |
| IN BIS_APPLICATION_HANDLE AppHandle, |
| IN EFI_BIS_DATA *Credentials, |
| IN EFI_BIS_DATA *DataObject, |
| IN EFI_BIS_DATA *SectionName, |
| IN EFI_BIS_DATA *AuthorityCertificate, |
| OUT BOOLEAN *IsVerified |
| ); |
| |
| /** |
| Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength |
| combinations that the platform supports. |
| |
| @param AppHandle An opaque handle that identifies the caller's instance of initialization |
| of the BIS service. |
| @param SignatureInfo The function writes an allocated EFI_BIS_DATA* containing the array |
| of EFI_BIS_SIGNATURE_INFO structures representing the supported |
| digital certificate identifier, algorithm, and key length combinations. |
| The caller must eventually free the memory allocated by this function using the function Free(). |
| |
| @retval EFI_SUCCESS The function completed successfully. |
| @retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid |
| application instance handle associated with the EFI_BIS protocol. |
| @retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. |
| @retval EFI_INVALID_PARAMETER The SignatureInfo parameter supplied by the caller is NULL |
| or an invalid memory reference. |
| @retval EFI_DEVICE_ERROR An unexpected internal error occurred in a |
| cryptographic software module, or |
| The function encountered an unexpected internal consistency check |
| failure (possible corruption of stored Boot Object Authorization Certificate). |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_BIS_GET_SIGNATURE_INFO)( |
| IN BIS_APPLICATION_HANDLE AppHandle, |
| OUT EFI_BIS_DATA **SignatureInfo |
| ); |
| |
| /// |
| /// The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital |
| /// certificate for the purpose of an integrity and authorization check. |
| /// |
| struct _EFI_BIS_PROTOCOL { |
| EFI_BIS_INITIALIZE Initialize; |
| EFI_BIS_SHUTDOWN Shutdown; |
| EFI_BIS_FREE Free; |
| EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE GetBootObjectAuthorizationCertificate; |
| EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG GetBootObjectAuthorizationCheckFlag; |
| EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN GetBootObjectAuthorizationUpdateToken; |
| EFI_BIS_GET_SIGNATURE_INFO GetSignatureInfo; |
| EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION UpdateBootObjectAuthorization; |
| EFI_BIS_VERIFY_BOOT_OBJECT VerifyBootObject; |
| EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL VerifyObjectWithCredential; |
| }; |
| |
| extern EFI_GUID gEfiBisProtocolGuid; |
| extern EFI_GUID gBootObjectAuthorizationParmsetGuid; |
| |
| #endif |