MdeModulePkg: Deprecate EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS
[mirror_edk2.git] / MdeModulePkg / Include / Library / AuthVariableLib.h
1 /** @file
2 Provides services to initialize and process authenticated variables.
3
4 Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials are licensed and made available under
6 the terms and conditions of the BSD License that accompanies this distribution.
7 The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php.
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 **/
14
15 #ifndef _AUTH_VARIABLE_LIB_H_
16 #define _AUTH_VARIABLE_LIB_H_
17
18 #include <Protocol/VarCheck.h>
19
20 ///
21 /// Size of AuthInfo prior to the data payload.
22 ///
23 #define AUTHINFO_SIZE ((OFFSET_OF (EFI_VARIABLE_AUTHENTICATION, AuthInfo)) + \
24 (OFFSET_OF (WIN_CERTIFICATE_UEFI_GUID, CertData)) + \
25 sizeof (EFI_CERT_BLOCK_RSA_2048_SHA256))
26
27 #define AUTHINFO2_SIZE(VarAuth2) ((OFFSET_OF (EFI_VARIABLE_AUTHENTICATION_2, AuthInfo)) + \
28 (UINTN) ((EFI_VARIABLE_AUTHENTICATION_2 *) (VarAuth2))->AuthInfo.Hdr.dwLength)
29
30 #define OFFSET_OF_AUTHINFO2_CERT_DATA ((OFFSET_OF (EFI_VARIABLE_AUTHENTICATION_2, AuthInfo)) + \
31 (OFFSET_OF (WIN_CERTIFICATE_UEFI_GUID, CertData)))
32
33 typedef struct {
34 CHAR16 *VariableName;
35 EFI_GUID *VendorGuid;
36 UINT32 Attributes;
37 UINTN DataSize;
38 VOID *Data;
39 UINT32 PubKeyIndex;
40 UINT64 MonotonicCount;
41 EFI_TIME *TimeStamp;
42 } AUTH_VARIABLE_INFO;
43
44 /**
45 Finds variable in storage blocks of volatile and non-volatile storage areas.
46
47 This code finds variable in storage blocks of volatile and non-volatile storage areas.
48 If VariableName is an empty string, then we just return the first
49 qualified variable without comparing VariableName and VendorGuid.
50
51 @param[in] VariableName Name of the variable to be found.
52 @param[in] VendorGuid Variable vendor GUID to be found.
53 @param[out] AuthVariableInfo Pointer to AUTH_VARIABLE_INFO structure for
54 output of the variable found.
55
56 @retval EFI_INVALID_PARAMETER If VariableName is not an empty string,
57 while VendorGuid is NULL.
58 @retval EFI_SUCCESS Variable successfully found.
59 @retval EFI_NOT_FOUND Variable not found
60
61 **/
62 typedef
63 EFI_STATUS
64 (EFIAPI *AUTH_VAR_LIB_FIND_VARIABLE) (
65 IN CHAR16 *VariableName,
66 IN EFI_GUID *VendorGuid,
67 OUT AUTH_VARIABLE_INFO *AuthVariableInfo
68 );
69
70 /**
71 Finds next variable in storage blocks of volatile and non-volatile storage areas.
72
73 This code finds next variable in storage blocks of volatile and non-volatile storage areas.
74 If VariableName is an empty string, then we just return the first
75 qualified variable without comparing VariableName and VendorGuid.
76
77 @param[in] VariableName Name of the variable to be found.
78 @param[in] VendorGuid Variable vendor GUID to be found.
79 @param[out] AuthVariableInfo Pointer to AUTH_VARIABLE_INFO structure for
80 output of the next variable.
81
82 @retval EFI_INVALID_PARAMETER If VariableName is not an empty string,
83 while VendorGuid is NULL.
84 @retval EFI_SUCCESS Variable successfully found.
85 @retval EFI_NOT_FOUND Variable not found
86
87 **/
88 typedef
89 EFI_STATUS
90 (EFIAPI *AUTH_VAR_LIB_FIND_NEXT_VARIABLE) (
91 IN CHAR16 *VariableName,
92 IN EFI_GUID *VendorGuid,
93 OUT AUTH_VARIABLE_INFO *AuthVariableInfo
94 );
95
96 /**
97 Update the variable region with Variable information.
98
99 @param[in] AuthVariableInfo Pointer AUTH_VARIABLE_INFO structure for
100 input of the variable.
101
102 @retval EFI_SUCCESS The update operation is success.
103 @retval EFI_INVALID_PARAMETER Invalid parameter.
104 @retval EFI_WRITE_PROTECTED Variable is write-protected.
105 @retval EFI_OUT_OF_RESOURCES There is not enough resource.
106
107 **/
108 typedef
109 EFI_STATUS
110 (EFIAPI *AUTH_VAR_LIB_UPDATE_VARIABLE) (
111 IN AUTH_VARIABLE_INFO *AuthVariableInfo
112 );
113
114 /**
115 Get scratch buffer.
116
117 @param[in, out] ScratchBufferSize Scratch buffer size. If input size is greater than
118 the maximum supported buffer size, this value contains
119 the maximum supported buffer size as output.
120 @param[out] ScratchBuffer Pointer to scratch buffer address.
121
122 @retval EFI_SUCCESS Get scratch buffer successfully.
123 @retval EFI_UNSUPPORTED If input size is greater than the maximum supported buffer size.
124
125 **/
126 typedef
127 EFI_STATUS
128 (EFIAPI *AUTH_VAR_LIB_GET_SCRATCH_BUFFER) (
129 IN OUT UINTN *ScratchBufferSize,
130 OUT VOID **ScratchBuffer
131 );
132
133 /**
134 This function is to check if the remaining variable space is enough to set
135 all Variables from argument list successfully. The purpose of the check
136 is to keep the consistency of the Variables to be in variable storage.
137
138 Note: Variables are assumed to be in same storage.
139 The set sequence of Variables will be same with the sequence of VariableEntry from argument list,
140 so follow the argument sequence to check the Variables.
141
142 @param[in] Attributes Variable attributes for Variable entries.
143 @param ... The variable argument list with type VARIABLE_ENTRY_CONSISTENCY *.
144 A NULL terminates the list. The VariableSize of
145 VARIABLE_ENTRY_CONSISTENCY is the variable data size as input.
146 It will be changed to variable total size as output.
147
148 @retval TRUE Have enough variable space to set the Variables successfully.
149 @retval FALSE No enough variable space to set the Variables successfully.
150
151 **/
152 typedef
153 BOOLEAN
154 (EFIAPI *AUTH_VAR_LIB_CHECK_REMAINING_SPACE) (
155 IN UINT32 Attributes,
156 ...
157 );
158
159 /**
160 Return TRUE if at OS runtime.
161
162 @retval TRUE If at OS runtime.
163 @retval FALSE If at boot time.
164
165 **/
166 typedef
167 BOOLEAN
168 (EFIAPI *AUTH_VAR_LIB_AT_RUNTIME) (
169 VOID
170 );
171
172 #define AUTH_VAR_LIB_CONTEXT_IN_STRUCT_VERSION 0x01
173
174 typedef struct {
175 UINTN StructVersion;
176 UINTN StructSize;
177 //
178 // Reflect the overhead associated with the saving
179 // of a single EFI authenticated variable with the exception
180 // of the overhead associated with the length
181 // of the string name of the EFI variable.
182 //
183 UINTN MaxAuthVariableSize;
184 AUTH_VAR_LIB_FIND_VARIABLE FindVariable;
185 AUTH_VAR_LIB_FIND_NEXT_VARIABLE FindNextVariable;
186 AUTH_VAR_LIB_UPDATE_VARIABLE UpdateVariable;
187 AUTH_VAR_LIB_GET_SCRATCH_BUFFER GetScratchBuffer;
188 AUTH_VAR_LIB_CHECK_REMAINING_SPACE CheckRemainingSpaceForConsistency;
189 AUTH_VAR_LIB_AT_RUNTIME AtRuntime;
190 } AUTH_VAR_LIB_CONTEXT_IN;
191
192 #define AUTH_VAR_LIB_CONTEXT_OUT_STRUCT_VERSION 0x01
193
194 typedef struct {
195 UINTN StructVersion;
196 UINTN StructSize;
197 //
198 // Caller needs to set variable property for the variables.
199 //
200 VARIABLE_ENTRY_PROPERTY *AuthVarEntry;
201 UINTN AuthVarEntryCount;
202 //
203 // Caller needs to ConvertPointer() for the pointers.
204 //
205 VOID ***AddressPointer;
206 UINTN AddressPointerCount;
207 } AUTH_VAR_LIB_CONTEXT_OUT;
208
209 /**
210 Initialization for authenticated varibale services.
211 If this initialization returns error status, other APIs will not work
212 and expect to be not called then.
213
214 @param[in] AuthVarLibContextIn Pointer to input auth variable lib context.
215 @param[out] AuthVarLibContextOut Pointer to output auth variable lib context.
216
217 @retval EFI_SUCCESS Function successfully executed.
218 @retval EFI_INVALID_PARAMETER If AuthVarLibContextIn == NULL or AuthVarLibContextOut == NULL.
219 @retval EFI_OUT_OF_RESOURCES Fail to allocate enough resource.
220 @retval EFI_UNSUPPORTED Unsupported to process authenticated variable.
221
222 **/
223 EFI_STATUS
224 EFIAPI
225 AuthVariableLibInitialize (
226 IN AUTH_VAR_LIB_CONTEXT_IN *AuthVarLibContextIn,
227 OUT AUTH_VAR_LIB_CONTEXT_OUT *AuthVarLibContextOut
228 );
229
230 /**
231 Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set.
232
233 @param[in] VariableName Name of the variable.
234 @param[in] VendorGuid Variable vendor GUID.
235 @param[in] Data Data pointer.
236 @param[in] DataSize Size of Data.
237 @param[in] Attributes Attribute value of the variable.
238
239 @retval EFI_SUCCESS The firmware has successfully stored the variable and its data as
240 defined by the Attributes.
241 @retval EFI_INVALID_PARAMETER Invalid parameter.
242 @retval EFI_WRITE_PROTECTED Variable is write-protected.
243 @retval EFI_OUT_OF_RESOURCES There is not enough resource.
244 @retval EFI_SECURITY_VIOLATION The variable is with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACESS
245 set, but the AuthInfo does NOT pass the validation
246 check carried out by the firmware.
247 @retval EFI_UNSUPPORTED Unsupported to process authenticated variable.
248
249 **/
250 EFI_STATUS
251 EFIAPI
252 AuthVariableLibProcessVariable (
253 IN CHAR16 *VariableName,
254 IN EFI_GUID *VendorGuid,
255 IN VOID *Data,
256 IN UINTN DataSize,
257 IN UINT32 Attributes
258 );
259
260 #endif