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   Clean up signer's certificates for common authenticated variable
 191   by corresponding VariableName and VendorGuid from "certdb".
 192   Sytem may break down during Timebased Variable update & certdb update,
 193   make them inconsistent,  this function is called in AuthVariable Init to ensure
 194   consistency
 195
 196   @retval  EFI_NOT_FOUND         Fail to find matching certs.
 197   @retval  EFI_SUCCESS           Find matching certs and output parameters.
 198
 199 **/
 200 EFI_STATUS
 201 CleanCertsFromDb (
 202   VOID
 203   );
 204
 205 /**
 206   Filter out the duplicated EFI_SIGNATURE_DATA from the new data by comparing to the original data.
 207
 208   @param[in]        Data          Pointer to original EFI_SIGNATURE_LIST.
 209   @param[in]        DataSize      Size of Data buffer.
 210   @param[in, out]   NewData       Pointer to new EFI_SIGNATURE_LIST.
 211   @param[in, out]   NewDataSize   Size of NewData buffer.
 212
 213 **/
 214 EFI_STATUS
 215 FilterSignatureList (
 216   IN     VOID       *Data,
 217   IN     UINTN      DataSize,
 218   IN OUT VOID       *NewData,
 219   IN OUT UINTN      *NewDataSize
 220   );
 221
 222 /**
 223   Process variable with platform key for verification.
 224
 225   Caution: This function may receive untrusted input.
 226   This function may be invoked in SMM mode, and datasize and data are external input.
 227   This function will do basic validation, before parse the data.
 228   This function will parse the authentication carefully to avoid security issues, like
 229   buffer overflow, integer overflow.
 230   This function will check attribute carefully to avoid authentication bypass.
 231
 232   @param[in]  VariableName                Name of Variable to be found.
 233   @param[in]  VendorGuid                  Variable vendor GUID.
 234   @param[in]  Data                        Data pointer.
 235   @param[in]  DataSize                    Size of Data found. If size is less than the
 236                                           data, this value contains the required size.
 237   @param[in]  Attributes                  Attribute value of the variable
 238   @param[in]  IsPk                        Indicate whether it is to process pk.
 239
 240   @return EFI_INVALID_PARAMETER           Invalid parameter.
 241   @return EFI_SECURITY_VIOLATION          The variable does NOT pass the validation.
 242                                           check carried out by the firmware.
 243   @return EFI_SUCCESS                     Variable passed validation successfully.
 244
 245 **/
 246 EFI_STATUS
 247 ProcessVarWithPk (
 248   IN  CHAR16                    *VariableName,
 249   IN  EFI_GUID                  *VendorGuid,
 250   IN  VOID                      *Data,
 251   IN  UINTN                     DataSize,
 252   IN  UINT32                    Attributes OPTIONAL,
 253   IN  BOOLEAN                   IsPk
 254   );
 255
 256 /**
 257   Process variable with key exchange key for verification.
 258
 259   Caution: This function may receive untrusted input.
 260   This function may be invoked in SMM mode, and datasize and data are external input.
 261   This function will do basic validation, before parse the data.
 262   This function will parse the authentication carefully to avoid security issues, like
 263   buffer overflow, integer overflow.
 264   This function will check attribute carefully to avoid authentication bypass.
 265
 266   @param[in]  VariableName                Name of Variable to be found.
 267   @param[in]  VendorGuid                  Variable vendor GUID.
 268   @param[in]  Data                        Data pointer.
 269   @param[in]  DataSize                    Size of Data found. If size is less than the
 270                                           data, this value contains the required size.
 271   @param[in]  Attributes                  Attribute value of the variable.
 272
 273   @return EFI_INVALID_PARAMETER           Invalid parameter.
 274   @return EFI_SECURITY_VIOLATION          The variable does NOT pass the validation
 275                                           check carried out by the firmware.
 276   @return EFI_SUCCESS                     Variable pass validation successfully.
 277
 278 **/
 279 EFI_STATUS
 280 ProcessVarWithKek (
 281   IN  CHAR16                               *VariableName,
 282   IN  EFI_GUID                             *VendorGuid,
 283   IN  VOID                                 *Data,
 284   IN  UINTN                                DataSize,
 285   IN  UINT32                               Attributes OPTIONAL
 286   );
 287
 288 /**
 289   Process variable with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS/EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
 290
 291   Caution: This function may receive untrusted input.
 292   This function may be invoked in SMM mode, and datasize and data are external input.
 293   This function will do basic validation, before parse the data.
 294   This function will parse the authentication carefully to avoid security issues, like
 295   buffer overflow, integer overflow.
 296   This function will check attribute carefully to avoid authentication bypass.
 297
 298   @param[in]  VariableName                Name of the variable.
 299   @param[in]  VendorGuid                  Variable vendor GUID.
 300   @param[in]  Data                        Data pointer.
 301   @param[in]  DataSize                    Size of Data.
 302   @param[in]  Attributes                  Attribute value of the variable.
 303
 304   @return EFI_INVALID_PARAMETER           Invalid parameter.
 305   @return EFI_WRITE_PROTECTED             Variable is write-protected and needs authentication with
 306                                           EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS set.
 307   @return EFI_OUT_OF_RESOURCES            The Database to save the public key is full.
 308   @return EFI_SECURITY_VIOLATION          The variable is with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS
 309                                           set, but the AuthInfo does NOT pass the validation
 310                                           check carried out by the firmware.
 311   @return EFI_SUCCESS                     Variable is not write-protected or pass validation successfully.
 312
 313 **/
 314 EFI_STATUS
 315 ProcessVariable (
 316   IN     CHAR16                             *VariableName,
 317   IN     EFI_GUID                           *VendorGuid,
 318   IN     VOID                               *Data,
 319   IN     UINTN                              DataSize,
 320   IN     UINT32                             Attributes OPTIONAL
 321   );
 322
 323 /**
 324   Finds variable in storage blocks of volatile and non-volatile storage areas.
 325
 326   This code finds variable in storage blocks of volatile and non-volatile storage areas.
 327   If VariableName is an empty string, then we just return the first
 328   qualified variable without comparing VariableName and VendorGuid.
 329
 330   @param[in]  VariableName          Name of the variable to be found.
 331   @param[in]  VendorGuid            Variable vendor GUID to be found.
 332   @param[out] Data                  Pointer to data address.
 333   @param[out] DataSize              Pointer to data size.
 334
 335   @retval EFI_INVALID_PARAMETER     If VariableName is not an empty string,
 336                                     while VendorGuid is NULL.
 337   @retval EFI_SUCCESS               Variable successfully found.
 338   @retval EFI_NOT_FOUND             Variable not found
 339
 340 **/
 341 EFI_STATUS
 342 AuthServiceInternalFindVariable (
 343   IN  CHAR16        *VariableName,
 344   IN  EFI_GUID      *VendorGuid,
 345   OUT VOID          **Data,
 346   OUT UINTN         *DataSize
 347   );
 348
 349 /**
 350   Update the variable region with Variable information.
 351
 352   @param[in] VariableName           Name of variable.
 353   @param[in] VendorGuid             Guid of variable.
 354   @param[in] Data                   Data pointer.
 355   @param[in] DataSize               Size of Data.
 356   @param[in] Attributes             Attribute value of the variable.
 357
 358   @retval EFI_SUCCESS               The update operation is success.
 359   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 360   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 361   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 362
 363 **/
 364 EFI_STATUS
 365 AuthServiceInternalUpdateVariable (
 366   IN CHAR16         *VariableName,
 367   IN EFI_GUID       *VendorGuid,
 368   IN VOID           *Data,
 369   IN UINTN          DataSize,
 370   IN UINT32         Attributes
 371   );
 372
 373 /**
 374   Update the variable region with Variable information.
 375
 376   @param[in] VariableName           Name of variable.
 377   @param[in] VendorGuid             Guid of variable.
 378   @param[in] Data                   Data pointer.
 379   @param[in] DataSize               Size of Data.
 380   @param[in] Attributes             Attribute value of the variable.
 381   @param[in] KeyIndex               Index of associated public key.
 382   @param[in] MonotonicCount         Value of associated monotonic count.
 383
 384   @retval EFI_SUCCESS               The update operation is success.
 385   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 386   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 387   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 388
 389 **/
 390 EFI_STATUS
 391 AuthServiceInternalUpdateVariableWithMonotonicCount (
 392   IN CHAR16         *VariableName,
 393   IN EFI_GUID       *VendorGuid,
 394   IN VOID           *Data,
 395   IN UINTN          DataSize,
 396   IN UINT32         Attributes,
 397   IN UINT32         KeyIndex,
 398   IN UINT64         MonotonicCount
 399   );
 400
 401 /**
 402   Update the variable region with Variable information.
 403
 404   @param[in] VariableName           Name of variable.
 405   @param[in] VendorGuid             Guid of variable.
 406   @param[in] Data                   Data pointer.
 407   @param[in] DataSize               Size of Data.
 408   @param[in] Attributes             Attribute value of the variable.
 409   @param[in] TimeStamp              Value of associated TimeStamp.
 410
 411   @retval EFI_SUCCESS               The update operation is success.
 412   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 413   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 414   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 415
 416 **/
 417 EFI_STATUS
 418 AuthServiceInternalUpdateVariableWithTimeStamp (
 419   IN CHAR16         *VariableName,
 420   IN EFI_GUID       *VendorGuid,
 421   IN VOID           *Data,
 422   IN UINTN          DataSize,
 423   IN UINT32         Attributes,
 424   IN EFI_TIME       *TimeStamp
 425   );
 426
 427 #endif