+/** @file\r
+ This file declares Security2 Architectural PPI.\r
+\r
+ Copyright (c) 2006 - 2007, 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
+ http://opensource.org/licenses/bsd-license.php \r
+\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
+\r
+**/\r
+\r
+#ifndef __SECURITY2_PPI_H__\r
+#define __SECURITY2_PPI_H__\r
+\r
+#define EFI_PEI_SECURITY2_PPI_GUID \\r
+ { 0xdcd0be23, 0x9586, 0x40f4, { 0xb6, 0x43, 0x6, 0x52, 0x2c, 0xed, 0x4e, 0xde } }\r
+\r
+\r
+typedef _EFI_PEI_SECURITY2_PPI EFI_PEI_SECURITY2_PPI;\r
+\r
+/**\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
+ in a GUIDed encapsulation section and the extraction of the PEI\r
+ file section yields an authentication failure, there is no a\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
+\r
+**/\r
+typedef\r
+EFI_STATUS\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 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
+struct _EFI_PEI_SECURITY2_PPI {\r
+ EFI_PEI_SECURITY_AUTHENTICATION_STATE AuthenticationState;\r
+};\r
+\r
+\r
+extern EFI_GUID gEfiPeiSecurity2PpiGuid;\r
+\r
+#endif\r
projects / mirror_edk2.git / commitdiff