TPM 程序设计基础 1-2-4 ：新的 PCR 命令

New PCR commands

新的 PCR 命令

• 注意：本文只提供相关函数的说明、定义、参数、返回值、注释等的简单翻译，对于更多信息、疑问或错误之处，请阅读原英文文档。

Tspi_TPM_PcrReset

重置PCR寄存器。

《TSS V1.2.pdf》 P298 4.3.4.15.1 Tspi_TPM_PcrReset

信息说明开始
该方法重置PCR寄存器。它是否成功取决于执行命令的位置。可以在平台特定的规范中定义PCRs，以便仅在特定的位置上允许重置某些PCRs。唯一的例外是PCR 16，它总是可以在1.2实现中重置。(这是为了软件测试)。
信息说明结束

定义
	TSS_RESULT Tspi_TPM_PcrReset 
	(
        TSS_HTPM hTPM, // in 
        TSS_HPCRS hPcrComposite // in 
	);

参数
	hTPM
		TPM对象的句柄
	hPcrComposite
		指定要重置的PCR组合对象实例的PCR句柄;这必须是一个TCPA_PCR_INFO结构。

返回值
	TSS_SUCCESS
	TSS_E_INVALID_HANDLE
	TSS_TPM_NOT_RESETABLE
	TSS_E_WRONG_LOCALITY
	TSS_E_INTERNAL_ERROR

注释

Tspi_Data_Seal

《TSS V1.2.pdf》 P299 4.3.4.15.2 Tspi_Data_Seal

信息说明开始
此方法在1.2 TSS堆栈上执行时是一个“重载”函数。
该方法以一种只有在同一系统上通过Tspi_Data_Unseal才能解密的方式对数据blob进行加密。数据blob使用公钥操作进行加密，公钥操作使用由给定的加密密钥对象寻址的不可移动密钥。
此外，Tspi_Data_Seal操作允许软件显式地声明平台必须处于的未来“受信任的”配置，以便公开加密的数据，并在执行Tspi_Data_Seal操作时显式地包含相关平台配置寄存器(PCR)值的列表。
当用作1.1函数时，在PCR_Object中选择一个PCR寄存器子集，这些寄存器都被记录下来，并用于匹配系统发布时的状态。
从1.2规范开始,PCR对象传递给这个函数可以包含一个地方还有两套PCR发布,一旦识别子集的PCR在密封被记录,和其他指定一个子集(可能不同)的PCR和它们的值必须匹配为了执行开启。
如果Tspi_Data_Unseal操作成功，则会向调用者返回在执行Tspi_Data_Seal操作时生效的平台配置的证据，以及秘密数据。这个证明可能有趣，也可能不有趣。
如果使用密封的秘密向第三方验证平台，则调用方通常不关心密封的秘密时平台的状态，其验证可能没有任何意义。
另一方面，如果使用密封的秘密对平台的第三方进行身份验证，则调用者通常会关心密封秘密时平台的状态。那么证明是有趣的。
例如,如果密封用于存储密钥为未来配置平台(可能证明是一个特定的平台,是在一个特定的配置),唯一的要求就是,关键时,才可以使用平台是未来的配置。
那么，当秘密密钥被密封时，就没有兴趣进行平台配置了。这种情况的一个例子是使用SEAL存储网络身份验证密钥。
另一方面，假设一个操作系统包含一个允许登录到平台的用户的加密数据库。操作系统使用一个密封的blob来存储用户数据库的加密密钥。然而，SEAL的本质是任何SW堆栈都可以为任何其他软件堆栈封装一个blob。
因此，操作系统可能会受到另一个操作系统的攻击，该操作系统既替换了被密封的blob加密密钥，也替换了用户数据库本身，从而允许不受信任的方访问操作系统的服务。
为了阻止这种攻击，密封的气泡包括过去的SW配置。因此，如果操作系统关心这样的攻击，它可能会检查过去的配置是否被认为是可信的。
要密封大于RSA公钥模数的数据，调用者的责任是执行数据的阻塞和随后的组合。
需要注意的是，当TCPA_PCR_INFO或TCPA_PCR_INFO_LONG结构与1.1或1.2命令一起使用时，会产生什么效果。
例如，在1.1中，如果使用命令Tspi_PcrComposite_SelectPcrIndex和Tspi_PcrComposite_SetPcrValue。
然后，当与SEAL命令一起使用时，最终创建的TCPA_PCR_INFO结构将选择一些值，这些值将在创建时记录，并检查如果最终生成了TCPA_PCR_INFO_LONG，那么在1.2中也必须发生相同的事情。新定义的函数Tspi_PcrComposite_SelectPcrIndexX是一个更好的函数，可以在使用1.2功能时选择不同的值来记录创建和检查发布。 由PcrIndex筛选的发布值。
如何在TSS内部完成这一任务则留给了开发人员。如果他们想要始终保持1.2的结构，然后在使用之前尽可能将结构压缩到1.1，他们可以这样做。如果他们想携带两个版本，他们可以这样做。如果他们想做一些完全不同的事情，他们也可以这样做。
信息说明结束

定义
	TSS_RESULT Tspi_Data_Seal 
	( 
        TSS_HENCDATA hEncData, // in 
        TSS_HKEY hEncKey, // in 
        UINT32 ulDataLength, // in 
        BYTE* rgbDataToSeal, // in 
        TSS_HPCRS hPcrComposite // in 
	);

参数
	hEncData
    	数据对象的句柄，其中包含成功完成命令时密封的数据。
    hEncKey
    	密钥对象的句柄，处理用于加密数据的不可移动密钥。
    ulDataLength
    	rgbDataToSeal参数的长度(以字节为单位)。
    rgbDataToSeal
    	指向包含要加密的数据的内存的指针。
	hPcrComposite
        复合PCR对象的句柄，它可以包含TCPA_PCR_INFO或TCPA_PCR_INFO_LONG。
        TCPA_PCR_INFO将只包含一个PCRs子集和值，必须在打开时进行匹配。TCPA_PCR_INFO_LONG包含两个PCRs子集，一个标识要记录在密封blob中的PCRs，另一个标识必须在未密封时匹配的PCRs——以及它们必须匹配的值。 
        此外，TCPA_PCR_INFO_LONG对象可以指定必须匹配的位置来打开数据。设置为NULL，如果加密的数据应该只绑定到系统和不感兴趣的pcr。
       
返回值
	TSS_SUCCESS 
	TSS_E_INVALID_HANDLE 
	TSS_E_BAD_PARAMETER 
	TSS_E_ENC_INVALID_LENGTH 
	TSS_E_ENC_NO_DATA 
	TSS_E_ENC_INVALID_TYPE 
	TSS_E_INTERNAL_ERROR

注释
密封的数据blob存储在由hEncData寻址的数据对象中，可以通过GetAttribData()从该对象导出。调用者根据TCG的规则获取这个导出的加密数据blob。
在调用该方法之前，必须在由hPcrComposite处理的PCR复合对象中设置关于所使用的PCR的信息。hPcrComposite可以使用TCPA_PCR_INFO(1.1格式)或TCPA_PCR_INFO_LONG(1.2格式)。如果不需要PCR值，则hPcrComposite必须设置为NULL。
Tspi_Data_Seal maximum data input size* s = key size (bytes)
| TSS_KEY_TYPE_STORAGE | s-(40-2)-65 |

Tspi_TPM_Quote2

《TSS V1.2.pdf》 P302 4.3.4.15.3 Tspi_TPM_Quote2

信息说明开始
该方法使用TPM_Quote2引用TCG系统，TPM_Quote2为请求者提供了比TPM_Quote更完整的当前平台配置视图。
信息说明结束

定义
	TSS_RESULT Tspi_TPM_Quote2 
	( 
        TSS_HTPM hTPM, // in 
        TSS_HKEY hIdentKey, // in 
        TSS_BOOL fAddVersion, // in 
        TSS_HPCRS* hPcrComposite, // in 
        TSS_VALIDATION* pValidationData,// in, out 
        UINT32* versionInfoSize,//out 
        BYTE** versionInfo // out
	}

参数
	hTPM
    	TPM对象的句柄
    hIdentKey
    	签名密钥对象的句柄
    fAddVersion
    	如果为真，则将TPM版本添加到输出中。
    	如果为假，则不会将TPM版本添加到输出中。
    hPcrComposite
    	PCR复合物的句柄;结构类型必须是TSS_PCRS_STRUCT_INFO_SHORT。
    	[IN]选定的pcr中引用。
    pValidationData
    	验证数据结构
    	[IN]提供计算签名所需的外部数据信息。
    	[OUT]成功完成该命令后，该结构将提供一个包含验证数据的缓冲区和一个包含验证数据的缓冲区。
    	这与Tspi_TPM_Quote的不同之处在于，数据包含TCPA_PCR_INFO_SHORT，而不是TCPA_PCR_COMPOSITE，并且版本信息以TPM_QUOTE_INFO2而不是TPM_QUOTE_INFO返回
    versionInfoSize
    	versionInfo返回的字节流的大小。如果fAddVersion为假，则为0。
	versionInfo
		如果fAddVersion为真，则以字节流形式返回的版本信息反映TSS_CAP_VERSION_INFO中的数据。否则为空。
		
返回值
	TSS_SUCCESS 
	TSS_E_INVALID_HANDLE 
	TSS_E_BAD_PARAMETER 
	TSS_E_INTERNAL_ERROR

注释
在调用这个方法之前，必须在PCR_Composite对象中设置关于应该引用哪些pcr的所需信息。在返回时，验证数据包含关于集合如何具有其位置和PCR摘要集的信息。
如果在hPcrComposite对象中使用的结构类型不是TSS_PCRS_STRUCT_INFO_SHORT，那么将返回错误TSS_E_INVALID_OBJ_ACCESS。
返回的签名通过TCPA_QUOTE_INFO2结构与单独返回的TPM-CAP_VERSION_INFO结构进行计算。
Tspi_TPM_Quote2方法为请求的验证数据分配内存块。必须使用Tspi_Context_FreeMemory方法释放该内存。

Tspi_PcrComposite_SetPcrLocality

《TSS V1.2.pdf》 P304 4.3.4.15.4 Tspi_PcrComposite_SetPcrLocality

信息说明开始
该方法使用1.2 TCPA_PCR_INFO_LONG或TCPA_PCR_INFO_SHORT结构在PCR复合对象中设置LocalityAtRelease。
信息说明结束

定义
	TSS_RESULT Tspi_PcrComposite_SetPcrLocality 
	( 
        TSS_HPCRS hPcrComposite, //in 
        UINT32 LocalityValue //in 
	);

参数
	hPcrComposite
    	处理PCR复合对象实例，其中应该设置局部值。
    LocalityValue
    	要设置的LocalityAtRelease值

返回值
	TSS_SUCCESS 
	TSS_E_INVALID_HANDLE 
	TSS_E_INVALID_OBJ_ACCESS 
	TSS_E_BAD_PARAMETER 
	TSS_E_INTERNAL_ERROR

注释
如果PcrComposite对象使用1.1 TCPA_PCR_INFO结构，则该函数将返回TSS_E_INVALID_OBJ_ACCESS。

Tspi_PcrComposite_GetPcrLocality

《TSS V1.2.pdf》 P305 4.3.4.15.5 Tspi_PcrComposite_GetPcrLocality

信息说明开始
该方法使用1.2 TCPA_PCR_INFO_LONG结构或1.2 TCPA_PCR_INFO_SHORT结构从PCR复合对象中获取LocalityAtRelease。
信息说明结束

定义
	TSS_RESULT Tspi_PcrComposite_GetPcrLocality 
	( 
        TSS_HPCRS hPcrComposite, //in 
        UINT32* pLocalityValue //out 
	);

参数
	hPcrComposite
    	处理PCR复合对象实例，从该实例返回局部值
    pLocalityValue
    	接收请求的位置值

返回值
	TSS_SUCCESS 
	TSS_E_INVALID_HANDLE 
	TSS_E_INVALID_OBJ_ACCESS 
	TSS_E_BAD_PARAMETER 
	TSS_E_INTERNAL_ERROR

注释
如果PcrComposite对象使用1.1 TCPA_PCR_INFO结构，则该函数将返回TSS_E_INVALID_OBJ_ACCESS。

Tspi_PcrComposite_GetCompositeHash

《TSS V1.2.pdf》 P306 4.3.4.15.6 Tspi_PcrComposite_GetCompositeHash

信息说明开始
该方法使用1.2 TCPA_PCR_INFO_LONG结构或1.2 TCPA_PCR_INFO_SHORT结构从PCR复合对象中获取digestAtRelease。
信息说明结束

定义
	TSS_RESULT Tspi_PcrComposite_GetCompositeHash 
	( 
        TSS_HPCRS hPcrComposite,//in 
        UINT32* pLen, //out 
        BYTE** ppbHashData //out 
	);

参数
	hPcrComposite
    	复合对象实例的句柄，应该从该对象实例返回复合散列摘要
    pLen
    	接收ppbHashData参数的长度(以字节为单位)
    ppbHashData
    	创建时摘要或发布时摘要

返回值
	TSS_SUCCESS 
	TSS_E_INVALID_HANDLE 
	TSS_E_INVALID_OBJ_ACCESS 
	TSS_E_BAD_PARAMETER 
	TSS_E_INTERNAL_ERROR

注释
如果PcrComposite对象使用1.1 TCPA_PCR_INFO结构，则该函数将返回TSS_E_INVALID_OBJ_ACCESS。
Tspi_PcrComposite_GetCompositeHash方法为ppbHashData数据分配一个内存块。必须使用Tspi_Context_FreeMemory方法释放该内存。

Tspi_PcrComposite_SelectPcrIndexEx

PCR复合对象中选择PCR指数。

《TSS V1.2.pdf》 P307 4.3.4.15.7 Tspi_PcrComposite_SelectPcrIndexEx

信息说明开始
该方法在一个包含TCPA_PCR_INFO_LONG或TCPA_PCR_INFO_SHORT结构的PCR复合对象中选择PCR指数。对于TCPA_PCR_INFO_LONG结构,可以选择索引来创建或发布索引;对于TCPA_PCR_INFO_SHORT,可以选择该索引来发布。必须用函数Tspi_Context_CreateObject()来创建PCR组合对象。使用的一个例子是在调用tpm_quote2()之前选择PCR寄存器。
信息说明结束

定义
	TSS_RESULT Tspi_PcrComposite_SelectPcrIndexEx 
	(
        TSS_HPCRS hPcrComposite, //in 
        UINT32 ulPcrIndex, //in 
        UINT32 Direction //in 
	);

参数
	hPcrComposite
		处理PCR复合对象实例，其中应该设置PCR值。
	ulPcrIndex
		指示PCR指标选择的参数
	Direction 
		选择所选的索引是用于创建时的PCR还是用于释放时的PCR

返回值
	TSS_SUCCESS
	TSS_E_INVALID_HANDLE
	TSS_E_BAD_PARAMETER
	TSS_E_INTERNAL_ERROR

注释
如果PcrComposite对象使用1.1 TCPA_PCR_INFO结构，则该函数将返回TSS_E_INVALID_OBJ_ACCESS。
如果PcrComposite对象使用1.2 TCPA_PCR_INFO_SHORT结构，并且选择用于创建，则此函数将返回TSS_E_INVALID_OBJ_ACCESS。