開放SSL

密碼學和 SSL/TLS 工具組

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) 提供給應用程式使用。

此處提到的所有「函式」都會以函式指標在 OSSL_DISPATCH(3) 陣列中，透過 OSSL_ALGORITHM(3) 陣列（由提供者的 provider_query_operation() 函式傳回，請參閱 provider-base(7) 中的「提供者函式」）傳遞給 libcrypto 和提供者之間。

所有這些「函式」都有對應的函式類型定義，稱為 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() 會初始化一個 mac 作業，並在 mctx 參數中提供一個新建立的提供者端 mac 內容。params 會在設定 keylen 位元組的 MAC key 之前設定。

呼叫 OSSL_FUNC_mac_update() 以提供資料，用於先前初始化的 MAC 作業的 MAC 計算。mctx 參數包含指向先前初始化的提供者端內容的指標。OSSL_FUNC_mac_update() 可針對單一 MAC 作業呼叫多次。

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() 將傳回與提供者端內容相關聯的參數，並處於目前狀態。否則，它們會傳回與提供者端演算法 provctx 相關聯的參數。

預期所有 MAC 實作都能處理下列參數

搭配 OSSL_FUNC_set_ctx_params()
"key" (OSSL_MAC_PARAM_KEY) <八位元組字串>

設定相關聯 MAC 內容中的金鑰。這與將 key 引數傳遞給 OSSL_FUNC_mac_init() 函式相同。

搭配 OSSL_FUNC_get_params()
"size" (OSSL_MAC_PARAM_SIZE) <整數>

可用於取得預設 MAC 大小（可能是實作中唯一允許的 MAC 大小）。

請注意，有些實作允許設定產生的 MAC 應具有的大小，請參閱實作文件。

「大小」(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 中引入。

Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.

根據 Apache 授權條款 2.0 版 (「授權條款」) 授權。您只能在遵守授權條款的情況下使用此檔案。您可以在原始程式碼散佈中的 LICENSE 檔案中取得一份副本，或至 https://www.openssl.org/source/license.html 取得。