/docs/man3.3/man7/provider-keyexch.html

provider-keyexch

名称

provider-keyexch - 密钥交换库 <-> 提供程序函数

概要

#include <openssl/core_dispatch.h>
#include <openssl/core_names.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.
 */

/* Context management */
void *OSSL_FUNC_keyexch_newctx(void *provctx);
void OSSL_FUNC_keyexch_freectx(void *ctx);
void *OSSL_FUNC_keyexch_dupctx(void *ctx);

/* Shared secret derivation */
int OSSL_FUNC_keyexch_init(void *ctx, void *provkey,
                           const OSSL_PARAM params[]);
int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey);
int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen,
                             size_t outlen);

/* Key Exchange parameters */
int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void *ctx,
                                                        void *provctx);
int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void *ctx,
                                                        void *provctx);

描述

本文档主要面向提供程序作者。有关更多信息，请参阅 provider(7)。

密钥交换 (OSSL_OP_KEYEXCH) 操作使提供程序能够实现密钥交换算法，并通过 EVP_PKEY_derive(3) 和其他相关函数将其提供给应用程序。

此处提到的所有“函数”都作为函数指针在 libcrypto 和提供程序之间传递，位于 OSSL_DISPATCH(3) 数组中，通过 OSSL_ALGORITHM(3) 数组，这些数组由提供程序的 provider_query_operation() 函数返回（请参阅 provider-base(7)中的“提供程序函数”）。

所有这些“函数”都有一个相应的函数类型定义，名为 OSSL_FUNC_{name}_fn，以及一个辅助函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH(3) 元素中检索函数指针。例如，“函数”OSSL_FUNC_keyexch_newctx() 具有以下内容

typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_keyexch_newctx_fn
    OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH(3) 数组由数字索引，这些数字作为宏在 openssl-core_dispatch.h(7) 中提供，如下所示

OSSL_FUNC_keyexch_newctx                OSSL_FUNC_KEYEXCH_NEWCTX
OSSL_FUNC_keyexch_freectx               OSSL_FUNC_KEYEXCH_FREECTX
OSSL_FUNC_keyexch_dupctx                OSSL_FUNC_KEYEXCH_DUPCTX

OSSL_FUNC_keyexch_init                  OSSL_FUNC_KEYEXCH_INIT
OSSL_FUNC_keyexch_set_peer              OSSL_FUNC_KEYEXCH_SET_PEER
OSSL_FUNC_keyexch_derive                OSSL_FUNC_KEYEXCH_DERIVE

OSSL_FUNC_keyexch_set_ctx_params        OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS
OSSL_FUNC_keyexch_settable_ctx_params   OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS
OSSL_FUNC_keyexch_get_ctx_params        OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS
OSSL_FUNC_keyexch_gettable_ctx_params   OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS

密钥交换算法实现可能不会实现所有这些函数。为了成为一组一致的函数，提供程序必须实现 OSSL_FUNC_keyexch_newctx、OSSL_FUNC_keyexch_freectx、OSSL_FUNC_keyexch_init 和 OSSL_FUNC_keyexch_derive。所有其他函数都是可选的。

密钥交换算法还必须实现某种机制来通过密钥管理 (OSSL_OP_KEYMGMT) 操作生成、加载或导入密钥。有关更多详细信息，请参阅 provider-keymgmt(7)。

上下文管理函数

OSSL_FUNC_keyexch_newctx() 应该创建并返回指向提供程序端结构的指针，用于在密钥交换操作期间保存上下文信息。指向此上下文的指针将在许多其他密钥交换操作函数调用中传递回。参数 provctx 是在提供程序初始化期间生成的提供程序上下文（请参阅 provider(7)）。

OSSL_FUNC_keyexch_freectx() 会将指向 ctx 参数中提供程序端密钥交换上下文的指针传递给它。此函数应释放与该上下文关联的任何资源。

OSSL_FUNC_keyexch_dupctx() 应复制 ctx 参数中的提供程序端密钥交换上下文，并返回副本。

共享密钥派生函数

OSSL_FUNC_keyexch_init() 初始化给定的密钥交换操作，其中 ctx 参数中包含提供程序端密钥交换上下文，provkey 参数中包含指向提供程序密钥对象的指针。如果 params 不为 NULL，则应以类似于使用 OSSL_FUNC_keyexch_set_params() 的方式将其设置为上下文。密钥对象应已使用密钥管理 (OSSL_OP_KEYMGMT) 操作（请参阅 provider-keymgmt(7)>）先前在提供程序中生成、加载或导入。

OSSL_FUNC_keyexch_set_peer() 被调用以提供对等方的公钥（在 provkey 参数中），以便在派生共享密钥时使用。它还将 ctx 参数中先前初始化的密钥交换上下文传递给它。密钥对象应已使用密钥管理 (OSSL_OP_KEYMGMT) 操作（请参阅 provider-keymgmt(7)>）先前在提供程序中生成、加载或导入。

OSSL_FUNC_keyexch_derive() 通过派生共享密钥来执行实际的密钥交换本身。ctx 参数中传递了先前初始化的密钥交换上下文。派生的密钥应写入 secret 位置，该位置不应超过 outlen 字节。共享密钥的长度应写入 *secretlen。如果 secret 为 NULL，则应将共享密钥的最大长度写入 *secretlen。

密钥交换参数函数

OSSL_FUNC_keyexch_set_ctx_params() 将与给定提供程序端密钥交换上下文 ctx 关联的密钥交换参数设置为 params，请参阅 “常见密钥交换参数”。任何参数设置都将添加到先前设置的任何参数。将 NULL 传递给 params 应返回 true。

OSSL_FUNC_keyexch_get_ctx_params() 将与给定提供程序端密钥交换上下文 ctx 关联的密钥交换参数获取到 params 中，请参阅 “常见密钥交换参数”。将 NULL 传递给 params 应返回 true。

OSSL_FUNC_keyexch_settable_ctx_params() 生成一个描述可设置参数的常量 OSSL_PARAM(3) 数组，即可与 OP_signature_set_ctx_params() 一起使用的参数。如果存在 OSSL_FUNC_keyexch_settable_ctx_params()，则 OSSL_FUNC_keyexch_set_ctx_params() 也必须存在，反之亦然。类似地，OSSL_FUNC_keyexch_gettable_ctx_params() 生成一个描述可获取参数的常量 OSSL_PARAM(3) 数组，即可以由 OP_signature_get_ctx_params() 处理的参数。如果存在 OSSL_FUNC_keyexch_gettable_ctx_params()，则 OSSL_FUNC_keyexch_get_ctx_params() 也必须存在，反之亦然。

请注意，并非所有可设置参数也都是可获取的，反之亦然。

常见密钥交换参数

有关 OSSL_FUNC_keyexch_set_ctx_params() 和 OSSL_FUNC_keyexch_get_ctx_params() 函数使用的参数结构的更多详细信息，请参阅 OSSL_PARAM(3)。

内置密钥交换算法当前识别的常见参数如下。

"kdf-type" (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 字符串>: 设置或获取要在关联的密钥交换 ctx 中应用的密钥派生函数类型。
"kdf-digest" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 字符串>: 设置或获取要作为与给定密钥交换 ctx 关联的密钥派生函数一部分使用的摘要算法。
"kdf-digest-props" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 字符串>: 设置要用于查找为与给定密钥交换 ctx 关联的密钥派生函数选择的摘要算法的实现的属性。
"kdf-outlen" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <无符号整数>: 设置或获取与给定密钥交换 ctx 关联的所选密钥派生函数输出的所需大小。"kdf-outlen" 参数的长度不应超过 size_t 的长度。
"kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <八位字节串>: 设置要作为与给定密钥交换 ctx 关联的所选密钥派生函数一部分使用的用户密钥材料。
"kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <八位字节串指针>: 获取指向要作为与给定密钥交换 ctx 关联的所选密钥派生函数一部分使用的用户密钥材料的指针。提供程序通常不需要支持此可获取参数，因为其唯一目的是支持已弃用的 EVP_PKEY_CTX_get0_ecdh_kdf_ukm() 和 EVP_PKEY_CTX_get0_dh_kdf_ukm() 函数的功能。

返回值

OSSL_FUNC_keyexch_newctx() 和 OSSL_FUNC_keyexch_dupctx() 应返回新创建的提供程序端密钥交换上下文，或在失败时返回 NULL。

OSSL_FUNC_keyexch_init()、OSSL_FUNC_keyexch_set_peer()、OSSL_FUNC_keyexch_derive()、OSSL_FUNC_keyexch_set_params() 和 OSSL_FUNC_keyexch_get_params() 应在成功时返回 1，在错误时返回 0。

OSSL_FUNC_keyexch_settable_ctx_params() 和 OSSL_FUNC_keyexch_gettable_ctx_params() 应始终返回一个常量 OSSL_PARAM(3) 数组。

参见

provider(7)

历史

提供程序 KEYEXCH 接口是在 OpenSSL 3.0 中引入的。

版权

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