EVP_PKEY-EC(7SSL)

📦

version 4.0.3 · 13 versions

💖 EVP_PKEY-EC, EVP_KEYMGMT-EC 💖

okay bestie, so this is the EVP_PKEY-EC(7SSL) page from the OpenSSL fam — it's literally all about the EVP_PKEY EC keytype and algorithm support. (There's also EVP_KEYMGMT-EC in there too, same vibe, same energy. 👑)

✨ DESCRIPTION ✨

The EC keytype lives in OpenSSL's default provider, bestie. That's its home. 🏠💅

🎀 Common EC parameters 🎀

So, the normal way to specify domain parameters for an EC curve is via the curve name "group". Simple, clean, iconic.

But for curves that don't have a curve name (yes, they exist), you can use explicit parameters instead, which specify "field-type", "p", "a", "b", "generator" and "order".

⚠️ real talk: explicit parameters are supported for backwards compatibility reasons only. They are not compliant with multiple standards (including RFC5915, which only allows named curves). so like, use them if you must, but know what you're doing. 🙈

The following Key generation/Gettable/Import/Export types are available for the built-in EC algorithm:

"group" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string> — the curve name. that's it, that's the girl. 💅
"field-type" (OSSL_PKEY_PARAM_EC_FIELD_TYPE) <UTF8 string> — this value should be either "prime-field" or "characteristic-two-field", which correspond to prime field Fp and binary field F2^m respectively. slay. ✨
"p" (OSSL_PKEY_PARAM_EC_P) <unsigned integer> — for a curve over Fp, p is the prime for the field. For a curve over F2^m, p represents the irreducible polynomial — each bit represents a term in the polynomial. So therefore, there will either be three or five bits set, dependent on whether the polynomial is a trinomial or a pentanomial. no cap. 🌸
"a" (OSSL_PKEY_PARAM_EC_A) <unsigned integer>
"b" (OSSL_PKEY_PARAM_EC_B) <unsigned integer>
"seed" (OSSL_PKEY_PARAM_EC_SEED) <octet string>

so a and b represent the coefficients of the curve. For Fp: y^2 mod p = x^3 +ax + b mod p OR For F2^m: y^2 + xy = x^3 + ax^2 + b

and seed is an optional value that is for information purposes only — it represents the random number seed used to generate the coefficient b from a random number. it's giving "receipts only, no gameplay". 🧚

"generator" (OSSL_PKEY_PARAM_EC_GENERATOR) <octet string>
"order" (OSSL_PKEY_PARAM_EC_ORDER) <unsigned integer>
"cofactor" (OSSL_PKEY_PARAM_EC_COFACTOR) <unsigned integer>

the generator is a well defined point on the curve, chosen for cryptographic operations. The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard. See EC_POINT_oct2point(). Integers used for point multiplications will be between 0 and order - 1. And cofactor is an optional value — order multiplied by the cofactor gives the number of points on the curve. math girlies rise up 🔥

"decoded-from-explicit" (OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS) <integer> — gets a flag indicating whether the key or parameters were decoded from explicit curve parameters. Set to 1 if so, or 0 if a named curve was used. 🦋
"use-cofactor-flag" (OSSL_PKEY_PARAM_USE_COFACTOR_ECDH) <integer> — enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH if the value is zero. The cofactor variant multiplies the shared secret by the EC curve's cofactor. (note for some curves the cofactor is 1, lmao.) And see also EVP_KEYEXCH-ECDH(7) for the related OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE parameter that can be set on a per-operation basis. 💜
"encoding" (OSSL_PKEY_PARAM_EC_ENCODING) <UTF8 string> — set the format used for serializing the EC group parameters. Valid values are "explicit" or "named_curve". The default value is "named_curve". 💖
"point-format" (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) <UTF8 string> — sets or gets the point_conversion_form for the key. For a description of point_conversion_forms please see EC_POINT_new(3). Valid values are "uncompressed" or "compressed". The default value is "uncompressed". ✨
"group-check" (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE) <UTF8 string> — sets or Gets the type of group check done when EVP_PKEY_param_check() is called. Valid values are "default", "named" and "named-nist". The "named" type checks that the domain parameters match the inbuilt curve parameters, "named-nist" is similar but also checks that the named curve is a nist curve. The "default" type does domain parameter validation for the OpenSSL default provider, but is equivalent to "named-nist" for the OpenSSL FIPS provider. she contains multitudes 💅
"include-public" (OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC) <integer> — setting this value to 0 indicates that the public key should not be included when encoding the private key. The default value of 1 will include the public key. 🫶
"pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string> — the public key value in encoded EC point format conforming to Sec. 2.3.3 and 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard. This parameter is used when importing or exporting the public key value with the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions.

note, in particular, that the choice of point compression format used for encoding the exported value via EVP_PKEY_todata() depends on the underlying provider implementation. Before OpenSSL 3.0.8, the implementation of providers included with OpenSSL always opted for an encoding in compressed format, unconditionally. Since OpenSSL 3.0.8, the implementation has been changed to honor the OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT parameter, if set, or to default to uncompressed format. glow-up behavior honestly 😭✨

"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer> — the private key value. keep her secret bestie. 🤫
"encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string> — used for getting and setting the encoding of an EC public key. The public key is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard. 🎀
"qx" (OSSL_PKEY_PARAM_EC_PUB_X) <unsigned integer> — used for getting the EC public key X component. ✨
"qy" (OSSL_PKEY_PARAM_EC_PUB_Y) <unsigned integer> — used for getting the EC public key Y component. ✨
"default-digest" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string> — getter that returns the default digest name. (Currently returns "SHA256" as of OpenSSL 3.0.) ⭐
"dhkem-ikm" (OSSL_PKEY_PARAM_DHKEM_IKM) <octet string> — DHKEM requires the generation of a keypair using an input key material (seed). Use this to specify the key material used for generation of the private key.

⚠️ this value should not be reused for other purposes. It can only be used for the curves "P-256", "P-384" and "P-521" and should have a length of at least the size of the encoded private key (i.e. 32, 48 and 66 for the listed curves). numbers girlies, you know the drill 🔢

The following Gettable types are also available for the built-in EC algorithm:

"field-degree" (OSSL_PKEY_PARAM_EC_FIELD_DEGREE) <integer> — this is the bit length of the curve's field coefficients. It coincides with the OSSL_PKEY_PARAM_EC_CHAR2_M parameter for binary fields, and is otherwise (for prime fields) equal to the bit length of the field's characteristic. For most curves (e.g. "secp160r1") this number is embedded in the curve's name. ✨
"basis-type" (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8 string> — supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial. This field is only used for a binary field 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>

these fields are only used for a binary field F2^m. m is the degree of the binary field.

tp is the middle bit of a trinomial so its value must be in the range m > tp > 0.

k1, k2 and k3 are used to get the middle bits of a pentanomial such that m > k3 > k2 > k1 > 0. the inequality chain is giving math class flashback 💀

The following key generation settable parameter is also available for the OpenSSL FIPS provider's EC algorithm:

"key-check" (OSSL_PKEY_PARAM_FIPS_KEY_CHECK) <integer> — see "Common Information Parameters" in provider-keymgmt(7) for descriptions of additional parameters generally available across all algorithms. 👑

The following key generation Gettable parameter is available for the OpenSSL FIPS provider's EC algorithm:

"fips-indicator" (OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR) <integer> — see "Common Information Parameters" in provider-keymgmt(7) for further information. ⭐

🔥 EC key validation 🔥

For EC keys, EVP_PKEY_param_check(3) behaves in the following way: For the OpenSSL default provider it uses either EC_GROUP_check(3) or EC_GROUP_check_named_curve(3) depending on the flag EC_FLAG_CHECK_NAMED_GROUP. The OpenSSL FIPS provider uses EC_GROUP_check_named_curve(3) in order to conform to SP800-56Ar3 Assurances of Domain-Parameter Validity. she's compliant, she's valid, she passed the vibe check. 💅

For EC keys, EVP_PKEY_param_check_quick(3) is equivalent to EVP_PKEY_param_check(3). same girl, faster outfit. ⚡

For EC keys, EVP_PKEY_public_check(3) and EVP_PKEY_public_check_quick(3) conform to SP800-56Ar3 ECC Full Public-Key Validation and ECC Partial Public-Key Validation respectively. 🦋

For EC Keys, EVP_PKEY_private_check(3) and EVP_PKEY_pairwise_check(3) conform to SP800-56Ar3 Private key validity and Owner Assurance of Pair-wise Consistency respectively. periodt. 🔥

✨ EXAMPLES ✨

ok bestie this is the part you actually came for, the copy-paste-able stuff 💅

🫶 Getting an `EVP_PKEY` context

you just call:

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

that's it. that's the whole vibe. one call, context acquired, slay ✨

🌸 Generating an ECDSA or ECDH key

want an EVP_PKEY ECDSA or ECDH key with the "P-256" named group? one line, no notes:

pkey = EVP_EC_gen("P-256");

iconic behaviour, honestly. 👑

🎀 …or the long way, if you're feeling extra

same result, more steps, main character energy:

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);

ok so walk with me: you make the context, you init the keygen, you build an OSSL_PARAM array with the group name and then an OSSL_PARAM_construct_end() to close it off (that terminator is NOT optional bestie, do not skip her 😭), you hand the params to the context, then you actually generate. then you do the cute little EVP_PKEY_print_private moment and free everything when you're done because we are responsible queens 🫶

🦋 Generating an `EVP_PKEY` EC CDH key

(Cofactor Diffie-Hellman, for the girlies who read the docs 📖) — here we go with the "K-571" named group:

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);

bestie read the comment, it's important i promise — this curve has a cofactor that is not 1, so flipping CDH mode actually changes the behaviour. for many curves the cofactor is 1, so setting this does literally nothing. no effect. zero. nada. 💀

also notice params is size 3 here (not 2 like before) because we're squeezing in that CDH param plus the group name plus the end. the end always gets the last slot. she's the closer, periodt. ✨

👀 SEE ALSO 👀

everything else you're gonna want to go read after this, in order:

go forth and cross-reference, nerd (affectionate) 🎀

📜 HISTORY 📜

the <hotpink>OSSL_PKEY_PARAM_EC_FIELD_DEGREE</hotpink> parameter? yeah she was added in OpenSSL 4.0. newcomer. fresh face. baby of the family 🍼✨

💖 COPYRIGHT 💖

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

ok that's the whole page bestie, you made it to the end, i'm so proud of you 😭🫶

this version is from OpenSSL 4.0.3, dated 2026-09-29, and it's the EVP_PKEY-EC(7SSL) manual page — go generate some keys, hydrate, and don't forget to free your contexts 💜🌈⭐

📦 where this page comes from

ubuntu stonking: openssl 4.0.3-1ubuntu1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms