provider-kem
名稱
provider-kem - kem 函式庫 <-> 提供者函式
語法
#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_kem_newctx(void *provctx);
void OSSL_FUNC_kem_freectx(void *ctx);
void *OSSL_FUNC_kem_dupctx(void *ctx);
/* Encapsulation */
int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey,
const OSSL_PARAM params[]);
int OSSL_FUNC_kem_auth_encapsulate_init(void *ctx, void *provkey,
void *provauthkey,
const OSSL_PARAM params[]);
int OSSL_FUNC_kem_encapsulate(void *ctx, unsigned char *out, size_t *outlen,
unsigned char *secret, size_t *secretlen);
/* Decapsulation */
int OSSL_FUNC_kem_decapsulate_init(void *ctx, void *provkey);
int OSSL_FUNC_kem_auth_decapsulate_init(void *ctx, void *provkey,
void *provauthkey,
const OSSL_PARAM params[]);
int OSSL_FUNC_kem_decapsulate(void *ctx, unsigned char *out, size_t *outlen,
const unsigned char *in, size_t inlen);
/* KEM parameters */
int OSSL_FUNC_kem_get_ctx_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_kem_gettable_ctx_params(void *ctx, void *provctx);
int OSSL_FUNC_kem_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_kem_settable_ctx_params(void *ctx, void *provctx);說明
本文件主要針對提供者作者。如需進一步資訊，請參閱 provider(7)。
不對稱 kem (OSSL_OP_KEM) 作業讓提供者能夠實作不對稱 kem 演算法，並透過 API 函式 EVP_PKEY_encapsulate(3)、EVP_PKEY_decapsulate(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_kem_newctx() 有這些
typedef void *(OSSL_FUNC_kem_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_kem_newctx_fn
OSSL_FUNC_kem_newctx(const OSSL_DISPATCH *opf);OSSL_DISPATCH(3) 陣列會根據 openssl-core_dispatch.h(7) 中提供為巨集的數字編製索引，如下所示
OSSL_FUNC_kem_newctx OSSL_FUNC_KEM_NEWCTX
OSSL_FUNC_kem_freectx OSSL_FUNC_KEM_FREECTX
OSSL_FUNC_kem_dupctx OSSL_FUNC_KEM_DUPCTX
OSSL_FUNC_kem_encapsulate_init OSSL_FUNC_KEM_ENCAPSULATE_INIT
OSSL_FUNC_kem_auth_encapsulate_init OSSL_FUNC_KEM_AUTH_ENCAPSULATE_INIT
OSSL_FUNC_kem_encapsulate OSSL_FUNC_KEM_ENCAPSULATE
OSSL_FUNC_kem_decapsulate_init OSSL_FUNC_KEM_DECAPSULATE_INIT
OSSL_FUNC_kem_auth_decapsulate_init OSSL_FUNC_KEM_AUTH_DECAPSULATE_INIT
OSSL_FUNC_kem_decapsulate OSSL_FUNC_KEM_DECAPSULATE
OSSL_FUNC_kem_get_ctx_params OSSL_FUNC_KEM_GET_CTX_PARAMS
OSSL_FUNC_kem_gettable_ctx_params OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS
OSSL_FUNC_kem_set_ctx_params OSSL_FUNC_KEM_SET_CTX_PARAMS
OSSL_FUNC_kem_settable_ctx_params OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS不對稱 kem 演算法實作可能不會實作所有這些函式。為了成為一組一致的函式，提供者必須實作 OSSL_FUNC_kem_newctx 和 OSSL_FUNC_kem_freectx。它還必須同時實作 OSSL_FUNC_kem_encapsulate_init 和 OSSL_FUNC_kem_encapsulate，或同時實作 OSSL_FUNC_kem_decapsulate_init 和 OSSL_FUNC_kem_decapsulate。OSSL_FUNC_kem_auth_encapsulate_init 是選用的，但如果存在，則 OSSL_FUNC_kem_auth_decapsulate_init 也必須存在。OSSL_FUNC_kem_get_ctx_params 是選用的，但如果存在，則 OSSL_FUNC_kem_gettable_ctx_params 也必須存在。同樣地，OSSL_FUNC_kem_set_ctx_params 是選用的，但如果存在，則 OSSL_FUNC_kem_settable_ctx_params 也必須存在。
不對稱 kem 演算法還必須實作一些機制，透過金鑰管理 (OSSL_OP_KEYMGMT) 作業來產生、載入或匯入金鑰。如需進一步詳細資訊，請參閱 provider-keymgmt(7)。
內容管理函式
OSSL_FUNC_kem_newctx() 應建立並傳回一個指向提供者端結構的指標，用於在非對稱 kem 作業期間保存內容資訊。此內容的指標會在其他非對稱 kem 作業函式呼叫中傳回。參數 provctx 是在提供者初始化期間產生的提供者內容（請參閱 provider(7)）。
OSSL_FUNC_kem_freectx() 會傳遞一個指向提供者端非對稱 kem 內容的指標，作為 ctx 參數。此函式應釋放與該內容相關的所有資源。
OSSL_FUNC_kem_dupctx() 應複製 ctx 參數中的提供者端非對稱 kem 內容，並傳回複製副本。
非對稱金鑰封裝函式
OSSL_FUNC_kem_encapsulate_init() 會初始化非對稱封裝的內容，並在 ctx 參數中提供提供者端非對稱 kem 內容，在 provkey 參數中提供指向提供者金鑰物件的指標，以及演算法的 name。如果 params 不為 NULL，應使用類似於 OSSL_FUNC_kem_set_ctx_params() 的方式在內容中設定。金鑰物件應事先使用金鑰管理 (OSSL_OP_KEYMGMT) 作業產生、載入或匯入提供者（請參閱 provider-keymgmt(7)>）。
OSSL_FUNC_kem_auth_encapsulate_init() 類似於 OSSL_FUNC_kem_encapsulate_init()，但也會傳遞額外的驗證金鑰 provauthkey，且不能為 NULL。
OSSL_FUNC_kem_encapsulate() 會執行實際封裝。先前初始化的非對稱 kem 內容會傳遞在 ctx 參數中。除非 out 為 NULL，否則會在內部產生要封裝的資料，並傳回 secret 參數所指的緩衝區，且封裝資料也應寫入 out 參數所指的位置。封裝資料的長度應寫入 *outlen，而產生機密的長度應寫入 *secretlen。
如果 out 為 NULL，則應將封裝資料的最大長度寫入 *outlen，而產生機密的最大長度應寫入 *secretlen。
解封裝函式
OSSL_FUNC_kem_decapsulate_init() 會初始化非對稱解封裝的內容，並在 ctx 參數中提供提供者端非對稱 kem 內容，在 provkey 參數中提供指向提供者金鑰物件的指標，以及演算法的 name。金鑰物件應事先使用金鑰管理 (OSSL_OP_KEYMGMT) 作業產生、載入或匯入提供者（請參閱 provider-keymgmt(7)>）。
OSSL_FUNC_kem_auth_decapsulate_init() 類似於 OSSL_FUNC_kem_decapsulate_init()，但也會傳遞額外的驗證金鑰 provauthkey，且不能為 NULL。
OSSL_FUNC_kem_decapsulate() 本身執行實際的解密封裝。先前初始化的非對稱 kem 背景會傳遞至 ctx 參數中。要解密封裝的資料由 in 參數指向，其長度為 inlen 位元組。除非 out 為 NULL，否則解密封裝的資料應寫入由 out 參數指向的位置。解密封裝資料的長度應寫入 *outlen。如果 out 為 NULL，則應將解密封裝資料的最大長度寫入 *outlen。
非對稱金鑰封裝參數
請參閱 OSSL_PARAM(3) 以進一步瞭解 OSSL_FUNC_kem_get_ctx_params() 和 OSSL_FUNC_kem_set_ctx_params() 函式所使用的參數結構。
OSSL_FUNC_kem_get_ctx_params() 會取得與指定提供者端非對稱 kem 背景 ctx 相關的非對稱 kem 參數，並將其儲存在 params 中。將 NULL 傳遞給 params 應傳回 true。
OSSL_FUNC_kem_set_ctx_params() 會將與指定提供者端非對稱 kem 背景 ctx 相關的非對稱 kem 參數設定為 params。任何參數設定都會新增至先前設定的任何設定。將 NULL 傳遞給 params 應傳回 true。
內建非對稱 kem 演算法目前不識別任何參數。
OSSL_FUNC_kem_gettable_ctx_params() 和 OSSL_FUNC_kem_settable_ctx_params() 會取得一個常數 OSSL_PARAM(3) 陣列，用於描述可取得和可設定參數，亦即分別可與 OSSL_FUNC_kem_get_ctx_params() 和 OSSL_FUNC_kem_set_ctx_params() 搭配使用的參數。
傳回值
OSSL_FUNC_kem_newctx() 和 OSSL_FUNC_kem_dupctx() 應傳回新建立的提供者端非對稱 kem 背景，或在失敗時傳回 NULL。
所有其他函式應在成功時傳回 1，或在發生錯誤時傳回 0。
另請參閱
歷程記錄
提供者 KEM 介面於 OpenSSL 3.0 中引入。
OSSL_FUNC_kem_auth_encapsulate_init() 和 OSSL_FUNC_kem_auth_decapsulate_init() 於 OpenSSL 3.2 中新增。
版權
Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
根據 Apache License 2.0（「授權」）授權。您不得在不遵守授權的情況下使用此檔案。您可以在原始程式碼散佈中的 LICENSE 檔案中取得副本，或至 https://www.openssl.org/source/license.html 取得。