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 FIPS186-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-2025 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 233
Indexes created Fri Oct 09 00:27:48 UTC 2026