keymaster2_device 结构体参考文档

中止以 begin() 开头的加密操作，释放所有内部资源并使 operation_handle 失效。

定义位于文件 keymaster2.h 的 415 行。

向 Keymaster 使用的 RNG 添加熵。通过此方法添加的熵保证不是使用的唯一熵源，并且混合函数必须是安全的，也就是说，如果 RNG 使用攻击者无法预测（或控制）的任何数据（来自任何来源）作为种子，则 RNG 输出与随机输出无法区分。因此，如果来自任何来源的熵较高，输出也会较高。

参数

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

定义位于文件 keymaster2.h 的第 74 行。

生成签名的 X.509 证书链，用于证明密钥管理器中存在 key_to_attest （TODO(swillden)：详细说明证书内容）。证书将包含一个 OID 为 1.3.6.1.4.1.11129.2.1.17 的扩展，以及 <TODO:swillden – insert link here> 中定义的值，其中包含密钥说明。

参数

[in]	dev	Keymaster 设备结构。
[in]	key_to_attest	将为其生成认证证书的 Keymaster 密钥。
[in]	attest_params	用于定义如何进行证明的参数。目前，唯一的参数是 KM_TAG_ALGORITHM，该参数必须为 KM_ALGORITHM_EC 或 KM_ALGORITHM_RSA。这会选择要用于对证书进行签名的预配认证密钥。
[out]	cert_chain	一个 DER 编码的 X.509 证书数组。第一个是 key_to_attest 的证书。其余条目会链接回根目录。调用方获得所有权，并且必须使用 keymaster_free_cert_chain 取消分配。

定义位于文件 keymaster2.h 的 239 行。

使用指定的密钥开始执行加密操作。如果一切顺利， 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。
[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。

定义位于文件 keymaster2.h 的 332 行。

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

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

配置 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.h 的 58 行。

定义位于文件 keymaster2.h 的 37 行。

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

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

参数

[in]

dev

Keymaster 设备结构。

定义位于文件 keymaster2.h 的 288 行。

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

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

参数

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

定义位于文件 keymaster2.h 的 276 行。

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

请注意，只有在使用 KM_TAG_EXPORTABLE 创建密钥且满足所有密钥使用要求（例如身份验证）的情况下，才允许对称密钥进行导出。

参数

[in]	dev	Keymaster 设备结构。
[in]	export_format	用于导出密钥的格式。
[in]	key_to_export	要导出的密钥。
[in]	client_id	客户端 ID blob，必须与密钥生成期间在 KM_TAG_APPLICATION_ID 中提供的 blob（如果有）一致。
[in]	app_data	应用数据 blob，必须与密钥生成期间在 KM_TAG_APPLICATION_DATA 中提供的 blob（如果有）一致。
[out]	export_data	导出的密钥材料。调用方会承担所有权。

定义位于文件 keymaster2.h 的 213 行。

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

参数

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

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

定义位于文件 keymaster2.h 的 405 行。

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

定义位于文件 keymaster2.h 的 43 行。

生成密钥或密钥对，并返回密钥 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	密钥生成参数数组
[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。

定义位于文件 keymaster2.h 的第 112 行。

返回指定密钥的特征；如果 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。

参数

[in]	dev	Keymaster 设备结构。
[in]	key_blob	要从中检索特征的键。
[in]	client_id	客户 ID 数据，如果未关联任何 ID，则返回 null。
[in]	app_id	应用数据，如果未关联任何数据，则为 NULL。
[out]	特征	主要特征。不得为 NULL。调用方会承担内容的所有权，并且必须使用 keymaster_free_characteristics() 取消分配。

定义位于文件 keymaster2.h 的 139 行。

导入密钥或密钥对，并返回密钥 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_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA。

定义位于文件 keymaster2.h 的 186 行。

向通过 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()）。

定义位于文件 keymaster2.h 的 376 行。

升级旧密钥。密钥有两种方式会变为“旧”：Keymaster 可以升级到新版本，或者系统可以更新以使操作系统版本和/或补丁级别失效。无论是哪种情况，尝试使用旧密钥都会导致密钥管理器返回 KM_ERROR_KEY_REQUIRES_UPGRADE。然后，应调用此方法来升级密钥。

参数

[in]	dev	Keymaster 设备结构。
[in]	key_to_upgrade	要升级的 Keymaster 密钥。
[in]	upgrade_params	完成升级所需的参数。具体而言，如果为密钥定义了 KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA，则它们是必需的。
[out]	upgraded_key	升级后的密钥 blob。

定义位于文件 keymaster2.h 的 260 行。