MdePkg/Include/Ppi/Security2.h

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