xref: /freebsd/crypto/openssl/doc/man7/EVP_PKEY-FFC.pod (revision f81cdf24ba5436367377f7c8e8f51f6df2a75ca7) 
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