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   This code gets the pointer to the variable data.
 200
 201   @param Variable        Pointer to the Variable Header.
 202
 203   @return Pointer to Variable Data.
 204
 205 **/
 206 UINT8 *
 207 GetVariableDataPtr (
 208   IN  VARIABLE_HEADER   *Variable
 209   );
 210
 211 /**
 212
 213   This code gets the size of variable data.
 214
 215   @param Variable        Pointer to the Variable Header.
 216
 217   @return Size of variable in bytes.
 218
 219 **/
 220 UINTN
 221 DataSizeOfVariable (
 222   IN  VARIABLE_HEADER   *Variable
 223   );
 224
 225 /**
 226   This function is to check if the remaining variable space is enough to set
 227   all Variables from argument list successfully. The purpose of the check
 228   is to keep the consistency of the Variables to be in variable storage.
 229
 230   Note: Variables are assumed to be in same storage.
 231   The set sequence of Variables will be same with the sequence of VariableEntry from argument list,
 232   so follow the argument sequence to check the Variables.
 233
 234   @param[in] Attributes         Variable attributes for Variable entries.
 235   @param ...                    The variable argument list with type VARIABLE_ENTRY_CONSISTENCY *.
 236                                 A NULL terminates the list. The VariableSize of
 237                                 VARIABLE_ENTRY_CONSISTENCY is the variable data size as input.
 238                                 It will be changed to variable total size as output.
 239
 240   @retval TRUE                  Have enough variable space to set the Variables successfully.
 241   @retval FALSE                 No enough variable space to set the Variables successfully.
 242
 243 **/
 244 BOOLEAN
 245 EFIAPI
 246 CheckRemainingSpaceForConsistency (
 247   IN UINT32                     Attributes,
 248   ...
 249   );
 250
 251 /**
 252   Update the variable region with Variable information. If EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS is set,
 253   index of associated public key is needed.
 254
 255   @param[in] VariableName       Name of variable.
 256   @param[in] VendorGuid         Guid of variable.
 257   @param[in] Data               Variable data.
 258   @param[in] DataSize           Size of data. 0 means delete.
 259   @param[in] Attributes         Attributes of the variable.
 260   @param[in] KeyIndex           Index of associated public key.
 261   @param[in] MonotonicCount     Value of associated monotonic count.
 262   @param[in, out] Variable      The variable information that is used to keep track of variable usage.
 263
 264   @param[in] TimeStamp          Value of associated TimeStamp.
 265
 266   @retval EFI_SUCCESS           The update operation is success.
 267   @retval EFI_OUT_OF_RESOURCES  Variable region is full, cannot write other data into this region.
 268
 269 **/
 270 EFI_STATUS
 271 UpdateVariable (
 272   IN      CHAR16          *VariableName,
 273   IN      EFI_GUID        *VendorGuid,
 274   IN      VOID            *Data,
 275   IN      UINTN           DataSize,
 276   IN      UINT32          Attributes OPTIONAL,
 277   IN      UINT32          KeyIndex  OPTIONAL,
 278   IN      UINT64          MonotonicCount  OPTIONAL,
 279   IN OUT  VARIABLE_POINTER_TRACK *Variable,
 280   IN      EFI_TIME        *TimeStamp  OPTIONAL
 281   );
 282
 283
 284 /**
 285   Return TRUE if ExitBootServices () has been called.
 286
 287   @retval TRUE If ExitBootServices () has been called.
 288 **/
 289 BOOLEAN
 290 AtRuntime (
 291   VOID
 292   );
 293
 294 /**
 295   Initializes a basic mutual exclusion lock.
 296
 297   This function initializes a basic mutual exclusion lock to the released state
 298   and returns the lock.  Each lock provides mutual exclusion access at its task
 299   priority level.  Since there is no preemption or multiprocessor support in EFI,
 300   acquiring the lock only consists of raising to the locks TPL.
 301   If Lock is NULL, then ASSERT().
 302   If Priority is not a valid TPL value, then ASSERT().
 303
 304   @param  Lock       A pointer to the lock data structure to initialize.
 305   @param  Priority   EFI TPL is associated with the lock.
 306
 307   @return The lock.
 308
 309 **/
 310 EFI_LOCK *
 311 InitializeLock (
 312   IN OUT EFI_LOCK  *Lock,
 313   IN EFI_TPL        Priority
 314   );
 315
 316
 317 /**
 318   Acquires lock only at boot time. Simply returns at runtime.
 319
 320   This is a temperary function that will be removed when
 321   EfiAcquireLock() in UefiLib can handle the call in UEFI
 322   Runtimer driver in RT phase.
 323   It calls EfiAcquireLock() at boot time, and simply returns
 324   at runtime.
 325
 326   @param  Lock         A pointer to the lock to acquire.
 327
 328 **/
 329 VOID
 330 AcquireLockOnlyAtBootTime (
 331   IN EFI_LOCK  *Lock
 332   );
 333
 334
 335 /**
 336   Releases lock only at boot time. Simply returns at runtime.
 337
 338   This is a temperary function which will be removed when
 339   EfiReleaseLock() in UefiLib can handle the call in UEFI
 340   Runtimer driver in RT phase.
 341   It calls EfiReleaseLock() at boot time and simply returns
 342   at runtime.
 343
 344   @param  Lock         A pointer to the lock to release.
 345
 346 **/
 347 VOID
 348 ReleaseLockOnlyAtBootTime (
 349   IN EFI_LOCK  *Lock
 350   );
 351
 352 /**
 353   Retrive the FVB protocol interface by HANDLE.
 354
 355   @param[in]  FvBlockHandle     The handle of FVB protocol that provides services for
 356                                 reading, writing, and erasing the target block.
 357   @param[out] FvBlock           The interface of FVB protocol
 358
 359   @retval EFI_SUCCESS           The interface information for the specified protocol was returned.
 360   @retval EFI_UNSUPPORTED       The device does not support the FVB protocol.
 361   @retval EFI_INVALID_PARAMETER FvBlockHandle is not a valid EFI_HANDLE or FvBlock is NULL.
 362
 363 **/
 364 EFI_STATUS
 365 GetFvbByHandle (
 366   IN  EFI_HANDLE                          FvBlockHandle,
 367   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvBlock
 368   );
 369
 370
 371 /**
 372   Retrive the Swap Address Range protocol interface.
 373
 374   @param[out] SarProtocol       The interface of SAR protocol
 375
 376   @retval EFI_SUCCESS           The SAR protocol instance was found and returned in SarProtocol.
 377   @retval EFI_NOT_FOUND         The SAR protocol instance was not found.
 378   @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
 379
 380 **/
 381 EFI_STATUS
 382 GetSarProtocol (
 383   OUT VOID                                **SarProtocol
 384   );
 385
 386 /**
 387   Function returns an array of handles that support the FVB protocol
 388   in a buffer allocated from pool.
 389
 390   @param[out]  NumberHandles    The number of handles returned in Buffer.
 391   @param[out]  Buffer           A pointer to the buffer to return the requested
 392                                 array of  handles that support FVB protocol.
 393
 394   @retval EFI_SUCCESS           The array of handles was returned in Buffer, and the number of
 395                                 handles in Buffer was returned in NumberHandles.
 396   @retval EFI_NOT_FOUND         No FVB handle was found.
 397   @retval EFI_OUT_OF_RESOURCES  There is not enough pool memory to store the matching results.
 398   @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
 399
 400 **/
 401 EFI_STATUS
 402 GetFvbCountAndBuffer (
 403   OUT UINTN                               *NumberHandles,
 404   OUT EFI_HANDLE                          **Buffer
 405   );
 406
 407 /**
 408   Initializes variable store area for non-volatile and volatile variable.
 409
 410   @retval EFI_SUCCESS           Function successfully executed.
 411   @retval EFI_OUT_OF_RESOURCES  Fail to allocate enough memory resource.
 412
 413 **/
 414 EFI_STATUS
 415 VariableCommonInitialize (
 416   VOID
 417   );
 418
 419 /**
 420
 421   Variable store garbage collection and reclaim operation.
 422
 423   If ReclaimPubKeyStore is FALSE, reclaim variable space by deleting the obsoleted varaibles.
 424   If ReclaimPubKeyStore is TRUE, reclaim invalid key in public key database and update the PubKeyIndex
 425   for all the count-based authenticate variable in NV storage.
 426
 427   @param[in]      VariableBase            Base address of variable store.
 428   @param[out]     LastVariableOffset      Offset of last variable.
 429   @param[in]      IsVolatile              The variable store is volatile or not;
 430                                           if it is non-volatile, need FTW.
 431   @param[in, out] UpdatingPtrTrack        Pointer to updating variable pointer track structure.
 432   @param[in]      NewVariable             Pointer to new variable.
 433   @param[in]      NewVariableSize         New variable size.
 434   @param[in]      ReclaimPubKeyStore      Reclaim for public key database or not.
 435
 436   @return EFI_SUCCESS                  Reclaim operation has finished successfully.
 437   @return EFI_OUT_OF_RESOURCES         No enough memory resources or variable space.
 438   @return EFI_DEVICE_ERROR             The public key database doesn't exist.
 439   @return Others                       Unexpect error happened during reclaim operation.
 440
 441 **/
 442 EFI_STATUS
 443 Reclaim (
 444   IN     EFI_PHYSICAL_ADDRESS         VariableBase,
 445   OUT    UINTN                        *LastVariableOffset,
 446   IN     BOOLEAN                      IsVolatile,
 447   IN OUT VARIABLE_POINTER_TRACK       *UpdatingPtrTrack,
 448   IN     VARIABLE_HEADER              *NewVariable,
 449   IN     UINTN                        NewVariableSize,
 450   IN     BOOLEAN                      ReclaimPubKeyStore
 451   );
 452
 453 /**
 454   This function reclaims variable storage if free size is below the threshold.
 455
 456 **/
 457 VOID
 458 ReclaimForOS(
 459   VOID
 460   );
 461
 462
 463 /**
 464   Initializes variable write service after FVB was ready.
 465
 466   @retval EFI_SUCCESS          Function successfully executed.
 467   @retval Others               Fail to initialize the variable service.
 468
 469 **/
 470 EFI_STATUS
 471 VariableWriteServiceInitialize (
 472   VOID
 473   );
 474
 475 /**
 476   Retrive the SMM Fault Tolerent Write protocol interface.
 477
 478   @param[out] FtwProtocol       The interface of SMM Ftw protocol
 479
 480   @retval EFI_SUCCESS           The SMM SAR protocol instance was found and returned in SarProtocol.
 481   @retval EFI_NOT_FOUND         The SMM SAR protocol instance was not found.
 482   @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
 483
 484 **/
 485 EFI_STATUS
 486 GetFtwProtocol (
 487   OUT VOID                                **FtwProtocol
 488   );
 489
 490 /**
 491   Get the proper fvb handle and/or fvb protocol by the given Flash address.
 492
 493   @param[in] Address        The Flash address.
 494   @param[out] FvbHandle     In output, if it is not NULL, it points to the proper FVB handle.
 495   @param[out] FvbProtocol   In output, if it is not NULL, it points to the proper FVB protocol.
 496
 497 **/
 498 EFI_STATUS
 499 GetFvbInfoByAddress (
 500   IN  EFI_PHYSICAL_ADDRESS                Address,
 501   OUT EFI_HANDLE                          *FvbHandle OPTIONAL,
 502   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvbProtocol OPTIONAL
 503   );
 504
 505 /**
 506
 507   This code finds variable in storage blocks (Volatile or Non-Volatile).
 508
 509   Caution: This function may receive untrusted input.
 510   This function may be invoked in SMM mode, and datasize and data are external input.
 511   This function will do basic validation, before parse the data.
 512
 513   @param VariableName               Name of Variable to be found.
 514   @param VendorGuid                 Variable vendor GUID.
 515   @param Attributes                 Attribute value of the variable found.
 516   @param DataSize                   Size of Data found. If size is less than the
 517                                     data, this value contains the required size.
 518   @param Data                       Data pointer.
 519
 520   @return EFI_INVALID_PARAMETER     Invalid parameter.
 521   @return EFI_SUCCESS               Find the specified variable.
 522   @return EFI_NOT_FOUND             Not found.
 523   @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.
 524
 525 **/
 526 EFI_STATUS
 527 EFIAPI
 528 VariableServiceGetVariable (
 529   IN      CHAR16            *VariableName,
 530   IN      EFI_GUID          *VendorGuid,
 531   OUT     UINT32            *Attributes OPTIONAL,
 532   IN OUT  UINTN             *DataSize,
 533   OUT     VOID              *Data
 534   );
 535
 536 /**
 537
 538   This code Finds the Next available variable.
 539
 540   Caution: This function may receive untrusted input.
 541   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 542
 543   @param VariableNameSize           Size of the variable name.
 544   @param VariableName               Pointer to variable name.
 545   @param VendorGuid                 Variable Vendor Guid.
 546
 547   @return EFI_INVALID_PARAMETER     Invalid parameter.
 548   @return EFI_SUCCESS               Find the specified variable.
 549   @return EFI_NOT_FOUND             Not found.
 550   @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.
 551
 552 **/
 553 EFI_STATUS
 554 EFIAPI
 555 VariableServiceGetNextVariableName (
 556   IN OUT  UINTN             *VariableNameSize,
 557   IN OUT  CHAR16            *VariableName,
 558   IN OUT  EFI_GUID          *VendorGuid
 559   );
 560
 561 /**
 562
 563   This code sets variable in storage blocks (Volatile or Non-Volatile).
 564
 565   Caution: This function may receive untrusted input.
 566   This function may be invoked in SMM mode, and datasize and data are external input.
 567   This function will do basic validation, before parse the data.
 568   This function will parse the authentication carefully to avoid security issues, like
 569   buffer overflow, integer overflow.
 570   This function will check attribute carefully to avoid authentication bypass.
 571
 572   @param VariableName                     Name of Variable to be found.
 573   @param VendorGuid                       Variable vendor GUID.
 574   @param Attributes                       Attribute value of the variable found
 575   @param DataSize                         Size of Data found. If size is less than the
 576                                           data, this value contains the required size.
 577   @param Data                             Data pointer.
 578
 579   @return EFI_INVALID_PARAMETER           Invalid parameter.
 580   @return EFI_SUCCESS                     Set successfully.
 581   @return EFI_OUT_OF_RESOURCES            Resource not enough to set variable.
 582   @return EFI_NOT_FOUND                   Not found.
 583   @return EFI_WRITE_PROTECTED             Variable is read-only.
 584
 585 **/
 586 EFI_STATUS
 587 EFIAPI
 588 VariableServiceSetVariable (
 589   IN CHAR16                  *VariableName,
 590   IN EFI_GUID                *VendorGuid,
 591   IN UINT32                  Attributes,
 592   IN UINTN                   DataSize,
 593   IN VOID                    *Data
 594   );
 595
 596 /**
 597
 598   This code returns information about the EFI variables.
 599
 600   Caution: This function may receive untrusted input.
 601   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 602
 603   @param Attributes                     Attributes bitmask to specify the type of variables
 604                                         on which to return information.
 605   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available
 606                                         for the EFI variables associated with the attributes specified.
 607   @param RemainingVariableStorageSize   Pointer to the remaining size of the storage space available
 608                                         for EFI variables associated with the attributes specified.
 609   @param MaximumVariableSize            Pointer to the maximum size of an individual EFI variables
 610                                         associated with the attributes specified.
 611
 612   @return EFI_SUCCESS                   Query successfully.
 613
 614 **/
 615 EFI_STATUS
 616 EFIAPI
 617 VariableServiceQueryVariableInfoInternal (
 618   IN  UINT32                 Attributes,
 619   OUT UINT64                 *MaximumVariableStorageSize,
 620   OUT UINT64                 *RemainingVariableStorageSize,
 621   OUT UINT64                 *MaximumVariableSize
 622   );
 623
 624 /**
 625
 626   This code returns information about the EFI variables.
 627
 628   Caution: This function may receive untrusted input.
 629   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 630
 631   @param Attributes                     Attributes bitmask to specify the type of variables
 632                                         on which to return information.
 633   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available
 634                                         for the EFI variables associated with the attributes specified.
 635   @param RemainingVariableStorageSize   Pointer to the remaining size of the storage space available
 636                                         for EFI variables associated with the attributes specified.
 637   @param MaximumVariableSize            Pointer to the maximum size of an individual EFI variables
 638                                         associated with the attributes specified.
 639
 640   @return EFI_INVALID_PARAMETER         An invalid combination of attribute bits was supplied.
 641   @return EFI_SUCCESS                   Query successfully.
 642   @return EFI_UNSUPPORTED               The attribute is not supported on this platform.
 643
 644 **/
 645 EFI_STATUS
 646 EFIAPI
 647 VariableServiceQueryVariableInfo (
 648   IN  UINT32                 Attributes,
 649   OUT UINT64                 *MaximumVariableStorageSize,
 650   OUT UINT64                 *RemainingVariableStorageSize,
 651   OUT UINT64                 *MaximumVariableSize
 652   );
 653
 654 /**
 655   Mark a variable that will become read-only after leaving the DXE phase of execution.
 656
 657   @param[in] This          The VARIABLE_LOCK_PROTOCOL instance.
 658   @param[in] VariableName  A pointer to the variable name that will be made read-only subsequently.
 659   @param[in] VendorGuid    A pointer to the vendor GUID that will be made read-only subsequently.
 660
 661   @retval EFI_SUCCESS           The variable specified by the VariableName and the VendorGuid was marked
 662                                 as pending to be read-only.
 663   @retval EFI_INVALID_PARAMETER VariableName or VendorGuid is NULL.
 664                                 Or VariableName is an empty string.
 665   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 666                                 already been signaled.
 667   @retval EFI_OUT_OF_RESOURCES  There is not enough resource to hold the lock request.
 668 **/
 669 EFI_STATUS
 670 EFIAPI
 671 VariableLockRequestToLock (
 672   IN CONST EDKII_VARIABLE_LOCK_PROTOCOL *This,
 673   IN       CHAR16                       *VariableName,
 674   IN       EFI_GUID                     *VendorGuid
 675   );
 676
 677 /**
 678   Check if a Unicode character is a hexadecimal character.
 679
 680   This function checks if a Unicode character is a
 681   hexadecimal character.  The valid hexadecimal character is
 682   L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
 683
 684
 685   @param Char           The character to check against.
 686
 687   @retval TRUE          If the Char is a hexadecmial character.
 688   @retval FALSE         If the Char is not a hexadecmial character.
 689
 690 **/
 691 BOOLEAN
 692 EFIAPI
 693 IsHexaDecimalDigitCharacter (
 694   IN CHAR16             Char
 695   );
 696
 697 /**
 698   Internal SetVariable check.
 699
 700   @param[in] VariableName       Name of Variable to set.
 701   @param[in] VendorGuid         Variable vendor GUID.
 702   @param[in] Attributes         Attribute value of the variable.
 703   @param[in] DataSize           Size of Data to set.
 704   @param[in] Data               Data pointer.
 705
 706   @retval EFI_SUCCESS           The SetVariable check result was success.
 707   @retval EFI_INVALID_PARAMETER An invalid combination of attribute bits, name, and GUID were supplied,
 708                                 or the DataSize exceeds the minimum or maximum allowed,
 709                                 or the Data value is not following UEFI spec for UEFI defined variables.
 710   @retval EFI_WRITE_PROTECTED   The variable in question is read-only.
 711   @retval Others                The return status from check handler.
 712
 713 **/
 714 EFI_STATUS
 715 EFIAPI
 716 InternalVarCheckSetVariableCheck (
 717   IN CHAR16     *VariableName,
 718   IN EFI_GUID   *VendorGuid,
 719   IN UINT32     Attributes,
 720   IN UINTN      DataSize,
 721   IN VOID       *Data
 722   );
 723
 724 /**
 725   Register SetVariable check handler.
 726
 727   @param[in] Handler            Pointer to check handler.
 728
 729   @retval EFI_SUCCESS           The SetVariable check handler was registered successfully.
 730   @retval EFI_INVALID_PARAMETER Handler is NULL.
 731   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 732                                 already been signaled.
 733   @retval EFI_OUT_OF_RESOURCES  There is not enough resource for the SetVariable check handler register request.
 734   @retval EFI_UNSUPPORTED       This interface is not implemented.
 735                                 For example, it is unsupported in VarCheck protocol if both VarCheck and SmmVarCheck protocols are present.
 736
 737 **/
 738 EFI_STATUS
 739 EFIAPI
 740 VarCheckRegisterSetVariableCheckHandler (
 741   IN VAR_CHECK_SET_VARIABLE_CHECK_HANDLER   Handler
 742   );
 743
 744 /**
 745   Internal variable property get.
 746
 747   @param[in]  Name              Pointer to the variable name.
 748   @param[in]  Guid              Pointer to the vendor GUID.
 749   @param[out] VariableProperty  Pointer to the output variable property.
 750
 751   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was got successfully.
 752   @retval EFI_NOT_FOUND         The property of variable specified by the Name and Guid was not found.
 753
 754 **/
 755 EFI_STATUS
 756 EFIAPI
 757 InternalVarCheckVariablePropertyGet (
 758   IN CHAR16                         *Name,
 759   IN EFI_GUID                       *Guid,
 760   OUT VAR_CHECK_VARIABLE_PROPERTY   *VariableProperty
 761   );
 762
 763 /**
 764   Variable property set.
 765
 766   @param[in] Name               Pointer to the variable name.
 767   @param[in] Guid               Pointer to the vendor GUID.
 768   @param[in] VariableProperty   Pointer to the input variable property.
 769
 770   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was set successfully.
 771   @retval EFI_INVALID_PARAMETER Name, Guid or VariableProperty is NULL, or Name is an empty string,
 772                                 or the fields of VariableProperty are not valid.
 773   @retval EFI_ACCESS_DENIED     EFI_END_OF_DXE_EVENT_GROUP_GUID or EFI_EVENT_GROUP_READY_TO_BOOT has
 774                                 already been signaled.
 775   @retval EFI_OUT_OF_RESOURCES  There is not enough resource for the variable property set request.
 776
 777 **/
 778 EFI_STATUS
 779 EFIAPI
 780 VarCheckVariablePropertySet (
 781   IN CHAR16                         *Name,
 782   IN EFI_GUID                       *Guid,
 783   IN VAR_CHECK_VARIABLE_PROPERTY    *VariableProperty
 784   );
 785
 786 /**
 787   Variable property get.
 788
 789   @param[in]  Name              Pointer to the variable name.
 790   @param[in]  Guid              Pointer to the vendor GUID.
 791   @param[out] VariableProperty  Pointer to the output variable property.
 792
 793   @retval EFI_SUCCESS           The property of variable specified by the Name and Guid was got successfully.
 794   @retval EFI_INVALID_PARAMETER Name, Guid or VariableProperty is NULL, or Name is an empty string.
 795   @retval EFI_NOT_FOUND         The property of variable specified by the Name and Guid was not found.
 796
 797 **/
 798 EFI_STATUS
 799 EFIAPI
 800 VarCheckVariablePropertyGet (
 801   IN CHAR16                         *Name,
 802   IN EFI_GUID                       *Guid,
 803   OUT VAR_CHECK_VARIABLE_PROPERTY   *VariableProperty
 804   );
 805
 806 /**
 807   Initialize variable quota.
 808
 809 **/
 810 VOID
 811 InitializeVariableQuota (
 812   VOID
 813   );
 814
 815 extern VARIABLE_MODULE_GLOBAL  *mVariableModuleGlobal;
 816
 817 #endif