1=pod 2 3=head1 NAME 4 5EVP_PKEY-EC, 6EVP_KEYMGMT-EC 7- EVP_PKEY EC keytype and algorithm support 8 9=head1 DESCRIPTION 10 11The B<EC> keytype is implemented in OpenSSL's default provider. 12 13=head2 Common EC parameters 14 15The normal way of specifying domain parameters for an EC curve is via the 16curve name "group". For curves with no curve name, explicit parameters can be 17used that specify "field-type", "p", "a", "b", "generator" and "order". 18Explicit parameters are supported for backwards compatibility reasons, but they 19are not compliant with multiple standards (including RFC5915) which only allow 20named curves. 21 22The following Key generation/Gettable/Import/Export types are available for the 23built-in EC algorithm: 24 25=over 4 26 27=item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string> 28 29The curve name. 30 31=item "field-type" (B<OSSL_PKEY_PARAM_EC_FIELD_TYPE>) <UTF8 string> 32 33The value should be either "prime-field" or "characteristic-two-field", 34which correspond to prime field Fp and binary field F2^m. 35 36=item "p" (B<OSSL_PKEY_PARAM_EC_P>) <unsigned integer> 37 38For a curve over Fp I<p> is the prime for the field. For a curve over F2^m I<p> 39represents the irreducible polynomial - each bit represents a term in the 40polynomial. Therefore, there will either be three or five bits set dependent on 41whether the polynomial is a trinomial or a pentanomial. 42 43=item "a" (B<OSSL_PKEY_PARAM_EC_A>) <unsigned integer> 44 45=item "b" (B<OSSL_PKEY_PARAM_EC_B>) <unsigned integer> 46 47=item "seed" (B<OSSL_PKEY_PARAM_EC_SEED>) <octet string> 48 49I<a> and I<b> represents the coefficients of the curve 50For Fp: y^2 mod p = x^3 +ax + b mod p OR 51For F2^m: y^2 + xy = x^3 + ax^2 + b 52 53I<seed> is an optional value that is for information purposes only. 54It represents the random number seed used to generate the coefficient I<b> from a 55random number. 56 57=item "generator" (B<OSSL_PKEY_PARAM_EC_GENERATOR>) <octet string> 58 59=item "order" (B<OSSL_PKEY_PARAM_EC_ORDER>) <unsigned integer> 60 61=item "cofactor" (B<OSSL_PKEY_PARAM_EC_COFACTOR>) <unsigned integer> 62 63The I<generator> is a well defined point on the curve chosen for cryptographic 64operations. The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve 65Cryptography") standard. See EC_POINT_oct2point(). 66Integers used for point multiplications will be between 0 and 67I<order> - 1. 68I<cofactor> is an optional value. 69I<order> multiplied by the I<cofactor> gives the number of points on the curve. 70 71=item "decoded-from-explicit" (B<OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS>) <integer> 72 73Gets a flag indicating whether the key or parameters were decoded from explicit 74curve parameters. Set to 1 if so or 0 if a named curve was used. 75 76=item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer> 77 78Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH 79if the value is zero. The cofactor variant multiplies the shared secret by the 80EC curve's cofactor (note for some curves the cofactor is 1). 81 82See also L<EVP_KEYEXCH-ECDH(7)> for the related 83B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a 84per-operation basis. 85 86=item "encoding" (B<OSSL_PKEY_PARAM_EC_ENCODING>) <UTF8 string> 87 88Set the format used for serializing the EC group parameters. 89Valid values are "explicit" or "named_curve". The default value is "named_curve". 90 91=item "point-format" (B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>) <UTF8 string> 92 93Sets or gets the point_conversion_form for the I<key>. For a description of 94point_conversion_forms please see L<EC_POINT_new(3)>. Valid values are 95"uncompressed" or "compressed". The default value is "uncompressed". 96 97=item "group-check" (B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>) <UTF8 string> 98 99Sets or Gets the type of group check done when EVP_PKEY_param_check() is called. 100Valid values are "default", "named" and "named-nist". 101The "named" type checks that the domain parameters match the inbuilt curve parameters, 102"named-nist" is similar but also checks that the named curve is a nist curve. 103The "default" type does domain parameter validation for the OpenSSL default provider, 104but is equivalent to "named-nist" for the OpenSSL FIPS provider. 105 106=item "include-public" (B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>) <integer> 107 108Setting this value to 0 indicates that the public key should not be included when 109encoding the private key. The default value of 1 will include the public key. 110 111=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string> 112 113The public key value in encoded EC point format conforming to Sec. 2.3.3 and 1142.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard. 115This parameter is used when importing or exporting the public key value with the 116EVP_PKEY_fromdata() and EVP_PKEY_todata() functions. 117 118Note, in particular, that the choice of point compression format used for 119encoding the exported value via EVP_PKEY_todata() depends on the underlying 120provider implementation. 121Before OpenSSL 3.0.8, the implementation of providers included with OpenSSL always 122opted for an encoding in compressed format, unconditionally. 123Since OpenSSL 3.0.8, the implementation has been changed to honor the 124B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT> parameter, if set, or to default 125to uncompressed format. 126 127=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer> 128 129The private key value. 130 131=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string> 132 133Used for getting and setting the encoding of an EC public key. The public key 134is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic 135Curve Cryptography") standard. 136 137=item "qx" (B<OSSL_PKEY_PARAM_EC_PUB_X>) <unsigned integer> 138 139Used for getting the EC public key X component. 140 141=item "qy" (B<OSSL_PKEY_PARAM_EC_PUB_Y>) <unsigned integer> 142 143Used for getting the EC public key Y component. 144 145=item "default-digest" (B<OSSL_PKEY_PARAM_DEFAULT_DIGEST>) <UTF8 string> 146 147Getter that returns the default digest name. 148(Currently returns "SHA256" as of OpenSSL 3.0). 149 150=item "dhkem-ikm" (B<OSSL_PKEY_PARAM_DHKEM_IKM>) <octet string> 151 152DHKEM requires the generation of a keypair using an input key material (seed). 153Use this to specify the key material used for generation of the private key. 154This value should not be reused for other purposes. It can only be used 155for the curves "P-256", "P-384" and "P-521" and should have a length of at least 156the size of the encoded private key (i.e. 32, 48 and 66 for the listed curves). 157 158=back 159 160The following Gettable types are also available for the built-in EC algorithm: 161 162=over 4 163 164=item "basis-type" (B<OSSL_PKEY_PARAM_EC_CHAR2_TYPE>) <UTF8 string> 165 166Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial. 167This field is only used for a binary field F2^m. 168 169=item "m" (B<OSSL_PKEY_PARAM_EC_CHAR2_M>) <integer> 170 171=item "tp" (B<OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS>) <integer> 172 173=item "k1" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K1>) <integer> 174 175=item "k2" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K2>) <integer> 176 177=item "k3" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K3>) <integer> 178 179These fields are only used for a binary field F2^m. 180I<m> is the degree of the binary field. 181 182I<tp> is the middle bit of a trinomial so its value must be in the 183range m > tp > 0. 184 185I<k1>, I<k2> and I<k3> are used to get the middle bits of a pentanomial such 186that m > k3 > k2 > k1 > 0 187 188=back 189 190The following key generation settable parameter is also available for the 191OpenSSL FIPS provider's EC algorithm: 192 193=over 4 194 195=item "key-check" (B<OSSL_PKEY_PARAM_FIPS_KEY_CHECK>) <integer> 196 197See L<provider-keymgmt(7)/Common Information Parameters> for further information. 198 199=back 200 201The following key generation Gettable parameter is available for the OpenSSL 202FIPS provider's EC algorithm: 203 204=over 4 205 206=item "fips-indicator" (B<OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 207 208See L<provider-keymgmt(7)/Common Information Parameters> for further information. 209 210=back 211 212=head2 EC key validation 213 214For EC keys, L<EVP_PKEY_param_check(3)> behaves in the following way: 215For the OpenSSL default provider it uses either 216L<EC_GROUP_check(3)> or L<EC_GROUP_check_named_curve(3)> depending on the flag 217EC_FLAG_CHECK_NAMED_GROUP. 218The OpenSSL FIPS provider uses L<EC_GROUP_check_named_curve(3)> in order to 219conform to SP800-56Ar3 I<Assurances of Domain-Parameter Validity>. 220 221For EC keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to 222L<EVP_PKEY_param_check(3)>. 223 224For EC keys, L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_public_check_quick(3)> 225conform to SP800-56Ar3 I<ECC Full Public-Key Validation> and 226I<ECC Partial Public-Key Validation> respectively. 227 228For EC Keys, L<EVP_PKEY_private_check(3)> and L<EVP_PKEY_pairwise_check(3)> 229conform to SP800-56Ar3 I<Private key validity> and 230I<Owner Assurance of Pair-wise Consistency> respectively. 231 232=head1 EXAMPLES 233 234An B<EVP_PKEY> context can be obtained by calling: 235 236 EVP_PKEY_CTX *pctx = 237 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 238 239An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by 240calling: 241 242 pkey = EVP_EC_gen("P-256"); 243 244or like this: 245 246 EVP_PKEY *key = NULL; 247 OSSL_PARAM params[2]; 248 EVP_PKEY_CTX *gctx = 249 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 250 251 EVP_PKEY_keygen_init(gctx); 252 253 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, 254 "P-256", 0); 255 params[1] = OSSL_PARAM_construct_end(); 256 EVP_PKEY_CTX_set_params(gctx, params); 257 258 EVP_PKEY_generate(gctx, &key); 259 260 EVP_PKEY_print_private(bio_out, key, 0, NULL); 261 ... 262 EVP_PKEY_free(key); 263 EVP_PKEY_CTX_free(gctx); 264 265An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a 266"K-571" named group by calling: 267 268 int use_cdh = 1; 269 EVP_PKEY *key = NULL; 270 OSSL_PARAM params[3]; 271 EVP_PKEY_CTX *gctx = 272 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 273 274 EVP_PKEY_keygen_init(gctx); 275 276 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, 277 "K-571", 0); 278 /* 279 * This curve has a cofactor that is not 1 - so setting CDH mode changes 280 * the behaviour. For many curves the cofactor is 1 - so setting this has 281 * no effect. 282 */ 283 params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH, 284 &use_cdh); 285 params[2] = OSSL_PARAM_construct_end(); 286 EVP_PKEY_CTX_set_params(gctx, params); 287 288 EVP_PKEY_generate(gctx, &key); 289 EVP_PKEY_print_private(bio_out, key, 0, NULL); 290 ... 291 EVP_PKEY_free(key); 292 EVP_PKEY_CTX_free(gctx); 293 294=head1 SEE ALSO 295 296L<EVP_EC_gen(3)>, 297L<EVP_KEYMGMT(3)>, 298L<EVP_PKEY(3)>, 299L<provider-keymgmt(7)>, 300L<EVP_SIGNATURE-ECDSA(7)>, 301L<EVP_KEYEXCH-ECDH(7)> 302 303=head1 COPYRIGHT 304 305Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved. 306 307Licensed under the Apache License 2.0 (the "License"). You may not use 308this file except in compliance with the License. You can obtain a copy 309in the file LICENSE in the source distribution or at 310L<https://www.openssl.org/source/license.html>. 311 312=cut 313
