文章目录
🌺概要
#include <openssl/core_dispatch.h>
/*
* None of these are actual functions, but are displayed like this for
* the function signatures for functions that are offered as function
* pointers in OSSL_DISPATCH arrays.
*/
/* Key object (keydata) creation and destruction */
void *OSSL_FUNC_keymgmt_new(void *provctx);
void OSSL_FUNC_keymgmt_free(void *keydata);
/* Generation, a more complex constructor */
void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection,
const OSSL_PARAM params[]);
int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template);
int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx,
void *provctx);
void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg);
void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx);
/* Key loading by object reference, also a constructor */
void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz);
/* Key object information */
int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void *provctx);
int OSSL_FUNC_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_settable_params(void *provctx);
/* Key object content checks */
int OSSL_FUNC_keymgmt_has(const void *keydata, int selection);
int OSSL_FUNC_keymgmt_match(const void *keydata1, const void *keydata2,
int selection);
/* Discovery of supported operations */
const char *OSSL_FUNC_keymgmt_query_operation_name(int operation_id);
/* Key object import and export functions */
int OSSL_FUNC_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection);
int OSSL_FUNC_keymgmt_export(int selection, void *keydata,
OSSL_CALLBACK *param_cb, void *cbarg);
const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection);
/* Key object duplication, a constructor */
void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection);
/* Key object validation */
int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype);
🌻描述
KEYMGMT 操作在 OpenSSL 库中没有太多的公共可见性，而是一个内部操作，旨在与使用私钥/公钥对的操作协同工作。
由于 KEYMGMT 操作与其协同处理的操作共享知识，因此它们必须属于同一提供程序。OpenSSL库将确保它们这样做。
KEYMGMT 操作的主要职责是保存 OpenSSL 库的提供程序端密钥数据，EVP_PKEY结构。
这里提到的所有"函数"都作为函数指针在libcrypto和OSSL_DISPATCH数组中的提供者之间传递，通过由提供者的**provider_query_operation（）**函数返回的OSSL_ALGORITHM数组。
所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"OSSL_FUNC_keymgmt_new（） 具有以下功能：
typedef void *(OSSL_FUNC_keymgmt_new_fn)(void *provctx);
static ossl_inline OSSL_FUNC_keymgmt_new_fn
OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf);
OSSL_DISPATCH数组由 openssl-core_dispatch.h中作为宏提供的数字编制索引，如下所示：
OSSL_FUNC_keymgmt_new OSSL_FUNC_KEYMGMT_NEW
OSSL_FUNC_keymgmt_free OSSL_FUNC_KEYMGMT_FREE
OSSL_FUNC_keymgmt_gen_init OSSL_FUNC_KEYMGMT_GEN_INIT
OSSL_FUNC_keymgmt_gen_set_template OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE
OSSL_FUNC_keymgmt_gen_set_params OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS
OSSL_FUNC_keymgmt_gen_settable_params OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS
OSSL_FUNC_keymgmt_gen OSSL_FUNC_KEYMGMT_GEN
OSSL_FUNC_keymgmt_gen_cleanup OSSL_FUNC_KEYMGMT_GEN_CLEANUP
OSSL_FUNC_keymgmt_load OSSL_FUNC_KEYMGMT_LOAD
OSSL_FUNC_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS
OSSL_FUNC_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
OSSL_FUNC_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS
OSSL_FUNC_keymgmt_settable_params OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS
OSSL_FUNC_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
OSSL_FUNC_keymgmt_has OSSL_FUNC_KEYMGMT_HAS
OSSL_FUNC_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE
OSSL_FUNC_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH
OSSL_FUNC_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT
OSSL_FUNC_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES
OSSL_FUNC_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT
OSSL_FUNC_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES
OSSL_FUNC_keymgmt_dup OSSL_FUNC_KEYMGMT_DUP
🌹密钥对象
密钥对象是非对称密钥的数据集合，在本手册中表示为密钥数据(keydata)。
密钥对象的确切内容由提供程序定义，并且假定一个和同一个提供程序中的不同操作使用完全相同的结构来表示此数据集合.例如，使用我们在这里记录的KEYMGMT接口创建的键对象可以按原样传递给其他提供程序操作， 例如 OP_signature_sign_init（） （参见提供程序-signature）。
使用某些KEYMGMT函数，可以选择要处理的特定数据子集，由选择指示器中的位控制。位为：
-
OSSL_KEYMGMT_SELECT_PRIVATE_KEY
指示应考虑密钥对象中的私钥数据。 -
OSSL_KEYMGMT_SELECT_PUBLIC_KEY
指示应考虑密钥对象中的公钥数据。 -
OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS
指示应考虑键对象中的域参数。 -
OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS
指示应考虑键对象中的其他参数。
其他参数是不符合任何其他分类的关键参数。换句话说，此特定选择器位用作最后的手段位存储桶选择器。
一些选择器位也已组合在一起，以便于使用：
-
OSSL_KEYMGMT_SELECT_ALL_PARAMETERS
指示应考虑所有密钥对象参数，而不管其更精细的分类如何。
这是OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS和OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS的结合。 -
OSSL_KEYMGMT_SELECT_KEYPAIR
指示应考虑密钥对象中的整个密钥对，即公钥和私钥的组合。
这是OSSL_KEYMGMT_SELECT_PRIVATE_KEY和OSSL_KEYMGMT_SELECT_PUBLIC_KEY的结合。 -
OSSL_KEYMGMT_SELECT_ALL
指示应考虑键对象中的所有内容。
这些位的确切解释或它们如何组合留给每个函数，您可以在其中指定选择器。
🌷构造和销毁函数
OSSL_FUNC_keymgmt_new（） 应创建提供程序端键对象。提供程序上下文 provctx 已传递，并且可以合并到键对象中，但这不是必需的。
OSSL_FUNC_keymgmt_free（） 应释放传递的密钥数据。
OSSL_FUNC_keymgmt_gen_init（）、OSSL_FUNC_keymgmt_gen_set_template（）、OSSL_FUNC_keymgmt_gen_set_params（）、OSSL_FUNC_keymgmt_gen_settable_params（）、OSSL_FUNC_keymgmt_gen（） 和 OSSL_FUNC_keymgmt_gen_cleanup（） 协同工作，作为更详细的基于上下文的密钥对象构造函数。
OSSL_FUNC_keymgmt_gen_init（） 应创建密钥对象生成上下文并使用选择对其进行初始化，这将确定要生成的密钥对象应获取的内容类型。参数（如果不是 NULL）应以类似于使用 OSSL_FUNC_keymgmt_set_params（） 的方式在上下文中设置。
OSSL_FUNC_keymgmt_gen_set_template（） 应将模板添加到上下文 genctx。该模板假定是使用相同的 KEYMGMT 构造的键对象，并且实现从中选择的内容可用作要生成的键对象的模板。通常，生成 DSA 或 DH 密钥将从此模板获取域参数。
OSSL_FUNC_keymgmt_gen_set_params（） 应该在密钥对象生成上下文 genctx 中设置参数。
OSSL_FUNC_keymgmt_gen_settable_params（） 应为 OSSL_FUNC_keymgmt_gen_set_params（） 可以处理的参数返回描述符OSSL_PARAM的常量数组。
OSSL_FUNC_keymgmt_gen（） 应自行执行密钥对象生成，并返回结果。应定期调用回调 cb，并指示密钥对象生成进度。
OSSL_FUNC_keymgmt_gen_cleanup（） 应该清理并释放密钥对象生成上下文 genctx
OSSL_FUNC_keymgmt_load（） 基于大小为 reference_sz 字节的引用对象创建提供程序端键对象，只有提供程序知道如何解释该对象，但该对象可能来自其他操作。在提供程序外部，此引用只是一个字节数组。
OSSL_FUNC_keymgmt_new（）、OSSL_FUNC_keymgmt_gen（） 和 OSSL_FUNC_keymgmt_load（） 中至少有一个是必需的，并且OSSL_FUNC_keymgmt_free（）。此外，如果存在 OSSL_FUNC_keymgmt_gen（），则还必须存在 OSSL_FUNC_keymgmt_gen_init（） 和 OSSL_FUNC_keymgmt_gen_cleanup（）。
🌼密钥对象信息函数
OSSL_FUNC_keymgmt_get_params（） 应提取与给定密钥数据相关联的信息数据，请参阅"通用信息参数"。
OSSL_FUNC_keymgmt_gettable_params（） 应为 OSSL_FUNC_keymgmt_get_params（） 可以处理的参数返回描述符OSSL_PARAM的常量数组。
如果存在 OSSL_FUNC_keymgmt_gettable_params（），则还必须存在OSSL_FUNC_keymgmt_get_params（），反之亦然。
OSSL_FUNC_keymgmt_set_params（） 应更新与给定密钥数据相关联的信息数据，请参阅"通用信息参数"。
OSSL_FUNC_keymgmt_settable_params（） 应为 OSSL_FUNC_keymgmt_set_params（） 可以处理的参数返回描述符OSSL_PARAM的常量数组。
如果存在 OSSL_FUNC_keymgmt_settable_params（），则还必须存在OSSL_FUNC_keymgmt_set_params（），反之亦然。
🌸密钥对象检查函数
OSSL_FUNC_keymgmt_query_operation_name（） 应返回操作operation_id受支持算法的名称。这类似于provider_query_operation（）（参见 提供程序-base），但仅用作通报。如果此函数不存在或返回 NULL，则调用方可以自由地假定存在来自同一提供程序的算法，该算法与用于获取 keymgmt 并尝试使用它的算法同名。
OSSL_FUNC_keymgmt_has（） 应检查给定的密钥数据是否包含选择器指示的数据子集。多个选择器位的组合必须考虑所有这些子集，而不仅仅是一个子集。但是，实现可以自由地将空的数据子集视为仍然是有效的子集。对于某些选择没有意义的算法，例如 rsa 密钥的OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS，函数应只返回 1，因为所选子集在密钥中并未真正丢失。
OSSL_FUNC_keymgmt_validate（） 应检查密钥数据是否包含选择所指示的有效数据子集。某些数据子集的组合选择可能会导致对组合数据的验证。例如，OSSL_KEYMGMT_SELECT_PRIVATE_KEY和OSSL_KEYMGMT_SELECT_PUBLIC_KEY（或简称OSSL_KEYMGMT_SELECT_KEYPAIR）的组合应检查密钥数据的成对一致性是否有效。checktype 参数控制对数据子集执行的检查类型。定义了两种类型的检查：OSSL_KEYMGMT_VALIDATE_FULL_CHECK检查和OSSL_KEYMGMT_VALIDATE_QUICK_CHECK检查。对完整检查与快速检查中执行的检查量的解释是特定于密钥类型的。某些提供商可能没有完整检查和快速检查之间的区别。对于某些选择没有意义的算法，例如 rsa 密钥的OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS，该函数应只返回 1，因为该选择没有任何要验证的内容。
OSSL_FUNC_keymgmt_match（） 应检查 keydata1 和 keydata2 中选择的数据子集是否匹配。假定调用方已确保 keydata1 和 keydata2 都归此函数的实现所有。
💐密钥对象导入、导出和复制功能
OSSL_FUNC_keymgmt_import（） 应将所选指示的数据导入到密钥数据中，其值取自OSSL_PARAM数组参数。
OSSL_FUNC_keymgmt_export（） 应从 keydata 中提取通过选择指示的值，使用它们创建一个OSSL_PARAM数组，并使用该数组以及给定的 cbarg 调用param_cb。
OSSL_FUNC_keymgmt_import_types（） 应返回一个描述符OSSL_PARAM的常量数组，用于选择指示的数据，用于OSSL_FUNC_keymgmt_import（） 可以处理的参数。
OSSL_FUNC_keymgmt_export_types（） 应返回一个常量描述符数组，OSSL_PARAM用于选择指示的数据，OSSL_FUNC_keymgmt_export（） 回调可以预期接收这些数据。
OSSL_FUNC_keymgmt_dup（） 应复制由选择指示的数据子集或keydata_from的整个密钥数据，并使用数据创建新的提供程序端密钥对象。
🍂常用信息参数
有关参数结构的更多详细信息，请参见 OSSL_PARAM。
目前所有内置keymgmt算法都能识别的常见信息参数如下：
-
“bits” (OSSL_PKEY_PARAM_BITS) < integer >
该值应为密钥所属的密码系统的加密长度（以位为单位）。加密长度的定义特定于密钥密码系统。 -
“max-size” (OSSL_PKEY_PARAM_MAX_SIZE) < integer >
该值应为调用方应分配的最大大小以安全存储签名（在提供程序-signature中称为 sig）、非对称加密/解密的结果（在提供程序-asym_cipher中输出）、密钥交换（提供程序-keyexch 中的机密和类似数据）。
由于EVP_KEYMGMT方法始终与另一种方法（签名、非对称密码、密钥交换等）紧密绑定，并且必须属于同一提供程序，因此此数字只需与同一提供程序的其余部分中处理的维度同步。 -
“security-bits” (OSSL_PKEY_PARAM_SECURITY_BITS) < integer >
该值应为给定密钥的安全位数。SP800-57 中定义了安全位。
🍁返回值
OSSL_FUNC_keymgmt_new（） 和 OSSL_FUNC_keymgmt_dup（） 应返回对新创建的提供程序端密钥对象的有效引用，或在失败时返回 NULL。
OSSL_FUNC_keymgmt_import（）、OSSL_FUNC_keymgmt_export（）、OSSL_FUNC_keymgmt_get_params（） 和 OSSL_FUNC_keymgmt_set_params（） 应返回 1 表示成功，或在错误时返回 0。
OSSL_FUNC_keymgmt_validate（） 在验证成功时应返回 1，在验证失败时应返回 0。
如果所有选定的数据子集都包含在给定的密钥数据中，则 OSSL_FUNC_keymgmt_has（） 应返回 1，否则应返回 0。
OSSL_FUNC_keymgmt_query_operation_name（） 应返回指向与请求操作匹配的字符串的指针，如果用于获取 keymgmt 的相同名称适用，则返回 NULL。
OSSL_FUNC_keymgmt_gettable_params（） 和 OSSL_FUNC_keymgmt_settable_params（） OSSL_FUNC_keymgmt_import_types（），OSSL_FUNC_keymgmt_export_types（） 应始终返回常量OSSL_PARAM数组。
