文章目录
🌺概要
#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);
🌻描述
本文档主要面向提供程序作者。有关详细信息，请参阅提供程序。
密钥交换（OSSL_OP_KEYEXCH）操作使提供程序能够实现密钥交换算法，并通过EVP_PKEY_derive和其他相关功能将其提供给应用程序。
这里提到的所有"函数"都作为函数指针在libcrypto和OSSL_DISPATCH数组中的提供程序之间传递，通过由提供程序的**provider_query_operation（）**函数返回的OSSL_ALGORITHM数组（参见提供程序-base中的"提供程序函数"）。
所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"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数组由 openssl-core_dispatch.h 中作为宏提供的数字编制索引，如下所示：
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） 操作生成、加载或导入密钥。有关详细信息，请参阅 提供程序-keymgmt。
🌹上下文管理功能
OSSL_FUNC_keyexch_newctx（） 应创建并返回指向提供程序端结构的指针，以便在密钥交换操作期间保存上下文信息。指向此上下文的指针将在许多其他密钥交换操作函数调用中传递回去。参数 provctx 是在提供程序初始化期间生成的提供程序上下文（参见 提供程序）。
OSSL_FUNC_keyexch_freectx（） 在 ctx 参数中传递一个指向提供程序端密钥交换上下文的指针。此函数应释放与该上下文关联的任何资源。
OSSL_FUNC_keyexch_dupctx（） 应在 ctx 参数中复制提供程序端密钥交换上下文，并返回重复的副本。
🌷共享密钥派生函数
OSSL_FUNC_keyexch_init（） 初始化密钥交换操作，给定 ctx 参数中的提供程序端密钥交换上下文，以及 provkey 参数中指向提供程序密钥对象的指针。参数（如果不是 NULL）应以类似于使用 OSSL_FUNC_keyexch_set_params（） 的方式在上下文中设置。密钥对象应已于先前使用密钥管理 （OSSL_OP_KEYMGMT） 操作生成、加载或导入到提供程序中（请参阅提供程序-keymgmt）。
调用 OSSL_FUNC_keyexch_set_peer（） 以提供在派生共享密钥时要使用的对等方公钥（在 provkey 参数中）。它还会在 ctx 参数中传递先前初始化的密钥交换上下文。密钥对象应已于先前使用密钥管理 （OSSL_OP_KEYMGMT） 操作生成、加载或导入到提供程序中（请参阅提供程序-keymgmt）。
OSSL_FUNC_keyexch_derive（） 通过派生共享密钥来执行实际的密钥交换本身。以前初始化的密钥交换上下文在 ctx 参数中传递。派生的机密应写入不应超过字节的位置机密。共享机密的长度应写入 *secretlen。如果机密为 NULL，则共享机密的最大长度应写入 *secretlen。
🌼密钥交换参数函数
OSSL_FUNC_keyexch_set_ctx_params（） 将与给定提供程序端密钥交换上下文 ctx 关联的密钥交换参数设置为params，请参阅"公用密钥交换参数"。任何参数设置都是对以前设置的任何参数设置的附加设置。为params传递 NULL 应返回 true。
OSSL_FUNC_keyexch_get_ctx_params（） 获取与给定提供程序端密钥交换上下文 ctx 关联的密钥交换参数到params中，请参阅"公用密钥交换参数"。为params传递 NULL 应返回 true。
OSSL_FUNC_keyexch_settable_ctx_params（） 生成一个常量OSSL_PARAM数组，用于描述可设置的参数，即可与 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数组，即可由 OP_signature_get_ctx_params（） 处理的参数。如果存在 OSSL_FUNC_keyexch_gettable_ctx_params（），则还必须存在OSSL_FUNC_keyexch_get_ctx_params（），反之亦然。请参阅 OSSL_PARAM 以使用 OSSL_PARAM 作为参数描述符。
注意，并不是所有可设置的参数都是可获取的，反之亦然。
🌸常用密钥交换参数
有关 OSSL_FUNC_keyexch_set_ctx_params（） 和 OSSL_FUNC_keyexch_get_ctx_params（） 函数使用的参数结构的更多详细信息，请参见 OSSL_PARAM。
内置密钥交换算法当前识别的常见参数如下。
“pad” (OSSL_EXCHANGE_PARAM_PAD) < unsigned integer >
设置关联的密钥交换 ctx 的填充模式。将值设置为 1 将打开填充。将值设置为 0 将关闭填充。如果填充处于关闭状态，则派生的共享机密可能小于最大可能的机密大小。如果填充处于打开状态，则派生的共享机密将在必要时将其第一个字节填充为 0，以使共享机密的大小与最大可能的机密大小相同。
💐返回值
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数组。
