/docs/man3.3/man7/EVP_PKEY-EC.html - OpenSSL 繁體中文

EVP_PKEY-EC

名稱

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

說明

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

常見的 EC 參數

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

內建 EC 演算法有下列 KeyGen/Gettable/Import/Export 類型可用

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

曲線名稱。

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

值應該是「prime-field」或「characteristic-two-field」，分別對應於質數欄位 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) <八位元組字串>

符合 SECG SEC 1 («橢圓曲線密碼學») 標準第 2.3.3 和 2.3.4 節的編碼 EC 點格式中的公開金鑰值。在使用 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) <unsigned integer>

私鑰值。

"encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>

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

"qx" (OSSL_PKEY_PARAM_EC_PUB_X) <unsigned integer>

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

"qy" (OSSL_PKEY_PARAM_EC_PUB_Y) <unsigned integer>

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

"default-digest" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>

取得器，傳回預設摘要名稱。（目前在 OpenSSL 3.0 中傳回「SHA256」）。

"dhkem-ikm" (OSSL_PKEY_PARAM_DHKEM_IKM) <octet string>

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

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

"basis-type" (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8 string>

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

"m" (OSSL_PKEY_PARAM_EC_CHAR2_M) <integer>

"tp" (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS) <integer>

"k1" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1) <integer>

"k2" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2) <integer>

"k3" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3) <integer>

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

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

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

EC 金鑰驗證

對於 EC 金鑰，EVP_PKEY_param_check(3) 的行為如下：對於 OpenSSL 預設提供者，它會使用 EC_GROUP_check(3) 或 EC_GROUP_check_named_curve(3)，視旗標 EC_FLAG_CHECK_NAMED_GROUP 而定。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_PKEY-EC

名稱

說明

常見的 EC 參數

EC 金鑰驗證

範例

另請參閱

版權