]>
Commit | Line | Data |
---|---|---|
b8086652 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
f1ffaaee | 5 | EVP_PKEY-FFC - EVP_PKEY DSA and DH/DHX shared FFC parameters. |
b8086652 SL |
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 | ||
f1ffaaee SL |
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 | |
b8086652 SL |
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 | ||
f1ffaaee SL |
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 | ||
b8086652 SL |
33 | =head2 FFC parameters |
34 | ||
35 | In addition to the common parameters that all keytypes should support (see | |
f1ffaaee | 36 | L<provider-keymgmt(7)/Common parameters>), the B<DSA>, B<DH> and B<DHX> keytype |
b8086652 SL |
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 | ||
f1ffaaee | 49 | =back |
b8086652 | 50 | |
f1ffaaee | 51 | =head2 FFC DSA, DH and DHX domain parameters |
b8086652 | 52 | |
f1ffaaee | 53 | =over 4 |
b8086652 | 54 | |
f1ffaaee SL |
55 | =item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer> |
56 | ||
57 | A DSA or Diffie-Hellman prime "p" value. | |
b8086652 SL |
58 | |
59 | =item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer> | |
60 | ||
61 | A DSA or Diffie-Hellman generator "g" value. | |
62 | ||
f1ffaaee SL |
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 | ||
b8086652 SL |
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 | ||
57cd10dd | 95 | For unverifiable generation of the generator I<g> this value is output during |
b8086652 SL |
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 | ||
b98f752e SL |
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 | ||
b8086652 SL |
120 | =back |
121 | ||
122 | =head2 FFC key generation parameters | |
123 | ||
f1ffaaee | 124 | The following key generation types are available for DSA and DHX algorithms: |
b8086652 SL |
125 | |
126 | =over 4 | |
127 | ||
c9f18e59 | 128 | =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <UTF8 string> |
b8086652 SL |
129 | |
130 | Sets the type of parameter generation. The shared valid values are: | |
131 | ||
132 | =over 4 | |
133 | ||
134 | =item "fips186_4" | |
135 | ||
3a37ddde | 136 | The current standard. |
b8086652 SL |
137 | |
138 | =item "fips186_2" | |
139 | ||
140 | The old standard that should only be used for legacy purposes. | |
141 | ||
142 | =item "default" | |
143 | ||
3a37ddde SL |
144 | This can choose one of "fips186_4" or "fips186_2" depending on other |
145 | parameters set for parameter generation. | |
b8086652 SL |
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 | ||
c9f18e59 | 160 | =item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <UTF8 string> |
b8086652 SL |
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 | ||
c9f18e59 | 166 | =item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <UTF8 string> |
b8086652 SL |
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 | ||
0b3d2594 | 199 | The following sections of FIPS186-4: |
b8086652 SL |
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 | ||
3c2bdd7d | 225 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. |
b8086652 SL |
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 |