VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/MdeModulePkg/Include/Library/VariablePolicyLib.h@ 105670

Last change on this file since 105670 was 105670, checked in by vboxsync, 4 months ago

Devices/EFI/FirmwareNew: Merge edk2-stable-202405 and make it build on aarch64, bugref:4643
  • Property svn:eol-style set to native
File size: 13.1 KB
Line 
1/** @file -- VariablePolicyLib.h
2Business logic for Variable Policy enforcement.
3
4Copyright (c) Microsoft Corporation.
5SPDX-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**/
30EFI_STATUS
31EFIAPI
32RegisterVariablePolicy (
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**/
55EFI_STATUS
56EFIAPI
57ValidateSetVariable (
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**/
76EFI_STATUS
77EFIAPI
78DisableVariablePolicy (
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**/
98EFI_STATUS
99EFIAPI
100DumpVariablePolicy (
101 OUT UINT8 *Policy,
102 IN OUT UINT32 *Size
103 );
104
105/**
106 This function will return variable policy information for a UEFI variable with a
107 registered variable policy.
108
109 @param[in] VariableName The name of the variable to use for the policy search.
110 @param[in] VendorGuid The vendor GUID of the variable to use for the policy search.
111 @param[in,out] VariablePolicyVariableNameBufferSize On input, the size, in bytes, of the VariablePolicyVariableName
112 buffer.
113
114 On output, the size, in bytes, needed to store the variable
115 policy variable name.
116
117 If testing for the VariablePolicyVariableName buffer size
118 needed, set this value to zero so EFI_BUFFER_TOO_SMALL is
119 guaranteed to be returned if the variable policy variable name
120 is found.
121 @param[out] VariablePolicy Pointer to a buffer where the policy entry will be written
122 if found.
123 @param[out] VariablePolicyVariableName Pointer to a buffer where the variable name used for the
124 variable policy will be written if a variable name is
125 registered.
126
127 If the variable policy is not associated with a variable name
128 (e.g. applied to variable vendor namespace) and this parameter
129 is given, this parameter will not be modified and
130 VariablePolicyVariableNameBufferSize will be set to zero to
131 indicate a name was not present.
132
133 If the pointer given is not NULL,
134 VariablePolicyVariableNameBufferSize must be non-NULL.
135
136 @retval EFI_SUCCESS A variable policy entry was found and returned successfully.
137 @retval EFI_BAD_BUFFER_SIZE An internal buffer size caused a calculation error.
138 @retval EFI_BUFFER_TOO_SMALL The VariablePolicyVariableName buffer value is too small for the size needed.
139 The buffer should now point to the size needed.
140 @retval EFI_NOT_READY Variable policy has not yet been initialized.
141 @retval EFI_INVALID_PARAMETER A required pointer argument passed is NULL. This will be returned if
142 VariablePolicyVariableName is non-NULL and VariablePolicyVariableNameBufferSize
143 is NULL.
144 @retval EFI_NOT_FOUND A variable policy was not found for the given UEFI variable name and vendor GUID.
145
146**/
147EFI_STATUS
148EFIAPI
149GetVariablePolicyInfo (
150 IN CONST CHAR16 *VariableName,
151 IN CONST EFI_GUID *VendorGuid,
152 IN OUT UINTN *VariablePolicyVariableNameBufferSize OPTIONAL,
153 OUT VARIABLE_POLICY_ENTRY *VariablePolicy,
154 OUT CHAR16 *VariablePolicyVariableName OPTIONAL
155 );
156
157/**
158 This function will return the Lock on Variable State policy information for the policy
159 associated with the given UEFI variable.
160
161 @param[in] VariableName The name of the variable to use for the policy search.
162 @param[in] VendorGuid The vendor GUID of the variable to use for the policy
163 search.
164 @param[in,out] VariableLockPolicyVariableNameBufferSize On input, the size, in bytes, of the
165 VariableLockPolicyVariableName buffer.
166
167 On output, the size, in bytes, needed to store the variable
168 policy variable name.
169
170 If testing for the VariableLockPolicyVariableName buffer
171 size needed, set this value to zero so EFI_BUFFER_TOO_SMALL
172 is guaranteed to be returned if the variable policy variable
173 name is found.
174 @param[out] VariablePolicy Pointer to a buffer where the policy entry will be written
175 if found.
176 @param[out] VariableLockPolicyVariableName Pointer to a buffer where the variable name used for the
177 variable lock on variable state policy will be written if
178 a variable name is registered.
179
180 If the lock on variable policy is not associated with a
181 variable name (e.g. applied to variable vendor namespace)
182 and this parameter is given, this parameter will not be
183 modified and VariableLockPolicyVariableNameBufferSize will
184 be set to zero to indicate a name was not present.
185
186 If the pointer given is not NULL,
187 VariableLockPolicyVariableNameBufferSize must be non-NULL.
188
189 @retval EFI_SUCCESS A Lock on Variable State variable policy entry was found and returned
190 successfully.
191 @retval EFI_BAD_BUFFER_SIZE An internal buffer size caused a calculation error.
192 @retval EFI_BUFFER_TOO_SMALL The VariableLockPolicyVariableName buffer is too small for the size needed.
193 The buffer should now point to the size needed.
194 @retval EFI_NOT_READY Variable policy has not yet been initialized.
195 @retval EFI_INVALID_PARAMETER A required pointer argument passed is NULL. This will be returned if
196 VariableLockPolicyVariableName is non-NULL and
197 VariableLockPolicyVariableNameBufferSize is NULL.
198 @retval EFI_NOT_FOUND A Lock on Variable State variable policy was not found for the given UEFI
199 variable name and vendor GUID.
200
201**/
202EFI_STATUS
203EFIAPI
204GetLockOnVariableStateVariablePolicyInfo (
205 IN CONST CHAR16 *VariableName,
206 IN CONST EFI_GUID *VendorGuid,
207 IN OUT UINTN *VariableLockPolicyVariableNameBufferSize OPTIONAL,
208 OUT VARIABLE_LOCK_ON_VAR_STATE_POLICY *VariablePolicy,
209 OUT CHAR16 *VariableLockPolicyVariableName OPTIONAL
210 );
211
212/**
213 This API function returns whether or not the policy engine is
214 currently being enforced.
215
216 @retval TRUE
217 @retval FALSE
218 @retval FALSE Library has not yet been initialized.
219
220**/
221BOOLEAN
222EFIAPI
223IsVariablePolicyEnabled (
224 VOID
225 );
226
227/**
228 This API function locks the interface so that no more policy updates
229 can be performed or changes made to the enforcement until the next boot.
230
231 @retval EFI_SUCCESS
232 @retval EFI_NOT_READY Library has not yet been initialized.
233
234**/
235EFI_STATUS
236EFIAPI
237LockVariablePolicy (
238 VOID
239 );
240
241/**
242 This API function returns whether or not the policy interface is locked
243 for the remainder of the boot.
244
245 @retval TRUE
246 @retval FALSE
247 @retval FALSE Library has not yet been initialized.
248
249**/
250BOOLEAN
251EFIAPI
252IsVariablePolicyInterfaceLocked (
253 VOID
254 );
255
256/**
257 This helper function initializes the library and sets
258 up any required internal structures or handlers.
259
260 Also registers the internal pointer for the GetVariable helper.
261
262 @param[in] GetVariableHelper A function pointer matching the EFI_GET_VARIABLE prototype that will be used to
263 check policy criteria that involve the existence of other variables.
264
265 @retval EFI_SUCCESS
266 @retval EFI_ALREADY_STARTED The initialize function has been called more than once without a call to
267 deinitialize.
268
269**/
270EFI_STATUS
271EFIAPI
272InitVariablePolicyLib (
273 IN EFI_GET_VARIABLE GetVariableHelper
274 );
275
276/**
277 This helper function returns whether or not the library is currently initialized.
278
279 @retval TRUE
280 @retval FALSE
281
282**/
283BOOLEAN
284EFIAPI
285IsVariablePolicyLibInitialized (
286 VOID
287 );
288
289/**
290 This helper function tears down the library.
291
292 Should generally only be used for test harnesses.
293
294 @retval EFI_SUCCESS
295 @retval EFI_NOT_READY Deinitialize was called without first calling initialize.
296
297**/
298EFI_STATUS
299EFIAPI
300DeinitVariablePolicyLib (
301 VOID
302 );
303
304#endif // _VARIABLE_POLICY_LIB_H_
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette