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

provider-kem

名称

provider-kem - kem库 <-> 提供程序函数

摘要

#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 OSSL_PARAM params[]);
int OSSL_FUNC_kem_auth_encapsulate_init(void *ctx, void *provkey,
                                        void *provauthkey,
                                        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);
int OSSL_FUNC_kem_auth_decapsulate_init(void *ctx, void *provkey,
                                        void *provauthkey,
                                        const OSSL_PARAM params[]);
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);

描述

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

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

此处提到的所有“函数”都作为函数指针在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_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(3) 数组由数字索引，这些数字作为宏提供在 openssl-core_dispatch.h(7) 中，如下所示：

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_auth_encapsulate_init OSSL_FUNC_KEM_AUTH_ENCAPSULATE_INIT
OSSL_FUNC_kem_encapsulate           OSSL_FUNC_KEM_ENCAPSULATE

OSSL_FUNC_kem_decapsulate_init      OSSL_FUNC_KEM_DECAPSULATE_INIT
OSSL_FUNC_kem_auth_decapsulate_init OSSL_FUNC_KEM_AUTH_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_auth_encapsulate_init是可选的，但如果存在，则OSSL_FUNC_kem_auth_decapsulate_init也必须存在。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）操作生成、加载或导入密钥。有关更多详细信息，请参阅 provider-keymgmt(7)。

上下文管理函数

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

OSSL_FUNC_kem_freectx()将指向ctx参数中提供程序端非对称kem上下文的指针作为参数传递。此函数应释放与该上下文关联的任何资源。

OSSL_FUNC_kem_dupctx()应复制ctx参数中提供程序端非对称kem上下文，并返回副本。

非对称密钥封装函数

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

OSSL_FUNC_kem_auth_encapsulate_init()类似于OSSL_FUNC_kem_encapsulate_init()，但还传递了一个额外的身份验证密钥provauthkey，该密钥不能为NULL。

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

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

解封装函数

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

OSSL_FUNC_kem_auth_decapsulate_init()类似于OSSL_FUNC_kem_decapsulate_init()，但还传递了一个额外的身份验证密钥provauthkey，该密钥不能为NULL。

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(3)。

OSSL_FUNC_kem_get_ctx_params()获取与给定的提供程序端非对称kem上下文ctx关联的非对称kem参数，并将它们存储在params中。如果将params传递为NULL，则应返回true。

OSSL_FUNC_kem_set_ctx_params()将与给定的提供程序端非对称kem上下文ctx关联的非对称kem参数设置为params。任何参数设置都是对之前设置的任何参数的补充。如果将params传递为NULL，则应返回true。

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

OSSL_FUNC_kem_gettable_ctx_params()和OSSL_FUNC_kem_settable_ctx_params()获取一个常量 OSSL_PARAM(3) 数组，该数组描述可获取和可设置的参数，即可分别与OSSL_FUNC_kem_get_ctx_params()和OSSL_FUNC_kem_set_ctx_params()一起使用的参数。

返回值

OSSL_FUNC_kem_newctx()和OSSL_FUNC_kem_dupctx()应返回新创建的提供程序端非对称kem上下文，或在失败时返回NULL。

所有其他函数在成功时应返回1，在错误时返回0。

参见

provider(7)

历史

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

OSSL_FUNC_kem_auth_encapsulate_init()和OSSL_FUNC_kem_auth_decapsulate_init()是在OpenSSL 3.2中添加的。

版权

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