]>
Commit | Line | Data |
---|---|---|
b8086652 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
0b3d2594 | 5 | EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH, EVP_KEYMGMT-DHX |
f1ffaaee | 6 | - EVP_PKEY DH and DHX keytype and algorithm support |
b8086652 SL |
7 | |
8 | =head1 DESCRIPTION | |
9 | ||
10 | For B<DH> FFC key agreement, two classes of domain parameters can be used: | |
11 | "safe" domain parameters that are associated with approved named safe-prime | |
0b3d2594 | 12 | groups, and a class of "FIPS186-type" domain parameters. FIPS186-type domain |
b8086652 SL |
13 | parameters should only be used for backward compatibility with existing |
14 | applications that cannot be upgraded to use the approved safe-prime groups. | |
15 | ||
16 | See L<EVP_PKEY-FFC(7)> for more information about FFC keys. | |
17 | ||
0b3d2594 | 18 | The B<DH> key type uses PKCS#3 format which saves I<p> and I<g>, but not the |
19 | I<q> value. | |
20 | The B<DHX> key type uses X9.42 format which saves the value of I<q> and this | |
21 | must be used for FIPS186-4. If key validation is required, users should be aware | |
22 | of the nuances associated with FIPS186-4 style parameters as discussed in | |
23 | L</DH key validation>. | |
b8086652 | 24 | |
f1ffaaee | 25 | =head2 DH and DHX domain parameters |
b8086652 SL |
26 | |
27 | In addition to the common FCC parameters that all FFC keytypes should support | |
f1ffaaee SL |
28 | (see L<EVP_PKEY-FFC(7)/FFC parameters>) the B<DHX> and B<DH> keytype |
29 | implementations support the following: | |
b8086652 SL |
30 | |
31 | =over 4 | |
32 | ||
023b188c | 33 | =item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string> |
b8086652 | 34 | |
f1ffaaee SL |
35 | Sets or gets a string that associates a B<DH> or B<DHX> named safe prime group |
36 | with known values for I<p>, I<q> and I<g>. | |
b8086652 SL |
37 | |
38 | The following values can be used by the OpenSSL's default and FIPS providers: | |
39 | "ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192", | |
40 | "modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192". | |
41 | ||
42 | The following additional values can also be used by OpenSSL's default provider: | |
43 | "modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256". | |
44 | ||
f1ffaaee | 45 | DH/DHX named groups can be easily validated since the parameters are well known. |
b8086652 SL |
46 | For protocols that only transfer I<p> and I<g> the value of I<q> can also be |
47 | retrieved. | |
48 | ||
f1ffaaee | 49 | =back |
b8086652 | 50 | |
f1ffaaee | 51 | =head2 DH and DHX additional parameters |
b8086652 | 52 | |
f1ffaaee | 53 | =over 4 |
b8086652 | 54 | |
5ac8fb58 | 55 | =item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string> |
6a9bd929 MC |
56 | |
57 | Used for getting and setting the encoding of the DH public key used in a key | |
58 | exchange message for the TLS protocol. | |
f1ffaaee SL |
59 | See EVP_PKEY_set1_encoded_public_key() and EVP_PKEY_get1_encoded_public_key(). |
60 | ||
61 | =back | |
62 | ||
63 | =head2 DH additional domain parameters | |
64 | ||
65 | =over 4 | |
66 | ||
67 | =item "safeprime-generator" (B<OSSL_PKEY_PARAM_DH_GENERATOR>) <integer> | |
68 | ||
69 | Used for DH generation of safe primes using the old safe prime generator code. | |
70 | The default value is 2. | |
71 | It is recommended to use a named safe prime group instead, if domain parameter | |
57cd10dd | 72 | validation is required. |
f1ffaaee SL |
73 | |
74 | Randomly generated safe primes are not allowed by FIPS, so setting this value | |
75 | for the OpenSSL FIPS provider will instead choose a named safe prime group | |
76 | based on the size of I<p>. | |
6a9bd929 | 77 | |
b8086652 SL |
78 | =back |
79 | ||
f1ffaaee | 80 | =head2 DH and DHX domain parameter / key generation parameters |
b8086652 | 81 | |
05fa5fde MC |
82 | In addition to the common FFC key generation parameters that all FFC key types |
83 | should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>) the | |
f1ffaaee | 84 | B<DH> and B<DHX> keytype implementation supports the following: |
b8086652 SL |
85 | |
86 | =over 4 | |
87 | ||
c9f18e59 | 88 | =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <UTF8 string> |
b8086652 SL |
89 | |
90 | Sets the type of parameter generation. For B<DH> valid values are: | |
91 | ||
92 | =over 4 | |
93 | ||
94 | =item "fips186_4" | |
95 | ||
96 | =item "default" | |
97 | ||
98 | =item "fips186_2" | |
99 | ||
100 | These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters> | |
101 | ||
102 | =item "group" | |
103 | ||
104 | This specifies that a named safe prime name will be chosen using the "pbits" | |
105 | type. | |
106 | ||
107 | =item "generator" | |
108 | ||
109 | A safe prime generator. See the "safeprime-generator" type above. | |
f1ffaaee | 110 | This is only valid for B<DH> keys. |
b8086652 SL |
111 | |
112 | =back | |
113 | ||
114 | =item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer> | |
115 | ||
116 | Sets the size (in bits) of the prime 'p'. | |
117 | ||
118 | For "fips186_4" this must be 2048. | |
119 | For "fips186_2" this must be 1024. | |
120 | For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192. | |
121 | ||
122 | =item "priv_len" (B<OSSL_PKEY_PARAM_DH_PRIV_LEN>) <integer> | |
123 | ||
124 | An optional value to set the maximum length of the generated private key. | |
8c1cbc72 | 125 | The default value used if this is not set is the maximum value of |
b8086652 SL |
126 | BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s. |
127 | Where s is the security strength of the key which has values of | |
128 | 112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192. | |
129 | ||
130 | =back | |
131 | ||
0b3d2594 | 132 | =head2 DH key validation |
133 | ||
134 | For B<DHX> that is not a named group the FIPS186-4 standard specifies that the | |
135 | values used for FFC parameter generation are also required for parameter | |
136 | validation. This means that optional FFC domain parameter values for | |
137 | I<seed>, I<pcounter> and I<gindex> or I<hindex> may need to be stored for | |
138 | validation purposes. | |
139 | For B<DHX> the I<seed> and I<pcounter> can be stored in ASN1 data | |
140 | (but the I<gindex> or I<hindex> cannot be stored). It is recommended to use a | |
141 | named safe prime group instead. | |
142 | ||
143 | For DH keys, L<EVP_PKEY_param_check(3)> behaves in the following way: | |
144 | The OpenSSL FIPS provider tests if the parameters are either an approved safe | |
145 | prime group OR that the FFC parameters conform to FIPS186-4 as defined in | |
146 | SP800-56Ar3 I<Assurances of Domain-Parameter Validity>. | |
147 | The OpenSSL default provider uses simpler checks that allows there to be no I<q> | |
148 | value for backwards compatibility. | |
149 | ||
150 | For DH keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to | |
151 | L<EVP_PKEY_param_check(3)>. | |
152 | ||
153 | For DH keys, L<EVP_PKEY_public_check(3)> conforms to | |
154 | SP800-56Ar3 I<FFC Full Public-Key Validation>. | |
155 | ||
156 | For DH keys, L<EVP_PKEY_public_check_quick(3)> conforms to | |
157 | SP800-56Ar3 I<FFC Partial Public-Key Validation> when the | |
158 | DH key is an approved named safe prime group, otherwise it is the same as | |
159 | L<EVP_PKEY_public_check(3)>. | |
160 | ||
161 | For DH Keys, L<EVP_PKEY_private_check(3)> tests that the private key is in the | |
162 | correct range according to SP800-56Ar3. The OpenSSL FIPS provider requires the | |
163 | value of I<q> to be set (note that this is set for named safe prime groups). | |
164 | For backwards compatibility the OpenSSL default provider only requires I<p> to | |
165 | be set. | |
166 | ||
167 | For DH keys, L<EVP_PKEY_pairwise_check(3)> conforms to | |
168 | SP800-56Ar3 I<Owner Assurance of Pair-wise Consistency>. | |
169 | ||
b8086652 SL |
170 | =head1 EXAMPLES |
171 | ||
172 | An B<EVP_PKEY> context can be obtained by calling: | |
173 | ||
174 | EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); | |
175 | ||
185e1aa2 | 176 | A B<DH> key can be generated with a named safe prime group by calling: |
b8086652 SL |
177 | |
178 | int priv_len = 2 * 112; | |
179 | OSSL_PARAM params[3]; | |
180 | EVP_PKEY *pkey = NULL; | |
181 | EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); | |
182 | ||
183 | params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0); | |
184 | /* "priv_len" is optional */ | |
185 | params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len); | |
186 | params[2] = OSSL_PARAM_construct_end(); | |
187 | ||
188 | EVP_PKEY_keygen_init(pctx); | |
189 | EVP_PKEY_CTX_set_params(pctx, params); | |
f9253152 | 190 | EVP_PKEY_generate(pctx, &pkey); |
b8086652 | 191 | ... |
29a84567 | 192 | EVP_PKEY_free(pkey); |
b8086652 SL |
193 | EVP_PKEY_CTX_free(pctx); |
194 | ||
0b3d2594 | 195 | B<DHX> domain parameters can be generated according to B<FIPS186-4> by calling: |
05fa5fde | 196 | |
990aa405 | 197 | int gindex = 2; |
b8086652 SL |
198 | unsigned int pbits = 2048; |
199 | unsigned int qbits = 256; | |
990aa405 | 200 | OSSL_PARAM params[6]; |
b8086652 SL |
201 | EVP_PKEY *param_key = NULL; |
202 | EVP_PKEY_CTX *pctx = NULL; | |
203 | ||
185e1aa2 | 204 | pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL); |
b8086652 | 205 | EVP_PKEY_paramgen_init(pctx); |
2edb571b | 206 | |
b8086652 SL |
207 | params[0] = OSSL_PARAM_construct_uint("pbits", &pbits); |
208 | params[1] = OSSL_PARAM_construct_uint("qbits", &qbits); | |
990aa405 SL |
209 | params[2] = OSSL_PARAM_construct_int("gindex", &gindex); |
210 | params[3] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0); | |
211 | params[4] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0); | |
212 | params[5] = OSSL_PARAM_construct_end(); | |
b8086652 SL |
213 | EVP_PKEY_CTX_set_params(pctx, params); |
214 | ||
f9253152 | 215 | EVP_PKEY_generate(pctx, ¶m_key); |
b8086652 SL |
216 | |
217 | EVP_PKEY_print_params(bio_out, param_key, 0, NULL); | |
218 | ... | |
219 | EVP_PKEY_free(param_key); | |
220 | EVP_PKEY_CTX_free(pctx); | |
221 | ||
185e1aa2 | 222 | A B<DH> key can be generated using domain parameters by calling: |
b8086652 SL |
223 | |
224 | EVP_PKEY *key = NULL; | |
225 | EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL); | |
226 | ||
227 | EVP_PKEY_keygen_init(gctx); | |
f9253152 | 228 | EVP_PKEY_generate(gctx, &key); |
b8086652 SL |
229 | EVP_PKEY_print_private(bio_out, key, 0, NULL); |
230 | ... | |
231 | EVP_PKEY_free(key); | |
232 | EVP_PKEY_CTX_free(gctx); | |
233 | ||
0b3d2594 | 234 | To validate B<FIPS186-4> B<DHX> domain parameters decoded from B<PEM> or |
185e1aa2 TM |
235 | B<DER> data, additional values used during generation may be required to |
236 | be set into the key. | |
237 | ||
238 | EVP_PKEY_todata(), OSSL_PARAM_merge(), and EVP_PKEY_fromdata() are useful | |
239 | to add these parameters to the original key or domain parameters before | |
990aa405 | 240 | the actual validation. In production code the return values should be checked. |
185e1aa2 TM |
241 | |
242 | EVP_PKEY *received_domp = ...; /* parameters received and decoded */ | |
243 | unsigned char *seed = ...; /* and additional parameters received */ | |
244 | size_t seedlen = ...; /* by other means, required */ | |
245 | int gindex = ...; /* for the validation */ | |
246 | int pcounter = ...; | |
247 | int hindex = ...; | |
990aa405 | 248 | OSSL_PARAM extra_params[4]; |
185e1aa2 TM |
249 | OSSL_PARAM *domain_params = NULL; |
250 | OSSL_PARAM *merged_params = NULL; | |
251 | EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL; | |
252 | EVP_PKEY *complete_domp = NULL; | |
253 | ||
254 | EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, | |
255 | &domain_params); | |
256 | extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen); | |
990aa405 SL |
257 | /* |
258 | * NOTE: For unverifiable g use "hindex" instead of "gindex" | |
259 | * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex); | |
260 | */ | |
185e1aa2 TM |
261 | extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex); |
262 | extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter); | |
990aa405 | 263 | extra_params[3] = OSSL_PARAM_construct_end(); |
185e1aa2 TM |
264 | merged_params = OSSL_PARAM_merge(domain_params, extra_params); |
265 | ||
266 | ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL); | |
267 | EVP_PKEY_fromdata_init(ctx); | |
268 | EVP_PKEY_fromdata(ctx, &complete_domp, OSSL_KEYMGMT_SELECT_ALL, | |
269 | merged_params); | |
270 | ||
271 | validate_ctx = EVP_PKEY_CTX_new_from_pkey(NULL, complete_domp, NULL); | |
272 | if (EVP_PKEY_param_check(validate_ctx) > 0) | |
273 | /* validation_passed(); */ | |
274 | else | |
275 | /* validation_failed(); */ | |
276 | ||
277 | OSSL_PARAM_free(domain_params); | |
278 | OSSL_PARAM_free(merged_params); | |
279 | EVP_PKEY_CTX_free(ctx); | |
280 | EVP_PKEY_CTX_free(validate_ctx); | |
281 | EVP_PKEY_free(complete_domp); | |
b8086652 SL |
282 | |
283 | =head1 CONFORMING TO | |
284 | ||
285 | =over 4 | |
286 | ||
287 | =item RFC 7919 (TLS ffdhe named safe prime groups) | |
288 | ||
289 | =item RFC 3526 (IKE modp named safe prime groups) | |
290 | ||
291 | =item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224" | |
292 | and "dh_2048_256"). | |
293 | ||
294 | =back | |
295 | ||
296 | The following sections of SP800-56Ar3: | |
297 | ||
298 | =over 4 | |
299 | ||
300 | =item 5.5.1.1 FFC Domain Parameter Selection/Generation | |
301 | ||
302 | =item Appendix D: FFC Safe-prime Groups | |
303 | ||
304 | =back | |
305 | ||
0b3d2594 | 306 | The following sections of FIPS186-4: |
b8086652 SL |
307 | |
308 | =over 4 | |
309 | ||
310 | =item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function. | |
311 | ||
312 | =item A.2.3 Generation of canonical generator g. | |
313 | ||
314 | =item A.2.1 Unverifiable Generation of the Generator g. | |
315 | ||
316 | =back | |
317 | ||
318 | =head1 SEE ALSO | |
319 | ||
320 | L<EVP_PKEY-FFC(7)>, | |
321 | L<EVP_KEYEXCH-DH(7)> | |
322 | L<EVP_PKEY(3)>, | |
323 | L<provider-keymgmt(7)>, | |
324 | L<EVP_KEYMGMT(3)>, | |
325 | L<OSSL_PROVIDER-default(7)>, | |
326 | L<OSSL_PROVIDER-FIPS(7)> | |
327 | ||
328 | =head1 COPYRIGHT | |
329 | ||
f5afac4b | 330 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. |
b8086652 SL |
331 | |
332 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
333 | this file except in compliance with the License. You can obtain a copy | |
334 | in the file LICENSE in the source distribution or at | |
335 | L<https://www.openssl.org/source/license.html>. | |
336 | ||
337 | =cut |