Bis.h File Reference

Go to the source code of this file.

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.

Definition in file Bis.h.

Macro Definition Documentation

BIS_ALG_DSA

#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".

Definition at line 80 of file Bis.h.

BIS_ALG_RSA_MD5

#define BIS_ALG_RSA_MD5   (42)

Definition at line 81 of file Bis.h.

BIS_CERT_ID_DSA

#define BIS_CERT_ID_DSA   BIS_ALG_DSA

values for EFI_BIS_SIGNATURE_INFO.CertificateId.

Definition at line 85 of file Bis.h.

BIS_CERT_ID_MASK

#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.

Definition at line 93 of file Bis.h.

BIS_CERT_ID_RSA_MD5

#define BIS_CERT_ID_RSA_MD5   BIS_ALG_RSA_MD5

Definition at line 86 of file Bis.h.

BIS_CURRENT_VERSION_MAJOR

#define BIS_CURRENT_VERSION_MAJOR   BIS_VERSION_1

Definition at line 63 of file Bis.h.

BIS_GET_SIGINFO_ARRAY

#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*.

Definition at line 108 of file Bis.h.

BIS_GET_SIGINFO_COUNT

#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*.

Definition at line 102 of file Bis.h.

BIS_VERSION_1

#define BIS_VERSION_1   1

Definition at line 64 of file Bis.h.

BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID

#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID

Value:

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

Definition at line 27 of file Bis.h.

BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE

#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE    BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID

Support an old name for backward compatibility.

Definition at line 113 of file Bis.h.

EFI_BIS_PROTOCOL_GUID

#define EFI_BIS_PROTOCOL_GUID

Value:

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

Definition at line 16 of file Bis.h.

Typedef Documentation

BIS_ALG_ID

typedef UINT16 BIS_ALG_ID

Definition at line 38 of file Bis.h.

BIS_APPLICATION_HANDLE

typedef VOID* BIS_APPLICATION_HANDLE

Definition at line 37 of file Bis.h.

BIS_CERT_ID

typedef UINT32 BIS_CERT_ID

Definition at line 39 of file Bis.h.

EFI_BIS_FREE

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.

Definition at line 183 of file Bis.h.

EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE

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.

Definition at line 230 of file Bis.h.

EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG

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.

Definition at line 285 of file Bis.h.

EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN

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.

Definition at line 312 of file Bis.h.

EFI_BIS_GET_SIGNATURE_INFO

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).

Definition at line 416 of file Bis.h.

EFI_BIS_INITIALIZE

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.

Definition at line 158 of file Bis.h.

EFI_BIS_PROTOCOL

typedef struct _EFI_BIS_PROTOCOL EFI_BIS_PROTOCOL

Definition at line 32 of file Bis.h.

EFI_BIS_SHUTDOWN

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.

Definition at line 205 of file Bis.h.

EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION

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.

Definition at line 344 of file Bis.h.

EFI_BIS_VERIFY_BOOT_OBJECT

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.

Definition at line 259 of file Bis.h.

EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL

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.

Definition at line 382 of file Bis.h.