xref: /freebsd/crypto/openssl/doc/man7/EVP_PKEY-DH.pod (revision 9f23cbd6cae82fd77edfad7173432fa8dccd0a95) 
1=pod
2
3=head1 NAME
4
5EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH, EVP_KEYMGMT-DHX
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 "FIPS186-type" domain parameters. FIPS186-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 I<p> and I<g>, but not the
19I<q> value.
20The B<DHX> key type uses X9.42 format which saves the value of I<q> and this
21must be used for FIPS186-4. If key validation is required, users should be aware
22of the nuances associated with FIPS186-4 style parameters as discussed in
23L</DH key validation>.
24
25=head2 DH and DHX domain parameters
26
27In addition to the common FCC parameters that all FFC keytypes should support
28(see L<EVP_PKEY-FFC(7)/FFC parameters>) the B<DHX> and B<DH> keytype
29implementations support the following:
30
31=over 4
32
33=item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string>
34
35Sets or gets a string that associates a B<DH> or B<DHX> named safe prime group
36with known values for I<p>, I<q> and I<g>.
37
38The 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
42The 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
45DH/DHX named groups can be easily validated since the parameters are well known.
46For protocols that only transfer I<p> and I<g> the value of I<q> can also be
47retrieved.
48
49=back
50
51=head2 DH and DHX additional parameters
52
53=over 4
54
55=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>
56
57Used for getting and setting the encoding of the DH public key used in a key
58exchange message for the TLS protocol.
59See 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
69Used for DH generation of safe primes using the old safe prime generator code.
70The default value is 2.
71It is recommended to use a named safe prime group instead, if domain parameter
72validation is required.
73
74Randomly generated safe primes are not allowed by FIPS, so setting this value
75for the OpenSSL FIPS provider will instead choose a named safe prime group
76based on the size of I<p>.
77
78=back
79
80=head2 DH and DHX domain parameter / key generation parameters
81
82In addition to the common FFC key generation parameters that all FFC key types
83should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>) the
84B<DH> and B<DHX> keytype implementation supports the following:
85
86=over 4
87
88=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <UTF8 string>
89
90Sets 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
100These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters>
101
102=item "group"
103
104This specifies that a named safe prime name will be chosen using the "pbits"
105type.
106
107=item "generator"
108
109A safe prime generator. See the "safeprime-generator" type above.
110This is only valid for B<DH> keys.
111
112=back
113
114=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
115
116Sets the size (in bits) of the prime 'p'.
117
118For "fips186_4" this must be 2048.
119For "fips186_2" this must be 1024.
120For "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
124An optional value to set the maximum length of the generated private key.
125The default value used if this is not set is the maximum value of
126BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s.
127Where s is the security strength of the key which has values of
128112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.
129
130=back
131
132=head2 DH key validation
133
134For B<DHX> that is not a named group the FIPS186-4 standard specifies that the
135values used for FFC parameter generation are also required for parameter
136validation. This means that optional FFC domain parameter values for
137I<seed>, I<pcounter> and I<gindex> or I<hindex> may need to be stored for
138validation purposes.
139For 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
141named safe prime group instead.
142
143For DH keys, L<EVP_PKEY_param_check(3)> behaves in the following way:
144The OpenSSL FIPS provider tests if the parameters are either an approved safe
145prime group OR that the FFC parameters conform to FIPS186-4 as defined in
146SP800-56Ar3 I<Assurances of Domain-Parameter Validity>.
147The OpenSSL default provider uses simpler checks that allows there to be no I<q>
148value for backwards compatibility.
149
150For DH keys, L<EVP_PKEY_param_check_quick(3)> is equivalent to
151L<EVP_PKEY_param_check(3)>.
152
153For DH keys, L<EVP_PKEY_public_check(3)> conforms to
154SP800-56Ar3 I<FFC Full Public-Key Validation>.
155
156For DH keys, L<EVP_PKEY_public_check_quick(3)> conforms to
157SP800-56Ar3 I<FFC Partial Public-Key Validation> when the
158DH key is an approved named safe prime group, otherwise it is the same as
159L<EVP_PKEY_public_check(3)>.
160
161For DH Keys, L<EVP_PKEY_private_check(3)> tests that the private key is in the
162correct range according to SP800-56Ar3. The OpenSSL FIPS provider requires the
163value of I<q> to be set (note that this is set for named safe prime groups).
164For backwards compatibility the OpenSSL default provider only requires I<p> to
165be set.
166
167For DH keys, L<EVP_PKEY_pairwise_check(3)> conforms to
168SP800-56Ar3 I<Owner Assurance of Pair-wise Consistency>.
169
170=head1 EXAMPLES
171
172An 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
176A B<DH> key can be generated with a named safe prime group by calling:
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);
190    EVP_PKEY_generate(pctx, &pkey);
191    ...
192    EVP_PKEY_free(pkey);
193    EVP_PKEY_CTX_free(pctx);
194
195B<DHX> domain parameters can be generated according to B<FIPS186-4> by calling:
196
197    int gindex = 2;
198    unsigned int pbits = 2048;
199    unsigned int qbits = 256;
200    OSSL_PARAM params[6];
201    EVP_PKEY *param_key = NULL;
202    EVP_PKEY_CTX *pctx = NULL;
203
204    pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
205    EVP_PKEY_paramgen_init(pctx);
206
207    params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
208    params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
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();
213    EVP_PKEY_CTX_set_params(pctx, params);
214
215    EVP_PKEY_generate(pctx, &param_key);
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
222A B<DH> key can be generated using domain parameters by calling:
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);
228    EVP_PKEY_generate(gctx, &key);
229    EVP_PKEY_print_private(bio_out, key, 0, NULL);
230    ...
231    EVP_PKEY_free(key);
232    EVP_PKEY_CTX_free(gctx);
233
234To validate B<FIPS186-4> B<DHX> domain parameters decoded from B<PEM> or
235B<DER> data, additional values used during generation may be required to
236be set into the key.
237
238EVP_PKEY_todata(), OSSL_PARAM_merge(), and EVP_PKEY_fromdata() are useful
239to add these parameters to the original key or domain parameters before
240the actual validation. In production code the return values should be checked.
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 = ...;
248    OSSL_PARAM extra_params[4];
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);
257    /*
258     * NOTE: For unverifiable g use "hindex" instead of "gindex"
259     * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex);
260     */
261    extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex);
262    extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter);
263    extra_params[3] = OSSL_PARAM_construct_end();
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);
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
296The 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
306The following sections of FIPS186-4:
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
320L<EVP_PKEY-FFC(7)>,
321L<EVP_KEYEXCH-DH(7)>
322L<EVP_PKEY(3)>,
323L<provider-keymgmt(7)>,
324L<EVP_KEYMGMT(3)>,
325L<OSSL_PROVIDER-default(7)>,
326L<OSSL_PROVIDER-FIPS(7)>
327
328=head1 COPYRIGHT
329
330Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
331
332Licensed under the Apache License 2.0 (the "License").  You may not use
333this file except in compliance with the License.  You can obtain a copy
334in the file LICENSE in the source distribution or at
335L<https://www.openssl.org/source/license.html>.
336
337=cut
338