《OpenSSL3.0学习之十六提供程序-asym_cipher｜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_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);

🌻描述

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

非对称密码（OSSL_OP_ASYM_CIPHER）操作使提供程序能够实现非对称密码算法，并通过API函数EVP_PKEY_encrypt，EVP_PKEY_decrypt和其他相关函数）将其提供给应用程序。

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

所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"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数组由openssl-core_dispatch.h中作为宏提供的数字编制索引，如下所示：

 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）操作生成、加载或导入密钥。有关详细信息，请参阅提供程序-keymgmt。

🌹上下文管理功能

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

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

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

🌷加密函数

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

🌼解密函数

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

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

🌸非对称密码参数

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

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

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

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

“pad-mode” (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) < integer >
要使用的填充类型。此值的解释将取决于所使用的算法。默认提供程序 RSA 填充模式：1（RSA_PKCS1_PADDING）、3（RSA_NO_PADDING）、4（RSA_PKCS1_OAEP_PADDING）、5（RSA_X931_PADDING）、6（RSA_PKCS1_PSS_PADDING）和 7（RSA_PKCS1_WITH_TLS_PADDING）。有关详细信息，请参见 EVP_PKEY_CTX_set_rsa_padding。
“digest” (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) < UTF8 string >
获取或设置在使用 OAEP 填充时使用的 OAEP 摘要算法的名称。
“digest” (OSSL_ASYM_CIPHER_PARAM_DIGEST) < UTF8 string >
获取或设置算法使用的摘要算法的名称（如果适用）。
“digest-props” (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) < UTF8 string >
获取或设置在提取 OAEP 摘要算法时要使用的属性。
“digest-props” (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) < UTF8 string >
获取或设置在提取密码摘要算法时要使用的属性。
“mgf1-digest” (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) < UTF8 string >
获取或设置在使用 OAEP 或 PSS 填充时使用的 MGF1 摘要算法的名称。
“mgf1-digest-props” (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) < UTF8 string >
获取或设置在获取 MGF1 摘要算法时要使用的属性。
“oaep-label” (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) < octet string >
获取或设置在使用 OAEP 填充时使用的 OAEP 标签。
“tls-client-version” (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) < unsigned integer >
客户端首先请求的 TLS 协议版本。请参阅EVP_PKEY_CTX_set_rsa_padding页上的RSA_PKCS1_WITH_TLS_PADDING。
“tls-negotiated-version” (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) < unsigned integer >
协商的 TLS 协议版本。请参阅EVP_PKEY_CTX_set_rsa_padding页上的RSA_PKCS1_WITH_TLS_PADDING。

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