MdeModulePkg/Include/Library/AuthVariableLib.h

   1 /** @file
   2   Provides services to initialize and process authenticated variables.
   3
   4 Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials are licensed and made available under
   6 the terms and conditions of the BSD License that accompanies this distribution.
   7 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 _AUTH_VARIABLE_LIB_H_
  16 #define _AUTH_VARIABLE_LIB_H_
  17
  18 #include <Protocol/VarCheck.h>
  19
  20 ///
  21 /// Size of AuthInfo prior to the data payload.
  22 ///
  23 #define AUTHINFO_SIZE ((OFFSET_OF (EFI_VARIABLE_AUTHENTICATION, AuthInfo)) + \
  24                        (OFFSET_OF (WIN_CERTIFICATE_UEFI_GUID, CertData)) + \
  25                        sizeof (EFI_CERT_BLOCK_RSA_2048_SHA256))
  26
  27 #define AUTHINFO2_SIZE(VarAuth2) ((OFFSET_OF (EFI_VARIABLE_AUTHENTICATION_2, AuthInfo)) + \
  28                                   (UINTN) ((EFI_VARIABLE_AUTHENTICATION_2 *) (VarAuth2))->AuthInfo.Hdr.dwLength)
  29
  30 #define OFFSET_OF_AUTHINFO2_CERT_DATA ((OFFSET_OF (EFI_VARIABLE_AUTHENTICATION_2, AuthInfo)) + \
  31                                        (OFFSET_OF (WIN_CERTIFICATE_UEFI_GUID, CertData)))
  32
  33 typedef struct {
  34   CHAR16        *VariableName;
  35   EFI_GUID      *VendorGuid;
  36   UINT32        Attributes;
  37   UINTN         DataSize;
  38   VOID          *Data;
  39   UINT32        PubKeyIndex;
  40   UINT64        MonotonicCount;
  41   EFI_TIME      *TimeStamp;
  42 } AUTH_VARIABLE_INFO;
  43
  44 /**
  45   Finds variable in storage blocks of volatile and non-volatile storage areas.
  46
  47   This code finds variable in storage blocks of volatile and non-volatile storage areas.
  48   If VariableName is an empty string, then we just return the first
  49   qualified variable without comparing VariableName and VendorGuid.
  50
  51   @param[in]  VariableName          Name of the variable to be found.
  52   @param[in]  VendorGuid            Variable vendor GUID to be found.
  53   @param[out] AuthVariableInfo      Pointer to AUTH_VARIABLE_INFO structure for
  54                                     output of the variable found.
  55
  56   @retval EFI_INVALID_PARAMETER     If VariableName is not an empty string,
  57                                     while VendorGuid is NULL.
  58   @retval EFI_SUCCESS               Variable successfully found.
  59   @retval EFI_NOT_FOUND             Variable not found
  60
  61 **/
  62 typedef
  63 EFI_STATUS
  64 (EFIAPI *AUTH_VAR_LIB_FIND_VARIABLE) (
  65   IN  CHAR16                *VariableName,
  66   IN  EFI_GUID              *VendorGuid,
  67   OUT AUTH_VARIABLE_INFO    *AuthVariableInfo
  68   );
  69
  70 /**
  71   Finds next variable in storage blocks of volatile and non-volatile storage areas.
  72
  73   This code finds next variable in storage blocks of volatile and non-volatile storage areas.
  74   If VariableName is an empty string, then we just return the first
  75   qualified variable without comparing VariableName and VendorGuid.
  76
  77   @param[in]  VariableName          Name of the variable to be found.
  78   @param[in]  VendorGuid            Variable vendor GUID to be found.
  79   @param[out] AuthVariableInfo      Pointer to AUTH_VARIABLE_INFO structure for
  80                                     output of the next variable.
  81
  82   @retval EFI_INVALID_PARAMETER     If VariableName is not an empty string,
  83                                     while VendorGuid is NULL.
  84   @retval EFI_SUCCESS               Variable successfully found.
  85   @retval EFI_NOT_FOUND             Variable not found
  86
  87 **/
  88 typedef
  89 EFI_STATUS
  90 (EFIAPI *AUTH_VAR_LIB_FIND_NEXT_VARIABLE) (
  91   IN  CHAR16                *VariableName,
  92   IN  EFI_GUID              *VendorGuid,
  93   OUT AUTH_VARIABLE_INFO    *AuthVariableInfo
  94   );
  95
  96 /**
  97   Update the variable region with Variable information.
  98
  99   @param[in] AuthVariableInfo       Pointer AUTH_VARIABLE_INFO structure for
 100                                     input of the variable.
 101
 102   @retval EFI_SUCCESS               The update operation is success.
 103   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 104   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 105   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 106
 107 **/
 108 typedef
 109 EFI_STATUS
 110 (EFIAPI *AUTH_VAR_LIB_UPDATE_VARIABLE) (
 111   IN AUTH_VARIABLE_INFO     *AuthVariableInfo
 112   );
 113
 114 /**
 115   Get scratch buffer.
 116
 117   @param[in, out] ScratchBufferSize Scratch buffer size. If input size is greater than
 118                                     the maximum supported buffer size, this value contains
 119                                     the maximum supported buffer size as output.
 120   @param[out]     ScratchBuffer     Pointer to scratch buffer address.
 121
 122   @retval EFI_SUCCESS       Get scratch buffer successfully.
 123   @retval EFI_UNSUPPORTED   If input size is greater than the maximum supported buffer size.
 124
 125 **/
 126 typedef
 127 EFI_STATUS
 128 (EFIAPI *AUTH_VAR_LIB_GET_SCRATCH_BUFFER) (
 129   IN OUT UINTN      *ScratchBufferSize,
 130   OUT    VOID       **ScratchBuffer
 131   );
 132
 133 /**
 134   This function is to check if the remaining variable space is enough to set
 135   all Variables from argument list successfully. The purpose of the check
 136   is to keep the consistency of the Variables to be in variable storage.
 137
 138   Note: Variables are assumed to be in same storage.
 139   The set sequence of Variables will be same with the sequence of VariableEntry from argument list,
 140   so follow the argument sequence to check the Variables.
 141
 142   @param[in] Attributes         Variable attributes for Variable entries.
 143   @param ...                    The variable argument list with type VARIABLE_ENTRY_CONSISTENCY *.
 144                                 A NULL terminates the list. The VariableSize of
 145                                 VARIABLE_ENTRY_CONSISTENCY is the variable data size as input.
 146                                 It will be changed to variable total size as output.
 147
 148   @retval TRUE                  Have enough variable space to set the Variables successfully.
 149   @retval FALSE                 No enough variable space to set the Variables successfully.
 150
 151 **/
 152 typedef
 153 BOOLEAN
 154 (EFIAPI *AUTH_VAR_LIB_CHECK_REMAINING_SPACE) (
 155   IN UINT32                     Attributes,
 156   ...
 157   );
 158
 159 /**
 160   Return TRUE if at OS runtime.
 161
 162   @retval TRUE If at OS runtime.
 163   @retval FALSE If at boot time.
 164
 165 **/
 166 typedef
 167 BOOLEAN
 168 (EFIAPI *AUTH_VAR_LIB_AT_RUNTIME) (
 169   VOID
 170   );
 171
 172 #define AUTH_VAR_LIB_CONTEXT_IN_STRUCT_VERSION  0x01
 173
 174 typedef struct {
 175   UINTN                                 StructVersion;
 176   UINTN                                 StructSize;
 177   //
 178   // Reflect the overhead associated with the saving
 179   // of a single EFI authenticated variable with the exception
 180   // of the overhead associated with the length
 181   // of the string name of the EFI variable.
 182   //
 183   UINTN                                 MaxAuthVariableSize;
 184   AUTH_VAR_LIB_FIND_VARIABLE            FindVariable;
 185   AUTH_VAR_LIB_FIND_NEXT_VARIABLE       FindNextVariable;
 186   AUTH_VAR_LIB_UPDATE_VARIABLE          UpdateVariable;
 187   AUTH_VAR_LIB_GET_SCRATCH_BUFFER       GetScratchBuffer;
 188   AUTH_VAR_LIB_CHECK_REMAINING_SPACE    CheckRemainingSpaceForConsistency;
 189   AUTH_VAR_LIB_AT_RUNTIME               AtRuntime;
 190 } AUTH_VAR_LIB_CONTEXT_IN;
 191
 192 #define AUTH_VAR_LIB_CONTEXT_OUT_STRUCT_VERSION 0x01
 193
 194 typedef struct {
 195   UINTN                                 StructVersion;
 196   UINTN                                 StructSize;
 197   //
 198   // Caller needs to set variable property for the variables.
 199   //
 200   VARIABLE_ENTRY_PROPERTY               *AuthVarEntry;
 201   UINTN                                 AuthVarEntryCount;
 202   //
 203   // Caller needs to ConvertPointer() for the pointers.
 204   //
 205   VOID                                  ***AddressPointer;
 206   UINTN                                 AddressPointerCount;
 207 } AUTH_VAR_LIB_CONTEXT_OUT;
 208
 209 /**
 210   Initialization for authenticated varibale services.
 211   If this initialization returns error status, other APIs will not work
 212   and expect to be not called then.
 213
 214   @param[in]  AuthVarLibContextIn   Pointer to input auth variable lib context.
 215   @param[out] AuthVarLibContextOut  Pointer to output auth variable lib context.
 216
 217   @retval EFI_SUCCESS               Function successfully executed.
 218   @retval EFI_INVALID_PARAMETER     If AuthVarLibContextIn == NULL or AuthVarLibContextOut == NULL.
 219   @retval EFI_OUT_OF_RESOURCES      Fail to allocate enough resource.
 220   @retval EFI_UNSUPPORTED           Unsupported to process authenticated variable.
 221
 222 **/
 223 EFI_STATUS
 224 EFIAPI
 225 AuthVariableLibInitialize (
 226   IN  AUTH_VAR_LIB_CONTEXT_IN   *AuthVarLibContextIn,
 227   OUT AUTH_VAR_LIB_CONTEXT_OUT  *AuthVarLibContextOut
 228   );
 229
 230 /**
 231   Process variable with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS set.
 232
 233   @param[in] VariableName           Name of the variable.
 234   @param[in] VendorGuid             Variable vendor GUID.
 235   @param[in] Data                   Data pointer.
 236   @param[in] DataSize               Size of Data.
 237   @param[in] Attributes             Attribute value of the variable.
 238
 239   @retval EFI_SUCCESS               The firmware has successfully stored the variable and its data as
 240                                     defined by the Attributes.
 241   @retval EFI_INVALID_PARAMETER     Invalid parameter.
 242   @retval EFI_WRITE_PROTECTED       Variable is write-protected.
 243   @retval EFI_OUT_OF_RESOURCES      There is not enough resource.
 244   @retval EFI_SECURITY_VIOLATION    The variable is with EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACESS
 245                                     set, but the AuthInfo does NOT pass the validation
 246                                     check carried out by the firmware.
 247   @retval EFI_UNSUPPORTED           Unsupported to process authenticated variable.
 248
 249 **/
 250 EFI_STATUS
 251 EFIAPI
 252 AuthVariableLibProcessVariable (
 253   IN CHAR16         *VariableName,
 254   IN EFI_GUID       *VendorGuid,
 255   IN VOID           *Data,
 256   IN UINTN          DataSize,
 257   IN UINT32         Attributes
 258   );
 259
 260 #endif