1=pod
2
3=head1 NAME
4
5EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH
6- EVP_PKEY DH and DHX keytype and algorithm support
7
8=head1 DESCRIPTION
9
10For 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
12groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain
13parameters should only be used for backward compatibility with existing
14applications that cannot be upgraded to use the approved safe-prime groups.
15
16See L<EVP_PKEY-FFC(7)> for more information about FFC keys.
17
18The B<DH> key type uses PKCS#3 format which saves p and g, but not the 'q' value.
19The B<DHX> key type uses X9.42 format which saves the value of 'q' and this
20must be used for FIPS186-4.
21
22For B<DHX> that is not a named group the FIPS186-4 standard specifies that the
23values used for FFC parameter generation are also required for parameter
24validation. This means that optional FFC domain parameter values for
25I<seed>, I<pcounter> and I<gindex> or I<hindex> may need to be stored for
26validation purposes.
27For 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).
29
30=head2 DH and DHX domain parameters
31
32In addition to the common FCC parameters that all FFC keytypes should support
33(see L<EVP_PKEY-FFC(7)/FFC parameters>) the B<DHX> and B<DH> keytype
34implementations support the following:
35
36=over 4
37
38=item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string>
39
40Sets or gets a string that associates a B<DH> or B<DHX> named safe prime group
41with known values for I<p>, I<q> and I<g>.
42
43The 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
47The 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
50DH/DHX named groups can be easily validated since the parameters are well known.
51For protocols that only transfer I<p> and I<g> the value of I<q> can also be
52retrieved.
53
54=back
55
56=head2 DH and DHX additional parameters
57
58=over 4
59
60=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>
61
62Used for getting and setting the encoding of the DH public key used in a key
63exchange message for the TLS protocol.
64See 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
74Used for DH generation of safe primes using the old safe prime generator code.
75The default value is 2.
76It is recommended to use a named safe prime group instead, if domain parameter
77validation is required.
78
79Randomly generated safe primes are not allowed by FIPS, so setting this value
80for the OpenSSL FIPS provider will instead choose a named safe prime group
81based on the size of I<p>.
82
83=back
84
85=head2 DH and DHX domain parameter / key generation parameters
86
87In addition to the common FFC key generation parameters that all FFC key types
88should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>) the
89B<DH> and B<DHX> keytype implementation supports the following:
90
91=over 4
92
93=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <UTF8 string>
94
95Sets 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
105These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters>
106
107=item "group"
108
109This specifies that a named safe prime name will be chosen using the "pbits"
110type.
111
112=item "generator"
113
114A safe prime generator. See the "safeprime-generator" type above.
115This is only valid for B<DH> keys.
116
117=back
118
119=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
120
121Sets the size (in bits) of the prime 'p'.
122
123For "fips186_4" this must be 2048.
124For "fips186_2" this must be 1024.
125For "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
129An optional value to set the maximum length of the generated private key.
130The default value used if this is not set is the maximum value of
131BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s.
132Where s is the security strength of the key which has values of
133112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.
134
135=back
136
137=head1 EXAMPLES
138
139An 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
143A B<DH> key can be generated with a named safe prime group by calling:
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);
157    EVP_PKEY_generate(pctx, &pkey);
158    ...
159    EVP_PKEY_free(pkey);
160    EVP_PKEY_CTX_free(pctx);
161
162B<DHX> domain parameters can be generated according to B<FIPS 186-4> by calling:
163
164    int gindex = 2;
165    unsigned int pbits = 2048;
166    unsigned int qbits = 256;
167    OSSL_PARAM params[6];
168    EVP_PKEY *param_key = NULL;
169    EVP_PKEY_CTX *pctx = NULL;
170
171    pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
172    EVP_PKEY_paramgen_init(pctx);
173
174    params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
175    params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
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();
180    EVP_PKEY_CTX_set_params(pctx, params);
181
182    EVP_PKEY_generate(pctx, &param_key);
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
189A B<DH> key can be generated using domain parameters by calling:
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);
195    EVP_PKEY_generate(gctx, &key);
196    EVP_PKEY_print_private(bio_out, key, 0, NULL);
197    ...
198    EVP_PKEY_free(key);
199    EVP_PKEY_CTX_free(gctx);
200
201To validate B<FIPS 186-4> B<DHX> domain parameters decoded from B<PEM> or
202B<DER> data, additional values used during generation may be required to
203be set into the key.
204
205EVP_PKEY_todata(), OSSL_PARAM_merge(), and EVP_PKEY_fromdata() are useful
206to add these parameters to the original key or domain parameters before
207the actual validation. In production code the return values should be checked.
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 = ...;
215    OSSL_PARAM extra_params[4];
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);
224    /*
225     * NOTE: For unverifiable g use "hindex" instead of "gindex"
226     * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex);
227     */
228    extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex);
229    extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter);
230    extra_params[3] = OSSL_PARAM_construct_end();
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);
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
263The 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
273The 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
287L<EVP_PKEY-FFC(7)>,
288L<EVP_KEYEXCH-DH(7)>
289L<EVP_PKEY(3)>,
290L<provider-keymgmt(7)>,
291L<EVP_KEYMGMT(3)>,
292L<OSSL_PROVIDER-default(7)>,
293L<OSSL_PROVIDER-FIPS(7)>
294
295=head1 COPYRIGHT
296
297Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
298
299Licensed under the Apache License 2.0 (the "License").  You may not use
300this file except in compliance with the License.  You can obtain a copy
301in the file LICENSE in the source distribution or at
302L<https://www.openssl.org/source/license.html>.
303
304=cut
305