33b19a74f9b2e64c5d7a44de32d9557301fc42d1
[openssl.git] / doc / man7 / EVP_PKEY-DH.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_PKEY-DH, EVP_KEYMGMT-DH - EVP_PKEY DH keytype and algorithm support
6
7 =head1 DESCRIPTION
8
9 For B<DH> FFC key agreement, two classes of domain parameters can be used:
10 "safe" domain parameters that are associated with approved named safe-prime
11 groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain
12 parameters should only be used for backward compatibility with existing
13 applications that cannot be upgraded to use the approved safe-prime groups.
14
15 See L<EVP_PKEY-FFC(7)> for more information about FFC keys.
16
17 For B<DH> that is not a named group) the FIPS186-4 standard specifies that the
18 values used for FFC parameter generation are also required for parameter
19 validation. This means that optional FFC domain parameter values for
20 I<seed>, I<pcounter> and I<gindex> may need to be stored for validation purposes.
21 For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
22 (but the I<gindex> is not).
23
24 =head2 DH parameters
25
26 In addition to the common FCC parameters that all FFC keytypes should support
27 (see L<EVP_PKEY-FFC(7)/FFC parameters>)) the B<DH> keytype
28 implementation supports the following:
29
30 =over 4
31
32 =item "group" (B<OSSL_PKEY_PARAM_DH_GROUP>) <UTF8 string>
33
34 Set or gets a string that associates a B<DH> named safe prime group with known
35 values for I<p>, I<q> and I<g>.
36
37 The following values can be used by the OpenSSL's default and FIPS providers:
38 "ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192",
39 "modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192".
40
41 The following additional values can also be used by OpenSSL's default provider:
42 "modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256".
43
44 DH named groups can be easily validated since the parameters are well known.
45 For protocols that only transfer I<p> and I<g> the value of I<q> can also be
46 retrieved.
47
48 =item "safeprime-generator" (B<OSSL_PKEY_PARAM_DH_GENERATOR>) <integer>
49
50 Used for DH generation of safe primes using the old generator code.
51 It is recommended to use a named safe prime group instead, if domain parameter
52 validation is required. The default value is 2.
53
54 These are not named safe prime groups so setting this value for the OpenSSL FIPS
55 provider will instead choose a named safe prime group based on the size of I<p>.
56
57 =back
58
59 =head2 DH domain parameter / key generation parameters
60
61 In addition to the common FCC key generation parameters that all FFC key types
62 should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>)) the
63 B<DH> keytype implementation supports the following:
64
65 =over 4
66
67 =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
68
69 Sets the type of parameter generation. For B<DH> valid values are:
70
71 =over 4
72
73 =item "fips186_4"
74
75 =item "default"
76
77 =item "fips186_2"
78
79 These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters>
80
81 =item "group"
82
83 This specifies that a named safe prime name will be chosen using the "pbits"
84 type.
85
86 =item "generator"
87
88 A safe prime generator. See the "safeprime-generator" type above.
89
90 =back
91
92 =item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
93
94 Sets the size (in bits) of the prime 'p'.
95
96 For "fips186_4" this must be 2048.
97 For "fips186_2" this must be 1024.
98 For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
99
100 =item "priv_len" (B<OSSL_PKEY_PARAM_DH_PRIV_LEN>) <integer>
101
102 An optional value to set the maximum length of the generated private key.
103 The default valure used if this is not set is the maximum value of
104 BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s.
105 Where s is the security strength of the key which has values of
106 112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.
107
108 =back
109
110 =head1 EXAMPLES
111
112 An B<EVP_PKEY> context can be obtained by calling:
113
114     EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
115
116 An B<DH> key can be generated with a named safe prime group by calling:
117
118     int priv_len = 2 * 112;
119     OSSL_PARAM params[3];
120     EVP_PKEY *pkey = NULL;
121     EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
122
123     params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0);
124     /* "priv_len" is optional */
125     params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len);
126     params[2] = OSSL_PARAM_construct_end();
127
128     EVP_PKEY_keygen_init(pctx);
129     EVP_PKEY_CTX_set_params(pctx, params);
130     EVP_PKEY_gen(pctx, &pkey);
131     ...
132     EVP_PKEY_free(key);
133     EVP_PKEY_CTX_free(pctx);
134
135 Legacy B<DH> domain parameters can be generated by calling:
136     unsigned int pbits = 2048;
137     unsigned int qbits = 256;
138     int gindex = 1;
139     OSSL_PARAM params[5];
140     EVP_PKEY *param_key = NULL;
141     EVP_PKEY_CTX *pctx = NULL;
142
143     pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
144     EVP_PKEY_paramgen_init(pctx);
145     
146     params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
147     params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
148     params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
149     params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
150     params[4] = OSSL_PARAM_construct_end();
151     EVP_PKEY_CTX_set_params(pctx, params);
152
153     EVP_PKEY_gen(pctx, &param_key);
154
155     EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
156     ...
157     EVP_PKEY_free(param_key);
158     EVP_PKEY_CTX_free(pctx);
159
160 An B<DH> key can be generated using domain parameters by calling:
161
162     EVP_PKEY *key = NULL;
163     EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
164
165     EVP_PKEY_keygen_init(gctx);
166     EVP_PKEY_gen(gctx, &key);
167     EVP_PKEY_print_private(bio_out, key, 0, NULL);
168     ...
169     EVP_PKEY_free(key);
170     EVP_PKEY_CTX_free(gctx);
171
172 =for comment TODO(3.0): To validate domain parameters, additional values used
173 during generation may be required to be set into the key.
174
175 =head1 CONFORMING TO
176
177 =over 4
178
179 =item RFC 7919 (TLS ffdhe named safe prime groups)
180
181 =item RFC 3526 (IKE modp named safe prime groups)
182
183 =item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224"
184           and "dh_2048_256").
185
186 =back
187
188 The following sections of SP800-56Ar3:
189
190 =over 4
191
192 =item 5.5.1.1 FFC Domain Parameter Selection/Generation
193
194 =item Appendix D: FFC Safe-prime Groups
195
196 =back
197
198 The following sections of FIPS 186-4:
199
200 =over 4
201
202 =item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
203
204 =item A.2.3 Generation of canonical generator g.
205
206 =item A.2.1 Unverifiable Generation of the Generator g.
207
208 =back
209
210 =head1 SEE ALSO
211
212 L<EVP_PKEY-FFC(7)>,
213 L<EVP_KEYEXCH-DH(7)>
214 L<EVP_PKEY(3)>,
215 L<provider-keymgmt(7)>,
216 L<EVP_KEYMGMT(3)>,
217 L<OSSL_PROVIDER-default(7)>,
218 L<OSSL_PROVIDER-FIPS(7)>
219
220 =head1 COPYRIGHT
221
222 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
223
224 Licensed under the Apache License 2.0 (the "License").  You may not use
225 this file except in compliance with the License.  You can obtain a copy
226 in the file LICENSE in the source distribution or at
227 L<https://www.openssl.org/source/license.html>.
228
229 =cut