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

EVP_KEYMGMT-EC

名称

EVP_PKEY-EC, EVP_KEYMGMT-EC - EVP_PKEY EC 密钥类型和算法支持

描述

EC密钥类型在OpenSSL的默认提供程序中实现。

常用EC参数

指定EC曲线的域参数的正常方式是通过曲线名称“group”。对于没有曲线名称的曲线，可以使用显式参数，这些参数指定“field-type”、“p”、“a”、“b”、“generator”和“order”。出于向后兼容性的原因，支持显式参数，但它们不符合多个标准（包括RFC5915），这些标准只允许命名曲线。

以下KeyGen/Gettable/Import/Export类型可用于内置的EC算法

"group" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8字符串>

曲线名称。

"field-type" (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) <无符号整数>

"seed" (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

seed是一个可选值，仅供参考。它表示用于从随机数生成系数b的随机数种子。

"generator" (OSSL_PKEY_PARAM_EC_GENERATOR) <八位字节字符串>

"order" (OSSL_PKEY_PARAM_EC_ORDER) <无符号整数>

"cofactor" (OSSL_PKEY_PARAM_EC_COFACTOR) <无符号整数>

generator是曲线上为密码学运算选择的明确点。编码符合SECG SEC 1（“椭圆曲线密码学”）标准的第2.3.3节。参见EC_POINT_oct2point()。用于点乘法的整数将在0到order - 1之间。cofactor是一个可选值。order乘以cofactor得到曲线上点的数量。

"decoded-from-explicit" (OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS) <整数>

获取一个标志，指示密钥或参数是否从显式曲线参数解码。如果是，则设置为1；如果是使用命名曲线，则设置为0。

"use-cofactor-flag" (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参数。

"encoding" (OSSL_PKEY_PARAM_EC_ENCODING) <UTF8字符串>

设置用于序列化EC组参数的格式。有效值为“explicit”或“named_curve”。默认值为“named_curve”。

"point-format" (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) <UTF8字符串>

设置或获取key的point_conversion_form。有关point_conversion_form的描述，请参见EC_POINT_new(3)。有效值为“uncompressed”或“compressed”。默认值为“uncompressed”。

"group-check" (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE) <UTF8字符串>

设置或获取调用EVP_PKEY_param_check()时执行的组检查类型。有效值为“default”、“named”和“named-nist”。“named”类型检查域参数是否与内置曲线参数匹配，“named-nist”类似，但还检查命名曲线是否为nist曲线。“default”类型对OpenSSL默认提供程序执行域参数验证，但对于OpenSSL FIPS提供程序等效于“named-nist”。

"include-public" (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) <无符号整数>

私钥值。

"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字符串>

获取器，返回默认摘要名称。（截至OpenSSL 3.0，当前返回“SHA256”）。

"dhkem-ikm" (OSSL_PKEY_PARAM_DHKEM_IKM) <八位字节字符串>

DHKEM要求使用输入密钥材料（种子）生成密钥对。使用此方法指定用于生成私钥的密钥材料。此值不应重复用于其他目的。它只能用于“P-256”、“P-384”和“P-521”曲线，并且长度应至少与编码的私钥大小相同（即列出曲线的32、48和66）。

以下Gettable类型也可用于内置的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_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-56Ar3ECC完整公钥验证和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获取副本。