keymaster1_device 结构参考

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

在文件keymaster1.h的第531行定义。

向 keymaster 使用的 RNG 添加熵。保证通过这种方法添加的熵不是唯一使用的熵源，并且混合函数必须是安全的，从某种意义上说，如果 RNG 是用攻击者无法预测的任何数据（来自任何来源）播种（或控制），则 RNG 输出与随机无法区分。因此，如果来自任何来源的熵是好的，那么输出就会是好的。

参数

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

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

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

这已被弃用。在 keymaster_module 初始化中使用新的“module_api_version”和“hal_api_version”字段。

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

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

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

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

已弃用：

删除硬件密钥库中的所有密钥。当密钥库完全重置时使用。

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

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

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

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

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

参数

[在]

开发者

keymaster 设备结构。

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

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

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

参数

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

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

已弃用：

删除与密钥 Blob 关联的密钥对。

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

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

在文件keymaster1.h的第88行定义。

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

参数

[在]	开发者	keymaster 设备结构。
[在]	导出格式	用于导出密钥的格式。
[在]	key_to_export	出口的关键。
[出去]	导出数据	导出的密钥材料。调用者承担所有权。
[出去]	导出数据长度	export_data的长度。

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

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

参数

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

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

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

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

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

生成密钥或密钥对，返回密钥 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行定义。

已弃用：

生成公钥和私钥。返回的密钥块是不透明的，必须随后提供用于签名和验证。

返回：0 表示成功或错误代码小于 0。

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

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

已弃用：

获取密钥对的公钥部分。公钥必须是 X.509 格式（Java 标准）编码的字节数组。

返回：成功时返回 0 或小于 0 的错误代码。出错时，不应分配 x509_data。

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

获取支持的算法。

参数

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

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

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

参数

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

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

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

参数

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

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

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

参数

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

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

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

参数

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

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

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

参数

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

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

导入密钥或密钥对，返回密钥 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行的定义。

已弃用：

导入公钥和私钥对。导入的密钥将采用带有 DER 编码（Java 标准）的 PKCS#8 格式。返回的密钥块是不透明的，随后将提供给签名和验证。

返回：0 表示成功或错误代码小于 0。

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

已弃用：

使用之前生成的密钥块对数据进行签名。这可以使用非对称密钥或秘密密钥。

返回：0 表示成功或错误代码小于 0。

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

向以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行的定义。

已弃用：

验证使用密钥块签名的数据。这可以使用非对称密钥或秘密密钥。

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

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