keymaster1_device 结构参考

数据字段
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）
整数（*删除_密钥对)(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_tsigned_data_length，const uint8_t *signature，const size_t 签名_length）
keymaster_error_t (* get_supported_algorithms ）（const struct keymaster1_device *dev， keymaster_algorithm_t **算法，size_t *algorithms_length）
keymaster_error_t (* get_supported_block_modes ）（const struct keymaster1_device *dev、 keymaster_algorithm_t算法、 keymaster_ Purpose_t目的、 keymaster_block_mode_t **模式、size_t *modes_length）
keymaster_error_t (* get_supported_pa​​dding_modes ）（const struct keymaster1_device *dev， keymaster_algorithm_t算法， keymaster_ Purpose_t目的， keymaster_padding_t **模式，size_t *modes_length）
keymaster_error_t (* get_supported_digests ）（const struct keymaster1_device *dev、 keymaster_algorithm_t算法、 keymaster_ Purpose_t目的、 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 **格式, size_t *formats_length)
keymaster_error_t (* get_supported_export_formats ）（const struct keymaster1_device *dev， keymaster_algorithm_t算法， keymaster_key_format_t **格式，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 **特征）
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 **特征）
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 **特征）
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目的, 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 *输入，size_t *input_consumed， keymaster_key_param_set_t *out_params， keymaster_blob_t *输出）
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 (*中止）（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 输出与随机输出无法区分。因此，如果任何来源的熵良好，则输出也会良好。

参数
[在]开发者密钥主设备结构。
[在]数据要混合的随机数据。
[在]数据长度data长度。

文件keymaster1.h第242行的定义。

keymaster_error_t (* 开始)(const struct keymaster1_device *dev, keymaster_ Purpose_t目的, 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 ）。

参数
[在]开发者密钥主设备结构。
[在]目的操作的目的，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。对于 AEAD 操作，此处指定 KM_TAG_CHUNK_SIZE。
[出去]输出参数输出参数。用于从操作初始化返回附加数据，特别是从生成 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。

文件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)
已弃用：
删除硬件密钥库中的所有密钥。当密钥库完全重置时使用。

该函数是可选的，如果未实现，则应设置为 NULL。

成功时返回 0 或小于 0 的错误代码。

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

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

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

该函数是可选的，如果未实现，则应设置为 NULL。

参数
[在]开发者密钥主设备结构。

文件keymaster1.h第407行的定义。

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

删除与密钥 blob 关联的密钥或密钥对。调用此函数后，将无法使用该键进行任何其他操作。可以应用于来自外部信任根的密钥（在当前信任根下不可用的密钥）。

该函数是可选的，如果未实现，则应设置为 NULL。

参数
[在]开发者密钥主设备结构。
[在]钥匙要删除的密钥。

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

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

参数
[在]开发者密钥主设备结构。
[在]导出格式用于导出密钥的格式。
[在]导出密钥导出的关键。
[出去]导出数据导出的密钥材料。调用者取得所有权。
[出去]导出数据长度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无效。

参数
[在]开发者密钥主设备结构。
[在]操作句柄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 **特征)

生成密钥或密钥对，返回密钥 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
参数
[在]开发者密钥主设备结构。
[在]参数关键生成参数数组。
[在]参数计数params的长度。
[出去]密钥块返回生成的密钥。 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)
已弃用：
生成公钥和私钥。返回的密钥块是不透明的，随后必须提供用于签名和验证。

返回：成功时返回 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 **特征)

返回指定密钥的特征，如果 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 永远不会返回。

参数
[在]开发者密钥主设备结构。
[在]密钥块从中检索特征的关键。
[在]客户ID客户端 ID 数据，如果没有关联则为 NULL。
[在]应用程序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 **算法, size_t *algorithms_length)

获取支持的算法。

参数
[在]开发者密钥主设备结构。
[出去]算法支持的算法数组。调用者获得数组的所有权并且必须 free() 它。
[出去]算法长度algorithms的长度。

文件keymaster1.h第133行的定义。

keymaster_error_t (* get_supported_block_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t算法, keymaster_ Purpose_t目的, keymaster_block_mode_t **模式, size_t *modes_length)

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

参数
[在]开发者密钥主设备结构。
[在]算法将返回支持的模式的算法。
[出去]模式支持的模式数组。调用者获得数组的所有权并且必须 free() 它。
[出去]模式长度modes的长度。

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

keymaster_error_t (* get_supported_digests)(const struct keymaster1_device *dev, keymaster_algorithm_t算法, keymaster_ Purpose_t目的, keymaster_digest_t **摘要, size_t *digests_length)

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

参数
[在]开发者密钥主设备结构。
[在]算法将返回支持的摘要的算法。
[出去]摘要支持摘要数组。调用者获得数组的所有权并且必须 free() 它。
[出去]摘要长度digests的长度。

文件keymaster1.h第187行的定义。

keymaster_error_t (* get_supported_export_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t算法, keymaster_key_format_t **格式, size_t *formats_length)

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

参数
[在]开发者密钥主设备结构。
[在]算法将返回支持的格式的算法。
[出去]格式支持的格式数组。调用者获得数组的所有权并且必须 free() 它。
[出去]格式长度formats的长度。

文件keymaster1.h第224行的定义。

keymaster_error_t (* get_supported_import_formats)(const struct keymaster1_device *dev, keymaster_algorithm_t算法, keymaster_key_format_t **格式, size_t *formats_length)

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

参数
[在]开发者密钥主设备结构。
[在]算法将返回支持的格式的算法。
[出去]格式支持的格式数组。调用者获得数组的所有权并且必须 free() 它。
[出去]格式长度formats的长度。

文件keymaster1.h第206行的定义。

keymaster_error_t (* get_supported_pa​​dding_modes)(const struct keymaster1_device *dev, keymaster_algorithm_t算法, keymaster_ Purpose_t目的, keymaster_padding_t **模式, size_t *modes_length)

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

参数
[在]开发者密钥主设备结构。
[在]算法将返回支持的填充模式的算法。
[出去]模式支持的填充模式数组。调用者获得数组的所有权并且必须 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 **特征)

导入密钥或密钥对，返回密钥 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_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)
已弃用：
使用之前生成的密钥块对数据进行签名。这可以使用非对称密钥或秘密密钥。

返回：成功时返回 0，或者小于 0 的错误代码。

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

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 *输入，size_t *input_consumed， keymaster_key_param_set_t *out_params， 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() 它）。

定义位于文件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_tsigned_data_length, const uint8_t *signature, const size_t 签名_length)
已弃用：
验证使用密钥 blob 签名的数据。这可以使用非对称密钥或秘密密钥。

返回：验证成功时返回 0 或小于 0 的错误代码。

文件keymaster1.h第118行的定义。

该结构的文档是从以下文件生成的：