| 1 | /** @file
|
|---|
| 2 | Security Architectural Protocol as defined in PI Specification VOLUME 2 DXE
|
|---|
| 3 |
|
|---|
| 4 | Used to provide Security services. Specifically, dependening upon the
|
|---|
| 5 | authentication state of a discovered driver in a Firmware Volume, the
|
|---|
| 6 | portable DXE Core Dispatcher will call into the Security Architectural
|
|---|
| 7 | Protocol (SAP) with the authentication state of the driver.
|
|---|
| 8 |
|
|---|
| 9 | This call-out allows for OEM-specific policy decisions to be made, such
|
|---|
| 10 | as event logging for attested boots, locking flash in response to discovering
|
|---|
| 11 | an unsigned driver or failed signature check, or other exception response.
|
|---|
| 12 |
|
|---|
| 13 | The SAP can also change system behavior by having the DXE core put a driver
|
|---|
| 14 | in the Schedule-On-Request (SOR) state. This will allow for later disposition
|
|---|
| 15 | of the driver by platform agent, such as Platform BDS.
|
|---|
| 16 |
|
|---|
| 17 | Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
|
|---|
| 18 | SPDX-License-Identifier: BSD-2-Clause-Patent
|
|---|
| 19 |
|
|---|
| 20 | **/
|
|---|
| 21 |
|
|---|
| 22 | #ifndef __ARCH_PROTOCOL_SECURITY_H__
|
|---|
| 23 | #define __ARCH_PROTOCOL_SECURITY_H__
|
|---|
| 24 |
|
|---|
| 25 | ///
|
|---|
| 26 | /// Global ID for the Security Code Architectural Protocol
|
|---|
| 27 | ///
|
|---|
| 28 | #define EFI_SECURITY_ARCH_PROTOCOL_GUID \
|
|---|
| 29 | { 0xA46423E3, 0x4617, 0x49f1, {0xB9, 0xFF, 0xD1, 0xBF, 0xA9, 0x11, 0x58, 0x39 } }
|
|---|
| 30 |
|
|---|
| 31 | typedef struct _EFI_SECURITY_ARCH_PROTOCOL EFI_SECURITY_ARCH_PROTOCOL;
|
|---|
| 32 |
|
|---|
| 33 | /**
|
|---|
| 34 | The EFI_SECURITY_ARCH_PROTOCOL (SAP) is used to abstract platform-specific
|
|---|
| 35 | policy from the DXE core response to an attempt to use a file that returns a
|
|---|
| 36 | given status for the authentication check from the section extraction protocol.
|
|---|
| 37 |
|
|---|
| 38 | The possible responses in a given SAP implementation may include locking
|
|---|
| 39 | flash upon failure to authenticate, attestation logging for all signed drivers,
|
|---|
| 40 | and other exception operations. The File parameter allows for possible logging
|
|---|
| 41 | within the SAP of the driver.
|
|---|
| 42 |
|
|---|
| 43 | If File is NULL, then EFI_INVALID_PARAMETER is returned.
|
|---|
| 44 |
|
|---|
| 45 | If the file specified by File with an authentication status specified by
|
|---|
| 46 | AuthenticationStatus is safe for the DXE Core to use, then EFI_SUCCESS is returned.
|
|---|
| 47 |
|
|---|
| 48 | If the file specified by File with an authentication status specified by
|
|---|
| 49 | AuthenticationStatus is not safe for the DXE Core to use under any circumstances,
|
|---|
| 50 | then EFI_ACCESS_DENIED is returned.
|
|---|
| 51 |
|
|---|
| 52 | If the file specified by File with an authentication status specified by
|
|---|
| 53 | AuthenticationStatus is not safe for the DXE Core to use right now, but it
|
|---|
| 54 | might be possible to use it at a future time, then EFI_SECURITY_VIOLATION is
|
|---|
| 55 | returned.
|
|---|
| 56 |
|
|---|
| 57 | @param This The EFI_SECURITY_ARCH_PROTOCOL instance.
|
|---|
| 58 | @param AuthenticationStatus
|
|---|
| 59 | This is the authentication type returned from the Section
|
|---|
| 60 | Extraction protocol. See the Section Extraction Protocol
|
|---|
| 61 | Specification for details on this type.
|
|---|
| 62 | @param File This is a pointer to the device path of the file that is
|
|---|
| 63 | being dispatched. This will optionally be used for logging.
|
|---|
| 64 |
|
|---|
| 65 | @retval EFI_SUCCESS The file specified by File did authenticate, and the
|
|---|
| 66 | platform policy dictates that the DXE Core may use File.
|
|---|
| 67 | @retval EFI_INVALID_PARAMETER Driver is NULL.
|
|---|
| 68 | @retval EFI_SECURITY_VIOLATION The file specified by File did not authenticate, and
|
|---|
| 69 | the platform policy dictates that File should be placed
|
|---|
| 70 | in the untrusted state. A file may be promoted from
|
|---|
| 71 | the untrusted to the trusted state at a future time
|
|---|
| 72 | with a call to the Trust() DXE Service.
|
|---|
| 73 | @retval EFI_ACCESS_DENIED The file specified by File did not authenticate, and
|
|---|
| 74 | the platform policy dictates that File should not be
|
|---|
| 75 | used for any purpose.
|
|---|
| 76 |
|
|---|
| 77 | **/
|
|---|
| 78 | typedef
|
|---|
| 79 | EFI_STATUS
|
|---|
| 80 | (EFIAPI *EFI_SECURITY_FILE_AUTHENTICATION_STATE)(
|
|---|
| 81 | IN CONST EFI_SECURITY_ARCH_PROTOCOL *This,
|
|---|
| 82 | IN UINT32 AuthenticationStatus,
|
|---|
| 83 | IN CONST EFI_DEVICE_PATH_PROTOCOL *File
|
|---|
| 84 | );
|
|---|
| 85 |
|
|---|
| 86 | ///
|
|---|
| 87 | /// The EFI_SECURITY_ARCH_PROTOCOL is used to abstract platform-specific policy
|
|---|
| 88 | /// from the DXE core. This includes locking flash upon failure to authenticate,
|
|---|
| 89 | /// attestation logging, and other exception operations.
|
|---|
| 90 | ///
|
|---|
| 91 | struct _EFI_SECURITY_ARCH_PROTOCOL {
|
|---|
| 92 | EFI_SECURITY_FILE_AUTHENTICATION_STATE FileAuthenticationState;
|
|---|
| 93 | };
|
|---|
| 94 |
|
|---|
| 95 | extern EFI_GUID gEfiSecurityArchProtocolGuid;
|
|---|
| 96 |
|
|---|
| 97 | #endif
|
|---|
