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