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 - 2018, Intel Corporation. All rights reserved.<BR>
  16 SPDX-License-Identifier: BSD-2-Clause-Patent
  17
  18 **/
  19
  20 #ifndef _AUTHSERVICE_INTERNAL_H_
  21 #define _AUTHSERVICE_INTERNAL_H_
  22
  23 #include <Library/AuthVariableLib.h>
  24 #include <Library/BaseLib.h>
  25 #include <Library/BaseMemoryLib.h>
  26 #include <Library/DebugLib.h>
  27 #include <Library/MemoryAllocationLib.h>
  28 #include <Library/BaseCryptLib.h>
  29 #include <Library/PlatformSecureLib.h>
  30
  31 #include <Guid/AuthenticatedVariableFormat.h>
  32 #include <Guid/ImageAuthentication.h>
  33
  34 #define TWO_BYTE_ENCODE  0x82
  35
  36 ///
  37 /// Struct to record signature requirement defined by UEFI spec.
  38 /// For SigHeaderSize and SigDataSize, ((UINT32) ~0) means NO exact length requirement for this field.
  39 ///
  40 typedef struct {
  41   EFI_GUID    SigType;
  42   // Expected SignatureHeader size in Bytes.
  43   UINT32      SigHeaderSize;
  44   // Expected SignatureData size in Bytes.
  45   UINT32      SigDataSize;
  46 } EFI_SIGNATURE_ITEM;
  47
  48 typedef enum {
  49   AuthVarTypePk,
  50   AuthVarTypeKek,
  51   AuthVarTypePriv,
  52   AuthVarTypePayload
  53 } AUTHVAR_TYPE;
  54
  55 ///
  56 ///  "certdb" variable stores the signer's certificates for non PK/KEK/DB/DBX
  57 /// variables with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS|EFI_VARIABLE_NON_VOLATILE set.
  58 ///  "certdbv" variable stores the signer's certificates for non PK/KEK/DB/DBX
  59 /// variables with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
  60 ///
  61 /// GUID: gEfiCertDbGuid
  62 ///
  63 /// We need maintain atomicity.
  64 ///
  65 /// Format:
  66 /// +----------------------------+
  67 /// | UINT32                     | <-- CertDbListSize, including this UINT32
  68 /// +----------------------------+
  69 /// | AUTH_CERT_DB_DATA          | <-- First CERT
  70 /// +----------------------------+
  71 /// | ........                   |
  72 /// +----------------------------+
  73 /// | AUTH_CERT_DB_DATA          | <-- Last CERT
  74 /// +----------------------------+
  75 ///
  76 #define EFI_CERT_DB_NAME           L"certdb"
  77 #define EFI_CERT_DB_VOLATILE_NAME  L"certdbv"
  78
  79 #pragma pack(1)
  80 typedef struct {
  81   EFI_GUID    VendorGuid;
  82   UINT32      CertNodeSize;
  83   UINT32      NameSize;
  84   UINT32      CertDataSize;
  85   /// CHAR16  VariableName[NameSize];
  86   /// UINT8   CertData[CertDataSize];
  87 } AUTH_CERT_DB_DATA;
  88 #pragma pack()
  89
  90 extern UINT8   *mCertDbStore;
  91 extern UINT32  mMaxCertDbSize;
  92 extern UINT32  mPlatformMode;
  93 extern UINT8   mVendorKeyState;
  94
  95 extern VOID  *mHashCtx;
  96
  97 extern AUTH_VAR_LIB_CONTEXT_IN  *mAuthVarLibContextIn;
  98
  99 /**
 100   Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
 101
 102   Caution: This function may receive untrusted input.
 103   This function may be invoked in SMM mode, and datasize and data are external input.
 104   This function will do basic validation, before parse the data.
 105   This function will parse the authentication carefully to avoid security issues, like
 106   buffer overflow, integer overflow.
 107
 108   @param[in]  VariableName                Name of Variable to be found.
 109   @param[in]  VendorGuid                  Variable vendor GUID.
 110   @param[in]  Data                        Data pointer.
 111   @param[in]  DataSize                    Size of Data found. If size is less than the
 112                                           data, this value contains the required size.
 113   @param[in]  Attributes                  Attribute value of the variable.
 114   @param[in]  AuthVarType                 Verify against PK, KEK database, private database or certificate in data payload.
 115   @param[out] VarDel                      Delete the variable or not.
 116
 117   @retval EFI_INVALID_PARAMETER           Invalid parameter.
 118   @retval EFI_SECURITY_VIOLATION          The variable does NOT pass the validation
 119                                           check carried out by the firmware.
 120   @retval EFI_OUT_OF_RESOURCES            Failed to process variable due to lack
 121                                           of resources.
 122   @retval EFI_SUCCESS                     Variable pass validation successfully.
 123
 124 **/
 125 EFI_STATUS
 126 VerifyTimeBasedPayloadAndUpdate (
 127   IN     CHAR16        *VariableName,
 128   IN     EFI_GUID      *VendorGuid,
 129   IN     VOID          *Data,
 130   IN     UINTN         DataSize,
 131   IN     UINT32        Attributes,
 132   IN     AUTHVAR_TYPE  AuthVarType,
 133   OUT    BOOLEAN       *VarDel
 134   );
 135
 136 /**
 137   Delete matching signer's certificates when deleting common authenticated
 138   variable by corresponding VariableName and VendorGuid from "certdb" or
 139   "certdbv" according to authenticated variable attributes.
 140
 141   @param[in]  VariableName   Name of authenticated Variable.
 142   @param[in]  VendorGuid     Vendor GUID of authenticated Variable.
 143   @param[in]  Attributes        Attributes of authenticated variable.
 144
 145   @retval  EFI_INVALID_PARAMETER Any input parameter is invalid.
 146   @retval  EFI_NOT_FOUND         Fail to find "certdb"/"certdbv" or matching certs.
 147   @retval  EFI_OUT_OF_RESOURCES  The operation is failed due to lack of resources.
 148   @retval  EFI_SUCCESS           The operation is completed successfully.
 149
 150 **/
 151 EFI_STATUS
 152 DeleteCertsFromDb (
 153   IN     CHAR16    *VariableName,
 154   IN     EFI_GUID  *VendorGuid,
 155   IN     UINT32    Attributes
 156   );
 157
 158 /**
 159   Clean up signer's certificates for common authenticated variable
 160   by corresponding VariableName and VendorGuid from "certdb".
 161   System may break down during Timebased Variable update & certdb update,
 162   make them inconsistent,  this function is called in AuthVariable Init to ensure
 163   consistency
 164
 165   @retval  EFI_NOT_FOUND         Fail to find matching certs.
 166   @retval  EFI_SUCCESS           Find matching certs and output parameters.
 167
 168 **/
 169 EFI_STATUS
 170 CleanCertsFromDb (
 171   VOID
 172   );
 173
 174 /**
 175   Filter out the duplicated EFI_SIGNATURE_DATA from the new data by comparing to the original data.
 176
 177   @param[in]        Data          Pointer to original EFI_SIGNATURE_LIST.
 178   @param[in]        DataSize      Size of Data buffer.
 179   @param[in, out]   NewData       Pointer to new EFI_SIGNATURE_LIST.
 180   @param[in, out]   NewDataSize   Size of NewData buffer.
 181
 182 **/
 183 EFI_STATUS
 184 FilterSignatureList (
 185   IN     VOID   *Data,
 186   IN     UINTN  DataSize,
 187   IN OUT VOID   *NewData,
 188   IN OUT UINTN  *NewDataSize
 189   );
 190
 191 /**
 192   Process variable with platform key for verification.
 193
 194   Caution: This function may receive untrusted input.
 195   This function may be invoked in SMM mode, and datasize and data are external input.
 196   This function will do basic validation, before parse the data.
 197   This function will parse the authentication carefully to avoid security issues, like
 198   buffer overflow, integer overflow.
 199   This function will check attribute carefully to avoid authentication bypass.
 200
 201   @param[in]  VariableName                Name of Variable to be found.
 202   @param[in]  VendorGuid                  Variable vendor GUID.
 203   @param[in]  Data                        Data pointer.
 204   @param[in]  DataSize                    Size of Data found. If size is less than the
 205                                           data, this value contains the required size.
 206   @param[in]  Attributes                  Attribute value of the variable
 207   @param[in]  IsPk                        Indicate whether it is to process pk.
 208
 209   @return EFI_INVALID_PARAMETER           Invalid parameter.
 210   @return EFI_SECURITY_VIOLATION          The variable does NOT pass the validation.
 211                                           check carried out by the firmware.
 212   @return EFI_SUCCESS                     Variable passed validation successfully.
 213
 214 **/
 215 EFI_STATUS
 216 ProcessVarWithPk (
 217   IN  CHAR16    *VariableName,
 218   IN  EFI_GUID  *VendorGuid,
 219   IN  VOID      *Data,
 220   IN  UINTN     DataSize,
 221   IN  UINT32    Attributes OPTIONAL,
 222   IN  BOOLEAN   IsPk
 223   );
 224
 225 /**
 226   Process variable with key exchange key for verification.
 227
 228   Caution: This function may receive untrusted input.
 229   This function may be invoked in SMM mode, and datasize and data are external input.
 230   This function will do basic validation, before parse the data.
 231   This function will parse the authentication carefully to avoid security issues, like
 232   buffer overflow, integer overflow.
 233   This function will check attribute carefully to avoid authentication bypass.
 234
 235   @param[in]  VariableName                Name of Variable to be found.
 236   @param[in]  VendorGuid                  Variable vendor GUID.
 237   @param[in]  Data                        Data pointer.
 238   @param[in]  DataSize                    Size of Data found. If size is less than the
 239                                           data, this value contains the required size.
 240   @param[in]  Attributes                  Attribute value of the variable.
 241
 242   @return EFI_INVALID_PARAMETER           Invalid parameter.
 243   @return EFI_SECURITY_VIOLATION          The variable does NOT pass the validation
 244                                           check carried out by the firmware.
 245   @return EFI_SUCCESS                     Variable pass validation successfully.
 246
 247 **/
 248 EFI_STATUS
 249 ProcessVarWithKek (
 250   IN  CHAR16    *VariableName,
 251   IN  EFI_GUID  *VendorGuid,
 252   IN  VOID      *Data,
 253   IN  UINTN     DataSize,
 254   IN  UINT32    Attributes OPTIONAL
 255   );
 256
 257 /**
 258   Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
 259
 260   Caution: This function may receive untrusted input.
 261   This function may be invoked in SMM mode, and datasize and data are external input.
 262   This function will do basic validation, before parse the data.
 263   This function will parse the authentication carefully to avoid security issues, like
 264   buffer overflow, integer overflow.
 265   This function will check attribute carefully to avoid authentication bypass.
 266
 267   @param[in]  VariableName                Name of the variable.
 268   @param[in]  VendorGuid                  Variable vendor GUID.
 269   @param[in]  Data                        Data pointer.
 270   @param[in]  DataSize                    Size of Data.
 271   @param[in]  Attributes                  Attribute value of the variable.
 272
 273   @return EFI_INVALID_PARAMETER           Invalid parameter.
 274   @return EFI_WRITE_PROTECTED             Variable is write-protected and needs authentication with
 275                                           EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS or EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set.
 276   @return EFI_OUT_OF_RESOURCES            The Database to save the public key is full.
 277   @return EFI_SECURITY_VIOLATION          The variable is with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS
 278                                           set, but the AuthInfo does NOT pass the validation
 279                                           check carried out by the firmware.
 280   @return EFI_SUCCESS                     Variable is not write-protected or pass validation successfully.
 281
 282 **/
 283 EFI_STATUS
 284 ProcessVariable (
 285   IN     CHAR16    *VariableName,
 286   IN     EFI_GUID  *VendorGuid,
 287   IN     VOID      *Data,
 288   IN     UINTN     DataSize,
 289   IN     UINT32    Attributes
 290   );
 291
 292 /**
 293   Finds variable in storage blocks of volatile and non-volatile storage areas.
 294
 295   This code finds variable in storage blocks of volatile and non-volatile storage areas.
 296   If VariableName is an empty string, then we just return the first
 297   qualified variable without comparing VariableName and VendorGuid.
 298
 299   @param[in]  VariableName          Name of the variable to be found.
 300   @param[in]  VendorGuid            Variable vendor GUID to be found.
 301   @param[out] Data                  Pointer to data address.
 302   @param[out] DataSize              Pointer to data size.
 303
 304   @retval EFI_INVALID_PARAMETER     If VariableName is not an empty string,
 305                                     while VendorGuid is NULL.
 306   @retval EFI_SUCCESS               Variable successfully found.
 307   @retval EFI_NOT_FOUND             Variable not found
 308
 309 **/
 310 EFI_STATUS
 311 AuthServiceInternalFindVariable (
 312   IN  CHAR16    *VariableName,
 313   IN  EFI_GUID  *VendorGuid,
 314   OUT VOID      **Data,
 315   OUT UINTN     *DataSize
 316   );
 317
 318 /**
 319   Update the variable region with Variable information.
 320
 321   @param[in] VariableName           Name of variable.
 322   @param[in] VendorGuid             Guid of variable.
 323   @param[in] Data                   Data pointer.
 324   @param[in] DataSize               Size of Data.
 325   @param[in] Attributes             Attribute value of the variable.
 326
 327   @retval EFI_SUCCESS               The update operation is success.
 328   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 329   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 330   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 331
 332 **/
 333 EFI_STATUS
 334 AuthServiceInternalUpdateVariable (
 335   IN CHAR16    *VariableName,
 336   IN EFI_GUID  *VendorGuid,
 337   IN VOID      *Data,
 338   IN UINTN     DataSize,
 339   IN UINT32    Attributes
 340   );
 341
 342 /**
 343   Update the variable region with Variable information.
 344
 345   @param[in] VariableName           Name of variable.
 346   @param[in] VendorGuid             Guid of variable.
 347   @param[in] Data                   Data pointer.
 348   @param[in] DataSize               Size of Data.
 349   @param[in] Attributes             Attribute value of the variable.
 350   @param[in] TimeStamp              Value of associated TimeStamp.
 351
 352   @retval EFI_SUCCESS               The update operation is success.
 353   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 354   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 355   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 356
 357 **/
 358 EFI_STATUS
 359 AuthServiceInternalUpdateVariableWithTimeStamp (
 360   IN CHAR16    *VariableName,
 361   IN EFI_GUID  *VendorGuid,
 362   IN VOID      *Data,
 363   IN UINTN     DataSize,
 364   IN UINT32    Attributes,
 365   IN EFI_TIME  *TimeStamp
 366   );
 367
 368 #endif