SecurityPkg/VariableAuthenticated/EsalVariableDxeSal/Variable.h

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