《OpenSSL3.0学习之十九 提供程序-mac｜CSDN创作打卡》

文章目录

• • • 🌺概要
    • 🌻描述
    • • 🌹上下文管理功能
      • 🌷加密/解密功能
      • 🌼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[]);

🌻描述

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

MAC 操作使提供商能够实现 mac 算法，并通过 API 函数EVP_MAC_init、EVP_MAC_update 和 EVP_MAC_final 向应用程序提供这些算法。

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

所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"OSSL_FUNC_mac_newctx（） 具有以下各项：

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

OSSL_DISPATCH数组由 openssl-core_dispatch.h中作为宏提供的数字编制索引，如下所示：

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

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

OSSL_FUNC_mac_dupctx（） 应在 mctx 参数中复制提供程序端 mac 上下文并返回重复的副本。

🌷加密/解密功能

OSSL_FUNC_mac_init（） 在 mctx 参数中给定新创建的提供程序端 mac 上下文，初始化 mac 操作。参数是在设置密钥字节的 MAC 密钥之前设置的。

调用 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字节。与 EVP_MAC_final中记录的超大尺寸相同的预期也适用于outsize。

🌼MAC参数

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

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

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

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

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

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

通过 OSSL_FUNC_set_ctx_params（）：

• “key” （OSSL_MAC_PARAM_KEY） < octet string >
  在关联的 MAC ctx 中设置密钥。这与将密钥参数传递给 OSSL_FUNC_mac_init（） 函数相同。

通过OSSL_FUNC_get_params（）：

• “size” （OSSL_MAC_PARAM_SIZE） < integer >
  可用于获取默认 MAC 大小（这可能是实现唯一允许的 MAC 大小）。
  请注意，某些实现还允许设置生成的 MAC 应具有的大小，请参阅实现的文档。

• “size” （OSSL_MAC_PARAM_BLOCK_SIZE） < integer >
  可用于获取 MAC 块大小（如果算法支持）。

🌸注意

MAC 生命周期在 life_cycle-rand 中描述。提供程序应确保其中列出的各种转换受支持。在某些时候，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数组，如果未提供，则返回 NULL。