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。