keymaster2_device 結構參考
#include < keymaster2.h >
詳細說明
Keymaster2 裝置定義
定義位於檔案keymaster2.h第28行。
現場文檔
| keymaster_error_t (* abort)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle) |
中止以begin()開始的加密操作，釋放所有內部資源並使operation_handle無效。
檔案keymaster2.h第415行的定義。
| keymaster_error_t (* add_rng_entropy)(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length) |
將熵加入 keymaster 使用的 RNG。透過此方法添加的熵保證不是所使用的熵的唯一來源，並且混合函數需要是安全的，從某種意義上說，如果 RNG（來自任何來源）使用攻擊者無法預測（或控制），則RNG輸出與隨機輸出無法區分。因此，如果任何來源的熵良好，則輸出也會良好。
- 參數
[在] 開發者 密鑰主設備結構。 [在] 數據 要混合的隨機資料。 [在] 資料長度 data長度。
檔案keymaster2.h第74行的定義。
| keymaster_error_t (* attest_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain) |
產生簽署的 X.509 憑證鏈，證明 keymaster 中存在key_to_attest （TODO(swillden)：更詳細地描述憑證內容）。此憑證將包含 OID 1.3.6.1.4.1.11129.2.1.17 的擴充功能以及 <TODO:swillden – 在此處插入連結> 中定義的值，其中包含金鑰描述。
- 參數
[在] 開發者 密鑰主設備結構。 [在] 證明密鑰 將為其產生證明證書的密鑰主密鑰。 [在] 證明參數 定義如何進行證明的參數。目前唯一的參數是 KM_TAG_ALGORITHM，它必須是 KM_ALGORITHM_EC 或 KM_ALGORITHM_RSA。這選擇將使用哪個預先配置的證明金鑰來簽署憑證。 [出去] 憑證鏈 一組 DER 編碼的 X.509 證書。第一個是 key_to_attest的憑證。其餘條目將連結回根。呼叫者取得所有權並且必須使用 keymaster_free_cert_chain 取消分配。
定義位於檔案keymaster2.h的第239行。
| keymaster_error_t (* 開始)(const struct keymaster2_device *dev, keymaster_ Purpose_t目的, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_key_param_set_t *in_params, keymaster_key_param_set_t . |
使用指定密鑰開始加密操作。如果一切順利， 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 ）。
- 參數
[在] 開發者 密鑰主設備結構。 [在] 目的 操作的目的，KM_PURPOSE_ENCRYPT、KM_PURPOSE_DECRYPT、KM_PURPOSE_SIGN 或 KM_PURPOSE_VERIFY 之一。請注意，對於 AEAD 模式，加密和解密分別意味著簽章和驗證，但應指定為 KM_PURPOSE_ENCRYPT 和 KM_PURPOSE_DECRYPT。 [在] 鑰匙 用於操作的密鑰。 key必須具有與purpose相容的用途，並且必須滿足其所有使用要求，否則begin()將傳回適當的錯誤代碼。[在] 輸入參數 操作的附加參數。這通常用於透過 KM_TAG_AUTH_TOKEN 提供身份驗證資料。如果在生成期間提供了 KM_TAG_APPLICATION_ID 或 KM_TAG_APPLICATION_DATA，則必須在此處提供它們，否則操作將失敗並顯示 KM_ERROR_INVALID_KEY_BLOB。對於需要隨機數或 IV 的操作，在使用 KM_TAG_CALLER_NONCE 產生的金鑰上，in_params 可能包含標籤 KM_TAG_NONCE。 [出去] 輸出參數 輸出參數。用於從操作初始化返回附加數據，特別是從生成 IV 或隨機數的操作返回 IV 或隨機數。呼叫者擁有輸出參數陣列的所有權，並且必須使用keymaster_free_param_set()釋放它。如果不需要輸出參數，out_params 可以設定為 NULL。如果 out_params 為 NULL，且產生了輸出參數，則begin()將傳回 KM_ERROR_OUTPUT_PARAMETER_NULL。 [出去] 操作句柄 新建立的操作句柄必須傳遞給update() 、 finish()或abort() 。如果操作句柄為 NULL，則begin()將傳回 KM_ERROR_OUTPUT_PARAMETER_NULL。
檔案keymaster2.h第332行的定義。
| 結構體hw_device_t公共 |
Keymaster設備的常用方法。這必須是 keymaster_device 的第一個成員，因為該結構的使用者將在已知hw_device_t引用 keymaster_device的上下文中將 hw_device_t 強制轉換為 keymaster_device 指標。
定義位於檔案keymaster2.h第35行。
| keymaster_error_t (* 設定)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params) |
配置密鑰管理器。此方法必須在設備開啟後和使用前呼叫一次。它用於向金鑰管理員提供 KM_TAG_OS_VERSION 和 KM_TAG_OS_PATCHLEVEL。在呼叫該方法之前，所有其他方法都會傳回 KM_ERROR_KEYMASTER_NOT_CONFIGURED。此方法提供的值每次啟動時僅被 keymaster 接受一次。後續呼叫將傳回 KM_ERROR_OK，但不執行任何操作。
如果 keymaster 實作位於安全硬體中，且提供的作業系統版本和修補程式等級值與引導程式提供給安全硬體的值不相符（或引導程式未提供值），則此方法將傳回 KM_ERROR_INVALID_ARGUMENT，並且所有其他方法將繼續傳回KM_ERROR_KEYMASTER_NOT_CONFIGURED。
定義位於檔案keymaster2.h第58行。
| 無效*上下文 |
定義位於檔案keymaster2.h第37行。
| keymaster_error_t (* delete_all_keys)(const struct keymaster2_device *dev) |
刪除硬體金鑰庫中的所有金鑰。當密鑰庫完全重置時使用。呼叫此函數後，將無法使用任何先前產生或匯入的密鑰 blob 進行任何操作。
此函數是可選的，如果未實現，則應設為 NULL。
- 參數
[在] 開發者 密鑰主設備結構。
定義位於檔案keymaster2.h的第288行。
| keymaster_error_t (* delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key) |
刪除與密鑰 blob 關聯的密鑰或密鑰對。呼叫此函數後，將無法使用該鍵進行任何其他操作。可以應用於來自外部信任根的密鑰（在當前信任根下不可用的密鑰）。
此函數是可選的，如果未實現，則應設為 NULL。
- 參數
[在] 開發者 密鑰主設備結構。 [在] 鑰匙 要刪除的密鑰。
檔案keymaster2.h第276行的定義。
匯出公鑰或對稱金鑰，傳回指定格式的位元組數組。
請注意，只有當金鑰是使用 KM_TAG_EXPORTABLE 建立的，並且滿足金鑰使用的所有要求（例如驗證）時，才允許對稱金鑰匯出。
- 參數
[在] 開發者 密鑰主設備結構。 [在] 導出格式 用於導出密鑰的格式。 [在] 匯出金鑰 導出的關鍵。 [在] 客戶ID 客戶端 ID blob，必須與金鑰產生期間 KM_TAG_APPLICATION_ID 中提供的 blob 相符（如果有）。 [在] 應用程式數據 應用程式資料 blob，必須與密鑰產生期間 KM_TAG_APPLICATION_DATA 中提供的 blob 相符（如果有）。 [出去] 匯出數據 導出的密鑰材料。呼叫者取得所有權。
檔案keymaster2.h第213行的定義。
| keymaster_error_t （*完成）（const struct keymaster2_device *dev， keymaster_operation_handle_t operation_handle，const keymaster_key_param_set_t *in_params，const keymaster_blob_t *輸入，const keymaster_blobmaster_params ，const keymaster_blob_t *輸入， const keymaster_blobmaster_m_keymaster |
完成以begin()開始的加密操作並使operation_handle無效。
- 參數
[在] 開發者 密鑰主設備結構。 [在] 操作句柄 begin()傳回的操作句柄。該句柄將失效。 [在] 輸入參數 操作的附加參數。對於 AEAD 模式，這用於指定 KM_TAG_ADDITIONAL_DATA，但前提是未向update()提供輸入資料。 [在] 輸入 根據呼叫begin()中建立的參數來處理資料。 finish()必須消耗所有提供的資料或傳回 KM_ERROR_INVALID_INPUT_LENGTH。 [在] 簽名 如果begin()呼叫中指定的目的是 KM_PURPOSE_VERIFY，則要驗證的簽章。 [出去] 輸出 輸出數據（如果有）。呼叫者承擔所分配緩衝區的所有權。
如果正在完成的操作是簽章驗證或 AEAD 模式解密且驗證失敗，則finish()將傳回 KM_ERROR_VERIFICATION_FAILED。
檔案keymaster2.h第405行的定義。
| uint32_t 標誌 |
請參閱keymaster_common.h中為 keymaster0_devices::flags 定義的標誌。僅用於向後相容； keymaster2 硬體設備必須設定為零。
定義位於檔案keymaster2.h第43行。
| keymaster_error_t (*generate_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics) |
產生密鑰或密鑰對，傳回密鑰 blob 和/或密鑰的描述。
金鑰產生參數定義為 keymaster 標籤/值對，在params中提供。有關完整列表，請參閱 keymaster_tag_t。產生有用密鑰始終需要的一些值是：
- KM_TAG_演算法；
- KM_TAG_目的；和
- （KM_TAG_USER_SECURE_ID 和 KM_TAG_USER_AUTH_TYPE）或 KM_TAG_NO_AUTH_REQUIRED。
通常應指定 KM_TAG_AUTH_TIMEOUT，除非存在 KM_TAG_NO_AUTH_REQUIRED，否則使用者必須對每次使用進行驗證。
對於需要它們的演算法，必須指定 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
- 參數
[在] 開發者 密鑰主設備結構。 [在] 參數 金鑰產生參數數組 [出去] 密鑰區塊 傳回產生的密鑰。 key_blob不能為 NULL。呼叫者假定擁有 key_blob->key_material 所有權且必須 free() 它。[出去] 特徵 如果非 NULL，則傳回已產生的鍵的特徵。如果非 NULL，則呼叫者假定所有權並且必須使用keymaster_free_characteristics()取消指派。請注意，KM_TAG_ROOT_OF_TRUST、KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA 永遠不會回傳。
檔案keymaster2.h第112行的定義。
| keymaster_error_t (* get_key_characteristics)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key *client_id, const. |
傳回指定金鑰的特徵，如果 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 永遠不會回傳。
- 參數
[在] 開發者 密鑰主設備結構。 [在] 密鑰區塊 從中檢索特徵的關鍵。 [在] 客戶ID 客戶端 ID 數據，如果沒有關聯則為 NULL。 [在] 應用程式ID 應用程式數據，如果沒有關聯則為 NULL。 [出去] 特徵 關鍵特徵。不能為 NULL。呼叫者假定內容的所有權，並且必須使用keymaster_free_characteristics()取消分配。
定義位於檔案keymaster2.h的第139行。
| keymaster_error_t (* import_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params , keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_mtics_tmaster |
匯入密鑰或密鑰對，傳回密鑰 blob 和/或密鑰的描述。
大多數關鍵導入參數被定義為 keymaster 標籤/值對，在「params」中提供。有關完整列表，請參閱 keymaster_tag_t。導入有用密鑰始終需要的值是：
- KM_TAG_演算法；
- KM_TAG_目的；和
- （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
- 參數
[在] 開發者 密鑰主設備結構。 [在] 參數 定義導入密鑰的參數。 [在] 參數計數 params中的條目數。[在] 密鑰格式 指定key_data中金鑰資料的格式。 [出去] 密鑰區塊 用於傳回不透明的密鑰塊。必須為非 NULL。呼叫者假定所包含的 key_material 的所有權。 [出去] 特徵 用於傳回導入密鑰的特徵。可能為 NULL，在這種情況下不會傳回任何特徵。如果非 NULL，則呼叫者假定內容的所有權，並且必須使用keymaster_free_characteristics()取消指派。請注意，KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA 永遠不會回傳。
檔案keymaster2.h第186行的定義。
| keymaster_error_t （*更新） （ const struct keymaster2_device *dev， keymaster_operation_handle_t operation_handle，const keymaster_key_param_set_t *in_params，const keymaster_blob_t *輸入，size_t *input_consumed， const keymaster_blob_t *. |
向以begin()開始的正在進行的加密操作提供數據，並可能從該操作接收輸出。
如果操作句柄無效， update()將傳回 KM_ERROR_INVALID_OPERATION_HANDLE。
update()可能不會消耗資料緩衝區中提供的所有資料。 update()將傳回 *data_consumed 中消耗的數量。調用者應在後續調用中提供未使用的資料。
- 參數
[在] 開發者 密鑰主設備結構。 [在] 操作句柄 begin()傳回的操作句柄。 [在] 輸入參數 操作的附加參數。對於 AEAD 模式，這用於指定 KM_TAG_ADDITIONAL_DATA。請注意，可以在對update()的多次呼叫中提供附加數據，但僅限於提供輸入資料之前。 [在] 輸入 根據呼叫begin()中建立的參數來處理資料。請注意， update()可能會也可能不會消耗所提供的所有資料。請參閱 input_consumed。[出去] 輸入消耗 update()消耗的資料量。如果這小於提供的金額，則呼叫者應在後續呼叫update()時提供剩餘部分。 [出去] 輸出參數 輸出參數。用於從操作傳回附加資料 呼叫者取得輸出參數陣列的所有權，並且必須使用keymaster_free_param_set()釋放它。如果不需要輸出參數，out_params 可以設定為 NULL。如果 out_params 為 NULL，且產生了輸出參數，則begin()將傳回 KM_ERROR_OUTPUT_PARAMETER_NULL。 [出去] 輸出 輸出數據（如果有）。呼叫者承擔所分配緩衝區的所有權。輸出不能為 NULL。
請注意， update()可能不提供任何輸出，在這種情況下，output->data_length 將為零，並且output->data 可能為 NULL 或零長度（因此呼叫者應始終 free() 它）。
檔案keymaster2.h第376行的定義。
| keymaster_error_t (*upgrade_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key) |
升級舊鑰匙。金鑰可以透過兩種方式變「舊」：Keymaster 可以升級到新版本，或者係統可以更新以使作業系統版本和/或修補程式等級失效。無論哪種情況，嘗試使用舊密鑰都會導致 keymaster 傳回 KM_ERROR_KEY_REQUIRES_UPGRADE。然後應該呼叫此方法來升級金鑰。
- 參數
[在] 開發者 密鑰主設備結構。 [在] 升級金鑰 用於升級的 keymaster 金鑰。 [在] 升級參數 完成升級所需的參數。特別是，如果為金鑰定義了 KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA，則需要它們。 [出去] 升級金鑰 升級後的密鑰塊。
檔案keymaster2.h第260行的定義。
該結構的文檔是從以下文件產生的：