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

provider-encoder

名稱

provider-encoder - OSSL_ENCODER 函式庫 <-> 提供者函式

語法

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

/* Encoder parameter accessor and descriptor */
const OSSL_PARAM *OSSL_FUNC_encoder_gettable_params(void *provctx);
int OSSL_FUNC_encoder_get_params(OSSL_PARAM params[]);

/* Functions to construct / destruct / manipulate the encoder context */
void *OSSL_FUNC_encoder_newctx(void *provctx);
void OSSL_FUNC_encoder_freectx(void *ctx);
int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx);

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

/* Functions to encode object data */
int OSSL_FUNC_encoder_encode(void *ctx, OSSL_CORE_BIO *out,
                             const void *obj_raw,
                             const OSSL_PARAM obj_abstract[],
                             int selection,
                             OSSL_PASSPHRASE_CALLBACK *cb,
                             void *cbarg);

/* Functions to import and free a temporary object to be encoded */
void *OSSL_FUNC_encoder_import_object(void *ctx, int selection,
                                      const OSSL_PARAM params[]);
void OSSL_FUNC_encoder_free_object(void *obj);

說明

我們在本手冊中使用廣義的「編碼」一詞。這包括但不限於序列化。

ENCODER 操作是一種通用方法，用於將提供者原生物件 (obj_raw) 或物件抽象 (object_abstract，請參閱 provider-object(7)) 編碼成編碼形式，並將結果寫入指定的 OSSL_CORE_BIO。如果呼叫者想要將編碼串流傳送至記憶體，則應提供 BIO_s_mem(3) BIO。

編碼器不需要知道 OSSL_CORE_BIO 指標的詳細資訊，只要能夠將其傳遞至適當的 BIO 上呼叫即可 (請參閱 provider-base(7) 中的「核心函式」)。

ENCODER 實作可能是鏈的一部分，其中資料會從一個傳遞至下一個。例如，可能有一個實作將物件編碼為 DER (假設該物件是提供者原生物件，因此透過 obj_raw 傳遞)，而另一個實作將 DER 編碼為 PEM (該實作會透過 obj_abstract 接收 DER 編碼)。

使用 OSSL_PARAM(3) 陣列形式進行編碼，讓編碼器可以針對從其他提供者匯出的資料使用，並因此讓它們可以獨立存在。

使用提供者端物件進行編碼僅能安全地與來自相同提供者的提供者資料搭配使用，例如具有 KEYMGMT 提供者的金鑰。

這裡提到的所有「函式」都以函式指標的形式在 OSSL_DISPATCH(3) 陣列中傳遞，透過 OSSL_ALGORITHM(3) 陣列 (由提供者的 provider_query_operation() 函式傳回) 在 libcrypto 和提供者之間傳遞 (請參閱 provider-base(7) 中的「提供者函式」)。

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

typedef int
    (OSSL_FUNC_encoder_encode_fn)(void *ctx, OSSL_CORE_BIO *out,
                                  const void *obj_raw,
                                  const OSSL_PARAM obj_abstract[],
                                  int selection,
                                  OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
static ossl_inline OSSL_FUNC_encoder_encode_fn
    OSSL_FUNC_encoder_encode(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_encoder_get_params          OSSL_FUNC_ENCODER_GET_PARAMS
OSSL_FUNC_encoder_gettable_params     OSSL_FUNC_ENCODER_GETTABLE_PARAMS

OSSL_FUNC_encoder_newctx              OSSL_FUNC_ENCODER_NEWCTX
OSSL_FUNC_encoder_freectx             OSSL_FUNC_ENCODER_FREECTX
OSSL_FUNC_encoder_set_ctx_params      OSSL_FUNC_ENCODER_SET_CTX_PARAMS
OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS

OSSL_FUNC_encoder_does_selection      OSSL_FUNC_ENCODER_DOES_SELECTION

OSSL_FUNC_encoder_encode              OSSL_FUNC_ENCODER_ENCODE

OSSL_FUNC_encoder_import_object       OSSL_FUNC_ENCODER_IMPORT_OBJECT
OSSL_FUNC_encoder_free_object         OSSL_FUNC_ENCODER_FREE_OBJECT

名稱和屬性

實作的名稱應與其處理的物件類型相符。例如，編碼 RSA 金鑰的實作應命名為「RSA」。同樣地，進一步編碼 DER 的實作應命名為「DER」。

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

輸出

此屬性用於指定實作產生的輸出類型。

此屬性為強制性。

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

文字: 具有該輸出類型的實作會輸出人類可讀的文字，使該實作適用於各種 openssl(1) 命令中的 -text 輸出。
pem: 具有該輸出類型的實作會輸出 PEM 格式化的資料。
der: 具有該輸出類型的實作會輸出 DER 格式化的資料。
msblob: 具有該輸出類型的實作會輸出 MSBLOB 格式化的資料。
pvk: 具有該輸出類型的實作會輸出 PVK 格式化的資料。

結構

此屬性用於指定編碼物件所使用的結構。例如，pkcs8，用於明確指定物件（在本例中可能是非對稱金鑰對）將作為編碼的一部分封裝在 PKCS#8 結構中。

此屬性為選用性。

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

子集選取

有時，物件有多個子集資料，可以分開或一起處理。可以指定要編碼哪些子集，方法是傳遞int 中的一組位元選取。

這組位元完全取決於傳遞哪種類型的提供者端物件。例如，當物件是非對稱金鑰對時，假設這些位元與 provider-keymgmt(7) 中使用的位元相同（請參閱 "Key Objects" in provider-keymgmt(7)）。

ENCODER 實作可以自由地將選取視為一組提示，但必須小心執行。最後，輸出必須有意義，如果有對應的解碼器，則產生的解碼物件必須與編碼的原始物件相符。

OSSL_FUNC_encoder_does_selection() 應告知特定實作是否支援選取給定的任何組合。

內容函式

OSSL_FUNC_encoder_newctx() 傳回一個內容，供其他函式使用。

OSSL_FUNC_encoder_freectx() 會釋放指定的 ctx，如果它是由 OSSL_FUNC_encoder_newctx() 所建立。

OSSL_FUNC_encoder_set_ctx_params() 會根據它辨識的 params 參數設定內容資料。未辨識的參數應予以忽略。傳遞 NULL 給 params 應傳回 true。

OSSL_FUNC_encoder_settable_ctx_params() 會傳回一個常數 OSSL_PARAM(3) 陣列，說明 OSSL_FUNC_encoder_set_ctx_params() 可以處理的參數。

請參閱 OSSL_PARAM(3) 以進一步了解 OSSL_FUNC_encoder_set_ctx_params() 和 OSSL_FUNC_encoder_settable_ctx_params() 所使用的參數結構。

匯入函式

供應商原生物件可能會與外部供應商相關聯，因此可能不適合與指定的 ENCODER 實作直接使用。只要外部供應商的實作有函式可以將該物件匯出成 OSSL_PARAM(3) 陣列形式，ENCODER 實作就應該能夠匯入該陣列，並建立一個適合傳遞給 OSSL_FUNC_encoder_encode() 的 obj_raw 的物件。

OSSL_FUNC_encoder_import_object() 應匯入 selection 所提供的 params 子集，以建立一個供應商原生物件，該物件可以作為 obj_raw 傳遞給 OSSL_FUNC_encoder_encode()。

OSSL_FUNC_encoder_free_object() 應釋放使用 OSSL_FUNC_encoder_import_object() 所建立的物件。

編碼函式

OSSL_FUNC_encoder_encode() 應採用供應商原生物件 (在 obj_raw 中) 或物件抽象 (在 obj_abstract 中)，並應將物件以編碼形式輸出到 OSSL_CORE_BIO。如果相關的話，selection 位元應更詳細地決定要輸出什麼。編碼函式也會採用 OSSL_PASSPHRASE_CALLBACK(3) 函式指標，以及應用程式資料指標 cbarg，這應在需要密語提示時使用。

編碼器操作參數

內建編碼器目前辨識的操作參數如下

"cipher" (OSSL_ENCODER_PARAM_CIPHER) <UTF8 字串>

在產生加密編碼時要使用的加密密碼名稱。這用於編碼私密金鑰，以及其他需要保護的物件。

如果此名稱對於編碼實作無效，實作應拒絕執行編碼，即 OSSL_FUNC_encoder_encode_data() 和 OSSL_FUNC_encoder_encode_object() 應傳回錯誤。

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

嘗試擷取使用 "cipher" 參數提供的演算法時要查詢的屬性。這必須與 "cipher" 參數一起提供，才算有效。

編碼實作沒有義務使用此值。但是，建議不處理屬性字串的實作在收到此參數時傳回錯誤，除非其值為 NULL 或空字串。

"儲存參數" (OSSL_ENCODER_PARAM_SAVE_PARAMETERS) <整數>

如果設為 0，將停用儲存金鑰網域參數。預設值為 1。目前僅對 DSA 金鑰有影響。

內建密碼短語回呼目前辨識的參數

"資訊" (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 字串>: 會成為密碼短語提示一部分的資訊字串。這可用於向使用者提供有關提示物件類型的資訊。

傳回值

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

OSSL_FUNC_encoder_set_ctx_params() 傳回 1，除非辨識的參數無效或造成錯誤，否則傳回 0。

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

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

OSSL_FUNC_encoder_encode() 在成功時傳回 1，或在失敗時傳回 0。

另請參閱

provider(7)

歷程

ENCODER 介面在 OpenSSL 3.0 中引入。

版權

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

開放SSL

密碼學和 SSL/TLS 工具組