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

provider-kdf

名稱

provider-kdf - KDF 函式庫 <-> 提供者函式

語法

#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_kdf_newctx(void *provctx);
void OSSL_FUNC_kdf_freectx(void *kctx);
void *OSSL_FUNC_kdf_dupctx(void *src);

/* Encryption/decryption */
int OSSL_FUNC_kdf_reset(void *kctx);
int OSSL_FUNC_kdf_derive(void *kctx, unsigned char *key, size_t keylen,
                         const OSSL_PARAM params[]);

/* KDF parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_kdf_gettable_params(void *provctx);
const OSSL_PARAM *OSSL_FUNC_kdf_gettable_ctx_params(void *kcxt, void *provctx);
const OSSL_PARAM *OSSL_FUNC_kdf_settable_ctx_params(void *kcxt, void *provctx);

/* KDF parameters */
int OSSL_FUNC_kdf_get_params(OSSL_PARAM params[]);
int OSSL_FUNC_kdf_get_ctx_params(void *kctx, OSSL_PARAM params[]);
int OSSL_FUNC_kdf_set_ctx_params(void *kctx, const OSSL_PARAM params[]);

說明

此文件主要針對提供者作者。如需進一步資訊，請參閱 provider(7)。

KDF 作業讓提供者能夠實作 KDF 演算法，並透過 API 函式 EVP_KDF_CTX_reset(3) 和 EVP_KDF_derive(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_kdf_newctx() 有這些

typedef void *(OSSL_FUNC_kdf_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_kdf_newctx_fn
    OSSL_FUNC_kdf_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH(3) 陣列項目由 openssl-core_dispatch.h(7) 中的巨集識別，如下所示

OSSL_FUNC_kdf_newctx               OSSL_FUNC_KDF_NEWCTX
OSSL_FUNC_kdf_freectx              OSSL_FUNC_KDF_FREECTX
OSSL_FUNC_kdf_dupctx               OSSL_FUNC_KDF_DUPCTX

OSSL_FUNC_kdf_reset                OSSL_FUNC_KDF_RESET
OSSL_FUNC_kdf_derive               OSSL_FUNC_KDF_DERIVE

OSSL_FUNC_kdf_get_params           OSSL_FUNC_KDF_GET_PARAMS
OSSL_FUNC_kdf_get_ctx_params       OSSL_FUNC_KDF_GET_CTX_PARAMS
OSSL_FUNC_kdf_set_ctx_params       OSSL_FUNC_KDF_SET_CTX_PARAMS

OSSL_FUNC_kdf_gettable_params      OSSL_FUNC_KDF_GETTABLE_PARAMS
OSSL_FUNC_kdf_gettable_ctx_params  OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS
OSSL_FUNC_kdf_settable_ctx_params  OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS

KDF 演算法實作可能不會實作所有這些函式。為了成為一致的函式組，至少必須實作下列函式：OSSL_FUNC_kdf_newctx()、OSSL_FUNC_kdf_freectx()、OSSL_FUNC_kdf_set_ctx_params()、OSSL_FUNC_kdf_derive()。所有其他函式都是選用的。

內容管理函式

OSSL_FUNC_kdf_newctx() 應該建立並傳回一個指標，指向提供者端結構，用於在 KDF 作業期間保存內容資訊。此內容的指標會在其他許多 KDF 作業函式呼叫中傳回。參數 provctx 是在提供者初始化期間產生的提供者內容（請參閱 provider(7)）。

OSSL_FUNC_kdf_freectx() 會在 kctx 參數中傳入一個指標，指向 KDF 提供者端內容。如果它收到 NULL 作為 kctx 值，它不應執行任何動作，除了傳回之外。此函式應釋放與該內容相關的任何資源。

OSSL_FUNC_kdf_dupctx() 應該複製 kctx 參數中的 KDF 提供者端內容，並傳回複製副本。

加密/解密函數

OSSL_FUNC_kdf_reset() 初始化一個 KDF 作業，並在 kctx 參數中提供一個供應商端的 KDF 內容。

OSSL_FUNC_kdf_derive() 處理 params 後執行 KDF 作業，處理方式依照 OSSL_FUNC_kdf_set_ctx_params()。kctx 參數包含一個指向供應商端內容的指標。所需 keylen 的結果金鑰應寫入 key。如果演算法不支援所要求的 keylen，函數必須傳回錯誤。

KDF 參數

請參閱 OSSL_PARAM(3)，以進一步了解這些函數所使用的參數結構。

OSSL_FUNC_kdf_get_params() 取得與供應商演算法相關聯的參數值詳細資料，並將其儲存在 params 中。

OSSL_FUNC_kdf_set_ctx_params() 將與給定的供應商端 KDF 內容 kctx 相關聯的 KDF 參數設定為 params。任何參數設定都會新增至先前設定的任何設定。傳遞 NULL 給 params 應傳回 true。

OSSL_FUNC_kdf_get_ctx_params() 擷取與給定的供應商端 KDF 內容 kctx 相關聯的可取得參數值，並將其儲存在 params 中。傳遞 NULL 給 params 應傳回 true。

OSSL_FUNC_kdf_gettable_params()、OSSL_FUNC_kdf_gettable_ctx_params() 和 OSSL_FUNC_kdf_settable_ctx_params() 都傳回常數 OSSL_PARAM(3) 陣列，作為 OSSL_FUNC_kdf_get_params()、OSSL_FUNC_kdf_get_ctx_params() 和 OSSL_FUNC_kdf_set_ctx_params() 分別可以處理的參數描述。如果 kctx 不是 NULL，OSSL_FUNC_kdf_gettable_ctx_params() 和 OSSL_FUNC_kdf_settable_ctx_params() 將傳回與供應商端內容相關聯的參數，並維持其目前狀態。否則，它們會傳回與供應商端演算法 provctx 相關聯的參數。

內建 KDF 目前識別的參數如下。並非所有參數都與所有 KDF 相關，或為所有 KDF 所理解

"size" (OSSL_KDF_PARAM_SIZE) <無符號整數>

從相關聯的 KDF ctx 取得輸出大小。如果演算法產生變動數量的輸出，應傳回 SIZE_MAX。如果尚未提供計算固定輸出大小所需的輸入參數，應傳回 0 來表示錯誤。

"key" (OSSL_KDF_PARAM_KEY) <八進位字串>

在相關聯的 KDF ctx 中設定金鑰。

"secret" (OSSL_KDF_PARAM_SECRET) <八進位字串>

在相關聯的 KDF ctx 中設定機密。

"pass" (OSSL_KDF_PARAM_PASSWORD) <八進位字串>

在相關聯的 KDF ctx 中設定密碼。

"cipher" (OSSL_KDF_PARAM_CIPHER) <UTF8 字串>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 字串>

"mac" (OSSL_KDF_PARAM_MAC) <UTF8 字串>

設定要使用的底層密碼、摘要或 MAC 的名稱。它必須為正在使用的 KDF 命名一個合適的演算法。

"maclen" (OSSL_KDF_PARAM_MAC_SIZE) <八進位字串>

設定關聯 KDF ctx 中 MAC 的長度。

"屬性" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 字串>

設定嘗試擷取基礎演算法時要查詢的屬性。這必須與演算法命名參數一起提供，才能被視為有效。

"反覆運算" (OSSL_KDF_PARAM_ITER) <無符號整數>

設定關聯 KDF ctx 中的反覆運算次數。

"模式" (OSSL_KDF_PARAM_MODE) <UTF8 字串>

設定關聯 KDF ctx 中的模式。

"pkcs5" (OSSL_KDF_PARAM_PKCS5) <整數>

啟用或停用 SP800-132 相符性檢查。模式 0 會啟用相符性檢查。

執行的檢查為

- 反覆運算次數至少為 1000。
- 鹽長至少為 128 位元。
- 衍生金鑰長至少為 112 位元。

"ukm" (OSSL_KDF_PARAM_UKM) <八位元組字串>

設定由寄件者提供的隨機字串，稱為「partyAInfo」。在 CMS 中，這是使用者金鑰材料。

"cekalg" (OSSL_KDF_PARAM_CEK_ALG) <UTF8 字串>

設定關聯 KDF ctx 中的 CEK 封裝演算法名稱。

"n" (OSSL_KDF_PARAM_SCRYPT_N) <無符號整數>

設定關聯 KDF ctx 中的 scrypt 工作因子參數 N。

"r" (OSSL_KDF_PARAM_SCRYPT_R) <無符號整數>

設定關聯 KDF ctx 中的 scrypt 工作因子參數 r。

"p" (OSSL_KDF_PARAM_SCRYPT_P) <無符號整數>

設定關聯 KDF ctx 中的 scrypt 工作因子參數 p。

"maxmem_bytes" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <無符號整數>

設定關聯 KDF ctx 中的 scrypt 工作因子參數 maxmem。

"prefix" (OSSL_KDF_PARAM_PREFIX) <八位元組字串>

設定關聯 KDF ctx 中由 TLS 1.3 版本的 HKDF 使用的前置字串。

"標籤" (OSSL_KDF_PARAM_LABEL) <八位元組字串>

設定關聯 KDF ctx 中由 TLS 1.3 版本的 HKDF 使用的標籤字串。

"資料" (OSSL_KDF_PARAM_DATA) <八位元組字串>

設定關聯 KDF ctx 中由 TLS 1.3 版本的 HKDF 使用的內容字串。

"資訊" (OSSL_KDF_PARAM_INFO) <八位元組字串>

設定關聯 KDF ctx 中的選用共用資訊。

"種子" (OSSL_KDF_PARAM_SEED) <八位元組字串>

設定關聯 KDF ctx 中的 IV。

"xcghash" (OSSL_KDF_PARAM_SSHKDF_XCGHASH) <八位元組字串>

設定關聯 KDF ctx 中的 xcghash。

"session_id" (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) <八位元組字串>

設定關聯 KDF ctx 中的階段 ID。

"類型" (OSSL_KDF_PARAM_SSHKDF_TYPE) <UTF8 字串>

設定關聯 KDF ctx 中的 SSH KDF 類型參數。支援六種類型

EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV: 從用戶端到伺服器的初始 IV。單一字元值為 65 (ASCII 字元 'A')。
EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI: 從伺服器到用戶端的初始 IV。單一字元值為 66 (ASCII 字元 'B')。
EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV: 從用戶端到伺服器的加密金鑰。單一字元值為 67 (ASCII 字元 'C')。
EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI: 從伺服器到用戶端的加密金鑰。單一字元值為 68 (ASCII 字元 'D')。
EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV: 從用戶端到伺服器的完整性金鑰。單一字元值為 69 (ASCII 字元 'E')。
EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI: 從用戶端到伺服器的完整性金鑰。單一字元值為 70 (ASCII 字元 'F')。

"constant" (OSSL_KDF_PARAM_CONSTANT) <八位元組字串>

設定關聯 KDF ctx 中的常數值。

"id" (OSSL_KDF_PARAM_PKCS12_ID) <整數>

設定關聯 KDF ctx 中輸出位元的預期用途。其定義如 RFC 7292 第 B.3 節所述。

傳回值

OSSL_FUNC_kdf_newctx() 和 OSSL_FUNC_kdf_dupctx() 應傳回新建立的提供者端 KDF 內容，或在失敗時傳回 NULL。

OSSL_FUNC_kdf_derive()、OSSL_FUNC_kdf_get_params()、OSSL_FUNC_kdf_get_ctx_params() 和 OSSL_FUNC_kdf_set_ctx_params() 應傳回 1 表示成功，或在錯誤時傳回 0。

OSSL_FUNC_kdf_gettable_params()、OSSL_FUNC_kdf_gettable_ctx_params() 和 OSSL_FUNC_kdf_settable_ctx_params() 應傳回常數 OSSL_PARAM(3) 陣列，或在沒有提供時傳回 NULL。

注意事項

KDF 生命週期說明於 life_cycle-kdf(7) 中。提供者應確保支援所列出的各種轉換。在某個時間點，EVP 層會開始強制執行所列出的轉換。

另請參閱

provider(7)、life_cycle-kdf(7)、EVP_KDF(3)。

歷程

提供者 KDF 介面於 OpenSSL 3.0 中引入。

版權

根據 Apache 授權條款 2.0 版 (「授權條款」) 授權。您不得使用此檔案，除非符合授權條款。您可以在原始程式碼散佈中的 LICENSE 檔案中取得副本，或至 https://www.openssl.org/source/license.html 取得。