SecurityPkg/Library/AuthVariableLib/AuthServiceInternal.h File Reference


Data Structures

struct  EFI_SIGNATURE_ITEM
struct  AUTHVAR_KEY_DB_DATA
struct  AUTH_CERT_DB_DATA

Defines

#define AUTHVAR_KEYDB_NAME   L"AuthVarKeyDatabase"
#define EFI_CERT_TYPE_RSA2048_SHA256_SIZE   256
#define EFI_CERT_TYPE_RSA2048_SIZE   256
#define EFI_CERT_DB_NAME   L"certdb"

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)
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, IN BOOLEAN IsPk)
EFI_STATUS ProcessVarWithKek (IN CHAR16 *VariableName, IN EFI_GUID *VendorGuid, IN VOID *Data, IN UINTN DataSize, IN UINT32 Attributes)
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 AuthServiceInternalUpdateVariableWithMonotonicCount (IN CHAR16 *VariableName, IN EFI_GUID *VendorGuid, IN VOID *Data, IN UINTN DataSize, IN UINT32 Attributes, IN UINT32 KeyIndex, IN UINT64 MonotonicCount)
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 * mPubKeyStore
UINT32 mPubKeyNumber
UINT32 mMaxKeyNumber
UINT32 mMaxKeyDbSize
UINT8 * mCertDbStore
UINT32 mMaxCertDbSize
UINT32 mPlatformMode
UINT8 mVendorKeyState
VOID * mHashCtx
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 - 2015, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at http://opensource.org/licenses/bsd-license.php

THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.


Define Documentation

#define AUTHVAR_KEYDB_NAME   L"AuthVarKeyDatabase"

"AuthVarKeyDatabase" variable for the Public Key store of variables with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS set.

GUID: gEfiAuthenticatedVariableGuid

We need maintain atomicity.

Format: +----------------------------+ | AUTHVAR_KEY_DB_DATA | <-- First AuthVarKey +----------------------------+ | ...... | +----------------------------+ | AUTHVAR_KEY_DB_DATA | <-- Last AuthKey +----------------------------+

Referenced by AddPubKeyInStore(), and GetAvailableKeyIndex().

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

GUID: gEfiCertDbGuid

We need maintain atomicity.

Format: +----------------------------+ | UINT32 | <-- CertDbListSize, including this UINT32 +----------------------------+ | AUTH_CERT_DB_DATA | <-- First CERT +----------------------------+ | ........ | +----------------------------+ | AUTH_CERT_DB_DATA | <-- Last CERT +----------------------------+

Referenced by CleanCertsFromDb(), DeleteCertsFromDb(), GetCertsFromDb(), and InsertCertsToDb().

#define EFI_CERT_TYPE_RSA2048_SHA256_SIZE   256

#define EFI_CERT_TYPE_RSA2048_SIZE   256


Enumeration Type Documentation

Enumerator:
AuthVarTypePk 
AuthVarTypeKek 
AuthVarTypePriv 
AuthVarTypePayload 


Function Documentation

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

References EFI_STATUS(), and mAuthVarLibContextIn.

Referenced by AuthServiceInternalUpdateVariableWithTimeStamp(), AuthVariableLibInitialize(), CleanCertsFromDb(), DeleteCertsFromDb(), GetAvailableKeyIndex(), GetCertsFromDb(), InCustomMode(), InsertCertsToDb(), UpdatePlatformMode(), and VerifyTimeBasedPayload().

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.

References mAuthVarLibContextIn.

Referenced by AddPubKeyInStore(), AuthVariableLibInitialize(), DeleteCertsFromDb(), InsertCertsToDb(), ProcessVariable(), UpdatePlatformMode(), and VendorKeyIsModified().

EFI_STATUS AuthServiceInternalUpdateVariableWithMonotonicCount ( IN CHAR16 *  VariableName,
IN EFI_GUID *  VendorGuid,
IN VOID *  Data,
IN UINTN  DataSize,
IN UINT32  Attributes,
IN UINT32  KeyIndex,
IN UINT64  MonotonicCount 
)

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] KeyIndex Index of associated public key.
[in] MonotonicCount Value of associated monotonic count.
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.

References mAuthVarLibContextIn.

Referenced by ProcessVariable().

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.

References AuthServiceInternalFindVariable(), EFI_STATUS(), FilterSignatureList(), mAuthVarLibContextIn, and UINTN().

Referenced by ProcessVarWithKek(), ProcessVarWithPk(), and VerifyTimeBasedPayloadAndUpdate().

EFI_STATUS CleanCertsFromDb ( VOID   ) 

Clean up signer's certificates for common authenticated variable by corresponding VariableName and VendorGuid from "certdb". Sytem 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.

References AuthServiceInternalFindVariable(), BOOLEAN(), AUTH_CERT_DB_DATA::CertNodeSize, DeleteCertsFromDb(), EFI_CERT_DB_NAME, EFI_STATUS(), gEfiCertDbGuid, AUTH_CERT_DB_DATA::NameSize, TRUE, UINTN(), and AUTH_CERT_DB_DATA::VendorGuid.

Referenced by AuthVariableLibInitialize().

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

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

Parameters:
[in] VariableName Name of authenticated Variable.
[in] VendorGuid Vendor GUID of authenticated Variable.
Return values:
EFI_INVALID_PARAMETER Any input parameter is invalid.
EFI_NOT_FOUND Fail to find "certdb" or matching certs.
EFI_OUT_OF_RESOURCES The operation is failed due to lack of resources.
EFI_SUCCESS The operation is completed successfully.

References AuthServiceInternalFindVariable(), AuthServiceInternalUpdateVariable(), EFI_CERT_DB_NAME, EFI_STATUS(), FindCertsFromDb(), gEfiCertDbGuid, mCertDbStore, and UINTN().

Referenced by CleanCertsFromDb(), ProcessVariable(), and VerifyTimeBasedPayloadAndUpdate().

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.

References BOOLEAN(), EFI_STATUS(), mAuthVarLibContextIn, TRUE, and UINTN().

Referenced by AuthServiceInternalUpdateVariableWithTimeStamp().

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

Process variable with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS/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 set.

EFI_OUT_OF_RESOURCES The Database to save the public key is full.

EFI_SECURITY_VIOLATION The variable is with EFI_VARIABLE_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.

References AddPubKeyInStore(), AUTHINFO_SIZE, AuthServiceInternalUpdateVariable(), AuthServiceInternalUpdateVariableWithMonotonicCount(), AuthVarTypePriv, BOOLEAN(), DeleteCertsFromDb(), EFI_CERT_TYPE_RSA2048_SIZE, EFI_STATUS(), IsDeleteAuthVariable(), mAuthVarLibContextIn, mPubKeyNumber, mPubKeyStore, NeedPhysicallyPresent(), TRUE, UserPhysicalPresent(), VerifyCounterBasedPayload(), and VerifyTimeBasedPayloadAndUpdate().

Referenced by AuthVariableLibProcessVariable().

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

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.

References AuthServiceInternalUpdateVariableWithTimeStamp(), AuthVarTypeKek, CheckSignatureListFormat(), EFI_STATUS(), InCustomMode(), mPlatformMode, UINTN(), UserPhysicalPresent(), VendorKeyIsModified(), and VerifyTimeBasedPayloadAndUpdate().

Referenced by AuthVariableLibProcessVariable(), and EsalSetVariable().

EFI_STATUS ProcessVarWithPk ( IN CHAR16 *  VariableName,
IN EFI_GUID *  VendorGuid,
IN VOID *  Data,
IN UINTN  DataSize,
IN UINT32  Attributes,
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.

References AuthServiceInternalUpdateVariableWithTimeStamp(), AuthVarTypePayload, AuthVarTypePk, BOOLEAN(), CheckSignatureListFormat(), EFI_STATUS(), InCustomMode(), mPlatformMode, TRUE, UINTN(), UpdatePlatformMode(), UserPhysicalPresent(), VendorKeyIsModified(), and VerifyTimeBasedPayloadAndUpdate().

Referenced by AuthVariableLibProcessVariable(), and EsalSetVariable().

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.

References AuthServiceInternalUpdateVariableWithTimeStamp(), AuthVarTypePriv, BOOLEAN(), DeleteCertsFromDb(), EFI_STATUS(), mAuthVarLibContextIn, TRUE, UINTN(), and VerifyTimeBasedPayload().

Referenced by ProcessVariable(), ProcessVarWithKek(), and ProcessVarWithPk().


Variable Documentation

AUTH_VAR_LIB_CONTEXT_IN* mAuthVarLibContextIn

UINT8* mCertDbStore

VOID* mHashCtx

UINT32 mMaxKeyDbSize

UINT32 mMaxKeyNumber

UINT32 mPlatformMode

UINT32 mPubKeyNumber

UINT8* mPubKeyStore

Global database array for scratch

Referenced by AddPubKeyInStore(), AuthVariableLibInitialize(), GetAvailableKeyIndex(), and ProcessVariable().


Generated on Thu Sep 24 23:44:24 2015 for SecurityPkg[ALL] by  doxygen 1.5.7.1