SecurityPkg/Include/Library/TrEEPpVendorLib.h

   1 /** @file
   2   This library is to support Trusted Execution Environment (TrEE) ACPI Profile
   3   >= 128 Vendor Specific PPI Operation.
   4
   5   The Vendor Specific PPI operation may change TPM state, BIOS TPM management
   6   flags, and may need additional boot cycle.
   7
   8   Caution: This function may receive untrusted input.
   9
  10 Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>
  11 This program and the accompanying materials
  12 are licensed and made available under the terms and conditions of the BSD License
  13 which accompanies this distribution.  The full text of the license may be found at
  14 http://opensource.org/licenses/bsd-license.php
  15
  16 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  17 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  18
  19 **/
  20
  21 #ifndef _TREE_PP_VENDOR_LIB_H_
  22 #define _TREE_PP_VENDOR_LIB_H_
  23
  24 #include <IndustryStandard/Tpm20.h>
  25 #include <Protocol/TrEEProtocol.h>
  26
  27 //
  28 // The definition of physical presence operation actions
  29 //
  30 #define TREE_PHYSICAL_PRESENCE_VENDOR_SPECIFIC_OPERATION                         128
  31
  32 //
  33 // The definition bit of the BIOS TPM Management Flags
  34 //
  35 // BIT0 is reserved
  36 #define TREE_BIOS_TPM_MANAGEMENT_FLAG_NO_PPI_CLEAR                        BIT1
  37 // BIT2 is reserved
  38 #define TREE_VENDOR_LIB_FLAG_RESET_TRACK                                  BIT3
  39
  40 //
  41 // The definition for TPM Operation Response to OS Environment
  42 //
  43 #define TREE_PP_OPERATION_RESPONSE_SUCCESS              0x0
  44 #define TREE_PP_OPERATION_RESPONSE_USER_ABORT           0xFFFFFFF0
  45 #define TREE_PP_OPERATION_RESPONSE_BIOS_FAILURE         0xFFFFFFF1
  46
  47 //
  48 // The return code for Sumbit TPM Request to Pre-OS Environment
  49 // and Sumbit TPM Request to Pre-OS Environment 2
  50 //
  51 #define TREE_PP_SUBMIT_REQUEST_TO_PREOS_SUCCESS                                  0
  52 #define TREE_PP_SUBMIT_REQUEST_TO_PREOS_NOT_IMPLEMENTED                          1
  53 #define TREE_PP_SUBMIT_REQUEST_TO_PREOS_GENERAL_FAILURE                          2
  54 #define TREE_PP_SUBMIT_REQUEST_TO_PREOS_BLOCKED_BY_BIOS_SETTINGS                 3
  55
  56 //
  57 // The return code for Get User Confirmation Status for Operation
  58 //
  59 #define TREE_PP_GET_USER_CONFIRMATION_NOT_IMPLEMENTED                                 0
  60 #define TREE_PP_GET_USER_CONFIRMATION_BIOS_ONLY                                       1
  61 #define TREE_PP_GET_USER_CONFIRMATION_BLOCKED_BY_BIOS_CONFIGURATION                   2
  62 #define TREE_PP_GET_USER_CONFIRMATION_ALLOWED_AND_PPUSER_REQUIRED                     3
  63 #define TREE_PP_GET_USER_CONFIRMATION_ALLOWED_AND_PPUSER_NOT_REQUIRED                 4
  64
  65 /**
  66   Check and execute the requested physical presence command.
  67
  68   This API should be invoked in BIOS boot phase to process pending request.
  69
  70   Caution: This function may receive untrusted input.
  71
  72   If OperationRequest < 128, then ASSERT().
  73
  74   @param[in]      PlatformAuth     platform auth value. NULL means no platform auth change.
  75   @param[in]      OperationRequest TPM physical presence operation request.
  76   @param[in, out] ManagementFlags  BIOS TPM Management Flags.
  77   @param[out]     ResetRequired    If reset is required to vendor settings in effect.
  78                                    True, it indicates the reset is required.
  79                                    False, it indicates the reset is not required.
  80
  81   @return TPM Operation Response to OS Environment.
  82 **/
  83 UINT32
  84 EFIAPI
  85 TrEEPpVendorLibExecutePendingRequest (
  86   IN TPM2B_AUTH             *PlatformAuth,  OPTIONAL
  87   IN UINT32                 OperationRequest,
  88   IN OUT UINT32             *ManagementFlags,
  89   OUT BOOLEAN               *ResetRequired
  90   );
  91
  92 /**
  93   Check if there is a valid physical presence command request.
  94
  95   This API should be invoked in BIOS boot phase to process pending request.
  96
  97   Caution: This function may receive untrusted input.
  98
  99   If OperationRequest < 128, then ASSERT().
 100
 101   @param[in]      OperationRequest TPM physical presence operation request.
 102   @param[in]      ManagementFlags  BIOS TPM Management Flags.
 103   @param[out]     RequestConfirmed If the physical presence operation command required user confirm from UI.
 104                                    True, it indicates the command doesn't require user confirm.
 105                                    False, it indicates the command need user confirm from UI.
 106
 107   @retval  TRUE        Physical Presence operation command is valid.
 108   @retval  FALSE       Physical Presence operation command is invalid.
 109 **/
 110 BOOLEAN
 111 EFIAPI
 112 TrEEPpVendorLibHasValidRequest (
 113   IN UINT32                 OperationRequest,
 114   IN UINT32                 ManagementFlags,
 115   OUT BOOLEAN               *RequestConfirmed
 116   );
 117
 118 /**
 119   The callback for TPM vendor specific physical presence which is called for
 120   Submit TPM Operation Request to Pre-OS Environment and
 121   Submit TPM Operation Request to Pre-OS Environment 2.
 122
 123   This API should be invoked in OS runtime phase to interface with ACPI method.
 124
 125   Caution: This function may receive untrusted input.
 126
 127   If OperationRequest < 128, then ASSERT().
 128
 129   @param[in]      OperationRequest TPM physical presence operation request.
 130   @param[in]      ManagementFlags  BIOS TPM Management Flags.
 131
 132   @return Return Code for Submit TPM Operation Request to Pre-OS Environment and
 133           Submit TPM Operation Request to Pre-OS Environment 2.
 134 **/
 135 UINT32
 136 EFIAPI
 137 TrEEPpVendorLibSubmitRequestToPreOSFunction (
 138   IN UINT32                 OperationRequest,
 139   IN UINT32                 ManagementFlags
 140   );
 141
 142 /**
 143   The callback for TPM vendor specific physical presence which is called for
 144   Get User Confirmation Status for Operation.
 145
 146   This API should be invoked in OS runtime phase to interface with ACPI method.
 147
 148   Caution: This function may receive untrusted input.
 149
 150   If OperationRequest < 128, then ASSERT().
 151
 152   @param[in]      OperationRequest TPM physical presence operation request.
 153   @param[in]      ManagementFlags  BIOS TPM Management Flags.
 154
 155   @return Return Code for Get User Confirmation Status for Operation.
 156 **/
 157 UINT32
 158 EFIAPI
 159 TrEEPpVendorLibGetUserConfirmationStatusFunction (
 160   IN UINT32                 OperationRequest,
 161   IN UINT32                 ManagementFlags
 162   );
 163
 164 #endif