1=pod 2 3=head1 NAME 4 5EVP_PKEY-FFC - EVP_PKEY DSA and DH/DHX shared FFC parameters. 6 7=head1 DESCRIPTION 8 9Finite field cryptography (FFC) is a method of implementing discrete logarithm 10cryptography using finite field mathematics. DSA is an example of FFC and 11Diffie-Hellman key establishment algorithms specified in SP800-56A can also be 12implemented as FFC. 13 14The B<DSA>, B<DH> and B<DHX> keytypes are implemented in OpenSSL's default and 15FIPS providers. 16The implementations support the basic DSA, DH and DHX keys, containing the public 17and private keys I<pub> and I<priv> as well as the three main domain parameters 18I<p>, I<q> and I<g>. 19 20For B<DSA> (and B<DH> that is not a named group) the FIPS186-4 standard 21specifies that the values used for FFC parameter generation are also required 22for parameter validation. 23This means that optional FFC domain parameter values for I<seed>, I<pcounter> 24and I<gindex> may need to be stored for validation purposes. 25For 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 27the ASN1 data so they need to be stored externally if validation is required. 28 29The B<DH> key type uses PKCS#3 format which saves p and g, but not the 'q' value. 30The B<DHX> key type uses X9.42 format which saves the value of 'q' and this 31must be used for FIPS186-4. 32 33=head2 FFC parameters 34 35In addition to the common parameters that all keytypes should support (see 36L<provider-keymgmt(7)/Common parameters>), the B<DSA>, B<DH> and B<DHX> keytype 37implementations support the following. 38 39=over 4 40 41=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer> 42 43The public key value. 44 45=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer> 46 47The 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 57A DSA or Diffie-Hellman prime "p" value. 58 59=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer> 60 61A 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 71A DSA or Diffie-Hellman prime "q" value. 72 73=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string> 74 75An optional domain parameter I<seed> value used during generation and validation 76of I<p>, I<q> and canonical I<g>. 77For 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 81Sets the index to use for canonical generation and verification of the generator 82I<g>. 83Set this to a positive value from 0..FF to use this mode. This I<gindex> can 84then be reused during key validation to verify the value of I<g>. If this value 85is not set or is -1 then unverifiable generation of the generator I<g> will be 86used. 87 88=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer> 89 90An optional domain parameter I<counter> value that is output during generation 91of 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 95For unverifiable generation of the generator I<g> this value is output during 96generation of I<g>. Its value is the first integer larger than one that 97satisfies 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 101An 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 107These 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 109I<validate-pq> and I<validate-g> are both set to 1 to check that p,q and g are 110valid. Either of these may be set to 0 to skip a test, which is mainly useful 111for testing purposes. 112 113=item "validate-legacy" (B<OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY>) <unsigned integer> 114 115This boolean value is used during key validation checks 116(See L<EVP_PKEY_param_check(3)>) to select the validation type. The default 117value of 0 selects FIPS186-4 validation. Setting this value to 1 selects 118FIPS186-2 validation. 119 120=back 121 122=head2 FFC key generation parameters 123 124The 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 130Sets the type of parameter generation. The shared valid values are: 131 132=over 4 133 134=item "fips186_4" 135 136The current standard. 137 138=item "fips186_2" 139 140The old standard that should only be used for legacy purposes. 141 142=item "default" 143 144This can choose one of "fips186_4" or "fips186_2" depending on other 145parameters set for parameter generation. 146 147=back 148 149=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer> 150 151Sets the size (in bits) of the prime 'p'. 152 153=item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer> 154 155Sets the size (in bits) of the prime 'q'. 156 157For "fips186_4" this can be either 224 or 256. 158For "fips186_2" this has a size of 160. 159 160=item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <UTF8 string> 161 162Sets the Digest algorithm to be used as part of the Key Generation Function 163associated with the given Key Generation I<ctx>. 164This must also be set for key validation. 165 166=item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <UTF8 string> 167 168Sets properties to be used upon look up of the implementation for the selected 169Digest algorithm for the Key Generation Function associated with the given key 170generation I<ctx>. This may also be set for key validation. 171 172=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string> 173 174For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use 175instead of generating a random seed internally. This should be used for 176testing purposes only. This will either produce fixed values for the generated 177parameters 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 185These types are described above. 186 187=back 188 189=head1 CONFORMING TO 190 191The 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 199The 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 213L<EVP_PKEY-DSA(7)>, 214L<EVP_PKEY-DH(7)>, 215L<EVP_SIGNATURE-DSA(7)>, 216L<EVP_KEYEXCH-DH(7)> 217L<EVP_KEYMGMT(3)>, 218L<EVP_PKEY(3)>, 219L<provider-keymgmt(7)>, 220L<OSSL_PROVIDER-default(7)>, 221L<OSSL_PROVIDER-FIPS(7)>, 222 223=head1 COPYRIGHT 224 225Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved. 226 227Licensed under the Apache License 2.0 (the "License"). You may not use 228this file except in compliance with the License. You can obtain a copy 229in the file LICENSE in the source distribution or at 230L<https://www.openssl.org/source/license.html>. 231 232=cut 233