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 =back
 104
 105 =head2 FFC key generation parameters
 106
 107 The following key generation types are available for DSA and DHX algorithms:
 108
 109 =over 4
 110
 111 =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
 112
 113 Sets the type of parameter generation. The shared valid values are:
 114
 115 =over 4
 116
 117 =item "fips186_4"
 118
 119 The current standard.
 120
 121 =item "fips186_2"
 122
 123 The old standard that should only be used for legacy purposes.
 124
 125 =item "default"
 126
 127 This can choose one of "fips186_4" or "fips186_2" depending on other
 128 parameters set for parameter generation.
 129
 130 =back
 131
 132 =item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
 133
 134 Sets the size (in bits) of the prime 'p'.
 135
 136 =item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
 137
 138 Sets the size (in bits) of the prime 'q'.
 139
 140 For "fips186_4" this can be either 224 or 256.
 141 For "fips186_2" this has a size of 160.
 142
 143 =item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>)  <utf8_string>
 144
 145 Sets the Digest algorithm to be used as part of the Key Generation Function
 146 associated with the given Key Generation I<ctx>.
 147 This must also be set for key validation.
 148
 149 =item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string>
 150
 151 Sets properties to be used upon look up of the implementation for the selected
 152 Digest algorithm for the Key Generation Function associated with the given key
 153 generation I<ctx>. This may also be set for key validation.
 154
 155 =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
 156
 157 For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use
 158 instead of generating a random seed internally. This should be used for
 159 testing purposes only. This will either produce fixed values for the generated
 160 parameters OR it will fail if the seed did not generate valid primes.
 161
 162 =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
 163
 164 =item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
 165
 166 =item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
 167
 168 These types are described above.
 169
 170 =back
 171
 172 =head1 CONFORMING TO
 173
 174 The following sections of SP800-56Ar3:
 175
 176 =over 4
 177
 178 =item 5.5.1.1 FFC Domain Parameter Selection/Generation
 179
 180 =back
 181
 182 The following sections of FIPS 186-4:
 183
 184 =over 4
 185
 186 =item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
 187
 188 =item A.2.3 Generation of canonical generator g.
 189
 190 =item A.2.1 Unverifiable Generation of the Generator g.
 191
 192 =back
 193
 194 =head1 SEE ALSO
 195
 196 L<EVP_PKEY-DSA(7)>,
 197 L<EVP_PKEY-DH(7)>,
 198 L<EVP_SIGNATURE-DSA(7)>,
 199 L<EVP_KEYEXCH-DH(7)>
 200 L<EVP_KEYMGMT(3)>,
 201 L<EVP_PKEY(3)>,
 202 L<provider-keymgmt(7)>,
 203 L<OSSL_PROVIDER-default(7)>,
 204 L<OSSL_PROVIDER-FIPS(7)>,
 205
 206 =head1 COPYRIGHT
 207
 208 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
 209
 210 Licensed under the Apache License 2.0 (the "License").  You may not use
 211 this file except in compliance with the License.  You can obtain a copy
 212 in the file LICENSE in the source distribution or at
 213 L<https://www.openssl.org/source/license.html>.
 214
 215 =cut