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