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

provider-keyexch

名稱

provider-keyexch - keyexch 函式庫 <-> 提供者函式

語法

#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_keyexch_newctx(void *provctx);
void OSSL_FUNC_keyexch_freectx(void *ctx);
void *OSSL_FUNC_keyexch_dupctx(void *ctx);

/* Shared secret derivation */
int OSSL_FUNC_keyexch_init(void *ctx, void *provkey,
                           const OSSL_PARAM params[]);
int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey);
int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen,
                             size_t outlen);

/* Key Exchange parameters */
int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void *ctx,
                                                        void *provctx);
int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void *ctx,
                                                        void *provctx);

說明

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

金鑰交換 (OSSL_OP_KEYEXCH) 作業讓提供者能夠實作金鑰交換演算法，並透過 EVP_PKEY_derive(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_keyexch_newctx() 有這些

typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_keyexch_newctx_fn
    OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH(3) 陣列由 openssl-core_dispatch.h(7) 中提供為巨集的數字編制索引，如下所示

OSSL_FUNC_keyexch_newctx                OSSL_FUNC_KEYEXCH_NEWCTX
OSSL_FUNC_keyexch_freectx               OSSL_FUNC_KEYEXCH_FREECTX
OSSL_FUNC_keyexch_dupctx                OSSL_FUNC_KEYEXCH_DUPCTX

OSSL_FUNC_keyexch_init                  OSSL_FUNC_KEYEXCH_INIT
OSSL_FUNC_keyexch_set_peer              OSSL_FUNC_KEYEXCH_SET_PEER
OSSL_FUNC_keyexch_derive                OSSL_FUNC_KEYEXCH_DERIVE

OSSL_FUNC_keyexch_set_ctx_params        OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS
OSSL_FUNC_keyexch_settable_ctx_params   OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS
OSSL_FUNC_keyexch_get_ctx_params        OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS
OSSL_FUNC_keyexch_gettable_ctx_params   OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS

金鑰交換演算法實作可能不會實作所有這些函式。為了成為一致的函式組，提供者必須實作 OSSL_FUNC_keyexch_newctx、OSSL_FUNC_keyexch_freectx、OSSL_FUNC_keyexch_init 和 OSSL_FUNC_keyexch_derive。所有其他函式都是選用的。

金鑰交換演算法也必須實作一些機制，透過金鑰管理 (OSSL_OP_KEYMGMT) 作業來產生、載入或匯入金鑰。如需更多詳細資料，請參閱 provider-keymgmt(7)。

內容管理函式

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

OSSL_FUNC_keyexch_freectx() 會傳遞一個指標到提供者端金鑰交換內容，在 ctx 參數中。此函數應該釋放與該內容相關聯的任何資源。

OSSL_FUNC_keyexch_dupctx() 應該複製提供者端金鑰交換內容，在 ctx 參數中，並傳回複製副本。

共用秘密衍生函數

OSSL_FUNC_keyexch_init() 初始化金鑰交換操作，在 ctx 參數中給定提供者端金鑰交換內容，以及在 provkey 參數中給定一個指向提供者金鑰物件的指標。如果 params 不為 NULL，應該以類似於使用 OSSL_FUNC_keyexch_set_params() 的方式設定在內容中。金鑰物件應該先前使用金鑰管理 (OSSL_OP_KEYMGMT) 操作產生、載入或匯入到提供者中 (請參閱 provider-keymgmt(7)>。

呼叫 OSSL_FUNC_keyexch_set_peer() 以提供同儕公鑰 (在 provkey 參數中)，以便在衍生共用秘密時使用。它也會傳遞先前在 ctx 參數中初始化的金鑰交換內容。金鑰物件應該先前使用金鑰管理 (OSSL_OP_KEYMGMT) 操作產生、載入或匯入到提供者中 (請參閱 provider-keymgmt(7)>。

OSSL_FUNC_keyexch_derive() 透過衍生共用秘密來執行實際的金鑰交換。先前初始化的金鑰交換內容會傳遞在 ctx 參數中。衍生的秘密應該寫入到位置 secret，它不應該超過 outlen 位元組。共用秘密的長度應該寫入到 *secretlen。如果 secret 為 NULL，則共用秘密的最大長度應該寫入到 *secretlen。

金鑰交換參數函數

OSSL_FUNC_keyexch_set_ctx_params() 將與給定的提供者端金鑰交換內容 ctx 相關聯的金鑰交換參數設定為 params，請參閱 "常見金鑰交換參數"。任何參數設定都是額外的，除了先前設定的任何設定。傳遞 NULL 作為 params 應該傳回 true。

OSSL_FUNC_keyexch_get_ctx_params() 將與給定的提供者端金鑰交換內容 ctx 相關聯的金鑰交換參數取得到 params 中，請參閱 "常見金鑰交換參數"。傳遞 NULL 作為 params 應該傳回 true。

OSSL_FUNC_keyexch_settable_ctx_params() 產生一個常數 OSSL_PARAM(3) 陣列，用來描述可設定的參數，即可以使用 OP_signature_set_ctx_params() 的參數。如果 OSSL_FUNC_keyexch_settable_ctx_params() 存在，則 OSSL_FUNC_keyexch_set_ctx_params() 也必須存在，反之亦然。類似地，OSSL_FUNC_keyexch_gettable_ctx_params() 產生一個常數 OSSL_PARAM(3) 陣列，用來描述可取得的參數，即 OP_signature_get_ctx_params() 可以處理的參數。如果 OSSL_FUNC_keyexch_gettable_ctx_params() 存在，則 OSSL_FUNC_keyexch_get_ctx_params() 也必須存在，反之亦然。

請注意，並非所有可設定的參數都是可取得的，反之亦然。

常見金鑰交換參數

請參閱 OSSL_PARAM(3)，以進一步了解 OSSL_FUNC_keyexch_set_ctx_params() 和 OSSL_FUNC_keyexch_get_ctx_params() 函式所使用的參數結構。

內建金鑰交換演算法目前辨識的常見參數如下。

"kdf-type" (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 字串>: 設定或取得要套用在關聯金鑰交換 ctx 中的金鑰衍生函數類型。
"kdf-digest" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 字串>: 設定或取得要作為與給定金鑰交換 ctx 關聯的金鑰衍生函數一部分的摘要演算法。
"kdf-digest-props" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 字串>: 設定要使用在為與給定金鑰交換 ctx 關聯的金鑰衍生函數所選摘要演算法尋找實作時所使用的屬性。
"kdf-outlen" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <未簽署整數>: 設定或取得與給定金鑰交換 ctx 關聯的所選金鑰衍生函數輸出的所需大小。 "kdf-outlen" 參數的長度不應超過 size_t。
"kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <八位元組字串>: 設定要作為與給定金鑰交換 ctx 關聯的所選金鑰衍生函數一部分的使用者金鑰資料。
"kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <八位元組字串指標>: 取得要作為與給定金鑰交換 ctx 關聯的所選金鑰衍生函數一部分的使用者金鑰資料的指標。提供者通常不需要支援這個可取得參數，因為它的唯一目的是支援已棄用的 EVP_PKEY_CTX_get0_ecdh_kdf_ukm() 和 EVP_PKEY_CTX_get0_dh_kdf_ukm() 函數的功能。

傳回值

OSSL_FUNC_keyexch_newctx() 和 OSSL_FUNC_keyexch_dupctx() 應傳回新建立的提供者端金鑰交換內容，或在失敗時傳回 NULL。

OSSL_FUNC_keyexch_init()、OSSL_FUNC_keyexch_set_peer()、OSSL_FUNC_keyexch_derive()、OSSL_FUNC_keyexch_set_params() 和 OSSL_FUNC_keyexch_get_params() 應傳回 1 表示成功，或在發生錯誤時傳回 0。

OSSL_FUNC_keyexch_settable_ctx_params() 和 OSSL_FUNC_keyexch_gettable_ctx_params() 應始終傳回一個常數 OSSL_PARAM(3) 陣列。

另請參閱

provider(7)

歷程記錄

provider KEYEXCH 介面是在 OpenSSL 3.0 中引入的。

版權

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