]>
Commit | Line | Data |
---|---|---|
b8086652 SL |
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 | ||
023b188c | 32 | =item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string> |
b8086652 SL |
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 | ||
6a9bd929 MC |
57 | =item "tls-encoded-pt" (B<OSSL_PKEY_PARAM_TLS_ENCODED_PT>) <octet string> |
58 | ||
59 | Used for getting and setting the encoding of the DH public key used in a key | |
60 | exchange message for the TLS protocol. | |
61 | ||
b8086652 SL |
62 | =back |
63 | ||
64 | =head2 DH domain parameter / key generation parameters | |
65 | ||
66 | In addition to the common FCC key generation parameters that all FFC key types | |
67 | should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>)) the | |
68 | B<DH> keytype implementation supports the following: | |
69 | ||
70 | =over 4 | |
71 | ||
72 | =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string> | |
73 | ||
74 | Sets the type of parameter generation. For B<DH> valid values are: | |
75 | ||
76 | =over 4 | |
77 | ||
78 | =item "fips186_4" | |
79 | ||
80 | =item "default" | |
81 | ||
82 | =item "fips186_2" | |
83 | ||
84 | These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters> | |
85 | ||
86 | =item "group" | |
87 | ||
88 | This specifies that a named safe prime name will be chosen using the "pbits" | |
89 | type. | |
90 | ||
91 | =item "generator" | |
92 | ||
93 | A safe prime generator. See the "safeprime-generator" type above. | |
94 | ||
95 | =back | |
96 | ||
97 | =item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer> | |
98 | ||
99 | Sets the size (in bits) of the prime 'p'. | |
100 | ||
101 | For "fips186_4" this must be 2048. | |
102 | For "fips186_2" this must be 1024. | |
103 | For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192. | |
104 | ||
105 | =item "priv_len" (B<OSSL_PKEY_PARAM_DH_PRIV_LEN>) <integer> | |
106 | ||
107 | An optional value to set the maximum length of the generated private key. | |
8c1cbc72 | 108 | The default value used if this is not set is the maximum value of |
b8086652 SL |
109 | BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s. |
110 | Where s is the security strength of the key which has values of | |
111 | 112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192. | |
112 | ||
113 | =back | |
114 | ||
115 | =head1 EXAMPLES | |
116 | ||
117 | An B<EVP_PKEY> context can be obtained by calling: | |
118 | ||
119 | EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); | |
120 | ||
121 | An B<DH> key can be generated with a named safe prime group by calling: | |
122 | ||
123 | int priv_len = 2 * 112; | |
124 | OSSL_PARAM params[3]; | |
125 | EVP_PKEY *pkey = NULL; | |
126 | EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); | |
127 | ||
128 | params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0); | |
129 | /* "priv_len" is optional */ | |
130 | params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len); | |
131 | params[2] = OSSL_PARAM_construct_end(); | |
132 | ||
133 | EVP_PKEY_keygen_init(pctx); | |
134 | EVP_PKEY_CTX_set_params(pctx, params); | |
135 | EVP_PKEY_gen(pctx, &pkey); | |
136 | ... | |
137 | EVP_PKEY_free(key); | |
138 | EVP_PKEY_CTX_free(pctx); | |
139 | ||
140 | Legacy B<DH> domain parameters can be generated by calling: | |
141 | unsigned int pbits = 2048; | |
142 | unsigned int qbits = 256; | |
143 | int gindex = 1; | |
144 | OSSL_PARAM params[5]; | |
145 | EVP_PKEY *param_key = NULL; | |
146 | EVP_PKEY_CTX *pctx = NULL; | |
147 | ||
148 | pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); | |
149 | EVP_PKEY_paramgen_init(pctx); | |
2edb571b | 150 | |
b8086652 SL |
151 | params[0] = OSSL_PARAM_construct_uint("pbits", &pbits); |
152 | params[1] = OSSL_PARAM_construct_uint("qbits", &qbits); | |
153 | params[2] = OSSL_PARAM_construct_int("gindex", &gindex); | |
154 | params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0); | |
155 | params[4] = OSSL_PARAM_construct_end(); | |
156 | EVP_PKEY_CTX_set_params(pctx, params); | |
157 | ||
158 | EVP_PKEY_gen(pctx, ¶m_key); | |
159 | ||
160 | EVP_PKEY_print_params(bio_out, param_key, 0, NULL); | |
161 | ... | |
162 | EVP_PKEY_free(param_key); | |
163 | EVP_PKEY_CTX_free(pctx); | |
164 | ||
165 | An B<DH> key can be generated using domain parameters by calling: | |
166 | ||
167 | EVP_PKEY *key = NULL; | |
168 | EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL); | |
169 | ||
170 | EVP_PKEY_keygen_init(gctx); | |
171 | EVP_PKEY_gen(gctx, &key); | |
172 | EVP_PKEY_print_private(bio_out, key, 0, NULL); | |
173 | ... | |
174 | EVP_PKEY_free(key); | |
175 | EVP_PKEY_CTX_free(gctx); | |
176 | ||
177 | =for comment TODO(3.0): To validate domain parameters, additional values used | |
178 | during generation may be required to be set into the key. | |
179 | ||
180 | =head1 CONFORMING TO | |
181 | ||
182 | =over 4 | |
183 | ||
184 | =item RFC 7919 (TLS ffdhe named safe prime groups) | |
185 | ||
186 | =item RFC 3526 (IKE modp named safe prime groups) | |
187 | ||
188 | =item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224" | |
189 | and "dh_2048_256"). | |
190 | ||
191 | =back | |
192 | ||
193 | The following sections of SP800-56Ar3: | |
194 | ||
195 | =over 4 | |
196 | ||
197 | =item 5.5.1.1 FFC Domain Parameter Selection/Generation | |
198 | ||
199 | =item Appendix D: FFC Safe-prime Groups | |
200 | ||
201 | =back | |
202 | ||
203 | The following sections of FIPS 186-4: | |
204 | ||
205 | =over 4 | |
206 | ||
207 | =item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function. | |
208 | ||
209 | =item A.2.3 Generation of canonical generator g. | |
210 | ||
211 | =item A.2.1 Unverifiable Generation of the Generator g. | |
212 | ||
213 | =back | |
214 | ||
215 | =head1 SEE ALSO | |
216 | ||
217 | L<EVP_PKEY-FFC(7)>, | |
218 | L<EVP_KEYEXCH-DH(7)> | |
219 | L<EVP_PKEY(3)>, | |
220 | L<provider-keymgmt(7)>, | |
221 | L<EVP_KEYMGMT(3)>, | |
222 | L<OSSL_PROVIDER-default(7)>, | |
223 | L<OSSL_PROVIDER-FIPS(7)> | |
224 | ||
225 | =head1 COPYRIGHT | |
226 | ||
227 | Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. | |
228 | ||
229 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
230 | this file except in compliance with the License. You can obtain a copy | |
231 | in the file LICENSE in the source distribution or at | |
232 | L<https://www.openssl.org/source/license.html>. | |
233 | ||
234 | =cut |