Tbsi_Get_TCG_Log 函数 (tbs.h)

项目
03/16/2023

检索最新的 Windows 启动配置日志 (WBCL) ，也称为 TCG 日志。

语法

TBS_RESULT Tbsi_Get_TCG_Log(
  [in]      TBS_HCONTEXT hContext,
  [out]     PBYTE        pOutputBuf,
  [in, out] PUINT32      pOutputBufLen
);

参数

[in] hContext

正在检索日志的上下文的 TBS 句柄。从对 Tbsi_Context_Create 函数的上一次调用中获取此参数。

[out] pOutputBuf

指向用于接收和存储 WBCL 的缓冲区的指针。当 输入时，当由输出 指向的位置也为 0 时，此参数可能为 NULL 来估计所需的缓冲区。

[in, out] pOutputBufLen

指向无符号长整数的指针，该整数在输入时指定输出缓冲区的大小（以字节为单位）。如果函数成功，则此参数在输出时接收 pOutputBuf 指向的数据的大小（以字节为单位）。如果函数失败，此参数不会接收值。

使用零长度缓冲区调用 Tbsi_Get_TCG_Log 函数将返回所需缓冲区的大小。 Windows Vista SP1 和 Windows Server 2008： 此功能不可用。

返回值

返回代码/值	说明
TBS_SUCCESS 0 (0x0)	函数成功。
TBS_E_INTERNAL_ERROR 2150121473 (0x80284001)	出现内部软件错误。注意如果返回TBS_E_INTERNAL_ERROR，则系统事件日志可能包含 TBS 事件源的事件 ID 16385，错误代码0x80070032。这可能表示硬件平台未向操作系统提供 TCG 事件日志。有时，可以通过安装平台制造商提供的 BIOS 升级来解决此问题。
TBS_E_INVALID_OUTPUT_POINTER 2150121475 (0x80284003)	指定的输出指针无效。
TBS_E_INVALID_CONTEXT 2150121476 (0x80284004)	指定的上下文句柄不引用有效的上下文。
TBS_E_INSUFFICIENT_BUFFER 2150121477 (0x80284005)	输出缓冲区太小。
TBS_E_BUFFER_TOO_LARGE 2150121486 (0x8028400E)	输出缓冲区太大。
TBS_E_TPM_NOT_FOUND 2150121487 (0x8028400F)	在此计算机上找不到兼容的受信任平台模块 (TPM) 安全设备。
TBS_E_DEACTIVATED 2150121494 (0x80284016)	TPM) 安全设备的受信任平台模块 (已停用。 Windows Vista SP1 和 Windows Server 2008：此返回值不可用。

注解

Tbsi_Get_TCG_Log函数返回系统的 TCG 事件日志，缓冲区大小取决于事件数。

Windows 10：

该函数可能会返回使用与不同哈希算法兼容的格式的日志，具体取决于硬件功能和固件设置。此日志将除第一个事件之外的每个事件格式化为TCG_PCR_EVENT2结构：

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;

日志将第一个事件格式化为 TCG_PCR_EVENT 结构，稍后将在此备注部分进行介绍。下表描述了此结构中第一个事件的成员的值。

TCG_PCR_EVENT 成员	值或说明
PCRIndex	0
EventType	EV_NO_ACTION
摘要式	20 字节的零
EventSize	事件成员的大小
事件	具有类型TCG_EfiSpecIdEventStruct

下面显示了 TCG_PCR_EVENT 结构的 Event 成员用于第一个日志事件的 TCG_EfiSpecIdEventStruct 结构的语法。

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;

当日志使用与不同哈希算法兼容的格式时，TCG_EfiSpecIdEventStruct 结构的 Signature 成员设置为以 null 结尾的 ASCII 字符串“Spec ID Event03”。第一个事件中的 DigestSizes 数组包含日志使用的不同哈希算法的摘要大小。当分析程序检查 TCG_PCR_EVENT2类型的事件时，分析程序可以分析 TPML_DIGEST_VALUES 成员，而无需提供有关所有哈希算法的信息。第一个事件中的摘要大小允许分析程序跳过存在的摘要的正确字节数。

如果 Signature 成员未设置为以 null 结尾的 ASCII 字符串“Spec ID Event03”，则日志中的事件的类型 为 TCG_PCR_EVENT，并且 TCG_EfiSpecIdEventStruct 结构不包含 NumberOfAlgorithms 和 DigestSizes 成员。

与不同哈希算法兼容的日志格式允许平台和操作系统使用 SHA1、SHA256 或其他哈希算法。如果平台支持 SHA256 哈希算法，并且使用与不同哈希算法兼容的日志格式，则平台使用 SHA256 算法而不是 SHA1。

Windows Vista SP1 和 Windows Server 2008： 函数直接从 ACPI 表返回日志，并返回整个 ACPI 分配的缓冲区，包括任何事件后未使用的缓冲区。

TCG 事件日志中 Windows 定义的事件是 {Type， Length， Value} 的元组。可以使用 TCG PC 客户端规范中的以下TCG_PCR_EVENT结构分析日志。可以使用 TPM PCP 工具包和 TPM 主规范中的信息在日志事件列表之间创建关联。

typedef struct {
  TCG_PCRINDEX PCRIndex;
  TCG_EVENTTYPE EventType;
  TCG_DIGEST Digest;
  UINT32 EventSize;
  UINT8 Event[EventSize];
} TCG_PCR_EVENT;

pOutputBuf 参数所需的内存大小应为 TBS_IN_OUT_BUF_SIZE_MAX 中的常量（在 Tbs.h 头文件中定义），或者应通过调用长度为零的Tbsi_Get_TCG_Log函数来获取所需的缓冲区大小。

Windows Vista SP1 和 Windows Server 2008： 不支持调用长度为零的缓冲区的 Tbsi_Get_TCG_Log 函数以获取所需的缓冲区大小。建议对 pOutputBuf 参数的内存大小使用 Tbs.h 头文件中定义的常量TBS_IN_OUT_BUF_SIZE_MAX。

示例

#include <windows.h>
#include <tbs.h>
#pragma comment(lib, "Tbs.lib")

void main()
{
    TBS_RESULT result;
    TBS_HCONTEXT hContext;
    TBS_CONTEXT_PARAMS contextParams;
    contextParams.version = TBS_CONTEXT_VERSION_ONE;
    result = Tbsi_Context_Create(&contextParams, &hContext);
    if (result == TBS_SUCCESS) 
    {
        UINT32 iLogSize = TBS_IN_OUT_BUF_SIZE_MAX;
        BYTE* pLogBuffer = new BYTE[iLogSize];
        result = Tbsi_Get_TCG_Log(hContext, pLogBuffer, &iLogSize);
    }
}

要求


最低受支持的客户端	Windows Vista SP1 [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	tbs.h
Library	Tbs.lib
DLL	Tbs.dll

通过

Tbsi_Get_TCG_Log 函数 (tbs.h)

语法

参数

返回值

注解

示例

要求

反馈

反馈

其他资源