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

provider-storemgmt

名稱

provider-storemgmt - OSSL_STORE 函式庫 <-> 提供者函式

語法

#include <openssl/core_dispatch.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.
 */

void *OSSL_FUNC_store_open(void *provctx, const char *uri);
void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio);
const OSSL_PARAM *store_settable_ctx_params(void *provctx);
int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]);
int OSSL_FUNC_store_load(void *loaderctx,
                         OSSL_CALLBACK *object_cb, void *object_cbarg,
                         OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);
int OSSL_FUNC_store_eof(void *loaderctx);
int OSSL_FUNC_store_close(void *loaderctx);

int OSSL_FUNC_store_export_object
    (void *loaderctx, const void *objref, size_t objref_sz,
     OSSL_CALLBACK *export_cb, void *export_cbarg);
void *OSSL_FUNC_store_open_ex(void *provctx, const char *uri,
                              const OSSL_PARAM params[],
                              OSSL_PASSPHRASE_CALLBACK *pw_cb,
                              void *pw_cbarg);

int OSSL_FUNC_store_delete(void *provctx, const char *uri,
                   const OSSL_PARAM params[],
                   OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);

說明

STORE 作業是 ossl_store(7) API 的提供者端。

STORE 作業的主要責任是從 URI 指示的容器載入各種物件。這些物件以提供者原生物件抽象形式提供給 OpenSSL 函式庫（請參閱 provider-object(7)）。然後，OpenSSL 函式庫負責將該抽象傳遞給合適的提供函式。

OpenSSL 函式庫可以將抽象傳遞給的函式範例包括 OSSL_FUNC_keymgmt_load() (provider-keymgmt(7))、OSSL_FUNC_store_export_object()（以參數化形式匯出物件）。

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

所有這些「函式」都有對應的函式類型定義，稱為 OSSL_FUNC_{name}_fn，以及一個輔助函式，用於從 OSSL_DISPATCH(3) 元素中擷取函式指標，稱為 OSSL_get_{name}。例如，「函式」OSSL_FUNC_store_attach() 有這些

typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx,
                                          OSSL_CORE_BIO * bio);
static ossl_inline OSSL_FUNC_store_attach_fn
    OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_store_open                 OSSL_FUNC_STORE_OPEN
OSSL_FUNC_store_attach               OSSL_FUNC_STORE_ATTACH
OSSL_FUNC_store_settable_ctx_params  OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS
OSSL_FUNC_store_set_ctx_params       OSSL_FUNC_STORE_SET_CTX_PARAMS
OSSL_FUNC_store_load                 OSSL_FUNC_STORE_LOAD
OSSL_FUNC_store_eof                  OSSL_FUNC_STORE_EOF
OSSL_FUNC_store_close                OSSL_FUNC_STORE_CLOSE
OSSL_FUNC_store_export_object        OSSL_FUNC_STORE_EXPORT_OBJECT
OSSL_FUNC_store_delete               OSSL_FUNC_STORE_DELETE
OSSL_FUNC_store_open_ex              OSSL_FUNC_STORE_OPEN_EX

函式

OSSL_FUNC_store_open() 應根據輸入 uri 建立具有資料的提供者端內容。實作完全負責詮釋 URI。

OSSL_FUNC_store_attach() 應建立具有附加核心 BIO bio 的提供者端內容。這是使用 URI 尋找儲存空間的替代方案，支援 OSSL_STORE_attach(3)。

OSSL_FUNC_store_settable_ctx_params() 應傳回常數陣列描述符 OSSL_PARAM(3)，以供 OSSL_FUNC_store_set_ctx_params() 處理的參數。

OSSL_FUNC_store_set_ctx_params() 應設定其他參數，例如預期的資料類型、搜尋條件等。有關這些內容的詳細資訊，請參閱「載入參數」中的內容。是否將無法辨識的參數視為錯誤或忽略，則由實作自行決定。傳遞 NULL 給 params 應傳回 true。

OSSL_FUNC_store_load() 從 OSSL_FUNC_store_open() 開啟的 URI 載入下一個物件，為其建立物件抽象（請參閱 provider-object(7)），並使用它以及 object_cbarg 呼叫 object_cb。然後，object_cb 將詮釋物件抽象，並盡可能將其包裝或解碼成 OpenSSL 結構。如果需要提示輸入密碼來解鎖物件，則應呼叫 pw_cb。

OSSL_FUNC_store_eof() 指示是否已到達來自 URI 的物件集合的結尾。發生這種情況時，嘗試進行任何進一步載入都沒有意義。

OSSL_FUNC_store_close() 會釋放提供者端的內容 ctx。

當提供者原生物件由儲存管理員建立時，它將不適合直接與外部提供者一起使用。如果外部提供者支援物件類型並提供匯入函式，則匯出函式允許將物件匯出至該外部提供者。

OSSL_FUNC_store_export_object() 應將 objref 參照的長度為 objref_sz 的物件匯出為 OSSL_PARAM(3) 陣列，並將其傳遞給 export_cb 以及指定的 export_cbarg。

OSSL_FUNC_store_delete() 會刪除由 uri 識別的物件。實作完全負責詮釋 URI。如果需要提示輸入密語來移除物件，則應呼叫 pw_cb。

OSSL_FUNC_store_open_ex() 是 OSSL_FUNC_store_open() 的延伸變體。如果提供者未實作此函式，則程式碼內部會改用原始的 OSSL_FUNC_store_open()。此變體另外會接受 OSSL_PARAM(3) 物件和 pw_cb 回呼，可在需要在執行任何載入作業前先解鎖整個儲存時用來要求輸入密語。

載入參數

"預期" (OSSL_STORE_PARAM_EXPECT) <整數>

是 OpenSSL 函式庫預期取得的資料類型的提示。這僅對最佳化有用，因為函式庫會檢查物件類型是否也符合預期。

可透過此參數提供的數字可以在 <openssl/store.h> 中找到，其中巨集名稱以 OSSL_STORE_INFO_ 開頭。這些會進一步在 OSSL_STORE_INFO(3) 中的「支援的物件」中說明。

"主旨" (OSSL_STORE_PARAM_SUBJECT) <八位元組字串>

表示呼叫者想要搜尋與指定主旨關聯的物件。這可用於依主旨選取特定憑證。

八位元組字串的內容預期為 DER 格式。

"發行者" (OSSL_STORE_PARAM_ISSUER) <八位元組字串>

表示呼叫者想要搜尋與給定發行者關聯的物件。這可用於透過發行者來選取特定憑證。

八位元組字串的內容預期為 DER 格式。

"serial" (OSSL_STORE_PARAM_SERIAL) <整數>

表示呼叫者想要搜尋與給定序號關聯的物件。

"digest" (OSSL_STORE_PARAM_DIGEST) <UTF8 字串>

"fingerprint" (OSSL_STORE_PARAM_FINGERPRINT) <八位元組字串>

表示呼叫者想要搜尋與給定指紋關聯的物件，並以給定摘要計算。

"alias" (OSSL_STORE_PARAM_ALIAS) <UTF8 字串>

表示呼叫者想要搜尋與給定別名（有些人稱之為「友善名稱」）關聯的物件。

"properties" (OSSL_STORE_PARAM_PROPERTIES) <utf8 字串>

查詢演算法時要使用的屬性字串，例如 OSSL_DECODER 解碼器實作。

"input-type" (OSSL_STORE_PARAM_INPUT_TYPE) <utf8 字串>

儲存庫中物件解碼時要使用的輸入格式類型提示。

可以結合這些搜尋條件中的多個條件。例如，要透過發行者+序號搜尋憑證，將同時提供「issuer」和「serial」參數。

另請參閱

provider(7)

歷程

STORE 介面在 OpenSSL 3.0 中引入。

OSSL_FUNC_store_delete() 回呼在 OpenSSL 3.2 中加入

版權

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

開啟SSL

密碼學和 SSL/TLS 工具包

provider-storemgmt

名稱

語法

說明

函式

載入參數

另請參閱

歷程

版權