開放SSL

密碼學和 SSL/TLS 工具組

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) 以取得更多資訊。

摘要操作讓提供者能夠實作摘要演算法，並透過 API 函式 EVP_DigestInit_ex(3)、EVP_DigestUpdate(3) 和 EVP_DigestFinal(3) (以及其他相關函式) 將這些演算法提供給應用程式使用。

此處提到所有「函式」都以函式指標的方式在 OSSL_DISPATCH(3) 陣列中傳遞給 libcrypto 和提供者，並透過 OSSL_ALGORITHM(3) 陣列傳回，而這些陣列是由提供者的 provider_query_operation() 函式傳回的 (請參閱 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() 的方式在內容中設定 params。

OSSL_FUNC_digest_update() 會呼叫來提供資料，以作為先前初始化摘要作業的一部分進行摘要。dctx 參數包含指向先前初始化的提供者端內容的指標。OSSL_FUNC_digest_update() 應摘要 inl 位元組的資料，其位置由 in 指向。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_t。

「旗標」(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 結合使用，後者將會優先。目前未使用。

「旗標」參數的長度應等於 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 中引入。

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

在 Apache License 2.0（「授權」）下取得授權。您不得在不遵守授權的情況下使用此檔案。您可以在原始程式碼散佈中的 LICENSE 檔案或 https://www.openssl.org/source/license.html 中取得副本。