#include <Library/AuthVariableLib.h>
#include <Library/BaseLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/DebugLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/BaseCryptLib.h>
#include <Library/PlatformSecureLib.h>
#include <Guid/AuthenticatedVariableFormat.h>
#include <Guid/ImageAuthentication.h>

Data Structures
struct	EFI_SIGNATURE_ITEM

struct	AUTH_CERT_DB_DATA

Macros
#define	TWO_BYTE_ENCODE 0x82

#define	EFI_CERT_DB_NAME L"certdb"

#define	EFI_CERT_DB_VOLATILE_NAME L"certdbv"

Enumerations
enum	AUTHVAR_TYPE { AuthVarTypePk , AuthVarTypeKek , AuthVarTypePriv , AuthVarTypePayload }

Functions
EFI_STATUS	VerifyTimeBasedPayloadAndUpdate (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, IN VOID Data, IN UINTN DataSize, IN UINT32 Attributes, IN AUTHVAR_TYPE AuthVarType, OUT BOOLEAN VarDel)

EFI_STATUS	DeleteCertsFromDb (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, IN UINT32 Attributes)

EFI_STATUS	CleanCertsFromDb (VOID)

EFI_STATUS	FilterSignatureList (IN VOID Data, IN UINTN DataSize, IN OUT VOID NewData, IN OUT UINTN *NewDataSize)

EFI_STATUS	ProcessVarWithPk (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, IN VOID *Data, IN UINTN DataSize, IN UINT32 Attributes OPTIONAL, IN BOOLEAN IsPk)

EFI_STATUS	ProcessVarWithKek (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, IN VOID *Data, IN UINTN DataSize, IN UINT32 Attributes OPTIONAL)

EFI_STATUS	ProcessVariable (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, IN VOID *Data, IN UINTN DataSize, IN UINT32 Attributes)

EFI_STATUS	AuthServiceInternalFindVariable (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, OUT VOID *Data, OUT UINTN DataSize)

EFI_STATUS	AuthServiceInternalUpdateVariable (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, IN VOID *Data, IN UINTN DataSize, IN UINT32 Attributes)

EFI_STATUS	AuthServiceInternalUpdateVariableWithTimeStamp (IN CHAR16 VariableName, IN EFI_GUID VendorGuid, IN VOID Data, IN UINTN DataSize, IN UINT32 Attributes, IN EFI_TIME TimeStamp)

Variables
UINT8 *	mCertDbStore

UINT32	mMaxCertDbSize

UINT32	mPlatformMode

UINT8	mVendorKeyState

VOID *	mHashSha256Ctx

VOID *	mHashSha384Ctx

VOID *	mHashSha512Ctx

AUTH_VAR_LIB_CONTEXT_IN *	mAuthVarLibContextIn

Detailed Description

The internal header file includes the common header files, defines internal structure and functions used by AuthService module.

Caution: This module requires additional review when modified. This driver will have external input - variable data. It may be input in SMM mode. This external input must be validated carefully to avoid security issue like buffer overflow, integer overflow. Variable attribute should also be checked to avoid authentication bypass. The whole SMM authentication variable design relies on the integrity of flash part and SMM. which is assumed to be protected by platform. All variable code and metadata in flash/SMM Memory may not be modified without authorization. If platform fails to protect these resources, the authentication service provided in this driver will be broken, and the behavior is undefined.

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

Definition in file AuthServiceInternal.h.

Macro Definition Documentation

◆ EFI_CERT_DB_NAME

#define EFI_CERT_DB_NAME L"certdb"

"certdb" variable stores the signer's certificates for non PK/KEK/DB/DBX variables with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS|EFI_VARIABLE_NON_VOLATILE set. "certdbv" variable stores the signer's certificates for non PK/KEK/DB/DBX variables with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set

GUID: gEfiCertDbGuid

We need maintain atomicity.

Definition at line 76 of file AuthServiceInternal.h.

◆ EFI_CERT_DB_VOLATILE_NAME

#define EFI_CERT_DB_VOLATILE_NAME L"certdbv"

Definition at line 77 of file AuthServiceInternal.h.

◆ TWO_BYTE_ENCODE

#define TWO_BYTE_ENCODE 0x82

Definition at line 34 of file AuthServiceInternal.h.

Enumeration Type Documentation

◆ AUTHVAR_TYPE

enum AUTHVAR_TYPE

Definition at line 48 of file AuthServiceInternal.h.

Function Documentation

◆ AuthServiceInternalFindVariable()

EFI_STATUS AuthServiceInternalFindVariable	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		OUT VOID **	Data,
		OUT UINTN *	DataSize
	)

Finds variable in storage blocks of volatile and non-volatile storage areas.

This code finds variable in storage blocks of volatile and non-volatile storage areas. If VariableName is an empty string, then we just return the first qualified variable without comparing VariableName and VendorGuid.

Parameters

[in]	VariableName	Name of the variable to be found.
[in]	VendorGuid	Variable vendor GUID to be found.
[out]	Data	Pointer to data address.
[out]	DataSize	Pointer to data size.

Return values

EFI_INVALID_PARAMETER	If VariableName is not an empty string, while VendorGuid is NULL.
EFI_SUCCESS	Variable successfully found.
EFI_NOT_FOUND	Variable not found

Definition at line 191 of file AuthService.c.

◆ AuthServiceInternalUpdateVariable()

EFI_STATUS AuthServiceInternalUpdateVariable	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		IN VOID *	Data,
		IN UINTN	DataSize,
		IN UINT32	Attributes
	)

Update the variable region with Variable information.

Parameters

[in]	VariableName	Name of variable.
[in]	VendorGuid	Guid of variable.
[in]	Data	Data pointer.
[in]	DataSize	Size of Data.
[in]	Attributes	Attribute value of the variable.

Return values

EFI_SUCCESS	The update operation is success.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_WRITE_PROTECTED	Variable is write-protected.
EFI_OUT_OF_RESOURCES	There is not enough resource.

Definition at line 228 of file AuthService.c.

◆ AuthServiceInternalUpdateVariableWithTimeStamp()

EFI_STATUS AuthServiceInternalUpdateVariableWithTimeStamp	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		IN VOID *	Data,
		IN UINTN	DataSize,
		IN UINT32	Attributes,
		IN EFI_TIME *	TimeStamp
	)

Update the variable region with Variable information.

Parameters

[in]	VariableName	Name of variable.
[in]	VendorGuid	Guid of variable.
[in]	Data	Data pointer.
[in]	DataSize	Size of Data.
[in]	Attributes	Attribute value of the variable.
[in]	TimeStamp	Value of associated TimeStamp.

Return values

EFI_SUCCESS	The update operation is success.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_WRITE_PROTECTED	Variable is write-protected.
EFI_OUT_OF_RESOURCES	There is not enough resource.

Definition at line 267 of file AuthService.c.

◆ CleanCertsFromDb()

EFI_STATUS CleanCertsFromDb ( VOID )

Clean up signer's certificates for common authenticated variable by corresponding VariableName and VendorGuid from "certdb". System may break down during Timebased Variable update & certdb update, make them inconsistent, this function is called in AuthVariable Init to ensure consistency

Return values

EFI_NOT_FOUND	Fail to find matching certs.
EFI_SUCCESS	Find matching certs and output parameters.

Clean up signer's certificates for common authenticated variable by corresponding VariableName and VendorGuid from "certdb". System may break down during Timebased Variable update & certdb update, make them inconsistent, this function is called in AuthVariable Init to ensure consistency.

Return values

EFI_NOT_FOUND	Fail to find variable "certdb".
EFI_OUT_OF_RESOURCES	The operation is failed due to lack of resources.
EFI_SUCCESS	The operation is completed successfully.

Definition at line 1825 of file AuthService.c.

◆ DeleteCertsFromDb()

EFI_STATUS DeleteCertsFromDb	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		IN UINT32	Attributes
	)

Delete matching signer's certificates when deleting common authenticated variable by corresponding VariableName and VendorGuid from "certdb" or "certdbv" according to authenticated variable attributes.

Parameters

[in]	VariableName	Name of authenticated Variable.
[in]	VendorGuid	Vendor GUID of authenticated Variable.
[in]	Attributes	Attributes of authenticated variable.

Return values

EFI_INVALID_PARAMETER	Any input parameter is invalid.
EFI_NOT_FOUND	Fail to find "certdb"/"certdbv" or matching certs.
EFI_OUT_OF_RESOURCES	The operation is failed due to lack of resources.
EFI_SUCCESS	The operation is completed successfully.

Definition at line 1518 of file AuthService.c.

◆ FilterSignatureList()

EFI_STATUS FilterSignatureList	(	IN VOID *	Data,
		IN UINTN	DataSize,
		IN OUT VOID *	NewData,
		IN OUT UINTN *	NewDataSize
	)

Filter out the duplicated EFI_SIGNATURE_DATA from the new data by comparing to the original data.

Parameters

[in]	Data	Pointer to original EFI_SIGNATURE_LIST.
[in]	DataSize	Size of Data buffer.
[in,out]	NewData	Pointer to new EFI_SIGNATURE_LIST.
[in,out]	NewDataSize	Size of NewData buffer.

Definition at line 1058 of file AuthService.c.

◆ ProcessVariable()

EFI_STATUS ProcessVariable	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		IN VOID *	Data,
		IN UINTN	DataSize,
		IN UINT32	Attributes
	)

Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set

Caution: This function may receive untrusted input. This function may be invoked in SMM mode, and datasize and data are external input. This function will do basic validation, before parse the data. This function will parse the authentication carefully to avoid security issues, like buffer overflow, integer overflow. This function will check attribute carefully to avoid authentication bypass.

Parameters

[in]	VariableName	Name of the variable.
[in]	VendorGuid	Variable vendor GUID.
[in]	Data	Data pointer.
[in]	DataSize	Size of Data.
[in]	Attributes	Attribute value of the variable.

Returns: EFI_INVALID_PARAMETER Invalid parameter.; EFI_WRITE_PROTECTED Variable is write-protected and needs authentication with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS or EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set.; EFI_OUT_OF_RESOURCES The Database to save the public key is full.; EFI_SECURITY_VIOLATION The variable is with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set, but the AuthInfo does NOT pass the validation check carried out by the firmware.; EFI_SUCCESS Variable is not write-protected or pass validation successfully.

Definition at line 965 of file AuthService.c.

◆ ProcessVarWithKek()

EFI_STATUS ProcessVarWithKek	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		IN VOID *	Data,
		IN UINTN	DataSize,
		IN UINT32 Attributes	OPTIONAL
	)

Process variable with key exchange key for verification.

Caution: This function may receive untrusted input. This function may be invoked in SMM mode, and datasize and data are external input. This function will do basic validation, before parse the data. This function will parse the authentication carefully to avoid security issues, like buffer overflow, integer overflow. This function will check attribute carefully to avoid authentication bypass.

Parameters

[in]	VariableName	Name of Variable to be found.
[in]	VendorGuid	Variable vendor GUID.
[in]	Data	Data pointer.
[in]	DataSize	Size of Data found. If size is less than the data, this value contains the required size.
[in]	Attributes	Attribute value of the variable.

Returns: EFI_INVALID_PARAMETER Invalid parameter.; EFI_SECURITY_VIOLATION The variable does NOT pass the validation check carried out by the firmware.; EFI_SUCCESS Variable pass validation successfully.

Definition at line 820 of file AuthService.c.

◆ ProcessVarWithPk()

EFI_STATUS ProcessVarWithPk	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		IN VOID *	Data,
		IN UINTN	DataSize,
		IN UINT32 Attributes	OPTIONAL,
		IN BOOLEAN	IsPk
	)

Process variable with platform key for verification.

Caution: This function may receive untrusted input. This function may be invoked in SMM mode, and datasize and data are external input. This function will do basic validation, before parse the data. This function will parse the authentication carefully to avoid security issues, like buffer overflow, integer overflow. This function will check attribute carefully to avoid authentication bypass.

Parameters

[in]	VariableName	Name of Variable to be found.
[in]	VendorGuid	Variable vendor GUID.
[in]	Data	Data pointer.
[in]	DataSize	Size of Data found. If size is less than the data, this value contains the required size.
[in]	Attributes	Attribute value of the variable
[in]	IsPk	Indicate whether it is to process pk.

Returns: EFI_INVALID_PARAMETER Invalid parameter.; EFI_SECURITY_VIOLATION The variable does NOT pass the validation. check carried out by the firmware.; EFI_SUCCESS Variable passed validation successfully.

Definition at line 691 of file AuthService.c.

◆ VerifyTimeBasedPayloadAndUpdate()

EFI_STATUS VerifyTimeBasedPayloadAndUpdate	(	IN CHAR16 *	VariableName,
		IN EFI_GUID *	VendorGuid,
		IN VOID *	Data,
		IN UINTN	DataSize,
		IN UINT32	Attributes,
		IN AUTHVAR_TYPE	AuthVarType,
		OUT BOOLEAN *	VarDel
	)

Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set

Caution: This function may receive untrusted input. This function may be invoked in SMM mode, and datasize and data are external input. This function will do basic validation, before parse the data. This function will parse the authentication carefully to avoid security issues, like buffer overflow, integer overflow.

Parameters

[in]	VariableName	Name of Variable to be found.
[in]	VendorGuid	Variable vendor GUID.
[in]	Data	Data pointer.
[in]	DataSize	Size of Data found. If size is less than the data, this value contains the required size.
[in]	Attributes	Attribute value of the variable.
[in]	AuthVarType	Verify against PK, KEK database, private database or certificate in data payload.
[out]	VarDel	Delete the variable or not.

Return values

EFI_INVALID_PARAMETER	Invalid parameter.
EFI_SECURITY_VIOLATION	The variable does NOT pass the validation check carried out by the firmware.
EFI_OUT_OF_RESOURCES	Failed to process variable due to lack of resources.
EFI_SUCCESS	Variable pass validation successfully.

Definition at line 2462 of file AuthService.c.

Variable Documentation

◆ mAuthVarLibContextIn

AUTH_VAR_LIB_CONTEXT_IN* mAuthVarLibContextIn

extern

Definition at line 98 of file AuthVariableLib.c.

◆ mCertDbStore

UINT8* mCertDbStore

extern

Global database array for scratch

Definition at line 24 of file AuthVariableLib.c.

◆ mHashSha256Ctx

VOID* mHashSha256Ctx

extern

Definition at line 34 of file AuthVariableLib.c.

◆ mHashSha384Ctx

VOID* mHashSha384Ctx

extern

Definition at line 35 of file AuthVariableLib.c.

◆ mHashSha512Ctx

VOID* mHashSha512Ctx

extern

Definition at line 36 of file AuthVariableLib.c.

◆ mMaxCertDbSize

UINT32 mMaxCertDbSize

extern

Definition at line 25 of file AuthVariableLib.c.

◆ mPlatformMode

UINT32 mPlatformMode

extern

Definition at line 26 of file AuthVariableLib.c.

◆ mVendorKeyState

UINT8 mVendorKeyState

extern

Definition at line 27 of file AuthVariableLib.c.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ EFI_CERT_DB_NAME

◆ EFI_CERT_DB_VOLATILE_NAME

◆ TWO_BYTE_ENCODE

Enumeration Type Documentation

◆ AUTHVAR_TYPE

Function Documentation

◆ AuthServiceInternalFindVariable()

◆ AuthServiceInternalUpdateVariable()

◆ AuthServiceInternalUpdateVariableWithTimeStamp()

◆ CleanCertsFromDb()

◆ DeleteCertsFromDb()

◆ FilterSignatureList()

◆ ProcessVariable()

◆ ProcessVarWithKek()

◆ ProcessVarWithPk()

◆ VerifyTimeBasedPayloadAndUpdate()

Variable Documentation

◆ mAuthVarLibContextIn

◆ mCertDbStore

◆ mHashSha256Ctx

◆ mHashSha384Ctx

◆ mHashSha512Ctx

◆ mMaxCertDbSize

◆ mPlatformMode

◆ mVendorKeyState