doc/man7/EVP_PKEY-FFC.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY-FFC - EVP_PKEY DSA and DH/DHX shared FFC parameters.
   6
   7 =head1 DESCRIPTION
   8
   9 Finite field cryptography (FFC) is a method of implementing discrete logarithm
  10 cryptography using finite field mathematics. DSA is an example of FFC and
  11 Diffie-Hellman key establishment algorithms specified in SP800-56A can also be
  12 implemented as FFC.
  13
  14 The B<DSA>, B<DH> and B<DHX> keytypes are implemented in OpenSSL's default and
  15 FIPS providers.
  16 The implementations support the basic DSA, DH and DHX keys, containing the public
  17 and private keys I<pub> and I<priv> as well as the three main domain parameters
  18 I<p>, I<q> and I<g>.
  19
  20 For B<DSA> (and B<DH> that is not a named group) the FIPS186-4 standard
  21 specifies that the values used for FFC parameter generation are also required
  22 for parameter validation.
  23 This means that optional FFC domain parameter values for I<seed>, I<pcounter>
  24 and I<gindex> may need to be stored for validation purposes.
  25 For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
  26 (but the I<gindex> is not). For B<DSA> however, these fields are not stored in
  27 the ASN1 data so they need to be stored externally if validation is required.
  28
  29 The B<DH> key type uses PKCS#3 format which saves p and g, but not the 'q' value.
  30 The B<DHX> key type uses X9.42 format which saves the value of 'q' and this
  31 must be used for FIPS186-4.
  32
  33 =head2 FFC parameters
  34
  35 In addition to the common parameters that all keytypes should support (see
  36 L<provider-keymgmt(7)/Common parameters>), the B<DSA>, B<DH> and B<DHX> keytype
  37 implementations support the following.
  38
  39 =over 4
  40
  41 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
  42
  43 The public key value.
  44
  45 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
  46
  47 The private key value.
  48
  49 =back
  50
  51 =head2 FFC DSA, DH and DHX domain parameters
  52
  53 =over 4
  54
  55 =item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
  56
  57 A DSA or Diffie-Hellman prime "p" value.
  58
  59 =item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
  60
  61 A DSA or Diffie-Hellman generator "g" value.
  62
  63 =back
  64
  65 =head2 FFC DSA and DHX domain parameters
  66
  67 =over 4
  68
  69 =item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
  70
  71 A DSA or Diffie-Hellman prime "q" value.
  72
  73 =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
  74
  75 An optional domain parameter I<seed> value used during generation and validation
  76 of I<p>, I<q> and canonical I<g>.
  77 For validation this needs to set the I<seed> that was produced during generation.
  78
  79 =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
  80
  81 Sets the index to use for canonical generation and verification of the generator
  82 I<g>.
  83 Set this to a positive value from 0..FF to use this mode. This I<gindex> can
  84 then be reused during key validation to verify the value of I<g>. If this value
  85 is not set or is -1 then unverifiable generation of the generator I<g> will be
  86 used.
  87
  88 =item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
  89
  90 An optional domain parameter I<counter> value that is output during generation
  91 of I<p>. This value must be saved if domain parameter validation is required.
  92
  93 =item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
  94
  95 For unverifiable generation of the generator I<g> this value is output during
  96 generation of I<g>. Its value is the first integer larger than one that
  97 satisfies g = h^j mod p (where g != 1 and "j" is the cofactor).
  98
  99 =item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
 100
 101 An optional informational cofactor parameter that should equal to (p - 1) / q.
 102
 103 =item "validate-pq" (B<OSSL_PKEY_PARAM_FFC_VALIDATE_PQ>) <unsigned integer>
 104
 105 =item "validate-g" (B<OSSL_PKEY_PARAM_FFC_VALIDATE_G>) <unsigned integer>
 106
 107 These boolean values are used during FIPS186-4 or FIPS186-2 key validation checks
 108 (See L<EVP_PKEY_param_check(3)>) to select validation options. By default
 109 I<validate-pq> and I<validate-g> are both set to 1 to check that p,q and g are
 110 valid. Either of these may be set to 0 to skip a test, which is mainly useful
 111 for testing purposes.
 112
 113 =item "validate-legacy" (B<OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY>) <unsigned integer>
 114
 115 This boolean value is used during key validation checks
 116 (See L<EVP_PKEY_param_check(3)>) to select the validation type. The default
 117 value of 0 selects FIPS186-4 validation. Setting this value to 1 selects
 118 FIPS186-2 validation.
 119
 120 =back
 121
 122 =head2 FFC key generation parameters
 123
 124 The following key generation types are available for DSA and DHX algorithms:
 125
 126 =over 4
 127
 128 =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <UTF8 string>
 129
 130 Sets the type of parameter generation. The shared valid values are:
 131
 132 =over 4
 133
 134 =item "fips186_4"
 135
 136 The current standard.
 137
 138 =item "fips186_2"
 139
 140 The old standard that should only be used for legacy purposes.
 141
 142 =item "default"
 143
 144 This can choose one of "fips186_4" or "fips186_2" depending on other
 145 parameters set for parameter generation.
 146
 147 =back
 148
 149 =item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
 150
 151 Sets the size (in bits) of the prime 'p'.
 152
 153 =item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
 154
 155 Sets the size (in bits) of the prime 'q'.
 156
 157 For "fips186_4" this can be either 224 or 256.
 158 For "fips186_2" this has a size of 160.
 159
 160 =item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>)  <UTF8 string>
 161
 162 Sets the Digest algorithm to be used as part of the Key Generation Function
 163 associated with the given Key Generation I<ctx>.
 164 This must also be set for key validation.
 165
 166 =item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <UTF8 string>
 167
 168 Sets properties to be used upon look up of the implementation for the selected
 169 Digest algorithm for the Key Generation Function associated with the given key
 170 generation I<ctx>. This may also be set for key validation.
 171
 172 =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
 173
 174 For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use
 175 instead of generating a random seed internally. This should be used for
 176 testing purposes only. This will either produce fixed values for the generated
 177 parameters OR it will fail if the seed did not generate valid primes.
 178
 179 =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
 180
 181 =item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
 182
 183 =item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
 184
 185 These types are described above.
 186
 187 =back
 188
 189 =head1 CONFORMING TO
 190
 191 The following sections of SP800-56Ar3:
 192
 193 =over 4
 194
 195 =item 5.5.1.1 FFC Domain Parameter Selection/Generation
 196
 197 =back
 198
 199 The following sections of FIPS 186-4:
 200
 201 =over 4
 202
 203 =item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
 204
 205 =item A.2.3 Generation of canonical generator g.
 206
 207 =item A.2.1 Unverifiable Generation of the Generator g.
 208
 209 =back
 210
 211 =head1 SEE ALSO
 212
 213 L<EVP_PKEY-DSA(7)>,
 214 L<EVP_PKEY-DH(7)>,
 215 L<EVP_SIGNATURE-DSA(7)>,
 216 L<EVP_KEYEXCH-DH(7)>
 217 L<EVP_KEYMGMT(3)>,
 218 L<EVP_PKEY(3)>,
 219 L<provider-keymgmt(7)>,
 220 L<OSSL_PROVIDER-default(7)>,
 221 L<OSSL_PROVIDER-FIPS(7)>,
 222
 223 =head1 COPYRIGHT
 224
 225 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
 226
 227 Licensed under the Apache License 2.0 (the "License").  You may not use
 228 this file except in compliance with the License.  You can obtain a copy
 229 in the file LICENSE in the source distribution or at
 230 L<https://www.openssl.org/source/license.html>.
 231
 232 =cut