Debian Codegraph @

upstream/debian-unstable/man7/EVP_PKEY-DH.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_PKEY-DH 7SSL"
58 .TH EVP_PKEY-DH 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_PKEY\-DH, EVP_PKEY\-DHX, EVP_KEYMGMT\-DH, EVP_KEYMGMT\-DHX
65 \&\- EVP_PKEY DH and DHX keytype and algorithm support
66 .SH DESCRIPTION
67 .IX Header "DESCRIPTION"
68 For finite field Diffie-Hellman key agreement, two classes of domain
69 parameters can be used: "safe" domain parameters that are associated with
70 approved named safe-prime groups, and a class of "FIPS186\-type" domain
71 parameters. FIPS186\-type domain parameters should only be used for backward
72 compatibility with existing applications that cannot be upgraded to use the
73 approved safe-prime groups.
74 .PP
75 See \fBEVP_PKEY\-FFC\fR\|(7) for more information about FFC keys.
76 .PP
77 The \fBDH\fR key type uses PKCS#3 format which saves \fIp\fR and \fIg\fR, but not the
78 \&\fIq\fR value.
79 The \fBDHX\fR key type uses X9.42 format which saves the value of \fIq\fR and this
80 must be used for FIPS186\-4. If key validation is required, users should be aware
81 of the nuances associated with FIPS186\-4 style parameters as discussed in
82 "DH and DHX key validation".
83 .SS "DH and DHX domain parameters"
84 .IX Subsection "DH and DHX domain parameters"
85 In addition to the common FFC parameters that all FFC keytypes should support
86 (see "FFC parameters" in \fBEVP_PKEY\-FFC\fR\|(7)) the \fBDHX\fR and \fBDH\fR keytype
87 implementations support the following:
88 .IP """group"" (\fBOSSL_PKEY_PARAM_GROUP_NAME\fR) <UTF8 string>" 4
89 .IX Item """group"" (OSSL_PKEY_PARAM_GROUP_NAME) <UTF8 string>"
90 Sets or gets a string that associates a \fBDH\fR or \fBDHX\fR named safe prime group
91 with known values for \fIp\fR, \fIq\fR and \fIg\fR.
92 .Sp
93 The following values can be used by the OpenSSL's default and FIPS providers:
94 "ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192",
95 "modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192".
96 .Sp
97 The following additional values can also be used by OpenSSL's default provider:
98 "modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256".
99 .Sp
100 DH/DHX named groups can be easily validated since the parameters are well known.
101 For protocols that only transfer \fIp\fR and \fIg\fR the value of \fIq\fR can also be
102 retrieved.
103 .SS "DH and DHX additional parameters"
104 .IX Subsection "DH and DHX additional parameters"
105 .IP """encoded-pub-key"" (\fBOSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY\fR) <octet string>" 4
106 .IX Item """encoded-pub-key"" (OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY) <octet string>"
107 Used for getting and setting the encoding of the DH public key used in a key
108 exchange message for the TLS protocol.
109 See \fBEVP_PKEY_set1_encoded_public_key()\fR and \fBEVP_PKEY_get1_encoded_public_key()\fR.
110 .SS "DH additional domain parameters"
111 .IX Subsection "DH additional domain parameters"
112 .IP """safeprime-generator"" (\fBOSSL_PKEY_PARAM_DH_GENERATOR\fR) <integer>" 4
113 .IX Item """safeprime-generator"" (OSSL_PKEY_PARAM_DH_GENERATOR) <integer>"
114 Used for DH generation of safe primes using the old safe prime generator code.
115 The default value is 2.
116 It is recommended to use a named safe prime group instead, if domain parameter
117 validation is required.
118 .Sp
119 Randomly generated safe primes are not allowed by FIPS, so setting this value
120 for the OpenSSL FIPS provider will instead choose a named safe prime group
121 based on the size of \fIp\fR.
122 .SS "DH and DHX domain parameter / key generation parameters"
123 .IX Subsection "DH and DHX domain parameter / key generation parameters"
124 In addition to the common FFC key generation parameters that all FFC key types
125 should support (see "FFC key generation parameters" in \fBEVP_PKEY\-FFC\fR\|(7)) the
126 \&\fBDH\fR and \fBDHX\fR keytype implementation supports the following:
127 .IP """type"" (\fBOSSL_PKEY_PARAM_FFC_TYPE\fR) <UTF8 string>" 4
128 .IX Item """type"" (OSSL_PKEY_PARAM_FFC_TYPE) <UTF8 string>"
129 Sets the type of parameter generation. For \fBDH\fR valid values are:
130 .RS 4
131 .IP """fips186_4""" 4
132 .IX Item """fips186_4"""
133 .PD 0
134 .IP """default""" 4
135 .IX Item """default"""
136 .IP """fips186_2""" 4
137 .IX Item """fips186_2"""
138 .PD
139 These are described in "FFC key generation parameters" in \fBEVP_PKEY\-FFC\fR\|(7)
140 .IP """group""" 4
141 .IX Item """group"""
142 This specifies that a named safe prime name will be chosen using the "pbits"
143 type.
144 .IP """generator""" 4
145 .IX Item """generator"""
146 A safe prime generator. See the "safeprime-generator" type above.
147 This is only valid for \fBDH\fR keys.
148 .RE
149 .RS 4
150 .RE
151 .IP """pbits"" (\fBOSSL_PKEY_PARAM_FFC_PBITS\fR) <unsigned integer>" 4
152 .IX Item """pbits"" (OSSL_PKEY_PARAM_FFC_PBITS) <unsigned integer>"
153 Sets the size (in bits) of the prime 'p'.
154 .Sp
155 For "fips186_4" this must be 2048.
156 For "fips186_2" this must be 1024.
157 For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
158 .IP """priv_len"" (\fBOSSL_PKEY_PARAM_DH_PRIV_LEN\fR) <integer>" 4
159 .IX Item """priv_len"" (OSSL_PKEY_PARAM_DH_PRIV_LEN) <integer>"
160 An optional value to set the maximum length of the generated private key.
161 The default value used if this is not set is the maximum value of
162 BN_num_bits(\fIq\fR)). The minimum value that this can be set to is 2 * s.
163 Where s is the security strength of the key which has values of
164 112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.
165 .SS "DH and DHX key validation"
166 .IX Subsection "DH and DHX key validation"
167 For keys that are not a named group the FIPS186\-4 standard specifies that the
168 values used for FFC parameter generation are also required for parameter
169 validation. This means that optional FFC domain parameter values for
170 \&\fIseed\fR, \fIpcounter\fR and \fIgindex\fR or \fIhindex\fR may need to be stored for
171 validation purposes.
172 For \fBDHX\fR the \fIseed\fR and \fIpcounter\fR can be stored in ASN1 data
173 (but the \fIgindex\fR or \fIhindex\fR cannot be stored). It is recommended to use a
174 \&\fBDH\fR parameters with named safe prime group instead.
175 .PP
176 With the OpenSSL FIPS provider, \fBEVP_PKEY_param_check\fR\|(3) and
177 \&\fBEVP_PKEY_param_check_quick\fR\|(3) behave in the following way: the parameters
178 are tested if they are either an approved safe prime group OR that the FFC
179 parameters conform to FIPS186\-4 as defined in SP800\-56Ar3 \fIAssurances of
180 Domain-Parameter Validity\fR.
181 .PP
182 The OpenSSL default provider uses simpler checks that allows there to be no \fIq\fR
183 value for backwards compatibility, however the \fBEVP_PKEY_param_check\fR\|(3) will
184 test the \fIp\fR value for being a prime (and a safe prime if \fIq\fR is missing)
185 which can take significant time. The \fBEVP_PKEY_param_check_quick\fR\|(3) avoids
186 the prime tests.
187 .PP
188 \&\fBEVP_PKEY_public_check\fR\|(3) conforms to SP800\-56Ar3
189 \&\fIFFC Full Public-Key Validation\fR.
190 .PP
191 \&\fBEVP_PKEY_public_check_quick\fR\|(3) conforms to SP800\-56Ar3
192 \&\fIFFC Partial Public-Key Validation\fR when the key is an approved named safe
193 prime group, otherwise it is the same as \fBEVP_PKEY_public_check\fR\|(3).
194 .PP
195 \&\fBEVP_PKEY_private_check\fR\|(3) tests that the private key is in the correct range
196 according to SP800\-56Ar3. The OpenSSL FIPS provider requires the value of \fIq\fR
197 to be set (note that this is implicitly set for named safe prime groups).
198 For backwards compatibility the OpenSSL default provider only requires \fIp\fR to
199 be set.
200 .PP
201 \&\fBEVP_PKEY_pairwise_check\fR\|(3) conforms to SP800\-56Ar3
202 \&\fIOwner Assurance of Pair-wise Consistency\fR.
203 .SH EXAMPLES
204 .IX Header "EXAMPLES"
205 An \fBEVP_PKEY\fR context can be obtained by calling:
206 .PP
207 .Vb 1
208 \& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
209 .Ve
210 .PP
211 A \fBDH\fR key can be generated with a named safe prime group by calling:
212 .PP
213 .Vb 4
214 \& int priv_len = 2 * 112;
215 \& OSSL_PARAM params[3];
216 \& EVP_PKEY *pkey = NULL;
217 \& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
218 \&
219 \& params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0);
220 \& /* "priv_len" is optional */
221 \& params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len);
222 \& params[2] = OSSL_PARAM_construct_end();
223 \&
224 \& EVP_PKEY_keygen_init(pctx);
225 \& EVP_PKEY_CTX_set_params(pctx, params);
226 \& EVP_PKEY_generate(pctx, &pkey);
227 \& ...
228 \& EVP_PKEY_free(pkey);
229 \& EVP_PKEY_CTX_free(pctx);
230 .Ve
231 .PP
232 \&\fBDHX\fR domain parameters can be generated according to \fBFIPS186\-4\fR by calling:
233 .PP
234 .Vb 6
235 \& int gindex = 2;
236 \& unsigned int pbits = 2048;
237 \& unsigned int qbits = 256;
238 \& OSSL_PARAM params[6];
239 \& EVP_PKEY *param_key = NULL;
240 \& EVP_PKEY_CTX *pctx = NULL;
241 \&
242 \& pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
243 \& EVP_PKEY_paramgen_init(pctx);
244 \&
245 \& params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
246 \& params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
247 \& params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
248 \& params[3] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0);
249 \& params[4] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0);
250 \& params[5] = OSSL_PARAM_construct_end();
251 \& EVP_PKEY_CTX_set_params(pctx, params);
252 \&
253 \& EVP_PKEY_generate(pctx, &param_key);
254 \&
255 \& EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
256 \& ...
257 \& EVP_PKEY_free(param_key);
258 \& EVP_PKEY_CTX_free(pctx);
259 .Ve
260 .PP
261 A \fBDH\fR key can be generated using domain parameters by calling:
262 .PP
263 .Vb 2
264 \& EVP_PKEY *key = NULL;
265 \& EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
266 \&
267 \& EVP_PKEY_keygen_init(gctx);
268 \& EVP_PKEY_generate(gctx, &key);
269 \& EVP_PKEY_print_private(bio_out, key, 0, NULL);
270 \& ...
271 \& EVP_PKEY_free(key);
272 \& EVP_PKEY_CTX_free(gctx);
273 .Ve
274 .PP
275 To validate \fBFIPS186\-4\fR \fBDHX\fR domain parameters decoded from \fBPEM\fR or
276 \&\fBDER\fR data, additional values used during generation may be required to
277 be set into the key.
278 .PP
279 \&\fBEVP_PKEY_todata()\fR, \fBOSSL_PARAM_merge()\fR, and \fBEVP_PKEY_fromdata()\fR are useful
280 to add these parameters to the original key or domain parameters before
281 the actual validation. In production code the return values should be checked.
282 .PP
283 .Vb 11
284 \& EVP_PKEY *received_domp = ...; /* parameters received and decoded */
285 \& unsigned char *seed = ...; /* and additional parameters received */
286 \& size_t seedlen = ...; /* by other means, required */
287 \& int gindex = ...; /* for the validation */
288 \& int pcounter = ...;
289 \& int hindex = ...;
290 \& OSSL_PARAM extra_params[4];
291 \& OSSL_PARAM *domain_params = NULL;
292 \& OSSL_PARAM *merged_params = NULL;
293 \& EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL;
294 \& EVP_PKEY *complete_domp = NULL;
295 \&
296 \& EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS,
297 \& &domain_params);
298 \& extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen);
299 \& /*
300 \& * NOTE: For unverifiable g use "hindex" instead of "gindex"
301 \& * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex);
302 \& */
303 \& extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex);
304 \& extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter);
305 \& extra_params[3] = OSSL_PARAM_construct_end();
306 \& merged_params = OSSL_PARAM_merge(domain_params, extra_params);
307 \&
308 \& ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
309 \& EVP_PKEY_fromdata_init(ctx);
310 \& EVP_PKEY_fromdata(ctx, &complete_domp, OSSL_KEYMGMT_SELECT_ALL,
311 \& merged_params);
312 \&
313 \& validate_ctx = EVP_PKEY_CTX_new_from_pkey(NULL, complete_domp, NULL);
314 \& if (EVP_PKEY_param_check(validate_ctx) > 0)
315 \& /* validation_passed(); */
316 \& else
317 \& /* validation_failed(); */
318 \&
319 \& OSSL_PARAM_free(domain_params);
320 \& OSSL_PARAM_free(merged_params);
321 \& EVP_PKEY_CTX_free(ctx);
322 \& EVP_PKEY_CTX_free(validate_ctx);
323 \& EVP_PKEY_free(complete_domp);
324 .Ve
325 .SH "CONFORMING TO"
326 .IX Header "CONFORMING TO"
327 .IP "RFC 7919 (TLS ffdhe named safe prime groups)" 4
328 .IX Item "RFC 7919 (TLS ffdhe named safe prime groups)"
329 .PD 0
330 .IP "RFC 3526 (IKE modp named safe prime groups)" 4
331 .IX Item "RFC 3526 (IKE modp named safe prime groups)"
332 .IP "RFC 5114 (Additional DH named groups for dh_1024_160"", ""dh_2048_224"" and ""dh_2048_256"")." 4
333 .IX Item "RFC 5114 (Additional DH named groups for dh_1024_160"", ""dh_2048_224"" and ""dh_2048_256"")."
334 .PD
335 .PP
336 The following sections of SP800\-56Ar3:
337 .IP "5.5.1.1 FFC Domain Parameter Selection/Generation" 4
338 .IX Item "5.5.1.1 FFC Domain Parameter Selection/Generation"
339 .PD 0
340 .IP "Appendix D: FFC Safe-prime Groups" 4
341 .IX Item "Appendix D: FFC Safe-prime Groups"
342 .PD
343 .PP
344 The following sections of FIPS186\-4:
345 .IP "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function." 4
346 .IX Item "A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function."
347 .PD 0
348 .IP "A.2.3 Generation of canonical generator g." 4
349 .IX Item "A.2.3 Generation of canonical generator g."
350 .IP "A.2.1 Unverifiable Generation of the Generator g." 4
351 .IX Item "A.2.1 Unverifiable Generation of the Generator g."
352 .PD
353 .SH "SEE ALSO"
354 .IX Header "SEE ALSO"
355 \&\fBEVP_PKEY\-FFC\fR\|(7),
356 \&\fBEVP_KEYEXCH\-DH\fR\|(7)
357 \&\fBEVP_PKEY\fR\|(3),
358 \&\fBprovider\-keymgmt\fR\|(7),
359 \&\fBEVP_KEYMGMT\fR\|(3),
360 \&\fBOSSL_PROVIDER\-default\fR\|(7),
361 \&\fBOSSL_PROVIDER\-FIPS\fR\|(7)
362 .SH COPYRIGHT
363 .IX Header "COPYRIGHT"
364 Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved.
365 .PP
366 Licensed under the Apache License 2.0 (the "License"). You may not use
367 this file except in compliance with the License. You can obtain a copy
368 in the file LICENSE in the source distribution or at
369 <https://www.openssl.org/source/license.html>.