2 Provides generic security measurement functions for DXE module.
4 Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
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.
16 #include <Protocol/LoadFile.h>
17 #include <Library/DebugLib.h>
18 #include <Library/DxeServicesLib.h>
19 #include <Library/MemoryAllocationLib.h>
20 #include <Library/SecurityManagementLib.h>
21 #include <Library/DevicePathLib.h>
22 #include <Library/UefiBootServicesTableLib.h>
24 #define SECURITY_HANDLER_TABLE_SIZE 0x10
27 // Secruity Operation on Image and none Image.
29 #define EFI_AUTH_IMAGE_OPERATION_MASK (EFI_AUTH_OPERATION_VERIFY_IMAGE \
30 | EFI_AUTH_OPERATION_DEFER_IMAGE_LOAD \
31 | EFI_AUTH_OPERATION_MEASURE_IMAGE)
32 #define EFI_AUTH_NONE_IMAGE_OPERATION_MASK (EFI_AUTH_OPERATION_CONNECT_POLICY \
33 | EFI_AUTH_OPERATION_AUTHENTICATION_STATE)
36 UINT32 SecurityOperation
;
37 SECURITY_FILE_AUTHENTICATION_STATE_HANDLER SecurityHandler
;
41 UINT32 Security2Operation
;
42 SECURITY2_FILE_AUTHENTICATION_HANDLER Security2Handler
;
45 UINT32 mCurrentAuthOperation
= 0;
46 UINT32 mNumberOfSecurityHandler
= 0;
47 UINT32 mMaxNumberOfSecurityHandler
= 0;
48 SECURITY_INFO
*mSecurityTable
= NULL
;
50 UINT32 mCurrentAuthOperation2
= 0;
51 UINT32 mNumberOfSecurity2Handler
= 0;
52 UINT32 mMaxNumberOfSecurity2Handler
= 0;
53 SECURITY2_INFO
*mSecurity2Table
= NULL
;
56 Reallocates more global memory to store the registered Handler list.
58 @retval RETURN_SUCCESS Reallocate memory successfully.
59 @retval RETURN_OUT_OF_RESOURCES No enough memory to allocated.
63 ReallocateSecurityHandlerTable (
67 // Reallocate memory for security info structure.
69 mSecurityTable
= ReallocatePool (
70 mMaxNumberOfSecurityHandler
* sizeof (SECURITY_INFO
),
71 (mMaxNumberOfSecurityHandler
+ SECURITY_HANDLER_TABLE_SIZE
) * sizeof (SECURITY_INFO
),
76 // No enough resource is allocated.
78 if (mSecurityTable
== NULL
) {
79 return RETURN_OUT_OF_RESOURCES
;
83 // Increase max handler number
85 mMaxNumberOfSecurityHandler
= mMaxNumberOfSecurityHandler
+ SECURITY_HANDLER_TABLE_SIZE
;
86 return RETURN_SUCCESS
;
90 Check whether an operation is valid according to the requirement of current operation,
91 which must make sure that the measure image operation is the last one.
93 @param CurrentAuthOperation Current operation.
94 @param CheckAuthOperation Operation to be checked.
96 @retval TRUE Operation is valid for current operation.
97 @retval FALSE Operation is invalid for current operation.
100 CheckAuthenticationOperation (
101 IN UINT32 CurrentAuthOperation
,
102 IN UINT32 CheckAuthOperation
106 // Make sure new auth operation can be recognized.
108 ASSERT ((CheckAuthOperation
& ~(EFI_AUTH_IMAGE_OPERATION_MASK
| EFI_AUTH_OPERATION_AUTHENTICATION_STATE
| EFI_AUTH_OPERATION_IMAGE_REQUIRED
)) == 0);
111 // When current operation includes measure image operation,
112 // only another measure image operation or none operation will be allowed.
114 if ((CurrentAuthOperation
& EFI_AUTH_OPERATION_MEASURE_IMAGE
) == EFI_AUTH_OPERATION_MEASURE_IMAGE
) {
115 if (((CheckAuthOperation
& EFI_AUTH_OPERATION_MEASURE_IMAGE
) == EFI_AUTH_OPERATION_MEASURE_IMAGE
) ||
116 ((CheckAuthOperation
& EFI_AUTH_IMAGE_OPERATION_MASK
) == EFI_AUTH_OPERATION_NONE
)) {
124 // When current operation doesn't include measure image operation,
125 // any new operation will be allowed.
131 Register security measurement handler with its operation type. The different
132 handler with the same operation can all be registered.
134 If SecurityHandler is NULL, then ASSERT().
135 If no enough resources available to register new handler, then ASSERT().
136 If AuthenticationOperation is not recongnized, then ASSERT().
137 If the previous register handler can't be executed before the later register handler, then ASSERT().
139 @param[in] SecurityHandler Security measurement service handler to be registered.
140 @param[in] AuthenticationOperation Operation type is specified for the registered handler.
142 @retval EFI_SUCCESS The handlers were registered successfully.
146 RegisterSecurityHandler (
147 IN SECURITY_FILE_AUTHENTICATION_STATE_HANDLER SecurityHandler
,
148 IN UINT32 AuthenticationOperation
153 ASSERT (SecurityHandler
!= NULL
);
156 // Make sure AuthenticationOperation is valid in the register order.
158 ASSERT (CheckAuthenticationOperation (mCurrentAuthOperation
, AuthenticationOperation
));
159 mCurrentAuthOperation
= mCurrentAuthOperation
| AuthenticationOperation
;
162 // Check whether the handler lists is enough to store new handler.
164 if (mNumberOfSecurityHandler
== mMaxNumberOfSecurityHandler
) {
166 // Allocate more resources for new handler.
168 Status
= ReallocateSecurityHandlerTable();
169 ASSERT_EFI_ERROR (Status
);
173 // Register new handler into the handler list.
175 mSecurityTable
[mNumberOfSecurityHandler
].SecurityOperation
= AuthenticationOperation
;
176 mSecurityTable
[mNumberOfSecurityHandler
].SecurityHandler
= SecurityHandler
;
177 mNumberOfSecurityHandler
++;
183 Execute registered handlers until one returns an error and that error is returned.
184 If none of the handlers return an error, then EFI_SUCCESS is returned.
186 Before exectue handler, get the image buffer by file device path if a handler
187 requires the image file. And return the image buffer to each handler when exectue handler.
189 The handlers are executed in same order to their registered order.
191 @param[in] AuthenticationStatus
192 This is the authentication type returned from the Section
193 Extraction protocol. See the Section Extraction Protocol
194 Specification for details on this type.
195 @param[in] FilePath This is a pointer to the device path of the file that is
196 being dispatched. This will optionally be used for logging.
198 @retval EFI_SUCCESS The file specified by File did authenticate when more
199 than one security handler services were registered,
200 or the file did not authenticate when no security
201 handler service was registered. And the platform policy
202 dictates that the DXE Core may use File.
203 @retval EFI_INVALID_PARAMETER File is NULL.
204 @retval EFI_SECURITY_VIOLATION The file specified by File did not authenticate, and
205 the platform policy dictates that File should be placed
206 in the untrusted state. A file may be promoted from
207 the untrusted to the trusted state at a future time
208 with a call to the Trust() DXE Service.
209 @retval EFI_ACCESS_DENIED The file specified by File did not authenticate, and
210 the platform policy dictates that File should not be
211 used for any purpose.
215 ExecuteSecurityHandlers (
216 IN UINT32 AuthenticationStatus
,
217 IN CONST EFI_DEVICE_PATH_PROTOCOL
*FilePath
222 UINT32 HandlerAuthenticationStatus
;
226 EFI_DEVICE_PATH_PROTOCOL
*Node
;
227 EFI_DEVICE_PATH_PROTOCOL
*FilePathToVerfiy
;
229 if (FilePath
== NULL
) {
230 return EFI_INVALID_PARAMETER
;
234 // Directly return successfully when no handler is registered.
236 if (mNumberOfSecurityHandler
== 0) {
240 Status
= EFI_SUCCESS
;
243 HandlerAuthenticationStatus
= AuthenticationStatus
;
244 FilePathToVerfiy
= (EFI_DEVICE_PATH_PROTOCOL
*) FilePath
;
246 // Run security handler in same order to their registered list
248 for (Index
= 0; Index
< mNumberOfSecurityHandler
; Index
++) {
249 if ((mSecurityTable
[Index
].SecurityOperation
& EFI_AUTH_OPERATION_IMAGE_REQUIRED
) == EFI_AUTH_OPERATION_IMAGE_REQUIRED
) {
251 // Try get file buffer when the handler requires image buffer.
253 if (FileBuffer
== NULL
) {
254 Node
= FilePathToVerfiy
;
255 Status
= gBS
->LocateDevicePath (&gEfiLoadFileProtocolGuid
, &Node
, &Handle
);
257 // Try to get image by FALSE boot policy for the exact boot file path.
259 FileBuffer
= GetFileBufferByFilePath (FALSE
, FilePath
, &FileSize
, &AuthenticationStatus
);
260 if (FileBuffer
== NULL
) {
262 // Try to get image by TRUE boot policy for the inexact boot file path.
264 FileBuffer
= GetFileBufferByFilePath (TRUE
, FilePath
, &FileSize
, &AuthenticationStatus
);
266 if ((FileBuffer
!= NULL
) && (!EFI_ERROR (Status
))) {
268 // LoadFile () may cause the device path of the Handle be updated.
270 FilePathToVerfiy
= AppendDevicePath (DevicePathFromHandle (Handle
), Node
);
274 Status
= mSecurityTable
[Index
].SecurityHandler (
275 HandlerAuthenticationStatus
,
280 if (EFI_ERROR (Status
)) {
285 if (FileBuffer
!= NULL
) {
286 FreePool (FileBuffer
);
288 if (FilePathToVerfiy
!= FilePath
) {
289 FreePool (FilePathToVerfiy
);
296 Reallocates more global memory to store the registered Securit2Handler list.
298 @retval RETURN_SUCCESS Reallocate memory successfully.
299 @retval RETURN_OUT_OF_RESOURCES No enough memory to allocated.
303 ReallocateSecurity2HandlerTable (
307 // Reallocate memory for security info structure.
309 mSecurity2Table
= ReallocatePool (
310 mMaxNumberOfSecurity2Handler
* sizeof (SECURITY2_INFO
),
311 (mMaxNumberOfSecurity2Handler
+ SECURITY_HANDLER_TABLE_SIZE
) * sizeof (SECURITY2_INFO
),
316 // No enough resource is allocated.
318 if (mSecurity2Table
== NULL
) {
319 return RETURN_OUT_OF_RESOURCES
;
323 // Increase max handler number
325 mMaxNumberOfSecurity2Handler
= mMaxNumberOfSecurity2Handler
+ SECURITY_HANDLER_TABLE_SIZE
;
326 return RETURN_SUCCESS
;
330 Check whether an operation is valid according to the requirement of current operation,
331 which must make sure that the measure image operation is the last one.
333 If AuthenticationOperation is not recongnized, return FALSE.
334 If AuthenticationOperation is EFI_AUTH_OPERATION_NONE, return FALSE.
335 If AuthenticationOperation includes security operation and authentication operation, return FALSE.
336 If the previous register handler can't be executed before the later register handler, return FALSE.
338 @param CurrentAuthOperation Current operation.
339 @param CheckAuthOperation Operation to be checked.
341 @retval TRUE Operation is valid for current operation.
342 @retval FALSE Operation is invalid for current operation.
345 CheckAuthentication2Operation (
346 IN UINT32 CurrentAuthOperation
,
347 IN UINT32 CheckAuthOperation
351 // Make sure new auth operation can be recognized.
353 if (CheckAuthOperation
== EFI_AUTH_OPERATION_NONE
) {
356 if ((CheckAuthOperation
& ~(EFI_AUTH_IMAGE_OPERATION_MASK
|
357 EFI_AUTH_NONE_IMAGE_OPERATION_MASK
|
358 EFI_AUTH_OPERATION_IMAGE_REQUIRED
)) != 0) {
363 // When current operation includes measure image operation,
364 // only another measure image or none image operation will be allowed.
366 if ((CurrentAuthOperation
& EFI_AUTH_OPERATION_MEASURE_IMAGE
) == EFI_AUTH_OPERATION_MEASURE_IMAGE
) {
367 if (((CheckAuthOperation
& EFI_AUTH_OPERATION_MEASURE_IMAGE
) == EFI_AUTH_OPERATION_MEASURE_IMAGE
) ||
368 ((CheckAuthOperation
& EFI_AUTH_IMAGE_OPERATION_MASK
) == 0)) {
376 // Any other operation will be allowed.
382 Register security measurement handler with its operation type. Different
383 handlers with the same operation can all be registered.
385 If Security2Handler is NULL, then ASSERT().
386 If no enough resources available to register new handler, then ASSERT().
387 If AuthenticationOperation is not recongnized, then ASSERT().
388 If AuthenticationOperation is EFI_AUTH_OPERATION_NONE, then ASSERT().
389 If the previous register handler can't be executed before the later register handler, then ASSERT().
391 @param[in] Security2Handler The security measurement service handler to be registered.
392 @param[in] AuthenticationOperation The operation type is specified for the registered handler.
394 @retval EFI_SUCCESS The handlers were registered successfully.
398 RegisterSecurity2Handler (
399 IN SECURITY2_FILE_AUTHENTICATION_HANDLER Security2Handler
,
400 IN UINT32 AuthenticationOperation
405 ASSERT (Security2Handler
!= NULL
);
408 // Make sure AuthenticationOperation is valid in the register order.
410 ASSERT (CheckAuthentication2Operation (mCurrentAuthOperation2
, AuthenticationOperation
));
411 mCurrentAuthOperation2
= mCurrentAuthOperation2
| AuthenticationOperation
;
414 // Check whether the handler lists is enough to store new handler.
416 if (mNumberOfSecurity2Handler
== mMaxNumberOfSecurity2Handler
) {
418 // Allocate more resources for new handler.
420 Status
= ReallocateSecurity2HandlerTable();
421 ASSERT_EFI_ERROR (Status
);
425 // Register new handler into the handler list.
427 mSecurity2Table
[mNumberOfSecurity2Handler
].Security2Operation
= AuthenticationOperation
;
428 mSecurity2Table
[mNumberOfSecurity2Handler
].Security2Handler
= Security2Handler
;
429 mNumberOfSecurity2Handler
++;
435 Execute registered handlers based on input AuthenticationOperation until
436 one returns an error and that error is returned.
438 If none of the handlers return an error, then EFI_SUCCESS is returned.
439 The handlers those satisfy AuthenticationOperation will only be executed.
440 The handlers are executed in same order to their registered order.
442 @param[in] AuthenticationOperation
443 The operation type specifies which handlers will be executed.
444 @param[in] AuthenticationStatus
445 The authentication status for the input file.
446 @param[in] File This is a pointer to the device path of the file that is
447 being dispatched. This will optionally be used for logging.
448 @param[in] FileBuffer A pointer to the buffer with the UEFI file image
449 @param[in] FileSize The size of File buffer.
450 @param[in] BootPolicy A boot policy that was used to call LoadImage() UEFI service.
452 @retval EFI_SUCCESS The file specified by DevicePath and non-NULL
453 FileBuffer did authenticate, and the platform policy dictates
454 that the DXE Foundation may use the file.
455 @retval EFI_SUCCESS The device path specified by NULL device path DevicePath
456 and non-NULL FileBuffer did authenticate, and the platform
457 policy dictates that the DXE Foundation may execute the image in
459 @retval EFI_SUCCESS FileBuffer is NULL and current user has permission to start
460 UEFI device drivers on the device path specified by DevicePath.
461 @retval EFI_SECURITY_VIOLATION The file specified by File or FileBuffer did not
462 authenticate, and the platform policy dictates that
463 the file should be placed in the untrusted state.
464 @retval EFI_SECURITY_VIOLATION FileBuffer FileBuffer is NULL and the user has no
465 permission to start UEFI device drivers on the device path specified
467 @retval EFI_SECURITY_VIOLATION FileBuffer is not NULL and the user has no permission to load
468 drivers from the device path specified by DevicePath. The
469 image has been added into the list of the deferred images.
470 @retval EFI_ACCESS_DENIED The file specified by File did not authenticate, and
471 the platform policy dictates that the DXE
472 Foundation may not use File.
473 @retval EFI_INVALID_PARAMETER File and FileBuffer are both NULL.
477 ExecuteSecurity2Handlers (
478 IN UINT32 AuthenticationOperation
,
479 IN UINT32 AuthenticationStatus
,
480 IN CONST EFI_DEVICE_PATH_PROTOCOL
*File
,
483 IN BOOLEAN BootPolicy
490 // Invalid case if File and FileBuffer are both NULL.
492 if (File
== NULL
&& FileBuffer
== NULL
) {
493 return EFI_INVALID_PARAMETER
;
497 // Directly return successfully when no handler is registered.
499 if (mNumberOfSecurity2Handler
== 0) {
504 // Run security handler in same order to their registered list
506 for (Index
= 0; Index
< mNumberOfSecurity2Handler
; Index
++) {
508 // If FileBuffer is not NULL, the input is Image, which will be handled by EFI_AUTH_IMAGE_OPERATION_MASK operation.
509 // If FileBuffer is NULL, the input is not Image, which will be handled by EFI_AUTH_NONE_IMAGE_OPERATION_MASK operation.
510 // Other cases are ignored.
512 if ((FileBuffer
!= NULL
&& (mSecurity2Table
[Index
].Security2Operation
& EFI_AUTH_IMAGE_OPERATION_MASK
) != 0) ||
513 (FileBuffer
== NULL
&& (mSecurity2Table
[Index
].Security2Operation
& EFI_AUTH_NONE_IMAGE_OPERATION_MASK
) != 0)) {
515 // Execute registered handlers based on input AuthenticationOperation
517 if ((mSecurity2Table
[Index
].Security2Operation
& AuthenticationOperation
) != 0) {
518 Status
= mSecurity2Table
[Index
].Security2Handler (
519 AuthenticationStatus
,
525 if (EFI_ERROR (Status
)) {