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 82=item "encoding" (B<OSSL_PKEY_PARAM_EC_ENCODING>) <UTF8 string> 83 84Set the format used for serializing the EC group parameters. 85Valid values are "explicit" or "named_curve". The default value is "named_curve". 86 87=item "point-format" (B<OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT>) <UTF8 string> 88 89Sets or gets the point_conversion_form for the I<key>. For a description of 90point_conversion_forms please see L<EC_POINT_new(3)>. Valid values are 91"uncompressed" or "compressed". The default value is "uncompressed". 92 93=item "group-check" (B<OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE>) <UTF8 string> 94 95Sets or Gets the type of group check done when EVP_PKEY_param_check() is called. 96Valid values are "default", "named" and "named-nist". 97The "named" type checks that the domain parameters match the inbuilt curve parameters, 98"named-nist" is similar but also checks that the named curve is a nist curve. 99The "default" type does domain parameter validation for the OpenSSL default provider, 100but is equivalent to "named-nist" for the OpenSSL FIPS provider. 101 102=item "include-public" (B<OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC>) <integer> 103 104Setting this value to 0 indicates that the public key should not be included when 105encoding the private key. The default value of 1 will include the public key. 106 107See also L<EVP_KEYEXCH-ECDH(7)> for the related 108B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a 109per-operation basis. 110 111=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string> 112 113The public key value in encoded EC point format. This parameter is used 114when importing or exporting the public key value with the EVP_PKEY_fromdata() 115and EVP_PKEY_todata() functions. 116 117=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer> 118 119The private key value. 120 121=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string> 122 123Used for getting and setting the encoding of an EC public key. The public key 124is expected to be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic 125Curve Cryptography") standard. 126 127=item "qx" (B<OSSL_PKEY_PARAM_EC_PUB_X>) <unsigned integer> 128 129Used for getting the EC public key X component. 130 131=item "qy" (B<OSSL_PKEY_PARAM_EC_PUB_Y>) <unsigned integer> 132 133Used for getting the EC public key Y component. 134 135=item (B<OSSL_PKEY_PARAM_DEFAULT_DIGEST>) <UTF8 string> 136 137Getter that returns the default digest name. 138(Currently returns "SHA256" as of OpenSSL 3.0). 139 140=back 141 142The following Gettable types are also available for the built-in EC algorithm: 143 144=over 4 145 146=item "basis-type" (B<OSSL_PKEY_PARAM_EC_CHAR2_TYPE>) <UTF8 string> 147 148Supports the values "tpBasis" for a trinomial or "ppBasis" for a pentanomial. 149This field is only used for a binary field F2^m. 150 151=item "m" (B<OSSL_PKEY_PARAM_EC_CHAR2_M>) <integer> 152 153=item "tp" (B<OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS>) <integer> 154 155=item "k1" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K1>) <integer> 156 157=item "k2" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K2>) <integer> 158 159=item "k3" (B<OSSL_PKEY_PARAM_EC_CHAR2_PP_K3>) <integer> 160 161These fields are only used for a binary field F2^m. 162I<m> is the degree of the binary field. 163 164I<tp> is the middle bit of a trinomial so its value must be in the 165range m > tp > 0. 166 167I<k1>, I<k2> and I<k3> are used to get the middle bits of a pentanomial such 168that m > k3 > k2 > k1 > 0 169 170=back 171 172=head2 EC key validation 173 174For EC keys, L<EVP_PKEY_param_check(3)> behaves in the following way: 175For the OpenSSL default provider it uses either 176L<EC_GROUP_check(3)> or L<EC_GROUP_check_named_curve(3)> depending on the flag 177EC_FLAG_CHECK_NAMED_GROUP. 178The OpenSSL FIPS provider uses L<EC_GROUP_check_named_curve(3)> in order to 179conform to SP800-56Ar3 I<Assurances of Domain-Parameter Validity>. 180 181For EC keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to 182L<EVP_PKEY_param_check(3)>. 183 184For EC keys, L<EVP_PKEY_public_check(3)> and L<EVP_PKEY_public_check_quick(3)> 185conform to SP800-56Ar3 I<ECC Full Public-Key Validation> and 186I<ECC Partial Public-Key Validation> respectively. 187 188For EC Keys, L<EVP_PKEY_private_check(3)> and L<EVP_PKEY_pairwise_check(3)> 189conform to SP800-56Ar3 I<Private key validity> and 190I<Owner Assurance of Pair-wise Consistency> respectively. 191 192=head1 EXAMPLES 193 194An B<EVP_PKEY> context can be obtained by calling: 195 196 EVP_PKEY_CTX *pctx = 197 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 198 199An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by 200calling: 201 202 pkey = EVP_EC_gen("P-256"); 203 204or like this: 205 206 EVP_PKEY *key = NULL; 207 OSSL_PARAM params[2]; 208 EVP_PKEY_CTX *gctx = 209 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 210 211 EVP_PKEY_keygen_init(gctx); 212 213 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, 214 "P-256", 0); 215 params[1] = OSSL_PARAM_construct_end(); 216 EVP_PKEY_CTX_set_params(gctx, params); 217 218 EVP_PKEY_generate(gctx, &key); 219 220 EVP_PKEY_print_private(bio_out, key, 0, NULL); 221 ... 222 EVP_PKEY_free(key); 223 EVP_PKEY_CTX_free(gctx); 224 225An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a 226"K-571" named group by calling: 227 228 int use_cdh = 1; 229 EVP_PKEY *key = NULL; 230 OSSL_PARAM params[3]; 231 EVP_PKEY_CTX *gctx = 232 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); 233 234 EVP_PKEY_keygen_init(gctx); 235 236 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, 237 "K-571", 0); 238 /* 239 * This curve has a cofactor that is not 1 - so setting CDH mode changes 240 * the behaviour. For many curves the cofactor is 1 - so setting this has 241 * no effect. 242 */ 243 params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH, 244 &use_cdh); 245 params[2] = OSSL_PARAM_construct_end(); 246 EVP_PKEY_CTX_set_params(gctx, params); 247 248 EVP_PKEY_generate(gctx, &key); 249 EVP_PKEY_print_private(bio_out, key, 0, NULL); 250 ... 251 EVP_PKEY_free(key); 252 EVP_PKEY_CTX_free(gctx); 253 254=head1 SEE ALSO 255 256L<EVP_EC_gen(3)>, 257L<EVP_KEYMGMT(3)>, 258L<EVP_PKEY(3)>, 259L<provider-keymgmt(7)>, 260L<EVP_SIGNATURE-ECDSA(7)>, 261L<EVP_KEYEXCH-ECDH(7)> 262 263=head1 COPYRIGHT 264 265Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved. 266 267Licensed under the Apache License 2.0 (the "License"). You may not use 268this file except in compliance with the License. You can obtain a copy 269in the file LICENSE in the source distribution or at 270L<https://www.openssl.org/source/license.html>. 271 272=cut 273
