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