Provided by: openssl_3.3.1-2ubuntu2_amd64 
NAME
EVP_PKEY-EC, EVP_KEYMGMT-EC - EVP_PKEY EC keytype and algorithm support
DESCRIPTION
The EC keytype is implemented in OpenSSL's default provider.
Common EC parameters
The normal way of specifying domain parameters for an EC curve is via the curve name
"group". For curves with no curve name, explicit parameters can be used that specify
"field-type", "p", "a", "b", "generator" and "order". Explicit parameters are supported
for backwards compatibility reasons, but they are not compliant with multiple standards
(including RFC5915) which only allow named curves.
The following KeyGen/Gettable/Import/Export types are available for the built-in EC
algorithm:
"group" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>
The curve name.
"field-type" (OSSL_PKEY_PARAM_EC_FIELD_TYPE) <UTF8 string>
The value should be either "prime-field" or "characteristic-two-field", which
correspond to prime field Fp and binary field F2^m.
"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. Therefore,
there will either be three or five bits set dependent on whether the polynomial is a
trinomial or a pentanomial.
"a" (OSSL_PKEY_PARAM_EC_A) <unsigned integer>
"b" (OSSL_PKEY_PARAM_EC_B) <unsigned integer>
"seed" (OSSL_PKEY_PARAM_EC_SEED) <octet string>
a and b represents 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
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.
"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. cofactor is an optional value.
order multiplied by the cofactor gives the number of points on the curve.
"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).
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.
"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.
"priv" (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>
The private key value.
"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).
The following Gettable types are also available for the built-in EC algorithm:
"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
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.
For EC keys, EVP_PKEY_param_check_quick(3) is equivalent to EVP_PKEY_param_check(3).
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.
EXAMPLES
An EVP_PKEY context can be obtained by calling:
EVP_PKEY_CTX *pctx =
EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
An EVP_PKEY ECDSA or ECDH key can be generated with a "P-256" named group by calling:
pkey = EVP_EC_gen("P-256");
or like this:
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);
An EVP_PKEY EC CDH (Cofactor Diffie-Hellman) key can be generated with a "K-571" named
group by calling:
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);
SEE ALSO
EVP_EC_gen(3), EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7), EVP_SIGNATURE-ECDSA(7),
EVP_KEYEXCH-ECDH(7)
COPYRIGHT
Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
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>.