文章目录
🌵概要
#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_cipher_newctx(void *provctx);
void OSSL_FUNC_cipher_freectx(void *cctx);
void *OSSL_FUNC_cipher_dupctx(void *cctx);
/* Encryption/decryption */
int OSSL_FUNC_cipher_encrypt_init(void *cctx, const unsigned char *key,
size_t keylen, const unsigned char *iv,
size_t ivlen, const OSSL_PARAM params[]);
int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key,
size_t keylen, const unsigned char *iv,
size_t ivlen, const OSSL_PARAM params[]);
int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl,
size_t outsize, const unsigned char *in, size_t inl);
int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl,
size_t outsize);
int OSSL_FUNC_cipher_cipher(void *cctx, unsigned char *out, size_t *outl,
size_t outsize, const unsigned char *in, size_t inl);
/* Cipher parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_cipher_gettable_params(void *provctx);
/* Cipher operation parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void *cctx,
void *provctx);
const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void *cctx,
void *provctx);
/* Cipher parameters */
int OSSL_FUNC_cipher_get_params(OSSL_PARAM params[]);
/* Cipher operation parameters */
int OSSL_FUNC_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]);
int OSSL_FUNC_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]);
🎄描述
CIPHER 操作使提供程序能够实现密码算法，并通过 API 函数EVP_EncryptInit_ex、EVP_EncryptUpdate和 EVP_EncryptFinal （以及解密等效项和其他相关函数）将其提供给应用程序。
这里提到的所有"函数"都作为函数指针在libcrypto和OSSL_DISPATCH数组中的提供者之间传递，通过由提供者的**provider_query_operation（）**函数返回的OSSL_ALGORITHM数组。
所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"OSSL_FUNC_cipher_newctx（） 具有以下各项：
typedef void *(OSSL_OSSL_FUNC_cipher_newctx_fn)(void *provctx);
static ossl_inline OSSL_OSSL_FUNC_cipher_newctx_fn
OSSL_FUNC_cipher_newctx(const OSSL_DISPATCH *opf);
OSSL_DISPATCH数组由 openssl-core_dispatch.h中作为宏提供的数字编制索引，如下所示：
OSSL_FUNC_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX
OSSL_FUNC_cipher_freectx OSSL_FUNC_CIPHER_FREECTX
OSSL_FUNC_cipher_dupctx OSSL_FUNC_CIPHER_DUPCTX
OSSL_FUNC_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT
OSSL_FUNC_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT
OSSL_FUNC_cipher_update OSSL_FUNC_CIPHER_UPDATE
OSSL_FUNC_cipher_final OSSL_FUNC_CIPHER_FINAL
OSSL_FUNC_cipher_cipher OSSL_FUNC_CIPHER_CIPHER
OSSL_FUNC_cipher_get_params OSSL_FUNC_CIPHER_GET_PARAMS
OSSL_FUNC_cipher_get_ctx_params OSSL_FUNC_CIPHER_GET_CTX_PARAMS
OSSL_FUNC_cipher_set_ctx_params OSSL_FUNC_CIPHER_SET_CTX_PARAMS
OSSL_FUNC_cipher_gettable_params OSSL_FUNC_CIPHER_GETTABLE_PARAMS
OSSL_FUNC_cipher_gettable_ctx_params OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS
OSSL_FUNC_cipher_settable_ctx_params OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS
密码算法实现可能无法实现所有这些功能。为了成为一组一致的函数，至少必须有一组完整的"加密"函数，或者一套完整的"解密"函数，或者一个"密码"函数。在所有情况下，OSSL_FUNC_cipher_newctx和OSSL_FUNC_cipher_freectx功能都必须存在。所有其他功能都是可选的。
🌲上下文管理功能
OSSL_FUNC_cipher_newctx（） 应创建并返回指向提供程序端结构的指针，用于在密码操作期间保存上下文信息。指向此上下文的指针将在许多其他密码操作函数调用中传递回去。参数 provctx 是在提供程序初始化期间生成的提供程序上下文。
OSSL_FUNC_cipher_freectx（） 在 cctx 参数中传递指向提供程序端密码上下文的指针。此函数应释放与该上下文关联的任何资源。
OSSL_FUNC_cipher_dupctx（） 应在 cctx 参数中复制提供程序端密码上下文，并返回重复的副本。
🌳加密/解密功能
OSSL_FUNC_cipher_encrypt_init（） 初始化密码操作以进行加密，给定在 cctx 参数中新创建的提供程序端密码上下文。要使用的密钥以密钥形式给出，该密钥的长度为keylen字节。要使用的 IV 在 iv 中给出，ivlen 字节长。参数（如果不是 NULL），则应以类似于使用 OSSL_FUNC_cipher_set_ctx_params（） 的方式在上下文中设置。
OSSL_FUNC_cipher_decrypt_init（） 与 OSSL_FUNC_cipher_encrypt_init（） 相同，只是它初始化解密操作的上下文。
调用 OSSL_FUNC_cipher_update（） 以提供要加密/解密的数据，作为先前初始化的密码操作的一部分。cctx 参数包含指向以前初始化的提供程序端上下文的指针。OSSL_FUNC_cipher_update（） 应该在 in 所指向的位置加密/解密 in 的整数字节数据。加密的数据应存储在 out 中，写入 *outl 的数据量不应超过超大字节。对于单个密码操作，可以多次调用 OSSL_FUNC_cipher_update（）。密码实现负责处理不是块长度倍数的输入长度。在这种情况下，密码实现通常会缓存部分输入数据块，直到获得完整的块。out 可能与 in 的位置相同，但不应部分重叠。与EVP_EncryptUpdate和EVP_DecryptUpdate所记录的超大尺寸相同的预期。
OSSL_FUNC_cipher_final（） 完成通过以前的 OSSL_FUNC_cipher_encrypt_init（） 或 OSSL_FUNC_cipher_decrypt_init（） 启动的加密或解密，并OSSL_FUNC_cipher_update（） 调用。cctx 参数包含指向提供程序端上下文的指针。任何最终的加密/解密输出都应写入输出，并将数据量写入 *outl，这不应超过超大字节。与EVP_EncryptFinal和EVP_DecryptFinal所记录的超大尺寸相同的期望。
OSSL_FUNC_cipher_cipher（） 使用 cctx 参数中的提供程序端密码上下文执行加密/解密，该上下文之前应通过调用 OSSL_FUNC_cipher_encrypt_init（） 或 OSSL_FUNC_cipher_decrypt_init（） 进行初始化。这应该调用原始的基础密码函数，没有任何填充。这将在提供程序中作为应用程序调用 EVP_Cipher的结果被调用。应用程序负责确保输入是块长度的倍数。要加密/解密的数据将位于 in 中，并且长度为 1 个字节。加密/解密的输出应存储在 out 中，存储的数据量应放入 *outl 中，该值不应超过超大字节。
🌴密码参数
有关这些函数使用的参数结构的更多详细信息，请参见 OSSL_PARAM。
OSSL_FUNC_cipher_get_params（） 获取算法实现的详细信息，并将它们存储在params中。
OSSL_FUNC_cipher_set_ctx_params（） 将提供程序端密码上下文 cctx 的密码操作参数设置为params。任何参数设置都是对以前设置的任何参数设置的附加设置。为params传递 NULL 应返回 true。
OSSL_FUNC_cipher_get_ctx_params（） 从给定的提供程序端密码上下文 cctx 获取密码操作详细信息，并将其存储在params中。为params传递 NULL 应返回 true。
OSSL_FUNC_cipher_gettable_params（）、OSSL_FUNC_cipher_gettable_ctx_params（） 和 OSSL_FUNC_cipher_settable_ctx_params（） 都返回常量OSSL_PARAM数组，作为分别OSSL_FUNC_cipher_get_params（）、OSSL_FUNC_cipher_get_ctx_params（） 和 OSSL_FUNC_cipher_set_ctx_params（） 可以处理的参数的描述符。OSSL_FUNC_cipher_gettable_ctx_params（） 和 OSSL_FUNC_cipher_settable_ctx_params（） 将返回与提供程序端上下文 cctx 关联的参数（如果它不是 NULL），则为当前状态。否则，它们将返回与提供程序端算法 provctx 关联的参数。
内置密码当前识别的参数列在 EVP_EncryptInit的"参数"中。并非所有参数都与所有密码相关或被所有密码理解。
🌱返回值
OSSL_FUNC_cipher_newctx（） 和 OSSL_FUNC_cipher_dupctx（） 应返回新创建的提供程序端密码上下文，或在失败时返回 NULL。
OSSL_FUNC_cipher_encrypt_init（）、OSSL_FUNC_cipher_decrypt_init（）、OSSL_FUNC_cipher_update（）、OSSL_FUNC_cipher_final（）、OSSL_FUNC_cipher_cipher（）、OSSL_FUNC_cipher_get_params（）、OSSL_FUNC_cipher_get_ctx_params（） 和OSSL_FUNC_cipher_set_ctx_params（）应返回 1 表示成功，或在出错时返回 0。
OSSL_FUNC_cipher_gettable_params（）、OSSL_FUNC_cipher_gettable_ctx_params（） 和 OSSL_FUNC_cipher_settable_ctx_params（） 应返回常量OSSL_PARAM数组，如果未提供，则返回 NULL。
