keymaster2_device 结构参考
#include < keymaster2.h >
详细说明
Keymaster2 设备定义
定义位于文件keymaster2.h第28行。
现场文档
| 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 输出与随机输出无法区分。因此，如果任何来源的熵良好，则输出也会良好。
- 参数
[在] 开发者 密钥主设备结构。 [在] 数据 要混合的随机数据。 [在] 数据长度 data长度。
文件keymaster2.h第74行的定义。
| 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 证书链，证明 keymaster 中存在key_to_attest （TODO(swillden)：更详细地描述证书内容）。该证书将包含 OID 1.3.6.1.4.1.11129.2.1.17 的扩展以及 <TODO:swillden – 在此处插入链接> 中定义的值，其中包含密钥描述。
- 参数
[在] 开发者 密钥主设备结构。 [在] 证明密钥 将为其生成证明证书的密钥主密钥。 [在] 证明参数 定义如何进行证明的参数。目前唯一的参数是 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 (* 开始)(const struct keymaster2_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。 [出去] 输出参数 输出参数。用于从操作初始化返回附加数据，特别是从生成 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。
文件keymaster2.h第332行的定义。
| 结构体hw_device_t公共 |
Keymaster设备的常用方法。这必须是 keymaster_device 的第一个成员，因为该结构的用户将在已知hw_device_t引用 keymaster_device的上下文中将 hw_device_t 强制转换为 keymaster_device 指针。
定义位于文件keymaster2.h第35行。
| keymaster_error_t (* 配置)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params) |
配置密钥管理器。该方法必须在设备打开后和使用前调用一次。它用于向密钥管理员提供 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行。
| keymaster_error_t (* delete_all_keys)(const struct keymaster2_device *dev) |
删除硬件密钥库中的所有密钥。当密钥库完全重置时使用。调用此函数后，将无法使用任何先前生成或导入的密钥 blob 进行任何操作。
该函数是可选的，如果未实现，则应设置为 NULL。
- 参数
[在] 开发者 密钥主设备结构。
定义位于文件keymaster2.h的第288行。
| keymaster_error_t (* delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key) |
删除与密钥 blob 关联的密钥或密钥对。调用此函数后，将无法使用该键进行任何其他操作。可以应用于来自外部信任根的密钥（在当前信任根下不可用的密钥）。
该函数是可选的，如果未实现，则应设置为 NULL。
- 参数
[在] 开发者 密钥主设备结构。 [在] 钥匙 要删除的密钥。
文件keymaster2.h第276行的定义。
| 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 创建的，并且满足密钥使用的所有要求（例如身份验证）时，才允许对称密钥导出。
- 参数
[在] 开发者 密钥主设备结构。 [在] 导出格式 用于导出密钥的格式。 [在] 导出密钥 导出的关键。 [在] 客户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 *输入，const keymaster_blob_t *签名， keymaster_key_param_set_t *out_params， keymaster_blob_t *输出） |
完成以begin()开始的加密操作并使operation_handle无效。
- 参数
[在] 开发者 密钥主设备结构。 [在] 操作句柄 begin()返回的操作句柄。该句柄将失效。 [在] 输入参数 操作的附加参数。对于 AEAD 模式，这用于指定 KM_TAG_ADDITIONAL_DATA，但前提是未向update()提供输入数据。 [在] 输入 根据调用begin()中建立的参数来处理数据。 finish()必须消耗所有提供的数据或返回 KM_ERROR_INVALID_INPUT_LENGTH。 [在] 签名 如果begin()调用中指定的目的是 KM_PURPOSE_VERIFY，则要验证的签名。 [出去] 输出 输出数据（如果有）。调用者承担所分配缓冲区的所有权。
如果正在完成的操作是签名验证或 AEAD 模式解密且验证失败，则finish()将返回 KM_ERROR_VERIFICATION_FAILED。
文件keymaster2.h第405行的定义。
| uint32_t 标志 |
请参阅keymaster_common.h中为 keymaster0_devices::flags 定义的标志。仅用于向后兼容； keymaster2 硬件设备必须将其设置为零。
定义位于文件keymaster2.h第43行。
| 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_算法；
- 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
- 参数
[在] 开发者 密钥主设备结构。 [在] 参数 密钥生成参数数组 [出去] 密钥块 返回生成的密钥。 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.h第112行的定义。
| 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 永远不会返回。
- 参数
[在] 开发者 密钥主设备结构。 [在] 密钥块 从中检索特征的关键。 [在] 客户ID 客户端 ID 数据，如果没有关联则为 NULL。 [在] 应用程序ID 应用程序数据，如果没有关联则为 NULL。 [出去] 特征 关键特征。不能为 NULL。调用者假定内容的所有权，并且必须使用keymaster_free_characteristics()取消分配。
定义位于文件keymaster2.h的第139行。
| 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_算法；
- 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_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA 永远不会返回。
文件keymaster2.h第186行的定义。
| 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 *输入，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() 它）。
文件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 密钥。 [在] 升级参数 完成升级所需的参数。特别是，如果为密钥定义了 KM_TAG_APPLICATION_ID 和 KM_TAG_APPLICATION_DATA，则将需要它们。 [出去] 升级密钥 升级后的密钥块。
文件keymaster2.h第260行的定义。
该结构的文档是从以下文件生成的：