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

EVP_PKEY-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-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 中获取副本。