開啟SSL

密碼學和 SSL/TLS 工具包

provider-keymgmt

名稱

provider-keymgmt - KEYMGMT 函式庫 <-> 提供者函式

語法

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

/* Key object (keydata) creation and destruction */
void *OSSL_FUNC_keymgmt_new(void *provctx);
void OSSL_FUNC_keymgmt_free(void *keydata);

/* Generation, a more complex constructor */
void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection,
                                 const OSSL_PARAM params[]);
int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template);
int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx,
                                                        void *provctx);
void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg);
void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx);

/* Key loading by object reference, also a constructor */
void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz);

/* Key object information */
int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void *provctx);
int OSSL_FUNC_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_settable_params(void *provctx);

/* Key object content checks */
int OSSL_FUNC_keymgmt_has(const void *keydata, int selection);
int OSSL_FUNC_keymgmt_match(const void *keydata1, const void *keydata2,
                            int selection);

/* Discovery of supported operations */
const char *OSSL_FUNC_keymgmt_query_operation_name(int operation_id);

/* Key object import and export functions */
int OSSL_FUNC_keymgmt_import(void *keydata, int selection, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection);
const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types_ex(void *provctx, int selection);
int OSSL_FUNC_keymgmt_export(void *keydata, int selection,
                             OSSL_CALLBACK *param_cb, void *cbarg);
const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection);
const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types_ex(void *provctx, int selection);

/* Key object duplication, a constructor */
void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection);

/* Key object validation */
int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype);

說明

KEYMGMT 作業在 OpenSSL 函式庫中沒有太多公開能見度，它比較像是一個內部作業，設計為與使用私密/公開金鑰對的作業並行運作。

由於 KEYMGMT 作業與它並行運作的作業共享知識，因此它們必須屬於同一個提供者。OpenSSL 函式庫會確保它們屬於同一個提供者。

KEYMGMT 作業的主要責任是為 OpenSSL 函式庫 EVP_PKEY 結構保存提供者端金鑰資料。

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

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

typedef void *(OSSL_FUNC_keymgmt_new_fn)(void *provctx);
static ossl_inline OSSL_FUNC_keymgmt_new_fn
    OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_keymgmt_new                  OSSL_FUNC_KEYMGMT_NEW
OSSL_FUNC_keymgmt_free                 OSSL_FUNC_KEYMGMT_FREE

OSSL_FUNC_keymgmt_gen_init             OSSL_FUNC_KEYMGMT_GEN_INIT
OSSL_FUNC_keymgmt_gen_set_template     OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE
OSSL_FUNC_keymgmt_gen_set_params       OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS
OSSL_FUNC_keymgmt_gen_settable_params  OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS
OSSL_FUNC_keymgmt_gen                  OSSL_FUNC_KEYMGMT_GEN
OSSL_FUNC_keymgmt_gen_cleanup          OSSL_FUNC_KEYMGMT_GEN_CLEANUP

OSSL_FUNC_keymgmt_load                 OSSL_FUNC_KEYMGMT_LOAD

OSSL_FUNC_keymgmt_get_params           OSSL_FUNC_KEYMGMT_GET_PARAMS
OSSL_FUNC_keymgmt_gettable_params      OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
OSSL_FUNC_keymgmt_set_params           OSSL_FUNC_KEYMGMT_SET_PARAMS
OSSL_FUNC_keymgmt_settable_params      OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS

OSSL_FUNC_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME

OSSL_FUNC_keymgmt_has                  OSSL_FUNC_KEYMGMT_HAS
OSSL_FUNC_keymgmt_validate             OSSL_FUNC_KEYMGMT_VALIDATE
OSSL_FUNC_keymgmt_match                OSSL_FUNC_KEYMGMT_MATCH

OSSL_FUNC_keymgmt_import               OSSL_FUNC_KEYMGMT_IMPORT
OSSL_FUNC_keymgmt_import_types         OSSL_FUNC_KEYMGMT_IMPORT_TYPES
OSSL_FUNC_keymgmt_import_types_ex      OSSL_FUNC_KEYMGMT_IMPORT_TYPES_EX
OSSL_FUNC_keymgmt_export               OSSL_FUNC_KEYMGMT_EXPORT
OSSL_FUNC_keymgmt_export_types         OSSL_FUNC_KEYMGMT_EXPORT_TYPES
OSSL_FUNC_keymgmt_export_types_ex      OSSL_FUNC_KEYMGMT_EXPORT_TYPES_EX

OSSL_FUNC_keymgmt_dup                  OSSL_FUNC_KEYMGMT_DUP

金鑰物件

金鑰物件是非對稱金鑰資料的集合，在本手冊中表示為 keydata。

金鑰物件的確切內容由提供者定義，並且假設同一個提供者中的不同作業使用完全相同的結構來表示此資料集合，因此，例如，使用我們在此文件中檔的 KEYMGMT 介面建立的金鑰物件可以原樣傳遞給其他提供者作業，例如 OP_signature_sign_init()（請參閱 provider-signature(7)）。

使用部分 KEYMGMT 函式，可以選擇要處理的特定資料子集，由 selection 指標中的位元控制。這些位元是

OSSL_KEYMGMT_SELECT_PRIVATE_KEY

表示應考慮金鑰物件中的私密金鑰資料。

OSSL_KEYMGMT_SELECT_PUBLIC_KEY

表示應考慮金鑰物件中的公開金鑰資料。

OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS

表示應考慮金鑰物件中的網域參數。

OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS

表示應考慮金鑰物件中的其他參數。

其他參數是不符合任何其他分類的金鑰參數。換句話說，這個特定選擇器位元用作最後的手段位元桶選擇器。

有些選擇器位元也已合併以簡化使用

OSSL_KEYMGMT_SELECT_ALL_PARAMETERS

表示應考慮所有金鑰物件參數，不論其更細部的分類為何。

這是 OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS 和 OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS 的組合。

OSSL_KEYMGMT_SELECT_KEYPAIR

表示應考慮金鑰物件中的整個金鑰對，亦即公鑰和私鑰的組合。

這是 OSSL_KEYMGMT_SELECT_PRIVATE_KEY 和 OSSL_KEYMGMT_SELECT_PUBLIC_KEY 的組合。

OSSL_KEYMGMT_SELECT_ALL

表示應考慮金鑰物件中的所有內容。

這些位元的確切詮釋或其組合方式，交由您可以在其中指定選擇器的每個函式處理。

由提供者實作決定如何針對接收到的選擇器位元採取合理的動作，以及如何執行。在其他情況下，OSSL_FUNC_keymgmt_match() 的實作可能會選擇不比較私密的一半，如果它已比較公眾的一半，因為一半的配對意味著另一半也配對。

建構和解構函式

OSSL_FUNC_keymgmt_new() 應建立提供者端的金鑰物件。提供者內容 provctx 已傳遞，且可能會納入金鑰物件中，但這並非強制性的。

OSSL_FUNC_keymgmt_free() 應釋放已傳遞的 keydata。

OSSL_FUNC_keymgmt_gen_init()、OSSL_FUNC_keymgmt_gen_set_template()、OSSL_FUNC_keymgmt_gen_set_params()、OSSL_FUNC_keymgmt_gen_settable_params()、OSSL_FUNC_keymgmt_gen() 和 OSSL_FUNC_keymgmt_gen_cleanup() 共同作為一個更精細的基於內容的金鑰物件建構函式。

OSSL_FUNC_keymgmt_gen_init() 應建立金鑰物件產生內容並使用 selections 初始化它，這將決定要產生的金鑰物件應取得哪種類型的內容。如果 params 不為 NULL，應以類似使用 OSSL_FUNC_keymgmt_set_params() 的方式設定在內容中。

OSSL_FUNC_keymgmt_gen_set_template() 應將 template 加入內容 genctx。假設 template 是使用相同 KEYMGMT 建構的金鑰物件，且實作選擇的內容可用作要產生的金鑰物件的範本。通常，產生 DSA 或 DH 金鑰會從此 template 取得網域參數。

OSSL_FUNC_keymgmt_gen_set_params() 應從金鑰物件產生內容 genctx 中的 params 設定其他參數。

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

OSSL_FUNC_keymgmt_gen() 應執行金鑰物件產生本身，並傳回結果。呼叫回函數 cb 應定期呼叫，並指示金鑰物件產生進度。

OSSL_FUNC_keymgmt_gen_cleanup() 應清除並釋放金鑰物件產生內容 genctx

OSSL_FUNC_keymgmt_load() 會根據大小為 reference_sz 位元的 reference 物件建立提供者端金鑰物件，只有提供者知道如何詮釋，但可能來自其他作業。在提供者外部，此參考僅為位元組陣列。

OSSL_FUNC_keymgmt_new()、OSSL_FUNC_keymgmt_gen() 和 OSSL_FUNC_keymgmt_load() 其中至少一個是強制性的，以及 OSSL_FUNC_keymgmt_free() 和 OSSL_FUNC_keymgmt_has()。此外，如果存在 OSSL_FUNC_keymgmt_gen()，則 OSSL_FUNC_keymgmt_gen_init() 和 OSSL_FUNC_keymgmt_gen_cleanup() 也必須存在。

金鑰物件資訊函數

OSSL_FUNC_keymgmt_get_params() 應萃取與給定 keydata 相關的資訊資料，請參閱 "常見資訊參數"。

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

如果存在 OSSL_FUNC_keymgmt_gettable_params()，則 OSSL_FUNC_keymgmt_get_params() 也必須存在，反之亦然。

OSSL_FUNC_keymgmt_set_params() 應更新與給定 keydata 相關的資訊資料，請參閱 "常見資訊參數"。

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

如果存在 OSSL_FUNC_keymgmt_settable_params()，則 OSSL_FUNC_keymgmt_set_params() 也必須存在，反之亦然。

金鑰物件檢查函數

OSSL_FUNC_keymgmt_query_operation_name() 應傳回作業 operation_id 的支援演算法名稱。這類似於 provider_query_operation() (請參閱 provider-base(7))，但僅作為建議。如果此函數不存在或傳回 NULL，呼叫者可以自由假設有來自相同提供者、名稱與用於擷取 keymgmt 的演算法，並嘗試使用該演算法。

OSSL_FUNC_keymgmt_has() 應檢查給定的 keydata 是否包含 selector 指出的資料子集。多個選擇器位元的組合必須考量所有這些子集，而不僅僅是一個。然而，實作可以自由地將空的資料子集視為仍然是有效的子集。對於某些選擇沒有意義的演算法，例如 RSA 金鑰的 OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS，函數應僅傳回 1，因為所選的子集並未真正遺失在金鑰中。

OSSL_FUNC_keymgmt_validate() 應檢查 keydata 是否包含 selection 指出的有效資料子集。某些資料子集的組合選擇可能會造成組合資料的驗證。例如，預期 OSSL_KEYMGMT_SELECT_PRIVATE_KEY 和 OSSL_KEYMGMT_SELECT_PUBLIC_KEY（或簡稱 OSSL_KEYMGMT_SELECT_KEYPAIR）的組合會檢查 keydata 的成對一致性是否有效。checktype 參數控制對資料子集執行哪種類型的檢查。定義了兩種檢查類型：OSSL_KEYMGMT_VALIDATE_FULL_CHECK 和 OSSL_KEYMGMT_VALIDATE_QUICK_CHECK。如何詮釋在完整檢查和快速檢查中執行了多少檢查，這取決於金鑰類型。某些提供者可能不會區分完整檢查和快速檢查。對於某些選擇沒有意義的演算法，例如 RSA 金鑰的 OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS，函數應僅傳回 1，因為對於該選擇沒有任何需要驗證的內容。

OSSL_FUNC_keymgmt_match() 應檢查 keydata1 和 keydata2 中 selection 指出的資料子集是否相符。假設呼叫者已確保 keydata1 和 keydata2 都屬於此函數的實作。

金鑰物件匯入、匯出和複製函數

OSSL_FUNC_keymgmt_import() 應從 OSSL_PARAM(3) 陣列 params 中取得的值，將 selection 指出的資料匯入 keydata。

OSSL_FUNC_keymgmt_export() 應從 keydata 中萃取 selection 指出的值，建立一個包含這些值的 OSSL_PARAM(3) 陣列，並使用該陣列以及給定的 cbarg 呼叫 param_cb。

OSSL_FUNC_keymgmt_import_types() 和 OSSL_FUNC_keymgmt_import_types_ex() 應傳回描述符 OSSL_PARAM(3) 的常數陣列，以取得 selection 指出的資料，供 OSSL_FUNC_keymgmt_import() 處理的參數使用。必須實作 OSSL_FUNC_keymgmt_import_types() 或 OSSL_FUNC_keymgmt_import_types_ex()，如果實作了 OSSL_FUNC_keymgmt_import_types_ex()，則優先於 OSSL_FUNC_keymgmt_import_types()。假設與 OpenSSL 3.0 或 3.1 向後相容的提供者必須繼續實作 OSSL_FUNC_keymgmt_import_types()。

OSSL_FUNC_keymgmt_export_types() 和 OSSL_FUNC_keymgmt_export_types_ex() 應傳回描述符 OSSL_PARAM(3) 的常數陣列，以取得 selection 指出的資料，供 OSSL_FUNC_keymgmt_export() 回呼預期接收。必須實作 OSSL_FUNC_keymgmt_export_types() 或 OSSL_FUNC_keymgmt_export_types_ex()，如果實作了 OSSL_FUNC_keymgmt_export_types_ex()，則優先於 OSSL_FUNC_keymgmt_export_types()。假設與 OpenSSL 3.0 或 3.1 向後相容的提供者必須繼續實作 OSSL_FUNC_keymgmt_export_types()。

OSSL_FUNC_keymgmt_dup() 應複製 selection 指出的資料子集或整個金鑰資料 keydata_from，並使用資料建立一個新的提供者端金鑰物件。

共通資訊參數

有關參數結構的更多詳細資訊，請參閱 OSSL_PARAM(3)。

目前所有內建 keymgmt 演算法辨識的共通資訊參數如下

"bits" (OSSL_PKEY_PARAM_BITS) <整數>

此值應該是金鑰所屬密碼系統的密碼長度（以位元為單位）。密碼長度的定義特定於金鑰密碼系統。

"max-size" (OSSL_PKEY_PARAM_MAX_SIZE) <整數>

此值應該是呼叫者應該配置以安全儲存簽章（在 provider-signature(7) 中稱為 sig）、非對稱加密/解密結果（在 provider-asym_cipher(7) 中稱為 out）、衍生秘密（在 provider-keyexch(7) 中稱為 secret）和類似資料的最大大小。

提供者需要實作此參數才能適當地支援各種使用案例，例如 CMS 簽章。

由於 EVP_KEYMGMT 方法總是緊密繫結到另一個方法（簽章、非對稱密碼、金鑰交換，...）且必須來自同一個提供者，因此此數字只需要與同一個提供者中處理的維度同步。

"security-bits" (OSSL_PKEY_PARAM_SECURITY_BITS) <整數>

此值應該是給定金鑰的安全位元數。安全位元定義在 SP800-57 中。

"mandatory-digest" (OSSL_PKEY_PARAM_MANDATORY_DIGEST) <UTF8 字串>

如果使用此 keymgmt 中的金鑰執行簽章作業有強制摘要，此參數應取得其名稱作為值。

當 EVP_PKEY_get_default_digest_name() 查詢此參數且實作已填入時，其回傳值將為 2。

如果 keymgmt 實作填入值 "" 或 "UNDEF"，EVP_PKEY_get_default_digest_name(3) 會將字串 "UNDEF" 放入其引數 mdname 中。這表示不應在對應的簽章作業中指定摘要。

"default-digest" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 字串>

如果使用此 keymgmt 中的金鑰執行簽章作業有預設摘要，此參數應取得其名稱作為值。

當 EVP_PKEY_get_default_digest_name(3) 查詢此參數且實作已填入時，其回傳值將為 1。請注意，如果 OSSL_PKEY_PARAM_MANDATORY_DIGEST 也有回應，EVP_PKEY_get_default_digest_name(3) 會忽略對此參數的回應。

如果 keymgmt 實作填入值 "" 或 "UNDEF"，EVP_PKEY_get_default_digest_name(3) 會將字串 "UNDEF" 放入其引數 mdname 中。這表示不一定要在對應的簽章作業中指定摘要，但可以選擇指定。

傳回值

OSSL_FUNC_keymgmt_new() 和 OSSL_FUNC_keymgmt_dup() 應傳回新建立的提供者端金鑰物件的有效參考，或在失敗時傳回 NULL。

OSSL_FUNC_keymgmt_import()、OSSL_FUNC_keymgmt_export()、OSSL_FUNC_keymgmt_get_params() 和 OSSL_FUNC_keymgmt_set_params() 應傳回 1 表示成功，或在錯誤時傳回 0。

OSSL_FUNC_keymgmt_validate() 應在驗證成功時傳回 1，或在失敗時傳回 0。

如果所有選取的資料子集都包含在給定的 keydata 中，則 OSSL_FUNC_keymgmt_has() 應傳回 1，否則傳回 0。

OSSL_FUNC_keymgmt_query_operation_name() 應傳回指向與請求作業相符的字串指標，或如果用於擷取 keymgmt 的名稱相同，則傳回 NULL。

OSSL_FUNC_keymgmt_gettable_params() 和 OSSL_FUNC_keymgmt_settable_params() OSSL_FUNC_keymgmt_import_types()、OSSL_FUNC_keymgmt_import_types_ex()、OSSL_FUNC_keymgmt_export_types()、OSSL_FUNC_keymgmt_export_types_ex() 應始終傳回常數 OSSL_PARAM(3) 陣列。

另請參閱

EVP_PKEY_get_size(3)、EVP_PKEY_get_bits(3)、EVP_PKEY_get_security_bits(3)、provider(7)、EVP_PKEY-X25519(7)、EVP_PKEY-X448(7)、EVP_PKEY-ED25519(7)、EVP_PKEY-ED448(7)、EVP_PKEY-EC(7)、EVP_PKEY-RSA(7)、EVP_PKEY-DSA(7)、EVP_PKEY-DH(7)

歷程

KEYMGMT 介面在 OpenSSL 3.0 中引入。

OSSL_FUNC_keymgmt_import_types_ex() 和 OSSL_FUNC_keymgmt_export_types_ex() 函式在 OpenSSL 3.2 中新增。

Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.

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