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.
  45
  46   @param PeiServices             An indirect pointer to the PEI Services
  47                                  Table published by the PEI Foundation.
  48   @param This                    Interface pointer that implements the
  49                                  particular EFI_PEI_SECURITY2_PPI instance.
  50   @param AuthenticationStatus    Authentication status of the file.
  51   @param FvHandle                Handle of the volume in which the file
  52                                  resides. This allows different policies
  53                                  depending on different firmware volumes.
  54   @param FileHandle              Handle of the file under review.
  55   @param DeferExecution          Pointer to a variable that alerts the
  56                                  PEI Foundation to defer execution of a
  57                                  PEIM.
  58
  59   @retval EFI_SUCCESS            The service performed its action successfully.
  60   @retval EFI_SECURITY_VIOLATION The object cannot be trusted.
  61
  62 **/
  63 typedef
  64 EFI_STATUS
  65 (EFIAPI *EFI_PEI_SECURITY_AUTHENTICATION_STATE)(
  66   IN CONST  EFI_PEI_SERVICES      **PeiServices,
  67   IN CONST  EFI_PEI_SECURITY2_PPI *This,
  68   IN UINT32                       AuthenticationStatus,
  69   IN EFI_PEI_FV_HANDLE            FvHandle,
  70   IN EFI_PEI_FV_HANDLE            FileHandle,
  71   IN OUT    BOOLEAN               *DeferExecution
  72 );
  73
  74 ///
  75 /// This PPI is a means by which the platform builder can indicate
  76 /// a response to a PEIM's authentication state. This can be in
  77 /// the form of a requirement for the PEI Foundation to skip a
  78 /// module using the DeferExecution Boolean output in the
  79 /// AuthenticationState() member function. Alternately, the
  80 /// Security PPI can invoke something like a cryptographic PPI
  81 /// that hashes the PEIM contents to log attestations, for which
  82 /// the FileHandle parameter in AuthenticationState() will be
  83 /// useful. If this PPI does not exist, PEIMs will be considered
  84 /// trusted.
  85 ///
  86 struct _EFI_PEI_SECURITY2_PPI {
  87   ///
  88   /// Allows the platform builder to implement a security policy
  89   /// in response to varying file authentication states.
  90   ///
  91   EFI_PEI_SECURITY_AUTHENTICATION_STATE   AuthenticationState;
  92 };
  93
  94
  95 extern EFI_GUID gEfiPeiSecurity2PpiGuid;
  96
  97 #endif