xref: /illumos-gate/usr/src/boot/efi/include/Protocol/Tcg2Protocol.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   TPM2 Protocol as defined in TCG PC Client Platform EFI Protocol Specification Family "2.0".
3   See http://trustedcomputinggroup.org for the latest specification
4 
5 Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
7 
8 **/
9 
10 #ifndef __TCG2_PROTOCOL_H__
11 #define __TCG2_PROTOCOL_H__
12 
13 #include <IndustryStandard/UefiTcgPlatform.h>
14 #include <IndustryStandard/Tpm20.h>
15 
16 #define EFI_TCG2_PROTOCOL_GUID \
17   {0x607f766c, 0x7455, 0x42be, { 0x93, 0x0b, 0xe4, 0xd7, 0x6d, 0xb2, 0x72, 0x0f }}
18 
19 typedef struct tdEFI_TCG2_PROTOCOL EFI_TCG2_PROTOCOL;
20 
21 typedef struct tdEFI_TCG2_VERSION {
22   UINT8    Major;
23   UINT8    Minor;
24 } EFI_TCG2_VERSION;
25 
26 typedef UINT32 EFI_TCG2_EVENT_LOG_BITMAP;
27 typedef UINT32 EFI_TCG2_EVENT_LOG_FORMAT;
28 typedef UINT32 EFI_TCG2_EVENT_ALGORITHM_BITMAP;
29 
30 #define EFI_TCG2_EVENT_LOG_FORMAT_TCG_1_2  0x00000001
31 #define EFI_TCG2_EVENT_LOG_FORMAT_TCG_2    0x00000002
32 
33 typedef struct tdEFI_TCG2_BOOT_SERVICE_CAPABILITY {
34   //
35   // Allocated size of the structure
36   //
37   UINT8                              Size;
38   //
39   // Version of the EFI_TCG2_BOOT_SERVICE_CAPABILITY structure itself.
40   // For this version of the protocol, the Major version shall be set to 1
41   // and the Minor version shall be set to 1.
42   //
43   EFI_TCG2_VERSION                   StructureVersion;
44   //
45   // Version of the EFI TCG2 protocol.
46   // For this version of the protocol, the Major version shall be set to 1
47   // and the Minor version shall be set to 1.
48   //
49   EFI_TCG2_VERSION                   ProtocolVersion;
50   //
51   // Supported hash algorithms (this bitmap is determined by the supported PCR
52   // banks in the TPM and the hashing algorithms supported by the firmware)
53   //
54   EFI_TCG2_EVENT_ALGORITHM_BITMAP    HashAlgorithmBitmap;
55   //
56   // Bitmap of supported event log formats
57   //
58   EFI_TCG2_EVENT_LOG_BITMAP          SupportedEventLogs;
59   //
60   // False = TPM not present
61   //
62   BOOLEAN                            TPMPresentFlag;
63   //
64   // Max size (in bytes) of a command that can be sent to the TPM
65   //
66   UINT16                             MaxCommandSize;
67   //
68   // Max size (in bytes) of a response that can be provided by the TPM
69   //
70   UINT16                             MaxResponseSize;
71   //
72   // 4-byte Vendor ID
73   // (see TCG Vendor ID registry, Section "TPM Capabilities Vendor ID")
74   //
75   UINT32                             ManufacturerID;
76   //
77   // Maximum number of PCR banks (hashing algorithms) supported.
78   // No granularity is provided to support a specific set of algorithms.
79   // Minimum value is 1.
80   //
81   UINT32                             NumberOfPCRBanks;
82   //
83   // A bitmap of currently active PCR banks (hashing algorithms).
84   // This is a subset of the supported hashing algorithms reported in HashAlgorithmBitMap.
85   // NumberOfPcrBanks defines the number of bits that are set.
86   //
87   EFI_TCG2_EVENT_ALGORITHM_BITMAP    ActivePcrBanks;
88 } EFI_TCG2_BOOT_SERVICE_CAPABILITY;
89 
90 #define EFI_TCG2_BOOT_HASH_ALG_SHA1     0x00000001
91 #define EFI_TCG2_BOOT_HASH_ALG_SHA256   0x00000002
92 #define EFI_TCG2_BOOT_HASH_ALG_SHA384   0x00000004
93 #define EFI_TCG2_BOOT_HASH_ALG_SHA512   0x00000008
94 #define EFI_TCG2_BOOT_HASH_ALG_SM3_256  0x00000010
95 
96 //
97 // This bit is shall be set when an event shall be extended but not logged.
98 //
99 #define EFI_TCG2_EXTEND_ONLY  0x0000000000000001
100 //
101 // This bit shall be set when the intent is to measure a PE/COFF image.
102 //
103 #define PE_COFF_IMAGE  0x0000000000000010
104 
105 #define MAX_PCR_INDEX  23
106 
107 #pragma pack(1)
108 
109 #define EFI_TCG2_EVENT_HEADER_VERSION  1
110 
111 typedef struct {
112   //
113   // Size of the event header itself (sizeof(EFI_TCG2_EVENT_HEADER)).
114   //
115   UINT32           HeaderSize;
116   //
117   // Header version. For this version of this specification, the value shall be 1.
118   //
119   UINT16           HeaderVersion;
120   //
121   // Index of the PCR that shall be extended (0 - 23).
122   //
123   TCG_PCRINDEX     PCRIndex;
124   //
125   // Type of the event that shall be extended (and optionally logged).
126   //
127   TCG_EVENTTYPE    EventType;
128 } EFI_TCG2_EVENT_HEADER;
129 
130 typedef struct tdEFI_TCG2_EVENT {
131   //
132   // Total size of the event including the Size component, the header and the Event data.
133   //
134   UINT32                   Size;
135   EFI_TCG2_EVENT_HEADER    Header;
136   UINT8                    Event[1];
137 } EFI_TCG2_EVENT;
138 
139 #pragma pack()
140 
141 /**
142   The EFI_TCG2_PROTOCOL GetCapability function call provides protocol
143   capability information and state information.
144 
145   @param[in]      This               Indicates the calling context
146   @param[in, out] ProtocolCapability The caller allocates memory for a EFI_TCG2_BOOT_SERVICE_CAPABILITY
147                                      structure and sets the size field to the size of the structure allocated.
148                                      The callee fills in the fields with the EFI protocol capability information
149                                      and the current EFI TCG2 state information up to the number of fields which
150                                      fit within the size of the structure passed in.
151 
152   @retval EFI_SUCCESS            Operation completed successfully.
153   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
154                                  The ProtocolCapability variable will not be populated.
155   @retval EFI_INVALID_PARAMETER  One or more of the parameters are incorrect.
156                                  The ProtocolCapability variable will not be populated.
157   @retval EFI_BUFFER_TOO_SMALL   The ProtocolCapability variable is too small to hold the full response.
158                                  It will be partially populated (required Size field will be set).
159 **/
160 typedef
161 EFI_STATUS
162 (EFIAPI *EFI_TCG2_GET_CAPABILITY)(
163   IN EFI_TCG2_PROTOCOL                    *This,
164   IN OUT EFI_TCG2_BOOT_SERVICE_CAPABILITY *ProtocolCapability
165   );
166 
167 /**
168   The EFI_TCG2_PROTOCOL Get Event Log function call allows a caller to
169   retrieve the address of a given event log and its last entry.
170 
171   @param[in]  This               Indicates the calling context
172   @param[in]  EventLogFormat     The type of the event log for which the information is requested.
173   @param[out] EventLogLocation   A pointer to the memory address of the event log.
174   @param[out] EventLogLastEntry  If the Event Log contains more than one entry, this is a pointer to the
175                                  address of the start of the last entry in the event log in memory.
176   @param[out] EventLogTruncated  If the Event Log is missing at least one entry because an event would
177                                  have exceeded the area allocated for events, this value is set to TRUE.
178                                  Otherwise, the value will be FALSE and the Event Log will be complete.
179 
180   @retval EFI_SUCCESS            Operation completed successfully.
181   @retval EFI_INVALID_PARAMETER  One or more of the parameters are incorrect
182                                  (e.g. asking for an event log whose format is not supported).
183 **/
184 typedef
185 EFI_STATUS
186 (EFIAPI *EFI_TCG2_GET_EVENT_LOG)(
187   IN EFI_TCG2_PROTOCOL         *This,
188   IN EFI_TCG2_EVENT_LOG_FORMAT EventLogFormat,
189   OUT EFI_PHYSICAL_ADDRESS     *EventLogLocation,
190   OUT EFI_PHYSICAL_ADDRESS     *EventLogLastEntry,
191   OUT BOOLEAN                  *EventLogTruncated
192   );
193 
194 /**
195   The EFI_TCG2_PROTOCOL HashLogExtendEvent function call provides callers with
196   an opportunity to extend and optionally log events without requiring
197   knowledge of actual TPM commands.
198   The extend operation will occur even if this function cannot create an event
199   log entry (e.g. due to the event log being full).
200 
201   @param[in]  This               Indicates the calling context
202   @param[in]  Flags              Bitmap providing additional information.
203   @param[in]  DataToHash         Physical address of the start of the data buffer to be hashed.
204   @param[in]  DataToHashLen      The length in bytes of the buffer referenced by DataToHash.
205   @param[in]  EfiTcgEvent        Pointer to data buffer containing information about the event.
206 
207   @retval EFI_SUCCESS            Operation completed successfully.
208   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
209   @retval EFI_VOLUME_FULL        The extend operation occurred, but the event could not be written to one or more event logs.
210   @retval EFI_INVALID_PARAMETER  One or more of the parameters are incorrect.
211   @retval EFI_UNSUPPORTED        The PE/COFF image type is not supported.
212 **/
213 typedef
214 EFI_STATUS
215 (EFIAPI *EFI_TCG2_HASH_LOG_EXTEND_EVENT)(
216   IN EFI_TCG2_PROTOCOL    *This,
217   IN UINT64               Flags,
218   IN EFI_PHYSICAL_ADDRESS DataToHash,
219   IN UINT64               DataToHashLen,
220   IN EFI_TCG2_EVENT       *EfiTcgEvent
221   );
222 
223 /**
224   This service enables the sending of commands to the TPM.
225 
226   @param[in]  This                     Indicates the calling context
227   @param[in]  InputParameterBlockSize  Size of the TPM input parameter block.
228   @param[in]  InputParameterBlock      Pointer to the TPM input parameter block.
229   @param[in]  OutputParameterBlockSize Size of the TPM output parameter block.
230   @param[in]  OutputParameterBlock     Pointer to the TPM output parameter block.
231 
232   @retval EFI_SUCCESS            The command byte stream was successfully sent to the device and a response was successfully received.
233   @retval EFI_DEVICE_ERROR       The command was not successfully sent to the device or a response was not successfully received from the device.
234   @retval EFI_INVALID_PARAMETER  One or more of the parameters are incorrect.
235   @retval EFI_BUFFER_TOO_SMALL   The output parameter block is too small.
236 **/
237 typedef
238 EFI_STATUS
239 (EFIAPI *EFI_TCG2_SUBMIT_COMMAND)(
240   IN EFI_TCG2_PROTOCOL *This,
241   IN UINT32            InputParameterBlockSize,
242   IN UINT8             *InputParameterBlock,
243   IN UINT32            OutputParameterBlockSize,
244   IN UINT8             *OutputParameterBlock
245   );
246 
247 /**
248   This service returns the currently active PCR banks.
249 
250   @param[in]  This            Indicates the calling context
251   @param[out] ActivePcrBanks  Pointer to the variable receiving the bitmap of currently active PCR banks.
252 
253   @retval EFI_SUCCESS           The bitmap of active PCR banks was stored in the ActivePcrBanks parameter.
254   @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect.
255 **/
256 typedef
257 EFI_STATUS
258 (EFIAPI *EFI_TCG2_GET_ACTIVE_PCR_BANKS)(
259   IN  EFI_TCG2_PROTOCOL *This,
260   OUT UINT32            *ActivePcrBanks
261   );
262 
263 /**
264   This service sets the currently active PCR banks.
265 
266   @param[in]  This            Indicates the calling context
267   @param[in]  ActivePcrBanks  Bitmap of the requested active PCR banks. At least one bit SHALL be set.
268 
269   @retval EFI_SUCCESS           The bitmap in ActivePcrBank parameter is already active.
270   @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect.
271 **/
272 typedef
273 EFI_STATUS
274 (EFIAPI *EFI_TCG2_SET_ACTIVE_PCR_BANKS)(
275   IN EFI_TCG2_PROTOCOL *This,
276   IN UINT32            ActivePcrBanks
277   );
278 
279 /**
280   This service retrieves the result of a previous invocation of SetActivePcrBanks.
281 
282   @param[in]  This              Indicates the calling context
283   @param[out] OperationPresent  Non-zero value to indicate a SetActivePcrBank operation was invoked during the last boot.
284   @param[out] Response          The response from the SetActivePcrBank request.
285 
286   @retval EFI_SUCCESS           The result value could be returned.
287   @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect.
288 **/
289 typedef
290 EFI_STATUS
291 (EFIAPI *EFI_TCG2_GET_RESULT_OF_SET_ACTIVE_PCR_BANKS)(
292   IN  EFI_TCG2_PROTOCOL  *This,
293   OUT UINT32             *OperationPresent,
294   OUT UINT32             *Response
295   );
296 
297 struct tdEFI_TCG2_PROTOCOL {
298   EFI_TCG2_GET_CAPABILITY                        GetCapability;
299   EFI_TCG2_GET_EVENT_LOG                         GetEventLog;
300   EFI_TCG2_HASH_LOG_EXTEND_EVENT                 HashLogExtendEvent;
301   EFI_TCG2_SUBMIT_COMMAND                        SubmitCommand;
302   EFI_TCG2_GET_ACTIVE_PCR_BANKS                  GetActivePcrBanks;
303   EFI_TCG2_SET_ACTIVE_PCR_BANKS                  SetActivePcrBanks;
304   EFI_TCG2_GET_RESULT_OF_SET_ACTIVE_PCR_BANKS    GetResultOfSetActivePcrBanks;
305 };
306 
307 extern EFI_GUID  gEfiTcg2ProtocolGuid;
308 
309 //
310 // Log entries after Get Event Log service
311 //
312 
313 #define EFI_TCG2_FINAL_EVENTS_TABLE_GUID \
314   {0x1e2ed096, 0x30e2, 0x4254, { 0xbd, 0x89, 0x86, 0x3b, 0xbe, 0xf8, 0x23, 0x25 }}
315 
316 extern EFI_GUID  gEfiTcg2FinalEventsTableGuid;
317 
318 typedef struct tdEFI_TCG2_FINAL_EVENTS_TABLE {
319   //
320   // The version of this structure.
321   //
322   UINT64    Version;
323   //
324   // Number of events recorded after invocation of GetEventLog API
325   //
326   UINT64    NumberOfEvents;
327   //
328   // List of events of type TCG_PCR_EVENT2.
329   //
330   // TCG_PCR_EVENT2          Event[1];
331 } EFI_TCG2_FINAL_EVENTS_TABLE;
332 
333 #define EFI_TCG2_FINAL_EVENTS_TABLE_VERSION  1
334 
335 #endif
336