]>
Commit | Line | Data |
---|---|---|
e5544398 | 1 | /** @file\r |
d7132512 | 2 | This file declares Pei Security2 PPI.\r |
e5544398 | 3 | \r |
d7132512 | 4 | This PPI is installed by some platform PEIM that abstracts the security \r |
4ca9b6c4 | 5 | policy to the PEI Foundation, namely the case of a PEIM's authentication \r |
d7132512 LG |
6 | state being returned during the PEI section extraction process.\r |
7 | \r | |
8 | Copyright (c) 2006 - 2008, Intel Corporation\r | |
e5544398 | 9 | All rights reserved. This program and the accompanying materials \r |
10 | are licensed and made available under the terms and conditions of the BSD License \r | |
11 | which accompanies this distribution. The full text of the license may be found at \r | |
12 | http://opensource.org/licenses/bsd-license.php \r | |
13 | \r | |
14 | THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r | |
15 | WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r | |
16 | \r | |
e5544398 | 17 | @par Revision Reference:\r |
18 | This PPI is defined in PI.\r | |
19 | Version 1.0.\r | |
20 | \r | |
21 | **/\r | |
22 | \r | |
23 | #ifndef __SECURITY2_PPI_H__\r | |
24 | #define __SECURITY2_PPI_H__\r | |
25 | \r | |
26 | #define EFI_PEI_SECURITY2_PPI_GUID \\r | |
27 | { 0xdcd0be23, 0x9586, 0x40f4, { 0xb6, 0x43, 0x6, 0x52, 0x2c, 0xed, 0x4e, 0xde } }\r | |
28 | \r | |
29 | \r | |
53f2d96e | 30 | typedef struct _EFI_PEI_SECURITY2_PPI EFI_PEI_SECURITY2_PPI;\r |
e5544398 | 31 | \r |
32 | /**\r | |
d7132512 LG |
33 | Allows the platform builder to implement a security policy \r |
34 | in response to varying file authentication states.\r | |
35 | \r | |
e5544398 | 36 | This service is published by some platform PEIM. The purpose of\r |
37 | this service is to expose a given platform's policy-based\r | |
38 | response to the PEI Foundation. For example, if there is a PEIM\r | |
39 | in a GUIDed encapsulation section and the extraction of the PEI\r | |
40 | file section yields an authentication failure, there is no a\r | |
41 | priori policy in the PEI Foundation. Specifically, this\r | |
42 | situation leads to the question whether PEIMs that are either\r | |
43 | not in GUIDed sections or are in sections whose authentication\r | |
44 | fails should still be executed. In fact, it is the\r | |
45 | responsibility of the platform builder to make this decision.\r | |
46 | This platform-scoped policy is a result that a desktop system\r | |
47 | might not be able to skip or not execute PEIMs because the\r | |
48 | skipped PEIM could be the agent that initializes main memory.\r | |
49 | Alternately, a system may require that unsigned PEIMs not be\r | |
50 | executed under any circumstances. In either case, the PEI\r | |
51 | Foundation simply multiplexes access to the Section Extraction\r | |
52 | PPI and the Security PPI. The Section Extraction PPI determines\r | |
53 | the contents of a section, and the Security PPI tells the PEI\r | |
54 | Foundation whether or not to invoke the PEIM. The PEIM that\r | |
55 | publishes the AuthenticationState() service uses its parameters\r | |
56 | in the following ways: ?? AuthenticationStatus conveys the\r | |
57 | source information upon which the PEIM acts. 1) The\r | |
58 | DeferExecution value tells the PEI Foundation whether or not to\r | |
59 | dispatch the PEIM. In addition, between receiving the\r | |
60 | AuthenticationState() from the PEI Foundation and returning with\r | |
61 | the DeferExecution value, the PEIM that publishes\r | |
62 | AuthenticationState() can do the following: 2) Log the file\r | |
63 | state. 3) Lock the firmware hubs in response to an unsigned\r | |
64 | PEIM being discovered. These latter behaviors are platform-\r | |
65 | and market-specific and thus outside the scope of the PEI CIS.\r | |
66 | \r | |
d7132512 LG |
67 | @param PeiServices An indirect pointer to the PEI Services Table published by the PEI Foundation.\r |
68 | \r | |
e5544398 | 69 | @param This Interface pointer that implements the particular\r |
70 | EFI_PEI_SECURITY2_PPI instance.\r | |
71 | \r | |
72 | \r | |
73 | @param AuthenticationStatus Authentication status of the\r | |
74 | file.\r | |
75 | \r | |
76 | @param FvHandle Handle of the volume in which the file\r | |
77 | resides. Type EFI_PEI_FV_HANDLE is defined\r | |
78 | in FfsFindNextVolume. This allows different\r | |
79 | policies depending on different firmware\r | |
80 | volumes.\r | |
81 | \r | |
82 | @param FileHandle Handle of the file under review. Type\r | |
83 | EFI_PEI FILE HANDLE is defined in\r | |
84 | FfsFindNextFile.\r | |
85 | \r | |
86 | @param DeferExecution Pointer to a variable that alerts the\r | |
87 | PEI Foundation to defer execution of a\r | |
88 | PEIM.\r | |
89 | \r | |
90 | @retval EFI_SUCCESS The service performed its action\r | |
91 | successfully.\r | |
92 | \r | |
93 | @retval EFI_SECURITY_VIOLATION The object cannot be trusted.\r | |
94 | \r | |
95 | **/\r | |
96 | typedef\r | |
97 | EFI_STATUS\r | |
8b13229b | 98 | (EFIAPI *EFI_PEI_SECURITY_AUTHENTICATION_STATE)(\r |
e5544398 | 99 | IN CONST EFI_PEI_SERVICES **PeiServices,\r |
100 | IN CONST EFI_PEI_SECURITY2_PPI *This,\r | |
101 | IN CONST UINT32 AuthenticationStatus,\r | |
102 | IN CONST EFI_PEI_FV_HANDLE FvHandle,\r | |
103 | IN CONST EFI_PEI_FV_HANDLE FileHandle,\r | |
104 | IN OUT BOOLEAN *DeferExecution\r | |
105 | );\r | |
106 | \r | |
107 | /**\r | |
4ca9b6c4 | 108 | @par Ppi Description: \r |
e5544398 | 109 | This PPI is a means by which the platform builder can indicate\r |
110 | a response to a PEIM's authentication state. This can be in\r | |
111 | the form of a requirement for the PEI Foundation to skip a\r | |
112 | module using the DeferExecution Boolean output in the\r | |
113 | AuthenticationState() member function. Alternately, the\r | |
114 | Security PPI can invoke something like a cryptographic PPI\r | |
115 | that hashes the PEIM contents to log attestations, for which\r | |
116 | the FileHandle parameter in AuthenticationState() will be\r | |
117 | useful. If this PPI does not exist, PEIMs will be considered\r | |
118 | trusted.\r | |
119 | \r | |
120 | @param AuthenticationState Allows the platform builder to\r | |
121 | implement a security policy in\r | |
122 | response to varying file\r | |
123 | authentication states. See the\r | |
124 | AuthenticationState() function\r | |
125 | description.\r | |
126 | \r | |
127 | **/\r | |
128 | struct _EFI_PEI_SECURITY2_PPI {\r | |
129 | EFI_PEI_SECURITY_AUTHENTICATION_STATE AuthenticationState;\r | |
130 | };\r | |
131 | \r | |
132 | \r | |
133 | extern EFI_GUID gEfiPeiSecurity2PpiGuid;\r | |
134 | \r | |
135 | #endif\r |