《OpenSSL3.0学习之十五提供程序-kem｜CSDN创作打卡》-CFANZ编程社区

文章目录

🌺概要

 #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_kem_newctx(void *provctx);
 void OSSL_FUNC_kem_freectx(void *ctx);
 void *OSSL_FUNC_kem_dupctx(void *ctx);
 
 /* Encapsulation */
 int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey, const char *name,
                                    const OSSL_PARAM params[]);
 int OSSL_FUNC_kem_encapsulate(void *ctx, unsigned char *out, size_t *outlen,
                               unsigned char *secret, size_t *secretlen);
 
 /* Decapsulation */
 int OSSL_FUNC_kem_decapsulate_init(void *ctx, void *provkey, const char *name);
 int OSSL_FUNC_kem_decapsulate(void *ctx, unsigned char *out, size_t *outlen,
                               const unsigned char *in, size_t inlen);
 
 /* KEM parameters */
 int OSSL_FUNC_kem_get_ctx_params(void *ctx, OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_kem_gettable_ctx_params(void *ctx, void *provctx);
 int OSSL_FUNC_kem_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_kem_settable_ctx_params(void *ctx, void *provctx);

🌻描述

本文档主要面向提供程序作者。有关详细信息，请参阅提供程序。

非对称 kem （OSSL_OP_KEM）操作使提供程序能够实现非对称 kem 算法，并通过 API 函数 EVP_PKEY_encapsulate、EVP_PKEY_decapsulate和其他相关函数将它们提供给应用程序。

这里提到的所有"函数"都作为函数指针在libcrypto和OSSL_DISPATCH数组中的提供程序之间传递，通过由提供者的**provider_query_operation（）**函数返回的OSSL_ALGORITHM数组（参见提供程序-base中的"提供程序函数"）。

所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"OSSL_FUNC_kem_newctx（）具有以下功能：

 typedef void *(OSSL_FUNC_kem_newctx_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_kem_newctx_fn
     OSSL_FUNC_kem_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH数组由 openssl-core_dispatch.h中作为宏提供的数字编制索引，如下所示：

 OSSL_FUNC_kem_newctx               OSSL_FUNC_KEM_NEWCTX
 OSSL_FUNC_kem_freectx              OSSL_FUNC_KEM_FREECTX
 OSSL_FUNC_kem_dupctx               OSSL_FUNC_KEM_DUPCTX

 OSSL_FUNC_kem_encapsulate_init     OSSL_FUNC_KEM_ENCAPSULATE_INIT
 OSSL_FUNC_kem_encapsulate          OSSL_FUNC_KEM_ENCAPSULATE

 OSSL_FUNC_kem_decapsulate_init     OSSL_FUNC_KEM_DECAPSULATE_INIT
 OSSL_FUNC_kem_decapsulate          OSSL_FUNC_KEM_DECAPSULATE

 OSSL_FUNC_kem_get_ctx_params       OSSL_FUNC_KEM_GET_CTX_PARAMS
 OSSL_FUNC_kem_gettable_ctx_params  OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS
 OSSL_FUNC_kem_set_ctx_params       OSSL_FUNC_KEM_SET_CTX_PARAMS
 OSSL_FUNC_kem_settable_ctx_params  OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS

非对称 kem 算法实现可能无法实现所有这些功能。为了成为一组一致的函数，提供程序必须实现OSSL_FUNC_kem_newctx和OSSL_FUNC_kem_freectx。它还必须同时实施OSSL_FUNC_kem_encapsulate_init和OSSL_FUNC_kem_encapsulate，或同时实施OSSL_FUNC_kem_decapsulate_init和OSSL_FUNC_kem_decapsulate。OSSL_FUNC_kem_get_ctx_params是可选的，但如果存在，那么必须有OSSL_FUNC_kem_gettable_ctx_params。同样，OSSL_FUNC_kem_set_ctx_params是可选的，但如果它存在，那么OSSL_FUNC_kem_settable_ctx_params也必须存在。

非对称 kem 算法还必须实现一些机制，以便通过密钥管理（OSSL_OP_KEYMGMT）操作生成、加载或导入密钥。有关详细信息，请参阅提供程序-keymgmt。

🌹上下文管理功能

OSSL_FUNC_kem_newctx（）应创建并返回指向提供程序端结构的指针，以便在非对称 kem 操作期间保存上下文信息。指向此上下文的指针将在许多其他非对称 kem 操作函数调用中传递回去。参数 provctx 是在提供程序初始化期间生成的提供程序上下文（参见提供程序）。

OSSL_FUNC_kem_freectx（）在 ctx 参数中传递一个指向提供程序端非对称 kem 上下文的指针。此函数应释放与该上下文关联的任何资源。

OSSL_FUNC_kem_dupctx（）应在 ctx 参数中复制提供程序端非对称 kem 上下文，并返回重复的副本。

🌷非对称密钥封装函数

OSSL_FUNC_kem_encapsulate_init（）初始化非对称封装的上下文，给定 ctx 参数中的提供程序端非对称 kem 上下文、provkey 参数中指向提供程序键对象的指针以及算法的名称。参数（如果不是 NULL），则应以类似于使用 OSSL_FUNC_kem_set_ctx_params（）的方式在上下文中设置。键对象应已于先前使用密钥管理（OSSL_OP_KEYMGMT）操作生成、加载或导入到提供程序中（请参阅提供程序-keymgmt)。

OSSL_FUNC_kem_encapsulate（）执行实际的封装本身。在 ctx 参数中传递先前初始化的非对称 kem 上下文。除非 out 为 NULL，否则将在内部生成要封装的数据，并将其返回到 secret 参数所指向的缓冲区中，并且封装的数据也应写入 out 参数所指向的位置。封装数据的长度应写入 *outlen，生成的密钥的长度应写入 *secretlen。

如果 out 为 NULL，则封装数据的最大长度应写入 *outlen，生成的密钥的最大长度应写入 *secretlen。

🌼解封函数

OSSL_FUNC_kem_decapsulate_init（）初始化非对称解封装的上下文，给定 ctx 参数中的提供程序端非对称 kem 上下文、provkey 参数中指向提供程序密钥对象的指针以及算法的名称。密钥对象应已于先前使用密钥管理（OSSL_OP_KEYMGMT）操作生成、加载或导入到提供程序中（请参阅提供程序-keymgmt)。

OSSL_FUNC_kem_decapsulate（）执行实际的解封本身。在 ctx 参数中传递先前初始化的非对称 kem 上下文。要解封的数据由 in 参数指向，该参数的长度为 inlen 字节。除非 out 为 NULL，否则解封的数据应写入 out 参数所指向的位置。解封数据的长度应写入 *outlen。如果 out 为 NULL，则解封数据的最大长度应写入 *outlen。

🌸非对称密钥封装参数

有关 OSSL_FUNC_kem_get_ctx_params（）和OSSL_FUNC_kem_set_ctx_params（）函数使用的参数结构的更多详细信息，请参见OSSL_PARAM。

OSSL_FUNC_kem_get_ctx_params（）获取与给定提供者端非对称 kem 上下文 ctx 关联的非对称 kem 参数，并将它们存储在参数中。为参数传递 NULL 应返回 true。

OSSL_FUNC_kem_set_ctx_params（）将与给定提供者端非对称 kem 上下文 ctx 关联的非对称 kem 参数设置为参数。任何参数设置都是对以前设置的任何参数设置的附加设置。为参数传递 NULL 应返回 true。

内置的非对称 kem 算法目前无法识别任何参数。

OSSL_FUNC_kem_gettable_ctx_params（）和 OSSL_FUNC_kem_settable_ctx_params（）得到一个常量OSSL_PARAM数组，该数组描述了可获取参数和可设置参数，即可以分别与 OSSL_FUNC_kem_get_ctx_params（）和 OSSL_FUNC_kem_set_ctx_params（）一起使用的参数。请参阅OSSL_PARAM以使用OSSL_PARAM作为参数描述符。