1EVP_PKEY-DH(7ossl) OpenSSL EVP_PKEY-DH(7ossl)
2
6 EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH, EVP_KEYMGMT-DHX - EVP_PKEY
7 DH and DHX keytype and algorithm support
8
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 See EVP_PKEY-FFC(7) for more information about FFC keys.
18 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 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 "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 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 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 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 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 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 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 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 "type" (OSSL_PKEY_PARAM_FFC_TYPE) <UTF8 string>
72 Sets the type of parameter generation. For DH valid values are:
73 "fips186_4"
75 "default"
76 "fips186_2"
77 These are described in "FFC key generation parameters" in
78 EVP_PKEY-FFC(7)
79 "group"
81 This specifies that a named safe prime name will be chosen
82 using the "pbits" type.
83 "generator"
85 A safe prime generator. See the "safeprime-generator" type
86 above. This is only valid for DH keys.
87 "pbits" (OSSL_PKEY_PARAM_FFC_PBITS) <unsigned integer>
89 Sets the size (in bits) of the prime 'p'.
90 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 "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 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 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 For DH keys, EVP_PKEY_param_check_quick(3) is equivalent to
120 EVP_PKEY_param_check(3).
121 For DH keys, EVP_PKEY_public_check(3) conforms to SP800-56Ar3 FFC Full
123 Public-Key Validation.
124 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 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 For DH keys, EVP_PKEY_pairwise_check(3) conforms to SP800-56Ar3 Owner
136 Assurance of Pair-wise Consistency.
137
139 An EVP_PKEY context can be obtained by calling:
140 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
142 A DH key can be generated with a named safe prime group by calling:
144 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 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 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 DHX domain parameters can be generated according to FIPS186-4 by
163 calling:
164 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 pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
173 EVP_PKEY_paramgen_init(pctx);
174 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 EVP_PKEY_generate(pctx, ¶m_key);
184 EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
186 ...
187 EVP_PKEY_free(param_key);
188 EVP_PKEY_CTX_free(pctx);
189 A DH key can be generated using domain parameters by calling:
191 EVP_PKEY *key = NULL;
193 EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
194 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 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 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 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 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 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 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 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
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 The following sections of SP800-56Ar3:
259 5.5.1.1 FFC Domain Parameter Selection/Generation
261 Appendix D: FFC Safe-prime Groups
262 The following sections of FIPS186-4:
264 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
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 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>.
2813.0.5 2022-07-05 EVP_PKEY-DH(7ossl)