f3b2187d55
Introduces two new APIs to EDKII_VARIABLE_POLICY_PROTOCOL: 1. GetVariablePolicyInfo() 2. GetLockOnVariableStateVariablePolicyInfo() These allow a caller to retrieve policy information associated with a UEFI variable given the variable name and vendor GUID. GetVariablePolicyInfo() - Returns the variable policy applied to the UEFI variable. If the variable policy is applied toward an individual UEFI variable, that name can optionally be returned. GetLockOnVariableStateVariablePolicyInfo() - Returns the Lock on Variable State policy applied to the UEFI variable. If the Lock on Variable State policy is applied to a specific variable name, that name can optionally be returned. These functions can be useful for a variety of purposes such as auditing, testing, and functional flows. Also fixed some variable name typos in code touched by the changes. Cc: Dandan Bi <dandan.bi@intel.com> Cc: Hao A Wu <hao.a.wu@intel.com> Cc: Jian J Wang <jian.j.wang@intel.com> Cc: Liming Gao <gaoliming@byosoft.com.cn> Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com> Reviewed-by: Ard Biesheuvel <ardb@kernel.org> Reviewed-by: Liming Gao <gaoliming@byosoft.com.cn> Message-Id: <20231030203112.736-2-mikuback@linux.microsoft.com>
305 lines
13 KiB
C
305 lines
13 KiB
C
/** @file -- VariablePolicyLib.h
|
|
Business logic for Variable Policy enforcement.
|
|
|
|
Copyright (c) Microsoft Corporation.
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
**/
|
|
|
|
#ifndef _VARIABLE_POLICY_LIB_H_
|
|
#define _VARIABLE_POLICY_LIB_H_
|
|
|
|
#include <Protocol/VariablePolicy.h>
|
|
|
|
/**
|
|
This API function validates and registers a new policy with
|
|
the policy enforcement engine.
|
|
|
|
@param[in] NewPolicy Pointer to the incoming policy structure.
|
|
|
|
@retval EFI_SUCCESS
|
|
@retval EFI_INVALID_PARAMETER NewPolicy is NULL or is internally inconsistent.
|
|
@retval EFI_ALREADY_STARTED An identical matching policy already exists.
|
|
@retval EFI_WRITE_PROTECTED The interface has been locked until the next reboot.
|
|
@retval EFI_UNSUPPORTED Policy enforcement has been disabled. No reason to add more policies.
|
|
@retval EFI_ABORTED A calculation error has prevented this function from completing.
|
|
@retval EFI_OUT_OF_RESOURCES Cannot grow the table to hold any more policies.
|
|
@retval EFI_NOT_READY Library has not yet been initialized.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
RegisterVariablePolicy (
|
|
IN CONST VARIABLE_POLICY_ENTRY *NewPolicy
|
|
);
|
|
|
|
/**
|
|
This API function checks to see whether the parameters to SetVariable would
|
|
be allowed according to the current variable policies.
|
|
|
|
@param[in] VariableName Same as EFI_SET_VARIABLE.
|
|
@param[in] VendorGuid Same as EFI_SET_VARIABLE.
|
|
@param[in] Attributes Same as EFI_SET_VARIABLE.
|
|
@param[in] DataSize Same as EFI_SET_VARIABLE.
|
|
@param[in] Data Same as EFI_SET_VARIABLE.
|
|
|
|
@retval EFI_SUCCESS A matching policy allows this update.
|
|
@retval EFI_SUCCESS There are currently no policies that restrict this update.
|
|
@retval EFI_SUCCESS The protections have been disable until the next reboot.
|
|
@retval EFI_WRITE_PROTECTED Variable is currently locked.
|
|
@retval EFI_INVALID_PARAMETER Attributes or size are invalid.
|
|
@retval EFI_ABORTED A lock policy exists, but an error prevented evaluation.
|
|
@retval EFI_NOT_READY Library has not been initialized.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
ValidateSetVariable (
|
|
IN CHAR16 *VariableName,
|
|
IN EFI_GUID *VendorGuid,
|
|
IN UINT32 Attributes,
|
|
IN UINTN DataSize,
|
|
IN VOID *Data
|
|
);
|
|
|
|
/**
|
|
This API function disables the variable policy enforcement. If it's
|
|
already been called once, will return EFI_ALREADY_STARTED.
|
|
|
|
@retval EFI_SUCCESS
|
|
@retval EFI_ALREADY_STARTED Has already been called once this boot.
|
|
@retval EFI_WRITE_PROTECTED Interface has been locked until reboot.
|
|
@retval EFI_WRITE_PROTECTED Interface option is disabled by platform PCD.
|
|
@retval EFI_NOT_READY Library has not yet been initialized.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
DisableVariablePolicy (
|
|
VOID
|
|
);
|
|
|
|
/**
|
|
This API function will dump the entire contents of the variable policy table.
|
|
|
|
Similar to GetVariable, the first call can be made with a 0 size and it will return
|
|
the size of the buffer required to hold the entire table.
|
|
|
|
@param[out] Policy Pointer to the policy buffer. Can be NULL if Size is 0.
|
|
@param[in,out] Size On input, the size of the output buffer. On output, the size
|
|
of the data returned.
|
|
|
|
@retval EFI_SUCCESS Policy data is in the output buffer and Size has been updated.
|
|
@retval EFI_INVALID_PARAMETER Size is NULL, or Size is non-zero and Policy is NULL.
|
|
@retval EFI_BUFFER_TOO_SMALL Size is insufficient to hold policy. Size updated with required size.
|
|
@retval EFI_NOT_READY Library has not yet been initialized.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
DumpVariablePolicy (
|
|
OUT UINT8 *Policy,
|
|
IN OUT UINT32 *Size
|
|
);
|
|
|
|
/**
|
|
This function will return variable policy information for a UEFI variable with a
|
|
registered variable policy.
|
|
|
|
@param[in] VariableName The name of the variable to use for the policy search.
|
|
@param[in] VendorGuid The vendor GUID of the variable to use for the policy search.
|
|
@param[in,out] VariablePolicyVariableNameBufferSize On input, the size, in bytes, of the VariablePolicyVariableName
|
|
buffer.
|
|
|
|
On output, the size, in bytes, needed to store the variable
|
|
policy variable name.
|
|
|
|
If testing for the VariablePolicyVariableName buffer size
|
|
needed, set this value to zero so EFI_BUFFER_TOO_SMALL is
|
|
guaranteed to be returned if the variable policy variable name
|
|
is found.
|
|
@param[out] VariablePolicy Pointer to a buffer where the policy entry will be written
|
|
if found.
|
|
@param[out] VariablePolicyVariableName Pointer to a buffer where the variable name used for the
|
|
variable policy will be written if a variable name is
|
|
registered.
|
|
|
|
If the variable policy is not associated with a variable name
|
|
(e.g. applied to variable vendor namespace) and this parameter
|
|
is given, this parameter will not be modified and
|
|
VariablePolicyVariableNameBufferSize will be set to zero to
|
|
indicate a name was not present.
|
|
|
|
If the pointer given is not NULL,
|
|
VariablePolicyVariableNameBufferSize must be non-NULL.
|
|
|
|
@retval EFI_SUCCESS A variable policy entry was found and returned successfully.
|
|
@retval EFI_BAD_BUFFER_SIZE An internal buffer size caused a calculation error.
|
|
@retval EFI_BUFFER_TOO_SMALL The VariablePolicyVariableName buffer value is too small for the size needed.
|
|
The buffer should now point to the size needed.
|
|
@retval EFI_NOT_READY Variable policy has not yet been initialized.
|
|
@retval EFI_INVALID_PARAMETER A required pointer argument passed is NULL. This will be returned if
|
|
VariablePolicyVariableName is non-NULL and VariablePolicyVariableNameBufferSize
|
|
is NULL.
|
|
@retval EFI_NOT_FOUND A variable policy was not found for the given UEFI variable name and vendor GUID.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
GetVariablePolicyInfo (
|
|
IN CONST CHAR16 *VariableName,
|
|
IN CONST EFI_GUID *VendorGuid,
|
|
IN OUT UINTN *VariablePolicyVariableNameBufferSize OPTIONAL,
|
|
OUT VARIABLE_POLICY_ENTRY *VariablePolicy,
|
|
OUT CHAR16 *VariablePolicyVariableName OPTIONAL
|
|
);
|
|
|
|
/**
|
|
This function will return the Lock on Variable State policy information for the policy
|
|
associated with the given UEFI variable.
|
|
|
|
@param[in] VariableName The name of the variable to use for the policy search.
|
|
@param[in] VendorGuid The vendor GUID of the variable to use for the policy
|
|
search.
|
|
@param[in,out] VariableLockPolicyVariableNameBufferSize On input, the size, in bytes, of the
|
|
VariableLockPolicyVariableName buffer.
|
|
|
|
On output, the size, in bytes, needed to store the variable
|
|
policy variable name.
|
|
|
|
If testing for the VariableLockPolicyVariableName buffer
|
|
size needed, set this value to zero so EFI_BUFFER_TOO_SMALL
|
|
is guaranteed to be returned if the variable policy variable
|
|
name is found.
|
|
@param[out] VariablePolicy Pointer to a buffer where the policy entry will be written
|
|
if found.
|
|
@param[out] VariableLockPolicyVariableName Pointer to a buffer where the variable name used for the
|
|
variable lock on variable state policy will be written if
|
|
a variable name is registered.
|
|
|
|
If the lock on variable policy is not associated with a
|
|
variable name (e.g. applied to variable vendor namespace)
|
|
and this parameter is given, this parameter will not be
|
|
modified and VariableLockPolicyVariableNameBufferSize will
|
|
be set to zero to indicate a name was not present.
|
|
|
|
If the pointer given is not NULL,
|
|
VariableLockPolicyVariableNameBufferSize must be non-NULL.
|
|
|
|
@retval EFI_SUCCESS A Lock on Variable State variable policy entry was found and returned
|
|
successfully.
|
|
@retval EFI_BAD_BUFFER_SIZE An internal buffer size caused a calculation error.
|
|
@retval EFI_BUFFER_TOO_SMALL The VariableLockPolicyVariableName buffer is too small for the size needed.
|
|
The buffer should now point to the size needed.
|
|
@retval EFI_NOT_READY Variable policy has not yet been initialized.
|
|
@retval EFI_INVALID_PARAMETER A required pointer argument passed is NULL. This will be returned if
|
|
VariableLockPolicyVariableName is non-NULL and
|
|
VariableLockPolicyVariableNameBufferSize is NULL.
|
|
@retval EFI_NOT_FOUND A Lock on Variable State variable policy was not found for the given UEFI
|
|
variable name and vendor GUID.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
GetLockOnVariableStateVariablePolicyInfo (
|
|
IN CONST CHAR16 *VariableName,
|
|
IN CONST EFI_GUID *VendorGuid,
|
|
IN OUT UINTN *VariableLockPolicyVariableNameBufferSize OPTIONAL,
|
|
OUT VARIABLE_LOCK_ON_VAR_STATE_POLICY *VariablePolicy,
|
|
OUT CHAR16 *VariableLockPolicyVariableName OPTIONAL
|
|
);
|
|
|
|
/**
|
|
This API function returns whether or not the policy engine is
|
|
currently being enforced.
|
|
|
|
@retval TRUE
|
|
@retval FALSE
|
|
@retval FALSE Library has not yet been initialized.
|
|
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
IsVariablePolicyEnabled (
|
|
VOID
|
|
);
|
|
|
|
/**
|
|
This API function locks the interface so that no more policy updates
|
|
can be performed or changes made to the enforcement until the next boot.
|
|
|
|
@retval EFI_SUCCESS
|
|
@retval EFI_NOT_READY Library has not yet been initialized.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
LockVariablePolicy (
|
|
VOID
|
|
);
|
|
|
|
/**
|
|
This API function returns whether or not the policy interface is locked
|
|
for the remainder of the boot.
|
|
|
|
@retval TRUE
|
|
@retval FALSE
|
|
@retval FALSE Library has not yet been initialized.
|
|
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
IsVariablePolicyInterfaceLocked (
|
|
VOID
|
|
);
|
|
|
|
/**
|
|
This helper function initializes the library and sets
|
|
up any required internal structures or handlers.
|
|
|
|
Also registers the internal pointer for the GetVariable helper.
|
|
|
|
@param[in] GetVariableHelper A function pointer matching the EFI_GET_VARIABLE prototype that will be used to
|
|
check policy criteria that involve the existence of other variables.
|
|
|
|
@retval EFI_SUCCESS
|
|
@retval EFI_ALREADY_STARTED The initialize function has been called more than once without a call to
|
|
deinitialize.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
InitVariablePolicyLib (
|
|
IN EFI_GET_VARIABLE GetVariableHelper
|
|
);
|
|
|
|
/**
|
|
This helper function returns whether or not the library is currently initialized.
|
|
|
|
@retval TRUE
|
|
@retval FALSE
|
|
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
IsVariablePolicyLibInitialized (
|
|
VOID
|
|
);
|
|
|
|
/**
|
|
This helper function tears down the library.
|
|
|
|
Should generally only be used for test harnesses.
|
|
|
|
@retval EFI_SUCCESS
|
|
@retval EFI_NOT_READY Deinitialize was called without first calling initialize.
|
|
|
|
**/
|
|
EFI_STATUS
|
|
EFIAPI
|
|
DeinitVariablePolicyLib (
|
|
VOID
|
|
);
|
|
|
|
#endif // _VARIABLE_POLICY_LIB_H_
|