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 - 2013, 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 <Library/PcdLib.h>
  25 #include <Library/HobLib.h>
  26 #include <Library/UefiDriverEntryPoint.h>
  27 #include <Library/DxeServicesTableLib.h>
  28 #include <Library/UefiRuntimeLib.h>
  29 #include <Library/DebugLib.h>
  30 #include <Library/BaseMemoryLib.h>
  31 #include <Library/UefiBootServicesTableLib.h>
  32 #include <Library/UefiLib.h>
  33 #include <Library/BaseLib.h>
  34 #include <Library/SynchronizationLib.h>
  35 #include <Library/MemoryAllocationLib.h>
  36 #include <Library/BaseCryptLib.h>
  37 #include <Library/PlatformSecureLib.h>
  38 #include <Guid/GlobalVariable.h>
  39 #include <Guid/EventGroup.h>
  40 #include <Guid/AuthenticatedVariableFormat.h>
  41 #include <Guid/ImageAuthentication.h>
  42 #include <Guid/SystemNvDataGuid.h>
  43 #include <Guid/HardwareErrorVariable.h>
  44
  45 #define VARIABLE_RECLAIM_THRESHOLD (1024)
  46 #define EFI_VARIABLE_ATTRIBUTES_MASK (EFI_VARIABLE_NON_VOLATILE | \
  47                                       EFI_VARIABLE_BOOTSERVICE_ACCESS | \
  48                                       EFI_VARIABLE_RUNTIME_ACCESS | \
  49                                       EFI_VARIABLE_HARDWARE_ERROR_RECORD | \
  50                                       EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS | \
  51                                       EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS | \
  52                                       EFI_VARIABLE_APPEND_WRITE)
  53
  54 ///
  55 /// The size of a 3 character ISO639 language code.
  56 ///
  57 #define ISO_639_2_ENTRY_SIZE    3
  58
  59 typedef enum {
  60   VariableStoreTypeVolatile,
  61   VariableStoreTypeHob,
  62   VariableStoreTypeNv,
  63   VariableStoreTypeMax
  64 } VARIABLE_STORE_TYPE;
  65
  66 typedef struct {
  67   VARIABLE_HEADER *CurrPtr;
  68   VARIABLE_HEADER *EndPtr;
  69   VARIABLE_HEADER *StartPtr;
  70   BOOLEAN         Volatile;
  71 } VARIABLE_POINTER_TRACK;
  72
  73 typedef struct {
  74   EFI_PHYSICAL_ADDRESS  HobVariableBase;
  75   EFI_PHYSICAL_ADDRESS  VolatileVariableBase;
  76   EFI_PHYSICAL_ADDRESS  NonVolatileVariableBase;
  77   EFI_LOCK              VariableServicesLock;
  78   UINT32                ReentrantState;
  79 } VARIABLE_GLOBAL;
  80
  81 typedef struct {
  82   VARIABLE_GLOBAL VariableGlobal;
  83   UINTN           VolatileLastVariableOffset;
  84   UINTN           NonVolatileLastVariableOffset;
  85   UINTN           CommonVariableTotalSize;
  86   UINTN           HwErrVariableTotalSize;
  87   CHAR8           *PlatformLangCodes;
  88   CHAR8           *LangCodes;
  89   CHAR8           *PlatformLang;
  90   CHAR8           Lang[ISO_639_2_ENTRY_SIZE + 1];
  91   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *FvbInstance;
  92 } VARIABLE_MODULE_GLOBAL;
  93
  94 typedef struct {
  95   EFI_GUID    *Guid;
  96   CHAR16      *Name;
  97   UINT32      Attributes;
  98   UINTN       DataSize;
  99   VOID        *Data;
 100 } VARIABLE_CACHE_ENTRY;
 101
 102 /**
 103   Flush the HOB variable to flash.
 104
 105   @param[in] VariableName       Name of variable has been updated or deleted.
 106   @param[in] VendorGuid         Guid of variable has been updated or deleted.
 107
 108 **/
 109 VOID
 110 FlushHobVariableToFlash (
 111   IN CHAR16                     *VariableName,
 112   IN EFI_GUID                   *VendorGuid
 113   );
 114
 115 /**
 116   Writes a buffer to variable storage space, in the working block.
 117
 118   This function writes a buffer to variable storage space into a firmware
 119   volume block device. The destination is specified by the parameter
 120   VariableBase. Fault Tolerant Write protocol is used for writing.
 121
 122   @param  VariableBase   Base address of the variable to write.
 123   @param  Buffer         Point to the data buffer.
 124   @param  BufferSize     The number of bytes of the data Buffer.
 125
 126   @retval EFI_SUCCESS    The function completed successfully.
 127   @retval EFI_NOT_FOUND  Fail to locate Fault Tolerant Write protocol.
 128   @retval EFI_ABORTED    The function could not complete successfully.
 129
 130 **/
 131 EFI_STATUS
 132 FtwVariableSpace (
 133   IN EFI_PHYSICAL_ADDRESS   VariableBase,
 134   IN UINT8                  *Buffer,
 135   IN UINTN                  BufferSize
 136   );
 137
 138 /**
 139   Finds variable in storage blocks of volatile and non-volatile storage areas.
 140
 141   This code finds variable in storage blocks of volatile and non-volatile storage areas.
 142   If VariableName is an empty string, then we just return the first
 143   qualified variable without comparing VariableName and VendorGuid.
 144   If IgnoreRtCheck is TRUE, then we ignore the EFI_VARIABLE_RUNTIME_ACCESS attribute check
 145   at runtime when searching existing variable, only VariableName and VendorGuid are compared.
 146   Otherwise, variables without EFI_VARIABLE_RUNTIME_ACCESS are not visible at runtime.
 147
 148   @param[in]   VariableName           Name of the variable to be found.
 149   @param[in]   VendorGuid             Vendor GUID to be found.
 150   @param[out]  PtrTrack               VARIABLE_POINTER_TRACK structure for output,
 151                                       including the range searched and the target position.
 152   @param[in]   Global                 Pointer to VARIABLE_GLOBAL structure, including
 153                                       base of volatile variable storage area, base of
 154                                       NV variable storage area, and a lock.
 155   @param[in]   IgnoreRtCheck          Ignore EFI_VARIABLE_RUNTIME_ACCESS attribute
 156                                       check at runtime when searching variable.
 157
 158   @retval EFI_INVALID_PARAMETER       If VariableName is not an empty string, while
 159                                       VendorGuid is NULL.
 160   @retval EFI_SUCCESS                 Variable successfully found.
 161   @retval EFI_NOT_FOUND               Variable not found
 162
 163 **/
 164 EFI_STATUS
 165 FindVariable (
 166   IN  CHAR16                  *VariableName,
 167   IN  EFI_GUID                *VendorGuid,
 168   OUT VARIABLE_POINTER_TRACK  *PtrTrack,
 169   IN  VARIABLE_GLOBAL         *Global,
 170   IN  BOOLEAN                 IgnoreRtCheck
 171   );
 172
 173 /**
 174
 175   This code gets the pointer to the variable data.
 176
 177   @param Variable        Pointer to the Variable Header.
 178
 179   @return Pointer to Variable Data.
 180
 181 **/
 182 UINT8 *
 183 GetVariableDataPtr (
 184   IN  VARIABLE_HEADER   *Variable
 185   );
 186
 187 /**
 188
 189   This code gets the size of variable data.
 190
 191   @param Variable        Pointer to the Variable Header.
 192
 193   @return Size of variable in bytes.
 194
 195 **/
 196 UINTN
 197 DataSizeOfVariable (
 198   IN  VARIABLE_HEADER   *Variable
 199   );
 200
 201 /**
 202   Update the variable region with Variable information. If EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS is set,
 203   index of associated public key is needed.
 204
 205   @param[in] VariableName       Name of variable.
 206   @param[in] VendorGuid         Guid of variable.
 207   @param[in] Data               Variable data.
 208   @param[in] DataSize           Size of data. 0 means delete.
 209   @param[in] Attributes         Attributes of the variable.
 210   @param[in] KeyIndex           Index of associated public key.
 211   @param[in] MonotonicCount     Value of associated monotonic count.
 212   @param[in] Variable           The variable information that is used to keep track of variable usage.
 213
 214   @param[in] TimeStamp          Value of associated TimeStamp.
 215
 216   @retval EFI_SUCCESS           The update operation is success.
 217   @retval EFI_OUT_OF_RESOURCES  Variable region is full, cannot write other data into this region.
 218
 219 **/
 220 EFI_STATUS
 221 UpdateVariable (
 222   IN      CHAR16          *VariableName,
 223   IN      EFI_GUID        *VendorGuid,
 224   IN      VOID            *Data,
 225   IN      UINTN           DataSize,
 226   IN      UINT32          Attributes OPTIONAL,
 227   IN      UINT32          KeyIndex  OPTIONAL,
 228   IN      UINT64          MonotonicCount  OPTIONAL,
 229   IN      VARIABLE_POINTER_TRACK *Variable,
 230   IN      EFI_TIME        *TimeStamp  OPTIONAL
 231   );
 232
 233
 234 /**
 235   Return TRUE if ExitBootServices () has been called.
 236
 237   @retval TRUE If ExitBootServices () has been called.
 238 **/
 239 BOOLEAN
 240 AtRuntime (
 241   VOID
 242   );
 243
 244 /**
 245   Initializes a basic mutual exclusion lock.
 246
 247   This function initializes a basic mutual exclusion lock to the released state
 248   and returns the lock.  Each lock provides mutual exclusion access at its task
 249   priority level.  Since there is no preemption or multiprocessor support in EFI,
 250   acquiring the lock only consists of raising to the locks TPL.
 251   If Lock is NULL, then ASSERT().
 252   If Priority is not a valid TPL value, then ASSERT().
 253
 254   @param  Lock       A pointer to the lock data structure to initialize.
 255   @param  Priority   EFI TPL is associated with the lock.
 256
 257   @return The lock.
 258
 259 **/
 260 EFI_LOCK *
 261 InitializeLock (
 262   IN OUT EFI_LOCK  *Lock,
 263   IN EFI_TPL        Priority
 264   );
 265
 266
 267 /**
 268   Acquires lock only at boot time. Simply returns at runtime.
 269
 270   This is a temperary function that will be removed when
 271   EfiAcquireLock() in UefiLib can handle the call in UEFI
 272   Runtimer driver in RT phase.
 273   It calls EfiAcquireLock() at boot time, and simply returns
 274   at runtime.
 275
 276   @param  Lock         A pointer to the lock to acquire.
 277
 278 **/
 279 VOID
 280 AcquireLockOnlyAtBootTime (
 281   IN EFI_LOCK  *Lock
 282   );
 283
 284
 285 /**
 286   Releases lock only at boot time. Simply returns at runtime.
 287
 288   This is a temperary function which will be removed when
 289   EfiReleaseLock() in UefiLib can handle the call in UEFI
 290   Runtimer driver in RT phase.
 291   It calls EfiReleaseLock() at boot time and simply returns
 292   at runtime.
 293
 294   @param  Lock         A pointer to the lock to release.
 295
 296 **/
 297 VOID
 298 ReleaseLockOnlyAtBootTime (
 299   IN EFI_LOCK  *Lock
 300   );
 301
 302 /**
 303   Retrive the FVB protocol interface by HANDLE.
 304
 305   @param[in]  FvBlockHandle     The handle of FVB protocol that provides services for
 306                                 reading, writing, and erasing the target block.
 307   @param[out] FvBlock           The interface of FVB protocol
 308
 309   @retval EFI_SUCCESS           The interface information for the specified protocol was returned.
 310   @retval EFI_UNSUPPORTED       The device does not support the FVB protocol.
 311   @retval EFI_INVALID_PARAMETER FvBlockHandle is not a valid EFI_HANDLE or FvBlock is NULL.
 312
 313 **/
 314 EFI_STATUS
 315 GetFvbByHandle (
 316   IN  EFI_HANDLE                          FvBlockHandle,
 317   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvBlock
 318   );
 319
 320
 321 /**
 322   Retrive the Swap Address Range protocol interface.
 323
 324   @param[out] SarProtocol       The interface of SAR protocol
 325
 326   @retval EFI_SUCCESS           The SAR protocol instance was found and returned in SarProtocol.
 327   @retval EFI_NOT_FOUND         The SAR protocol instance was not found.
 328   @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
 329
 330 **/
 331 EFI_STATUS
 332 GetSarProtocol (
 333   OUT VOID                                **SarProtocol
 334   );
 335
 336 /**
 337   Function returns an array of handles that support the FVB protocol
 338   in a buffer allocated from pool.
 339
 340   @param[out]  NumberHandles    The number of handles returned in Buffer.
 341   @param[out]  Buffer           A pointer to the buffer to return the requested
 342                                 array of  handles that support FVB protocol.
 343
 344   @retval EFI_SUCCESS           The array of handles was returned in Buffer, and the number of
 345                                 handles in Buffer was returned in NumberHandles.
 346   @retval EFI_NOT_FOUND         No FVB handle was found.
 347   @retval EFI_OUT_OF_RESOURCES  There is not enough pool memory to store the matching results.
 348   @retval EFI_INVALID_PARAMETER NumberHandles is NULL or Buffer is NULL.
 349
 350 **/
 351 EFI_STATUS
 352 GetFvbCountAndBuffer (
 353   OUT UINTN                               *NumberHandles,
 354   OUT EFI_HANDLE                          **Buffer
 355   );
 356
 357 /**
 358   Initializes variable store area for non-volatile and volatile variable.
 359
 360   @retval EFI_SUCCESS           Function successfully executed.
 361   @retval EFI_OUT_OF_RESOURCES  Fail to allocate enough memory resource.
 362
 363 **/
 364 EFI_STATUS
 365 VariableCommonInitialize (
 366   VOID
 367   );
 368
 369 /**
 370
 371   Variable store garbage collection and reclaim operation.
 372
 373   If ReclaimPubKeyStore is FALSE, reclaim variable space by deleting the obsoleted varaibles.
 374   If ReclaimPubKeyStore is TRUE, reclaim invalid key in public key database and update the PubKeyIndex
 375   for all the count-based authenticate variable in NV storage.
 376
 377   @param[in]   VariableBase            Base address of variable store.
 378   @param[out]  LastVariableOffset      Offset of last variable.
 379   @param[in]   IsVolatile              The variable store is volatile or not;
 380                                        if it is non-volatile, need FTW.
 381   @param[in]   UpdatingVariable        Pointer to updating variable.
 382   @param[in]   ReclaimPubKeyStore      Reclaim for public key database or not.
 383   @param[in]   ReclaimAnyway           If TRUE, do reclaim anyway.
 384
 385   @return EFI_OUT_OF_RESOURCES         No enough memory resources.
 386   @return EFI_SUCCESS                  Reclaim operation has finished successfully.
 387   @return Others                       Unexpect error happened during reclaim operation.
 388
 389 **/
 390 EFI_STATUS
 391 Reclaim (
 392   IN  EFI_PHYSICAL_ADDRESS  VariableBase,
 393   OUT UINTN                 *LastVariableOffset,
 394   IN  BOOLEAN               IsVolatile,
 395   IN  VARIABLE_HEADER       *UpdatingVariable,
 396   IN  BOOLEAN               ReclaimPubKeyStore,
 397   IN  BOOLEAN               ReclaimAnyway
 398   );
 399
 400 /**
 401   This function reclaims variable storage if free size is below the threshold.
 402
 403 **/
 404 VOID
 405 ReclaimForOS(
 406   VOID
 407   );
 408
 409
 410 /**
 411   Initializes variable write service after FVB was ready.
 412
 413   @retval EFI_SUCCESS          Function successfully executed.
 414   @retval Others               Fail to initialize the variable service.
 415
 416 **/
 417 EFI_STATUS
 418 VariableWriteServiceInitialize (
 419   VOID
 420   );
 421
 422 /**
 423   Retrive the SMM Fault Tolerent Write protocol interface.
 424
 425   @param[out] FtwProtocol       The interface of SMM Ftw protocol
 426
 427   @retval EFI_SUCCESS           The SMM SAR protocol instance was found and returned in SarProtocol.
 428   @retval EFI_NOT_FOUND         The SMM SAR protocol instance was not found.
 429   @retval EFI_INVALID_PARAMETER SarProtocol is NULL.
 430
 431 **/
 432 EFI_STATUS
 433 GetFtwProtocol (
 434   OUT VOID                                **FtwProtocol
 435   );
 436
 437 /**
 438   Get the proper fvb handle and/or fvb protocol by the given Flash address.
 439
 440   @param[in] Address        The Flash address.
 441   @param[out] FvbHandle     In output, if it is not NULL, it points to the proper FVB handle.
 442   @param[out] FvbProtocol   In output, if it is not NULL, it points to the proper FVB protocol.
 443
 444 **/
 445 EFI_STATUS
 446 GetFvbInfoByAddress (
 447   IN  EFI_PHYSICAL_ADDRESS                Address,
 448   OUT EFI_HANDLE                          *FvbHandle OPTIONAL,
 449   OUT EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL  **FvbProtocol OPTIONAL
 450   );
 451
 452 /**
 453
 454   This code finds variable in storage blocks (Volatile or Non-Volatile).
 455
 456   Caution: This function may receive untrusted input.
 457   This function may be invoked in SMM mode, and datasize and data are external input.
 458   This function will do basic validation, before parse the data.
 459
 460   @param VariableName               Name of Variable to be found.
 461   @param VendorGuid                 Variable vendor GUID.
 462   @param Attributes                 Attribute value of the variable found.
 463   @param DataSize                   Size of Data found. If size is less than the
 464                                     data, this value contains the required size.
 465   @param Data                       Data pointer.
 466
 467   @return EFI_INVALID_PARAMETER     Invalid parameter.
 468   @return EFI_SUCCESS               Find the specified variable.
 469   @return EFI_NOT_FOUND             Not found.
 470   @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.
 471
 472 **/
 473 EFI_STATUS
 474 EFIAPI
 475 VariableServiceGetVariable (
 476   IN      CHAR16            *VariableName,
 477   IN      EFI_GUID          *VendorGuid,
 478   OUT     UINT32            *Attributes OPTIONAL,
 479   IN OUT  UINTN             *DataSize,
 480   OUT     VOID              *Data
 481   );
 482
 483 /**
 484
 485   This code Finds the Next available variable.
 486
 487   Caution: This function may receive untrusted input.
 488   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 489
 490   @param VariableNameSize           Size of the variable name.
 491   @param VariableName               Pointer to variable name.
 492   @param VendorGuid                 Variable Vendor Guid.
 493
 494   @return EFI_INVALID_PARAMETER     Invalid parameter.
 495   @return EFI_SUCCESS               Find the specified variable.
 496   @return EFI_NOT_FOUND             Not found.
 497   @return EFI_BUFFER_TO_SMALL       DataSize is too small for the result.
 498
 499 **/
 500 EFI_STATUS
 501 EFIAPI
 502 VariableServiceGetNextVariableName (
 503   IN OUT  UINTN             *VariableNameSize,
 504   IN OUT  CHAR16            *VariableName,
 505   IN OUT  EFI_GUID          *VendorGuid
 506   );
 507
 508 /**
 509
 510   This code sets variable in storage blocks (Volatile or Non-Volatile).
 511
 512   Caution: This function may receive untrusted input.
 513   This function may be invoked in SMM mode, and datasize and data are external input.
 514   This function will do basic validation, before parse the data.
 515   This function will parse the authentication carefully to avoid security issues, like
 516   buffer overflow, integer overflow.
 517   This function will check attribute carefully to avoid authentication bypass.
 518
 519   @param VariableName                     Name of Variable to be found.
 520   @param VendorGuid                       Variable vendor GUID.
 521   @param Attributes                       Attribute value of the variable found
 522   @param DataSize                         Size of Data found. If size is less than the
 523                                           data, this value contains the required size.
 524   @param Data                             Data pointer.
 525
 526   @return EFI_INVALID_PARAMETER           Invalid parameter.
 527   @return EFI_SUCCESS                     Set successfully.
 528   @return EFI_OUT_OF_RESOURCES            Resource not enough to set variable.
 529   @return EFI_NOT_FOUND                   Not found.
 530   @return EFI_WRITE_PROTECTED             Variable is read-only.
 531
 532 **/
 533 EFI_STATUS
 534 EFIAPI
 535 VariableServiceSetVariable (
 536   IN CHAR16                  *VariableName,
 537   IN EFI_GUID                *VendorGuid,
 538   IN UINT32                  Attributes,
 539   IN UINTN                   DataSize,
 540   IN VOID                    *Data
 541   );
 542
 543 /**
 544
 545   This code returns information about the EFI variables.
 546
 547   Caution: This function may receive untrusted input.
 548   This function may be invoked in SMM mode. This function will do basic validation, before parse the data.
 549
 550   @param Attributes                     Attributes bitmask to specify the type of variables
 551                                         on which to return information.
 552   @param MaximumVariableStorageSize     Pointer to the maximum size of the storage space available
 553                                         for the EFI variables associated with the attributes specified.
 554   @param RemainingVariableStorageSize   Pointer to the remaining size of the storage space available
 555                                         for EFI variables associated with the attributes specified.
 556   @param MaximumVariableSize            Pointer to the maximum size of an individual EFI variables
 557                                         associated with the attributes specified.
 558
 559   @return EFI_INVALID_PARAMETER         An invalid combination of attribute bits was supplied.
 560   @return EFI_SUCCESS                   Query successfully.
 561   @return EFI_UNSUPPORTED               The attribute is not supported on this platform.
 562
 563 **/
 564 EFI_STATUS
 565 EFIAPI
 566 VariableServiceQueryVariableInfo (
 567   IN  UINT32                 Attributes,
 568   OUT UINT64                 *MaximumVariableStorageSize,
 569   OUT UINT64                 *RemainingVariableStorageSize,
 570   OUT UINT64                 *MaximumVariableSize
 571   );
 572
 573 extern VARIABLE_MODULE_GLOBAL  *mVariableModuleGlobal;
 574
 575 #endif