/docs/man3.3/man7/EVP_KEYMGMT-EC.html

EVP_KEYMGMT-EC

名稱

EVP_PKEY-EC、EVP_KEYMGMT-EC - EVP_PKEY EC 金鑰類型和演算法支援

說明

EC 金鑰類型已在 OpenSSL 的預設提供者中實作。

常見 EC 參數

指定 EC 曲線的網域參數的正常方式是透過曲線名稱「群組」。對於沒有曲線名稱的曲線，可以使用明確參數來指定「欄位類型」、「p」、「a」、「b」、「產生器」和「順序」。明確參數基於向後相容性的理由而獲得支援，但它們不符合僅允許命名曲線的多個標準（包括 RFC5915）。

下列 KeyGen/可取得/匯入/匯出類型可供內建 EC 演算法使用

「群組」(OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 字串>

曲線名稱。

「欄位類型」(OSSL_PKEY_PARAM_EC_FIELD_TYPE) <UTF8 字串>

值應為「質數欄位」或「特徵二欄位」，分別對應於質數欄位 Fp 和二元欄位 F2^m。

「p」(OSSL_PKEY_PARAM_EC_P) <無符號整數>

對於 Fp 上的曲線，p 是欄位的質數。對於 F2^m 上的曲線，p 代表不可約多項式 - 每個位元代表多項式中的項次。因此，將會設定三個或五個位元，具體取決於多項式是三項式還是五項式。

「a」(OSSL_PKEY_PARAM_EC_A) <無符號整數>

「b」(OSSL_PKEY_PARAM_EC_B) <無符號整數>

「種子」(OSSL_PKEY_PARAM_EC_SEED) <八位元組字串>

a 和 b 代表曲線的係數，對於 Fp：y^2 mod p = x^3 +ax + b mod p，或對於 F2^m：y^2 + xy = x^3 + ax^2 + b

種子是僅供參考的選用值。它代表用於從亂數產生係數 b 的亂數種子。

「產生器」(OSSL_PKEY_PARAM_EC_GENERATOR) <八位元組字串>

「順序」(OSSL_PKEY_PARAM_EC_ORDER) <無符號整數>

「餘因子」(OSSL_PKEY_PARAM_EC_COFACTOR) <無符號整數>

產生器是曲線上一個定義良好的點，用於加密操作。編碼符合 SECG SEC 1（「橢圓曲線密碼學」）標準的第 2.3.3 節。請參閱 EC_POINT_oct2point()。用於點乘法的整數介於 0 和階數 - 1 之間。餘因子是一個選用值。階數乘以餘因子會得出曲線上的點數。

「從明確參數解碼」（OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS）<整數>

取得一個旗標，指出金鑰或參數是否從明確曲線參數解碼。如果是，則設定為 1，如果使用命名曲線，則設定為 0。

「使用餘因子旗標」（OSSL_PKEY_PARAM_USE_COFACTOR_ECDH）<整數>

如果此值為 1，則啟用餘因子 DH（ECC CDH），否則如果值為零，則使用一般 EC DH。餘因子變體會將共用密鑰乘以 EC 曲線的餘因子（注意，某些曲線的餘因子為 1）。

另請參閱 EVP_KEYEXCH-ECDH(7)，以取得相關的 OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE 參數，可以在每個操作的基礎上設定。

「編碼」（OSSL_PKEY_PARAM_EC_ENCODING）<UTF8 字串>

設定用於序列化 EC 群組參數的格式。有效值為「明確」或「命名曲線」。預設值為「命名曲線」。

「點格式」（OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT）<UTF8 字串>

設定或取得金鑰的 point_conversion_form。有關 point_conversion_forms 的說明，請參閱 EC_POINT_new(3)。有效值為「未壓縮」或「壓縮」。預設值為「未壓縮」。

「群組檢查」（OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE）<UTF8 字串>

設定或取得在呼叫 EVP_PKEY_param_check() 時執行的群組檢查類型。有效值為「預設」、「已命名」和「已命名-nist」。「已命名」類型會檢查網域參數是否與內建曲線參數相符，「已命名-nist」類似，但也會檢查已命名曲線是否為 nist 曲線。「預設」類型會針對 OpenSSL 預設提供者進行網域參數驗證，但對於 OpenSSL FIPS 提供者而言，等同於「已命名-nist」。

「包含公開」（OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC）<整數>

將此值設定為 0 表示編碼私鑰時不應包含公開金鑰。預設值 1 會包含公開金鑰。

"pub" (OSSL_PKEY_PARAM_PUB_KEY) <八位元組字串>

公鑰值採用編碼的 EC 點格式，符合 SECG SEC 1（「橢圓曲線密碼學」）標準的第 2.3.3 和 2.3.4 節。此參數用於透過 EVP_PKEY_fromdata() 和 EVP_PKEY_todata() 函數匯入或匯出公鑰值。

特別注意，用於透過 EVP_PKEY_todata() 編碼匯出值的點壓縮格式的選擇取決於底層提供者實作。在 OpenSSL 3.0.8 之前，OpenSSL 附帶的提供者實作總是無條件選擇以壓縮格式編碼。自 OpenSSL 3.0.8 起，實作已變更為尊重 OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT 參數（如果已設定），或預設為未壓縮格式。

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <無符號整數>

私鑰值。

"encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <八位元組字串>

用於取得和設定 EC 公鑰的編碼。公鑰預期為符合 SECG SEC 1（「橢圓曲線密碼學」）標準第 2.3.4 節的點。

"qx" (OSSL_PKEY_PARAM_EC_PUB_X) <無符號整數>

用於取得 EC 公鑰 X 組成元件。

"qy" (OSSL_PKEY_PARAM_EC_PUB_Y) <無符號整數>

用於取得 EC 公鑰 Y 組成元件。

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

取得預設摘要名稱的 getter。（截至 OpenSSL 3.0，目前傳回「SHA256」）

"dhkem-ikm" (OSSL_PKEY_PARAM_DHKEM_IKM) <八位元組字串>

DHKEM 需要使用輸入金鑰材料（種子）產生金鑰對。使用此項指定用於產生私鑰的金鑰材料。此值不應重複用於其他目的。它只能用於曲線「P-256」、「P-384」和「P-521」，且長度應至少等於編碼私鑰的大小（即列出的曲線為 32、48 和 66）。

內建 EC 演算法也提供下列可取得的類型

"basis-type" (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8 字串>

支援三項式的「tpBasis」值或五項式的「ppBasis」值。此欄位僅用於二元域 F2^m。

"m" (OSSL_PKEY_PARAM_EC_CHAR2_M) <整數>

"tp" (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS) <整數>

"k1" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1) <整數>

"k2" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2) <整數>

"k3" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3) <整數>

這些欄位僅用於二元域 F2^m。m 是二元域的次方。

tp 是三項式的中間位元，因此其值必須在 m > tp > 0 範圍內。

k1、k2 和 k3 用於取得五項式的中間位元，使得 m > k3 > k2 > k1 > 0

EC 金鑰驗證

對於 EC 金鑰，EVP_PKEY_param_check(3) 的行為方式如下：對於 OpenSSL 預設提供者，它會根據 EC_FLAG_CHECK_NAMED_GROUP 旗標使用 EC_GROUP_check(3) 或 EC_GROUP_check_named_curve(3)。OpenSSL FIPS 提供者使用 EC_GROUP_check_named_curve(3) 以符合 SP800-56Ar3 保證網域參數有效性。

對於 EC 金鑰，EVP_PKEY_param_check_quick(3) 等同於 EVP_PKEY_param_check(3)。

對於 EC 金鑰，EVP_PKEY_public_check(3) 和 EVP_PKEY_public_check_quick(3) 分別符合 SP800-56Ar3 ECC 完整公鑰驗證和 ECC 部分公鑰驗證。

對於 EC 金鑰，EVP_PKEY_private_check(3) 和 EVP_PKEY_pairwise_check(3) 分別符合 SP800-56Ar3 私人金鑰有效性 和 成對一致性的所有者保證。

範例

可以透過呼叫來取得 EVP_PKEY 內容

EVP_PKEY_CTX *pctx =
    EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);

可以透過呼叫來產生具有「P-256」命名群組的 EVP_PKEY ECDSA 或 ECDH 金鑰

pkey = EVP_EC_gen("P-256");

或像這樣

EVP_PKEY *key = NULL;
OSSL_PARAM params[2];
EVP_PKEY_CTX *gctx =
    EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);

EVP_PKEY_keygen_init(gctx);

params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
                                             "P-256", 0);
params[1] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(gctx, params);

EVP_PKEY_generate(gctx, &key);

EVP_PKEY_print_private(bio_out, key, 0, NULL);
...
EVP_PKEY_free(key);
EVP_PKEY_CTX_free(gctx);

可以透過呼叫來產生具有「K-571」命名群組的 EVP_PKEY EC CDH（餘因子 Diffie-Hellman）金鑰

int use_cdh = 1;
EVP_PKEY *key = NULL;
OSSL_PARAM params[3];
EVP_PKEY_CTX *gctx =
    EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);

EVP_PKEY_keygen_init(gctx);

params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
                                             "K-571", 0);
/*
 * This curve has a cofactor that is not 1 - so setting CDH mode changes
 * the behaviour. For many curves the cofactor is 1 - so setting this has
 * no effect.
 */
params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
                                     &use_cdh);
params[2] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(gctx, params);

EVP_PKEY_generate(gctx, &key);
EVP_PKEY_print_private(bio_out, key, 0, NULL);
...
EVP_PKEY_free(key);
EVP_PKEY_CTX_free(gctx);

另請參閱

EVP_EC_gen(3)、EVP_KEYMGMT(3)、EVP_PKEY(3)、provider-keymgmt(7)、EVP_SIGNATURE-ECDSA(7)、EVP_KEYEXCH-ECDH(7)

版權

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

開放SSL

密碼學和 SSL/TLS 工具包

EVP_KEYMGMT-EC

名稱

說明

常見 EC 參數

EC 金鑰驗證

範例

另請參閱

版權