[mirror_edk2.git] / MdePkg / Include / Protocol / Bis.h

/** @file\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
  @par Revision Reference:          \r
  This Protocol is introduced in EFI Specification 1.10.     \r
\r
**/\r
\r
#ifndef __BIS_H__\r
#define __BIS_H__\r
\r
#define EFI_BIS_PROTOCOL_GUID \\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
//\r
// Basic types\r
//\r
typedef VOID    *BIS_APPLICATION_HANDLE;\r
typedef UINT16  BIS_ALG_ID;\r
typedef UINT32  BIS_CERT_ID;\r
\r
///\r
/// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).\r
///\r
typedef struct {\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
typedef struct {\r
  UINT32  Major;  ///< The major BIS version number.\r
  UINT32  Minor;  ///< A minor BIS version number.\r
} EFI_BIS_VERSION;\r
\r
//\r
// ----------------------------------------------------//\r
// Use these values to initialize EFI_BIS_VERSION.Major\r
// and to interpret results of Initialize.\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
typedef struct {\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
/// 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
///\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
///\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
#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
#define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)\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
/**                                                                 \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
  @param  This                     A pointer to the EFI_BIS_PROTOCOL object.\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
  @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
                                   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
\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         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
  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
  @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
                                   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
  @retval EFI_INVALID_PARAMETER    The ToFree parameter is not or is no longer a memory resource\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
  );\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
  @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\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
  @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
  IN BIS_APPLICATION_HANDLE  AppHandle               \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
  @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.  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
  @retval EFI_INVALID_PARAMETER    The Certificate parameter supplied by the caller is NULL or\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
  );\r
\r
/**                                                                 \r
  Verifies the integrity and authorization of the indicated data object according to the\r
  indicated credentials.                                                                \r
      \r
  @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                   of the BIS service.                                                                                           \r
  @param  Credentials              A Signed Manifest containing verification information for the indicated\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
  @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 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
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
  );\r
\r
/**                                                                 \r
  Retrieves the current status of the Boot Authorization Check Flag.\r
      \r
  @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\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
  @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 CheckIsRequired parameter supplied by the caller is\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
  );\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
                                   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 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
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
  );\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
                                   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
  @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
  IN  BIS_APPLICATION_HANDLE AppHandle,               \r
  IN  EFI_BIS_DATA           *RequestCredential,      \r
  OUT EFI_BIS_DATA           **NewUpdateToken         \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
  @param  AppHandle                An opaque handle that identifies the caller's instance of initialization\r
                                   of the BIS service.                                                                                           \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 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
  @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
  @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
  @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
  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
  Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength\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
  @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
                                   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 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
  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
  EFI_BIS_FREE                                        Free;\r
  EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE   GetBootObjectAuthorizationCertificate;\r
  EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG     GetBootObjectAuthorizationCheckFlag;\r
  EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN  GetBootObjectAuthorizationUpdateToken;\r
  EFI_BIS_GET_SIGNATURE_INFO                          GetSignatureInfo;\r
  EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION            UpdateBootObjectAuthorization;\r
  EFI_BIS_VERIFY_BOOT_OBJECT                          VerifyBootObject;\r
  EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL               VerifyObjectWithCredential;\r
};\r
\r
extern EFI_GUID gEfiBisProtocolGuid;\r
extern EFI_GUID gBootObjectAuthorizationParmsetGuid;\r
\r
#endif\r
Commit	Line	Data
	1	/** @file\r
	2	The EFI_BIS_PROTOCOL is used to check a digital signature of a data block \r
	3	against a digital certificate for the purpose of an integrity and authorization check.\r
	4	\r
	5	Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>\r
	6	This program and the accompanying materials are licensed and made available under \r
	7	the terms and conditions of the BSD License that accompanies this distribution. \r
	8	The full text of the license may be found at\r
	9	http://opensource.org/licenses/bsd-license.php. \r
	10	\r
	11	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	12	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	13	\r
	14	@par Revision Reference: \r
	15	This Protocol is introduced in EFI Specification 1.10. \r
	16	\r
	17	**/\r
	18	\r
	19	#ifndef __BIS_H__\r
	20	#define __BIS_H__\r
	21	\r
	22	#define EFI_BIS_PROTOCOL_GUID \\r
	23	{ \\r
	24	0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \\r
	25	}\r
	26	\r
	27	//\r
	28	// X-Intel-BIS-ParameterSet\r
	29	// Attribute value\r
	30	// Binary Value of X-Intel-BIS-ParameterSet Attribute.\r
	31	// (Value is Base-64 encoded in actual signed manifest).\r
	32	//\r
	33	#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \\r
	34	{ \\r
	35	0xedd35e31, 0x7b9, 0x11d2, { 0x83,0xa3,0x0,0xa0,0xc9,0x1f,0xad,0xcf } \\r
	36	}\r
	37	\r
	38	\r
	39	\r
	40	typedef struct _EFI_BIS_PROTOCOL EFI_BIS_PROTOCOL;\r
	41	\r
	42	\r
	43	//\r
	44	// Basic types\r
	45	//\r
	46	typedef VOID *BIS_APPLICATION_HANDLE;\r
	47	typedef UINT16 BIS_ALG_ID;\r
	48	typedef UINT32 BIS_CERT_ID;\r
	49	\r
	50	///\r
	51	/// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).\r
	52	///\r
	53	typedef struct {\r
	54	UINT32 Length; ///< The length of Data in 8 bit bytes.\r
	55	UINT8 *Data; ///< 32 Bit Flat Address of data.\r
	56	} EFI_BIS_DATA;\r
	57	\r
	58	///\r
	59	/// EFI_BIS_VERSION type.\r
	60	///\r
	61	typedef struct {\r
	62	UINT32 Major; ///< The major BIS version number.\r
	63	UINT32 Minor; ///< A minor BIS version number.\r
	64	} EFI_BIS_VERSION;\r
	65	\r
	66	//\r
	67	// ----------------------------------------------------//\r
	68	// Use these values to initialize EFI_BIS_VERSION.Major\r
	69	// and to interpret results of Initialize.\r
	70	// ----------------------------------------------------//\r
	71	//\r
	72	#define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1\r
	73	#define BIS_VERSION_1 1\r
	74	\r
	75	///\r
	76	/// EFI_BIS_SIGNATURE_INFO type.\r
	77	///\r
	78	typedef struct {\r
	79	BIS_CERT_ID CertificateID; ///< Truncated hash of platform Boot Object\r
	80	BIS_ALG_ID AlgorithmID; ///< A signature algorithm number.\r
	81	UINT16 KeyLength; ///< The length of alg. keys in bits.\r
	82	} EFI_BIS_SIGNATURE_INFO;\r
	83	\r
	84	///\r
	85	/// values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.\r
	86	/// The exact numeric values come from the\r
	87	/// "Common Data Security Architecture (CDSA) Specification".\r
	88	///\r
	89	#define BIS_ALG_DSA (41) // CSSM_ALGID_DSA\r
	90	#define BIS_ALG_RSA_MD5 (42) // CSSM_ALGID_MD5_WITH_RSA\r
	91	///\r
	92	/// values for EFI_BIS_SIGNATURE_INFO.CertificateId.\r
	93	///\r
	94	#define BIS_CERT_ID_DSA BIS_ALG_DSA // CSSM_ALGID_DSA\r
	95	#define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA\r
	96	///\r
	97	/// The mask value that gets applied to the truncated hash of a\r
	98	/// platform Boot Object Authorization Certificate to create the certificateID.\r
	99	/// A certificateID must not have any bits set to the value 1 other than bits in\r
	100	/// this mask.\r
	101	///\r
	102	#define BIS_CERT_ID_MASK (0xFF7F7FFF)\r
	103	\r
	104	///\r
	105	/// Macros for dealing with the EFI_BIS_DATA object obtained\r
	106	/// from BIS_GetSignatureInfo().\r
	107	/// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO\r
	108	/// elements are contained in a EFI_BIS_DATA struct pointed to\r
	109	/// by the provided EFI_BIS_DATA*.\r
	110	///\r
	111	#define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))\r
	112	\r
	113	///\r
	114	/// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*\r
	115	/// from a given EFI_BIS_DATA*.\r
	116	///\r
	117	#define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)\r
	118	\r
	119	///\r
	120	/// Support an old name for backward compatibility.\r
	121	///\r
	122	#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \\r
	123	BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID\r
	124	\r
	125	/** \r
	126	Initializes the BIS service, checking that it is compatible with the version requested by the caller.\r
	127	After this call, other BIS functions may be invoked. \r
	128	\r
	129	@param This A pointer to the EFI_BIS_PROTOCOL object.\r
	130	@param AppHandle The function writes the new BIS_APPLICATION_HANDLE if \r
	131	successful, otherwise it writes NULL. The caller must eventually\r
	132	destroy this handle by calling Shutdown(). \r
	133	@param InterfaceVersion On input, the caller supplies the major version number of the\r
	134	interface version desired. \r
	135	On output, both the major and minor \r
	136	version numbers are updated with the major and minor version\r
	137	numbers of the interface. This update is done whether or not the\r
	138	initialization was successful. \r
	139	@param TargetAddress Indicates a network or device address of the BIS platform to connect to. \r
	140	\r
	141	@retval EFI_SUCCESS The function completed successfully.\r
	142	@retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the \r
	143	caller was not compatible with the interface version of the\r
	144	implementation. The InterfaceVersion.Major has\r
	145	been updated with the current interface version.\r
	146	@retval EFI_UNSUPPORTED This is a local-platform implementation and \r
	147	TargetAddress.Data was not NULL, or \r
	148	TargetAddress.Data was any other value that was not\r
	149	supported by the implementation. \r
	150	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	151	@retval EFI_DEVICE_ERROR One of the following device errors:\r
	152	* The function encountered an unexpected internal failure while initializing a cryptographic software module\r
	153	* No cryptographic software module with compatible version was found\r
	154	found\r
	155	* A resource limitation was encountered while using a cryptographic software module.\r
	156	@retval EFI_INVALID_PARAMETER The This parameter supplied by the caller is NULL or does not\r
	157	reference a valid EFI_BIS_PROTOCOL object. Or,\r
	158	the AppHandle parameter supplied by the caller is NULL or\r
	159	an invalid memory reference. Or,\r
	160	the InterfaceVersion parameter supplied by the caller\r
	161	is NULL or an invalid memory reference. Or,\r
	162	the TargetAddress parameter supplied by the caller is\r
	163	NULL or an invalid memory reference.\r
	164	\r
	165	**/ \r
	166	typedef\r
	167	EFI_STATUS\r
	168	(EFIAPI *EFI_BIS_INITIALIZE)(\r
	169	IN EFI_BIS_PROTOCOL *This, \r
	170	OUT BIS_APPLICATION_HANDLE *AppHandle, \r
	171	IN OUT EFI_BIS_VERSION *InterfaceVersion, \r
	172	IN EFI_BIS_DATA *TargetAddress \r
	173	);\r
	174	\r
	175	/** \r
	176	Frees memory structures allocated and returned by other functions in the EFI_BIS protocol. \r
	177	\r
	178	@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
	179	of the BIS service. \r
	180	@param ToFree An EFI_BIS_DATA* and associated memory block to be freed. \r
	181	This EFI_BIS_DATA* must have been allocated by one of the other BIS functions.\r
	182	\r
	183	@retval EFI_SUCCESS The function completed successfully.\r
	184	@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
	185	application instance handle associated with the EFI_BIS protocol. \r
	186	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	187	@retval EFI_INVALID_PARAMETER The ToFree parameter is not or is no longer a memory resource\r
	188	associated with this AppHandle. \r
	189	\r
	190	**/ \r
	191	typedef\r
	192	EFI_STATUS\r
	193	(EFIAPI *EFI_BIS_FREE)(\r
	194	IN BIS_APPLICATION_HANDLE AppHandle, \r
	195	IN EFI_BIS_DATA *ToFree \r
	196	);\r
	197	\r
	198	/** \r
	199	Shuts down an application's instance of the BIS service, invalidating the application handle. After\r
	200	this call, other BIS functions may no longer be invoked using the application handle value. \r
	201	\r
	202	@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
	203	of the BIS service. \r
	204	\r
	205	@retval EFI_SUCCESS The function completed successfully.\r
	206	@retval EFI_NO_MAPPING The AppHandle parameter is not, or is no longer, a valid\r
	207	application instance handle associated with the EFI_BIS protocol. \r
	208	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	209	@retval EFI_DEVICE_ERROR The function encountered an unexpected internal failure while\r
	210	returning resources associated with a cryptographic software module, or\r
	211	while trying to shut down a cryptographic software module.\r
	212	**/\r
	213	typedef\r
	214	EFI_STATUS\r
	215	(EFIAPI *EFI_BIS_SHUTDOWN)(\r
	216	IN BIS_APPLICATION_HANDLE AppHandle \r
	217	);\r
	218	\r
	219	/** \r
	220	Retrieves the certificate that has been configured as the identity of the organization designated as\r
	221	the source of authorization for signatures of boot objects.\r
	222	\r
	223	@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
	224	of the BIS service. \r
	225	@param Certificate The function writes an allocated EFI_BIS_DATA* containing the Boot\r
	226	Object Authorization Certificate object. The caller must\r
	227	eventually free the memory allocated by this function using the function Free().\r
	228	\r
	229	@retval EFI_SUCCESS The function completed successfully.\r
	230	@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
	231	application instance handle associated with the EFI_BIS protocol. \r
	232	@retval EFI_NOT_FOUND There is no Boot Object Authorization Certificate currently installed. \r
	233	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	234	@retval EFI_INVALID_PARAMETER The Certificate parameter supplied by the caller is NULL or\r
	235	an invalid memory reference. \r
	236	\r
	237	**/ \r
	238	typedef\r
	239	EFI_STATUS\r
	240	(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE)(\r
	241	IN BIS_APPLICATION_HANDLE AppHandle, \r
	242	OUT EFI_BIS_DATA **Certificate \r
	243	);\r
	244	\r
	245	/** \r
	246	Verifies the integrity and authorization of the indicated data object according to the\r
	247	indicated credentials. \r
	248	\r
	249	@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
	250	of the BIS service. \r
	251	@param Credentials A Signed Manifest containing verification information for the indicated\r
	252	data object. \r
	253	@param DataObject An in-memory copy of the raw data object to be verified.\r
	254	@param IsVerified The function writes TRUE if the verification succeeded, otherwise\r
	255	FALSE. \r
	256	\r
	257	@retval EFI_SUCCESS The function completed successfully.\r
	258	@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
	259	application instance handle associated with the EFI_BIS protocol. \r
	260	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	261	@retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
	262	@retval EFI_SECURITY_VIOLATION The signed manifest supplied as the Credentials parameter\r
	263	was invalid (could not be parsed) or Platform-specific authorization failed, etc.\r
	264	@retval EFI_DEVICE_ERROR An unexpected internal error occurred. \r
	265	\r
	266	**/ \r
	267	typedef\r
	268	EFI_STATUS\r
	269	(EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT)(\r
	270	IN BIS_APPLICATION_HANDLE AppHandle, \r
	271	IN EFI_BIS_DATA *Credentials, \r
	272	IN EFI_BIS_DATA *DataObject, \r
	273	OUT BOOLEAN *IsVerified \r
	274	);\r
	275	\r
	276	/** \r
	277	Retrieves the current status of the Boot Authorization Check Flag.\r
	278	\r
	279	@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
	280	of the BIS service. \r
	281	@param CheckIsRequired The function writes the value TRUE if a Boot Authorization Check is\r
	282	currently required on this platform, otherwise the function writes \r
	283	FALSE. \r
	284	\r
	285	@retval EFI_SUCCESS The function completed successfully.\r
	286	@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
	287	application instance handle associated with the EFI_BIS protocol. \r
	288	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	289	@retval EFI_INVALID_PARAMETER The CheckIsRequired parameter supplied by the caller is\r
	290	NULL or an invalid memory reference. \r
	291	\r
	292	**/ \r
	293	typedef\r
	294	EFI_STATUS\r
	295	(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG)(\r
	296	IN BIS_APPLICATION_HANDLE AppHandle, \r
	297	OUT BOOLEAN *CheckIsRequired \r
	298	);\r
	299	\r
	300	/** \r
	301	Retrieves a unique token value to be included in the request credential for the next update of any\r
	302	parameter in the Boot Object Authorization set \r
	303	\r
	304	@param AppHandle An opaque handle that identifies the caller's \r
	305	instance of initialization of the BIS service. \r
	306	@param UpdateToken The function writes an allocated EFI_BIS_DATA* \r
	307	containing the newunique update token value. \r
	308	The caller musteventually free the memory allocated \r
	309	by this function using the function Free().\r
	310	\r
	311	@retval EFI_SUCCESS The function completed successfully.\r
	312	@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid\r
	313	application instance handle associated with the EFI_BIS protocol. \r
	314	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	315	@retval EFI_INVALID_PARAMETER The UpdateToken parameter supplied by the caller is NULL or\r
	316	an invalid memory reference. \r
	317	@retval EFI_DEVICE_ERROR An unexpected internal error occurred. \r
	318	\r
	319	**/ \r
	320	typedef\r
	321	EFI_STATUS\r
	322	(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN)(\r
	323	IN BIS_APPLICATION_HANDLE AppHandle, \r
	324	OUT EFI_BIS_DATA **UpdateToken \r
	325	);\r
	326	\r
	327	/** \r
	328	Updates one of the configurable parameters of the Boot Object Authorization set.\r
	329	\r
	330	@param AppHandle An opaque handle that identifies the caller's \r
	331	instance of initialization of the BIS service. \r
	332	@param RequestCredential This is a Signed Manifest with embedded attributes \r
	333	that carry the details of the requested update. \r
	334	@param NewUpdateToken The function writes an allocated EFI_BIS_DATA* \r
	335	containing the new unique update token value. \r
	336	The caller must eventually free the memory allocated \r
	337	by this function using the function Free().\r
	338	\r
	339	@retval EFI_SUCCESS The function completed successfully. \r
	340	@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid \r
	341	application instance handle associated with the EFI_BIS protocol. \r
	342	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	343	@retval EFI_INVALID_PARAMETER One or more parameters are invalid. \r
	344	@retval EFI_SECURITY_VIOLATION The signed manifest supplied as the RequestCredential parameter \r
	345	was invalid (could not be parsed) or Platform-specific authorization failed, etc. \r
	346	@retval EFI_DEVICE_ERROR An unexpected internal error occurred while analyzing the new\r
	347	certificate's key algorithm, or while attempting to retrieve\r
	348	the public key algorithm of the manifest's signer's certificate,\r
	349	or An unexpected internal error occurred in a cryptographic software module. \r
	350	\r
	351	**/ \r
	352	typedef\r
	353	EFI_STATUS\r
	354	(EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION)(\r
	355	IN BIS_APPLICATION_HANDLE AppHandle, \r
	356	IN EFI_BIS_DATA *RequestCredential, \r
	357	OUT EFI_BIS_DATA **NewUpdateToken \r
	358	);\r
	359	\r
	360	/** \r
	361	Verifies the integrity and authorization of the indicated data object according to the indicated\r
	362	credentials and authority certificate. \r
	363	\r
	364	@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
	365	of the BIS service. \r
	366	@param Credentials A Signed Manifest containing verification information for the\r
	367	indicated data object. \r
	368	@param DataObject An in-memory copy of the raw data object to be verified.\r
	369	@param SectionName An ASCII string giving the section name in the \r
	370	manifest holding the verification information (in other words,\r
	371	hash value) that corresponds to DataObject. \r
	372	@param AuthorityCertificate A digital certificate whose public key must match the signer's \r
	373	public key which is found in the credentials. \r
	374	@param IsVerified The function writes TRUE if the verification was successful.\r
	375	Otherwise, the function writes FALSE. \r
	376	\r
	377	@retval EFI_SUCCESS The function completed successfully. \r
	378	@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid \r
	379	application instance handle associated with the EFI_BIS protocol. \r
	380	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	381	@retval EFI_INVALID_PARAMETER One or more parameters are invalid. \r
	382	@retval EFI_SECURITY_VIOLATION The Credentials.Data supplied by the caller is NULL,\r
	383	or the AuthorityCertificate supplied by the caller was \r
	384	invalid (could not be parsed), \r
	385	or Platform-specific authorization failed, etc. \r
	386	@retval EFI_DEVICE_ERROR An unexpected internal error occurred while attempting to retrieve\r
	387	the public key algorithm of the manifest's signer's certificate,\r
	388	or An unexpected internal error occurred in a cryptographic software module. \r
	389	**/ \r
	390	typedef\r
	391	EFI_STATUS\r
	392	(EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL)(\r
	393	IN BIS_APPLICATION_HANDLE AppHandle, \r
	394	IN EFI_BIS_DATA *Credentials, \r
	395	IN EFI_BIS_DATA *DataObject, \r
	396	IN EFI_BIS_DATA *SectionName, \r
	397	IN EFI_BIS_DATA *AuthorityCertificate, \r
	398	OUT BOOLEAN *IsVerified \r
	399	);\r
	400	\r
	401	/** \r
	402	Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength\r
	403	combinations that the platform supports. \r
	404	\r
	405	@param AppHandle An opaque handle that identifies the caller's instance of initialization\r
	406	of the BIS service. \r
	407	@param SignatureInfo The function writes an allocated EFI_BIS_DATA* containing the array\r
	408	of EFI_BIS_SIGNATURE_INFO structures representing the supported \r
	409	digital certificate identifier, algorithm, and key length combinations.\r
	410	The caller must eventually free the memory allocated by this function using the function Free().\r
	411	\r
	412	@retval EFI_SUCCESS The function completed successfully. \r
	413	@retval EFI_NO_MAPPING The AppHandle parameter is not or is no longer a valid \r
	414	application instance handle associated with the EFI_BIS protocol. \r
	415	@retval EFI_OUT_OF_RESOURCES The function failed due to lack of memory or other resources. \r
	416	@retval EFI_INVALID_PARAMETER The SignatureInfo parameter supplied by the caller is NULL\r
	417	or an invalid memory reference.\r
	418	@retval EFI_DEVICE_ERROR An unexpected internal error occurred in a\r
	419	cryptographic software module, or\r
	420	The function encountered an unexpected internal consistency check\r
	421	failure (possible corruption of stored Boot Object Authorization Certificate).\r
	422	\r
	423	**/\r
	424	typedef\r
	425	EFI_STATUS\r
	426	(EFIAPI *EFI_BIS_GET_SIGNATURE_INFO)(\r
	427	IN BIS_APPLICATION_HANDLE AppHandle, \r
	428	OUT EFI_BIS_DATA **SignatureInfo \r
	429	);\r
	430	\r
	431	///\r
	432	/// The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital\r
	433	/// certificate for the purpose of an integrity and authorization check.\r
	434	///\r
	435	struct _EFI_BIS_PROTOCOL {\r
	436	EFI_BIS_INITIALIZE Initialize;\r
	437	EFI_BIS_SHUTDOWN Shutdown;\r
	438	EFI_BIS_FREE Free;\r
	439	EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE GetBootObjectAuthorizationCertificate;\r
	440	EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG GetBootObjectAuthorizationCheckFlag;\r
	441	EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN GetBootObjectAuthorizationUpdateToken;\r
	442	EFI_BIS_GET_SIGNATURE_INFO GetSignatureInfo;\r
	443	EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION UpdateBootObjectAuthorization;\r
	444	EFI_BIS_VERIFY_BOOT_OBJECT VerifyBootObject;\r
	445	EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL VerifyObjectWithCredential;\r
	446	};\r
	447	\r
	448	extern EFI_GUID gEfiBisProtocolGuid;\r
	449	extern EFI_GUID gBootObjectAuthorizationParmsetGuid;\r
	450	\r
	451	#endif\r