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

provider-decoder

名稱

provider-decoder - OSSL_DECODER 函式庫 <-> 提供者函式

語法

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

/* Decoder parameter accessor and descriptor */
const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx);
int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]);

/* Functions to construct / destruct / manipulate the decoder context */
void *OSSL_FUNC_decoder_newctx(void *provctx);
void OSSL_FUNC_decoder_freectx(void *ctx);
const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx);
int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);

/* Functions to check selection support */
int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);

/* Functions to decode object data */
int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in,
                             int selection,
                             OSSL_CALLBACK *data_cb, void *data_cbarg,
                             OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);

/* Functions to export a decoded object */
int OSSL_FUNC_decoder_export_object(void *ctx,
                                      const void *objref, size_t objref_sz,
                                      OSSL_CALLBACK *export_cb,
                                      void *export_cbarg);

說明

本手冊中會使用「解碼」一詞。這包括但不限於反序列化，因為個別解碼器也可以將資料解碼成中間資料格式。

DECODER 作業是一種通用方法，可從給定的 OSSL_CORE_BIO 讀取編碼格式，建立提供者原生物件參考或中間解碼資料。如果呼叫者想要從記憶體解碼資料，應提供 BIO_s_mem(3) BIO。解碼資料或物件參考會連同最終的元資料傳遞給 metadata_cb 作為 OSSL_PARAM(3) 參數。

解碼器不需要知道 OSSL_CORE_BIO 指標的任何資訊，只要能將其傳遞給適當的 BIO 上游呼叫即可（請參閱 provider-base(7) 中的「核心函式」）。

DECODER 實作可能是鏈的一部分，其中資料會從一個傳遞到另一個。例如，可能有一個實作可以將物件從 PEM 解碼成 DER，另一個實作可以將 DER 解碼成提供者原生物件。

解碼鏈中的最後一個解碼步驟通常會建立一個物件參考所引用的提供者原生物件。若要將該物件匯入不同的提供者，可以在解碼程序的最後一個步驟呼叫 OSSL_FUNC_decoder_export_object()。

此處提到的所有「函式」都會透過 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_decoder_decode() 有這些

typedef int
    (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in,
                                  int selection,
                                  OSSL_CALLBACK *data_cb, void *data_cbarg,
                                  OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
static ossl_inline OSSL_FUNC_decoder_decode_fn*
    OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_decoder_get_params          OSSL_FUNC_DECODER_GET_PARAMS
OSSL_FUNC_decoder_gettable_params     OSSL_FUNC_DECODER_GETTABLE_PARAMS

OSSL_FUNC_decoder_newctx              OSSL_FUNC_DECODER_NEWCTX
OSSL_FUNC_decoder_freectx             OSSL_FUNC_DECODER_FREECTX
OSSL_FUNC_decoder_set_ctx_params      OSSL_FUNC_DECODER_SET_CTX_PARAMS
OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS

OSSL_FUNC_decoder_does_selection      OSSL_FUNC_DECODER_DOES_SELECTION

OSSL_FUNC_decoder_decode              OSSL_FUNC_DECODER_DECODE

OSSL_FUNC_decoder_export_object       OSSL_FUNC_DECODER_EXPORT_OBJECT

名稱和屬性

實作的名稱應與其解碼的目標物件類型相符。例如，解碼 RSA 金鑰的實作應命名為「RSA」。同樣地，從 PEM 輸入解碼 DER 資料的實作應命名為「DER」。

屬性可用於進一步指定實作的詳細資訊

輸入

此屬性用於指定實作可以解碼的輸入格式。

此屬性為強制性。

OpenSSL 提供者識別下列輸入類型

pem: 具有該輸入類型的實作會解碼 PEM 格式化的資料。
der: 具有該輸入類型的實作會解碼 DER 格式化的資料。
msblob: 具有該輸入類型的實作會解碼 MSBLOB 格式化的資料。
pvk: 具有該輸入類型的實作會解碼 PVK 格式化的資料。

structure

此屬性用於指定解碼資料預期的結構。

此屬性為選用。

內建解碼器目前識別的結構

"type-specific": 類型特定結構。
"pkcs8": 根據 PKCS#8 規範的結構。
"SubjectPublicKeyInfo": 根據 RFC 5280 的主旨公開金鑰資訊編碼公開金鑰。

這兩個屬性的可能值是開放式的。提供者很可能會指定 libcrypto 一無所知的輸入類型和結構。

子集選取

有時，一個物件有多個資料子集，可以分開或一起處理。可以指定要解碼哪些子集，使用以int傳遞的位元組selection。

這組位元組完全取決於要解碼的提供者端物件類型。例如，當物件是非對稱金鑰對時，假設這些位元組與 provider-keymgmt(7) (請參閱 "provider-keymgmt(7) 中的「金鑰物件」) 中使用的位元組相同，例如，如果要解碼的物件應包含私密金鑰元件，則為 OSSL_KEYMGMT_SELECT_PRIVATE_KEY。

OSSL_FUNC_decoder_does_selection() 應說明特定實作是否支援selection給定的任何組合。

內容函式

OSSL_FUNC_decoder_newctx() 傳回要與其他函式一起使用的內容。

OSSL_FUNC_decoder_freectx() 釋放由 OSSL_FUNC_decoder_newctx() 建立的ctx。

OSSL_FUNC_decoder_set_ctx_params() 根據params的參數設定內容資料，它會辨識這些參數。應忽略未辨識的參數。將 NULL 傳遞給params應傳回 true。

OSSL_FUNC_decoder_settable_ctx_params() 傳回常數 OSSL_PARAM(3) 陣列，描述 OSSL_FUNC_decoder_set_ctx_params() 可以處理的參數。

請參閱 OSSL_PARAM(3)，進一步了解 OSSL_FUNC_decoder_set_ctx_params() 和 OSSL_FUNC_decoder_settable_ctx_params() 使用的參數結構。

匯出函式

當解碼器建立提供者原生物件時，不適合直接與外部提供者一起使用。匯出函式允許將物件匯出到該外部提供者，如果外部提供者支援物件類型並提供匯入函式。

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

解碼函式

OSSL_FUNC_decoder_decode() 應解碼從OSSL_CORE_BIOin讀取的資料，以產生解碼資料或物件，作為 OSSL_PARAM(3) 陣列中的參考傳遞，以及從輸入解碼的其他可能的元資料。此 OSSL_PARAM(3) 陣列隨後傳遞給data_cb 回呼。如果相關，selection 位元組應決定輸入資料應包含什麼。解碼函式還會採用 OSSL_PASSPHRASE_CALLBACK(3) 函式指標以及指向應用程式資料cbarg，當需要密碼提示時應使用這些資料。

了解此函數的回傳值如何詮釋非常重要

True (1)

這表示「繼續解碼程序」，即使此函數無法將輸入解碼成任何內容，這仍然有意義，因為可能還有其他解碼器實作可以將其解碼成某些內容。

當此函數無法將輸入解碼成任何內容時，絕不應呼叫data_cb 回呼。

False (0)

這表示「停止解碼程序」，當輸入可以解碼成此函數理解的某種物件時，這是有意義的，但進一步處理該物件會導致錯誤，而其他解碼器實作無法取得不同的結果。

停止解碼程序的條件由實作決定。

解碼器操作參數

內建解碼器目前不識別任何操作參數。

內建通行詞組回呼目前識別的參數

"info" (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 字串>: 資訊字串，將成為通行詞提示的一部分。這可用於向使用者提供有關提示物件類型的資訊。

回傳值

OSSL_FUNC_decoder_newctx() 回傳指向內容的指標，或在失敗時回傳 NULL。

OSSL_FUNC_decoder_set_ctx_params() 回傳 1，除非識別的參數無效或導致錯誤，則回傳 0。

OSSL_FUNC_decoder_settable_ctx_params() 回傳指向常數 OSSL_PARAM(3) 元素陣列的指標。

如果解碼器實作支援任何選取位元，則 OSSL_FUNC_decoder_does_selection() 回傳 1，否則回傳 0。

OSSL_FUNC_decoder_decode() 回傳 1 以表示解碼程序應繼續，或回傳 0 以表示應停止。

另請參閱

provider(7)

歷程

DECODER 介面在 OpenSSL 3.0 中引入。

版權

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

開啟SSL

密碼編譯與 SSL/TLS 工具組