Data Structures
struct	EFI_BIS_DATA

struct	EFI_BIS_VERSION

struct	EFI_BIS_SIGNATURE_INFO

struct	_EFI_BIS_PROTOCOL

Macros
#define	EFI_BIS_PROTOCOL_GUID

#define	BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID

#define	BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1

#define	BIS_VERSION_1 1

#define	BIS_ALG_DSA (41)

#define	BIS_ALG_RSA_MD5 (42)

#define	BIS_CERT_ID_DSA BIS_ALG_DSA

#define	BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5

#define	BIS_CERT_ID_MASK (0xFF7F7FFF)

#define	BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))

#define	BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)

#define	BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID

Typedefs
typedef struct _EFI_BIS_PROTOCOL	EFI_BIS_PROTOCOL

typedef VOID *	BIS_APPLICATION_HANDLE

typedef UINT16	BIS_ALG_ID

typedef UINT32	BIS_CERT_ID

typedef EFI_STATUS(EFIAPI *	EFI_BIS_INITIALIZE )(IN EFI_BIS_PROTOCOL This, OUT BIS_APPLICATION_HANDLE AppHandle, IN OUT EFI_BIS_VERSION InterfaceVersion, IN EFI_BIS_DATA TargetAddress)

typedef EFI_STATUS(EFIAPI *	EFI_BIS_FREE )(IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA *ToFree)

typedef EFI_STATUS(EFIAPI *	EFI_BIS_SHUTDOWN )(IN BIS_APPLICATION_HANDLE AppHandle)

typedef EFI_STATUS(EFIAPI *	EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE )(IN BIS_APPLICATION_HANDLE AppHandle, OUT EFI_BIS_DATA **Certificate)

typedef EFI_STATUS(EFIAPI *	EFI_BIS_VERIFY_BOOT_OBJECT )(IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA Credentials, IN EFI_BIS_DATA DataObject, OUT BOOLEAN *IsVerified)

typedef EFI_STATUS(EFIAPI *	EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG )(IN BIS_APPLICATION_HANDLE AppHandle, OUT BOOLEAN *CheckIsRequired)

typedef EFI_STATUS(EFIAPI *	EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN )(IN BIS_APPLICATION_HANDLE AppHandle, OUT EFI_BIS_DATA **UpdateToken)

typedef EFI_STATUS(EFIAPI *	EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION )(IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA RequestCredential, OUT EFI_BIS_DATA *NewUpdateToken)

typedef EFI_STATUS(EFIAPI *	EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL )(IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA Credentials, IN EFI_BIS_DATA DataObject, IN EFI_BIS_DATA SectionName, IN EFI_BIS_DATA AuthorityCertificate, OUT BOOLEAN *IsVerified)

typedef EFI_STATUS(EFIAPI *	EFI_BIS_GET_SIGNATURE_INFO )(IN BIS_APPLICATION_HANDLE AppHandle, OUT EFI_BIS_DATA **SignatureInfo)

Variables
EFI_GUID	gEfiBisProtocolGuid

EFI_GUID	gBootObjectAuthorizationParmsetGuid

Detailed Description

The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital certificate for the purpose of an integrity and authorization check.

Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Revision Reference:: This Protocol is introduced in EFI Specification 1.10.

Macro Definition Documentation

#define BIS_ALG_DSA (41)

values for EFI_BIS_SIGNATURE_INFO.AlgorithmID. The exact numeric values come from the "Common Data Security Architecture (CDSA) Specification".

#define BIS_ALG_RSA_MD5 (42)

#define BIS_CERT_ID_DSA BIS_ALG_DSA

values for EFI_BIS_SIGNATURE_INFO.CertificateId.

#define BIS_CERT_ID_MASK (0xFF7F7FFF)

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_RSA_MD5 BIS_ALG_RSA_MD5

#define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1

#define BIS_GET_SIGINFO_ARRAY ( BisDataPtr ) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)

BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO* from a given EFI_BIS_DATA*.

#define BIS_GET_SIGINFO_COUNT ( BisDataPtr ) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))

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_VERSION_1 1

#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID

Value:

{ \
    0xedd35e31, 0x7b9, 0x11d2, { 0x83,0xa3,0x0,0xa0,0xc9,0x1f,0xad,0xcf } \
  }

#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID

Support an old name for backward compatibility.

#define EFI_BIS_PROTOCOL_GUID

Value:

{ \
    0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \
  }

Typedef Documentation

typedef UINT16 BIS_ALG_ID

typedef VOID* BIS_APPLICATION_HANDLE

typedef UINT32 BIS_CERT_ID

typedef EFI_STATUS(EFIAPI * EFI_BIS_FREE)(IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA *ToFree)

Frees memory structures allocated and returned by other functions in the EFI_BIS protocol.

Parameters

AppHandle	An opaque handle that identifies the caller's instance of initialization of the BIS service.
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.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NO_MAPPING	The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
EFI_INVALID_PARAMETER	The ToFree parameter is not or is no longer a memory resource associated with this AppHandle.

typedef EFI_STATUS(EFIAPI * EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE)(IN BIS_APPLICATION_HANDLE AppHandle, OUT EFI_BIS_DATA **Certificate)

Retrieves the certificate that has been configured as the identity of the organization designated as the source of authorization for signatures of boot objects.

Parameters

AppHandle	An opaque handle that identifies the caller's instance of initialization of the BIS service.
Certificate	The function writes an allocated EFI_BIS_DATA* containing the Boot Object Authorization Certificate object. The caller must eventually free the memory allocated by this function using the function Free().

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NO_MAPPING	The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.
EFI_NOT_FOUND	There is no Boot Object Authorization Certificate currently installed.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
EFI_INVALID_PARAMETER	The Certificate parameter supplied by the caller is NULL or an invalid memory reference.

typedef EFI_STATUS(EFIAPI * EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG)(IN BIS_APPLICATION_HANDLE AppHandle, OUT BOOLEAN *CheckIsRequired)

Retrieves the current status of the Boot Authorization Check Flag.

Parameters

AppHandle	An opaque handle that identifies the caller's instance of initialization of the BIS service.
CheckIsRequired	The function writes the value TRUE if a Boot Authorization Check is currently required on this platform, otherwise the function writes FALSE.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NO_MAPPING	The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
EFI_INVALID_PARAMETER	The CheckIsRequired parameter supplied by the caller is NULL or an invalid memory reference.

typedef EFI_STATUS(EFIAPI * EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN)(IN BIS_APPLICATION_HANDLE AppHandle, OUT EFI_BIS_DATA **UpdateToken)

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

Parameters

AppHandle	An opaque handle that identifies the caller's instance of initialization of the BIS service.
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().

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NO_MAPPING	The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
EFI_INVALID_PARAMETER	The UpdateToken parameter supplied by the caller is NULL or an invalid memory reference.
EFI_DEVICE_ERROR	An unexpected internal error occurred.

typedef EFI_STATUS(EFIAPI * EFI_BIS_GET_SIGNATURE_INFO)(IN BIS_APPLICATION_HANDLE AppHandle, OUT EFI_BIS_DATA **SignatureInfo)

Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength combinations that the platform supports.

Parameters

AppHandle	An opaque handle that identifies the caller's instance of initialization of the BIS service.
SignatureInfo	The function writes an allocated EFI_BIS_DATA* containing the array of EFI_BIS_SIGNATURE_INFO structures representing the supported digital certificate identifier, algorithm, and key length combinations. The caller must eventually free the memory allocated by this function using the function Free().

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NO_MAPPING	The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
EFI_INVALID_PARAMETER	The SignatureInfo parameter supplied by the caller is NULL or an invalid memory reference.
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_INITIALIZE)(IN EFI_BIS_PROTOCOL *This, OUT BIS_APPLICATION_HANDLE *AppHandle, IN OUT EFI_BIS_VERSION *InterfaceVersion, IN EFI_BIS_DATA *TargetAddress)

Initializes the BIS service, checking that it is compatible with the version requested by the caller. After this call, other BIS functions may be invoked.

Parameters

This	A pointer to the EFI_BIS_PROTOCOL object.
AppHandle	The function writes the new BIS_APPLICATION_HANDLE if successful, otherwise it writes NULL. The caller must eventually destroy this handle by calling Shutdown().
InterfaceVersion	On input, the caller supplies the major version number of the interface version desired. On output, both the major and minor version numbers are updated with the major and minor version numbers of the interface. This update is done whether or not the initialization was successful.
TargetAddress	Indicates a network or device address of the BIS platform to connect to.

Return values

EFI_SUCCESS	The function completed successfully.
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.
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.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
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.
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 struct _EFI_BIS_PROTOCOL EFI_BIS_PROTOCOL

typedef EFI_STATUS(EFIAPI * EFI_BIS_SHUTDOWN)(IN BIS_APPLICATION_HANDLE AppHandle)

Shuts down an application's instance of the BIS service, invalidating the application handle. After this call, other BIS functions may no longer be invoked using the application handle value.

Parameters

AppHandle An opaque handle that identifies the caller's instance of initialization of the BIS service.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NO_MAPPING	The AppHandle parameter is not, or is no longer, a valid application instance handle associated with the EFI_BIS protocol.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
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_UPDATE_BOOT_OBJECT_AUTHORIZATION)(IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA *RequestCredential, OUT EFI_BIS_DATA **NewUpdateToken)

Updates one of the configurable parameters of the Boot Object Authorization set.

Parameters

AppHandle	An opaque handle that identifies the caller's instance of initialization of the BIS service.
RequestCredential	This is a Signed Manifest with embedded attributes that carry the details of the requested update.
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().

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NO_MAPPING	The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
EFI_INVALID_PARAMETER	One or more parameters are invalid.
EFI_SECURITY_VIOLATION	The signed manifest supplied as the RequestCredential parameter was invalid (could not be parsed) or Platform-specific authorization failed, etc.
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_VERIFY_BOOT_OBJECT)(IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA *Credentials, IN EFI_BIS_DATA *DataObject, OUT BOOLEAN *IsVerified)

Verifies the integrity and authorization of the indicated data object according to the indicated credentials.

Parameters

AppHandle	An opaque handle that identifies the caller's instance of initialization of the BIS service.
Credentials	A Signed Manifest containing verification information for the indicated data object.
DataObject	An in-memory copy of the raw data object to be verified.
IsVerified	The function writes TRUE if the verification succeeded, otherwise FALSE.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NO_MAPPING	The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
EFI_INVALID_PARAMETER	One or more parameters are invalid.
EFI_SECURITY_VIOLATION	The signed manifest supplied as the Credentials parameter was invalid (could not be parsed) or Platform-specific authorization failed, etc.
EFI_DEVICE_ERROR	An unexpected internal error occurred.

typedef EFI_STATUS(EFIAPI * EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL)(IN BIS_APPLICATION_HANDLE AppHandle, IN EFI_BIS_DATA *Credentials, IN EFI_BIS_DATA *DataObject, IN EFI_BIS_DATA *SectionName, IN EFI_BIS_DATA *AuthorityCertificate, OUT BOOLEAN *IsVerified)

Verifies the integrity and authorization of the indicated data object according to the indicated credentials and authority certificate.

Parameters

AppHandle	An opaque handle that identifies the caller's instance of initialization of the BIS service.
Credentials	A Signed Manifest containing verification information for the indicated data object.
DataObject	An in-memory copy of the raw data object to be verified.
SectionName	An ASCII string giving the section name in the manifest holding the verification information (in other words, hash value) that corresponds to DataObject.
AuthorityCertificate	A digital certificate whose public key must match the signer's public key which is found in the credentials.
IsVerified	The function writes TRUE if the verification was successful. Otherwise, the function writes FALSE.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NO_MAPPING	The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.
EFI_OUT_OF_RESOURCES	The function failed due to lack of memory or other resources.
EFI_INVALID_PARAMETER	One or more parameters are invalid.
EFI_SECURITY_VIOLATION	The Credentials.Data supplied by the caller is NULL, or the AuthorityCertificate supplied by the caller was invalid (could not be parsed), or Platform-specific authorization failed, etc.
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.

Variable Documentation

EFI_GUID gBootObjectAuthorizationParmsetGuid

EFI_GUID gEfiBisProtocolGuid

Data Structures

Macros

Typedefs

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Variable Documentation