1EVP_PKEY-DH(7ossl)                  OpenSSL                 EVP_PKEY-DH(7ossl)
2
3
4

NAME

6       EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH, EVP_KEYMGMT-DHX - EVP_PKEY
7       DH and DHX keytype and algorithm support
8

DESCRIPTION

10       For DH FFC key agreement, two classes of domain parameters can be used:
11       "safe" domain parameters that are associated with approved named safe-
12       prime groups, and a class of "FIPS186-type" domain parameters.
13       FIPS186-type domain parameters should only be used for backward
14       compatibility with existing applications that cannot be upgraded to use
15       the approved safe-prime groups.
16
17       See EVP_PKEY-FFC(7) for more information about FFC keys.
18
19       The DH key type uses PKCS#3 format which saves p and g, but not the q
20       value.  The DHX key type uses X9.42 format which saves the value of q
21       and this must be used for FIPS186-4. If key validation is required,
22       users should be aware of the nuances associated with FIPS186-4 style
23       parameters as discussed in "DH key validation".
24
25   DH and DHX domain parameters
26       In addition to the common FCC parameters that all FFC keytypes should
27       support (see "FFC parameters" in EVP_PKEY-FFC(7)) the DHX and DH
28       keytype implementations support the following:
29
30       "group" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>
31           Sets or gets a string that associates a DH or DHX named safe prime
32           group with known values for p, q and g.
33
34           The following values can be used by the OpenSSL's default and FIPS
35           providers: "ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144",
36           "ffdhe8192", "modp_2048", "modp_3072", "modp_4096", "modp_6144",
37           "modp_8192".
38
39           The following additional values can also be used by OpenSSL's
40           default provider: "modp_1536", "dh_1024_160", "dh_2048_224",
41           "dh_2048_256".
42
43           DH/DHX named groups can be easily validated since the parameters
44           are well known.  For protocols that only transfer p and g the value
45           of q can also be retrieved.
46
47   DH and DHX additional parameters
48       "encoded-pub-key" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>
49           Used for getting and setting the encoding of the DH public key used
50           in a key exchange message for the TLS protocol.  See
51           EVP_PKEY_set1_encoded_public_key() and
52           EVP_PKEY_get1_encoded_public_key().
53
54   DH additional domain parameters
55       "safeprime-generator" (OSSL_PKEY_PARAM_DH_GENERATOR) <integer>
56           Used for DH generation of safe primes using the old safe prime
57           generator code.  The default value is 2.  It is recommended to use
58           a named safe prime group instead, if domain parameter validation is
59           required.
60
61           Randomly generated safe primes are not allowed by FIPS, so setting
62           this value for the OpenSSL FIPS provider will instead choose a
63           named safe prime group based on the size of p.
64
65   DH and DHX domain parameter / key generation parameters
66       In addition to the common FFC key generation parameters that all FFC
67       key types should support (see "FFC key generation parameters" in
68       EVP_PKEY-FFC(7)) the DH and DHX keytype implementation supports the
69       following:
70
71       "type" (OSSL_PKEY_PARAM_FFC_TYPE) <UTF8 string>
72           Sets the type of parameter generation. For DH valid values are:
73
74           "fips186_4"
75           "default"
76           "fips186_2"
77               These are described in "FFC key generation parameters" in
78               EVP_PKEY-FFC(7)
79
80           "group"
81               This specifies that a named safe prime name will be chosen
82               using the "pbits" type.
83
84           "generator"
85               A safe prime generator. See the "safeprime-generator" type
86               above.  This is only valid for DH keys.
87
88       "pbits" (OSSL_PKEY_PARAM_FFC_PBITS) <unsigned integer>
89           Sets the size (in bits) of the prime 'p'.
90
91           For "fips186_4" this must be 2048.  For "fips186_2" this must be
92           1024.  For "group" this can be any one of 2048, 3072, 4096, 6144 or
93           8192.
94
95       "priv_len" (OSSL_PKEY_PARAM_DH_PRIV_LEN) <integer>
96           An optional value to set the maximum length of the generated
97           private key.  The default value used if this is not set is the
98           maximum value of BN_num_bits(q)). The minimum value that this can
99           be set to is 2 * s.  Where s is the security strength of the key
100           which has values of 112, 128, 152, 176 and 200 for key sizes of
101           2048, 3072, 4096, 6144 and 8192.
102
103   DH key validation
104       For DHX that is not a named group the FIPS186-4 standard specifies that
105       the values used for FFC parameter generation are also required for
106       parameter validation. This means that optional FFC domain parameter
107       values for seed, pcounter and gindex or hindex may need to be stored
108       for validation purposes.  For DHX the seed and pcounter can be stored
109       in ASN1 data (but the gindex or hindex cannot be stored). It is
110       recommended to use a named safe prime group instead.
111
112       For DH keys, EVP_PKEY_param_check(3) behaves in the following way: The
113       OpenSSL FIPS provider tests if the parameters are either an approved
114       safe prime group OR that the FFC parameters conform to FIPS186-4 as
115       defined in SP800-56Ar3 Assurances of Domain-Parameter Validity.  The
116       OpenSSL default provider uses simpler checks that allows there to be no
117       q value for backwards compatibility.
118
119       For DH keys, EVP_PKEY_param_check_quick(3) is equivalent to
120       EVP_PKEY_param_check(3).
121
122       For DH keys, EVP_PKEY_public_check(3) conforms to SP800-56Ar3 FFC Full
123       Public-Key Validation.
124
125       For DH keys, EVP_PKEY_public_check_quick(3) conforms to SP800-56Ar3 FFC
126       Partial Public-Key Validation when the DH key is an approved named safe
127       prime group, otherwise it is the same as EVP_PKEY_public_check(3).
128
129       For DH Keys, EVP_PKEY_private_check(3) tests that the private key is in
130       the correct range according to SP800-56Ar3. The OpenSSL FIPS provider
131       requires the value of q to be set (note that this is set for named safe
132       prime groups).  For backwards compatibility the OpenSSL default
133       provider only requires p to be set.
134
135       For DH keys, EVP_PKEY_pairwise_check(3) conforms to SP800-56Ar3 Owner
136       Assurance of Pair-wise Consistency.
137

EXAMPLES

139       An EVP_PKEY context can be obtained by calling:
140
141           EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
142
143       A 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
162       DHX domain parameters can be generated according to FIPS186-4 by
163       calling:
164
165           int gindex = 2;
166           unsigned int pbits = 2048;
167           unsigned int qbits = 256;
168           OSSL_PARAM params[6];
169           EVP_PKEY *param_key = NULL;
170           EVP_PKEY_CTX *pctx = NULL;
171
172           pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
173           EVP_PKEY_paramgen_init(pctx);
174
175           params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
176           params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
177           params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
178           params[3] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0);
179           params[4] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0);
180           params[5] = OSSL_PARAM_construct_end();
181           EVP_PKEY_CTX_set_params(pctx, params);
182
183           EVP_PKEY_generate(pctx, &param_key);
184
185           EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
186           ...
187           EVP_PKEY_free(param_key);
188           EVP_PKEY_CTX_free(pctx);
189
190       A DH key can be generated using domain parameters by calling:
191
192           EVP_PKEY *key = NULL;
193           EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
194
195           EVP_PKEY_keygen_init(gctx);
196           EVP_PKEY_generate(gctx, &key);
197           EVP_PKEY_print_private(bio_out, key, 0, NULL);
198           ...
199           EVP_PKEY_free(key);
200           EVP_PKEY_CTX_free(gctx);
201
202       To validate FIPS186-4 DHX domain parameters decoded from PEM or DER
203       data, additional values used during generation may be required to be
204       set into the key.
205
206       EVP_PKEY_todata(), OSSL_PARAM_merge(), and EVP_PKEY_fromdata() are
207       useful to add these parameters to the original key or domain parameters
208       before the actual validation. In production code the return values
209       should be checked.
210
211           EVP_PKEY *received_domp = ...; /* parameters received and decoded */
212           unsigned char *seed = ...;     /* and additional parameters received */
213           size_t seedlen = ...;          /* by other means, required */
214           int gindex = ...;              /* for the validation */
215           int pcounter = ...;
216           int hindex = ...;
217           OSSL_PARAM extra_params[4];
218           OSSL_PARAM *domain_params = NULL;
219           OSSL_PARAM *merged_params = NULL;
220           EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL;
221           EVP_PKEY *complete_domp = NULL;
222
223           EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS,
224                           &domain_params);
225           extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen);
226           /*
227            * NOTE: For unverifiable g use "hindex" instead of "gindex"
228            * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex);
229            */
230           extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex);
231           extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter);
232           extra_params[3] = OSSL_PARAM_construct_end();
233           merged_params = OSSL_PARAM_merge(domain_params, extra_params);
234
235           ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
236           EVP_PKEY_fromdata_init(ctx);
237           EVP_PKEY_fromdata(ctx, &complete_domp, OSSL_KEYMGMT_SELECT_ALL,
238                             merged_params);
239
240           validate_ctx = EVP_PKEY_CTX_new_from_pkey(NULL, complete_domp, NULL);
241           if (EVP_PKEY_param_check(validate_ctx) > 0)
242               /* validation_passed(); */
243           else
244               /* validation_failed(); */
245
246           OSSL_PARAM_free(domain_params);
247           OSSL_PARAM_free(merged_params);
248           EVP_PKEY_CTX_free(ctx);
249           EVP_PKEY_CTX_free(validate_ctx);
250           EVP_PKEY_free(complete_domp);
251

CONFORMING TO

253       RFC 7919 (TLS ffdhe named safe prime groups)
254       RFC 3526 (IKE modp named safe prime groups)
255       RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224"
256       and "dh_2048_256").
257
258       The following sections of SP800-56Ar3:
259
260       5.5.1.1 FFC Domain Parameter Selection/Generation
261       Appendix D: FFC Safe-prime Groups
262
263       The following sections of FIPS186-4:
264
265       A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash
266       Function.
267       A.2.3 Generation of canonical generator g.
268       A.2.1 Unverifiable Generation of the Generator g.
269

SEE ALSO

271       EVP_PKEY-FFC(7), EVP_KEYEXCH-DH(7) EVP_PKEY(3), provider-keymgmt(7),
272       EVP_KEYMGMT(3), OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7)
273
275       Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
276
277       Licensed under the Apache License 2.0 (the "License").  You may not use
278       this file except in compliance with the License.  You can obtain a copy
279       in the file LICENSE in the source distribution or at
280       <https://www.openssl.org/source/license.html>.
281
282
283
2843.0.5                             2022-11-01                EVP_PKEY-DH(7ossl)
Impressum