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

provider-signature

名稱

provider-signature - 簽章函式庫 <-> 提供者函式

語法

#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_signature_newctx(void *provctx, const char *propq);
void OSSL_FUNC_signature_freectx(void *ctx);
void *OSSL_FUNC_signature_dupctx(void *ctx);

/* Signing */
int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey,
                                  const OSSL_PARAM params[]);
int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen,
                             size_t sigsize, const unsigned char *tbs, size_t tbslen);

/* Verifying */
int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey,
                                    const OSSL_PARAM params[]);
int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen,
                               const unsigned char *tbs, size_t tbslen);

/* Verify Recover */
int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey,
                                            const OSSL_PARAM params[]);
int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout,
                                       size_t *routlen, size_t routsize,
                                       const unsigned char *sig, size_t siglen);

/* Digest Sign */
int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname,
                                         void *provkey,
                                         const OSSL_PARAM params[]);
int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data,
                                    size_t datalen);
int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig,
                                          size_t *siglen, size_t sigsize);
int OSSL_FUNC_signature_digest_sign(void *ctx,
                             unsigned char *sig, size_t *siglen,
                             size_t sigsize, const unsigned char *tbs,
                             size_t tbslen);

/* Digest Verify */
int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname,
                                           void *provkey,
                                           const OSSL_PARAM params[]);
int OSSL_FUNC_signature_digest_verify_update(void *ctx,
                                             const unsigned char *data,
                                             size_t datalen);
int OSSL_FUNC_signature_digest_verify_final(void *ctx, const unsigned char *sig,
                                     size_t siglen);
int OSSL_FUNC_signature_digest_verify(void *ctx, const unsigned char *sig,
                               size_t siglen, const unsigned char *tbs,
                               size_t tbslen);

/* Signature parameters */
int OSSL_FUNC_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_signature_gettable_ctx_params(void *ctx,
                                                          void *provctx);
int OSSL_FUNC_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_signature_settable_ctx_params(void *ctx,
                                                          void *provctx);
/* MD parameters */
int OSSL_FUNC_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM * OSSL_FUNC_signature_gettable_ctx_md_params(void *ctx);
int OSSL_FUNC_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM * OSSL_FUNC_signature_settable_ctx_md_params(void *ctx);

說明

此文件主要針對提供者作者。請參閱 provider(7) 以取得更多資訊。

簽章 (OSSL_OP_SIGNATURE) 作業讓提供者能夠實作簽章演算法，並透過 API 函式 EVP_PKEY_sign(3)、EVP_PKEY_verify(3) 和 EVP_PKEY_verify_recover(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_signature_newctx() 具有下列

typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx, const char *propq);
static ossl_inline OSSL_FUNC_signature_newctx_fn
    OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_signature_newctx                 OSSL_FUNC_SIGNATURE_NEWCTX
OSSL_FUNC_signature_freectx                OSSL_FUNC_SIGNATURE_FREECTX
OSSL_FUNC_signature_dupctx                 OSSL_FUNC_SIGNATURE_DUPCTX

OSSL_FUNC_signature_sign_init              OSSL_FUNC_SIGNATURE_SIGN_INIT
OSSL_FUNC_signature_sign                   OSSL_FUNC_SIGNATURE_SIGN

OSSL_FUNC_signature_verify_init            OSSL_FUNC_SIGNATURE_VERIFY_INIT
OSSL_FUNC_signature_verify                 OSSL_FUNC_SIGNATURE_VERIFY

OSSL_FUNC_signature_verify_recover_init    OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT
OSSL_FUNC_signature_verify_recover         OSSL_FUNC_SIGNATURE_VERIFY_RECOVER

OSSL_FUNC_signature_digest_sign_init       OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT
OSSL_FUNC_signature_digest_sign_update     OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE
OSSL_FUNC_signature_digest_sign_final      OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL
OSSL_FUNC_signature_digest_sign            OSSL_FUNC_SIGNATURE_DIGEST_SIGN

OSSL_FUNC_signature_digest_verify_init     OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT
OSSL_FUNC_signature_digest_verify_update   OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE
OSSL_FUNC_signature_digest_verify_final    OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL
OSSL_FUNC_signature_digest_verify          OSSL_FUNC_SIGNATURE_DIGEST_VERIFY

OSSL_FUNC_signature_get_ctx_params         OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS
OSSL_FUNC_signature_gettable_ctx_params    OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS
OSSL_FUNC_signature_set_ctx_params         OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS
OSSL_FUNC_signature_settable_ctx_params    OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS

OSSL_FUNC_signature_get_ctx_md_params      OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS
OSSL_FUNC_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS
OSSL_FUNC_signature_set_ctx_md_params      OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS
OSSL_FUNC_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS

簽章演算法實作可能無法實作所有這些函式。為了成為一組一致的函式，我們至少必須具備一組內容函式（OSSL_FUNC_signature_newctx 和 OSSL_FUNC_signature_freectx），以及一組「簽章」函式，亦即至少下列其中一個

OSSL_FUNC_signature_sign_init 和 OSSL_FUNC_signature_sign
OSSL_FUNC_signature_verify_init 和 OSSL_FUNC_signature_verify
OSSL_FUNC_signature_verify_recover_init 和 OSSL_FUNC_signature_verify_recover
OSSL_FUNC_signature_digest_sign_init、OSSL_FUNC_signature_digest_sign_update 和 OSSL_FUNC_signature_digest_sign_final
OSSL_FUNC_signature_digest_verify_init、OSSL_FUNC_signature_digest_verify_update 和 OSSL_FUNC_signature_digest_verify_final
OSSL_FUNC_signature_digest_sign_init 和 OSSL_FUNC_signature_digest_sign
OSSL_FUNC_signature_digest_verify_init 和 OSSL_FUNC_signature_digest_verify

OSSL_FUNC_signature_set_ctx_params 和 OSSL_FUNC_signature_settable_ctx_params 是可選的，但如果其中一個存在，則另一個也必須存在。OSSL_FUNC_signature_get_ctx_params 和 OSSL_FUNC_signature_gettable_ctx_params 以及「md_params」函式也適用相同規則。OSSL_FUNC_signature_dupctx 函式是可選的。

簽章演算法也必須實作一些機制，透過金鑰管理 (OSSL_OP_KEYMGMT) 作業來產生、載入或匯入金鑰。請參閱 provider-keymgmt(7) 以取得進一步的詳細資料。

內容管理函式

OSSL_FUNC_signature_newctx() 應建立並傳回一個指標，指向提供者端結構，以在簽章作業期間保留內容資訊。此內容的指標將在許多其他簽章作業函式呼叫中傳回。參數 provctx 是在提供者初始化期間產生的提供者內容 (請參閱 provider(7))。propq 參數是一個屬性查詢字串，提供者可能會在執行任何「擷取」時使用 (如果執行任何「擷取」)。

OSSL_FUNC_signature_freectx() 傳入一個指標，指向 ctx 參數中的提供者端簽章內容。此函式應釋放與該內容相關的任何資源。

OSSL_FUNC_signature_dupctx() 應複製 ctx 參數中的提供者端簽章內容，並傳回複製的副本。

簽署函式

OSSL_FUNC_signature_sign_init() 初始化一個內容，以簽署 ctx 參數中提供的提供者端簽章內容，以及 provkey 參數中提供者金鑰物件的指標。如果 params 不為 NULL，應以類似於使用 OSSL_FUNC_signature_set_ctx_params() 的方式設定內容。金鑰物件應已先使用金鑰管理 (OSSL_OP_KEYMGMT) 作業產生、載入或匯入提供者 (請參閱 provider-keymgmt(7)>)。

OSSL_FUNC_signature_sign() 執行實際的簽署。先前初始化的簽章內容傳入 ctx 參數。要簽署的資料由 tbs 參數指向，長度為 tbslen 位元組。除非 sig 為 NULL，否則應將簽章寫入 sig 參數指向的位置，且長度不得超過 sigsize 位元組。應將簽章長度寫入 *siglen。如果 sig 為 NULL，則應將簽章的最大長度寫入 *siglen。

驗證函式

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

OSSL_FUNC_signature_verify() 執行實際驗證本身。先前初始化的簽章內容傳遞在 ctx 參數中。簽章涵蓋的資料指向 tbs 參數，長度為 tbslen 位元組。簽章由 sig 參數指向，長度為 siglen 位元組。

驗證還原函數

OSSL_FUNC_signature_verify_recover_init() 初始化一個還原已簽署資料的內容，給定提供者端的簽章內容在 ctx 參數中，以及指向提供者金鑰物件的指標在 provkey 參數中。如果 params 不是 NULL，應以類似於使用 OSSL_FUNC_signature_set_ctx_params() 的方式設定在內容中。金鑰物件應先前使用金鑰管理 (OSSL_OP_KEYMGMT) 作業產生、載入或匯入到提供者中 (請參閱 provider-keymgmt(7)>。

OSSL_FUNC_signature_verify_recover() 執行實際驗證還原本身。先前初始化的簽章內容傳遞在 ctx 參數中。簽章由 sig 參數指向，長度為 siglen 位元組。除非 rout 是 NULL，否則應將還原的資料寫入 rout 指向的位置，其長度不應超過 routsize 位元組。應將還原資料的長度寫入 *routlen。如果 rout 是 NULL，則將輸出緩衝區的最大大小寫入 routlen 參數。

摘要簽署函數

OSSL_FUNC_signature_digeset_sign_init() 初始化一個簽署的內容，給定提供者端的簽章內容在 ctx 參數中，以及指向提供者金鑰物件的指標在 provkey 參數中。如果 params 不是 NULL，應以類似於使用 OSSL_FUNC_signature_set_ctx_params() 和 OSSL_FUNC_signature_set_ctx_md_params() 的方式設定在內容中。金鑰物件應先前使用金鑰管理 (OSSL_OP_KEYMGMT) 作業產生、載入或匯入到提供者中 (請參閱 provider-keymgmt(7)>。要使用的摘要名稱將在 mdname 參數中。

OSSL_FUNC_signature_digest_sign_update() 提供要簽署的資料在 data 參數中，其長度應為 datalen。先前初始化的簽章內容傳遞在 ctx 參數中。此函數可呼叫多次以累計新增要簽署的資料。

OSSL_FUNC_signature_digest_sign_final() 完成先前透過 OSSL_FUNC_signature_digest_sign_init() 和 OSSL_FUNC_signature_digest_sign_update() 呼叫所啟動的簽章作業。完成後，將不會再透過 OSSL_FUNC_signature_digest_sign_update() 新增資料。先前初始化的簽章內容會傳遞至 ctx 參數。除非 sig 為 NULL，否則應將簽章寫入 sig 參數所指的位置，且其長度不得超過 sigsize 位元組。簽章的長度應寫入 *siglen。如果 sig 為 NULL，則應將簽章的最大長度寫入 *siglen。

OSSL_FUNC_signature_digest_sign() 實作先前透過 OSSL_FUNC_signature_digeset_sign_init() 啟動的「一次性」摘要簽章作業。先前初始化的簽章內容會傳遞至 ctx 參數。待簽章的資料位於 tbs 中，其長度應為 tbslen 位元組。除非 sig 為 NULL，否則應將簽章寫入 sig 參數所指的位置，且其長度不得超過 sigsize 位元組。簽章的長度應寫入 *siglen。如果 sig 為 NULL，則應將簽章的最大長度寫入 *siglen。

摘要驗證函數

OSSL_FUNC_signature_digeset_verify_init() 初始化驗證的內容，其中 ctx 參數為提供者端的驗證內容，而 provkey 參數為指向提供者金鑰物件的指標。如果 params 不為 NULL，應以類似於 OSSL_FUNC_signature_set_ctx_params() 和 OSSL_FUNC_signature_set_ctx_md_params() 的方式設定內容。金鑰物件應先前使用金鑰管理 (OSSL_OP_KEYMGMT) 作業產生、載入或匯入至提供者 (請參閱 provider-keymgmt(7)>)。待使用的摘要名稱會位於 mdname 參數中。

OSSL_FUNC_signature_digest_verify_update() 提供待驗證的資料，位於 data 參數中，其長度應為 datalen。先前初始化的驗證內容會傳遞至 ctx 參數。可以多次呼叫此函數，以累加待驗證的資料。

OSSL_FUNC_signature_digest_verify_final() 完成先前透過 OSSL_FUNC_signature_digest_verify_init() 和 OSSL_FUNC_signature_digest_verify_update() 呼叫所啟動的驗證作業。完成後，將不會再透過 OSSL_FUNC_signature_digest_verify_update() 新增資料。先前初始化的驗證內容會傳遞至 ctx 參數。待驗證的簽章位於 sig 中，其長度為 siglen 位元組。

OSSL_FUNC_signature_digest_verify() 實作先前透過 OSSL_FUNC_signature_digeset_verify_init() 啟動的「一次性」摘要驗證作業。先前初始化的驗證內容會傳遞至 ctx 參數。待驗證的資料位於 tbs 中，其長度應為 tbslen 位元組。待驗證的簽章位於 sig 中，其長度為 siglen 位元組。

簽章參數

有關 OSSL_FUNC_signature_get_ctx_params() 和 OSSL_FUNC_signature_set_ctx_params() 函式所使用的參數結構，請參閱 OSSL_PARAM(3)。

OSSL_FUNC_signature_get_ctx_params() 會取得與給定提供者端簽章內容 ctx 相關的簽章參數，並將其儲存在 params 中。如果 params 傳遞 NULL，則應傳回 true。

OSSL_FUNC_signature_set_ctx_params() 會將與給定提供者端簽章內容 ctx 相關的簽章參數設定為 params。任何參數設定都會附加到先前設定的任何參數。如果 params 傳遞 NULL，則應傳回 true。

內建簽章演算法目前識別的常見參數如下。

"摘要" (OSSL_SIGNATURE_PARAM_DIGEST) <UTF8 字串>: 取得或設定用於簽章函式輸入的摘要演算法名稱。這是計算「演算法識別碼」的必要條件。
"屬性" (OSSL_SIGNATURE_PARAM_PROPERTIES) <UTF8 字串>: 設定與「摘要」演算法相關的屬性查詢名稱。如果未設定這個選用值，則使用 NULL。
"摘要大小" (OSSL_SIGNATURE_PARAM_DIGEST_SIZE) <無符號整數>: 取得或設定用於簽章函式輸入的摘要演算法的輸出大小。「摘要大小」參數的長度不應超過 size_t。
"演算法識別碼" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <八進位字串>: 取得與簽章作業的簽章演算法和摘要演算法組合相符的 DER 編碼 AlgorithmIdentifier。
"隨機數類型" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <無符號整數>: 將此設定為 1，以使用 RFC 6979 中定義的 ECDSA 或 DSA 確定性數位簽章產生 (請參閱第 3.2 節「產生 k」)。在這種情況下，必須明確設定「摘要」參數 (否則，確定性隨機數產生將會失敗)。在使用確定性數位簽章產生之前，請閱讀 RFC 6979 第 4 節「安全性考量」。「隨機數類型」的預設值為 0，會導致使用 FIPS 186-4 第 6.3 節「機密數字產生」中定義的隨機值作為隨機數 k。
"已知答案測試" (OSSL_SIGNATURE_PARAM_KAT) <無符號整數>: 設定旗標，以修改簽章作業，如果初始計算的簽章無效，則傳回錯誤。在正常作業模式中，會選擇新的隨機值，直到簽章作業成功。預設情況下，它會重試，直到計算出簽章。將值設定為 0 會導致簽章作業重試，否則簽章作業只會嘗試一次，並傳回是否成功。如果覆寫隨機產生器以提供通過或失敗的已知值，則可以執行已知答案測試。

OSSL_FUNC_signature_gettable_ctx_params() 和 OSSL_FUNC_signature_settable_ctx_params() 會取得一個常數 OSSL_PARAM(3) 陣列，用來描述可取得和可設定的參數，亦即分別可與 OSSL_FUNC_signature_get_ctx_params() 和 OSSL_FUNC_signature_set_ctx_params() 搭配使用的參數。

MD 參數

有關 OSSL_FUNC_signature_get_md_ctx_params() 和 OSSL_FUNC_signature_set_md_ctx_params() 函式所使用的參數結構，請參閱 OSSL_PARAM(3)。

OSSL_FUNC_signature_get_md_ctx_params() 取得與給定的提供者端摘要簽章內容 ctx 相關的摘要參數，並將其儲存在 params 中。傳遞 NULL 給 params 應傳回 true。

OSSL_FUNC_signature_set_ms_ctx_params() 將與給定的提供者端摘要簽章內容 ctx 相關的摘要參數設定為 params。任何參數設定都會新增到先前設定的參數中。傳遞 NULL 給 params 應傳回 true。

內建簽章演算法目前識別的參數與內建摘要演算法的參數相同。請參閱 provider-digest(7) 中的「摘要參數」以取得更多資訊。

OSSL_FUNC_signature_gettable_md_ctx_params() 和 OSSL_FUNC_signature_settable_md_ctx_params() 取得描述可取得和可設定摘要參數的常數 OSSL_PARAM(3) 陣列，亦即可以分別與 OSSL_FUNC_signature_get_md_ctx_params() 和 OSSL_FUNC_signature_set_md_ctx_params() 搭配使用的參數。

傳回值

OSSL_FUNC_signature_newctx() 和 OSSL_FUNC_signature_dupctx() 應傳回新建立的提供者端簽章內容，或在失敗時傳回 NULL。

OSSL_FUNC_signature_gettable_ctx_params()、OSSL_FUNC_signature_settable_ctx_params()、OSSL_FUNC_signature_gettable_md_ctx_params() 和 OSSL_FUNC_signature_settable_md_ctx_params() 在常數 OSSL_PARAM(3) 陣列中傳回可取得或可設定的參數。

所有其他函式應傳回 1 表示成功，或在發生錯誤時傳回 0。

另請參閱

provider(7)

歷程

provider SIGNATURE 介面在 OpenSSL 3.0 中引入。

著作權

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

開放SSL

密碼學和 SSL/TLS 工具組