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