1EVP_PKEY-EC(7ossl) OpenSSL EVP_PKEY-EC(7ossl)
2
6 EVP_PKEY-EC, EVP_KEYMGMT-EC - EVP_PKEY EC keytype and algorithm support
7
9 The EC keytype is implemented in OpenSSL's default provider.
10 Common EC parameters
12 The normal way of specifying domain parameters for an EC curve is via
13 the curve name "group". For curves with no curve name, explicit
14 parameters can be used that specify "field-type", "p", "a", "b",
15 "generator" and "order". Explicit parameters are supported for
16 backwards compability reasons, but they are not compliant with multiple
17 standards (including RFC5915) which only allow named curves.
18 The following KeyGen/Gettable/Import/Export types are available for the
20 built-in EC algorithm:
21 "group" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>
23 The curve name.
24 "field-type" (OSSL_PKEY_PARAM_EC_FIELD_TYPE) <UTF8 string>
26 The value should be either "prime-field" or "characteristic-two-
27 field", which correspond to prime field Fp and binary field F2^m.
28 "p" (OSSL_PKEY_PARAM_EC_P) <unsigned integer>
30 For a curve over Fp p is the prime for the field. For a curve over
31 F2^m p represents the irreducible polynomial - each bit represents
32 a term in the polynomial. Therefore, there will either be three or
33 five bits set dependent on whether the polynomial is a trinomial or
34 a pentanomial.
35 "a" (OSSL_PKEY_PARAM_EC_A) <unsigned integer>
37 "b" (OSSL_PKEY_PARAM_EC_B) <unsigned integer>
38 "seed" (OSSL_PKEY_PARAM_EC_SEED) <octet string>
39 a and b represents the coefficients of the curve For Fp: y^2 mod
40 p = x^3 +ax + b mod p OR For F2^m: y^2 + xy = x^3 + ax^2 + b
41 seed is an optional value that is for information purposes only.
43 It represents the random number seed used to generate the
44 coefficient b from a random number.
45 "generator" (OSSL_PKEY_PARAM_EC_GENERATOR) <octet string>
47 "order" (OSSL_PKEY_PARAM_EC_ORDER) <unsigned integer>
48 "cofactor" (OSSL_PKEY_PARAM_EC_COFACTOR) <unsigned integer>
49 The generator is a well defined point on the curve chosen for
50 cryptographic operations. The encoding conforms with Sec. 2.3.3 of
51 the SECG SEC 1 ("Elliptic Curve Cryptography") standard. See
52 EC_POINT_oct2point(). Integers used for point multiplications will
53 be between 0 and order - 1. cofactor is an optional value. order
54 multiplied by the cofactor gives the number of points on the curve.
55 "decoded-from-explicit"
57 (OSSL_PKEY_PARAM_EC_DECODED_FROM_EXPLICIT_PARAMS) <integer>
58 Gets a flag indicating wether the key or parameters were decoded
59 from explicit curve parameters. Set to 1 if so or 0 if a named
60 curve was used.
61 "use-cofactor-flag" (OSSL_PKEY_PARAM_USE_COFACTOR_ECDH) <integer>
63 Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses
64 normal EC DH if the value is zero. The cofactor variant multiplies
65 the shared secret by the EC curve's cofactor (note for some curves
66 the cofactor is 1).
67 See also EVP_KEYEXCH-ECDH(7) for the related
69 OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE parameter that can be set
70 on a per-operation basis.
71 "encoding" (OSSL_PKEY_PARAM_EC_ENCODING) <UTF8 string>
73 Set the format used for serializing the EC group parameters. Valid
74 values are "explicit" or "named_curve". The default value is
75 "named_curve".
76 "point-format" (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) <UTF8
78 string>
79 Sets or gets the point_conversion_form for the key. For a
80 description of point_conversion_forms please see EC_POINT_new(3).
81 Valid values are "uncompressed" or "compressed". The default value
82 is "uncompressed".
83 "group-check" (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE) <UTF8 string>
85 Sets or Gets the type of group check done when
86 EVP_PKEY_param_check() is called. Valid values are "default",
87 "named" and "named-nist". The "named" type checks that the domain
88 parameters match the inbuilt curve parameters, "named-nist" is
89 similiar but also checks that the named curve is a nist curve. The
90 "default" type does domain parameter validation for the OpenSSL
91 default provider, but is equivalent to "named-nist" for the OpenSSL
92 FIPS provider.
93 "include-public" (OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC) <integer>
95 Setting this value to 0 indicates that the public key should not be
96 included when encoding the private key. The default value of 1 will
97 include the public key.
98 "pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>
100 The public key value in encoded EC point format conforming to Sec.
101 2.3.3 and 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography")
102 standard. This parameter is used when importing or exporting the
103 public key value with the EVP_PKEY_fromdata() and EVP_PKEY_todata()
104 functions.
105 Note, in particular, that the choice of point compression format
107 used for encoding the exported value via EVP_PKEY_todata() depends
108 on the underlying provider implementation. Before OpenSSL 3.0.8,
109 the implementation of providers included with OpenSSL always opted
110 for an encoding in compressed format, unconditionally. Since
111 OpenSSL 3.0.8, the implementation has been changed to honor the
112 OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT parameter, if set, or to
113 default to uncompressed format.
114 "priv" (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>
116 The private key value.
117 "encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>
119 Used for getting and setting the encoding of an EC public key. The
120 public key is expected to be a point conforming to Sec. 2.3.4 of
121 the SECG SEC 1 ("Elliptic Curve Cryptography") standard.
122 "qx" (OSSL_PKEY_PARAM_EC_PUB_X) <unsigned integer>
124 Used for getting the EC public key X component.
125 "qy" (OSSL_PKEY_PARAM_EC_PUB_Y) <unsigned integer>
127 Used for getting the EC public key Y component.
128 "default-digest" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>
130 Getter that returns the default digest name. (Currently returns
131 "SHA256" as of OpenSSL 3.0).
132 The following Gettable types are also available for the built-in EC
134 algorithm:
135 "basis-type" (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8 string>
137 Supports the values "tpBasis" for a trinomial or "ppBasis" for a
138 pentanomial. This field is only used for a binary field F2^m.
139 "m" (OSSL_PKEY_PARAM_EC_CHAR2_M) <integer>
141 "tp" (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS) <integer>
142 "k1" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1) <integer>
143 "k2" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2) <integer>
144 "k3" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3) <integer>
145 These fields are only used for a binary field F2^m. m is the
146 degree of the binary field.
147 tp is the middle bit of a trinomial so its value must be in the
149 range m > tp > 0.
150 k1, k2 and k3 are used to get the middle bits of a pentanomial such
152 that m > k3 > k2 > k1 > 0
153 EC key validation
155 For EC keys, EVP_PKEY_param_check(3) behaves in the following way: For
156 the OpenSSL default provider it uses either EC_GROUP_check(3) or
157 EC_GROUP_check_named_curve(3) depending on the flag
158 EC_FLAG_CHECK_NAMED_GROUP. The OpenSSL FIPS provider uses
159 EC_GROUP_check_named_curve(3) in order to conform to SP800-56Ar3
160 Assurances of Domain-Parameter Validity.
161 For EC keys, EVP_PKEY_param_check_quick(3) is equivalent to
163 EVP_PKEY_param_check(3).
164 For EC keys, EVP_PKEY_public_check(3) and
166 EVP_PKEY_public_check_quick(3) conform to SP800-56Ar3 ECC Full Public-
167 Key Validation and ECC Partial Public-Key Validation respectively.
168 For EC Keys, EVP_PKEY_private_check(3) and EVP_PKEY_pairwise_check(3)
170 conform to SP800-56Ar3 Private key validity and Owner Assurance of
171 Pair-wise Consistency respectively.
172
174 An EVP_PKEY context can be obtained by calling:
175 EVP_PKEY_CTX *pctx =
177 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
178 An EVP_PKEY ECDSA or ECDH key can be generated with a "P-256" named
180 group by calling:
181 pkey = EVP_EC_gen("P-256");
183 or like this:
185 EVP_PKEY *key = NULL;
187 OSSL_PARAM params[2];
188 EVP_PKEY_CTX *gctx =
189 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
190 EVP_PKEY_keygen_init(gctx);
192 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
194 "P-256", 0);
195 params[1] = OSSL_PARAM_construct_end();
196 EVP_PKEY_CTX_set_params(gctx, params);
197 EVP_PKEY_generate(gctx, &key);
199 EVP_PKEY_print_private(bio_out, key, 0, NULL);
201 ...
202 EVP_PKEY_free(key);
203 EVP_PKEY_CTX_free(gctx);
204 An EVP_PKEY EC CDH (Cofactor Diffie-Hellman) key can be generated with
206 a "K-571" named group by calling:
207 int use_cdh = 1;
209 EVP_PKEY *key = NULL;
210 OSSL_PARAM params[3];
211 EVP_PKEY_CTX *gctx =
212 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
213 EVP_PKEY_keygen_init(gctx);
215 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
217 "K-571", 0);
218 /*
219 * This curve has a cofactor that is not 1 - so setting CDH mode changes
220 * the behaviour. For many curves the cofactor is 1 - so setting this has
221 * no effect.
222 */
223 params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
224 &use_cdh);
225 params[2] = OSSL_PARAM_construct_end();
226 EVP_PKEY_CTX_set_params(gctx, params);
227 EVP_PKEY_generate(gctx, &key);
229 EVP_PKEY_print_private(bio_out, key, 0, NULL);
230 ...
231 EVP_PKEY_free(key);
232 EVP_PKEY_CTX_free(gctx);
233
235 EVP_EC_gen(3), EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7),
236 EVP_SIGNATURE-ECDSA(7), EVP_KEYEXCH-ECDH(7)
237
239 Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
240 Licensed under the Apache License 2.0 (the "License"). You may not use
242 this file except in compliance with the License. You can obtain a copy
243 in the file LICENSE in the source distribution or at
244 <https://www.openssl.org/source/license.html>.
2453.0.9 2023-07-27 EVP_PKEY-EC(7ossl)