keymaster1_device 結構參考
#include < keymaster1.h >
數據字段 | |
結構hw_device_t | 常見的 |
uint32_t | 客戶端版本 |
uint32_t | 旗幟 |
空白 * | 語境 |
整數(* | generate_keypair )(const struct keymaster1_device *dev, const keymaster_keypair_t key_type, const void *key_params, uint8_t **key_blob, size_t *key_blob_length) |
整數(* | import_keypair )(const struct keymaster1_device *dev, const uint8_t *key, const size_t key_length, uint8_t **key_blob, size_t *key_blob_length) |
整數(* | get_keypair_public )(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length, uint8_t **x509_data, size_t *x509_data_length) |
整數(* | delete_keypair )(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length) |
整數(* | delete_all )(const struct keymaster1_device *dev) |
整數(* | sign_data )(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *data, const size_t data_length, uint8_t **signed_data, size_t *signed_data_length) |
整數(* | verify_data )(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *signed_data, const size_t signed_data_length, const uint8_t *signature, const size_t signature_length) |
keymaster_error_t (* | get_supported_algorithms )(const struct keymaster1_device *dev, keymaster_algorithm_t **algorithms, size_t *algorithms_length) |
keymaster_error_t (* | get_supported_block_modes )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_ purpose_t purpose, keymaster_block_mode_t **modes, size_t *modes_length) |
keymaster_error_t (* | get_supported_pa dding_modes )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_ purpose_t purpose, keymaster_padding_t **modes, size_t *modes_length) |
keymaster_error_t (* | get_supported_digests )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_ purpose_t purpose, keymaster_digest_t **digests, size_t *digests_length) |
keymaster_error_t (* | get_supported_import_formats )(const struct keymaster1_device *dev, keymaster_algorithm_t算法, keymaster_key_format_t **formats, size_t *formats_length) |
keymaster_error_t (* | get_supported_export_formats )(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length) |
keymaster_error_t (* | add_rng_entropy )(const struct keymaster1_device *dev, const uint8_t *data, size_t data_length) |
keymaster_error_t (* | generate_key )(const struct keymaster1_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t **characteristics) |
keymaster_error_t (* | get_key_characteristics )(const struct keymaster1_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t **characteristics) |
keymaster_error_t (* | import_key )(const struct keymaster1_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t **characteristics) |
keymaster_error_t (* | export_key )(const struct keymaster1_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data) |
keymaster_error_t (* | delete_key )(const struct keymaster1_device *dev, const keymaster_key_blob_t *key) |
keymaster_error_t (* | delete_all_keys )(const struct keymaster1_device *dev) |
keymaster_error_t (* | 開始)(const struct keymaster1_device *dev, keymaster_ purpose_t purpose, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle) |
keymaster_error_t (* | 更新)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output) |
keymaster_error_t (* | 完成)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output) |
keymaster_error_t (* | abort )(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle) |
詳細說明
Keymaster1 設備定義
文件keymaster1.h第28行的定義。
現場文件
keymaster_error_t (* abort)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle) |
中止以begin()開始的加密操作,釋放所有內部資源並使operation_handle
無效。
在文件keymaster1.h的第531行定義。
keymaster_error_t (* add_rng_entropy)(const struct keymaster1_device *dev, const uint8_t *data, size_t data_length) |
向 keymaster 使用的 RNG 添加熵。保證通過這種方法添加的熵不是唯一使用的熵源,並且混合函數必須是安全的,從某種意義上說,如果 RNG 是用攻擊者無法預測的任何數據(來自任何來源)播種(或控制),則 RNG 輸出與隨機無法區分。因此,如果來自任何來源的熵是好的,那麼輸出就會是好的。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 數據 要混入的隨機數據。 [在] 數據長度 data
長度。
在文件keymaster1.h的第242行定義。
keymaster_error_t (* begin)(const struct keymaster1_device *dev, keymaster_ purpose_t purpose, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle) |
使用指定的密鑰開始加密操作。如果一切順利, 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)。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 目的 操作的目的,KM_PURPOSE_ENCRYPT、KM_PURPOSE_DECRYPT、KM_PURPOSE_SIGN 或 KM_PURPOSE_VERIFY 之一。請注意,對於 AEAD 模式,加密和解密分別意味著簽名和驗證,但應指定為 KM_PURPOSE_ENCRYPT 和 KM_PURPOSE_DECRYPT。 [在] 鑰匙 用於操作的密鑰。 key
必須具有與 purpose 兼容的purpose
,並且必須滿足其所有使用要求,否則begin()將返回適當的錯誤代碼。[在] in_params 操作的附加參數。這通常用於通過 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。對於 AEAD 操作,此處指定 KM_TAG_CHUNK_SIZE。 [出去] out_params 輸出參數。用於從操作初始化返回附加數據,特別是從生成 IV 或 nonce 的操作中返回 IV 或 nonce。調用者擁有輸出參數數組的所有權,並且必須使用keymaster_free_param_set()釋放它。如果不需要輸出參數,out_params 可以設置為 NULL。如果 out_params 為 NULL,並且生成了輸出參數, begin()將返回 KM_ERROR_OUTPUT_PARAMETER_NULL。 [出去] 操作句柄 必須傳遞給update() 、 finish()或abort()的新創建的操作句柄。如果 operation_handle 為 NULL, begin()將返回 KM_ERROR_OUTPUT_PARAMETER_NULL。
在文件keymaster1.h的第451行定義。
uint32_t 客戶端版本 |
這已被棄用。在 keymaster_module 初始化中使用新的“module_api_version”和“hal_api_version”字段。
文件keymaster1.h第41行的定義。
結構hw_device_t通用 |
keymaster 設備的常用方法。這必須是 keymaster_device 的第一個成員,因為此結構的用戶將在已知hw_device_t引用 keymaster_device 的上下文中將 hw_device_t 轉換為 keymaster_device 指針。
文件keymaster1.h第35行的定義。
無效*上下文 |
文件keymaster1.h第48行的定義。
int(* delete_all)(const struct keymaster1_device *dev) |
keymaster_error_t (* delete_all_keys)(const struct keymaster1_device *dev) |
刪除硬件密鑰庫中的所有密鑰。當密鑰庫完全重置時使用。調用此函數後,將無法將任何先前生成或導入的密鑰 blob 用於任何操作。
此函數是可選的,如果未實現,應設置為 NULL。
- 參數
[在] 開發者 keymaster 設備結構。
在文件keymaster1.h的第407行定義。
keymaster_error_t (* delete_key)(const struct keymaster1_device *dev, const keymaster_key_blob_t *key) |
刪除與密鑰 Blob 關聯的密鑰或密鑰對。調用此函數後,將無法使用該鍵進行任何其他操作。可應用於來自外部信任根的密鑰(在當前信任根下無法使用的密鑰)。
此函數是可選的,如果未實現,應設置為 NULL。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 鑰匙 要刪除的密鑰。
文件keymaster1.h第395行的定義。
int(* delete_keypair)(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length) |
keymaster_error_t (* export_key)(const struct keymaster1_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data) |
導出公鑰,返回指定格式的字節數組。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 導出格式 用於導出密鑰的格式。 [在] key_to_export 出口的關鍵。 [出去] 導出數據 導出的密鑰材料。調用者承擔所有權。 [出去] 導出數據長度 export_data
的長度。
文件keymaster1.h第377行的定義。
keymaster_error_t (* 完成)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output) |
結束以begin()開始的加密操作並使operation_handle
無效。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 操作句柄 begin()返回的操作句柄。此句柄將失效。 [在] 參數 操作的附加參數。對於 AEAD 模式,這用於指定 KM_TAG_ADDITIONAL_DATA,但前提是沒有向update()提供輸入數據。 [在] 簽名 如果在begin()調用中指定的目的是 KM_PURPOSE_VERIFY,則要驗證的簽名。 [出去] 輸出 輸出數據(如果有)。調用者承擔分配緩衝區的所有權。
如果正在完成的操作是簽名驗證或 AEAD 模式解密並且驗證失敗,則finish()將返回 KM_ERROR_VERIFICATION_FAILED。
文件keymaster1.h第521行的定義。
uint32_t 標誌 |
請參閱 keymaster_common.h 中為keymaster0_devices ::flags 定義的標誌
文件keymaster1.h第46行的定義。
keymaster_error_t (* generate_key)(const struct keymaster1_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_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
- 參數
[在] 開發者 keymaster 設備結構。 [在] 參數 密鑰生成參數數組。 [在] params_count params
長度。[出去] key_blob 返回生成的密鑰。 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。
在文件keymaster1.h的第282行定義。
int(* generate_keypair)(const struct keymaster1_device *dev, const keymaster_keypair_t key_type, const void *key_params, uint8_t **key_blob, size_t *key_blob_length) |
keymaster_error_t (* get_key_characteristics)(const struct keymaster1_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t **characteristics) |
返回指定密鑰的特徵,如果 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_ROOT_OF_TRUST、KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA。
- 參數
[在] 開發者 keymaster 設備結構。 [在] key_blob 從中檢索特徵的關鍵。 [在] client_id 客戶端 ID 數據,如果沒有關聯,則為 NULL。 [在] app_id 應用程序數據,如果沒有關聯,則為 NULL。 [出去] 特徵 關鍵特徵。
在文件keymaster1.h的第309行定義。
int(* get_keypair_public)(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length, uint8_t **x509_data, size_t *x509_data_length) |
- 已棄用:
- 獲取密鑰對的公鑰部分。公鑰必須是 X.509 格式(Java 標準)編碼的字節數組。
返回:成功時返回 0 或小於 0 的錯誤代碼。出錯時,不應分配 x509_data。
文件keymaster1.h第76行的定義。
keymaster_error_t (* get_supported_algorithms)(const struct keymaster1_device *dev, keymaster_algorithm_t **algorithms, size_t *algorithms_length) |
獲取支持的算法。
- 參數
[在] 開發者 keymaster 設備結構。 [出去] 算法 支持的算法數組。調用者獲得數組的所有權並且必須 free() 它。 [出去] 算法長度 algorithms
的長度。
文件keymaster1.h第133行的定義。
keymaster_error_t (* get_supported_block_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_ purpose_t purpose, keymaster_block_mode_t **modes, size_t *modes_length) |
獲取指定算法支持的模塊模式。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 算法 將返回支持的模式的算法。 [出去] 模式 支持的模式數組。調用者獲得數組的所有權並且必須 free() 它。 [出去] 模式長度 modes
的長度。
文件keymaster1.h第149行的定義。
keymaster_error_t (* get_supported_digests)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_ purpose_t purpose, keymaster_digest_t **digests, size_t *digests_length) |
獲取指定算法支持的摘要。調用者承擔分配數組的所有權。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 算法 將返回支持的摘要的算法。 [出去] 文摘 支持的摘要數組。調用者獲得數組的所有權並且必須 free() 它。 [出去] 摘要長度 digests
的長度。
文件keymaster1.h第187行的定義。
keymaster_error_t (* get_supported_export_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length) |
獲取指定算法的密鑰支持的密鑰導出格式。調用者承擔分配數組的所有權。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 算法 將返回支持的格式的算法。 [出去] 格式 支持的格式數組。調用者獲得數組的所有權並且必須 free() 它。 [出去] 格式長度 formats
的長度。
在文件keymaster1.h的第224行定義。
keymaster_error_t (* get_supported_import_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_key_format_t **formats, size_t *formats_length) |
獲取指定算法的密鑰支持的密鑰導入格式。調用者承擔分配數組的所有權。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 算法 將返回支持的格式的算法。 [出去] 格式 支持的格式數組。調用者獲得數組的所有權並且必須 free() 它。 [出去] 格式長度 formats
的長度。
在文件keymaster1.h的第206行定義。
keymaster_error_t (* get_supported_padding_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t algorithm, keymaster_ purpose_t purpose, keymaster_padding_t **modes, size_t *modes_length) |
獲取指定算法支持的填充模式。調用者承擔分配數組的所有權。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 算法 將返回支持的填充模式的算法。 [出去] 模式 支持的填充模式數組。調用者獲得數組的所有權並且必須 free() 它。 [出去] 模式長度 modes
的長度。
文件keymaster1.h第168行的定義。
keymaster_error_t (* import_key)(const struct keymaster1_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t **characteristics) |
導入密鑰或密鑰對,返回密鑰 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_AUTH_TIMEOUT。如果未指定,則用戶必須為每次使用進行身份驗證。
如果未指定,以下標籤將採用默認值:
- KM_TAG_KEY_SIZE 將默認為提供的密鑰的大小。
- KM_TAG_RSA_PUBLIC_EXPONENT 將默認為提供的密鑰中的值(對於 RSA 密鑰)
不能指定以下標籤;它們的值將由實現提供。
- KM_TAG_ORIGIN,
- KM_TAG_ROLLBACK_RESISTANT,
- KM_TAG_CREATION_DATETIME
- 參數
[在] 開發者 keymaster 設備結構。 [在] 參數 定義導入密鑰的參數。 [在] params_count params
中的條目數。[在] 密鑰格式 指定 key_data 中密鑰數據的格式。 [出去] key_blob 用於返回不透明的密鑰 blob。必須為非 NULL。調用者承擔所包含的 key_material 的所有權。 [出去] 特徵 用於返回導入密鑰的特徵。可能為 NULL,在這種情況下不會返回任何特徵。如果非 NULL,則調用者承擔所有權並且必須使用keymaster_free_characteristics()解除分配。請注意,永遠不會返回 KM_TAG_ROOT_OF_TRUST、KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA。
文件keymaster1.h第357行的定義。
int(* import_keypair)(const struct keymaster1_device *dev, const uint8_t *key, const size_t key_length, uint8_t **key_blob, size_t *key_blob_length) |
- 已棄用:
- 導入公鑰和私鑰對。導入的密鑰將採用帶有 DER 編碼(Java 標準)的 PKCS#8 格式。返回的密鑰塊是不透明的,隨後將提供給簽名和驗證。
返回:0 表示成功或錯誤代碼小於 0。
文件keymaster1.h第66行的定義。
int(* sign_data)(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *data, const size_t data_length, uint8_t **signed_data, size_t *signed_data_length) |
keymaster_error_t (* update)(const struct keymaster1_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output) |
向以begin()開始的正在進行的加密操作提供數據,並可能從其接收輸出。
如果 operation_handle 無效, update()將返回 KM_ERROR_INVALID_OPERATION_HANDLE。
update()可能不會消耗數據緩衝區中提供的所有數據。 update()將返回 *data_consumed 中消耗的數量。調用者應在後續調用中提供未使用的數據。
- 參數
[在] 開發者 keymaster 設備結構。 [在] 操作句柄 begin()返回的操作句柄。 [在] in_params 操作的附加參數。對於 AEAD 模式,這用於指定 KM_TAG_ADDITIONAL_DATA。請注意,可以在對update()的多次調用中提供附加數據,但僅在提供輸入數據之前提供。 [在] 輸入 要處理的數據,根據在begin()調用中建立的參數。請注意, update()可能會也可能不會使用所提供的所有數據。請參閱 input_consumed
。[出去] input_consumed update()使用的數據量。如果這少於提供的金額,則調用者應在後續調用update()時提供剩餘部分。 [出去] out_params 輸出參數。用於從操作中返回附加數據調用者擁有輸出參數數組的所有權,並且必須使用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() 它)。
文件keymaster1.h第495行的定義。
int(* verify_data)(const struct keymaster1_device *dev, const void *signing_params, const uint8_t *key_blob, const size_t key_blob_length, const uint8_t *signed_data, const size_t signed_data_length, const uint8_t *signature, const size_t signature_length) |
此結構的文檔是從以下文件生成的: