Tbsi_Get_TCG_Log_Ex function (tbs.h)
Gets the Windows Boot Configuration Log (WBCL), also referred to as the TCG log, of the specified type.
Syntax
TBS_RESULT Tbsi_Get_TCG_Log_Ex(
[in] UINT32 logType,
[out, optional] PBYTE pbOutput,
[in, out] PUINT32 pcbOutput
);
Parameters
[in] logType
The type of log to retrieve.
[out, optional] pbOutput
Pointer to a buffer that receives and stores the WBCL. Set to NULL to estimate the required buffer when the location pointed to by pcbOutput is also 0 on input.
[in, out] pcbOutput
Pointer to an unsigned long integer that specifies the size, in bytes, of the output buffer. On success, contains the size, in bytes, of the data pointed to by pOutput. On failure, does not contain a value.
Note If pbOutput is NULL and the location pointed to by pcbOutput is 0, the function returns TBS_E_BUFFER_TOO_SMALL. In that case, pcbOutput will point to the required size of pbOutput.
Return value
| Return code/value | Description |
|---|---|
|
The function succeeded. |
|
TBS_TCGLOG_DRTM_CURRENT was requested but DRTM was not enabled on the system when the system booted. |
|
An internal software error occurred.
Note If TBS_E_INTERNAL_ERROR is returned, the system event log may contain event ID 16385 from the TBS event source with error code 0x80070032. This may indicate that the hardware platform does not provide a TCG event log to the operating system. Sometimes this can be resolved by installing a BIOS upgrade from the platform manufacturer.
|
|
A specified output pointer is not valid. |
|
The output buffer is too small. |
|
The output buffer is too large. |
|
A compatible Trusted Platform Module (TPM) Security Device cannot be found on this computer. |
|
The Trusted Platform Module (TPM) Security Device is deactivated. |
Remarks
The Tbsi_Get_TCG_Log_Ex function returns the TCG Event Log for the system, and the buffer size depends on the number of events.
The function may return a log that uses a format that is compatible with different hashing algorithms, depending on hardware capabilities and firmware settings. This log formats each event except the first as a TCG_PCR_EVENT2 structure:
typedef struct {
TCG_PCRINDEX PCRIndex;
TCG_EVENTTYPE EventType;
TPML_DIGEST_VALUES Digests;
UINT32 EventSize;
UINT8 Event[EventSize];
} TCG_PCR_EVENT2;
typedef struct {
UINT32 Count;
TPMT_HA Digests;
} TPML_DIGEST_VALUES;
typedef struct {
UINT16 HashAlg;
UINT8 Digest[size_varies_with_algorithm];
} TPMT_HA;
The log formats the first event as a TCG_PCR_EVENT structure, which is described later in this Remarks section. The following table describes the values of the members of this structure for this first event.
| TCG_PCR_EVENT member | Value or description |
|---|---|
| PCRIndex | 0 |
| EventType | EV_NO_ACTION |
| Digest | 20 bytes of zeros |
| EventSize | The size of the Event member |
| Event | Has a type of TCG_EfiSpecIdEventStruct |
The following shows the syntax of the TCG_EfiSpecIdEventStruct structure that the Event member of the TCG_PCR_EVENT structure uses for the first log event.
typedef struct {
BYTE[16] Signature;
UINT32 PlatformClass;
UINT8 SpecVersionMinor;
UINT8 SpecVersionMajor;
UINT8 SpecErrata;
UINT8 UintNSize;
UINT32 NumberOfAlgorithms;
TCG_EfiSpecIdEventAlgorithmSize DigestSizes[NumberOfAlgorithms];
UINT8 VendorInfoSize;
UINT8 VendorInfo[VendorInfoSize];
} TCG_EfiSpecIdEventStruct;
typedef struct {
UINT16 HashAlg;
UINT16 DigestSize;
} TCG_EfiSpecIdEventAlgorithmSize;
The Signature member of the TCG_EfiSpecIdEventStruct structure is set to a null-terminated ASCII string of "Spec ID Event03" when the log uses the format that is compatible with different hashing algorithms. The DigestSizes array in this first event contains the digest sizes for the different hashing algorithms that the log uses. When a parser inspects an event of type TCG_PCR_EVENT2, the parser can parse the TPML_DIGEST_VALUES member without information about all of the hashing algorithms present. The digest sizes in the first event allow the parser to skip the correct number of bytes for the digests that are present.
If the Signature member is not set to a null-terminated ASCII string of "Spec ID Event03", then the events in the log are of type TCG_PCR_EVENT, and the TCG_EfiSpecIdEventStruct structure does not contain the NumberOfAlgorithms and DigestSizes members.
The log format that is compatible with different hashing algorithms allows the platform and operating system to use SHA1, SHA256, or other hashing algorithms. If the platform supports the SHA256 hashing algorithm and the uses the log format that is compatible with different hashing algorithms, the platform uses the SHA256 algorithm instead of SHA1.
The Windows-defined events in the TCG event log are a tuple of {Type, Length, Value}. You can parse the log using the following TCG_PCR_EVENT structure from the TCG PC Client spec. You can create a correlation between lists of log events using the information in the TPM PCP Toolkit and the TPM Main Specification.
typedef struct {
TCG_PCRINDEX PCRIndex;
TCG_EVENTTYPE EventType;
TCG_DIGEST Digest;
UINT32 EventSize;
UINT8 Event[EventSize];
} TCG_PCR_EVENT;
The memory size required for the pOutputBuf parameter should either be the constant in TBS_IN_OUT_BUF_SIZE_MAX, defined in the Tbs.h header file, or it should be obtained by calling the Tbsi_Get_TCG_Log_Ex function with a zero length buffer to get the required buffer size.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 10, version 1803 [desktop apps only] |
| Minimum supported server | Windows Server [desktop apps only] |
| Target Platform | Windows |
| Header | tbs.h |
| Library | Tbs.lib |
| DLL | Tbs.dll |