This file declares Pei Security2 PPI.\r
\r
This PPI is installed by some platform PEIM that abstracts the security \r
- policy to the PEI Foundation, namely the case of a PEIM¡¯s authentication \r
+ policy to the PEI Foundation, namely the case of a PEIM's authentication \r
state being returned during the PEI section extraction process.\r
\r
Copyright (c) 2006 - 2008, Intel Corporation\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
\r
@par Revision Reference:\r
- This PPI is defined in PI.\r
- Version 1.0.\r
+ This PPI is introduced in PI Version 1.0.\r
\r
**/\r
\r
priori policy in the PEI Foundation. Specifically, this\r
situation leads to the question whether PEIMs that are either\r
not in GUIDed sections or are in sections whose authentication\r
- fails should still be executed. In fact, it is the\r
- responsibility of the platform builder to make this decision.\r
- This platform-scoped policy is a result that a desktop system\r
- might not be able to skip or not execute PEIMs because the\r
- skipped PEIM could be the agent that initializes main memory.\r
- Alternately, a system may require that unsigned PEIMs not be\r
- executed under any circumstances. In either case, the PEI\r
- Foundation simply multiplexes access to the Section Extraction\r
- PPI and the Security PPI. The Section Extraction PPI determines\r
- the contents of a section, and the Security PPI tells the PEI\r
- Foundation whether or not to invoke the PEIM. The PEIM that\r
- publishes the AuthenticationState() service uses its parameters\r
- in the following ways: ?? AuthenticationStatus conveys the\r
- source information upon which the PEIM acts. 1) The\r
- DeferExecution value tells the PEI Foundation whether or not to\r
- dispatch the PEIM. In addition, between receiving the\r
- AuthenticationState() from the PEI Foundation and returning with\r
- the DeferExecution value, the PEIM that publishes\r
- AuthenticationState() can do the following: 2) Log the file\r
- state. 3) Lock the firmware hubs in response to an unsigned\r
- PEIM being discovered. These latter behaviors are platform-\r
- and market-specific and thus outside the scope of the PEI CIS.\r
-\r
- @param PeiServices An indirect pointer to the PEI Services Table published by the PEI Foundation.\r
-\r
- @param This Interface pointer that implements the particular\r
- EFI_PEI_SECURITY2_PPI instance.\r
-\r
-\r
- @param AuthenticationStatus Authentication status of the\r
- file.\r
-\r
- @param FvHandle Handle of the volume in which the file\r
- resides. Type EFI_PEI_FV_HANDLE is defined\r
- in FfsFindNextVolume. This allows different\r
- policies depending on different firmware\r
- volumes.\r
-\r
- @param FileHandle Handle of the file under review. Type\r
- EFI_PEI FILE HANDLE is defined in\r
- FfsFindNextFile.\r
-\r
- @param DeferExecution Pointer to a variable that alerts the\r
- PEI Foundation to defer execution of a\r
- PEIM.\r
-\r
- @retval EFI_SUCCESS The service performed its action\r
- successfully.\r
-\r
- @retval EFI_SECURITY_VIOLATION The object cannot be trusted.\r
+ fails should still be executed.\r
+\r
+ @param PeiServices An indirect pointer to the PEI Services\r
+ Table published by the PEI Foundation.\r
+ @param This Interface pointer that implements the\r
+ particular EFI_PEI_SECURITY2_PPI instance.\r
+ @param AuthenticationStatus Authentication status of the file.\r
+ xx00 Image was not signed.\r
+ xxx1 Platform security policy override. \r
+ Assumes same meaning as 0010 (the image was signed, the\r
+ signature was tested, and the signature passed authentication test).\r
+ 0010 Image was signed, the signature was tested, \r
+ and the signature passed authentication test.\r
+ 0110 Image was signed and the signature was not tested.\r
+ 1010 Image was signed, the signature was tested, \r
+ and the signature failed the authentication test.\r
+ @param FvHandle Handle of the volume in which the file\r
+ resides. This allows different policies\r
+ depending on different firmware volumes.\r
+ @param FileHandle Handle of the file under review.\r
+ @param DeferExecution Pointer to a variable that alerts the\r
+ PEI Foundation to defer execution of a\r
+ PEIM.\r
+\r
+ @retval EFI_SUCCESS The service performed its action successfully.\r
+ @retval EFI_SECURITY_VIOLATION The object cannot be trusted.\r
\r
**/\r
typedef\r
(EFIAPI *EFI_PEI_SECURITY_AUTHENTICATION_STATE)(\r
IN CONST EFI_PEI_SERVICES **PeiServices,\r
IN CONST EFI_PEI_SECURITY2_PPI *This,\r
- IN CONST UINT32 AuthenticationStatus,\r
- IN CONST EFI_PEI_FV_HANDLE FvHandle,\r
- IN CONST EFI_PEI_FV_HANDLE FileHandle,\r
+ IN UINT32 AuthenticationStatus,\r
+ IN EFI_PEI_FV_HANDLE FvHandle,\r
+ IN EFI_PEI_FV_HANDLE FileHandle,\r
IN OUT BOOLEAN *DeferExecution\r
);\r
\r
-/**\r
- \r
- This PPI is a means by which the platform builder can indicate\r
- a response to a PEIM's authentication state. This can be in\r
- the form of a requirement for the PEI Foundation to skip a\r
- module using the DeferExecution Boolean output in the\r
- AuthenticationState() member function. Alternately, the\r
- Security PPI can invoke something like a cryptographic PPI\r
- that hashes the PEIM contents to log attestations, for which\r
- the FileHandle parameter in AuthenticationState() will be\r
- useful. If this PPI does not exist, PEIMs will be considered\r
- trusted.\r
-\r
- @param AuthenticationState Allows the platform builder to\r
- implement a security policy in\r
- response to varying file\r
- authentication states. See the\r
- AuthenticationState() function\r
- description.\r
-\r
-**/\r
+///\r
+/// This PPI is a means by which the platform builder can indicate\r
+/// a response to a PEIM's authentication state. This can be in\r
+/// the form of a requirement for the PEI Foundation to skip a\r
+/// module using the DeferExecution Boolean output in the\r
+/// AuthenticationState() member function. Alternately, the\r
+/// Security PPI can invoke something like a cryptographic PPI\r
+/// that hashes the PEIM contents to log attestations, for which\r
+/// the FileHandle parameter in AuthenticationState() will be\r
+/// useful. If this PPI does not exist, PEIMs will be considered\r
+/// trusted.\r
+///\r
struct _EFI_PEI_SECURITY2_PPI {\r
EFI_PEI_SECURITY_AUTHENTICATION_STATE AuthenticationState;\r
};\r