/** @file\r
- This file defines the BIS protocol.\r
-\r
- Copyright (c) 2006, 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
+ 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
+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
\r
- Module Name: Bis.h\r
+ @par Revision Reference: \r
+ This Protocol is introduced in EFI Specification 1.10. \r
\r
**/\r
\r
0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \\r
}\r
\r
+//\r
+// X-Intel-BIS-ParameterSet\r
+// Attribute value\r
+// Binary Value of X-Intel-BIS-ParameterSet Attribute.\r
+// (Value is Base-64 encoded in actual signed manifest).\r
+//\r
+#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \\r
+ { \\r
+ 0xedd35e31, 0x7b9, 0x11d2, { 0x83,0xa3,0x0,0xa0,0xc9,0x1f,0xad,0xcf } \\r
+ }\r
+\r
+\r
+\r
typedef struct _EFI_BIS_PROTOCOL EFI_BIS_PROTOCOL;\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; ///< The 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; ///< The 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 the\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
-// Binary Value of "X-Intel-BIS-ParameterSet" Attribute.\r
-// (Value is Base64 encoded in actual signed manifest).\r
-// {EDD35E31-07B9-11d2-83A3-00A0C91FADCF}\r
-//\r
-#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \\r
- { \\r
- 0xedd35e31, 0x7b9, 0x11d2, \\r
- { \\r
- 0x83, 0xa3, 0x0, 0xa0, 0xc9, 0x1f, 0xad, 0xcf \\r
- } \\r
- }\r
-\r
-//\r
-// Support old name for backward compatible\r
-//\r
+///\r
+/// Support an 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
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
+ @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
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 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
+ @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
@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
/** \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 instance of initialization\r
- of the BIS service. \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
+ @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
@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
projects / mirror_edk2.git / blobdiff