keymaster2_device 結構體參考資料

中止以 begin() 開始的加密編譯作業，釋放所有內部資源並使 operation_handle 失效。

定義位於檔案 keymaster2.h 的 415 行。

為 Keymaster 使用的 RNG 新增隨機性。透過這種方法新增的熵值，保證不會是唯一使用的熵值來源，且混合函式必須安全，也就是說，如果 RNG 的種子 (來自任何來源) 是攻擊者無法預測 (或控制) 的任何資料，那麼 RNG 輸出內容就無法與隨機輸出內容區分。因此，如果任何來源的熵值都良好，輸出結果也會良好。

參數

[in]	dev	主控裝置結構。
[in]	資料	要混入的隨機資料。
[in]	data_length	data 的長度。

定義位於檔案 keymaster2.h 的 74 行。

產生已簽署的 X.509 憑證鏈結，證明 Keymaster 中存在 key_to_attest (TODO(swillden)：進一步說明憑證內容)。憑證會包含擴充功能，其中 OID 為 1.3.6.1.4.1.11129.2.1.17，並在 <TODO:swillden – 插入連結> 中定義值，其中包含關鍵說明。

參數

[in]	dev	主控裝置結構。
[in]	key_to_attest	系統將為此金鑰主控項產生認證憑證。
[in]	attest_params	定義如何進行認證的參數。目前唯一的參數是 KM_TAG_ALGORITHM，必須是 KM_ALGORITHM_EC 或 KM_ALGORITHM_RSA。這會選取要用於簽署憑證的已佈建認證金鑰。
[out]	cert_chain	DER 編碼 X.509 憑證的陣列。第一個是 key_to_attest 的憑證。其餘項目會鏈結回根目錄。呼叫端會取得擁有權，且必須使用 keymaster_free_cert_chain 釋放記憶體。

定義位於檔案 keymaster2.h 的 239 行。

使用指定的金鑰開始加密編譯作業。如果一切正常， begin() 會傳回 KM_ERROR_OK，並建立作業句柄，必須傳遞至後續對 update() 、 finish() 或 abort() 的呼叫。

請務必在每次呼叫 begin() 時，搭配後續呼叫 finish() 或 abort() ，以便 Keymaster 實作清除任何內部作業狀態。如果未執行此操作，可能會導致內部狀態空間或其他內部資源外洩，並可能最終導致 begin() 在運算空間用盡時傳回 KM_ERROR_TOO_MANY_OPERATIONS。 begin() 、 update() 或 finish() 傳回的結果若不是 KM_ERROR_OK，就會隱含地中止作業，在這種情況下，就不需要呼叫 abort() (如果呼叫，則會傳回 KM_ERROR_INVALID_OPERATION_HANDLE)。

參數

[in]	dev	主控裝置結構。
[in]	目的	作業用途，可選值為 KM_PURPOSE_ENCRYPT、KM_PURPOSE_DECRYPT、KM_PURPOSE_SIGN 或 KM_PURPOSE_VERIFY。請注意，對於 AEAD 模式，加密和解密分別代表簽署和驗證，但應指定為 KM_PURPOSE_ENCRYPT 和 KM_PURPOSE_DECRYPT。
[in]	鍵	用於該作業的鍵。 key 必須具有與 purpose 相容的用途，且必須符合其所有使用需求，否則 begin() 會傳回適當的錯誤代碼。
[in]	in_params	作業的其他參數。這個屬性通常會搭配 KM_TAG_AUTH_TOKEN 使用，用於提供驗證資料。如果在產生期間提供 KM_TAG_APPLICATION_ID 或 KM_TAG_APPLICATION_DATA，則必須在此提供，否則作業會失敗，並顯示 KM_ERROR_INVALID_KEY_BLOB。對於需要 Nonce 或 IV 的作業，如果金鑰是使用 KM_TAG_CALLER_NONCE 產生的，in_params 可能會包含標記 KM_TAG_NONCE。
[out]	out_params	輸出參數。用於從作業初始化傳回其他資料，特別是從產生 IV 或 Nonce 的作業中傳回 IV 或 Nonce。呼叫端會取得輸出參數陣列的擁有權，且必須使用 keymaster_free_param_set() 釋出該陣列。如果沒有預期的輸出參數，則可以將 out_params 設為 NULL。如果 out_params 為 NULL，且產生輸出參數， begin() 會傳回 KM_ERROR_OUTPUT_PARAMETER_NULL。
[out]	operation_handle	新建立的作業句柄，必須傳遞至 update() 、 finish() 或 abort() 。如果 operation_handle 為空值， begin() 會傳回 KM_ERROR_OUTPUT_PARAMETER_NULL。

定義位於檔案 keymaster2.h 的第 332 行。

主控裝置的常用方法。這個 必須是 keymaster_device 的第一個成員，因為這個結構體的使用者會在已知 hw_device_t 參照 keymaster_device 的情況下，將 hw_device_t 轉換為 keymaster_device 指標。

定義位於檔案 keymaster2.h 的 35 行。

設定 Keymaster。這個方法必須在裝置開啟後，且在使用前呼叫一次。這個值可用於將 KM_TAG_OS_VERSION 和 KM_TAG_OS_PATCHLEVEL 提供給 Keymaster。在這個方法呼叫之前，所有其他方法都會傳回 KM_ERROR_KEYMASTER_NOT_CONFIGURED。這個方法提供的值，每次開機時只會由 Keymaster 接受一次。後續呼叫會傳回 KM_ERROR_OK，但不會執行任何動作。

如果金鑰管理員實作項目位於安全硬體中，且提供的 OS 版本和修補程式級別值與引導程式提供給安全硬體的值不符 (或引導程式未提供值)，則這個方法會傳回 KM_ERROR_INVALID_ARGUMENT，而所有其他方法會繼續傳回 KM_ERROR_KEYMASTER_NOT_CONFIGURED。

定義位於檔案 keymaster2.h 的 58 行。

定義位於檔案 keymaster2.h 的 37 行。

刪除硬體 KeyStore 中的所有金鑰。當 KeyStore 已完全重設時使用。在呼叫這個函式後，就無法將先前產生或匯入的任何金鑰 Blob 用於任何作業。

這個函式為選用，如果未實作，應設為 NULL。

參數

[in]

dev

主控裝置結構。

定義位於檔案 keymaster2.h 的 288 行。

刪除與金鑰 blob 相關聯的金鑰或金鑰組。呼叫此函式後，就無法將金鑰用於任何其他作業。可套用至來自外部信任根的金鑰 (在目前信任根下無法使用的金鑰)。

這個函式為選用，如果未實作，應設為 NULL。

參數

[in]	dev	主控裝置結構。
[in]	鍵	要刪除的鍵。

定義位於檔案 keymaster2.h 的 276 行。

匯出公開或對稱金鑰，以指定格式傳回位元組陣列。

請注意，只有在使用 KM_TAG_EXPORTABLE 建立金鑰，且符合所有金鑰用途需求 (例如驗證) 時，系統才會允許匯出對稱式金鑰。

參數

[in]	dev	主控裝置結構。
[in]	export_format	用於匯出金鑰的格式。
[in]	key_to_export	要匯出的金鑰。
[in]	client_id	用戶端 ID 資料 blob，必須與金鑰產生期間在 KM_TAG_APPLICATION_ID 中提供的資料 blob (如果有的話) 相符。
[in]	app_data	應用程式資料資料 blob，必須與金鑰產生期間在 KM_TAG_APPLICATION_DATA 中提供的資料 blob (如有) 相符。
[out]	export_data	匯出的金鑰內容。呼叫端會假設擁有權。

定義位於檔案 keymaster2.h 的 213 行。

以 begin() 開始的加密編譯作業會在此完成，並使 operation_handle 失效。

參數

[in]	dev	主控裝置結構。
[in]	operation_handle	begin() 傳回的作業句柄。這個句柄將失效。
[in]	in_params	作業的其他參數。針對 AEAD 模式，這會用於指定 KM_TAG_ADDITIONAL_DATA，但只有在 update() 未提供任何輸入資料時才會使用。
[in]	輸入	根據呼叫 begin() 時建立的參數，所要處理的資料。 finish() 必須使用所有提供的資料，否則會傳回 KM_ERROR_INVALID_INPUT_LENGTH。
[in]	簽名	如果 begin() 呼叫中指定的用途為 KM_PURPOSE_VERIFY，則為要驗證的簽章。
[out]	輸出	輸出資料 (如果有的話)。呼叫端會假設已取得已配置緩衝區的擁有權。

如果完成的作業是簽名驗證或 AEAD 模式解密，且驗證失敗，則 finish() 會傳回 KM_ERROR_VERIFICATION_FAILED。

定義位於檔案 keymaster2.h 的 405 行。

請參閱 keymaster_common.h 中為 keymaster0_devices::flags 定義的標記。僅用於回溯相容性；keymaster2 硬體裝置必須將此值設為零。

定義位於檔案 keymaster2.h 的 43 行。

產生金鑰或金鑰組，並傳回金鑰 blob 和/或金鑰說明。

鍵產生參數會定義為 Keymaster 標記/值組合，並提供在 params 中。如需完整清單，請參閱 keymaster_tag_t。以下是產生實用鍵時一律需要的值：

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; 和
• (KM_TAG_USER_SECURE_ID 和 KM_TAG_USER_AUTH_TYPE) 或 KM_TAG_NO_AUTH_REQUIRED。

除非使用 KM_TAG_NO_AUTH_REQUIRED，否則通常應指定 KM_TAG_AUTH_TIMEOUT，否則使用者每次使用都必須進行驗證。

對於需要這些值的演算法，必須指定 KM_TAG_BLOCK_MODE、KM_TAG_PADDING、KM_TAG_MAC_LENGTH 和 KM_TAG_DIGEST。

下列標記不必指定，其值會由實作提供。

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

參數

[in]	dev	主控裝置結構。
[in]	params	金鑰產生參數的陣列
[out]	key_blob	傳回產生的金鑰。 key_blob 不得為空值。呼叫端會假設擁有權 key_blob->key_material，且必須 free() 該權限。
[out]	特性	傳回產生的鍵的特性 (如果非空值)。如果非空值，則呼叫端會假設擁有權，並必須使用 keymaster_free_characteristics() 釋出。請注意，系統不會傳回 KM_TAG_ROOT_OF_TRUST、KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA。

定義位於檔案 keymaster2.h 的 112 行。

傳回指定金鑰的特性，如果 key_blob 無效，則會傳回 KM_ERROR_INVALID_KEY_BLOB (實作必須完全驗證金鑰的完整性)。client_id 和 app_data 必須是產生或匯入金鑰時提供的 ID 和資料，如果產生時未提供 KM_TAG_APPLICATION_ID 和/或 KM_TAG_APPLICATION_DATA，則會傳回空白。這些值不會包含在傳回的特性中。呼叫端會假設已分配特徵物件擁有權，而該物件必須使用 keymaster_free_characteristics() 取消分配。

請注意，系統不會傳回 KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA。

參數

[in]	dev	主控裝置結構。
[in]	key_blob	要擷取特徵值的鍵。
[in]	client_id	用戶端 ID 資料，如果沒有相關聯的資料，則傳回空值。
[in]	app_id	應用程式資料，如果沒有關聯則為 NULL。
[out]	特性	主要特徵。不得為空值。呼叫端會取得內容的擁有權，且必須使用 keymaster_free_characteristics() 解除分配。

定義位於檔案 keymaster2.h 的 139 行。

匯入金鑰或金鑰組，並傳回金鑰 blob 和/或金鑰說明。

大部分的關鍵匯入參數都定義為「params」中提供的 Keymaster 標記/值組合。如需完整清單，請參閱 keymaster_tag_t。匯入實用鍵時，必須一律提供的值如下：

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; 和
• (KM_TAG_USER_SECURE_ID 和 KM_TAG_USER_AUTH_TYPE) 或 KM_TAG_NO_AUTH_REQUIRED。

通常應指定 KM_TAG_AUTH_TIMEOUT。如未指定，使用者每次使用都必須進行驗證。

如未指定，下列標記會採用預設值：

• KM_TAG_KEY_SIZE 預設為提供的金鑰大小。
• KM_TAG_RSA_PUBLIC_EXPONENT 的預設值為提供的金鑰值 (RSA 金鑰)

下列標記不必指定，其值會由實作提供。

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

參數

[in]	dev	主控裝置結構。
[in]	params	定義匯入金鑰的參數。
[in]	params_count	params 中的項目數量。
[in]	key_format	指定 key_data 中的鍵資料格式。
[out]	key_blob	用於傳回不透明金鑰 blob。不得為空值。呼叫端會假設所含 key_material 的擁有權。
[out]	特性	用於傳回匯入鍵的特性。可能為 NULL，在這種情況下，系統不會傳回任何特徵。如果非空值，則呼叫端會假設內容擁有權，並必須使用 keymaster_free_characteristics() 釋出。請注意，系統不會傳回 KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA。

定義位於檔案 keymaster2.h 的第 186 行。

為以 begin() 開始的持續性加密作業提供資料，並可能接收該作業的輸出內容。

如果 operation_handle 無效， update() 會傳回 KM_ERROR_INVALID_OPERATION_HANDLE。

update() 可能不會使用資料緩衝區提供的所有資料。 update() 會傳回 *data_consumed 中消耗的金額。呼叫端應在後續呼叫中提供未使用的資料。

參數

[in]	dev	主控裝置結構。
[in]	operation_handle	begin() 傳回的作業句柄。
[in]	in_params	作業的其他參數。針對 AEAD 模式，這會用於指定 KM_TAG_ADDITIONAL_DATA。請注意，您必須先提供輸入資料，才能在多次呼叫 update() 時提供其他資料。
[in]	輸入	根據呼叫 begin() 時建立的參數，所要處理的資料。請注意， update() 可能會或不會使用所有提供的資料。請參閱 input_consumed 。
[out]	input_consumed	update() 所耗用的資料量。如果此值小於提供的金額，呼叫端應在後續呼叫 update() 時提供其餘額。
[out]	out_params	輸出參數。用於從作業中傳回其他資料。呼叫端會取得輸出參數陣列的擁有權，並必須使用 keymaster_free_param_set() 釋放該陣列。如果沒有預期的輸出參數，則可以將 out_params 設為 NULL。如果 out_params 為 NULL，且產生輸出參數， begin() 會傳回 KM_ERROR_OUTPUT_PARAMETER_NULL。
[out]	輸出	輸出資料 (如果有的話)。呼叫端會假設已配置緩衝區的擁有權。輸出內容不得為空值。

請注意， update() 可能不會提供任何輸出內容，在這種情況下，output->data_length 會為零，而 output->data 可能為空值或零長度 (因此呼叫端應一律應 free() 這項資料)。

定義位於檔案 keymaster2.h 的 376 行。

升級舊金鑰。密鑰可能會因兩種情況而變得「過舊」：Keymaster 可能會升級至新版本，或是系統可能會更新，導致 OS 版本和/或修補程式級別失效。無論是哪種情況，嘗試使用舊金鑰都會導致 Keymaster 傳回 KM_ERROR_KEY_REQUIRES_UPGRADE。接著，應呼叫此方法來升級金鑰。

參數

[in]	dev	主控裝置結構。
[in]	key_to_upgrade	要升級的 Keymaster 金鑰。
[in]	upgrade_params	完成升級所需的參數。具體來說，如果為金鑰定義了 KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA，就必須使用這兩個值。
[out]	upgraded_key	已升級的金鑰 blob。

定義位於檔案 keymaster2.h 的 260 行。