1=pod 2 3=head1 NAME 4 5EVP_PKEY-DH, EVP_PKEY-DHX, EVP_KEYMGMT-DH, EVP_KEYMGMT-DHX 6- EVP_PKEY DH and DHX keytype and algorithm support 7 8=head1 DESCRIPTION 9 10For finite field Diffie-Hellman key agreement, two classes of domain 11parameters can be used: "safe" domain parameters that are associated with 12approved named safe-prime groups, and a class of "FIPS186-type" domain 13parameters. FIPS186-type domain parameters should only be used for backward 14compatibility with existing applications that cannot be upgraded to use the 15approved safe-prime groups. 16 17See L<EVP_PKEY-FFC(7)> for more information about FFC keys. 18 19The B<DH> key type uses PKCS#3 format which saves I<p> and I<g>, but not the 20I<q> value. 21The B<DHX> key type uses X9.42 format which saves the value of I<q> and this 22must be used for FIPS186-4. If key validation is required, users should be aware 23of the nuances associated with FIPS186-4 style parameters as discussed in 24L</DH and DHX key validation>. 25 26=head2 DH and DHX domain parameters 27 28In addition to the common FFC parameters that all FFC keytypes should support 29(see L<EVP_PKEY-FFC(7)/FFC parameters>) the B<DHX> and B<DH> keytype 30implementations support the following: 31 32=over 4 33 34=item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string> 35 36Sets or gets a string that associates a B<DH> or B<DHX> named safe prime group 37with known values for I<p>, I<q> and I<g>. 38 39The following values can be used by the OpenSSL's default and FIPS providers: 40"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192", 41"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192". 42 43The following additional values can also be used by OpenSSL's default provider: 44"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256". 45 46DH/DHX named groups can be easily validated since the parameters are well known. 47For protocols that only transfer I<p> and I<g> the value of I<q> can also be 48retrieved. 49 50=back 51 52=head2 DH and DHX additional parameters 53 54=over 4 55 56=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string> 57 58Used for getting and setting the encoding of the DH public key used in a key 59exchange message for the TLS protocol. 60See EVP_PKEY_set1_encoded_public_key() and EVP_PKEY_get1_encoded_public_key(). 61 62=back 63 64=head2 DH additional domain parameters 65 66=over 4 67 68=item "safeprime-generator" (B<OSSL_PKEY_PARAM_DH_GENERATOR>) <integer> 69 70Used for DH generation of safe primes using the old safe prime generator code. 71The default value is 2. 72It is recommended to use a named safe prime group instead, if domain parameter 73validation is required. 74 75Randomly generated safe primes are not allowed by FIPS, so setting this value 76for the OpenSSL FIPS provider will instead choose a named safe prime group 77based on the size of I<p>. 78 79=back 80 81=head2 DH and DHX domain parameter / key generation parameters 82 83In addition to the common FFC key generation parameters that all FFC key types 84should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>) the 85B<DH> and B<DHX> keytype implementation supports the following: 86 87=over 4 88 89=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <UTF8 string> 90 91Sets the type of parameter generation. For B<DH> valid values are: 92 93=over 4 94 95=item "fips186_4" 96 97=item "default" 98 99=item "fips186_2" 100 101These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters> 102 103=item "group" 104 105This specifies that a named safe prime name will be chosen using the "pbits" 106type. 107 108=item "generator" 109 110A safe prime generator. See the "safeprime-generator" type above. 111This is only valid for B<DH> keys. 112 113=back 114 115=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer> 116 117Sets the size (in bits) of the prime 'p'. 118 119For "fips186_4" this must be 2048. 120For "fips186_2" this must be 1024. 121For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192. 122 123=item "priv_len" (B<OSSL_PKEY_PARAM_DH_PRIV_LEN>) <integer> 124 125An optional value to set the maximum length of the generated private key. 126The default value used if this is not set is the maximum value of 127BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s. 128Where s is the security strength of the key which has values of 129112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192. 130 131=back 132 133=head2 DH and DHX key validation 134 135For keys that are not a named group the FIPS186-4 standard specifies that the 136values used for FFC parameter generation are also required for parameter 137validation. This means that optional FFC domain parameter values for 138I<seed>, I<pcounter> and I<gindex> or I<hindex> may need to be stored for 139validation purposes. 140For B<DHX> the I<seed> and I<pcounter> can be stored in ASN1 data 141(but the I<gindex> or I<hindex> cannot be stored). It is recommended to use a 142B<DH> parameters with named safe prime group instead. 143 144With the OpenSSL FIPS provider, L<EVP_PKEY_param_check(3)> and 145L<EVP_PKEY_param_check_quick(3)> behave in the following way: the parameters 146are tested if they are either an approved safe prime group OR that the FFC 147parameters conform to FIPS186-4 as defined in SP800-56Ar3 I<Assurances of 148Domain-Parameter Validity>. 149 150The OpenSSL default provider uses simpler checks that allows there to be no I<q> 151value for backwards compatibility, however the L<EVP_PKEY_param_check(3)> will 152test the I<p> value for being a prime (and a safe prime if I<q> is missing) 153which can take significant time. The L<EVP_PKEY_param_check_quick(3)> avoids 154the prime tests. 155 156L<EVP_PKEY_public_check(3)> conforms to SP800-56Ar3 157I<FFC Full Public-Key Validation>. 158 159L<EVP_PKEY_public_check_quick(3)> conforms to SP800-56Ar3 160I<FFC Partial Public-Key Validation> when the key is an approved named safe 161prime group, otherwise it is the same as L<EVP_PKEY_public_check(3)>. 162 163L<EVP_PKEY_private_check(3)> tests that the private key is in the correct range 164according to SP800-56Ar3. The OpenSSL FIPS provider requires the value of I<q> 165to be set (note that this is implicitly set for named safe prime groups). 166For backwards compatibility the OpenSSL default provider only requires I<p> to 167be set. 168 169L<EVP_PKEY_pairwise_check(3)> conforms to SP800-56Ar3 170I<Owner Assurance of Pair-wise Consistency>. 171 172=head1 EXAMPLES 173 174An B<EVP_PKEY> context can be obtained by calling: 175 176 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); 177 178A B<DH> key can be generated with a named safe prime group by calling: 179 180 int priv_len = 2 * 112; 181 OSSL_PARAM params[3]; 182 EVP_PKEY *pkey = NULL; 183 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); 184 185 params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0); 186 /* "priv_len" is optional */ 187 params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len); 188 params[2] = OSSL_PARAM_construct_end(); 189 190 EVP_PKEY_keygen_init(pctx); 191 EVP_PKEY_CTX_set_params(pctx, params); 192 EVP_PKEY_generate(pctx, &pkey); 193 ... 194 EVP_PKEY_free(pkey); 195 EVP_PKEY_CTX_free(pctx); 196 197B<DHX> domain parameters can be generated according to B<FIPS186-4> by calling: 198 199 int gindex = 2; 200 unsigned int pbits = 2048; 201 unsigned int qbits = 256; 202 OSSL_PARAM params[6]; 203 EVP_PKEY *param_key = NULL; 204 EVP_PKEY_CTX *pctx = NULL; 205 206 pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL); 207 EVP_PKEY_paramgen_init(pctx); 208 209 params[0] = OSSL_PARAM_construct_uint("pbits", &pbits); 210 params[1] = OSSL_PARAM_construct_uint("qbits", &qbits); 211 params[2] = OSSL_PARAM_construct_int("gindex", &gindex); 212 params[3] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0); 213 params[4] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0); 214 params[5] = OSSL_PARAM_construct_end(); 215 EVP_PKEY_CTX_set_params(pctx, params); 216 217 EVP_PKEY_generate(pctx, ¶m_key); 218 219 EVP_PKEY_print_params(bio_out, param_key, 0, NULL); 220 ... 221 EVP_PKEY_free(param_key); 222 EVP_PKEY_CTX_free(pctx); 223 224A B<DH> key can be generated using domain parameters by calling: 225 226 EVP_PKEY *key = NULL; 227 EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL); 228 229 EVP_PKEY_keygen_init(gctx); 230 EVP_PKEY_generate(gctx, &key); 231 EVP_PKEY_print_private(bio_out, key, 0, NULL); 232 ... 233 EVP_PKEY_free(key); 234 EVP_PKEY_CTX_free(gctx); 235 236To validate B<FIPS186-4> B<DHX> domain parameters decoded from B<PEM> or 237B<DER> data, additional values used during generation may be required to 238be set into the key. 239 240EVP_PKEY_todata(), OSSL_PARAM_merge(), and EVP_PKEY_fromdata() are useful 241to add these parameters to the original key or domain parameters before 242the actual validation. In production code the return values should be checked. 243 244 EVP_PKEY *received_domp = ...; /* parameters received and decoded */ 245 unsigned char *seed = ...; /* and additional parameters received */ 246 size_t seedlen = ...; /* by other means, required */ 247 int gindex = ...; /* for the validation */ 248 int pcounter = ...; 249 int hindex = ...; 250 OSSL_PARAM extra_params[4]; 251 OSSL_PARAM *domain_params = NULL; 252 OSSL_PARAM *merged_params = NULL; 253 EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL; 254 EVP_PKEY *complete_domp = NULL; 255 256 EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS, 257 &domain_params); 258 extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen); 259 /* 260 * NOTE: For unverifiable g use "hindex" instead of "gindex" 261 * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex); 262 */ 263 extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex); 264 extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter); 265 extra_params[3] = OSSL_PARAM_construct_end(); 266 merged_params = OSSL_PARAM_merge(domain_params, extra_params); 267 268 ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL); 269 EVP_PKEY_fromdata_init(ctx); 270 EVP_PKEY_fromdata(ctx, &complete_domp, OSSL_KEYMGMT_SELECT_ALL, 271 merged_params); 272 273 validate_ctx = EVP_PKEY_CTX_new_from_pkey(NULL, complete_domp, NULL); 274 if (EVP_PKEY_param_check(validate_ctx) > 0) 275 /* validation_passed(); */ 276 else 277 /* validation_failed(); */ 278 279 OSSL_PARAM_free(domain_params); 280 OSSL_PARAM_free(merged_params); 281 EVP_PKEY_CTX_free(ctx); 282 EVP_PKEY_CTX_free(validate_ctx); 283 EVP_PKEY_free(complete_domp); 284 285=head1 CONFORMING TO 286 287=over 4 288 289=item RFC 7919 (TLS ffdhe named safe prime groups) 290 291=item RFC 3526 (IKE modp named safe prime groups) 292 293=item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224" 294 and "dh_2048_256"). 295 296=back 297 298The following sections of SP800-56Ar3: 299 300=over 4 301 302=item 5.5.1.1 FFC Domain Parameter Selection/Generation 303 304=item Appendix D: FFC Safe-prime Groups 305 306=back 307 308The following sections of FIPS186-4: 309 310=over 4 311 312=item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function. 313 314=item A.2.3 Generation of canonical generator g. 315 316=item A.2.1 Unverifiable Generation of the Generator g. 317 318=back 319 320=head1 SEE ALSO 321 322L<EVP_PKEY-FFC(7)>, 323L<EVP_KEYEXCH-DH(7)> 324L<EVP_PKEY(3)>, 325L<provider-keymgmt(7)>, 326L<EVP_KEYMGMT(3)>, 327L<OSSL_PROVIDER-default(7)>, 328L<OSSL_PROVIDER-FIPS(7)> 329 330=head1 COPYRIGHT 331 332Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved. 333 334Licensed under the Apache License 2.0 (the "License"). You may not use 335this file except in compliance with the License. You can obtain a copy 336in the file LICENSE in the source distribution or at 337L<https://www.openssl.org/source/license.html>. 338 339=cut 340
