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 "encoding" (OSSL_PKEY_PARAM_EC_ENCODING) <UTF8 string>
69 Set the format used for serializing the EC group parameters. Valid
70 values are "explicit" or "named_curve". The default value is
71 "named_curve".
72 "point-format" (OSSL_PKEY_PARAM_EC_POINT_CONVERSION_FORMAT) <UTF8
74 string>
75 Sets or gets the point_conversion_form for the key. For a
76 description of point_conversion_forms please see EC_POINT_new(3).
77 Valid values are "uncompressed" or "compressed". The default value
78 is "uncompressed".
79 "group-check" (OSSL_PKEY_PARAM_EC_GROUP_CHECK_TYPE) <UTF8 string>
81 Sets or Gets the type of group check done when
82 EVP_PKEY_param_check() is called. Valid values are "default",
83 "named" and "named-nist". The "named" type checks that the domain
84 parameters match the inbuilt curve parameters, "named-nist" is
85 similiar but also checks that the named curve is a nist curve. The
86 "default" type does domain parameter validation for the OpenSSL
87 default provider, but is equivalent to "named-nist" for the OpenSSL
88 FIPS provider.
89 "include-public" (OSSL_PKEY_PARAM_EC_INCLUDE_PUBLIC) <integer>
91 Setting this value to 0 indicates that the public key should not be
92 included when encoding the private key. The default value of 1 will
93 include the public key.
94 See also EVP_KEYEXCH-ECDH(7) for the related
96 OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE parameter that can be set
97 on a per-operation basis.
98 "pub" (OSSL_PKEY_PARAM_PUB_KEY) <octet string>
100 The public key value in EC point format.
101 "priv" (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>
103 The private key value.
104 "encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>
106 Used for getting and setting the encoding of an EC public key. The
107 public key is expected to be a point conforming to Sec. 2.3.4 of
108 the SECG SEC 1 ("Elliptic Curve Cryptography") standard.
109 "qx" (OSSL_PKEY_PARAM_EC_PUB_X) <unsigned integer>
111 Used for getting the EC public key X component.
112 "qy" (OSSL_PKEY_PARAM_EC_PUB_Y) <unsigned integer>
114 Used for getting the EC public key Y component.
115 (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>
117 Getter that returns the default digest name. (Currently returns
118 "SHA256" as of OpenSSL 3.0).
119 The following Gettable types are also available for the built-in EC
121 algorithm:
122 "basis-type" (OSSL_PKEY_PARAM_EC_CHAR2_TYPE) <UTF8 string>
124 Supports the values "tpBasis" for a trinomial or "ppBasis" for a
125 pentanomial. This field is only used for a binary field F2^m.
126 "m" (OSSL_PKEY_PARAM_EC_CHAR2_M) <integer>
128 "tp" (OSSL_PKEY_PARAM_EC_CHAR2_TP_BASIS) <integer>
129 "k1" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K1) <integer>
130 "k2" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K2) <integer>
131 "k3" (OSSL_PKEY_PARAM_EC_CHAR2_PP_K3) <integer>
132 These fields are only used for a binary field F2^m. m is the
133 degree of the binary field.
134 tp is the middle bit of a trinomial so its value must be in the
136 range m > tp > 0.
137 k1, k2 and k3 are used to get the middle bits of a pentanomial such
139 that m > k3 > k2 > k1 > 0
140 EC key validation
142 For EC keys, EVP_PKEY_param_check(3) behaves in the following way: For
143 the OpenSSL default provider it uses either EC_GROUP_check(3) or
144 EC_GROUP_check_named_curve(3) depending on the flag
145 EC_FLAG_CHECK_NAMED_GROUP. The OpenSSL FIPS provider uses
146 EC_GROUP_check_named_curve(3) in order to conform to SP800-56Ar3
147 Assurances of Domain-Parameter Validity.
148 For EC keys, EVP_PKEY_param_check_quick(3) is equivalent to
150 EVP_PKEY_param_check(3).
151 For EC keys, EVP_PKEY_public_check(3) and
153 EVP_PKEY_public_check_quick(3) conform to SP800-56Ar3 ECC Full Public-
154 Key Validation and ECC Partial Public-Key Validation respectively.
155 For EC Keys, EVP_PKEY_private_check(3) and EVP_PKEY_pairwise_check(3)
157 conform to SP800-56Ar3 Private key validity and Owner Assurance of
158 Pair-wise Consistency respectively.
159
161 An EVP_PKEY context can be obtained by calling:
162 EVP_PKEY_CTX *pctx =
164 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
165 An EVP_PKEY ECDSA or ECDH key can be generated with a "P-256" named
167 group by calling:
168 pkey = EVP_EC_gen("P-256");
170 or like this:
172 EVP_PKEY *key = NULL;
174 OSSL_PARAM params[2];
175 EVP_PKEY_CTX *gctx =
176 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
177 EVP_PKEY_keygen_init(gctx);
179 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
181 "P-256", 0);
182 params[1] = OSSL_PARAM_construct_end();
183 EVP_PKEY_CTX_set_params(gctx, params);
184 EVP_PKEY_generate(gctx, &key);
186 EVP_PKEY_print_private(bio_out, key, 0, NULL);
188 ...
189 EVP_PKEY_free(key);
190 EVP_PKEY_CTX_free(gctx);
191 An EVP_PKEY EC CDH (Cofactor Diffie-Hellman) key can be generated with
193 a "K-571" named group by calling:
194 int use_cdh = 1;
196 EVP_PKEY *key = NULL;
197 OSSL_PARAM params[3];
198 EVP_PKEY_CTX *gctx =
199 EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
200 EVP_PKEY_keygen_init(gctx);
202 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME,
204 "K-571", 0);
205 /*
206 * This curve has a cofactor that is not 1 - so setting CDH mode changes
207 * the behaviour. For many curves the cofactor is 1 - so setting this has
208 * no effect.
209 */
210 params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
211 &use_cdh);
212 params[2] = OSSL_PARAM_construct_end();
213 EVP_PKEY_CTX_set_params(gctx, params);
214 EVP_PKEY_generate(gctx, &key);
216 EVP_PKEY_print_private(bio_out, key, 0, NULL);
217 ...
218 EVP_PKEY_free(key);
219 EVP_PKEY_CTX_free(gctx);
220
222 EVP_EC_gen(3), EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7),
223 EVP_SIGNATURE-ECDSA(7), EVP_KEYEXCH-ECDH(7)
224
226 Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
227 Licensed under the Apache License 2.0 (the "License"). You may not use
229 this file except in compliance with the License. You can obtain a copy
230 in the file LICENSE in the source distribution or at
231 <https://www.openssl.org/source/license.html>.
2323.0.5 2022-07-05 EVP_PKEY-EC(7ossl)