SecurityPkg/Library/AuthVariableLib/AuthServiceInternal.h

   1 /** @file
   2   The internal header file includes the common header files, defines
   3   internal structure and functions used by AuthService module.
   4
   5   Caution: This module requires additional review when modified.
   6   This driver will have external input - variable data. It may be input in SMM mode.
   7   This external input must be validated carefully to avoid security issue like
   8   buffer overflow, integer overflow.
   9   Variable attribute should also be checked to avoid authentication bypass.
  10      The whole SMM authentication variable design relies on the integrity of flash part and SMM.
  11   which is assumed to be protected by platform.  All variable code and metadata in flash/SMM Memory
  12   may not be modified without authorization. If platform fails to protect these resources,
  13   the authentication service provided in this driver will be broken, and the behavior is undefined.
  14
  15 Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>
  16 This program and the accompanying materials
  17 are licensed and made available under the terms and conditions of the BSD License
  18 which accompanies this distribution.  The full text of the license may be found at
  19 http://opensource.org/licenses/bsd-license.php
  20
  21 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  22 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  23
  24 **/
  25
  26 #ifndef _AUTHSERVICE_INTERNAL_H_
  27 #define _AUTHSERVICE_INTERNAL_H_
  28
  29 #include <Library/AuthVariableLib.h>
  30 #include <Library/BaseLib.h>
  31 #include <Library/BaseMemoryLib.h>
  32 #include <Library/DebugLib.h>
  33 #include <Library/MemoryAllocationLib.h>
  34 #include <Library/BaseCryptLib.h>
  35 #include <Library/PlatformSecureLib.h>
  36
  37 #include <Guid/AuthenticatedVariableFormat.h>
  38 #include <Guid/ImageAuthentication.h>
  39
  40 ///
  41 /// Struct to record signature requirement defined by UEFI spec.
  42 /// For SigHeaderSize and SigDataSize, ((UINT32) ~0) means NO exact length requirement for this field.
  43 ///
  44 typedef struct {
  45   EFI_GUID    SigType;
  46   // Expected SignatureHeader size in Bytes.
  47   UINT32      SigHeaderSize;
  48   // Expected SignatureData size in Bytes.
  49   UINT32      SigDataSize;
  50 } EFI_SIGNATURE_ITEM;
  51
  52 typedef enum {
  53   AuthVarTypePk,
  54   AuthVarTypeKek,
  55   AuthVarTypePriv,
  56   AuthVarTypePayload
  57 } AUTHVAR_TYPE;
  58
  59 ///
  60 /// "AuthVarKeyDatabase" variable for the Public Key store
  61 /// of variables with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS set.
  62 ///
  63 /// GUID: gEfiAuthenticatedVariableGuid
  64 ///
  65 /// We need maintain atomicity.
  66 ///
  67 /// Format:
  68 /// +----------------------------+
  69 /// | AUTHVAR_KEY_DB_DATA        | <-- First AuthVarKey
  70 /// +----------------------------+
  71 /// | ......                     |
  72 /// +----------------------------+
  73 /// | AUTHVAR_KEY_DB_DATA        | <-- Last AuthKey
  74 /// +----------------------------+
  75 ///
  76 #define AUTHVAR_KEYDB_NAME      L"AuthVarKeyDatabase"
  77
  78 #define EFI_CERT_TYPE_RSA2048_SHA256_SIZE 256
  79 #define EFI_CERT_TYPE_RSA2048_SIZE        256
  80
  81 #pragma pack(1)
  82 typedef struct {
  83   UINT32    KeyIndex;
  84   UINT8     KeyData[EFI_CERT_TYPE_RSA2048_SIZE];
  85 } AUTHVAR_KEY_DB_DATA;
  86 #pragma pack()
  87
  88 ///
  89 /// "certdb" variable stores the signer's certificates for non PK/KEK/DB/DBX
  90 /// variables with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set.
  91 ///
  92 /// GUID: gEfiCertDbGuid
  93 ///
  94 /// We need maintain atomicity.
  95 ///
  96 /// Format:
  97 /// +----------------------------+
  98 /// | UINT32                     | <-- CertDbListSize, including this UINT32
  99 /// +----------------------------+
 100 /// | AUTH_CERT_DB_DATA          | <-- First CERT
 101 /// +----------------------------+
 102 /// | ........                   |
 103 /// +----------------------------+
 104 /// | AUTH_CERT_DB_DATA          | <-- Last CERT
 105 /// +----------------------------+
 106 ///
 107 #define EFI_CERT_DB_NAME        L"certdb"
 108
 109 #pragma pack(1)
 110 typedef struct {
 111   EFI_GUID    VendorGuid;
 112   UINT32      CertNodeSize;
 113   UINT32      NameSize;
 114   UINT32      CertDataSize;
 115   /// CHAR16  VariableName[NameSize];
 116   /// UINT8   CertData[CertDataSize];
 117 } AUTH_CERT_DB_DATA;
 118 #pragma pack()
 119
 120 extern UINT8    *mPubKeyStore;
 121 extern UINT32   mPubKeyNumber;
 122 extern UINT32   mMaxKeyNumber;
 123 extern UINT32   mMaxKeyDbSize;
 124 extern UINT8    *mCertDbStore;
 125 extern UINT32   mMaxCertDbSize;
 126 extern UINT32   mPlatformMode;
 127 extern UINT8    mVendorKeyState;
 128
 129 extern VOID     *mHashCtx;
 130
 131 extern AUTH_VAR_LIB_CONTEXT_IN *mAuthVarLibContextIn;
 132
 133 /**
 134   Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
 135
 136   Caution: This function may receive untrusted input.
 137   This function may be invoked in SMM mode, and datasize and data are external input.
 138   This function will do basic validation, before parse the data.
 139   This function will parse the authentication carefully to avoid security issues, like
 140   buffer overflow, integer overflow.
 141
 142   @param[in]  VariableName                Name of Variable to be found.
 143   @param[in]  VendorGuid                  Variable vendor GUID.
 144   @param[in]  Data                        Data pointer.
 145   @param[in]  DataSize                    Size of Data found. If size is less than the
 146                                           data, this value contains the required size.
 147   @param[in]  Attributes                  Attribute value of the variable.
 148   @param[in]  AuthVarType                 Verify against PK, KEK database, private database or certificate in data payload.
 149   @param[out] VarDel                      Delete the variable or not.
 150
 151   @retval EFI_INVALID_PARAMETER           Invalid parameter.
 152   @retval EFI_SECURITY_VIOLATION          The variable does NOT pass the validation
 153                                           check carried out by the firmware.
 154   @retval EFI_OUT_OF_RESOURCES            Failed to process variable due to lack
 155                                           of resources.
 156   @retval EFI_SUCCESS                     Variable pass validation successfully.
 157
 158 **/
 159 EFI_STATUS
 160 VerifyTimeBasedPayloadAndUpdate (
 161   IN     CHAR16                             *VariableName,
 162   IN     EFI_GUID                           *VendorGuid,
 163   IN     VOID                               *Data,
 164   IN     UINTN                              DataSize,
 165   IN     UINT32                             Attributes,
 166   IN     AUTHVAR_TYPE                       AuthVarType,
 167   OUT    BOOLEAN                            *VarDel
 168   );
 169
 170 /**
 171   Delete matching signer's certificates when deleting common authenticated
 172   variable by corresponding VariableName and VendorGuid from "certdb".
 173
 174   @param[in]  VariableName   Name of authenticated Variable.
 175   @param[in]  VendorGuid     Vendor GUID of authenticated Variable.
 176
 177   @retval  EFI_INVALID_PARAMETER Any input parameter is invalid.
 178   @retval  EFI_NOT_FOUND         Fail to find "certdb" or matching certs.
 179   @retval  EFI_OUT_OF_RESOURCES  The operation is failed due to lack of resources.
 180   @retval  EFI_SUCCESS           The operation is completed successfully.
 181
 182 **/
 183 EFI_STATUS
 184 DeleteCertsFromDb (
 185   IN     CHAR16           *VariableName,
 186   IN     EFI_GUID         *VendorGuid
 187   );
 188
 189 /**
 190   Filter out the duplicated EFI_SIGNATURE_DATA from the new data by comparing to the original data.
 191
 192   @param[in]        Data          Pointer to original EFI_SIGNATURE_LIST.
 193   @param[in]        DataSize      Size of Data buffer.
 194   @param[in, out]   NewData       Pointer to new EFI_SIGNATURE_LIST.
 195   @param[in, out]   NewDataSize   Size of NewData buffer.
 196
 197 **/
 198 EFI_STATUS
 199 FilterSignatureList (
 200   IN     VOID       *Data,
 201   IN     UINTN      DataSize,
 202   IN OUT VOID       *NewData,
 203   IN OUT UINTN      *NewDataSize
 204   );
 205
 206 /**
 207   Process variable with platform key for verification.
 208
 209   Caution: This function may receive untrusted input.
 210   This function may be invoked in SMM mode, and datasize and data are external input.
 211   This function will do basic validation, before parse the data.
 212   This function will parse the authentication carefully to avoid security issues, like
 213   buffer overflow, integer overflow.
 214   This function will check attribute carefully to avoid authentication bypass.
 215
 216   @param[in]  VariableName                Name of Variable to be found.
 217   @param[in]  VendorGuid                  Variable vendor GUID.
 218   @param[in]  Data                        Data pointer.
 219   @param[in]  DataSize                    Size of Data found. If size is less than the
 220                                           data, this value contains the required size.
 221   @param[in]  Attributes                  Attribute value of the variable
 222   @param[in]  IsPk                        Indicate whether it is to process pk.
 223
 224   @return EFI_INVALID_PARAMETER           Invalid parameter.
 225   @return EFI_SECURITY_VIOLATION          The variable does NOT pass the validation.
 226                                           check carried out by the firmware.
 227   @return EFI_SUCCESS                     Variable passed validation successfully.
 228
 229 **/
 230 EFI_STATUS
 231 ProcessVarWithPk (
 232   IN  CHAR16                    *VariableName,
 233   IN  EFI_GUID                  *VendorGuid,
 234   IN  VOID                      *Data,
 235   IN  UINTN                     DataSize,
 236   IN  UINT32                    Attributes OPTIONAL,
 237   IN  BOOLEAN                   IsPk
 238   );
 239
 240 /**
 241   Process variable with key exchange key for verification.
 242
 243   Caution: This function may receive untrusted input.
 244   This function may be invoked in SMM mode, and datasize and data are external input.
 245   This function will do basic validation, before parse the data.
 246   This function will parse the authentication carefully to avoid security issues, like
 247   buffer overflow, integer overflow.
 248   This function will check attribute carefully to avoid authentication bypass.
 249
 250   @param[in]  VariableName                Name of Variable to be found.
 251   @param[in]  VendorGuid                  Variable vendor GUID.
 252   @param[in]  Data                        Data pointer.
 253   @param[in]  DataSize                    Size of Data found. If size is less than the
 254                                           data, this value contains the required size.
 255   @param[in]  Attributes                  Attribute value of the variable.
 256
 257   @return EFI_INVALID_PARAMETER           Invalid parameter.
 258   @return EFI_SECURITY_VIOLATION          The variable does NOT pass the validation
 259                                           check carried out by the firmware.
 260   @return EFI_SUCCESS                     Variable pass validation successfully.
 261
 262 **/
 263 EFI_STATUS
 264 ProcessVarWithKek (
 265   IN  CHAR16                               *VariableName,
 266   IN  EFI_GUID                             *VendorGuid,
 267   IN  VOID                                 *Data,
 268   IN  UINTN                                DataSize,
 269   IN  UINT32                               Attributes OPTIONAL
 270   );
 271
 272 /**
 273   Process variable with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS/EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
 274
 275   Caution: This function may receive untrusted input.
 276   This function may be invoked in SMM mode, and datasize and data are external input.
 277   This function will do basic validation, before parse the data.
 278   This function will parse the authentication carefully to avoid security issues, like
 279   buffer overflow, integer overflow.
 280   This function will check attribute carefully to avoid authentication bypass.
 281
 282   @param[in]  VariableName                Name of the variable.
 283   @param[in]  VendorGuid                  Variable vendor GUID.
 284   @param[in]  Data                        Data pointer.
 285   @param[in]  DataSize                    Size of Data.
 286   @param[in]  Attributes                  Attribute value of the variable.
 287
 288   @return EFI_INVALID_PARAMETER           Invalid parameter.
 289   @return EFI_WRITE_PROTECTED             Variable is write-protected and needs authentication with
 290                                           EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS set.
 291   @return EFI_OUT_OF_RESOURCES            The Database to save the public key is full.
 292   @return EFI_SECURITY_VIOLATION          The variable is with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS
 293                                           set, but the AuthInfo does NOT pass the validation
 294                                           check carried out by the firmware.
 295   @return EFI_SUCCESS                     Variable is not write-protected or pass validation successfully.
 296
 297 **/
 298 EFI_STATUS
 299 ProcessVariable (
 300   IN     CHAR16                             *VariableName,
 301   IN     EFI_GUID                           *VendorGuid,
 302   IN     VOID                               *Data,
 303   IN     UINTN                              DataSize,
 304   IN     UINT32                             Attributes OPTIONAL
 305   );
 306
 307 /**
 308   Finds variable in storage blocks of volatile and non-volatile storage areas.
 309
 310   This code finds variable in storage blocks of volatile and non-volatile storage areas.
 311   If VariableName is an empty string, then we just return the first
 312   qualified variable without comparing VariableName and VendorGuid.
 313
 314   @param[in]  VariableName          Name of the variable to be found.
 315   @param[in]  VendorGuid            Variable vendor GUID to be found.
 316   @param[out] Data                  Pointer to data address.
 317   @param[out] DataSize              Pointer to data size.
 318
 319   @retval EFI_INVALID_PARAMETER     If VariableName is not an empty string,
 320                                     while VendorGuid is NULL.
 321   @retval EFI_SUCCESS               Variable successfully found.
 322   @retval EFI_NOT_FOUND             Variable not found
 323
 324 **/
 325 EFI_STATUS
 326 AuthServiceInternalFindVariable (
 327   IN  CHAR16        *VariableName,
 328   IN  EFI_GUID      *VendorGuid,
 329   OUT VOID          **Data,
 330   OUT UINTN         *DataSize
 331   );
 332
 333 /**
 334   Update the variable region with Variable information.
 335
 336   @param[in] VariableName           Name of variable.
 337   @param[in] VendorGuid             Guid of variable.
 338   @param[in] Data                   Data pointer.
 339   @param[in] DataSize               Size of Data.
 340   @param[in] Attributes             Attribute value of the variable.
 341
 342   @retval EFI_SUCCESS               The update operation is success.
 343   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 344   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 345   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 346
 347 **/
 348 EFI_STATUS
 349 AuthServiceInternalUpdateVariable (
 350   IN CHAR16         *VariableName,
 351   IN EFI_GUID       *VendorGuid,
 352   IN VOID           *Data,
 353   IN UINTN          DataSize,
 354   IN UINT32         Attributes
 355   );
 356
 357 /**
 358   Update the variable region with Variable information.
 359
 360   @param[in] VariableName           Name of variable.
 361   @param[in] VendorGuid             Guid of variable.
 362   @param[in] Data                   Data pointer.
 363   @param[in] DataSize               Size of Data.
 364   @param[in] Attributes             Attribute value of the variable.
 365   @param[in] KeyIndex               Index of associated public key.
 366   @param[in] MonotonicCount         Value of associated monotonic count.
 367
 368   @retval EFI_SUCCESS               The update operation is success.
 369   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 370   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 371   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 372
 373 **/
 374 EFI_STATUS
 375 AuthServiceInternalUpdateVariableWithMonotonicCount (
 376   IN CHAR16         *VariableName,
 377   IN EFI_GUID       *VendorGuid,
 378   IN VOID           *Data,
 379   IN UINTN          DataSize,
 380   IN UINT32         Attributes,
 381   IN UINT32         KeyIndex,
 382   IN UINT64         MonotonicCount
 383   );
 384
 385 /**
 386   Update the variable region with Variable information.
 387
 388   @param[in] VariableName           Name of variable.
 389   @param[in] VendorGuid             Guid of variable.
 390   @param[in] Data                   Data pointer.
 391   @param[in] DataSize               Size of Data.
 392   @param[in] Attributes             Attribute value of the variable.
 393   @param[in] TimeStamp              Value of associated TimeStamp.
 394
 395   @retval EFI_SUCCESS               The update operation is success.
 396   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 397   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 398   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 399
 400 **/
 401 EFI_STATUS
 402 AuthServiceInternalUpdateVariableWithTimeStamp (
 403   IN CHAR16         *VariableName,
 404   IN EFI_GUID       *VendorGuid,
 405   IN VOID           *Data,
 406   IN UINTN          DataSize,
 407   IN UINT32         Attributes,
 408   IN EFI_TIME       *TimeStamp
 409   );
 410
 411 #endif