| 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 OPTIONAL,
|
|---|
| 265 | IN VOID *FileBuffer,
|
|---|
| 266 | IN UINTN FileSize,
|
|---|
| 267 | IN BOOLEAN BootPolicy
|
|---|
| 268 | );
|
|---|
| 269 |
|
|---|
| 270 | #endif
|
|---|
