开放SSL

密码学和 SSL/TLS 工具包

provider-asym_cipher

名称

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

概要

#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_asym_cipher_newctx(void *provctx);
void OSSL_FUNC_asym_cipher_freectx(void *ctx);
void *OSSL_FUNC_asym_cipher_dupctx(void *ctx);

/* Encryption */
int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey,
                                       const OSSL_PARAM params[]);
int OSSL_FUNC_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen,
                                  size_t outsize, const unsigned char *in,
                                  size_t inlen);

/* Decryption */
int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey,
                                       const OSSL_PARAM params[]);
int OSSL_FUNC_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen,
                                  size_t outsize, const unsigned char *in,
                                  size_t inlen);

/* Asymmetric Cipher parameters */
int OSSL_FUNC_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void *provctx);
int OSSL_FUNC_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void *provctx);

描述

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

非对称密码 (OSSL_OP_ASYM_CIPHER) 操作使提供程序能够实现非对称密码算法，并通过 API 函数 EVP_PKEY_encrypt(3)、EVP_PKEY_decrypt(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_asym_cipher_newctx() 具有以下内容

typedef void *(OSSL_FUNC_asym_cipher_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn
    OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_asym_cipher_newctx               OSSL_FUNC_ASYM_CIPHER_NEWCTX
OSSL_FUNC_asym_cipher_freectx              OSSL_FUNC_ASYM_CIPHER_FREECTX
OSSL_FUNC_asym_cipher_dupctx               OSSL_FUNC_ASYM_CIPHER_DUPCTX

OSSL_FUNC_asym_cipher_encrypt_init         OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT
OSSL_FUNC_asym_cipher_encrypt              OSSL_FUNC_ASYM_CIPHER_ENCRYPT

OSSL_FUNC_asym_cipher_decrypt_init         OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT
OSSL_FUNC_asym_cipher_decrypt              OSSL_FUNC_ASYM_CIPHER_DECRYPT

OSSL_FUNC_asym_cipher_get_ctx_params       OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS
OSSL_FUNC_asym_cipher_gettable_ctx_params  OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS
OSSL_FUNC_asym_cipher_set_ctx_params       OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS
OSSL_FUNC_asym_cipher_settable_ctx_params  OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS

非对称密码算法实现可能不会实现所有这些函数。为了成为一致的函数集，提供程序必须实现 OSSL_FUNC_asym_cipher_newctx 和 OSSL_FUNC_asym_cipher_freectx。它还必须实现 OSSL_FUNC_asym_cipher_encrypt_init 和 OSSL_FUNC_asym_cipher_encrypt 中的两个，或者 OSSL_FUNC_asym_cipher_decrypt_init 和 OSSL_FUNC_asym_cipher_decrypt 中的两个。OSSL_FUNC_asym_cipher_get_ctx_params 是可选的，但如果存在，则 OSSL_FUNC_asym_cipher_gettable_ctx_params 也必须存在。类似地，OSSL_FUNC_asym_cipher_set_ctx_params 是可选的，但如果存在，则 OSSL_FUNC_asym_cipher_settable_ctx_params 也必须存在。

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

上下文管理函数

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

OSSL_FUNC_asym_cipher_freectx() 在 ctx 参数中传递指向提供程序端非对称密码上下文的指针。此函数应该释放与该上下文相关联的任何资源。

OSSL_FUNC_asym_cipher_dupctx() 应该复制 ctx 参数中的提供程序端非对称密码上下文，并返回副本。

加密函数

OSSL_FUNC_asym_cipher_encrypt_init() 初始化一个用于非对称加密的上下文，该上下文在 ctx 参数中给出提供程序端非对称密码上下文，并在 provkey 参数中给出指向提供程序密钥对象的指针。如果 params 不为 NULL，则应该以类似于使用 OSSL_FUNC_asym_cipher_set_ctx_params() 的方式将其设置在上下文中。密钥对象应该事先使用密钥管理 (OSSL_OP_KEYMGMT) 操作（请参阅 provider-keymgmt(7)）在提供程序中生成、加载或导入。OSSL_FUNC_asym_cipher_encrypt() 执行实际的加密操作。先前初始化的非对称密码上下文在 ctx 参数中传递。要加密的数据由 in 参数指向，该参数长 inlen 字节。除非 out 为 NULL，否则加密后的数据应该写入 out 参数指向的位置，并且其长度不应超过 outsize 字节。加密后的数据长度应该写入 *outlen。如果 out 为 NULL，则加密后的数据的最大长度应该写入 *outlen。

解密函数

OSSL_FUNC_asym_cipher_decrypt_init() 初始化一个用于非对称解密的上下文，该上下文在 ctx 参数中给出提供程序端非对称密码上下文，并在 provkey 参数中给出指向提供程序密钥对象的指针。如果 params 不为 NULL，则应该以类似于使用 OSSL_FUNC_asym_cipher_set_ctx_params() 的方式将其设置在上下文中。密钥对象应该事先使用密钥管理 (OSSL_OP_KEYMGMT) 操作（请参阅 provider-keymgmt(7)）在提供程序中生成、加载或导入。

OSSL_FUNC_asym_cipher_decrypt() 执行实际的解密操作。先前初始化的非对称密码上下文在 ctx 参数中传递。要解密的数据由 in 参数指向，该参数长 inlen 字节。除非 out 为 NULL，否则解密后的数据应该写入 out 参数指向的位置，并且其长度不应超过 outsize 字节。解密后的数据长度应该写入 *outlen。如果 out 为 NULL，则解密后的数据的最大长度应该写入 *outlen。

非对称密码参数

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

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

OSSL_FUNC_asym_cipher_set_ctx_params() 将与给定提供程序端非对称密码上下文 ctx 关联的非对称密码参数设置为 params。任何参数设置都是对以前设置的任何参数设置的补充。将 NULL 传递给 params 应该返回 true。

内置非对称密码算法当前识别的参数如下所示。并非所有参数都与所有非对称密码算法相关或被所有算法理解

"pad-mode" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <UTF8 字符串> 或 <整数>

要使用的填充类型。此值的解释将取决于使用的算法。

"digest" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) <UTF8 字符串>

获取或设置使用 OAEP 填充时使用的 OAEP 摘要算法的名称。

"digest" (OSSL_ASYM_CIPHER_PARAM_DIGEST) <UTF8 字符串>

获取或设置算法使用的摘要算法的名称（如果适用）。

"digest-props" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) <UTF8 字符串>

获取或设置获取 OAEP 摘要算法时要使用的属性。

"digest-props" (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) <UTF8 字符串>

获取或设置获取密码摘要算法时要使用的属性。

"mgf1-digest" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) <UTF8 字符串>

获取或设置使用 OAEP 或 PSS 填充时使用的 MGF1 摘要算法的名称。

"mgf1-digest-props" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) <UTF8 字符串>

获取或设置获取 MGF1 摘要算法时要使用的属性。

"oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <八位字节字符串指针>

获取使用 OAEP 填充时使用的 OAEP 标签。

"oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <八位字节字符串>

设置使用 OAEP 填充时使用的 OAEP 标签。

"tls-client-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <无符号整数>

客户端首次请求的 TLS 协议版本。

"tls-negotiated-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <无符号整数>

协商的 TLS 协议版本。

"implicit-rejection" (OSSL_PKEY_PARAM_IMPLICIT_REJECTION) <无符号整数>

获取或设置用于 RSA PKCS#1 v1.5 解密的隐式拒绝机制的使用情况。当设置（非零值）时，如果 PKCS#1 v1.5 填充检查失败，则解密 API 将返回一个确定性随机值。这使得利用 Bleichenbacher 变得更加困难，即使使用 RSA 解密 API 的代码不是以无侧信道的方式实现的。默认情况下设置。需要提供程序支持。

OSSL_FUNC_asym_cipher_gettable_ctx_params() 和 OSSL_FUNC_asym_cipher_settable_ctx_params() 获取一个常量 OSSL_PARAM(3) 数组，该数组描述可获取和可设置的参数，即可以使用 OSSL_FUNC_asym_cipherget_ctx_params() 和 OSSL_FUNC_asym_cipher_set_ctx_params() 分别使用的参数。

返回值

OSSL_FUNC_asym_cipher_newctx() 和 OSSL_FUNC_asym_cipher_dupctx() 应该返回新创建的提供程序端非对称密码上下文，或者在失败时返回 NULL。

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

参见

provider(7)

历史

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

版权所有 2019-2023 OpenSSL 项目作者。保留所有权利。

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