SecurityPkg/VariableAuthenticated/RuntimeDxe/AuthService.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 Copyright (c) 2009 - 2012, 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 _AUTHSERVICE_H_
  17 #define _AUTHSERVICE_H_
  18
  19 #define EFI_CERT_TYPE_RSA2048_SHA256_SIZE 256
  20 #define EFI_CERT_TYPE_RSA2048_SIZE        256
  21
  22 ///
  23 /// Size of AuthInfo prior to the data payload.
  24 ///
  25 #define AUTHINFO_SIZE ((OFFSET_OF (EFI_VARIABLE_AUTHENTICATION, AuthInfo)) + \
  26                        (OFFSET_OF (WIN_CERTIFICATE_UEFI_GUID, CertData)) + \
  27                        sizeof (EFI_CERT_BLOCK_RSA_2048_SHA256))
  28
  29 #define AUTHINFO2_SIZE(VarAuth2) ((OFFSET_OF (EFI_VARIABLE_AUTHENTICATION_2, AuthInfo)) + \
  30                                   (UINTN) ((EFI_VARIABLE_AUTHENTICATION_2 *) (VarAuth2))->AuthInfo.Hdr.dwLength)
  31
  32 #define OFFSET_OF_AUTHINFO2_CERT_DATA ((OFFSET_OF (EFI_VARIABLE_AUTHENTICATION_2, AuthInfo)) + \
  33                                        (OFFSET_OF (WIN_CERTIFICATE_UEFI_GUID, CertData)))
  34
  35 ///
  36 /// "AuthVarKeyDatabase" variable for the Public Key store.
  37 ///
  38 #define AUTHVAR_KEYDB_NAME      L"AuthVarKeyDatabase"
  39 #define AUTHVAR_KEYDB_NAME_SIZE 38
  40
  41 ///
  42 /// Max size of public key database, restricted by max individal EFI varible size, exclude variable header and name size.
  43 ///
  44 #define MAX_KEYDB_SIZE  (FixedPcdGet32 (PcdMaxVariableSize) - sizeof (VARIABLE_HEADER) - AUTHVAR_KEYDB_NAME_SIZE)
  45 #define MAX_KEY_NUM     (MAX_KEYDB_SIZE / EFI_CERT_TYPE_RSA2048_SIZE)
  46
  47 ///
  48 /// Struct to record signature requirement defined by UEFI spec.
  49 /// For SigHeaderSize and SigDataSize, ((UINT32) ~0) means NO exact length requirement for this field.
  50 ///
  51 typedef struct {
  52   EFI_GUID    SigType;
  53   // Expected SignatureHeader size in Bytes.
  54   UINT32      SigHeaderSize;
  55   // Expected SignatureData size in Bytes.
  56   UINT32      SigDataSize;
  57 } EFI_SIGNATURE_ITEM;
  58
  59 typedef enum {
  60   AuthVarTypePk,
  61   AuthVarTypeKek,
  62   AuthVarTypePriv,
  63   AuthVarTypePayload
  64 } AUTHVAR_TYPE;
  65
  66 #pragma pack(1)
  67 typedef struct {
  68   EFI_GUID    VendorGuid;
  69   UINT32      CertNodeSize;
  70   UINT32      NameSize;
  71   UINT32      CertDataSize;
  72   /// CHAR16  VariableName[NameSize];
  73   /// UINT8   CertData[CertDataSize];
  74 } AUTH_CERT_DB_DATA;
  75 #pragma pack()
  76
  77 /**
  78   Process variable with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS/EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set.
  79
  80   Caution: This function may receive untrusted input.
  81   This function may be invoked in SMM mode, and datasize and data are external input.
  82   This function will do basic validation, before parse the data.
  83   This function will parse the authentication carefully to avoid security issues, like
  84   buffer overflow, integer overflow.
  85   This function will check attribute carefully to avoid authentication bypass.
  86
  87   @param[in]  VariableName                Name of Variable to be found.
  88   @param[in]  VendorGuid                  Variable vendor GUID.
  89
  90   @param[in]  Data                        Data pointer.
  91   @param[in]  DataSize                    Size of Data found. If size is less than the
  92                                           data, this value contains the required size.
  93   @param[in]  Variable                    The variable information which is used to keep track of variable usage.
  94   @param[in]  Attributes                  Attribute value of the variable.
  95
  96   @return EFI_INVALID_PARAMETER           Invalid parameter
  97   @return EFI_WRITE_PROTECTED             Variable is write-protected and needs authentication with
  98                                           EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS set.
  99   @return EFI_SECURITY_VIOLATION          The variable is with EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS
 100                                           set, but the AuthInfo does NOT pass the validation
 101                                           check carried out by the firmware.
 102   @return EFI_SUCCESS                     Variable is not write-protected, or passed validation successfully.
 103
 104 **/
 105 EFI_STATUS
 106 ProcessVariable (
 107   IN     CHAR16                             *VariableName,
 108   IN     EFI_GUID                           *VendorGuid,
 109   IN     VOID                               *Data,
 110   IN     UINTN                              DataSize,
 111   IN     VARIABLE_POINTER_TRACK             *Variable,
 112   IN     UINT32                             Attributes
 113   );
 114
 115 /**
 116   Update platform mode.
 117
 118   @param[in]      Mode                    SETUP_MODE or USER_MODE.
 119
 120   @return EFI_INVALID_PARAMETER           Invalid parameter.
 121   @return EFI_SUCCESS                     Update platform mode successfully.
 122
 123 **/
 124 EFI_STATUS
 125 UpdatePlatformMode (
 126   IN  UINT32                    Mode
 127   );
 128
 129 /**
 130   Initializes for authenticated varibale service.
 131
 132   @retval EFI_SUCCESS           Function successfully executed.
 133   @retval EFI_OUT_OF_RESOURCES  Fail to allocate enough memory resource.
 134
 135 **/
 136 EFI_STATUS
 137 AutenticatedVariableServiceInitialize (
 138   VOID
 139   );
 140
 141 /**
 142   Initializes for cryptlib service before use, include register algrithm and allocate scratch.
 143
 144 **/
 145 VOID
 146 CryptLibraryInitialize (
 147   VOID
 148   );
 149
 150 /**
 151   Check input data form to make sure it is a valid EFI_SIGNATURE_LIST for PK/KEK variable.
 152
 153   @param[in]  VariableName                Name of Variable to be check.
 154   @param[in]  VendorGuid                  Variable vendor GUID.
 155   @param[in]  Data                        Point to the variable data to be checked.
 156   @param[in]  DataSize                    Size of Data.
 157
 158   @return EFI_INVALID_PARAMETER           Invalid signature list format.
 159   @return EFI_SUCCESS                     Passed signature list format check successfully.
 160
 161 **/
 162 EFI_STATUS
 163 CheckSignatureListFormat(
 164   IN  CHAR16                    *VariableName,
 165   IN  EFI_GUID                  *VendorGuid,
 166   IN  VOID                      *Data,
 167   IN  UINTN                     DataSize
 168   );
 169
 170 /**
 171   Process variable with platform key for verification.
 172
 173   Caution: This function may receive untrusted input.
 174   This function may be invoked in SMM mode, and datasize and data are external input.
 175   This function will do basic validation, before parse the data.
 176   This function will parse the authentication carefully to avoid security issues, like
 177   buffer overflow, integer overflow.
 178   This function will check attribute carefully to avoid authentication bypass.
 179
 180   @param[in]  VariableName                Name of Variable to be found.
 181   @param[in]  VendorGuid                  Variable vendor GUID.
 182   @param[in]  Data                        Data pointer.
 183   @param[in]  DataSize                    Size of Data found. If size is less than the
 184                                           data, this value contains the required size.
 185   @param[in]  Variable                    The variable information which is used to keep track of variable usage.
 186   @param[in]  Attributes                  Attribute value of the variable.
 187   @param[in]  IsPk                        Indicate whether it is to process pk.
 188
 189   @return EFI_INVALID_PARAMETER           Invalid parameter
 190   @return EFI_SECURITY_VIOLATION          The variable does NOT pass the validation
 191                                           check carried out by the firmware.
 192   @return EFI_SUCCESS                     Variable passed validation successfully.
 193
 194 **/
 195 EFI_STATUS
 196 ProcessVarWithPk (
 197   IN  CHAR16                    *VariableName,
 198   IN  EFI_GUID                  *VendorGuid,
 199   IN  VOID                      *Data,
 200   IN  UINTN                     DataSize,
 201   IN  VARIABLE_POINTER_TRACK    *Variable,
 202   IN  UINT32                    Attributes OPTIONAL,
 203   IN  BOOLEAN                   IsPk
 204   );
 205
 206 /**
 207   Process variable with key exchange 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]  Variable                    The variable information that is used to keep track of variable usage.
 222   @param[in]  Attributes                  Attribute value of the variable.
 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 ProcessVarWithKek (
 232   IN  CHAR16                    *VariableName,
 233   IN  EFI_GUID                  *VendorGuid,
 234   IN  VOID                      *Data,
 235   IN  UINTN                     DataSize,
 236   IN  VARIABLE_POINTER_TRACK    *Variable,
 237   IN  UINT32                    Attributes OPTIONAL
 238   );
 239
 240 /**
 241   Merge two buffers which formatted as EFI_SIGNATURE_LIST. Only the new EFI_SIGNATURE_DATA
 242   will be appended to the original EFI_SIGNATURE_LIST, duplicate EFI_SIGNATURE_DATA
 243   will be ignored.
 244
 245   @param[in, out]  Data            Pointer to original EFI_SIGNATURE_LIST.
 246   @param[in]       DataSize        Size of Data buffer.
 247   @param[in]       NewData         Pointer to new EFI_SIGNATURE_LIST to be appended.
 248   @param[in]       NewDataSize     Size of NewData buffer.
 249
 250   @return Size of the merged buffer.
 251
 252 **/
 253 UINTN
 254 AppendSignatureList (
 255   IN  OUT VOID            *Data,
 256   IN  UINTN               DataSize,
 257   IN  VOID                *NewData,
 258   IN  UINTN               NewDataSize
 259   );
 260
 261 /**
 262   Compare two EFI_TIME data.
 263
 264
 265   @param FirstTime           A pointer to the first EFI_TIME data.
 266   @param SecondTime          A pointer to the second EFI_TIME data.
 267
 268   @retval  TRUE              The FirstTime is not later than the SecondTime.
 269   @retval  FALSE             The FirstTime is later than the SecondTime.
 270
 271 **/
 272 BOOLEAN
 273 CompareTimeStamp (
 274   IN EFI_TIME               *FirstTime,
 275   IN EFI_TIME               *SecondTime
 276   );
 277
 278
 279 /**
 280   Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set
 281
 282   Caution: This function may receive untrusted input.
 283   This function may be invoked in SMM mode, and datasize and data are external input.
 284   This function will do basic validation, before parse the data.
 285   This function will parse the authentication carefully to avoid security issues, like
 286   buffer overflow, integer overflow.
 287
 288   @param[in]  VariableName                Name of Variable to be found.
 289   @param[in]  VendorGuid                  Variable vendor GUID.
 290   @param[in]  Data                        Data pointer.
 291   @param[in]  DataSize                    Size of Data found. If size is less than the
 292                                           data, this value contains the required size.
 293   @param[in]  Variable                    The variable information which is used to keep track of variable usage.
 294   @param[in]  Attributes                  Attribute value of the variable.
 295   @param[in]  AuthVarType                 Verify against PK or KEK database or private database.
 296   @param[out] VarDel                      Delete the variable or not.
 297
 298   @retval EFI_INVALID_PARAMETER           Invalid parameter.
 299   @retval EFI_SECURITY_VIOLATION          The variable does NOT pass the validation
 300                                           check carried out by the firmware.
 301   @retval EFI_OUT_OF_RESOURCES            Failed to process variable due to lack
 302                                           of resources.
 303   @retval EFI_SUCCESS                     Variable pass validation successfully.
 304
 305 **/
 306 EFI_STATUS
 307 VerifyTimeBasedPayload (
 308   IN     CHAR16                             *VariableName,
 309   IN     EFI_GUID                           *VendorGuid,
 310   IN     VOID                               *Data,
 311   IN     UINTN                              DataSize,
 312   IN     VARIABLE_POINTER_TRACK             *Variable,
 313   IN     UINT32                             Attributes,
 314   IN     AUTHVAR_TYPE                       AuthVarType,
 315   OUT    BOOLEAN                            *VarDel
 316   );
 317
 318 extern UINT8  mPubKeyStore[MAX_KEYDB_SIZE];
 319 extern UINT32 mPubKeyNumber;
 320 extern VOID   *mHashCtx;
 321 extern VOID   *mStorageArea;
 322 extern UINT8  *mSerializationRuntimeBuffer;
 323
 324 #endif