5 EVP_PKEY-FFC - EVP_PKEY DSA and DH 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> and B<DH> keytypes are implemented in OpenSSL's default and FIPS
16 The implementations support the basic DSA and DH 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.
31 In addition to the common parameters that all keytypes should support (see
32 L<provider-keymgmt(7)/Common parameters>), the B<DSA> and B<DH> keytype
33 implementations support the following.
37 =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
41 =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
43 The private key value.
45 =item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
47 A DSA or Diffie-Hellman prime "p" value.
49 =item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
51 A DSA or Diffie-Hellman prime "q" value.
53 =item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
55 A DSA or Diffie-Hellman generator "g" value.
57 =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
59 An optional domain parameter I<seed> value used during generation and validation
60 of I<p>, I<q> and canonical I<g>.
61 For validation this needs to set the I<seed> that was produced during generation.
63 =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
65 Sets the index to use for canonical generation and verification of the generator
67 Set this to a positive value from 0..FF to use this mode. This I<gindex> can
68 then be reused during key validation to verify the value of I<g>. If this value
69 is not set or is -1 then unverifiable generation of the generator I<g> will be
72 =item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
74 An optional domain parameter I<counter> value that is output during generation
75 of I<p>. This value must be saved if domain parameter validation is required.
77 =item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
79 For unverifiable generation of the generator I<g> this value is output during
80 generation of I<g>. Its value is the first integer larger than one that
81 satisfies g = h^j mod p (where g != 1 and "j" is the cofactor).
83 =item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
85 An optional informational cofactor parameter that should equal to (p - 1) / q.
89 =head2 FFC key generation parameters
91 The following key generation types are available for DSA and DH algorithms:
95 =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
97 Sets the type of parameter generation. The shared valid values are:
103 The current standard.
107 The old standard that should only be used for legacy purposes.
111 This can choose one of "fips186_4" or "fips186_2" depending on other
112 parameters set for parameter generation.
116 =item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
118 Sets the size (in bits) of the prime 'p'.
120 =item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
122 Sets the size (in bits) of the prime 'q'.
124 For "fips186_4" this can be either 224 or 256.
125 For "fips186_2" this has a size of 160.
127 =item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <utf8_string>
129 Sets the Digest algorithm to be used as part of the Key Generation Function
130 associated with the given Key Generation I<ctx>.
131 This must also be set for key validation.
133 =item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string>
135 Sets properties to be used upon look up of the implementation for the selected
136 Digest algorithm for the Key Generation Function associated with the given key
137 generation I<ctx>. This may also be set for key validation.
139 =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
141 For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use
142 instead of generating a random seed internally. This should be used for
143 testing purposes only. This will either produce fixed values for the generated
144 parameters OR it will fail if the seed did not generate valid primes.
146 =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
148 =item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
150 =item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
152 These types are described above.
158 The following sections of SP800-56Ar3:
162 =item 5.5.1.1 FFC Domain Parameter Selection/Generation
166 The following sections of FIPS 186-4:
170 =item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
172 =item A.2.3 Generation of canonical generator g.
174 =item A.2.1 Unverifiable Generation of the Generator g.
182 L<EVP_SIGNATURE-DSA(7)>,
186 L<provider-keymgmt(7)>,
187 L<OSSL_PROVIDER-default(7)>,
188 L<OSSL_PROVIDER-FIPS(7)>,
192 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
194 Licensed under the Apache License 2.0 (the "License"). You may not use
195 this file except in compliance with the License. You can obtain a copy
196 in the file LICENSE in the source distribution or at
197 L<https://www.openssl.org/source/license.html>.