5 EVP_PKEY-FFC - EVP_PKEY DSA and DH/DHX shared FFC parameters.
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
14 The B<DSA>, B<DH> and B<DHX> keytypes are implemented in OpenSSL's default and
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
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.
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.
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.
41 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
45 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
47 The private key value.
51 =head2 FFC DSA, DH and DHX domain parameters
55 =item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
57 A DSA or Diffie-Hellman prime "p" value.
59 =item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
61 A DSA or Diffie-Hellman generator "g" value.
65 =head2 FFC DSA and DHX domain parameters
69 =item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
71 A DSA or Diffie-Hellman prime "q" value.
73 =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
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.
79 =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
81 Sets the index to use for canonical generation and verification of the generator
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
88 =item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
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.
93 =item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
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).
99 =item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
101 An optional informational cofactor parameter that should equal to (p - 1) / q.
105 =head2 FFC key generation parameters
107 The following key generation types are available for DSA and DHX algorithms:
111 =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <UTF8 string>
113 Sets the type of parameter generation. The shared valid values are:
119 The current standard.
123 The old standard that should only be used for legacy purposes.
127 This can choose one of "fips186_4" or "fips186_2" depending on other
128 parameters set for parameter generation.
132 =item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
134 Sets the size (in bits) of the prime 'p'.
136 =item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
138 Sets the size (in bits) of the prime 'q'.
140 For "fips186_4" this can be either 224 or 256.
141 For "fips186_2" this has a size of 160.
143 =item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <UTF8 string>
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.
149 =item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <UTF8 string>
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.
155 =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
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.
162 =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
164 =item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
166 =item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
168 These types are described above.
174 The following sections of SP800-56Ar3:
178 =item 5.5.1.1 FFC Domain Parameter Selection/Generation
182 The following sections of FIPS 186-4:
186 =item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
188 =item A.2.3 Generation of canonical generator g.
190 =item A.2.1 Unverifiable Generation of the Generator g.
198 L<EVP_SIGNATURE-DSA(7)>,
202 L<provider-keymgmt(7)>,
203 L<OSSL_PROVIDER-default(7)>,
204 L<OSSL_PROVIDER-FIPS(7)>,
208 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
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>.