MdeModulePkg/Include/Library/SecurityManagementLib.h

   1 /** @file
   2   This library class defines a set of interfaces to abstract the policy of
   3   security measurement by managing the different security measurement services.
   4   The library instances can be implemented according to the different security policy.
   5
   6 Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
   7 SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef __SECURITY_MANAGEMENT_LIB_H__
  12 #define __SECURITY_MANAGEMENT_LIB_H__
  13
  14 //
  15 // Authentication Operation defintions for User Identity (UID), Measured and Secure boot.
  16 //
  17 #define EFI_AUTH_OPERATION_NONE                0x00
  18 #define EFI_AUTH_OPERATION_VERIFY_IMAGE        0x01
  19 #define EFI_AUTH_OPERATION_DEFER_IMAGE_LOAD    0x02
  20 #define EFI_AUTH_OPERATION_MEASURE_IMAGE       0x04
  21 #define EFI_AUTH_OPERATION_CONNECT_POLICY      0x08
  22 //
  23 // Authentication State Operation will check the authentication status of a file.
  24 //
  25 #define EFI_AUTH_OPERATION_AUTHENTICATION_STATE  0x10
  26
  27 ///
  28 /// Image buffer is required by the security handler.
  29 ///
  30 #define EFI_AUTH_OPERATION_IMAGE_REQUIRED      0x80000000
  31
  32 /**
  33   The security handler is used to abstract platform-specific policy
  34   from the DXE core response to an attempt to use a file that returns a
  35   given status for the authentication check from the section extraction protocol.
  36
  37   The possible responses in a given SAP implementation may include locking
  38   flash upon failure to authenticate, attestation logging for all signed drivers,
  39   and other exception operations.  The File parameter allows for possible logging
  40   within the SAP of the driver.
  41
  42   If File is NULL, then EFI_INVALID_PARAMETER is returned.
  43
  44   If the file specified by File with an authentication status specified by
  45   AuthenticationStatus is safe for the DXE Core to use, then EFI_SUCCESS is returned.
  46
  47   If the file specified by File with an authentication status specified by
  48   AuthenticationStatus is not safe for the DXE Core to use under any circumstances,
  49   then EFI_ACCESS_DENIED is returned.
  50
  51   If the file specified by File with an authentication status specified by
  52   AuthenticationStatus is not safe for the DXE Core to use at the time, but it
  53   might be possible to use it at a future time, then EFI_SECURITY_VIOLATION is
  54   returned.
  55
  56   FileBuffer will be NULL and FileSize will be 0 if the handler being called
  57   did not set EFI_AUTH_OPERATION_IMAGE_REQUIRED when it was registered.
  58
  59   @param[in]    AuthenticationStatus
  60                            The authentication status returned from the security
  61                            measurement services for the input file.
  62   @param[in]    File       The pointer to the device path of the file that is
  63                            being dispatched. This will optionally be used for logging.
  64   @param[in]    FileBuffer The file buffer matches the input file device path.
  65   @param[in]    FileSize   The size of File buffer matches the input file device path.
  66
  67   @retval EFI_SUCCESS            The file specified by File did authenticate, and the
  68                                  platform policy dictates that the DXE Core may use File.
  69   @retval EFI_INVALID_PARAMETER  The file is NULL.
  70   @retval EFI_SECURITY_VIOLATION The file specified by File did not authenticate, and
  71                                  the platform policy dictates that File should be placed
  72                                  in the untrusted state. A file may be promoted from
  73                                  the untrusted to the trusted state at a future time
  74                                  with a call to the Trust() DXE Service.
  75   @retval EFI_ACCESS_DENIED      The file specified by File did not authenticate, and
  76                                  the platform policy dictates that File should not be
  77                                  used for any purpose.
  78
  79 **/
  80 typedef
  81 EFI_STATUS
  82 (EFIAPI *SECURITY_FILE_AUTHENTICATION_STATE_HANDLER)(
  83   IN  OUT   UINT32                     AuthenticationStatus,
  84   IN  CONST EFI_DEVICE_PATH_PROTOCOL   *File,
  85   IN  VOID                             *FileBuffer,
  86   IN  UINTN                            FileSize
  87   );
  88
  89 /**
  90   Register security measurement handler with its operation type. Different
  91   handlers with the same operation can all be registered.
  92
  93   If SecurityHandler is NULL, then ASSERT().
  94   If no enough resources available to register new handler, then ASSERT().
  95   If AuthenticationOperation is not recongnized, then ASSERT().
  96   If the previous register handler can't be executed before the later register handler, then ASSERT().
  97
  98   @param[in]  SecurityHandler           The security measurement service handler to be registered.
  99   @param[in]  AuthenticationOperation   Theoperation type is specified for the registered handler.
 100
 101   @retval EFI_SUCCESS              The handlers were registered successfully.
 102 **/
 103 EFI_STATUS
 104 EFIAPI
 105 RegisterSecurityHandler (
 106   IN  SECURITY_FILE_AUTHENTICATION_STATE_HANDLER  SecurityHandler,
 107   IN  UINT32                                      AuthenticationOperation
 108   );
 109
 110 /**
 111   Execute registered handlers until one returns an error and that error is returned.
 112   If none of the handlers return an error, then EFI_SUCCESS is returned.
 113
 114   Before exectue handler, get the image buffer by file device path if a handler
 115   requires the image file. And return the image buffer to each handler when exectue handler.
 116
 117   The handlers are executed in same order to their registered order.
 118
 119   @param[in]  AuthenticationStatus
 120                            This is the authentication type returned from the Section
 121                            Extraction protocol. See the Section Extraction Protocol
 122                            Specification for details on this type.
 123   @param[in]  FilePath     This is a pointer to the device path of the file that is
 124                            being dispatched. This will optionally be used for logging.
 125
 126   @retval EFI_SUCCESS            The file specified by File authenticated when more
 127                                  than one security handler services were registered,
 128                                  or the file did not authenticate when no security
 129                                  handler service was registered. And the platform policy
 130                                  dictates that the DXE Core may use File.
 131   @retval EFI_INVALID_PARAMETER  File is NULL.
 132   @retval EFI_SECURITY_VIOLATION The file specified by File did not authenticate, and
 133                                  the platform policy dictates that File should be placed
 134                                  in the untrusted state. A file may be promoted from
 135                                  the untrusted to the trusted state at a future time
 136                                  with a call to the Trust() DXE Service.
 137   @retval EFI_ACCESS_DENIED      The file specified by File did not authenticate, and
 138                                  the platform policy dictates that File should not be
 139                                  used for any purpose.
 140 **/
 141 EFI_STATUS
 142 EFIAPI
 143 ExecuteSecurityHandlers (
 144   IN  UINT32                            AuthenticationStatus,
 145   IN  CONST EFI_DEVICE_PATH_PROTOCOL    *FilePath
 146   );
 147
 148 /**
 149   The security handler is used to abstracts security-specific functions from the DXE
 150   Foundation of UEFI Image Verification, Trusted Computing Group (TCG) measured boot,
 151   User Identity policy for image loading and consoles, and for purposes of
 152   handling GUIDed section encapsulations.
 153
 154   @param[in]    AuthenticationStatus
 155                            The authentication status for the input file.
 156   @param[in]    File       The pointer to the device path of the file that is
 157                            being dispatched. This will optionally be used for logging.
 158   @param[in]    FileBuffer A pointer to the buffer with the UEFI file image
 159   @param[in]    FileSize   The size of File buffer.
 160   @param[in]    BootPolicy A boot policy that was used to call LoadImage() UEFI service.
 161
 162   @retval EFI_SUCCESS             The file specified by DevicePath and non-NULL
 163                                   FileBuffer did authenticate, and the platform policy dictates
 164                                   that the DXE Foundation may use the file.
 165   @retval EFI_SUCCESS             The device path specified by NULL device path DevicePath
 166                                   and non-NULL FileBuffer did authenticate, and the platform
 167                                   policy dictates that the DXE Foundation may execute the image in
 168                                   FileBuffer.
 169   @retval EFI_SUCCESS             FileBuffer is NULL and current user has permission to start
 170                                   UEFI device drivers on the device path specified by DevicePath.
 171   @retval EFI_SECURITY_VIOLATION  The file specified by DevicePath and FileBuffer did not
 172                                   authenticate, and the platform policy dictates that the file should be
 173                                   placed in the untrusted state. The image has been added to the file
 174                                   execution table.
 175   @retval EFI_ACCESS_DENIED       The file specified by File and FileBuffer did not
 176                                   authenticate, and the platform policy dictates that the DXE
 177                                   Foundation may not use File.
 178   @retval EFI_SECURITY_VIOLATION  FileBuffer is NULL and the user has no
 179                                   permission to start UEFI device drivers on the device path specified
 180                                   by DevicePath.
 181   @retval EFI_SECURITY_VIOLATION  FileBuffer is not NULL and the user has no permission to load
 182                                   drivers from the device path specified by DevicePath. The
 183                                   image has been added into the list of the deferred images.
 184 **/
 185 typedef
 186 EFI_STATUS
 187 (EFIAPI *SECURITY2_FILE_AUTHENTICATION_HANDLER) (
 188   IN  UINT32                           AuthenticationStatus,
 189   IN  CONST EFI_DEVICE_PATH_PROTOCOL   *File,
 190   IN  VOID                             *FileBuffer,
 191   IN  UINTN                            FileSize,
 192   IN  BOOLEAN                          BootPolicy
 193   );
 194
 195 /**
 196   Register security measurement handler with its operation type. Different
 197   handlers with the same operation can all be registered.
 198
 199   If SecurityHandler is NULL, then ASSERT().
 200   If no enough resources available to register new handler, then ASSERT().
 201   If AuthenticationOperation is not recongnized, then ASSERT().
 202   If AuthenticationOperation is EFI_AUTH_OPERATION_NONE, then ASSERT().
 203   If the previous register handler can't be executed before the later register handler, then ASSERT().
 204
 205   @param[in]  Security2Handler          The security measurement service handler to be registered.
 206   @param[in]  AuthenticationOperation   The operation type is specified for the registered handler.
 207
 208   @retval EFI_SUCCESS              The handlers were registered successfully.
 209 **/
 210 EFI_STATUS
 211 EFIAPI
 212 RegisterSecurity2Handler (
 213   IN  SECURITY2_FILE_AUTHENTICATION_HANDLER       Security2Handler,
 214   IN  UINT32                                      AuthenticationOperation
 215   );
 216
 217 /**
 218   Execute registered handlers based on input AuthenticationOperation until
 219   one returns an error and that error is returned.
 220
 221   If none of the handlers return an error, then EFI_SUCCESS is returned.
 222   The handlers those satisfy AuthenticationOperation will only be executed.
 223   The handlers are executed in same order to their registered order.
 224
 225   @param[in]  AuthenticationOperation
 226                            The operation type specifies which handlers will be executed.
 227   @param[in]  AuthenticationStatus
 228                            The authentication status for the input file.
 229   @param[in]  File         This is a pointer to the device path of the file that is
 230                            being dispatched. This will optionally be used for logging.
 231   @param[in]  FileBuffer   A pointer to the buffer with the UEFI file image
 232   @param[in]  FileSize     The size of File buffer.
 233   @param[in]  BootPolicy   A boot policy that was used to call LoadImage() UEFI service.
 234
 235   @retval EFI_SUCCESS             The file specified by DevicePath and non-NULL
 236                                   FileBuffer did authenticate, and the platform policy dictates
 237                                   that the DXE Foundation may use the file.
 238   @retval EFI_SUCCESS             The device path specified by NULL device path DevicePath
 239                                   and non-NULL FileBuffer did authenticate, and the platform
 240                                   policy dictates that the DXE Foundation may execute the image in
 241                                   FileBuffer.
 242   @retval EFI_SUCCESS             FileBuffer is NULL and current user has permission to start
 243                                   UEFI device drivers on the device path specified by DevicePath.
 244   @retval EFI_SECURITY_VIOLATION  The file specified by DevicePath and FileBuffer did not
 245                                   authenticate, and the platform policy dictates that the file should be
 246                                   placed in the untrusted state. The image has been added to the file
 247                                   execution table.
 248   @retval EFI_ACCESS_DENIED       The file specified by File and FileBuffer did not
 249                                   authenticate, and the platform policy dictates that the DXE
 250                                   Foundation may not use File.
 251   @retval EFI_SECURITY_VIOLATION  FileBuffer is NULL and the user has no
 252                                   permission to start UEFI device drivers on the device path specified
 253                                   by DevicePath.
 254   @retval EFI_SECURITY_VIOLATION  FileBuffer is not NULL and the user has no permission to load
 255                                   drivers from the device path specified by DevicePath. The
 256                                   image has been added into the list of the deferred images.
 257   @retval EFI_INVALID_PARAMETER   File and FileBuffer are both NULL.
 258 **/
 259 EFI_STATUS
 260 EFIAPI
 261 ExecuteSecurity2Handlers (
 262   IN  UINT32                           AuthenticationOperation,
 263   IN  UINT32                           AuthenticationStatus,
 264   IN  CONST EFI_DEVICE_PATH_PROTOCOL   *File,
 265   IN  VOID                             *FileBuffer,
 266   IN  UINTN                            FileSize,
 267   IN  BOOLEAN                          BootPolicy
 268   );
 269
 270 #endif