ecff20fb80f18568368e820a5cd5738215c32084
[mirror_edk2.git] / SecurityPkg / VariableAuthenticated / EsalVariableDxeSal / Variable.h
1 /** @file
2 Internal header file for Extended SAL variable service module.
3
4 Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. 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 _VARIABLE_H_
16 #define _VARIABLE_H_
17
18 #include <PiDxe.h>
19
20 #include <Protocol/VariableWrite.h>
21 #include <Protocol/FaultTolerantWrite.h>
22 #include <Protocol/FirmwareVolumeBlock.h>
23 #include <Protocol/Variable.h>
24 #include <Protocol/ExtendedSalBootService.h>
25 #include <Protocol/ExtendedSalServiceClasses.h>
26
27 #include <Guid/GlobalVariable.h>
28 #include <Guid/AuthenticatedVariableFormat.h>
29 #include <Guid/ImageAuthentication.h>
30 #include <Guid/EventGroup.h>
31
32 #include <Library/PcdLib.h>
33 #include <Library/UefiDriverEntryPoint.h>
34 #include <Library/DxeServicesTableLib.h>
35 #include <Library/UefiRuntimeLib.h>
36 #include <Library/DebugLib.h>
37 #include <Library/BaseMemoryLib.h>
38 #include <Library/UefiBootServicesTableLib.h>
39 #include <Library/UefiLib.h>
40 #include <Library/BaseLib.h>
41 #include <Library/SynchronizationLib.h>
42 #include <Library/MemoryAllocationLib.h>
43 #include <Library/ExtendedSalLib.h>
44 #include <Library/BaseCryptLib.h>
45
46 #define MAX_NAME_SIZE 0x100
47 #define NUM_VAR_NAME 9 // Number of pre-defined variable name to be referenced
48 #define VAR_PLATFORM_LANG_CODES 0 // Index of "PlatformLangCodes" variable
49 #define VAR_LANG_CODES 1 // Index of "LangCodes" variable
50 #define VAR_PLATFORM_LANG 2 // Index of "PlatformLang" variable
51 #define VAR_LANG 3 // Index of "Lang" variable
52 #define VAR_HW_ERR_REC 4 // Index of "HwErrRecXXXX" variable
53 #define VAR_AUTH_KEY_DB 5 // Index of "AuthVarKeyDatabase" variable
54 #define VAR_SETUP_MODE 6 // Index of "SetupMode" variable
55 #define VAR_PLATFORM_KEY 7 // Index of "PK" variable
56 #define VAR_KEY_EXCHANGE_KEY 8 // Index of "KEK" variable
57
58 ///
59 /// "AuthVarKeyDatabase" variable for the Public Key store.
60 ///
61 #define AUTHVAR_KEYDB_NAME L"AuthVarKeyDatabase"
62 #define AUTHVAR_KEYDB_NAME_SIZE 38
63
64 ///
65 /// The maximum size of the public key database, restricted by maximum individal EFI
66 /// varible size, and excluding the variable header and name size.
67 ///
68 #define MAX_KEYDB_SIZE (FixedPcdGet32 (PcdMaxVariableSize) - sizeof (VARIABLE_HEADER) - AUTHVAR_KEYDB_NAME_SIZE)
69 #define MAX_KEY_NUM (MAX_KEYDB_SIZE / EFI_CERT_TYPE_RSA2048_SIZE)
70
71 ///
72 /// The size of a 3 character ISO639 language code.
73 ///
74 #define ISO_639_2_ENTRY_SIZE 3
75
76 typedef enum {
77 Physical,
78 Virtual
79 } VARIABLE_POINTER_TYPE;
80
81 typedef struct {
82 EFI_PHYSICAL_ADDRESS CurrPtr;
83 EFI_PHYSICAL_ADDRESS EndPtr;
84 EFI_PHYSICAL_ADDRESS StartPtr;
85 BOOLEAN Volatile;
86 } VARIABLE_POINTER_TRACK;
87
88 typedef struct {
89 EFI_PHYSICAL_ADDRESS VolatileVariableBase;
90 EFI_PHYSICAL_ADDRESS NonVolatileVariableBase;
91 EFI_LOCK VariableServicesLock;
92 } VARIABLE_GLOBAL;
93
94 typedef struct {
95 VARIABLE_GLOBAL VariableGlobal[2];
96 CHAR16 *VariableName[2][NUM_VAR_NAME];
97 EFI_GUID *GlobalVariableGuid[2];
98 UINTN VolatileLastVariableOffset;
99 UINTN NonVolatileLastVariableOffset;
100 UINTN CommonVariableTotalSize;
101 UINTN HwErrVariableTotalSize;
102 CHAR8 *PlatformLangCodes[2];
103 CHAR8 *LangCodes[2];
104 CHAR8 *PlatformLang[2];
105 CHAR8 Lang[ISO_639_2_ENTRY_SIZE + 1];
106 UINT32 FvbInstance;
107 UINT32 ReentrantState;
108 EFI_GUID *AuthenticatedVariableGuid[2];
109 EFI_GUID *CertRsa2048Sha256Guid[2];
110 EFI_GUID *ImageSecurityDatabaseGuid[2];
111 VOID *HashContext[2]; // Hash context pointer
112 UINT8 KeyList[MAX_KEYDB_SIZE]; // Cached Platform Key list
113 UINT8 PubKeyStore[MAX_KEYDB_SIZE]; // Cached Public Key list
114 } ESAL_VARIABLE_GLOBAL;
115
116 typedef struct {
117 EFI_GUID *Guid;
118 CHAR16 *Name;
119 UINT32 Attributes;
120 UINTN DataSize;
121 VOID *Data;
122 } VARIABLE_CACHE_ENTRY;
123
124
125 extern ESAL_VARIABLE_GLOBAL *mVariableModuleGlobal;
126
127 //
128 // Functions
129 //
130
131 /**
132 Initializes variable store area for non-volatile and volatile variable.
133
134 This function allocates and initializes memory space for global context of ESAL
135 variable service and variable store area for non-volatile and volatile variable.
136
137 @param[in] ImageHandle The Image handle of this driver.
138 @param[in] SystemTable The pointer of EFI_SYSTEM_TABLE.
139
140 @retval EFI_SUCCESS Function successfully executed.
141 @retval EFI_OUT_OF_RESOURCES Failed to allocate enough memory resource.
142
143 **/
144 EFI_STATUS
145 VariableCommonInitialize (
146 IN EFI_HANDLE ImageHandle,
147 IN EFI_SYSTEM_TABLE *SystemTable
148 );
149
150 /**
151 Entry point of Extended SAL Variable service module.
152
153 This function is the entry point of Extended SAL Variable service module.
154 It registers all functions of Extended SAL Variable class, initializes
155 variable store for non-volatile and volatile variables, and registers
156 notification function for EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE event.
157
158 @param[in] ImageHandle The Image handle of this driver.
159 @param[in] SystemTable The pointer of EFI_SYSTEM_TABLE.
160
161 @retval EFI_SUCCESS Extended SAL Variable Services Class successfully registered.
162
163 **/
164 EFI_STATUS
165 EFIAPI
166 VariableServiceInitialize (
167 IN EFI_HANDLE ImageHandle,
168 IN EFI_SYSTEM_TABLE *SystemTable
169 );
170
171 /**
172 Notification function of EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE.
173
174 This is a notification function registered on EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE event.
175 It convers pointer to new virtual address.
176
177 @param[in] Event The event whose notification function is being invoked.
178 @param[in] Context The pointer to the notification function's context.
179
180 **/
181 VOID
182 EFIAPI
183 VariableClassAddressChangeEvent (
184 IN EFI_EVENT Event,
185 IN VOID *Context
186 );
187
188 /**
189 Implements EsalGetVariable function of Extended SAL Variable Services Class.
190
191 This function implements EsalGetVariable function of Extended SAL Variable Services Class.
192 It is equivalent in functionality to the EFI Runtime Service GetVariable().
193
194 @param[in] VariableName A Null-terminated Unicode string that is the name of
195 the vendor's variable.
196 @param[in] VendorGuid A unique identifier for the vendor.
197 @param[out] Attributes If not NULL, a pointer to the memory location to return the
198 attributes bitmask for the variable.
199 @param[in, out] DataSize Size of Data found. If size is less than the
200 data, this value contains the required size.
201 @param[out] Data On input, the size in bytes of the return Data buffer.
202 On output, the size of data returned in Data.
203 @param[in] VirtualMode Current calling mode for this function.
204 @param[in] Global Context of this Extended SAL Variable Services Class call.
205
206 @retval EFI_SUCCESS The function completed successfully.
207 @retval EFI_NOT_FOUND The variable was not found.
208 @retval EFI_BUFFER_TOO_SMALL DataSize is too small for the result. DataSize has
209 been updated with the size needed to complete the request.
210 @retval EFI_INVALID_PARAMETER VariableName is NULL.
211 @retval EFI_INVALID_PARAMETER VendorGuid is NULL.
212 @retval EFI_INVALID_PARAMETER DataSize is NULL.
213 @retval EFI_INVALID_PARAMETER DataSize is not too small and Data is NULL.
214 @retval EFI_DEVICE_ERROR The variable could not be retrieved due to a hardware error.
215 @retval EFI_SECURITY_VIOLATION The variable could not be retrieved due to an authentication failure.
216
217 **/
218 EFI_STATUS
219 EFIAPI
220 EsalGetVariable (
221 IN CHAR16 *VariableName,
222 IN EFI_GUID *VendorGuid,
223 OUT UINT32 *Attributes OPTIONAL,
224 IN OUT UINTN *DataSize,
225 OUT VOID *Data,
226 IN BOOLEAN VirtualMode,
227 IN ESAL_VARIABLE_GLOBAL *Global
228 );
229
230 /**
231 Implements EsalGetNextVariableName function of Extended SAL Variable Services Class.
232
233 This function implements EsalGetNextVariableName function of Extended SAL Variable Services Class.
234 It is equivalent in functionality to the EFI Runtime Service GetNextVariableName().
235
236 @param[in, out] VariableNameSize Size of the variable
237 @param[in, out] VariableName On input, supplies the last VariableName that was returned by GetNextVariableName().
238 On output, returns the Null-terminated Unicode string of the current variable.
239 @param[in, out] VendorGuid On input, supplies the last VendorGuid that was returned by GetNextVariableName().
240 On output, returns the VendorGuid of the current variable.
241 @param[in] VirtualMode Current calling mode for this function.
242 @param[in] Global Context of this Extended SAL Variable Services Class call.
243
244 @retval EFI_SUCCESS The function completed successfully.
245 @retval EFI_NOT_FOUND The next variable was not found.
246 @retval EFI_BUFFER_TOO_SMALL VariableNameSize is too small for the result.
247 VariableNameSize has been updated with the size needed to complete the request.
248 @retval EFI_INVALID_PARAMETER VariableNameSize is NULL.
249 @retval EFI_INVALID_PARAMETER VariableName is NULL.
250 @retval EFI_INVALID_PARAMETER VendorGuid is NULL.
251 @retval EFI_DEVICE_ERROR The variable name could not be retrieved due to a hardware error.
252
253 **/
254 EFI_STATUS
255 EFIAPI
256 EsalGetNextVariableName (
257 IN OUT UINTN *VariableNameSize,
258 IN OUT CHAR16 *VariableName,
259 IN OUT EFI_GUID *VendorGuid,
260 IN BOOLEAN VirtualMode,
261 IN ESAL_VARIABLE_GLOBAL *Global
262 );
263
264 /**
265 Implements EsalSetVariable function of Extended SAL Variable Services Class.
266
267 This function implements EsalSetVariable function of Extended SAL Variable Services Class.
268 It is equivalent in functionality to the EFI Runtime Service SetVariable().
269
270 @param[in] VariableName A Null-terminated Unicode string that is the name of the vendor's
271 variable. Each VariableName is unique for each
272 VendorGuid. VariableName must contain 1 or more
273 Unicode characters. If VariableName is an empty Unicode
274 string, then EFI_INVALID_PARAMETER is returned.
275 @param[in] VendorGuid A unique identifier for the vendor.
276 @param[in] Attributes Attributes bitmask to set for the variable.
277 @param[in] DataSize The size in bytes of the Data buffer. A size of zero causes the
278 variable to be deleted.
279 @param[in] Data The contents for the variable.
280 @param[in] VirtualMode Current calling mode for this function.
281 @param[in] Global Context of this Extended SAL Variable Services Class call.
282
283 @retval EFI_SUCCESS The firmware has successfully stored the variable and its data as
284 defined by the Attributes.
285 @retval EFI_INVALID_PARAMETER An invalid combination of attribute bits was supplied, or the
286 DataSize exceeds the maximum allowed.
287 @retval EFI_INVALID_PARAMETER VariableName is an empty Unicode string.
288 @retval EFI_OUT_OF_RESOURCES Not enough storage is available to hold the variable and its data.
289 @retval EFI_DEVICE_ERROR The variable could not be saved due to a hardware failure.
290 @retval EFI_WRITE_PROTECTED The variable in question is read-only.
291 @retval EFI_WRITE_PROTECTED The variable in question cannot be deleted.
292 @retval EFI_SECURITY_VIOLATION The variable could not be retrieved due to an authentication failure.
293 @retval EFI_NOT_FOUND The variable trying to be updated or deleted was not found.
294
295 **/
296 EFI_STATUS
297 EFIAPI
298 EsalSetVariable (
299 IN CHAR16 *VariableName,
300 IN EFI_GUID *VendorGuid,
301 IN UINT32 Attributes,
302 IN UINTN DataSize,
303 IN VOID *Data,
304 IN BOOLEAN VirtualMode,
305 IN ESAL_VARIABLE_GLOBAL *Global
306 );
307
308 /**
309 Implements EsalQueryVariableInfo function of Extended SAL Variable Services Class.
310
311 This function implements EsalQueryVariableInfo function of Extended SAL Variable Services Class.
312 It is equivalent in functionality to the EFI Runtime Service QueryVariableInfo().
313
314 @param[in] Attributes Attributes bitmask to specify the type of variables
315 on which to return information.
316 @param[out] MaximumVariableStorageSize On output the maximum size of the storage space available for
317 the EFI variables associated with the attributes specified.
318 @param[out] RemainingVariableStorageSize Returns the remaining size of the storage space available for EFI
319 variables associated with the attributes specified.
320 @param[out] MaximumVariableSize Returns the maximum size of an individual EFI variable
321 associated with the attributes specified.
322 @param[in] VirtualMode Current calling mode for this function
323 @param[in] Global Context of this Extended SAL Variable Services Class call
324
325 @retval EFI_SUCCESS Valid answer returned.
326 @retval EFI_INVALID_PARAMETER An invalid combination of attribute bits was supplied.
327 @retval EFI_UNSUPPORTED The attribute is not supported on this platform, and the
328 MaximumVariableStorageSize, RemainingVariableStorageSize,
329 MaximumVariableSize are undefined.
330 **/
331 EFI_STATUS
332 EFIAPI
333 EsalQueryVariableInfo (
334 IN UINT32 Attributes,
335 OUT UINT64 *MaximumVariableStorageSize,
336 OUT UINT64 *RemainingVariableStorageSize,
337 OUT UINT64 *MaximumVariableSize,
338 IN BOOLEAN VirtualMode,
339 IN ESAL_VARIABLE_GLOBAL *Global
340 );
341
342 /**
343 Writes a buffer to variable storage space.
344
345 This function writes a buffer to variable storage space into firmware
346 volume block device. The destination is specified by parameter
347 VariableBase. Fault Tolerant Write protocol is used for writing.
348
349 @param[in] VariableBase The base address of the variable to write.
350 @param[in] Buffer Points to the data buffer.
351 @param[in] BufferSize The number of bytes of the data Buffer.
352
353 @retval EFI_SUCCESS The function completed successfully.
354 @retval EFI_NOT_FOUND Fail to locate Fault Tolerant Write protocol.
355 @retval Other The function could not complete successfully.
356
357 **/
358 EFI_STATUS
359 FtwVariableSpace (
360 IN EFI_PHYSICAL_ADDRESS VariableBase,
361 IN UINT8 *Buffer,
362 IN UINTN BufferSize
363 );
364
365 /**
366 Finds variable in volatile and non-volatile storage areas.
367
368 This code finds variable in volatile and non-volatile storage areas.
369 If VariableName is an empty string, then we just return the first
370 qualified variable without comparing VariableName and VendorGuid.
371 Otherwise, VariableName and VendorGuid are compared.
372
373 @param[in] VariableName Name of the variable to be found.
374 @param[in] VendorGuid Vendor GUID to be found.
375 @param[out] PtrTrack VARIABLE_POINTER_TRACK structure for output,
376 including the range searched and the target position.
377 @param[in] Global Pointer to VARIABLE_GLOBAL structure, including
378 base of volatile variable storage area, base of
379 NV variable storage area, and a lock.
380 @param[in] Instance Instance of FV Block services.
381
382 @retval EFI_INVALID_PARAMETER If VariableName is not an empty string, while
383 VendorGuid is NULL.
384 @retval EFI_SUCCESS Variable successfully found.
385 @retval EFI_INVALID_PARAMETER Variable not found.
386
387 **/
388 EFI_STATUS
389 FindVariable (
390 IN CHAR16 *VariableName,
391 IN EFI_GUID *VendorGuid,
392 OUT VARIABLE_POINTER_TRACK *PtrTrack,
393 IN VARIABLE_GLOBAL *Global,
394 IN UINTN Instance
395 );
396
397 /**
398 Gets the pointer to variable data area.
399
400 This function gets the pointer to variable data area.
401 The variable is specified by its variable header.
402
403 @param[in] VariableAddress Start address of variable header.
404 @param[in] Volatile TRUE - Variable is volatile.
405 FALSE - Variable is non-volatile.
406 @param[in] Global Pointer to VARAIBLE_GLOBAL structure.
407 @param[in] Instance Instance of FV Block services.
408 @param[out] VariableData Buffer to hold variable data for output.
409
410 **/
411 VOID
412 GetVariableDataPtr (
413 IN EFI_PHYSICAL_ADDRESS VariableAddress,
414 IN BOOLEAN Volatile,
415 IN VARIABLE_GLOBAL *Global,
416 IN UINTN Instance,
417 OUT CHAR16 *VariableData
418 );
419
420 /**
421 Gets the size of variable data area.
422
423 This function gets the size of variable data area.
424 The variable is specified by its variable header.
425 If variable header contains raw data, just return 0.
426
427 @param[in] Variable Pointer to the variable header.
428
429 @return Size of variable data area in bytes.
430
431 **/
432 UINTN
433 DataSizeOfVariable (
434 IN VARIABLE_HEADER *Variable
435 );
436
437 /**
438 Update the variable region with Variable information. These are the same
439 arguments as the EFI Variable services.
440
441 @param[in] VariableName Name of variable.
442 @param[in] VendorGuid Guid of variable.
443 @param[in] Data Variable data.
444 @param[in] DataSize Size of data. 0 means delete.
445 @param[in] Attributes Attributes of the variable.
446 @param[in] KeyIndex Index of associated public key.
447 @param[in] MonotonicCount Value of associated monotonic count.
448 @param[in] VirtualMode Current calling mode for this function.
449 @param[in] Global Context of this Extended SAL Variable Services Class call.
450 @param[in] Variable The variable information which is used to keep track of variable usage.
451
452 @retval EFI_SUCCESS The update operation is success.
453 @retval EFI_OUT_OF_RESOURCES Variable region is full, can not write other data into this region.
454
455 **/
456 EFI_STATUS
457 EFIAPI
458 UpdateVariable (
459 IN CHAR16 *VariableName,
460 IN EFI_GUID *VendorGuid,
461 IN VOID *Data,
462 IN UINTN DataSize,
463 IN UINT32 Attributes OPTIONAL,
464 IN UINT32 KeyIndex OPTIONAL,
465 IN UINT64 MonotonicCount OPTIONAL,
466 IN BOOLEAN VirtualMode,
467 IN ESAL_VARIABLE_GLOBAL *Global,
468 IN VARIABLE_POINTER_TRACK *Variable
469 );
470
471 /**
472 Checks variable header.
473
474 This function checks if variable header is valid or not.
475
476 @param[in] VariableAddress Start address of variable header.
477 @param[in] Volatile TRUE - Variable is volatile.
478 FALSE - Variable is non-volatile.
479 @param[in] Global Pointer to VARAIBLE_GLOBAL structure.
480 @param[in] Instance Instance of FV Block services.
481 @param[out] VariableHeader Pointer to VARIABLE_HEADER for output.
482
483 @retval TRUE Variable header is valid.
484 @retval FALSE Variable header is not valid.
485
486 **/
487 BOOLEAN
488 IsValidVariableHeader (
489 IN EFI_PHYSICAL_ADDRESS VariableAddress,
490 IN BOOLEAN Volatile,
491 IN VARIABLE_GLOBAL *Global,
492 IN UINTN Instance,
493 OUT VARIABLE_HEADER *VariableHeader OPTIONAL
494 );
495
496 #endif