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

provider-mac

名称

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

概要

#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_mac_newctx(void *provctx);
void OSSL_FUNC_mac_freectx(void *mctx);
void *OSSL_FUNC_mac_dupctx(void *src);

/* Encryption/decryption */
int OSSL_FUNC_mac_init(void *mctx, unsigned char *key, size_t keylen,
                       const OSSL_PARAM params[]);
int OSSL_FUNC_mac_update(void *mctx, const unsigned char *in, size_t inl);
int OSSL_FUNC_mac_final(void *mctx, unsigned char *out, size_t *outl, size_t outsize);

/* MAC parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_mac_gettable_params(void *provctx);
const OSSL_PARAM *OSSL_FUNC_mac_gettable_ctx_params(void *mctx, void *provctx);
const OSSL_PARAM *OSSL_FUNC_mac_settable_ctx_params(void *mctx, void *provctx);

/* MAC parameters */
int OSSL_FUNC_mac_get_params(OSSL_PARAM params[]);
int OSSL_FUNC_mac_get_ctx_params(void *mctx, OSSL_PARAM params[]);
int OSSL_FUNC_mac_set_ctx_params(void *mctx, const OSSL_PARAM params[]);

描述

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

MAC操作使提供程序能够实现mac算法，并通过API函数 EVP_MAC_init(3)、EVP_MAC_update(3) 和 EVP_MAC_final(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_mac_newctx()具有以下内容

typedef void *(OSSL_FUNC_mac_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_mac_newctx_fn
    OSSL_FUNC_mac_newctx(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_mac_newctx               OSSL_FUNC_MAC_NEWCTX
OSSL_FUNC_mac_freectx              OSSL_FUNC_MAC_FREECTX
OSSL_FUNC_mac_dupctx               OSSL_FUNC_MAC_DUPCTX

OSSL_FUNC_mac_init                 OSSL_FUNC_MAC_INIT
OSSL_FUNC_mac_update               OSSL_FUNC_MAC_UPDATE
OSSL_FUNC_mac_final                OSSL_FUNC_MAC_FINAL

OSSL_FUNC_mac_get_params           OSSL_FUNC_MAC_GET_PARAMS
OSSL_FUNC_mac_get_ctx_params       OSSL_FUNC_MAC_GET_CTX_PARAMS
OSSL_FUNC_mac_set_ctx_params       OSSL_FUNC_MAC_SET_CTX_PARAMS

OSSL_FUNC_mac_gettable_params      OSSL_FUNC_MAC_GETTABLE_PARAMS
OSSL_FUNC_mac_gettable_ctx_params  OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS
OSSL_FUNC_mac_settable_ctx_params  OSSL_FUNC_MAC_SETTABLE_CTX_PARAMS

mac算法实现可能不会实现所有这些函数。为了成为一组一致的函数，至少必须实现以下函数：OSSL_FUNC_mac_newctx()、OSSL_FUNC_mac_freectx()、OSSL_FUNC_mac_init()、OSSL_FUNC_mac_update()、OSSL_FUNC_mac_final()。所有其他函数都是可选的。

上下文管理函数

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

OSSL_FUNC_mac_freectx()将mctx参数中指向提供程序端mac上下文的指针作为参数传递。如果它接收NULL作为mctx值，则除了返回外不应执行任何操作。此函数应释放与该上下文关联的任何资源。

OSSL_FUNC_mac_dupctx()应复制mctx参数中的提供程序端mac上下文，并返回副本。

加密/解密函数

OSSL_FUNC_mac_init()初始化给定mctx参数中新创建的提供程序端mac上下文的mac操作。在设置keylen字节的MACkey之前设置params。

OSSL_FUNC_mac_update()用于提供先前初始化的mac操作的MAC计算数据。mctx参数包含指向先前初始化的提供程序端上下文的指针。对于单个mac操作，可以多次调用OSSL_FUNC_mac_update()。

OSSL_FUNC_mac_final()完成通过以前的OSSL_FUNC_mac_init()和OSSL_FUNC_mac_update()调用启动的MAC计算。mctx参数包含指向提供程序端上下文的指针。结果MAC应写入out，并将写入的数据量写入*outl，它不应超过outsize字节。outsize适用与 EVP_MAC_final(3) 中记录的相同预期。

Mac参数

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

OSSL_FUNC_mac_get_params()获取与提供程序算法关联的参数值的详细信息，并将它们存储在params中。

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

OSSL_FUNC_mac_get_ctx_params()获取与给定提供程序端mac上下文mctx关联的当前设置的参数值的详细信息，并将它们存储在params中。将NULL传递给params应返回true。

OSSL_FUNC_mac_gettable_params()、OSSL_FUNC_mac_gettable_ctx_params()和OSSL_FUNC_mac_settable_ctx_params()都返回常量 OSSL_PARAM(3) 数组作为OSSL_FUNC_mac_get_params()、OSSL_FUNC_mac_get_ctx_params()和OSSL_FUNC_mac_set_ctx_params()可以分别处理的参数的描述符。如果mctx不为NULL，则OSSL_FUNC_mac_gettable_ctx_params()和OSSL_FUNC_mac_settable_ctx_params()将返回与提供程序端上下文mctx关联的参数，处于其当前状态。否则，它们将返回与提供程序端算法provctx关联的参数。

所有MAC实现都应处理以下参数

使用OSSL_FUNC_set_ctx_params()

"key" (OSSL_MAC_PARAM_KEY) <八位字节串>: 在关联的MAC ctx中设置密钥。这与将key参数传递给OSSL_FUNC_mac_init()函数相同。

使用OSSL_FUNC_get_params()

"size" (OSSL_MAC_PARAM_SIZE) <整数>

可用于获取默认MAC大小（这可能是实现中唯一允许的MAC大小）。

请注意，某些实现也允许设置结果MAC应具有的大小，请参见实现的文档。

"size" (OSSL_MAC_PARAM_BLOCK_SIZE) <整数>: 可用于获取MAC块大小（如果算法支持）。

注释

MAC生命周期在 life_cycle-rand(7) 中进行了描述。提供程序应确保支持那里列出的各种转换。在某些时候，EVP层将开始强制执行列出的转换。

返回值

OSSL_FUNC_mac_newctx()和OSSL_FUNC_mac_dupctx()应返回新创建的提供程序端mac上下文，或在失败时返回NULL。

OSSL_FUNC_mac_init()、OSSL_FUNC_mac_update()、OSSL_FUNC_mac_final()、OSSL_FUNC_mac_get_params()、OSSL_FUNC_mac_get_ctx_params()和OSSL_FUNC_mac_set_ctx_params()在成功时应返回1，在错误时返回0。

OSSL_FUNC_mac_gettable_params()、OSSL_FUNC_mac_gettable_ctx_params()和OSSL_FUNC_mac_settable_ctx_params()应返回一个常量 OSSL_PARAM(3) 数组，或者如果没有提供则返回NULL。

参见

provider(7)、EVP_MAC-BLAKE2(7)、EVP_MAC-CMAC(7)、EVP_MAC-GMAC(7)、EVP_MAC-HMAC(7)、EVP_MAC-KMAC(7)、EVP_MAC-Poly1305(7)、EVP_MAC-Siphash(7)、life_cycle-mac(7)、EVP_MAC(3)

历史

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

版权

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