OpenSSL

密码学和 SSL/TLS 工具包

provider-keymgmt

名称

provider-keymgmt - KEYMGMT 库 <-> 提供程序函数

概要

#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(void *keydata, int selection, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection);
const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types_ex(void *provctx, int selection);
int OSSL_FUNC_keymgmt_export(void *keydata, int selection,
                             OSSL_CALLBACK *param_cb, void *cbarg);
const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection);
const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types_ex(void *provctx, 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(3) 数组中，通过 OSSL_ALGORITHM(3) 数组，这些数组由提供程序的 provider_query_operation() 函数返回（参见 provider-base(7) 中的“提供程序函数”）。

所有这些“函数”都有一个相应的函数类型定义，名为 OSSL_FUNC_{name}_fn，以及一个从 OSSL_DISPATCH(3) 元素中检索函数指针的辅助函数，名为 OSSL_FUNC_{name}。例如，“函数”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(3) 数组按数字索引，这些数字作为宏在 openssl-core_dispatch.h(7) 中提供，如下所示

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_import_types_ex      OSSL_FUNC_KEYMGMT_IMPORT_TYPES_EX
OSSL_FUNC_keymgmt_export               OSSL_FUNC_KEYMGMT_EXPORT
OSSL_FUNC_keymgmt_export_types         OSSL_FUNC_KEYMGMT_EXPORT_TYPES
OSSL_FUNC_keymgmt_export_types_ex      OSSL_FUNC_KEYMGMT_EXPORT_TYPES_EX

OSSL_FUNC_keymgmt_dup                  OSSL_FUNC_KEYMGMT_DUP

密钥对象

密钥对象是用于非对称密钥的数据集合，在本手册中表示为 keydata。

密钥对象的准确内容由提供程序定义，并假设同一个提供程序中的不同操作使用完全相同的结构来表示此数据集合，以便例如，使用我们在此处记录的 KEYMGMT 接口创建的密钥对象可以原样传递给其他提供程序操作，例如 OP_signature_sign_init()（参见 provider-signature(7)）。

对于某些 KEYMGMT 函数，可以选择特定数据子集进行处理，由 selection 指示器中的位控制。这些位是

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_match() 的实现可以选择不比较私钥部分，因为它已比较了公钥部分，因为一半的匹配意味着另一半的匹配。

构造和销毁函数

OSSL_FUNC_keymgmt_new() 应该创建一个提供程序端密钥对象。提供程序上下文 provctx 被传递，可以包含在密钥对象中，但这并不是强制性的。

OSSL_FUNC_keymgmt_free() 应该释放传递的 keydata。

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() 应该创建密钥对象生成上下文并用 selections 初始化它，这将决定要生成的密钥对象应该获得哪种内容。如果 params 不为 NULL，则应以类似于使用 OSSL_FUNC_keymgmt_set_params() 的方式将其设置在上下文中。

OSSL_FUNC_keymgmt_gen_set_template() 应该将 template 添加到上下文 genctx 中。假设 template 是使用同一个 KEYMGMT 构造的密钥对象，并且实现从中选择的任何内容都可以用作要生成的密钥对象的模板。通常，DSA 或 DH 密钥的生成将从此 template 中获取域参数。

OSSL_FUNC_keymgmt_gen_set_params() 应该在密钥对象生成上下文 genctx 中设置来自 params 的附加参数。

OSSL_FUNC_keymgmt_gen_settable_params() 应该返回描述符 OSSL_PARAM(3) 的常量数组，用于 OSSL_FUNC_keymgmt_gen_set_params() 可以处理的参数。

OSSL_FUNC_keymgmt_gen() 应该执行密钥对象生成本身，并返回结果。回调 cb 应该在定期间隔内被调用，并提供有关密钥对象生成进度的指示。

OSSL_FUNC_keymgmt_gen_cleanup() 应该清理并释放密钥对象生成上下文 genctx

OSSL_FUNC_keymgmt_load() 基于 reference 对象（大小为 reference_sz 字节）创建一个提供程序端密钥对象，只有提供程序知道如何解释它，但它可能来自其他操作。在提供程序之外，此引用只是一个字节数组。

OSSL_FUNC_keymgmt_new()、OSSL_FUNC_keymgmt_gen() 和 OSSL_FUNC_keymgmt_load() 中至少必须有一个，以及 OSSL_FUNC_keymgmt_free() 和 OSSL_FUNC_keymgmt_has()。此外，如果存在 OSSL_FUNC_keymgmt_gen()，则 OSSL_FUNC_keymgmt_gen_init() 和 OSSL_FUNC_keymgmt_gen_cleanup() 也必须存在。

密钥对象信息函数

OSSL_FUNC_keymgmt_get_params() 应该提取与给定的 keydata 相关联的信息数据，参见 "通用信息参数"。

OSSL_FUNC_keymgmt_gettable_params() 应该返回描述符 OSSL_PARAM(3) 的常量数组，用于 OSSL_FUNC_keymgmt_get_params() 可以处理的参数。

如果存在 OSSL_FUNC_keymgmt_gettable_params()，则 OSSL_FUNC_keymgmt_get_params() 也必须存在，反之亦然。

OSSL_FUNC_keymgmt_set_params() 应该更新与给定的 keydata 相关联的信息数据，参见 "通用信息参数"。

OSSL_FUNC_keymgmt_settable_params() 应该返回描述符 OSSL_PARAM(3) 的常量数组，用于 OSSL_FUNC_keymgmt_set_params() 可以处理的参数。

如果存在 OSSL_FUNC_keymgmt_settable_params()，则 OSSL_FUNC_keymgmt_set_params() 也必须存在，反之亦然。

密钥对象检查函数

OSSL_FUNC_keymgmt_query_operation_name() 应该返回操作 operation_id 支持的算法的名称。这类似于 provider_query_operation()（参见 provider-base(7)），但仅用作建议。如果此函数不存在或返回 NULL，则调用者可以自由地假设存在来自同一个提供程序的算法，其名称与用于获取 keymgmt 的算法相同，并尝试使用它。

OSSL_FUNC_keymgmt_has() 应该检查给定的 keydata 是否包含 selector 指示的数据子集。几个选择器位的组合必须考虑所有这些子集，而不仅仅是一个。但是，实现可以自由地将空数据子集视为有效子集。对于某些选择没有意义的算法，例如 RSA 密钥的 OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS，该函数应该只返回 1，因为所选子集实际上并没有丢失在密钥中。

OSSL_FUNC_keymgmt_validate() 应该检查 keydata 是否包含 selection 指示的有效数据子集。某些数据子集的组合选择可能会导致组合数据的验证。例如，OSSL_KEYMGMT_SELECT_PRIVATE_KEY 和 OSSL_KEYMGMT_SELECT_PUBLIC_KEY（或简称为 OSSL_KEYMGMT_SELECT_KEYPAIR）的组合预计将检查 keydata 的成对一致性是否有效。checktype 参数控制对数据子集执行什么类型的检查。定义了两种类型的检查：OSSL_KEYMGMT_VALIDATE_FULL_CHECK 和 OSSL_KEYMGMT_VALIDATE_QUICK_CHECK。完整检查与快速检查相比执行多少检查的解释是特定于密钥类型的。一些提供程序可能在完整检查和快速检查之间没有区别。对于某些选择没有意义的算法，例如 RSA 密钥的 OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS，该函数应该只返回 1，因为没有要验证的选择。

OSSL_FUNC_keymgmt_match() 应该检查 keydata1 和 keydata2 中 selection 指示的数据子集是否匹配。假设调用者已确保 keydata1 和 keydata2 均由此函数的实现拥有。

密钥对象导入、导出和复制函数

OSSL_FUNC_keymgmt_import() 应该将 selection 指示的数据导入 keydata，其值取自 OSSL_PARAM(3) 数组 params。

OSSL_FUNC_keymgmt_export() 应该从 keydata 中提取 selection 指示的值，使用它们创建一个 OSSL_PARAM(3) 数组，并使用该数组以及给定的 cbarg 调用 param_cb。

OSSL_FUNC_keymgmt_import_types() 和 OSSL_FUNC_keymgmt_import_types_ex() 应该返回描述符 OSSL_PARAM(3) 的常量数组，用于 selection 指示的数据，用于 OSSL_FUNC_keymgmt_import() 可以处理的参数。必须实现 OSSL_FUNC_keymgmt_import_types() 或 OSSL_FUNC_keymgmt_import_types_ex()，如果实现了 OSSL_FUNC_keymgmt_import_types_ex()，则它比 OSSL_FUNC_keymgmt_import_types() 更可取。应该与 OpenSSL 3.0 或 3.1 向后兼容的提供程序必须继续实现 OSSL_FUNC_keymgmt_import_types()。

OSSL_FUNC_keymgmt_export_types() 和 OSSL_FUNC_keymgmt_export_types_ex() 应该返回描述符 OSSL_PARAM(3) 的常量数组，用于 selection 指示的数据，OSSL_FUNC_keymgmt_export() 回调可以预期接收这些数据。必须实现 OSSL_FUNC_keymgmt_export_types() 或 OSSL_FUNC_keymgmt_export_types_ex()，如果实现了 OSSL_FUNC_keymgmt_export_types_ex()，则它比 OSSL_FUNC_keymgmt_export_types() 更可取。应该与 OpenSSL 3.0 或 3.1 向后兼容的提供程序必须继续实现 OSSL_FUNC_keymgmt_export_types()。

OSSL_FUNC_keymgmt_dup() 应该复制 selection 指示的数据子集或整个密钥数据 keydata_from，并使用该数据创建一个新的提供程序端密钥对象。

通用信息参数

有关参数结构的更多详细信息，请参见 OSSL_PARAM(3)。

目前所有内置 keymgmt 算法都识别的通用信息参数如下

"bits" (OSSL_PKEY_PARAM_BITS) <integer>

该值应该是密钥所属的密码系统的密码长度，以位为单位。密码长度的定义特定于密钥密码系统。

"max-size" (OSSL_PKEY_PARAM_MAX_SIZE) <integer>

该值应为调用者为安全存储签名（在provider-signature(7)中称为sig）、非对称加密/解密的结果（在provider-asym_cipher(7)中称为out）、派生密钥（在provider-keyexch(7)中称为secret）以及类似数据而应分配的最大大小。

提供者需要实现此参数才能正确支持各种用例，例如 CMS 签名。

由于 EVP_KEYMGMT 方法始终与另一种方法（签名、非对称密码、密钥交换等）紧密绑定，并且必须属于同一个提供者，因此此数字只需要与同一提供者中其他部分处理的尺寸同步即可。

"security-bits" (OSSL_PKEY_PARAM_SECURITY_BITS) <integer>

该值应为给定密钥的安全位数。安全位定义在 SP800-57 中。

"mandatory-digest" (OSSL_PKEY_PARAM_MANDATORY_DIGEST) <UTF8 string>

如果使用来自此 keymgmt 的密钥执行签名操作需要强制执行摘要，则此参数应获取其名称作为值。

当 EVP_PKEY_get_default_digest_name(3) 查询此参数且它由实现填充时，其返回值将为 2。

如果 keymgmt 实现填充了值 "" 或 "UNDEF"，EVP_PKEY_get_default_digest_name(3) 会将字符串 "UNDEF" 放入其参数 mdname 中。这表示在相应的签名操作中不应指定任何摘要。

"default-digest" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>

如果使用来自此 keymgmt 的密钥执行签名操作需要默认执行摘要，则此参数应获取其名称作为值。

当 EVP_PKEY_get_default_digest_name(3) 查询此参数且它由实现填充时，其返回值将为 1。请注意，如果 OSSL_PKEY_PARAM_MANDATORY_DIGEST 也得到响应，EVP_PKEY_get_default_digest_name(3) 会忽略对此参数的响应。

如果 keymgmt 实现填充了值 "" 或 "UNDEF"，EVP_PKEY_get_default_digest_name(3) 会将字符串 "UNDEF" 放入其参数 mdname 中。这表示在相应的签名操作中不必指定任何摘要，但可以作为选项指定。

返回值

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() 应该在给定的 keydata 中包含所有选定的数据子集时返回 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_import_types_ex()、OSSL_FUNC_keymgmt_export_types()、OSSL_FUNC_keymgmt_export_types_ex() 应该始终返回一个常数 OSSL_PARAM(3) 数组。

参见

EVP_PKEY_get_size(3)、EVP_PKEY_get_bits(3)、EVP_PKEY_get_security_bits(3)、provider(7)、EVP_PKEY-X25519(7)、EVP_PKEY-X448(7)、EVP_PKEY-ED25519(7)、EVP_PKEY-ED448(7)、EVP_PKEY-EC(7)、EVP_PKEY-RSA(7)、EVP_PKEY-DSA(7)、EVP_PKEY-DH(7)

历史

KEYMGMT 接口在 OpenSSL 3.0 中引入。

函数 OSSL_FUNC_keymgmt_import_types_ex() 和 OSSL_FUNC_keymgmt_export_types_ex() 是在 OpenSSL 3.2 中添加的。

版权所有 2019-2024 The OpenSSL Project Authors。保留所有权利。

根据 Apache 许可证 2.0（“许可证”）授权。除遵守许可证外，您不得使用此文件。您可以在源代码分发中的 LICENSE 文件或 https://www.openssl.org/source/license.html 中获取副本。