文章目录
🌵概要
#include <openssl/core_dispatch.h>
#include <openssl/core_names.h>
/*
* Digests support the following function signatures in OSSL_DISPATCH arrays.
* (The function signatures are not actual functions).
*/
/* Context management */
void *OSSL_FUNC_digest_newctx(void *provctx);
void OSSL_FUNC_digest_freectx(void *dctx);
void *OSSL_FUNC_digest_dupctx(void *dctx);
/* Digest generation */
int OSSL_FUNC_digest_init(void *dctx, const OSSL_PARAM params[]);
int OSSL_FUNC_digest_update(void *dctx, const unsigned char *in, size_t inl);
int OSSL_FUNC_digest_final(void *dctx, unsigned char *out, size_t *outl,
size_t outsz);
int OSSL_FUNC_digest_digest(void *provctx, const unsigned char *in, size_t inl,
unsigned char *out, size_t *outl, size_t outsz);
/* Digest parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_digest_gettable_params(void *provctx);
/* Digest operation parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_digest_gettable_ctx_params(void *dctx,
void *provctx);
const OSSL_PARAM *OSSL_FUNC_digest_settable_ctx_params(void *dctx,
void *provctx);
/* Digest parameters */
int OSSL_FUNC_digest_get_params(OSSL_PARAM params[]);
/* Digest operation parameters */
int OSSL_FUNC_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]);
int OSSL_FUNC_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]);
🎄描述
DIGEST 操作使提供程序能够实现摘要算法，并通过 API 函数EVP_DigestInit_ex、EVP_DigestUpdate和EVP_DigestFinal（以及其他相关函数）将其提供给应用程序。
这里提到的所有"函数"都作为函数指针在libcrypto和OSSL_DISPATCH数组中的提供者之间传递，通过由提供者的provider_query_operation（）函数返回的OSSL_ALGORITHM数组。
所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"OSSL_FUNC_digest_newctx（） 具有以下各项：
typedef void *(OSSL_OSSL_FUNC_digest_newctx_fn)(void *provctx);
static ossl_inline OSSL_OSSL_FUNC_digest_newctx_fn
OSSL_FUNC_digest_newctx(const OSSL_DISPATCH *opf);
OSSL_DISPATCH数组由 openssl-core_dispatch.h中作为宏提供的数字编制索引，如下所示：
OSSL_FUNC_digest_newctx OSSL_FUNC_DIGEST_NEWCTX
OSSL_FUNC_digest_freectx OSSL_FUNC_DIGEST_FREECTX
OSSL_FUNC_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX
OSSL_FUNC_digest_init OSSL_FUNC_DIGEST_INIT
OSSL_FUNC_digest_update OSSL_FUNC_DIGEST_UPDATE
OSSL_FUNC_digest_final OSSL_FUNC_DIGEST_FINAL
OSSL_FUNC_digest_digest OSSL_FUNC_DIGEST_DIGEST
OSSL_FUNC_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS
OSSL_FUNC_digest_get_ctx_params OSSL_FUNC_DIGEST_GET_CTX_PARAMS
OSSL_FUNC_digest_set_ctx_params OSSL_FUNC_DIGEST_SET_CTX_PARAMS
OSSL_FUNC_digest_gettable_params OSSL_FUNC_DIGEST_GETTABLE_PARAMS
OSSL_FUNC_digest_gettable_ctx_params OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS
OSSL_FUNC_digest_settable_ctx_params OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS
摘要算法实现可能无法实现所有这些功能。为了全部可用或不使用OSSL_FUNC_digest_newctx，应实施OSSL_FUNC_digest_freectx，OSSL_FUNC_digest_init，OSSL_FUNC_digest_update和OSSL_FUNC_digest_final。所有其他功能都是可选的。
🌲上下文管理功能
OSSL_FUNC_digest_newctx（） 应创建并返回指向提供程序端结构的指针，以便在摘要操作期间保存上下文信息。指向此上下文的指针将在许多其他摘要操作函数调用中传递回去。参数 provctx 是在提供程序初始化期间生成的提供程序上下文。
OSSL_FUNC_digest_freectx（） 在 dctx 参数中传递指向提供程序端摘要上下文的指针。此函数应释放与该上下文关联的任何资源。
OSSL_FUNC_digest_dupctx（） 应在 dctx 参数中复制提供程序端摘要上下文并返回重复的副本。
🌳摘要生成函数
OSSL_FUNC_digest_init（） 在 dctx 参数中给定新创建的提供程序端摘要上下文，初始化摘要操作。参数（如果不是 NULL）应以类似于使用 OSSL_FUNC_digest_set_ctx_params（） 的方式在上下文中设置。
调用 OSSL_FUNC_digest_update（） 以提供要作为先前初始化的摘要操作的一部分进行消化的数据。dctx 参数包含指向以前初始化的提供程序端上下文的指针。OSSL_FUNC_digest_update（） 应该在 in 所指向的位置消化 inl 字节的数据。对于单个摘要操作，可以多次调用 OSSL_FUNC_digest_update（）。
OSSL_FUNC_digest_final（） 生成通过以前的 OSSL_FUNC_digest_init（） 和 OSSL_FUNC_digest_update（） 调用启动的摘要。dctx 参数包含指向提供程序端上下文的指针。摘要应写为 *out，摘要的长度应写为 *outl。摘要不应超过 outsz 字节。
OSSL_FUNC_digest_digest（） 是一个"oneshot"摘要函数。不使用提供程序端摘要上下文。相反，在提供程序初始化期间创建的提供程序上下文在 provctx 参数中传递。应消化 in 处的 in 字节，并将结果存储在 out 处。摘要的长度应存储在 *outl 中，不应超过 outsz 字节。
🌴摘要参数
有关这些函数使用的参数结构的更多详细信息，请参见 OSSL_PARAM。
OSSL_FUNC_digest_get_params（） 获取算法实现的详细信息，并将其存储在params中。
OSSL_FUNC_digest_set_ctx_params（） 将提供程序端摘要上下文 dctx 的摘要操作参数设置为params。任何参数设置都是对以前设置的任何参数设置的附加设置。为params传递 NULL 应返回 true。
OSSL_FUNC_digest_get_ctx_params（） 从给定的提供程序端摘要上下文 dctx 获取摘要操作详细信息，并将其存储在params中。为params传递 NULL 应返回 true。
OSSL_FUNC_digest_gettable_params（） 返回一个常量OSSL_PARAM数组，其中包含 OSSL_FUNC_digest_get_params（） 可以处理的参数的描述符。
OSSL_FUNC_digest_gettable_ctx_params（） 和 OSSL_FUNC_digest_settable_ctx_params（） 都返回常量OSSL_PARAM数组，作为OSSL_FUNC_digest_get_ctx_params（） 和 OSSL_FUNC_digest_set_ctx_params（） 可以分别处理的参数的描述符。如果 dctx 不为 NULL，则该数组基于提供程序端上下文的当前状态，否则基于提供程序端算法 provctx 的当前状态。
具有此功能的内置摘要当前识别的参数如下所示。并非所有参数都与所有摘要相关或被所有摘要理解：
-
“blocksize” (OSSL_DIGEST_PARAM_BLOCK_SIZE)
摘要块大小。"块大小"参数的长度不应超过size_t的长度。 -
“size” (OSSL_DIGEST_PARAM_SIZE)
摘要输出大小。"size"参数的长度不应超过size_t的长度。 -
“flags” (OSSL_DIGEST_PARAM_FLAGS)
描述摘要特殊行为的各种标志：
EVP_MD_FLAG_ONESHOT
此摘要方法只能处理一个输入块。
EVP_MD_FLAG_XOF
此摘要方法是一个可扩展输出函数 （XOF），支持设置OSSL_DIGEST_PARAM_XOFLEN参数。
EVP_MD_FLAG_DIGALGID_NULL
设置 DigestAlgorithmIdentifier 时，默认情况下，此标志的参数将设置为 NULL。将此用于 PKCS#1。注意：如果与EVP_MD_FLAG_DIGALGID_ABSENT结合使用，后者将覆盖。
EVP_MD_FLAG_DIGALGID_ABSENT
设置 DigestAlgorithmIdentifier 时，默认情况下，此标志将缺少该参数。注意：如果与EVP_MD_FLAG_DIGALGID_NULL结合使用，后者将被覆盖。
EVP_MD_FLAG_DIGALGID_CUSTOM
自定义摘要算法通过 ctrl 进行识别器处理，默认EVP_MD_FLAG_DIGALGID_ABSENT。注意：如果与EVP_MD_FLAG_DIGALGID_NULL结合使用，后者将被覆盖。当前未使用。
“flags” 参数的长度应等于无符号长整数的长度。
🌱摘要上下文参数
OSSL_FUNC_digest_set_ctx_params（） 将与给定提供程序端摘要上下文 dctx 关联的摘要参数设置为参数。任何参数设置都是对以前设置的任何参数设置的附加设置。有关参数结构的更多详细信息，请参见 OSSL_PARAM。
OSSL_FUNC_digest_get_ctx_params（） 获取与给定提供程序端摘要上下文 dctx 关联的当前设置参数值的详细信息，并将它们存储在参数中。有关参数结构的更多详细信息，请参见 OSSL_PARAM。
🌿返回值
OSSL_FUNC_digest_newctx（） 和 OSSL_FUNC_digest_dupctx（） 应返回新创建的提供程序端摘要上下文，或在失败时返回 NULL。
OSSL_FUNC_digest_init（）、OSSL_FUNC_digest_update（）、OSSL_FUNC_digest_final（）、OSSL_FUNC_digest_digest（）、OSSL_FUNC_digest_set_params（） 和OSSL_FUNC_digest_get_params（）应返回 1 表示成功，或在错误时返回 0。
OSSL_FUNC_digest_size（） 应返回摘要大小。
OSSL_FUNC_digest_block_size（） 应返回基础摘要算法的块大小。
☘️错误
EVP_Q_digest（）、EVP_Digest（） 和 EVP_DigestFinal_ex（） API 调用不希望摘要大小大于 EVP_MAX_MD_SIZE。任何生成较大摘要的算法都无法用于这些 API 调用。
