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