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_GROUP_NAME>) <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 =item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <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
  62 =back
  63
  64 =head2 DH domain parameter / key generation parameters
  65
  66 In addition to the common FFC 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.
 108 The default value used if this is not set is the maximum value of
 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 A 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 B<DHX> domain parameters can be generated according to B<FIPS 186-4> by calling:
 141
 142     unsigned int pbits = 2048;
 143     unsigned int qbits = 256;
 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, "DHX", NULL);
 149     EVP_PKEY_paramgen_init(pctx);
 150
 151     params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
 152     params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
 153     params[2] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0);
 154     params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0);
 155     params[4] = OSSL_PARAM_construct_end();
 156     EVP_PKEY_CTX_set_params(pctx, params);
 157
 158     EVP_PKEY_gen(pctx, &param_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 A 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 To validate B<FIPS 186-4> B<DHX> domain parameters decoded from B<PEM> or
 178 B<DER> data, additional values used during generation may be required to
 179 be set into the key.
 180
 181 EVP_PKEY_todata(), OSSL_PARAM_merge(), and EVP_PKEY_fromdata() are useful
 182 to add these parameters to the original key or domain parameters before
 183 the actual validation.
 184
 185     EVP_PKEY *received_domp = ...; /* parameters received and decoded */
 186     unsigned char *seed = ...;     /* and additional parameters received */
 187     size_t seedlen = ...;          /* by other means, required */
 188     int gindex = ...;              /* for the validation */
 189     int pcounter = ...;
 190     int hindex = ...;
 191     OSSL_PARAM extra_params[5];
 192     OSSL_PARAM *domain_params = NULL;
 193     OSSL_PARAM *merged_params = NULL;
 194     EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL;
 195     EVP_PKEY *complete_domp = NULL;
 196
 197     EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS,
 198                     &domain_params);
 199     extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen);
 200     extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex);
 201     extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter);
 202     extra_params[3] = OSSL_PARAM_construct_int("hindex", &hindex);
 203     extra_params[4] = OSSL_PARAM_construct_end();
 204     merged_params = OSSL_PARAM_merge(domain_params, extra_params);
 205
 206     ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
 207     EVP_PKEY_fromdata_init(ctx);
 208     EVP_PKEY_fromdata(ctx, &complete_domp, OSSL_KEYMGMT_SELECT_ALL,
 209                       merged_params);
 210
 211     validate_ctx = EVP_PKEY_CTX_new_from_pkey(NULL, complete_domp, NULL);
 212     if (EVP_PKEY_param_check(validate_ctx) > 0)
 213         /* validation_passed(); */
 214     else
 215         /* validation_failed(); */
 216
 217     OSSL_PARAM_free(domain_params);
 218     OSSL_PARAM_free(merged_params);
 219     EVP_PKEY_CTX_free(ctx);
 220     EVP_PKEY_CTX_free(validate_ctx);
 221     EVP_PKEY_free(complete_domp);
 222
 223 =head1 CONFORMING TO
 224
 225 =over 4
 226
 227 =item RFC 7919 (TLS ffdhe named safe prime groups)
 228
 229 =item RFC 3526 (IKE modp named safe prime groups)
 230
 231 =item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224"
 232           and "dh_2048_256").
 233
 234 =back
 235
 236 The following sections of SP800-56Ar3:
 237
 238 =over 4
 239
 240 =item 5.5.1.1 FFC Domain Parameter Selection/Generation
 241
 242 =item Appendix D: FFC Safe-prime Groups
 243
 244 =back
 245
 246 The following sections of FIPS 186-4:
 247
 248 =over 4
 249
 250 =item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
 251
 252 =item A.2.3 Generation of canonical generator g.
 253
 254 =item A.2.1 Unverifiable Generation of the Generator g.
 255
 256 =back
 257
 258 =head1 SEE ALSO
 259
 260 L<EVP_PKEY-FFC(7)>,
 261 L<EVP_KEYEXCH-DH(7)>
 262 L<EVP_PKEY(3)>,
 263 L<provider-keymgmt(7)>,
 264 L<EVP_KEYMGMT(3)>,
 265 L<OSSL_PROVIDER-default(7)>,
 266 L<OSSL_PROVIDER-FIPS(7)>
 267
 268 =head1 COPYRIGHT
 269
 270 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
 271
 272 Licensed under the Apache License 2.0 (the "License").  You may not use
 273 this file except in compliance with the License.  You can obtain a copy
 274 in the file LICENSE in the source distribution or at
 275 L<https://www.openssl.org/source/license.html>.
 276
 277 =cut