/** @file\r
- This file declares Security2 Architectural PPI.\r
+ This file declares Pei Security2 PPI.\r
\r
- Copyright (c) 2006 - 2007, Intel Corporation\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
+ state being returned during the PEI section extraction process.\r
+\r
+ Copyright (c) 2006 - 2008, Intel Corporation\r
All rights reserved. This program and the accompanying materials \r
are licensed and made available under the terms and conditions of the BSD License \r
which accompanies this distribution. The full text of the license may be found at \r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
\r
- Module Name: Security.h\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
typedef struct _EFI_PEI_SECURITY2_PPI EFI_PEI_SECURITY2_PPI;\r
\r
/**\r
- \r
+ Allows the platform builder to implement a security policy \r
+ in response to varying file authentication states.\r
+\r
This service is published by some platform PEIM. The purpose of\r
this service is to expose a given platform's policy-based\r
response to the PEI Foundation. For example, if there is a PEIM\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 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
EFI_STATUS\r
-(EFIAPI *EFI_PEI_SECURITY_AUTHENTICATION_STATE) (\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