keymaster1_device 结构体参考文档

keymaster1_device 结构体参考文档

#include < keymaster1.h >

数据字段

struct hw_device_t   常见
 
uint32_t  client_version
 
uint32_t  标志
 
void *  上下文
 
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)
 
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)
 
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)
 
int(*  delete_keypair )(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length)
 
int(*  delete_all )(const struct keymaster1_device *dev)
 
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)
 
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)
 
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_padding_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 algorithm, 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 (*  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)
 
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)
 
keymaster_error_t (*  finish )(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 行

字段文档

中止以 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 输出与随机输出无法区分。因此,如果来自任何来源的熵较高,输出也会较高。

参数
[in] dev Keymaster 设备结构。
[in] data 要混入的随机数据。
[in] data_length data 的长度。

定义位于文件 keymaster1.h 的 242 行。

使用指定的密钥开始执行加密操作。如果一切顺利, begin() 将返回 KM_ERROR_OK 并创建一个操作句柄,该句柄必须传递给对 update() finish() abort() 的后续调用。

请务必将对 begin() 的每次调用与对 finish() abort() 的后续调用搭配使用,以便密钥管理器实现能够清理任何内部操作状态。如果不执行此操作,可能会泄露内部状态空间或其他内部资源,并最终导致 begin() 在操作空间用尽时返回 KM_ERROR_TOO_MANY_OPERATIONS。 begin() update() finish() 返回的任何结果(除了 KM_ERROR_OK)都会隐式中止操作,在这种情况下,无需调用 abort() (如果调用,则会返回 KM_ERROR_INVALID_OPERATION_HANDLE)。

参数
[in] dev Keymaster 设备结构。
[in] 用途 操作的用途,KM_PURPOSE_ENCRYPT、KM_PURPOSE_DECRYPT、KM_PURPOSE_SIGN 或 KM_PURPOSE_VERIFY 之一。请注意,对于 AEAD 模式,加密和解密分别表示签名和验证,但应指定为 KM_PURPOSE_ENCRYPT 和 KM_PURPOSE_DECRYPT。
[in] key 要用于操作的密钥。 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。对于 AEAD 操作,此处指定了 KM_TAG_CHUNK_SIZE。
[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 为 NULL, begin() 将返回 KM_ERROR_OUTPUT_PARAMETER_NULL。

定义位于文件 keymaster1.h 的 451 行。

uint32_t client_version

此版本已弃用。请改用 keymaster_module 初始化中的新“module_api_version”和“hal_api_version”字段。

定义位于文件 keymaster1.h 41 行

struct hw_device_t common

Keymaster 设备的常用方法。此 必须 是 keymaster_device 的第一个成员,因为此结构的用户会在已知 hw_device_t 引用 keymaster_device 的情况下,将 hw_device_t 转换为 keymaster_device 指针。

定义位于文件 keymaster1.h 的第 35 行。

void* context

定义位于文件 keymaster1.h 的第 48 行。

int(* delete_all)(const struct keymaster1_device *dev)
已弃用:
删除硬件密钥库中的所有密钥。在完全重置密钥库时使用。

此函数为可选函数,如果未实现,应将其设置为 NULL。

成功时返回 0,否则返回小于 0 的错误代码。

定义位于文件 keymaster1.h 100 行中。

keymaster_error_t (* delete_all_keys)(const struct keymaster1_device *dev)

删除硬件密钥库中的所有密钥。在完全重置密钥库时使用。调用此函数后,将无法再使用之前生成或导入的任何密钥 blob 进行任何操作。

此函数为可选函数,如果未实现,应将其设置为 NULL。

参数
[in] dev Keymaster 设备结构。

定义位于文件 keymaster1.h 407 行。

keymaster_error_t (* delete_key)(const struct keymaster1_device *dev, const keymaster_key_blob_t *key)

删除与密钥 blob 关联的密钥或密钥对。调用此函数后,将无法再将该密钥用于任何其他操作。可应用于来自外部信任根的密钥(在当前信任根下无法使用的密钥)。

此函数为可选函数,如果未实现,应将其设置为 NULL。

参数
[in] dev Keymaster 设备结构。
[in] key 要删除的键。

定义位于文件 keymaster1.h 的第 395 行。

int(* delete_keypair)(const struct keymaster1_device *dev, const uint8_t *key_blob, const size_t key_blob_length)
已弃用:
删除与密钥 blob 关联的密钥对。

此函数为可选函数,如果未实现,应将其设置为 NULL。

成功时返回 0,否则返回小于 0 的错误代码。

定义位于文件 keymaster1.h 88 行。

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)

导出公钥,返回指定格式的字节数组。

参数
[in] dev Keymaster 设备结构。
[in] export_format 用于导出密钥的格式。
[in] key_to_export 要导出的密钥。
[out] export_data 导出的密钥材料。调用方会承担所有权。
[out] export_data_length export_data 的长度。

定义位于文件 keymaster1.h 的 377 行。

用于最终完成通过 begin() 开始的加密操作,并使 operation_handle 失效。

参数
[in] dev Keymaster 设备结构。
[in] operation_handle begin() 返回的操作句柄。此句柄将失效。
[in] params 操作的其他参数。对于 AEAD 模式,此参数用于指定 KM_TAG_ADDITIONAL_DATA,但前提是未向 update() 提供任何输入数据。
[in] signature 如果 begin() 调用中指定的用途为 KM_PURPOSE_VERIFY,则要验证的签名。
[out] 输出 输出数据(如果有)。调用方会承担分配的缓冲区的所有权。

如果正在完成的操作是签名验证或 AEAD 模式解密,并且验证失败,则 finish() 将返回 KM_ERROR_VERIFICATION_FAILED。

定义位于文件 keymaster1.h 521 行

uint32_t 标志

请参阅 keymaster_common.h 中为 keymaster0_devices::flags 定义的标志

定义位于文件 keymaster1.h 46 行中。

生成密钥或密钥对,并返回密钥 blob 和/或密钥说明。

密钥生成参数定义为 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_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
参数
[in] dev Keymaster 设备结构。
[in] params 密钥生成参数数组。
[in] params_count params 的长度。
[out] key_blob 返回生成的密钥。 key_blob 不得为 null。调用方会获得 key_blob->key_material 的所有权,并且必须 free() 它。
[out] 特征 返回生成的密钥的特性(如果非 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)
已弃用:
生成公钥和私钥。返回的密钥 blob 是不可透的,必须在稍后提供以进行签名和验证。

返回值:如果成功,则返回 0;否则返回小于 0 的错误代码。

定义位于文件 keymaster1.h 的第 56 行。

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。

参数
[in] dev Keymaster 设备结构。
[in] key_blob 要从中检索特征的键。
[in] client_id 客户 ID 数据,如果未关联任何 ID,则返回 null。
[in] app_id 应用数据,如果未关联任何数据,则为 NULL。
[out] 特征 主要特征。

定义位于文件 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)

获取支持的算法。

参数
[in] dev Keymaster 设备结构。
[out] 算法 支持的算法数组。调用方获得数组的所有权,并且必须 free() 它。
[out] algorithms_length 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)

获取指定算法支持的分块模式。

参数
[in] dev Keymaster 设备结构。
[in] 算法 系统将返回哪种算法的支持模式。
[out] 模式 支持的模式数组。调用方获得数组的所有权,并且必须 free() 它。
[out] modes_length 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)

获取指定算法支持的摘要。调用方会承担分配的数组的所有权。

参数
[in] dev Keymaster 设备结构。
[in] 算法 将返回支持的摘要的算法。
[out] 摘要 支持摘要数组。调用方获得数组的所有权,并且必须 free() 它。
[out] digests_length 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)

获取指定算法的密钥支持的密钥导出格式。调用方会承担分配的数组的所有权。

参数
[in] dev Keymaster 设备结构。
[in] 算法 系统将针对该算法返回支持的格式。
[out] 格式 支持的格式数组。调用方获得数组的所有权,并且必须 free() 它。
[out] formats_length 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)

获取指定算法的密钥支持的密钥导入格式。调用方会承担分配的数组的所有权。

参数
[in] dev Keymaster 设备结构。
[in] 算法 系统将针对该算法返回支持的格式。
[out] 格式 支持的格式数组。调用方获得数组的所有权,并且必须 free() 它。
[out] formats_length 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)

获取指定算法支持的填充模式。调用方会承担分配的数组的所有权。

参数
[in] dev Keymaster 设备结构。
[in] 算法 系统将返回哪种算法的受支持填充模式。
[out] 模式 支持的填充模式数组。调用方获得数组的所有权,并且必须 free() 它。
[out] modes_length modes 的长度。

定义位于文件 keymaster1.h 的 168 行。

导入密钥或密钥对,并返回密钥 blob 和/或密钥说明。

大多数按键导入参数都定义为“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
参数
[in] dev Keymaster 设备结构。
[in] params 用于定义导入的密钥的参数。
[in] params_count params 中的条目数。
[in] key_format 指定 key_data 中密钥数据的格式。
[out] key_blob 用于返回不透明密钥 blob。必须为非 null。调用方会获得所含 key_material 的所有权。
[out] 特征 用于返回导入的密钥的特征。可以为 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)
已弃用:
导入公钥和私钥对。导入的密钥将采用 PKCS#8 格式和 DER 编码(Java 标准)。返回的密钥 Blob 是不可见的,并会在稍后提供以进行签名和验证。

返回值:如果成功,则返回 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)
已弃用:
使用之前生成的密钥 blob 对数据进行签名。这可以使用非对称密钥或 Secret 密钥。

返回值:如果成功,则返回 0;否则返回小于 0 的错误代码。

定义位于文件 keymaster1.h 的第 108 行。

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 中返回所消耗的数据量。调用方应在后续调用中提供未使用的部分数据。

参数
[in] dev Keymaster 设备结构。
[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] 输出 输出数据(如果有)。调用方会获得所分配缓冲区的所有权。output 不得为 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)
已弃用:
验证使用密钥 blob 签名的数据。这可以使用非对称密钥或 Secret 密钥。

返回值:验证成功时返回 0,否则返回小于 0 的错误代码。

定义位于文件 keymaster1.h 118 行。


此结构体的文档是根据以下文件生成的: