1 /** @file 2 This file declares Pei Security2 PPI. 3 4 This PPI is installed by some platform PEIM that abstracts the security 5 policy to the PEI Foundation, namely the case of a PEIM's authentication 6 state being returned during the PEI section extraction process. 7 8 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 9 SPDX-License-Identifier: BSD-2-Clause-Patent 10 11 @par Revision Reference: 12 This PPI is introduced in PI Version 1.0. 13 14 **/ 15 16 #ifndef __SECURITY2_PPI_H__ 17 #define __SECURITY2_PPI_H__ 18 19 #define EFI_PEI_SECURITY2_PPI_GUID \ 20 { 0xdcd0be23, 0x9586, 0x40f4, { 0xb6, 0x43, 0x6, 0x52, 0x2c, 0xed, 0x4e, 0xde } } 21 22 23 typedef struct _EFI_PEI_SECURITY2_PPI EFI_PEI_SECURITY2_PPI; 24 25 /** 26 Allows the platform builder to implement a security policy 27 in response to varying file authentication states. 28 29 This service is published by some platform PEIM. The purpose of 30 this service is to expose a given platform's policy-based 31 response to the PEI Foundation. For example, if there is a PEIM 32 in a GUIDed encapsulation section and the extraction of the PEI 33 file section yields an authentication failure, there is no a 34 priori policy in the PEI Foundation. Specifically, this 35 situation leads to the question whether PEIMs that are either 36 not in GUIDed sections or are in sections whose authentication 37 fails should still be executed. 38 39 @param PeiServices An indirect pointer to the PEI Services 40 Table published by the PEI Foundation. 41 @param This Interface pointer that implements the 42 particular EFI_PEI_SECURITY2_PPI instance. 43 @param AuthenticationStatus Authentication status of the file. 44 xx00 Image was not signed. 45 xxx1 Platform security policy override. 46 Assumes same meaning as 0010 (the image was signed, the 47 signature was tested, and the signature passed authentication test). 48 0010 Image was signed, the signature was tested, 49 and the signature passed authentication test. 50 0110 Image was signed and the signature was not tested. 51 1010 Image was signed, the signature was tested, 52 and the signature failed the authentication test. 53 @param FvHandle Handle of the volume in which the file 54 resides. This allows different policies 55 depending on different firmware volumes. 56 @param FileHandle Handle of the file under review. 57 @param DeferExecution Pointer to a variable that alerts the 58 PEI Foundation to defer execution of a 59 PEIM. 60 61 @retval EFI_SUCCESS The service performed its action successfully. 62 @retval EFI_SECURITY_VIOLATION The object cannot be trusted. 63 64 **/ 65 typedef 66 EFI_STATUS 67 (EFIAPI *EFI_PEI_SECURITY_AUTHENTICATION_STATE)( 68 IN CONST EFI_PEI_SERVICES **PeiServices, 69 IN CONST EFI_PEI_SECURITY2_PPI *This, 70 IN UINT32 AuthenticationStatus, 71 IN EFI_PEI_FV_HANDLE FvHandle, 72 IN EFI_PEI_FILE_HANDLE FileHandle, 73 IN OUT BOOLEAN *DeferExecution 74 ); 75 76 /// 77 /// This PPI is a means by which the platform builder can indicate 78 /// a response to a PEIM's authentication state. This can be in 79 /// the form of a requirement for the PEI Foundation to skip a 80 /// module using the DeferExecution Boolean output in the 81 /// AuthenticationState() member function. Alternately, the 82 /// Security PPI can invoke something like a cryptographic PPI 83 /// that hashes the PEIM contents to log attestations, for which 84 /// the FileHandle parameter in AuthenticationState() will be 85 /// useful. If this PPI does not exist, PEIMs will be considered 86 /// trusted. 87 /// 88 struct _EFI_PEI_SECURITY2_PPI { 89 EFI_PEI_SECURITY_AUTHENTICATION_STATE AuthenticationState; 90 }; 91 92 93 extern EFI_GUID gEfiPeiSecurity2PpiGuid; 94 95 #endif 96