/** @file\r
- This file defines the BIS protocol.\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, Intel Corporation \r
+ Copyright (c) 2006 - 2009, Intel Corporation \r
All rights reserved. This program and the accompanying materials \r
are licensed and made available under the terms and conditions of the BSD License \r
which accompanies this distribution. 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
+ 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
typedef UINT16 BIS_ALG_ID;\r
typedef UINT32 BIS_CERT_ID;\r
\r
-//\r
-// EFI_BIS_DATA type.\r
-//\r
-// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).\r
-//\r
+///\r
+/// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).\r
+///\r
typedef struct {\r
- UINT32 Length; // Length of Data in 8 bit bytes.\r
- UINT8 *Data; // 32 Bit Flat Address of data.\r
+ UINT32 Length; ///< Length of Data in 8 bit bytes.\r
+ UINT8 *Data; ///< 32 Bit Flat Address of data.\r
} EFI_BIS_DATA;\r
\r
-//\r
-// EFI_BIS_VERSION type.\r
-//\r
+///\r
+/// EFI_BIS_VERSION type.\r
+///\r
typedef struct {\r
- UINT32 Major; // BIS Interface version number.\r
- UINT32 Minor; // Build number.\r
+ UINT32 Major; ///< the major BIS version number.\r
+ UINT32 Minor; ///< a minor BIS version number.\r
} EFI_BIS_VERSION;\r
\r
//\r
#define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1\r
#define BIS_VERSION_1 1\r
\r
-//\r
-// EFI_BIS_SIGNATURE_INFO type.\r
-//\r
+///\r
+/// EFI_BIS_SIGNATURE_INFO type.\r
+///\r
typedef struct {\r
- BIS_CERT_ID CertificateID; // Truncated hash of platform Boot Object\r
- // authorization certificate.\r
- //\r
- BIS_ALG_ID AlgorithmID; // A signature algorithm number.\r
- UINT16 KeyLength; // Length of alg. keys in bits.\r
+ BIS_CERT_ID CertificateID; ///< Truncated hash of platform Boot Object\r
+ BIS_ALG_ID AlgorithmID; ///< A signature algorithm number.\r
+ UINT16 KeyLength; ///< Length of alg. keys in bits.\r
} EFI_BIS_SIGNATURE_INFO;\r
\r
-//\r
-// Currently defined values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.\r
-// The exact numeric values come from\r
-// "Common Data Security Architecture (CDSA) Specification".\r
-//\r
+///\r
+/// values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.\r
+/// The exact numeric values come from\r
+/// "Common Data Security Architecture (CDSA) Specification".\r
+///\r
#define BIS_ALG_DSA (41) // CSSM_ALGID_DSA\r
#define BIS_ALG_RSA_MD5 (42) // CSSM_ALGID_MD5_WITH_RSA\r
-// Currently defined values for EFI_BIS_SIGNATURE_INFO.CertificateId.\r
-//\r
+///\r
+/// values for EFI_BIS_SIGNATURE_INFO.CertificateId.\r
+///\r
#define BIS_CERT_ID_DSA BIS_ALG_DSA // CSSM_ALGID_DSA\r
#define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA\r
-// The following is a mask value that gets applied to the truncated hash of a\r
-// platform Boot Object Authorization Certificate to create the certificateID.\r
-// A certificateID must not have any bits set to the value 1 other than bits in\r
-// this mask.\r
-//\r
+///\r
+/// the mask value that gets applied to the truncated hash of a\r
+/// platform Boot Object Authorization Certificate to create the certificateID.\r
+/// A certificateID must not have any bits set to the value 1 other than bits in\r
+/// this mask.\r
+///\r
#define BIS_CERT_ID_MASK (0xFF7F7FFF)\r
\r
-//\r
-// Macros for dealing with the EFI_BIS_DATA object obtained\r
-// from BIS_GetSignatureInfo()\r
-// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO\r
-// elements are contained in a EFI_BIS_DATA struct pointed to\r
-// by the provided EFI_BIS_DATA*.\r
-//\r
+///\r
+/// Macros for dealing with the EFI_BIS_DATA object obtained\r
+/// from BIS_GetSignatureInfo()\r
+/// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO\r
+/// elements are contained in a EFI_BIS_DATA struct pointed to\r
+/// by the provided EFI_BIS_DATA*.\r
+///\r
#define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))\r
\r
-//\r
-// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*\r
-// from a given EFI_BIS_DATA*.\r
-//\r
+///\r
+/// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*\r
+/// from a given EFI_BIS_DATA*.\r
+///\r
#define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)\r
\r
-//\r
-// Support old name for backward compatible\r
-//\r
+///\r
+/// Support old name for backward compatibility\r
+///\r
#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \\r
BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID\r
\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 \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
\r
@retval EFI_SUCCESS The function completed successfully.\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
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
- @retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure.\r
- @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\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
+ found\r
+ * A resource limitation was encountered while using a cryptographic software module.\r
+ @retval EFI_INVALID_PARAMETER The This parameter supplied by the caller is NULL or does not\r
+ reference a valid EFI_BIS_PROTOCOL object, or\r
+ The AppHandle parameter supplied by the caller is NULL or\r
+ an invalid memory reference, or\r
+ The InterfaceVersion parameter supplied by the caller\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
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_INITIALIZE) (\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
\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
+ @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
**/ \r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_FREE) (\r
+(EFIAPI *EFI_BIS_FREE)(\r
IN BIS_APPLICATION_HANDLE AppHandle, \r
IN EFI_BIS_DATA *ToFree \r
);\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_DEVICE_ERROR The function encountered an unexpected internal failure. \r
- \r
-**/ \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
+**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_SHUTDOWN) (\r
+(EFIAPI *EFI_BIS_SHUTDOWN)(\r
IN BIS_APPLICATION_HANDLE AppHandle \r
);\r
\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
of the BIS service. \r
@param Certificate The function writes an allocated EFI_BIS_DATA* containing the Boot\r
- Object Authorization Certificate object. \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
**/ \r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE) (\r
+(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE)(\r
IN BIS_APPLICATION_HANDLE AppHandle, \r
OUT EFI_BIS_DATA **Certificate \r
);\r
**/ \r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT) (\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
**/ \r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG) (\r
+(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG)(\r
IN BIS_APPLICATION_HANDLE AppHandle, \r
OUT BOOLEAN *CheckIsRequired \r
);\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
of the BIS service. \r
@param UpdateToken The function writes an allocated EFI_BIS_DATA* containing the new\r
- unique update token value. \r
+ unique update token value. 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
**/ \r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN) (\r
+(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN)(\r
IN BIS_APPLICATION_HANDLE AppHandle, \r
OUT EFI_BIS_DATA **UpdateToken \r
);\r
@param RequestCredential This is a Signed Manifest with embedded attributes that carry the details\r
of the requested update. \r
@param NewUpdateToken The function writes an allocated EFI_BIS_DATA* containing the new \r
- unique update token value. \r
+ unique update token value. 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
@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. \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
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION) (\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
@param Credentials A Signed Manifest containing verification information for the\r
indicated data object. \r
@param DataObject An in-memory copy of the raw data object to be verified.\r
- @param SectionName An ASCII (not Unicode) 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
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. \r
- \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
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL) (\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
/** \r
Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength\r
combinations that the platform supports. \r
- \r
+\r
@param AppHandle An opaque handle that identifies the caller's instance of initialization\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
- digital certificate identifier, algorithm, and key length combinations. \r
- \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_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. \r
- \r
+ or an invalid memory reference.\r
+ @retval EFI_DEVICE_ERROR An unexpected internal error occurred in a\r
+ cryptographic software module, or\r
+ The function encountered an unexpected internal consistency check\r
+ failure (possible corruption of stored Boot Object Authorization Certificate).\r
+\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_BIS_GET_SIGNATURE_INFO) (\r
+(EFIAPI *EFI_BIS_GET_SIGNATURE_INFO)(\r
IN BIS_APPLICATION_HANDLE AppHandle, \r
OUT EFI_BIS_DATA **SignatureInfo \r
);\r
\r
+///\r
+/// The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital\r
+/// certificate for the purpose of an integrity and authorization check.\r
+///\r
struct _EFI_BIS_PROTOCOL {\r
EFI_BIS_INITIALIZE Initialize;\r
EFI_BIS_SHUTDOWN Shutdown;\r