MdeModulePkg/Include/Library/VariablePolicyLib.h

   1 /** @file -- VariablePolicyLib.h
   2 Business logic for Variable Policy enforcement.
   3
   4 Copyright (c) Microsoft Corporation.
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _VARIABLE_POLICY_LIB_H_
  10 #define _VARIABLE_POLICY_LIB_H_
  11
  12 #include <Protocol/VariablePolicy.h>
  13
  14 /**
  15   This API function validates and registers a new policy with
  16   the policy enforcement engine.
  17
  18   @param[in]  NewPolicy     Pointer to the incoming policy structure.
  19
  20   @retval     EFI_SUCCESS
  21   @retval     EFI_INVALID_PARAMETER   NewPolicy is NULL or is internally inconsistent.
  22   @retval     EFI_ALREADY_STARTED     An identical matching policy already exists.
  23   @retval     EFI_WRITE_PROTECTED     The interface has been locked until the next reboot.
  24   @retval     EFI_UNSUPPORTED         Policy enforcement has been disabled. No reason to add more policies.
  25   @retval     EFI_ABORTED             A calculation error has prevented this function from completing.
  26   @retval     EFI_OUT_OF_RESOURCES    Cannot grow the table to hold any more policies.
  27   @retval     EFI_NOT_READY           Library has not yet been initialized.
  28
  29 **/
  30 EFI_STATUS
  31 EFIAPI
  32 RegisterVariablePolicy (
  33   IN CONST VARIABLE_POLICY_ENTRY    *NewPolicy
  34   );
  35
  36
  37 /**
  38   This API function checks to see whether the parameters to SetVariable would
  39   be allowed according to the current variable policies.
  40
  41   @param[in]  VariableName       Same as EFI_SET_VARIABLE.
  42   @param[in]  VendorGuid         Same as EFI_SET_VARIABLE.
  43   @param[in]  Attributes         Same as EFI_SET_VARIABLE.
  44   @param[in]  DataSize           Same as EFI_SET_VARIABLE.
  45   @param[in]  Data               Same as EFI_SET_VARIABLE.
  46
  47   @retval     EFI_SUCCESS             A matching policy allows this update.
  48   @retval     EFI_SUCCESS             There are currently no policies that restrict this update.
  49   @retval     EFI_SUCCESS             The protections have been disable until the next reboot.
  50   @retval     EFI_WRITE_PROTECTED     Variable is currently locked.
  51   @retval     EFI_INVALID_PARAMETER   Attributes or size are invalid.
  52   @retval     EFI_ABORTED             A lock policy exists, but an error prevented evaluation.
  53   @retval     EFI_NOT_READY           Library has not been initialized.
  54
  55 **/
  56 EFI_STATUS
  57 EFIAPI
  58 ValidateSetVariable (
  59   IN  CHAR16                       *VariableName,
  60   IN  EFI_GUID                     *VendorGuid,
  61   IN  UINT32                       Attributes,
  62   IN  UINTN                        DataSize,
  63   IN  VOID                         *Data
  64   );
  65
  66
  67 /**
  68   This API function disables the variable policy enforcement. If it's
  69   already been called once, will return EFI_ALREADY_STARTED.
  70
  71   @retval     EFI_SUCCESS
  72   @retval     EFI_ALREADY_STARTED   Has already been called once this boot.
  73   @retval     EFI_WRITE_PROTECTED   Interface has been locked until reboot.
  74   @retval     EFI_WRITE_PROTECTED   Interface option is disabled by platform PCD.
  75   @retval     EFI_NOT_READY   Library has not yet been initialized.
  76
  77 **/
  78 EFI_STATUS
  79 EFIAPI
  80 DisableVariablePolicy (
  81   VOID
  82   );
  83
  84
  85 /**
  86   This API function will dump the entire contents of the variable policy table.
  87
  88   Similar to GetVariable, the first call can be made with a 0 size and it will return
  89   the size of the buffer required to hold the entire table.
  90
  91   @param[out]     Policy  Pointer to the policy buffer. Can be NULL if Size is 0.
  92   @param[in,out]  Size    On input, the size of the output buffer. On output, the size
  93                           of the data returned.
  94
  95   @retval     EFI_SUCCESS             Policy data is in the output buffer and Size has been updated.
  96   @retval     EFI_INVALID_PARAMETER   Size is NULL, or Size is non-zero and Policy is NULL.
  97   @retval     EFI_BUFFER_TOO_SMALL    Size is insufficient to hold policy. Size updated with required size.
  98   @retval     EFI_NOT_READY           Library has not yet been initialized.
  99
 100 **/
 101 EFI_STATUS
 102 EFIAPI
 103 DumpVariablePolicy (
 104   OUT     UINT8         *Policy,
 105   IN OUT  UINT32        *Size
 106   );
 107
 108
 109 /**
 110   This API function returns whether or not the policy engine is
 111   currently being enforced.
 112
 113   @retval     TRUE
 114   @retval     FALSE
 115   @retval     FALSE         Library has not yet been initialized.
 116
 117 **/
 118 BOOLEAN
 119 EFIAPI
 120 IsVariablePolicyEnabled (
 121   VOID
 122   );
 123
 124
 125 /**
 126   This API function locks the interface so that no more policy updates
 127   can be performed or changes made to the enforcement until the next boot.
 128
 129   @retval     EFI_SUCCESS
 130   @retval     EFI_NOT_READY   Library has not yet been initialized.
 131
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 LockVariablePolicy (
 136   VOID
 137   );
 138
 139
 140 /**
 141   This API function returns whether or not the policy interface is locked
 142   for the remainder of the boot.
 143
 144   @retval     TRUE
 145   @retval     FALSE
 146   @retval     FALSE         Library has not yet been initialized.
 147
 148 **/
 149 BOOLEAN
 150 EFIAPI
 151 IsVariablePolicyInterfaceLocked (
 152   VOID
 153   );
 154
 155
 156 /**
 157   This helper function initializes the library and sets
 158   up any required internal structures or handlers.
 159
 160   Also registers the internal pointer for the GetVariable helper.
 161
 162   @param[in]  GetVariableHelper A function pointer matching the EFI_GET_VARIABLE prototype that will be used to
 163                   check policy criteria that involve the existence of other variables.
 164
 165   @retval     EFI_SUCCESS
 166   @retval     EFI_ALREADY_STARTED   The initialize function has been called more than once without a call to
 167                                     deinitialize.
 168
 169 **/
 170 EFI_STATUS
 171 EFIAPI
 172 InitVariablePolicyLib (
 173   IN  EFI_GET_VARIABLE    GetVariableHelper
 174   );
 175
 176
 177 /**
 178   This helper function returns whether or not the library is currently initialized.
 179
 180   @retval     TRUE
 181   @retval     FALSE
 182
 183 **/
 184 BOOLEAN
 185 EFIAPI
 186 IsVariablePolicyLibInitialized (
 187   VOID
 188   );
 189
 190
 191 /**
 192   This helper function tears down  the library.
 193
 194   Should generally only be used for test harnesses.
 195
 196   @retval     EFI_SUCCESS
 197   @retval     EFI_NOT_READY     Deinitialize was called without first calling initialize.
 198
 199 **/
 200 EFI_STATUS
 201 EFIAPI
 202 DeinitVariablePolicyLib (
 203   VOID
 204   );
 205
 206
 207 #endif // _VARIABLE_POLICY_LIB_H_