SecurityPkg/VariableAuthenticated/RuntimeDxe/Variable.h

   1 /** @file
   2   The internal header file includes the common header files, defines
   3   internal structure and functions used by Variable modules.
   4
   5 Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _VARIABLE_H_
  17 #define _VARIABLE_H_
  18
  19 #include <PiDxe.h>
  20 #include <Protocol/VariableWrite.h>
  21 #include <Protocol/FaultTolerantWrite.h>
  22 #include <Protocol/FirmwareVolumeBlock.h>
  23 #include <Protocol/Variable.h>
  24 #include <Protocol/VariableLock.h>
  25 #include <Protocol/VarCheck.h>
  26 #include <Library/PcdLib.h>
  27 #include <Library/HobLib.h>
  28 #include <Library/UefiDriverEntryPoint.h>
  29 #include <Library/DxeServicesTableLib.h>
  30 #include <Library/UefiRuntimeLib.h>
  31 #include <Library/DebugLib.h>
  32 #include <Library/BaseMemoryLib.h>
  33 #include <Library/UefiBootServicesTableLib.h>
  34 #include <Library/UefiLib.h>
  35 #include <Library/BaseLib.h>
  36 #include <Library/SynchronizationLib.h>
  37 #include <Library/MemoryAllocationLib.h>
  38 #include <Library/BaseCryptLib.h>
  39 #include <Library/PlatformSecureLib.h>
  40 #include <Guid/GlobalVariable.h>
  41 #include <Guid/EventGroup.h>
  42 #include <Guid/AuthenticatedVariableFormat.h>
  43 #include <Guid/ImageAuthentication.h>
  44 #include <Guid/SystemNvDataGuid.h>
  45 #include <Guid/FaultTolerantWrite.h>
  46 #include <Guid/HardwareErrorVariable.h>
  47 #include <Guid/VarErrorFlag.h>
  48
  49 #define EFI_VARIABLE_ATTRIBUTES_MASK (EFI_VARIABLE_NON_VOLATILE | \
  50                                       EFI_VARIABLE_BOOTSERVICE_ACCESS | \
  51                                       EFI_VARIABLE_RUNTIME_ACCESS | \
  52                                       EFI_VARIABLE_HARDWARE_ERROR_RECORD | \
  53                                       EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS | \
  54                                       EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS | \
  55                                       EFI_VARIABLE_APPEND_WRITE)
  56
  57 #define VARIABLE_ATTRIBUTE_NV_BS        (EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_BOOTSERVICE_ACCESS)
  58 #define VARIABLE_ATTRIBUTE_BS_RT        (EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS)
  59 #define VARIABLE_ATTRIBUTE_NV_BS_RT     (VARIABLE_ATTRIBUTE_BS_RT | EFI_VARIABLE_NON_VOLATILE)
  60 #define VARIABLE_ATTRIBUTE_NV_BS_RT_AT  (VARIABLE_ATTRIBUTE_NV_BS_RT | EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS)
  61 #define VARIABLE_ATTRIBUTE_NV_BS_RT_HR  (VARIABLE_ATTRIBUTE_NV_BS_RT | EFI_VARIABLE_HARDWARE_ERROR_RECORD)
  62 #define VARIABLE_ATTRIBUTE_NV_BS_RT_AW  (VARIABLE_ATTRIBUTE_NV_BS_RT | EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS)
  63 #define VARIABLE_ATTRIBUTE_NV_BS_RT_AT_HR_AW  (VARIABLE_ATTRIBUTE_NV_BS_RT_AT | EFI_VARIABLE_HARDWARE_ERROR_RECORD | EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS)
  64
  65 ///
  66 /// The size of a 3 character ISO639 language code.
  67 ///
  68 #define ISO_639_2_ENTRY_SIZE    3
  69
  70 typedef enum {
  71   VariableStoreTypeVolatile,
  72   VariableStoreTypeHob,
  73   VariableStoreTypeNv,
  74   VariableStoreTypeMax
  75 } VARIABLE_STORE_TYPE;
  76
  77 typedef struct {
  78   VARIABLE_HEADER *CurrPtr;
  79   //
  80   // If both ADDED and IN_DELETED_TRANSITION variable are present,
  81   // InDeletedTransitionPtr will point to the IN_DELETED_TRANSITION one.
  82   // Otherwise, CurrPtr will point to the ADDED or IN_DELETED_TRANSITION one,
  83   // and InDeletedTransitionPtr will be NULL at the same time.
  84   //
  85   VARIABLE_HEADER *InDeletedTransitionPtr;
  86   VARIABLE_HEADER *EndPtr;
  87   VARIABLE_HEADER *StartPtr;
  88   BOOLEAN         Volatile;
  89 } VARIABLE_POINTER_TRACK;
  90
  91 typedef struct {
  92   EFI_PHYSICAL_ADDRESS  HobVariableBase;
  93   EFI_PHYSICAL_ADDRESS  VolatileVariableBase;
  94   EFI_PHYSICAL_ADDRESS  NonVolatileVariableBase;
  95   EFI_LOCK              VariableServicesLock;
  96   UINT32                ReentrantState;
  97 } VARIABLE_GLOBAL;
  98
  99 typedef struct {
 100   VARIABLE_GLOBAL VariableGlobal;
 101   UINTN           VolatileLastVariableOffset;
 102   UINTN           NonVolatileLastVariableOffset;
 103   UINTN           CommonVariableSpace;
 104   UINTN           CommonMaxUserVariableSpace;
 105   UINTN           CommonRuntimeVariableSpace;
 106   UINTN           CommonVariableTotalSize;
 107   UINTN           CommonUserVariableTotalSize;
 108   UINTN           HwErrVariableTotalSize;
 109   CHAR8           *PlatformLangCodes;
 110   CHAR8           *LangCodes;
 111   CHAR8           *PlatformLang;
 112   CHAR8           Lang[ISO_639_2_ENTRY_SIZE + 1];
 113   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvbInstance;
 114 } VARIABLE_MODULE_GLOBAL;
 115
 116 typedef struct {
 117   EFI_GUID    *Guid;
 118   CHAR16      *Name;
 119   UINTN       VariableSize;
 120 } VARIABLE_ENTRY_CONSISTENCY;
 121
 122 typedef struct {
 123   LIST_ENTRY  Link;
 124   EFI_GUID    Guid;
 125   //CHAR16      *Name;
 126 } VARIABLE_ENTRY;
 127
 128 /**
 129   Flush the HOB variable to flash.
 130
 131   @param[in] VariableName       Name of variable has been updated or deleted.
 132   @param[in] VendorGuid         Guid of variable has been updated or deleted.
 133
 134 **/
 135 VOID
 136 FlushHobVariableToFlash (
 137   IN CHAR16                     *VariableName,
 138   IN EFI_GUID                   *VendorGuid
 139   );
 140
 141 /**
 142   Writes a buffer to variable storage space, in the working block.
 143
 144   This function writes a buffer to variable storage space into a firmware
 145   volume block device. The destination is specified by the parameter
 146   VariableBase. Fault Tolerant Write protocol is used for writing.
 147
 148   @param  VariableBase   Base address of the variable to write.
 149   @param  VariableBuffer Point to the variable data buffer.
 150
 151   @retval EFI_SUCCESS    The function completed successfully.
 152   @retval EFI_NOT_FOUND  Fail to locate Fault Tolerant Write protocol.
 153   @retval EFI_ABORTED    The function could not complete successfully.
 154
 155 **/
 156 EFI_STATUS
 157 FtwVariableSpace (
 158   IN EFI_PHYSICAL_ADDRESS   VariableBase,
 159   IN VARIABLE_STORE_HEADER  *VariableBuffer
 160   );
 161
 162 /**
 163   Finds variable in storage blocks of volatile and non-volatile storage areas.
 164
 165   This code finds variable in storage blocks of volatile and non-volatile storage areas.
 166   If VariableName is an empty string, then we just return the first
 167   qualified variable without comparing VariableName and VendorGuid.
 168   If IgnoreRtCheck is TRUE, then we ignore the EFI_VARIABLE_RUNTIME_ACCESS attribute check
 169   at runtime when searching existing variable, only VariableName and VendorGuid are compared.
 170   Otherwise, variables without EFI_VARIABLE_RUNTIME_ACCESS are not visible at runtime.
 171
 172   @param[in]   VariableName           Name of the variable to be found.
 173   @param[in]   VendorGuid             Vendor GUID to be found.
 174   @param[out]  PtrTrack               VARIABLE_POINTER_TRACK structure for output,
 175                                       including the range searched and the target position.
 176   @param[in]   Global                 Pointer to VARIABLE_GLOBAL structure, including
 177                                       base of volatile variable storage area, base of
 178                                       NV variable storage area, and a lock.
 179   @param[in]   IgnoreRtCheck          Ignore EFI_VARIABLE_RUNTIME_ACCESS attribute
 180                                       check at runtime when searching variable.
 181
 182   @retval EFI_INVALID_PARAMETER       If VariableName is not an empty string, while
 183                                       VendorGuid is NULL.
 184   @retval EFI_SUCCESS                 Variable successfully found.
 185   @retval EFI_NOT_FOUND               Variable not found
 186
 187 **/
 188 EFI_STATUS
 189 FindVariable (
 190   IN  CHAR16                  *VariableName,
 191   IN  EFI_GUID                *VendorGuid,
 192   OUT VARIABLE_POINTER_TRACK  *PtrTrack,
 193   IN  VARIABLE_GLOBAL         *Global,
 194   IN  BOOLEAN                 IgnoreRtCheck
 195   );
 196
 197 /**
 198
 199   Gets the pointer to the end of the variable storage area.
 200
 201   This function gets pointer to the end of the variable storage
 202   area, according to the input variable store header.
 203
 204   @param VarStoreHeader  Pointer to the Variable Store Header.
 205
 206   @return Pointer to the end of the variable storage area.
 207
 208 **/
 209 VARIABLE_HEADER *
 210 GetEndPointer (
 211   IN VARIABLE_STORE_HEADER       *VarStoreHeader
 212   );
 213
 214 /**
 215
 216   This code gets the pointer to the variable data.
 217
 218   @param Variable        Pointer to the Variable Header.
 219
 220   @return Pointer to Variable Data.
 221
 222 **/
 223 UINT8 *
 224 GetVariableDataPtr (
 225   IN  VARIABLE_HEADER   *Variable
 226   );
 227
 228 /**
 229
 230   This code gets the size of variable data.
 231
 232   @param Variable        Pointer to the Variable Header.
 233
 234   @return Size of variable in bytes.
 235
 236 **/
 237 UINTN
 238 DataSizeOfVariable (
 239   IN  VARIABLE_HEADER   *Variable
 240   );
 241
 242 /**
 243   This function is to check if the remaining variable space is enough to set
 244   all Variables from argument list successfully. The purpose of the check
 245   is to keep the consistency of the Variables to be in variable storage.
 246
 247   Note: Variables are assumed to be in same storage.
 248   The set sequence of Variables will be same with the sequence of VariableEntry from argument list,
 249   so follow the argument sequence to check the Variables.
 250
 251   @param[in] Attributes         Variable attributes for Variable entries.
 252   @param ...                    The variable argument list with type VARIABLE_ENTRY_CONSISTENCY *.
 253                                 A NULL terminates the list. The VariableSize of
 254                                 VARIABLE_ENTRY_CONSISTENCY is the variable data size as input.
 255                                 It will be changed to variable total size as output.
 256
 257   @retval TRUE                  Have enough variable space to set the Variables successfully.
 258   @retval FALSE                 No enough variable space to set the Variables successfully.
 259
 260 **/
 261 BOOLEAN
 262 EFIAPI
 263 CheckRemainingSpaceForConsistency (
 264   IN UINT32                     Attributes,
 265   ...
 266   );
 267
 268 /**
 269   Update the variable region with Variable information. If EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS is set,
 270   index of associated public key is needed.
 271
 272   @param[in] VariableName       Name of variable.
 273   @param[in] VendorGuid         Guid of variable.
 274   @param[in] Data               Variable data.
 275   @param[in] DataSize           Size of data. 0 means delete.
 276   @param[in] Attributes         Attributes of the variable.
 277   @param[in] KeyIndex           Index of associated public key.
 278   @param[in] MonotonicCount     Value of associated monotonic count.
 279   @param[in, out] Variable      The variable information that is used to keep track of variable usage.
 280
 281   @param[in] TimeStamp          Value of associated TimeStamp.
 282
 283   @retval EFI_SUCCESS           The update operation is success.
 284   @retval EFI_OUT_OF_RESOURCES  Variable region is full, cannot write other data into this region.
 285
 286 **/
 287 EFI_STATUS
 288 UpdateVariable (
 289   IN      CHAR16          *VariableName,
 290   IN      EFI_GUID        *VendorGuid,
 291   IN      VOID            *Data,
 292   IN      UINTN           DataSize,
 293   IN      UINT32          Attributes OPTIONAL,
 294   IN      UINT32          KeyIndex  OPTIONAL,
 295   IN      UINT64          MonotonicCount  OPTIONAL,
 296   IN OUT  VARIABLE_POINTER_TRACK *Variable,
 297   IN      EFI_TIME        *TimeStamp  OPTIONAL
 298   );
 299
 300
 301 /**
 302   Return TRUE if ExitBootServices () has been called.
 303
 304   @retval TRUE If ExitBootServices () has been called.
 305 **/
 306 BOOLEAN
 307 AtRuntime (
 308   VOID
 309   );
 310
 311 /**
 312   Initializes a basic mutual exclusion lock.
 313
 314   This function initializes a basic mutual exclusion lock to the released state
 315   and returns the lock.  Each lock provides mutual exclusion access at its task
 316   priority level.  Since there is no preemption or multiprocessor support in EFI,
 317   acquiring the lock only consists of raising to the locks TPL.
 318   If Lock is NULL, then ASSERT().
 319   If Priority is not a valid TPL value, then ASSERT().
 320
 321   @param  Lock       A pointer to the lock data structure to initialize.
 322   @param  Priority   EFI TPL is associated with the lock.
 323
 324   @return The lock.
 325
 326 **/
 327 EFI_LOCK *
 328 InitializeLock (
 329   IN OUT EFI_LOCK  *Lock,
 330   IN EFI_TPL        Priority
 331   );
 332
 333
 334 /**
 335   Acquires lock only at boot time. Simply returns at runtime.
 336
 337   This is a temperary function that will be removed when
 338   EfiAcquireLock() in UefiLib can handle the call in UEFI
 339   Runtimer driver in RT phase.
 340   It calls EfiAcquireLock() at boot time, and simply returns
 341   at runtime.
 342
 343   @param  Lock         A pointer to the lock to acquire.
 344
 345 **/
 346 VOID
 347 AcquireLockOnlyAtBootTime (
 348   IN EFI_LOCK  *Lock
 349   );
 350
 351
 352 /**
 353   Releases lock only at boot time. Simply returns at runtime.
 354
 355   This is a temperary function which will be removed when
 356   EfiReleaseLock() in UefiLib can handle the call in UEFI
 357   Runtimer driver in RT phase.
 358   It calls EfiReleaseLock() at boot time and simply returns
 359   at runtime.
 360
 361   @param  Lock         A pointer to the lock to release.
 362
 363 **/
 364 VOID
 365 ReleaseLockOnlyAtBootTime (
 366   IN EFI_LOCK  *Lock
 367   );
 368
 369 /**
 370   Retrive the FVB protocol interface by HANDLE.
 371
 372   @param[in]  FvBlockHandle     The handle of FVB protocol that provides services for
 373                                 reading, writing, and erasing the target block.
 374   @param[out] FvBlock           The interface of FVB protocol
 375
 376   @retval EFI_SUCCESS           The interface information for the specified protocol was returned.
 377   @retval EFI_UNSUPPORTED       The device does not support the FVB protocol.
 378   @retval EFI_INVALID_PARAMETER FvBlockHandle is not a valid EFI_HANDLE or FvBlock is NULL.
 379
 380 **/
 381 EFI_STATUS
 382 GetFvbByHandle (
 383   IN  EFI_HANDLE                          FvBlockHandle,
 384   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvBlock
 385   );
 386
 387
 388 /**
 389   Retrive the Swap Address Range protocol interface.
 390
 391   @param[out] SarProtocol       The interface of SAR protocol
 392
 393   @retval EFI_SUCCESS           The SAR protocol instance was found and returned in SarProtocol.
 394   @retval EFI_NOT_FOUND         The SAR protocol instance was not found.
 395   @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
 396
 397 **/
 398 EFI_STATUS
 399 GetSarProtocol (
 400   OUT VOID                                **SarProtocol
 401   );
 402
 403 /**
 404   Function returns an array of handles that support the FVB protocol
 405   in a buffer allocated from pool.
 406
 407   @param[out]  NumberHandles    The number of handles returned in Buffer.
 408   @param[out]  Buffer           A pointer to the buffer to return the requested
 409                                 array of  handles that support FVB protocol.
 410
 411   @retval EFI_SUCCESS           The array of handles was returned in Buffer, and the number of
 412                                 handles in Buffer was returned in NumberHandles.
 413   @retval EFI_NOT_FOUND         No FVB handle was found.
 414   @retval EFI_OUT_OF_RESOURCES  There is not enough pool memory to store the matching results.
 415   @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
 416
 417 **/
 418 EFI_STATUS
 419 GetFvbCountAndBuffer (
 420   OUT UINTN                               *NumberHandles,
 421   OUT EFI_HANDLE                          **Buffer
 422   );
 423
 424 /**
 425   Initializes variable store area for non-volatile and volatile variable.
 426
 427   @retval EFI_SUCCESS           Function successfully executed.
 428   @retval EFI_OUT_OF_RESOURCES  Fail to allocate enough memory resource.
 429
 430 **/
 431 EFI_STATUS
 432 VariableCommonInitialize (
 433   VOID
 434   );
 435
 436 /**
 437
 438   Variable store garbage collection and reclaim operation.
 439
 440   If ReclaimPubKeyStore is FALSE, reclaim variable space by deleting the obsoleted varaibles.
 441   If ReclaimPubKeyStore is TRUE, reclaim invalid key in public key database and update the PubKeyIndex
 442   for all the count-based authenticate variable in NV storage.
 443
 444   @param[in]      VariableBase            Base address of variable store.
 445   @param[out]     LastVariableOffset      Offset of last variable.
 446   @param[in]      IsVolatile              The variable store is volatile or not;
 447                                           if it is non-volatile, need FTW.
 448   @param[in, out] UpdatingPtrTrack        Pointer to updating variable pointer track structure.
 449   @param[in]      NewVariable             Pointer to new variable.
 450   @param[in]      NewVariableSize         New variable size.
 451   @param[in]      ReclaimPubKeyStore      Reclaim for public key database or not.
 452
 453   @return EFI_SUCCESS                  Reclaim operation has finished successfully.
 454   @return EFI_OUT_OF_RESOURCES         No enough memory resources or variable space.
 455   @return EFI_DEVICE_ERROR             The public key database doesn't exist.
 456   @return Others                       Unexpect error happened during reclaim operation.
 457
 458 **/
 459 EFI_STATUS
 460 Reclaim (
 461   IN     EFI_PHYSICAL_ADDRESS         VariableBase,
 462   OUT    UINTN                        *LastVariableOffset,
 463   IN     BOOLEAN                      IsVolatile,
 464   IN OUT VARIABLE_POINTER_TRACK       *UpdatingPtrTrack,
 465   IN     VARIABLE_HEADER              *NewVariable,
 466   IN     UINTN                        NewVariableSize,
 467   IN     BOOLEAN                      ReclaimPubKeyStore
 468   );
 469
 470 /**
 471   This function reclaims variable storage if free size is below the threshold.
 472
 473 **/
 474 VOID
 475 ReclaimForOS(
 476   VOID
 477   );
 478
 479
 480 /**
 481   Initializes variable write service after FVB was ready.
 482
 483   @retval EFI_SUCCESS          Function successfully executed.
 484   @retval Others               Fail to initialize the variable service.
 485
 486 **/
 487 EFI_STATUS
 488 VariableWriteServiceInitialize (
 489   VOID
 490   );
 491
 492 /**
 493   Retrive the SMM Fault Tolerent Write protocol interface.
 494
 495   @param[out] FtwProtocol       The interface of SMM Ftw protocol
 496
 497   @retval EFI_SUCCESS           The SMM SAR protocol instance was found and returned in SarProtocol.
 498   @retval EFI_NOT_FOUND         The SMM SAR protocol instance was not found.
 499   @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
 500
 501 **/
 502 EFI_STATUS
 503 GetFtwProtocol (
 504   OUT VOID                                **FtwProtocol
 505   );
 506
 507 /**
 508   Get the proper fvb handle and/or fvb protocol by the given Flash address.
 509
 510   @param[in] Address        The Flash address.
 511   @param[out] FvbHandle     In output, if it is not NULL, it points to the proper FVB handle.
 512   @param[out] FvbProtocol   In output, if it is not NULL, it points to the proper FVB protocol.
 513
 514 **/
 515 EFI_STATUS
 516 GetFvbInfoByAddress (
 517   IN  EFI_PHYSICAL_ADDRESS                Address,
 518   OUT EFI_HANDLE                          *FvbHandle OPTIONAL,
 519   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvbProtocol OPTIONAL
 520   );
 521
 522 /**
 523
 524   This code finds variable in storage blocks (Volatile or Non-Volatile).
 525
 526   Caution: This function may receive untrusted input.
 527   This function may be invoked in SMM mode, and datasize and data are external input.
 528   This function will do basic validation, before parse the data.
 529
 530   @param VariableName               Name of Variable to be found.
 531   @param VendorGuid                 Variable vendor GUID.
 532   @param Attributes                 Attribute value of the variable found.
 533   @param DataSize                   Size of Data found. If size is less than the
 534                                     data, this value contains the required size.
 535   @param Data                       Data pointer.
 536
 537   @return EFI_INVALID_PARAMETER     Invalid parameter.
 538   @return EFI_SUCCESS               Find the specified variable.
 539   @return EFI_NOT_FOUND             Not found.
 540   @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.
 541
 542 **/
 543 EFI_STATUS
 544 EFIAPI
 545 VariableServiceGetVariable (
 546   IN      CHAR16            *VariableName,
 547   IN      EFI_GUID          *VendorGuid,
 548   OUT     UINT32            *Attributes OPTIONAL,
 549   IN OUT  UINTN             *DataSize,
 550   OUT     VOID              *Data
 551   );
 552
 553 /**
 554
 555   This code Finds the Next available variable.
 556
 557   Caution: This function may receive untrusted input.
 558   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 559
 560   @param VariableNameSize           Size of the variable name.
 561   @param VariableName               Pointer to variable name.
 562   @param VendorGuid                 Variable Vendor Guid.
 563
 564   @return EFI_INVALID_PARAMETER     Invalid parameter.
 565   @return EFI_SUCCESS               Find the specified variable.
 566   @return EFI_NOT_FOUND             Not found.
 567   @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.
 568
 569 **/
 570 EFI_STATUS
 571 EFIAPI
 572 VariableServiceGetNextVariableName (
 573   IN OUT  UINTN             *VariableNameSize,
 574   IN OUT  CHAR16            *VariableName,
 575   IN OUT  EFI_GUID          *VendorGuid
 576   );
 577
 578 /**
 579
 580   This code sets variable in storage blocks (Volatile or Non-Volatile).
 581
 582   Caution: This function may receive untrusted input.
 583   This function may be invoked in SMM mode, and datasize and data are external input.
 584   This function will do basic validation, before parse the data.
 585   This function will parse the authentication carefully to avoid security issues, like
 586   buffer overflow, integer overflow.
 587   This function will check attribute carefully to avoid authentication bypass.
 588
 589   @param VariableName                     Name of Variable to be found.
 590   @param VendorGuid                       Variable vendor GUID.
 591   @param Attributes                       Attribute value of the variable found
 592   @param DataSize                         Size of Data found. If size is less than the
 593                                           data, this value contains the required size.
 594   @param Data                             Data pointer.
 595
 596   @return EFI_INVALID_PARAMETER           Invalid parameter.
 597   @return EFI_SUCCESS                     Set successfully.
 598   @return EFI_OUT_OF_RESOURCES            Resource not enough to set variable.
 599   @return EFI_NOT_FOUND                   Not found.
 600   @return EFI_WRITE_PROTECTED             Variable is read-only.
 601
 602 **/
 603 EFI_STATUS
 604 EFIAPI
 605 VariableServiceSetVariable (
 606   IN CHAR16                  *VariableName,
 607   IN EFI_GUID                *VendorGuid,
 608   IN UINT32                  Attributes,
 609   IN UINTN                   DataSize,
 610   IN VOID                    *Data
 611   );
 612
 613 /**
 614
 615   This code returns information about the EFI variables.
 616
 617   Caution: This function may receive untrusted input.
 618   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 619
 620   @param Attributes                     Attributes bitmask to specify the type of variables
 621                                         on which to return information.
 622   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available
 623                                         for the EFI variables associated with the attributes specified.
 624   @param RemainingVariableStorageSize   Pointer to the remaining size of the storage space available
 625                                         for EFI variables associated with the attributes specified.
 626   @param MaximumVariableSize            Pointer to the maximum size of an individual EFI variables
 627                                         associated with the attributes specified.
 628
 629   @return EFI_SUCCESS                   Query successfully.
 630
 631 **/
 632 EFI_STATUS
 633 EFIAPI
 634 VariableServiceQueryVariableInfoInternal (
 635   IN  UINT32                 Attributes,
 636   OUT UINT64                 *MaximumVariableStorageSize,
 637   OUT UINT64                 *RemainingVariableStorageSize,
 638   OUT UINT64                 *MaximumVariableSize
 639   );
 640
 641 /**
 642
 643   This code returns information about the EFI variables.
 644
 645   Caution: This function may receive untrusted input.
 646   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 647
 648   @param Attributes                     Attributes bitmask to specify the type of variables
 649                                         on which to return information.
 650   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available
 651                                         for the EFI variables associated with the attributes specified.
 652   @param RemainingVariableStorageSize   Pointer to the remaining size of the storage space available
 653                                         for EFI variables associated with the attributes specified.
 654   @param MaximumVariableSize            Pointer to the maximum size of an individual EFI variables
 655                                         associated with the attributes specified.
 656
 657   @return EFI_INVALID_PARAMETER         An invalid combination of attribute bits was supplied.
 658   @return EFI_SUCCESS                   Query successfully.
 659   @return EFI_UNSUPPORTED               The attribute is not supported on this platform.
 660
 661 **/
 662 EFI_STATUS
 663 EFIAPI
 664 VariableServiceQueryVariableInfo (
 665   IN  UINT32                 Attributes,
 666   OUT UINT64                 *MaximumVariableStorageSize,
 667   OUT UINT64                 *RemainingVariableStorageSize,
 668   OUT UINT64                 *MaximumVariableSize
 669   );
 670
 671 /**
 672   Mark a variable that will become read-only after leaving the DXE phase of execution.
 673
 674   @param[in] This          The VARIABLE_LOCK_PROTOCOL instance.
 675   @param[in] VariableName  A pointer to the variable name that will be made read-only subsequently.
 676   @param[in] VendorGuid    A pointer to the vendor GUID that will be made read-only subsequently.
 677
 678   @retval EFI_SUCCESS           The variable specified by the VariableName and the VendorGuid was marked
 679                                 as pending to be read-only.
 680   @retval EFI_INVALID_PARAMETER VariableName or VendorGuid is NULL.
 681                                 Or VariableName is an empty string.
 682   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 683                                 already been signaled.
 684   @retval EFI_OUT_OF_RESOURCES  There is not enough resource to hold the lock request.
 685 **/
 686 EFI_STATUS
 687 EFIAPI
 688 VariableLockRequestToLock (
 689   IN CONST EDKII_VARIABLE_LOCK_PROTOCOL *This,
 690   IN       CHAR16                       *VariableName,
 691   IN       EFI_GUID                     *VendorGuid
 692   );
 693
 694 /**
 695   Check if a Unicode character is a hexadecimal character.
 696
 697   This function checks if a Unicode character is a
 698   hexadecimal character.  The valid hexadecimal character is
 699   L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
 700
 701
 702   @param Char           The character to check against.
 703
 704   @retval TRUE          If the Char is a hexadecmial character.
 705   @retval FALSE         If the Char is not a hexadecmial character.
 706
 707 **/
 708 BOOLEAN
 709 EFIAPI
 710 IsHexaDecimalDigitCharacter (
 711   IN CHAR16             Char
 712   );
 713
 714 /**
 715   Internal SetVariable check.
 716
 717   @param[in] VariableName       Name of Variable to set.
 718   @param[in] VendorGuid         Variable vendor GUID.
 719   @param[in] Attributes         Attribute value of the variable.
 720   @param[in] DataSize           Size of Data to set.
 721   @param[in] Data               Data pointer.
 722
 723   @retval EFI_SUCCESS           The SetVariable check result was success.
 724   @retval EFI_INVALID_PARAMETER An invalid combination of attribute bits, name, and GUID were supplied,
 725                                 or the DataSize exceeds the minimum or maximum allowed,
 726                                 or the Data value is not following UEFI spec for UEFI defined variables.
 727   @retval EFI_WRITE_PROTECTED   The variable in question is read-only.
 728   @retval Others                The return status from check handler.
 729
 730 **/
 731 EFI_STATUS
 732 EFIAPI
 733 InternalVarCheckSetVariableCheck (
 734   IN CHAR16     *VariableName,
 735   IN EFI_GUID   *VendorGuid,
 736   IN UINT32     Attributes,
 737   IN UINTN      DataSize,
 738   IN VOID       *Data
 739   );
 740
 741 /**
 742   Register SetVariable check handler.
 743
 744   @param[in] Handler            Pointer to check handler.
 745
 746   @retval EFI_SUCCESS           The SetVariable check handler was registered successfully.
 747   @retval EFI_INVALID_PARAMETER Handler is NULL.
 748   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 749                                 already been signaled.
 750   @retval EFI_OUT_OF_RESOURCES  There is not enough resource for the SetVariable check handler register request.
 751   @retval EFI_UNSUPPORTED       This interface is not implemented.
 752                                 For example, it is unsupported in VarCheck protocol if both VarCheck and SmmVarCheck protocols are present.
 753
 754 **/
 755 EFI_STATUS
 756 EFIAPI
 757 VarCheckRegisterSetVariableCheckHandler (
 758   IN VAR_CHECK_SET_VARIABLE_CHECK_HANDLER   Handler
 759   );
 760
 761 /**
 762   Internal variable property get.
 763
 764   @param[in]  Name              Pointer to the variable name.
 765   @param[in]  Guid              Pointer to the vendor GUID.
 766   @param[out] VariableProperty  Pointer to the output variable property.
 767
 768   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was got successfully.
 769   @retval EFI_NOT_FOUND         The property of variable specified by the Name and Guid was not found.
 770
 771 **/
 772 EFI_STATUS
 773 EFIAPI
 774 InternalVarCheckVariablePropertyGet (
 775   IN CHAR16                         *Name,
 776   IN EFI_GUID                       *Guid,
 777   OUT VAR_CHECK_VARIABLE_PROPERTY   *VariableProperty
 778   );
 779
 780 /**
 781   Variable property set.
 782
 783   @param[in] Name               Pointer to the variable name.
 784   @param[in] Guid               Pointer to the vendor GUID.
 785   @param[in] VariableProperty   Pointer to the input variable property.
 786
 787   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was set successfully.
 788   @retval EFI_INVALID_PARAMETER Name, Guid or VariableProperty is NULL, or Name is an empty string,
 789                                 or the fields of VariableProperty are not valid.
 790   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 791                                 already been signaled.
 792   @retval EFI_OUT_OF_RESOURCES  There is not enough resource for the variable property set request.
 793
 794 **/
 795 EFI_STATUS
 796 EFIAPI
 797 VarCheckVariablePropertySet (
 798   IN CHAR16                         *Name,
 799   IN EFI_GUID                       *Guid,
 800   IN VAR_CHECK_VARIABLE_PROPERTY    *VariableProperty
 801   );
 802
 803 /**
 804   Variable property get.
 805
 806   @param[in]  Name              Pointer to the variable name.
 807   @param[in]  Guid              Pointer to the vendor GUID.
 808   @param[out] VariableProperty  Pointer to the output variable property.
 809
 810   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was got successfully.
 811   @retval EFI_INVALID_PARAMETER Name, Guid or VariableProperty is NULL, or Name is an empty string.
 812   @retval EFI_NOT_FOUND         The property of variable specified by the Name and Guid was not found.
 813
 814 **/
 815 EFI_STATUS
 816 EFIAPI
 817 VarCheckVariablePropertyGet (
 818   IN CHAR16                         *Name,
 819   IN EFI_GUID                       *Guid,
 820   OUT VAR_CHECK_VARIABLE_PROPERTY   *VariableProperty
 821   );
 822
 823 /**
 824   Initialize variable quota.
 825
 826 **/
 827 VOID
 828 InitializeVariableQuota (
 829   VOID
 830   );
 831
 832 extern VARIABLE_MODULE_GLOBAL  *mVariableModuleGlobal;
 833
 834 #endif