MdePkg/Include/Ppi/Security2.h

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