keymaster2_device 结构参考

keymaster2_device 结构参考

#include < keymaster2.h >

数据字段

结构hw_device_t常见的
空白 *语境
uint32_t旗帜
keymaster_error_t (*配置)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)
keymaster_error_t (* add_rng_entropy )(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length)
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)
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_characteristics_t *characteristics)
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_blob_t *key_blob, keymaster_key_characteristics_t *characteristics)
keymaster_error_t (* export_key )(const struct keymaster2_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 (* 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)
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_error_t (* delete_key )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key)
keymaster_error_t (* delete_all_keys )(const struct keymaster2_device *dev)
keymaster_error_t (*开始)(const struct keymaster2_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 keymaster2_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 keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
keymaster_error_t (* abort )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle)

详细说明

Keymaster2 设备定义

文件keymaster2.h28行的定义。

现场文件

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 输出与随机无法区分。因此,如果来自任何来源的熵是好的,那么输出就会是好的。

参数
[在]开发者keymaster 设备结构。
[在]数据要混入的随机数据。
[在]数据长度data长度。

文件keymaster2.h74行的定义。

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 证书链,证明key_to_attest中存在 key_to_attest(TODO(swillden):更详细地描述证书内容)。证书将包含一个 OID 为 1.3.6.1.4.1.11129.2.1.17 的扩展,其值在 <TODO:swillden – insert link here> 中定义,其中包含密钥描述。

参数
[在]开发者keymaster 设备结构。
[在] key_to_attest将为其生成证明证书的密钥主密钥。
[在]证明参数定义如何进行证明的参数。目前唯一的参数是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 (* begin)(const struct keymaster2_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。
[出去] 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。

在文件keymaster2.h的第332行定义。

结构hw_device_t通用

keymaster 设备的常用方法。这必须是 keymaster_device 的第一个成员,因为此结构的用户将在已知hw_device_t引用 keymaster_device 的上下文中将 hw_device_t 转换为 keymaster_device 指针。

文件keymaster2.h35行的定义。

keymaster_error_t (* configure)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)

配置 keymaster。此方法必须在设备打开后使用前调用一次。它用于向 keymaster 提供 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.h58行的定义。

无效*上下文

文件keymaster2.h37行的定义。

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

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

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

参数
[在]开发者keymaster 设备结构。

在文件keymaster2.h的第288行定义。

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

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

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

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

文件keymaster2.h276行的定义。

keymaster_error_t (* export_key)(const struct keymaster2_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)

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

请注意,仅当使用 KM_TAG_EXPORTABLE 创建密钥并且满足密钥使用的所有要求(例如身份验证)时,才允许导出对称密钥。

参数
[在]开发者keymaster 设备结构。
[在]导出格式用于导出密钥的格式。
[在] key_to_export出口的关键。
[在] client_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 *input, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)

结束以begin()开始的加密操作并使operation_handle无效。

参数
[在]开发者keymaster 设备结构。
[在]操作句柄begin()返回的操作句柄。此句柄将失效。
[在] in_params操作的附加参数。对于 AEAD 模式,这用于指定 KM_TAG_ADDITIONAL_DATA,但前提是没有向update()提供输入数据。
[在]输入要处理的数据,根据在begin()调用中建立的参数。 finish()必须消耗所有提供的数据或返回 KM_ERROR_INVALID_INPUT_LENGTH。
[在]签名如果在begin()调用中指定的目的是 KM_PURPOSE_VERIFY,则要验证的签名。
[出去]输出输出数据(如果有)。调用者承担分配缓冲区的所有权。

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

文件keymaster2.h405行的定义。

uint32_t 标志

请参阅 keymaster_common.h 中为keymaster0_devices ::flags 定义的标志。仅用于向后兼容; keymaster2 硬件设备必须将此设置为零。

文件keymaster2.h43行的定义。

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_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 设备结构。
[在]参数密钥生成参数数组
[出去] 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。

文件keymaster2.h112行的定义。

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_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_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA。

参数
[在]开发者keymaster 设备结构。
[在] key_blob从中检索特征的关键。
[在] client_id客户端 ID 数据,如果没有关联,则为 NULL。
[在] app_id应用程序数据,如果没有关联,则为 NULL。
[出去]特征关键特征。不得为 NULL。调用者承担内容的所有权,并且必须使用keymaster_free_characteristics()解除分配。

文件keymaster2.h139行的定义。

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_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_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA。

文件keymaster2.h186行的定义。

keymaster_error_t (* update)(const struct keymaster2_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() 它)。

在文件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 设备结构。
[在] key_to_upgrade要升级的主密钥。
[在]升级参数完成升级所需的参数。特别是,如果为密钥定义了 KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA,则它们将是必需的。
[出去]升级密钥升级后的密钥 blob。

在文件keymaster2.h的第260行定义。


此结构的文档是从以下文件生成的: