MdePkg/Include/Protocol/TrEEProtocol.h

   1 /** @file
   2   This protocol is defined to abstract TPM2 hardware access in boot phase.
   3
   4 Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __TREE_H__
  10 #define __TREE_H__
  11
  12 #include <IndustryStandard/UefiTcgPlatform.h>
  13 #include <IndustryStandard/Tpm20.h>
  14
  15 #define EFI_TREE_PROTOCOL_GUID \
  16   {0x607f766c, 0x7455, 0x42be, 0x93, 0x0b, 0xe4, 0xd7, 0x6d, 0xb2, 0x72, 0x0f}
  17
  18 typedef struct _EFI_TREE_PROTOCOL EFI_TREE_PROTOCOL;
  19
  20 typedef struct _TREE_VERSION {
  21   UINT8    Major;
  22   UINT8    Minor;
  23 } TREE_VERSION;
  24
  25 typedef UINT32 TREE_EVENT_LOG_BITMAP;
  26 typedef UINT32 TREE_EVENT_LOG_FORMAT;
  27
  28 #define TREE_EVENT_LOG_FORMAT_TCG_1_2  0x00000001
  29
  30 typedef struct _TREE_BOOT_SERVICE_CAPABILITY {
  31   //
  32   // Allocated size of the structure passed in
  33   //
  34   UINT8                    Size;
  35   //
  36   // Version of the TREE_BOOT_SERVICE_CAPABILITY structure itself.
  37   // For this version of the protocol, the Major version shall be set to 1
  38   // and the Minor version shall be set to 0.
  39   //
  40   TREE_VERSION             StructureVersion;
  41   //
  42   // Version of the TrEE protocol.
  43   // For this version of the protocol, the Major version shall be set to 1
  44   // and the Minor version shall be set to 0.
  45   //
  46   TREE_VERSION             ProtocolVersion;
  47   //
  48   // Supported hash algorithms
  49   //
  50   UINT32                   HashAlgorithmBitmap;
  51   //
  52   // Bitmap of supported event log formats
  53   //
  54   TREE_EVENT_LOG_BITMAP    SupportedEventLogs;
  55   //
  56   // False = TrEE not present
  57   //
  58   BOOLEAN                  TrEEPresentFlag;
  59   //
  60   // Max size (in bytes) of a command that can be sent to the TrEE
  61   //
  62   UINT16                   MaxCommandSize;
  63   //
  64   // Max size (in bytes) of a response that can be provided by the TrEE
  65   //
  66   UINT16                   MaxResponseSize;
  67   //
  68   // 4-byte Vendor ID (see Trusted Computing Group, "TCG Vendor ID Registry,"
  69   // Version 1.0, Revision 0.1, August 31, 2007, "TPM Capabilities Vendor ID" section)
  70   //
  71   UINT32                   ManufacturerID;
  72 } TREE_BOOT_SERVICE_CAPABILITY_1_0;
  73
  74 typedef TREE_BOOT_SERVICE_CAPABILITY_1_0 TREE_BOOT_SERVICE_CAPABILITY;
  75
  76 #define TREE_BOOT_HASH_ALG_SHA1    0x00000001
  77 #define TREE_BOOT_HASH_ALG_SHA256  0x00000002
  78 #define TREE_BOOT_HASH_ALG_SHA384  0x00000004
  79 #define TREE_BOOT_HASH_ALG_SHA512  0x00000008
  80
  81 //
  82 // This bit is shall be set when an event shall be extended but not logged.
  83 //
  84 #define TREE_EXTEND_ONLY  0x0000000000000001
  85 //
  86 // This bit shall be set when the intent is to measure a PE/COFF image.
  87 //
  88 #define PE_COFF_IMAGE  0x0000000000000010
  89
  90 typedef UINT32 TrEE_PCRINDEX;
  91 typedef UINT32 TrEE_EVENTTYPE;
  92
  93 #define MAX_PCR_INDEX              23
  94 #define TREE_EVENT_HEADER_VERSION  1
  95
  96 #pragma pack(1)
  97
  98 typedef struct {
  99   //
 100   // Size of the event header itself (sizeof(TrEE_EVENT_HEADER)).
 101   //
 102   UINT32            HeaderSize;
 103   //
 104   // Header version. For this version of this specification, the value shall be 1.
 105   //
 106   UINT16            HeaderVersion;
 107   //
 108   // Index of the PCR that shall be extended (0 - 23).
 109   //
 110   TrEE_PCRINDEX     PCRIndex;
 111   //
 112   // Type of the event that shall be extended (and optionally logged).
 113   //
 114   TrEE_EVENTTYPE    EventType;
 115 } TrEE_EVENT_HEADER;
 116
 117 typedef struct {
 118   //
 119   // Total size of the event including the Size component, the header and the Event data.
 120   //
 121   UINT32               Size;
 122   TrEE_EVENT_HEADER    Header;
 123   UINT8                Event[1];
 124 } TrEE_EVENT;
 125
 126 #pragma pack()
 127
 128 /**
 129   The EFI_TREE_PROTOCOL GetCapability function call provides protocol
 130   capability information and state information about the TrEE.
 131
 132   @param[in]  This               Indicates the calling context
 133   @param[out] ProtocolCapability The caller allocates memory for a TREE_BOOT_SERVICE_CAPABILITY
 134                                  structure and sets the size field to the size of the structure allocated.
 135                                  The callee fills in the fields with the EFI protocol capability information
 136                                  and the current TrEE state information up to the number of fields which
 137                                  fit within the size of the structure passed in.
 138
 139   @retval EFI_SUCCESS            Operation completed successfully.
 140   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 141                                  The ProtocolCapability variable will not be populated.
 142   @retval EFI_INVALID_PARAMETER  One or more of the parameters are incorrect.
 143                                  The ProtocolCapability variable will not be populated.
 144   @retval EFI_BUFFER_TOO_SMALL   The ProtocolCapability variable is too small to hold the full response.
 145                                  It will be partially populated (required Size field will be set).
 146 **/
 147 typedef
 148 EFI_STATUS
 149 (EFIAPI *EFI_TREE_GET_CAPABILITY)(
 150   IN EFI_TREE_PROTOCOL                *This,
 151   IN OUT TREE_BOOT_SERVICE_CAPABILITY *ProtocolCapability
 152   );
 153
 154 /**
 155   The EFI_TREE_PROTOCOL Get Event Log function call allows a caller to
 156   retrieve the address of a given event log and its last entry.
 157
 158   @param[in]  This               Indicates the calling context
 159   @param[in]  EventLogFormat     The type of the event log for which the information is requested.
 160   @param[out] EventLogLocation   A pointer to the memory address of the event log.
 161   @param[out] EventLogLastEntry  If the Event Log contains more than one entry, this is a pointer to the
 162                                  address of the start of the last entry in the event log in memory.
 163   @param[out] EventLogTruncated  If the Event Log is missing at least one entry because an event would
 164                                  have exceeded the area allocated for events, this value is set to TRUE.
 165                                  Otherwise, the value will be FALSE and the Event Log will be complete.
 166
 167   @retval EFI_SUCCESS            Operation completed successfully.
 168   @retval EFI_INVALID_PARAMETER  One or more of the parameters are incorrect
 169                                  (e.g. asking for an event log whose format is not supported).
 170 **/
 171 typedef
 172 EFI_STATUS
 173 (EFIAPI *EFI_TREE_GET_EVENT_LOG)(
 174   IN EFI_TREE_PROTOCOL     *This,
 175   IN TREE_EVENT_LOG_FORMAT EventLogFormat,
 176   OUT EFI_PHYSICAL_ADDRESS *EventLogLocation,
 177   OUT EFI_PHYSICAL_ADDRESS *EventLogLastEntry,
 178   OUT BOOLEAN              *EventLogTruncated
 179   );
 180
 181 /**
 182   The EFI_TREE_PROTOCOL HashLogExtendEvent function call provides callers with
 183   an opportunity to extend and optionally log events without requiring
 184   knowledge of actual TPM commands.
 185   The extend operation will occur even if this function cannot create an event
 186   log entry (e.g. due to the event log being full).
 187
 188   @param[in]  This               Indicates the calling context
 189   @param[in]  Flags              Bitmap providing additional information.
 190   @param[in]  DataToHash         Physical address of the start of the data buffer to be hashed.
 191   @param[in]  DataToHashLen      The length in bytes of the buffer referenced by DataToHash.
 192   @param[in]  Event              Pointer to data buffer containing information about the event.
 193
 194   @retval EFI_SUCCESS            Operation completed successfully.
 195   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 196   @retval EFI_VOLUME_FULL        The extend operation occurred, but the event could not be written to one or more event logs.
 197   @retval EFI_INVALID_PARAMETER  One or more of the parameters are incorrect.
 198   @retval EFI_UNSUPPORTED        The PE/COFF image type is not supported.
 199 **/
 200 typedef
 201 EFI_STATUS
 202 (EFIAPI *EFI_TREE_HASH_LOG_EXTEND_EVENT)(
 203   IN EFI_TREE_PROTOCOL    *This,
 204   IN UINT64               Flags,
 205   IN EFI_PHYSICAL_ADDRESS DataToHash,
 206   IN UINT64               DataToHashLen,
 207   IN TrEE_EVENT           *Event
 208   );
 209
 210 /**
 211   This service enables the sending of commands to the TrEE.
 212
 213   @param[in]  This                     Indicates the calling context
 214   @param[in]  InputParameterBlockSize  Size of the TrEE input parameter block.
 215   @param[in]  InputParameterBlock      Pointer to the TrEE input parameter block.
 216   @param[in]  OutputParameterBlockSize Size of the TrEE output parameter block.
 217   @param[in]  OutputParameterBlock     Pointer to the TrEE output parameter block.
 218
 219   @retval EFI_SUCCESS            The command byte stream was successfully sent to the device and a response was successfully received.
 220   @retval EFI_DEVICE_ERROR       The command was not successfully sent to the device or a response was not successfully received from the device.
 221   @retval EFI_INVALID_PARAMETER  One or more of the parameters are incorrect.
 222   @retval EFI_BUFFER_TOO_SMALL   The output parameter block is too small.
 223 **/
 224 typedef
 225 EFI_STATUS
 226 (EFIAPI *EFI_TREE_SUBMIT_COMMAND)(
 227   IN EFI_TREE_PROTOCOL *This,
 228   IN UINT32            InputParameterBlockSize,
 229   IN UINT8             *InputParameterBlock,
 230   IN UINT32            OutputParameterBlockSize,
 231   IN UINT8             *OutputParameterBlock
 232   );
 233
 234 struct _EFI_TREE_PROTOCOL {
 235   EFI_TREE_GET_CAPABILITY           GetCapability;
 236   EFI_TREE_GET_EVENT_LOG            GetEventLog;
 237   EFI_TREE_HASH_LOG_EXTEND_EVENT    HashLogExtendEvent;
 238   EFI_TREE_SUBMIT_COMMAND           SubmitCommand;
 239 };
 240
 241 extern EFI_GUID  gEfiTrEEProtocolGuid;
 242
 243 #endif