2 Provides generic security measurement functions for DXE module.
4 Copyright (c) 2009 - 2013, 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 <Library/DebugLib.h>
17 #include <Library/DxeServicesLib.h>
18 #include <Library/MemoryAllocationLib.h>
19 #include <Library/SecurityManagementLib.h>
21 #define SECURITY_HANDLER_TABLE_SIZE 0x10
24 // Secruity Operation on Image and none Image.
26 #define EFI_AUTH_IMAGE_OPERATION_MASK (EFI_AUTH_OPERATION_VERIFY_IMAGE \
27 | EFI_AUTH_OPERATION_DEFER_IMAGE_LOAD \
28 | EFI_AUTH_OPERATION_MEASURE_IMAGE)
29 #define EFI_AUTH_NONE_IMAGE_OPERATION_MASK (EFI_AUTH_OPERATION_CONNECT_POLICY \
30 | EFI_AUTH_OPERATION_AUTHENTICATION_STATE)
33 UINT32 SecurityOperation
;
34 SECURITY_FILE_AUTHENTICATION_STATE_HANDLER SecurityHandler
;
38 UINT32 Security2Operation
;
39 SECURITY2_FILE_AUTHENTICATION_HANDLER Security2Handler
;
42 UINT32 mCurrentAuthOperation
= 0;
43 UINT32 mNumberOfSecurityHandler
= 0;
44 UINT32 mMaxNumberOfSecurityHandler
= 0;
45 SECURITY_INFO
*mSecurityTable
= NULL
;
47 UINT32 mCurrentAuthOperation2
= 0;
48 UINT32 mNumberOfSecurity2Handler
= 0;
49 UINT32 mMaxNumberOfSecurity2Handler
= 0;
50 SECURITY2_INFO
*mSecurity2Table
= NULL
;
53 Reallocates more global memory to store the registered Handler list.
55 @retval RETURN_SUCCESS Reallocate memory successfully.
56 @retval RETURN_OUT_OF_RESOURCES No enough memory to allocated.
60 ReallocateSecurityHandlerTable (
64 // Reallocate memory for security info structure.
66 mSecurityTable
= ReallocatePool (
67 mMaxNumberOfSecurityHandler
* sizeof (SECURITY_INFO
),
68 (mMaxNumberOfSecurityHandler
+ SECURITY_HANDLER_TABLE_SIZE
) * sizeof (SECURITY_INFO
),
73 // No enough resource is allocated.
75 if (mSecurityTable
== NULL
) {
76 return RETURN_OUT_OF_RESOURCES
;
80 // Increase max handler number
82 mMaxNumberOfSecurityHandler
= mMaxNumberOfSecurityHandler
+ SECURITY_HANDLER_TABLE_SIZE
;
83 return RETURN_SUCCESS
;
87 Check whether an operation is valid according to the requirement of current operation,
88 which must make sure that the measure image operation is the last one.
90 @param CurrentAuthOperation Current operation.
91 @param CheckAuthOperation Operation to be checked.
93 @retval TRUE Operation is valid for current operation.
94 @retval FALSE Operation is invalid for current operation.
97 CheckAuthenticationOperation (
98 IN UINT32 CurrentAuthOperation
,
99 IN UINT32 CheckAuthOperation
103 // Make sure new auth operation can be recognized.
105 ASSERT ((CheckAuthOperation
& ~(EFI_AUTH_IMAGE_OPERATION_MASK
| EFI_AUTH_OPERATION_AUTHENTICATION_STATE
| EFI_AUTH_OPERATION_IMAGE_REQUIRED
)) == 0);
108 // When current operation includes measure image operation,
109 // only another measure image operation or none operation will be allowed.
111 if ((CurrentAuthOperation
& EFI_AUTH_OPERATION_MEASURE_IMAGE
) == EFI_AUTH_OPERATION_MEASURE_IMAGE
) {
112 if (((CheckAuthOperation
& EFI_AUTH_OPERATION_MEASURE_IMAGE
) == EFI_AUTH_OPERATION_MEASURE_IMAGE
) ||
113 ((CheckAuthOperation
& EFI_AUTH_IMAGE_OPERATION_MASK
) == EFI_AUTH_OPERATION_NONE
)) {
121 // When current operation doesn't include measure image operation,
122 // any new operation will be allowed.
128 Register security measurement handler with its operation type. The different
129 handler with the same operation can all be registered.
131 If SecurityHandler is NULL, then ASSERT().
132 If no enough resources available to register new handler, then ASSERT().
133 If AuthenticationOperation is not recongnized, then ASSERT().
134 If the previous register handler can't be executed before the later register handler, then ASSERT().
136 @param[in] SecurityHandler Security measurement service handler to be registered.
137 @param[in] AuthenticationOperation Operation type is specified for the registered handler.
139 @retval EFI_SUCCESS The handlers were registered successfully.
143 RegisterSecurityHandler (
144 IN SECURITY_FILE_AUTHENTICATION_STATE_HANDLER SecurityHandler
,
145 IN UINT32 AuthenticationOperation
150 ASSERT (SecurityHandler
!= NULL
);
153 // Make sure AuthenticationOperation is valid in the register order.
155 ASSERT (CheckAuthenticationOperation (mCurrentAuthOperation
, AuthenticationOperation
));
156 mCurrentAuthOperation
= mCurrentAuthOperation
| AuthenticationOperation
;
159 // Check whether the handler lists is enough to store new handler.
161 if (mNumberOfSecurityHandler
== mMaxNumberOfSecurityHandler
) {
163 // Allocate more resources for new handler.
165 Status
= ReallocateSecurityHandlerTable();
166 ASSERT_EFI_ERROR (Status
);
170 // Register new handler into the handler list.
172 mSecurityTable
[mNumberOfSecurityHandler
].SecurityOperation
= AuthenticationOperation
;
173 mSecurityTable
[mNumberOfSecurityHandler
].SecurityHandler
= SecurityHandler
;
174 mNumberOfSecurityHandler
++;
180 Execute registered handlers until one returns an error and that error is returned.
181 If none of the handlers return an error, then EFI_SUCCESS is returned.
183 Before exectue handler, get the image buffer by file device path if a handler
184 requires the image file. And return the image buffer to each handler when exectue handler.
186 The handlers are executed in same order to their registered order.
188 @param[in] AuthenticationStatus
189 This is the authentication type returned from the Section
190 Extraction protocol. See the Section Extraction Protocol
191 Specification for details on this type.
192 @param[in] FilePath This is a pointer to the device path of the file that is
193 being dispatched. This will optionally be used for logging.
195 @retval EFI_SUCCESS The file specified by File did authenticate when more
196 than one security handler services were registered,
197 or the file did not authenticate when no security
198 handler service was registered. And the platform policy
199 dictates that the DXE Core may use File.
200 @retval EFI_INVALID_PARAMETER File is NULL.
201 @retval EFI_SECURITY_VIOLATION The file specified by File did not authenticate, and
202 the platform policy dictates that File should be placed
203 in the untrusted state. A file may be promoted from
204 the untrusted to the trusted state at a future time
205 with a call to the Trust() DXE Service.
206 @retval EFI_ACCESS_DENIED The file specified by File did not authenticate, and
207 the platform policy dictates that File should not be
208 used for any purpose.
212 ExecuteSecurityHandlers (
213 IN UINT32 AuthenticationStatus
,
214 IN CONST EFI_DEVICE_PATH_PROTOCOL
*FilePath
219 UINT32 HandlerAuthenticationStatus
;
223 if (FilePath
== NULL
) {
224 return EFI_INVALID_PARAMETER
;
228 // Directly return successfully when no handler is registered.
230 if (mNumberOfSecurityHandler
== 0) {
234 Status
= EFI_SUCCESS
;
237 HandlerAuthenticationStatus
= AuthenticationStatus
;
239 // Run security handler in same order to their registered list
241 for (Index
= 0; Index
< mNumberOfSecurityHandler
; Index
++) {
242 if ((mSecurityTable
[Index
].SecurityOperation
& EFI_AUTH_OPERATION_IMAGE_REQUIRED
) == EFI_AUTH_OPERATION_IMAGE_REQUIRED
) {
244 // Try get file buffer when the handler requires image buffer.
246 if (FileBuffer
== NULL
) {
248 // Try to get image by FALSE boot policy for the exact boot file path.
250 FileBuffer
= GetFileBufferByFilePath (FALSE
, FilePath
, &FileSize
, &AuthenticationStatus
);
251 if (FileBuffer
== NULL
) {
253 // Try to get image by TRUE boot policy for the inexact boot file path.
255 FileBuffer
= GetFileBufferByFilePath (TRUE
, FilePath
, &FileSize
, &AuthenticationStatus
);
259 Status
= mSecurityTable
[Index
].SecurityHandler (
260 HandlerAuthenticationStatus
,
265 if (EFI_ERROR (Status
)) {
270 if (FileBuffer
!= NULL
) {
271 FreePool (FileBuffer
);
278 Reallocates more global memory to store the registered Securit2Handler list.
280 @retval RETURN_SUCCESS Reallocate memory successfully.
281 @retval RETURN_OUT_OF_RESOURCES No enough memory to allocated.
285 ReallocateSecurity2HandlerTable (
289 // Reallocate memory for security info structure.
291 mSecurity2Table
= ReallocatePool (
292 mMaxNumberOfSecurity2Handler
* sizeof (SECURITY2_INFO
),
293 (mMaxNumberOfSecurity2Handler
+ SECURITY_HANDLER_TABLE_SIZE
) * sizeof (SECURITY2_INFO
),
298 // No enough resource is allocated.
300 if (mSecurity2Table
== NULL
) {
301 return RETURN_OUT_OF_RESOURCES
;
305 // Increase max handler number
307 mMaxNumberOfSecurity2Handler
= mMaxNumberOfSecurity2Handler
+ SECURITY_HANDLER_TABLE_SIZE
;
308 return RETURN_SUCCESS
;
312 Check whether an operation is valid according to the requirement of current operation,
313 which must make sure that the measure image operation is the last one.
315 If AuthenticationOperation is not recongnized, return FALSE.
316 If AuthenticationOperation is EFI_AUTH_OPERATION_NONE, return FALSE.
317 If AuthenticationOperation includes security operation and authentication operation, return FALSE.
318 If the previous register handler can't be executed before the later register handler, return FALSE.
320 @param CurrentAuthOperation Current operation.
321 @param CheckAuthOperation Operation to be checked.
323 @retval TRUE Operation is valid for current operation.
324 @retval FALSE Operation is invalid for current operation.
327 CheckAuthentication2Operation (
328 IN UINT32 CurrentAuthOperation
,
329 IN UINT32 CheckAuthOperation
333 // Make sure new auth operation can be recognized.
335 if (CheckAuthOperation
== EFI_AUTH_OPERATION_NONE
) {
338 if ((CheckAuthOperation
& ~(EFI_AUTH_IMAGE_OPERATION_MASK
|
339 EFI_AUTH_NONE_IMAGE_OPERATION_MASK
|
340 EFI_AUTH_OPERATION_IMAGE_REQUIRED
)) != 0) {
345 // When current operation includes measure image operation,
346 // only another measure image or none image operation will be allowed.
348 if ((CurrentAuthOperation
& EFI_AUTH_OPERATION_MEASURE_IMAGE
) == EFI_AUTH_OPERATION_MEASURE_IMAGE
) {
349 if (((CheckAuthOperation
& EFI_AUTH_OPERATION_MEASURE_IMAGE
) == EFI_AUTH_OPERATION_MEASURE_IMAGE
) ||
350 ((CheckAuthOperation
& EFI_AUTH_IMAGE_OPERATION_MASK
) == 0)) {
358 // Any other operation will be allowed.
364 Register security measurement handler with its operation type. Different
365 handlers with the same operation can all be registered.
367 If Security2Handler is NULL, then ASSERT().
368 If no enough resources available to register new handler, then ASSERT().
369 If AuthenticationOperation is not recongnized, then ASSERT().
370 If AuthenticationOperation is EFI_AUTH_OPERATION_NONE, then ASSERT().
371 If the previous register handler can't be executed before the later register handler, then ASSERT().
373 @param[in] Security2Handler The security measurement service handler to be registered.
374 @param[in] AuthenticationOperation The operation type is specified for the registered handler.
376 @retval EFI_SUCCESS The handlers were registered successfully.
380 RegisterSecurity2Handler (
381 IN SECURITY2_FILE_AUTHENTICATION_HANDLER Security2Handler
,
382 IN UINT32 AuthenticationOperation
387 ASSERT (Security2Handler
!= NULL
);
390 // Make sure AuthenticationOperation is valid in the register order.
392 ASSERT (CheckAuthentication2Operation (mCurrentAuthOperation2
, AuthenticationOperation
));
393 mCurrentAuthOperation2
= mCurrentAuthOperation2
| AuthenticationOperation
;
396 // Check whether the handler lists is enough to store new handler.
398 if (mNumberOfSecurity2Handler
== mMaxNumberOfSecurity2Handler
) {
400 // Allocate more resources for new handler.
402 Status
= ReallocateSecurity2HandlerTable();
403 ASSERT_EFI_ERROR (Status
);
407 // Register new handler into the handler list.
409 mSecurity2Table
[mNumberOfSecurity2Handler
].Security2Operation
= AuthenticationOperation
;
410 mSecurity2Table
[mNumberOfSecurity2Handler
].Security2Handler
= Security2Handler
;
411 mNumberOfSecurity2Handler
++;
417 Execute registered handlers based on input AuthenticationOperation until
418 one returns an error and that error is returned.
420 If none of the handlers return an error, then EFI_SUCCESS is returned.
421 The handlers those satisfy AuthenticationOperation will only be executed.
422 The handlers are executed in same order to their registered order.
424 @param[in] AuthenticationOperation
425 The operation type specifies which handlers will be executed.
426 @param[in] AuthenticationStatus
427 The authentication status for the input file.
428 @param[in] File This is a pointer to the device path of the file that is
429 being dispatched. This will optionally be used for logging.
430 @param[in] FileBuffer A pointer to the buffer with the UEFI file image
431 @param[in] FileSize The size of File buffer.
432 @param[in] BootPolicy A boot policy that was used to call LoadImage() UEFI service.
434 @retval EFI_SUCCESS The file specified by DevicePath and non-NULL
435 FileBuffer did authenticate, and the platform policy dictates
436 that the DXE Foundation may use the file.
437 @retval EFI_SUCCESS The device path specified by NULL device path DevicePath
438 and non-NULL FileBuffer did authenticate, and the platform
439 policy dictates that the DXE Foundation may execute the image in
441 @retval EFI_SUCCESS FileBuffer is NULL and current user has permission to start
442 UEFI device drivers on the device path specified by DevicePath.
443 @retval EFI_SECURITY_VIOLATION The file specified by File or FileBuffer did not
444 authenticate, and the platform policy dictates that
445 the file should be placed in the untrusted state.
446 @retval EFI_SECURITY_VIOLATION FileBuffer FileBuffer is NULL and the user has no
447 permission to start UEFI device drivers on the device path specified
449 @retval EFI_SECURITY_VIOLATION FileBuffer is not NULL and the user has no permission to load
450 drivers from the device path specified by DevicePath. The
451 image has been added into the list of the deferred images.
452 @retval EFI_ACCESS_DENIED The file specified by File did not authenticate, and
453 the platform policy dictates that the DXE
454 Foundation may not use File.
455 @retval EFI_INVALID_PARAMETER File and FileBuffer are both NULL.
459 ExecuteSecurity2Handlers (
460 IN UINT32 AuthenticationOperation
,
461 IN UINT32 AuthenticationStatus
,
462 IN CONST EFI_DEVICE_PATH_PROTOCOL
*File
,
465 IN BOOLEAN BootPolicy
472 // Invalid case if File and FileBuffer are both NULL.
474 if (File
== NULL
&& FileBuffer
== NULL
) {
475 return EFI_INVALID_PARAMETER
;
479 // Directly return successfully when no handler is registered.
481 if (mNumberOfSecurity2Handler
== 0) {
486 // Run security handler in same order to their registered list
488 for (Index
= 0; Index
< mNumberOfSecurity2Handler
; Index
++) {
490 // If FileBuffer is not NULL, the input is Image, which will be handled by EFI_AUTH_IMAGE_OPERATION_MASK operation.
491 // If FileBuffer is NULL, the input is not Image, which will be handled by EFI_AUTH_NONE_IMAGE_OPERATION_MASK operation.
492 // Other cases are ignored.
494 if ((FileBuffer
!= NULL
&& (mSecurity2Table
[Index
].Security2Operation
& EFI_AUTH_IMAGE_OPERATION_MASK
) != 0) ||
495 (FileBuffer
== NULL
&& (mSecurity2Table
[Index
].Security2Operation
& EFI_AUTH_NONE_IMAGE_OPERATION_MASK
) != 0)) {
497 // Execute registered handlers based on input AuthenticationOperation
499 if ((mSecurity2Table
[Index
].Security2Operation
& AuthenticationOperation
) != 0) {
500 Status
= mSecurity2Table
[Index
].Security2Handler (
501 AuthenticationStatus
,
507 if (EFI_ERROR (Status
)) {