X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FBis.h;h=03cae05907c2ceab265ad68d30a69e3c16f4fd33;hb=035987042c77a68ec0bc9b15f1d95ddda7949d6f;hp=37d1952c17a63326c61991c6385aa70ad3e68ae4;hpb=d1f950002362305fcd4c30f108ef7b76679f5843;p=mirror_edk2.git diff --git a/MdePkg/Include/Protocol/Bis.h b/MdePkg/Include/Protocol/Bis.h index 37d1952c17..03cae05907 100644 --- a/MdePkg/Include/Protocol/Bis.h +++ b/MdePkg/Include/Protocol/Bis.h @@ -1,16 +1,18 @@ /** @file - This file defines the BIS protocol. - - Copyright (c) 2006, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + 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 - 2010, Intel Corporation. All rights reserved.
+This program and the accompanying materials are licensed and made available under +the terms and conditions of the BSD License that accompanies this distribution. +The full text of the license may be found at +http://opensource.org/licenses/bsd-license.php. + +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - Module Name: Bis.h + @par Revision Reference: + This Protocol is introduced in EFI Specification 1.10. **/ @@ -22,6 +24,19 @@ 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; @@ -32,22 +47,20 @@ typedef VOID *BIS_APPLICATION_HANDLE; typedef UINT16 BIS_ALG_ID; typedef UINT32 BIS_CERT_ID; -// -// EFI_BIS_DATA type. -// -// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ). -// +/// +/// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ). +/// typedef struct { - UINT32 Length; // Length of Data in 8 bit bytes. - UINT8 *Data; // 32 Bit Flat Address of data. + 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. -// +/// +/// EFI_BIS_VERSION type. +/// typedef struct { - UINT32 Major; // BIS Interface version number. - UINT32 Minor; // Build number. + UINT32 Major; ///< The major BIS version number. + UINT32 Minor; ///< A minor BIS version number. } EFI_BIS_VERSION; // @@ -59,66 +72,53 @@ typedef struct { #define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1 #define BIS_VERSION_1 1 -// -// EFI_BIS_SIGNATURE_INFO type. -// +/// +/// EFI_BIS_SIGNATURE_INFO type. +/// typedef struct { - BIS_CERT_ID CertificateID; // Truncated hash of platform Boot Object - // authorization certificate. - // - BIS_ALG_ID AlgorithmID; // A signature algorithm number. - UINT16 KeyLength; // Length of alg. keys in bits. + 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; -// -// Currently defined values for EFI_BIS_SIGNATURE_INFO.AlgorithmID. -// The exact numeric values come from -// "Common Data Security Architecture (CDSA) Specification". -// +/// +/// 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 -// Currently defined values for EFI_BIS_SIGNATURE_INFO.CertificateId. -// +/// +/// 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 following is a 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. -// +/// +/// 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*. -// +/// +/// 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*. -// +/// +/// 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) -// -// Binary Value of "X-Intel-BIS-ParameterSet" Attribute. -// (Value is Base64 encoded in actual signed manifest). -// {EDD35E31-07B9-11d2-83A3-00A0C91FADCF} -// -#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \ - { \ - 0xedd35e31, 0x7b9, 0x11d2, \ - { \ - 0x83, 0xa3, 0x0, 0xa0, 0xc9, 0x1f, 0xad, 0xcf \ - } \ - } - -// -// Support old name for backward compatible -// +/// +/// Support an old name for backward compatibility. +/// #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \ BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID @@ -134,24 +134,38 @@ typedef struct { interface version desired. On output, both the major and minor version numbers are updated with the major and minor version - numbers of the interface + 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 The function encountered an unexpected internal failure. - @retval EFI_INVALID_PARAMETER One or more parameters are invalid. + @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) ( +(EFIAPI *EFI_BIS_INITIALIZE)( IN EFI_BIS_PROTOCOL *This, OUT BIS_APPLICATION_HANDLE *AppHandle, IN OUT EFI_BIS_VERSION *InterfaceVersion, @@ -163,7 +177,8 @@ EFI_STATUS @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. + @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 @@ -175,7 +190,7 @@ EFI_STATUS **/ typedef EFI_STATUS -(EFIAPI *EFI_BIS_FREE) ( +(EFIAPI *EFI_BIS_FREE)( IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA *ToFree ); @@ -188,15 +203,16 @@ EFI_STATUS 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 + @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. - -**/ + @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) ( +(EFIAPI *EFI_BIS_SHUTDOWN)( IN BIS_APPLICATION_HANDLE AppHandle ); @@ -207,7 +223,8 @@ EFI_STATUS @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. + 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 @@ -220,7 +237,7 @@ EFI_STATUS **/ typedef EFI_STATUS -(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE) ( +(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE)( IN BIS_APPLICATION_HANDLE AppHandle, OUT EFI_BIS_DATA **Certificate ); @@ -249,7 +266,7 @@ EFI_STATUS **/ typedef EFI_STATUS -(EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT) ( +(EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT)( IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA *Credentials, IN EFI_BIS_DATA *DataObject, @@ -275,7 +292,7 @@ EFI_STATUS **/ typedef EFI_STATUS -(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG) ( +(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG)( IN BIS_APPLICATION_HANDLE AppHandle, OUT BOOLEAN *CheckIsRequired ); @@ -284,10 +301,12 @@ EFI_STATUS 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 new - unique update token value. + @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 @@ -300,7 +319,7 @@ EFI_STATUS **/ typedef EFI_STATUS -(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN) ( +(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN)( IN BIS_APPLICATION_HANDLE AppHandle, OUT EFI_BIS_DATA **UpdateToken ); @@ -308,12 +327,14 @@ EFI_STATUS /** 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. + @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 @@ -322,12 +343,15 @@ EFI_STATUS @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. + @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) ( +(EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION)( IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA *RequestCredential, OUT EFI_BIS_DATA **NewUpdateToken @@ -342,7 +366,7 @@ EFI_STATUS @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 (not Unicode) string giving the section name in the + @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 @@ -359,12 +383,13 @@ EFI_STATUS 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. - + @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) ( +(EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL)( IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA *Credentials, IN EFI_BIS_DATA *DataObject, @@ -376,29 +401,37 @@ EFI_STATUS /** 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. - + 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. - + 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) ( +(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;