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