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