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 KeyGen/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=back 151 152The following Gettable types are also available for the built-in EC algorithm: 153 154=over 4 155 156=item "basis-type" (B<OSSL_PKEY_PARAM_EC_CHAR2_TYPE>) <UTF8 string> 157 158Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial. 159This field is only used for a binary field F2^m. 160 161=item "m" (B<OSSL_PKEY_PARAM_EC_CHAR2_M>) <integer> 162 163=item "tp" (B<OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS>) <integer> 164 165=item "k1" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K1>) <integer> 166 167=item "k2" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K2>) <integer> 168 169=item "k3" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K3>) <integer> 170 171These fields are only used for a binary field F2^m. 172I<m> is the degree of the binary field. 173 174I<tp> is the middle bit of a trinomial so its value must be in the 175range m > tp > 0. 176 177I<k1>, I<k2> and I<k3> are used to get the middle bits of a pentanomial such 178that m > k3 > k2 > k1 > 0 179 180=back 181 182=head2 EC key validation 183 184For EC keys, L<EVP_PKEY_param_check(3)> behaves in the following way: 185For the OpenSSL default provider it uses either 186L<EC_GROUP_check(3)> or L<EC_GROUP_check_named_curve(3)> depending on the flag 187EC_FLAG_CHECK_NAMED_GROUP. 188The OpenSSL FIPS provider uses L<EC_GROUP_check_named_curve(3)> in order to 189conform to SP800-56Ar3 I<Assurances of Domain-Parameter Validity>. 190 191For EC keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to 192L<EVP_PKEY_param_check(3)>. 193 194For EC keys, L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_public_check_quick(3)> 195conform to SP800-56Ar3 I<ECC Full Public-Key Validation> and 196I<ECC Partial Public-Key Validation> respectively. 197 198For EC Keys, L<EVP_PKEY_private_check(3)> and L<EVP_PKEY_pairwise_check(3)> 199conform to SP800-56Ar3 I<Private key validity> and 200I<Owner Assurance of Pair-wise Consistency> respectively. 201 202=head1 EXAMPLES 203 204An B<EVP_PKEY> context can be obtained by calling: 205 206 EVP_PKEY_CTX *pctx = 207 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 208 209An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by 210calling: 211 212 pkey = EVP_EC_gen("P-256"); 213 214or like this: 215 216 EVP_PKEY *key = NULL; 217 OSSL_PARAM params[2]; 218 EVP_PKEY_CTX *gctx = 219 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 220 221 EVP_PKEY_keygen_init(gctx); 222 223 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, 224 "P-256", 0); 225 params[1] = OSSL_PARAM_construct_end(); 226 EVP_PKEY_CTX_set_params(gctx, params); 227 228 EVP_PKEY_generate(gctx, &key); 229 230 EVP_PKEY_print_private(bio_out, key, 0, NULL); 231 ... 232 EVP_PKEY_free(key); 233 EVP_PKEY_CTX_free(gctx); 234 235An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a 236"K-571" named group by calling: 237 238 int use_cdh = 1; 239 EVP_PKEY *key = NULL; 240 OSSL_PARAM params[3]; 241 EVP_PKEY_CTX *gctx = 242 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 243 244 EVP_PKEY_keygen_init(gctx); 245 246 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, 247 "K-571", 0); 248 /* 249 * This curve has a cofactor that is not 1 - so setting CDH mode changes 250 * the behaviour. For many curves the cofactor is 1 - so setting this has 251 * no effect. 252 */ 253 params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH, 254 &use_cdh); 255 params[2] = OSSL_PARAM_construct_end(); 256 EVP_PKEY_CTX_set_params(gctx, params); 257 258 EVP_PKEY_generate(gctx, &key); 259 EVP_PKEY_print_private(bio_out, key, 0, NULL); 260 ... 261 EVP_PKEY_free(key); 262 EVP_PKEY_CTX_free(gctx); 263 264=head1 SEE ALSO 265 266L<EVP_EC_gen(3)>, 267L<EVP_KEYMGMT(3)>, 268L<EVP_PKEY(3)>, 269L<provider-keymgmt(7)>, 270L<EVP_SIGNATURE-ECDSA(7)>, 271L<EVP_KEYEXCH-ECDH(7)> 272 273=head1 COPYRIGHT 274 275Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. 276 277Licensed under the Apache License 2.0 (the "License"). You may not use 278this file except in compliance with the License. You can obtain a copy 279in the file LICENSE in the source distribution or at 280L<https://www.openssl.org/source/license.html>. 281 282=cut 283