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