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

provider-digest

名称

provider-digest - 散列库 <-> 提供程序函数

摘要

#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[]);

描述

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

DIGEST 操作使提供程序能够实现散列算法，并通过 API 函数 EVP_DigestInit_ex(3)、EVP_DigestUpdate(3) 和 EVP_DigestFinal(3)（以及其他相关函数）使应用程序能够使用这些算法。

此处提到的所有“函数”都作为函数指针在 libcrypto 和提供程序之间传递，位于 OSSL_DISPATCH(3) 数组中，通过提供程序的 provider_query_operation() 函数返回的 OSSL_ALGORITHM(3) 数组（请参见 provider-base(7) 中的“提供程序函数”）。

所有这些“函数”都有一个相应的函数类型定义，名为 OSSL_FUNC_{name}_fn，以及一个辅助函数，用于从 OSSL_DISPATCH(3) 元素中检索函数指针，名为 OSSL_FUNC_{name}。例如，“函数”OSSL_FUNC_digest_newctx() 具有以下内容

typedef void *(OSSL_FUNC_digest_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_digest_newctx_fn
    OSSL_FUNC_digest_newctx(const OSSL_DISPATCH *opf);

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

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 是在提供程序初始化期间生成的提供程序上下文（请参见 provider(7)）。

OSSL_FUNC_digest_freectx() 将指向 dctx 参数中提供程序端散列上下文的指针作为参数传递。此函数应释放与该上下文关联的任何资源。

OSSL_FUNC_digest_dupctx() 应复制 dctx 参数中提供程序端散列上下文，并返回副本。

散列生成函数

OSSL_FUNC_digest_init() 初始化散列操作，给定 dctx 参数中新创建的提供程序端散列上下文。如果 params 不为 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() 是一个“一次性”散列函数。不使用提供程序端散列上下文。而是将提供程序初始化期间创建的提供程序上下文传递给 provctx 参数（请参见 provider(7)）。in 处的 inl 字节应进行散列，结果应存储在 out 中。散列的长度应存储在 *outl 中，其不应超过 outsz 字节。

散列参数

有关这些函数使用的参数结构的更多详细信息，请参见 OSSL_PARAM(3)。

OSSL_FUNC_digest_get_params() 获取算法实现的详细信息并将其存储在 params 中。

OSSL_FUNC_digest_set_ctx_params() 将提供程序端散列上下文 dctx 的散列操作参数设置为 params。任何参数设置都是对先前设置的任何参数的补充。将 NULL 传递给 params 应返回 true。

OSSL_FUNC_digest_get_ctx_params() 从给定的提供程序端散列上下文 dctx 获取散列操作详细信息，并将它们存储在 params 中。将 NULL 传递给 params 应返回 true。

OSSL_FUNC_digest_gettable_params() 返回一个常量 OSSL_PARAM(3) 数组，其中包含 OSSL_FUNC_digest_get_params() 可以处理的参数的描述符。

OSSL_FUNC_digest_gettable_ctx_params() 和 OSSL_FUNC_digest_settable_ctx_params() 都返回常量 OSSL_PARAM(3) 数组作为 OSSL_FUNC_digest_get_ctx_params() 和 OSSL_FUNC_digest_set_ctx_params() 可以分别处理的参数的描述符。如果 dctx 不为 NULL，则数组基于提供程序端上下文的当前状态，否则基于提供程序端算法 provctx。

使用此函数，内置散列当前识别的参数如下所示。并非所有参数都与所有散列相关或为所有散列所理解

"blocksize" (OSSL_DIGEST_PARAM_BLOCK_SIZE) <无符号整数>

散列块大小。“blocksize”参数的长度不应超过 size_t 的长度。

"size" (OSSL_DIGEST_PARAM_SIZE) <无符号整数>

散列输出大小。“size”参数的长度不应超过 size_t 的长度。

"flags" (OSSL_DIGEST_PARAM_FLAGS) <无符号整数>

描述散列异常行为的各种标志

EVP_MD_FLAG_ONESHOT: 此散列方法只能处理一个输入块。
EVP_MD_FLAG_XOF: 此散列方法是可扩展输出函数 (XOF)。
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 进行自定义 DigestAlgorithmIdentifier 处理，默认值为 EVP_MD_FLAG_DIGALGID_ABSENT。注意：如果与 EVP_MD_FLAG_DIGALGID_NULL 结合使用，后者将覆盖前者。 当前未使用。

"flags" 参数的长度应等于 unsigned long int 的长度。

散列上下文参数

OSSL_FUNC_digest_set_ctx_params() 将与给定的提供程序端散列上下文 dctx 关联的散列参数设置为 params。任何参数设置都是对先前设置的任何参数的补充。有关参数结构的更多详细信息，请参见 OSSL_PARAM(3)。

OSSL_FUNC_digest_get_ctx_params() 获取与给定提供程序端散列上下文 dctx 关联的当前设置的参数值的详细信息，并将它们存储在 params 中。有关参数结构的更多详细信息，请参见 OSSL_PARAM(3)。

返回值

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 调用一起使用。

参见

provider(7)、OSSL_PROVIDER-FIPS(7)、OSSL_PROVIDER-default(7)、OSSL_PROVIDER-legacy(7)、EVP_MD-common(7)、EVP_MD-BLAKE2(7)、EVP_MD-MD2(7)、EVP_MD-MD4(7)、EVP_MD-MD5(7)、EVP_MD-MD5-SHA1(7)、EVP_MD-MDC2(7)、EVP_MD-RIPEMD160(7)、EVP_MD-SHA1(7)、EVP_MD-SHA2(7)、EVP_MD-SHA3(7)、EVP_MD-KECCAK(7) EVP_MD-SHAKE(7)、EVP_MD-SM3(7)、EVP_MD-WHIRLPOOL(7)、EVP_MD-NULL(7)、life_cycle-digest(7)、EVP_DigestInit(3)

历史

提供程序 DIGEST 接口在 OpenSSL 3.0 中引入。

版权

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