1EVP_PKEY-FFC(7ossl) OpenSSL EVP_PKEY-FFC(7ossl)
2
6 EVP_PKEY-FFC - EVP_PKEY DSA and DH/DHX shared FFC parameters.
7
9 Finite field cryptography (FFC) is a method of implementing discrete
10 logarithm cryptography using finite field mathematics. DSA is an
11 example of FFC and Diffie-Hellman key establishment algorithms
12 specified in SP800-56A can also be implemented as FFC.
13 The DSA, DH and DHX keytypes are implemented in OpenSSL's default and
15 FIPS providers. The implementations support the basic DSA, DH and DHX
16 keys, containing the public and private keys pub and priv as well as
17 the three main domain parameters p, q and g.
18 For DSA (and DH that is not a named group) the FIPS186-4 standard
20 specifies that the values used for FFC parameter generation are also
21 required for parameter validation. This means that optional FFC domain
22 parameter values for seed, pcounter and gindex may need to be stored
23 for validation purposes. For DH the seed and pcounter can be stored in
24 ASN1 data (but the gindex is not). For DSA however, these fields are
25 not stored in the ASN1 data so they need to be stored externally if
26 validation is required.
27 The DH key type uses PKCS#3 format which saves p and g, but not the 'q'
29 value. The DHX key type uses X9.42 format which saves the value of 'q'
30 and this must be used for FIPS186-4.
31 FFC parameters
33 In addition to the common parameters that all keytypes should support
34 (see "Common parameters" in provider-keymgmt(7)), the DSA, DH and DHX
35 keytype implementations support the following.
36 "pub" (OSSL_PKEY_PARAM_PUB_KEY) <unsigned integer>
38 The public key value.
39 "priv" (OSSL_PKEY_PARAM_PRIV_KEY) <unsigned integer>
41 The private key value.
42 FFC DSA, DH and DHX domain parameters
44 "p" (OSSL_PKEY_PARAM_FFC_P) <unsigned integer>
45 A DSA or Diffie-Hellman prime "p" value.
46 "g" (OSSL_PKEY_PARAM_FFC_G) <unsigned integer>
48 A DSA or Diffie-Hellman generator "g" value.
49 FFC DSA and DHX domain parameters
51 "q" (OSSL_PKEY_PARAM_FFC_Q) <unsigned integer>
52 A DSA or Diffie-Hellman prime "q" value.
53 "seed" (OSSL_PKEY_PARAM_FFC_SEED) <octet string>
55 An optional domain parameter seed value used during generation and
56 validation of p, q and canonical g. For validation this needs to
57 set the seed that was produced during generation.
58 "gindex" (OSSL_PKEY_PARAM_FFC_GINDEX) <integer>
60 Sets the index to use for canonical generation and verification of
61 the generator g. Set this to a positive value from 0..FF to use
62 this mode. This gindex can then be reused during key validation to
63 verify the value of g. If this value is not set or is -1 then
64 unverifiable generation of the generator g will be used.
65 "pcounter" (OSSL_PKEY_PARAM_FFC_PCOUNTER) <integer>
67 An optional domain parameter counter value that is output during
68 generation of p. This value must be saved if domain parameter
69 validation is required.
70 "hindex" (OSSL_PKEY_PARAM_FFC_H) <integer>
72 For unverifiable generation of the generator g this value is output
73 during generation of g. Its value is the first integer larger than
74 one that satisfies g = h^j mod p (where g != 1 and "j" is the
75 cofactor).
76 "j" (OSSL_PKEY_PARAM_FFC_COFACTOR) <unsigned integer>
78 An optional informational cofactor parameter that should equal to
79 (p - 1) / q.
80 "validate-pq" (OSSL_PKEY_PARAM_FFC_VALIDATE_PQ) <unsigned integer>
82 "validate-g" (OSSL_PKEY_PARAM_FFC_VALIDATE_G) <unsigned integer>
83 These boolean values are used during FIPS186-4 or FIPS186-2 key
84 validation checks (See EVP_PKEY_param_check(3)) to select
85 validation options. By default validate-pq and validate-g are both
86 set to 1 to check that p,q and g are valid. Either of these may be
87 set to 0 to skip a test, which is mainly useful for testing
88 purposes.
89 "validate-legacy" (OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY) <unsigned
91 integer>
92 This boolean value is used during key validation checks (See
93 EVP_PKEY_param_check(3)) to select the validation type. The default
94 value of 0 selects FIPS186-4 validation. Setting this value to 1
95 selects FIPS186-2 validation.
96 FFC key generation parameters
98 The following key generation types are available for DSA and DHX
99 algorithms:
100 "type" (OSSL_PKEY_PARAM_FFC_TYPE) <UTF8 string>
102 Sets the type of parameter generation. The shared valid values are:
103 "fips186_4"
105 The current standard.
106 "fips186_2"
108 The old standard that should only be used for legacy purposes.
109 "default"
111 This can choose one of "fips186_4" or "fips186_2" depending on
112 other parameters set for parameter generation.
113 "pbits" (OSSL_PKEY_PARAM_FFC_PBITS) <unsigned integer>
115 Sets the size (in bits) of the prime 'p'.
116 "qbits" (OSSL_PKEY_PARAM_FFC_QBITS) <unsigned integer>
118 Sets the size (in bits) of the prime 'q'.
119 For "fips186_4" this can be either 224 or 256. For "fips186_2"
121 this has a size of 160.
122 "digest" (OSSL_PKEY_PARAM_FFC_DIGEST) <UTF8 string>
124 Sets the Digest algorithm to be used as part of the Key Generation
125 Function associated with the given Key Generation ctx. This must
126 also be set for key validation.
127 "properties" (OSSL_PKEY_PARAM_FFC_DIGEST_PROPS) <UTF8 string>
129 Sets properties to be used upon look up of the implementation for
130 the selected Digest algorithm for the Key Generation Function
131 associated with the given key generation ctx. This may also be set
132 for key validation.
133 "seed" (OSSL_PKEY_PARAM_FFC_SEED) <octet string>
135 For "fips186_4" or "fips186_2" generation this sets the seed data
136 to use instead of generating a random seed internally. This should
137 be used for testing purposes only. This will either produce fixed
138 values for the generated parameters OR it will fail if the seed did
139 not generate valid primes.
140 "gindex" (OSSL_PKEY_PARAM_FFC_GINDEX) <integer>
142 "pcounter" (OSSL_PKEY_PARAM_FFC_PCOUNTER) <integer>
143 "hindex" (OSSL_PKEY_PARAM_FFC_H) <integer>
144 These types are described above.
145
147 The following sections of SP800-56Ar3:
148 5.5.1.1 FFC Domain Parameter Selection/Generation
150 The following sections of FIPS186-4:
152 A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash
154 Function.
155 A.2.3 Generation of canonical generator g.
156 A.2.1 Unverifiable Generation of the Generator g.
157
159 EVP_PKEY-DSA(7), EVP_PKEY-DH(7), EVP_SIGNATURE-DSA(7),
160 EVP_KEYEXCH-DH(7) EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7),
161 OSSL_PROVIDER-default(7), OSSL_PROVIDER-FIPS(7),
162
164 Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
165 Licensed under the Apache License 2.0 (the "License"). You may not use
167 this file except in compliance with the License. You can obtain a copy
168 in the file LICENSE in the source distribution or at
169 <https://www.openssl.org/source/license.html>.
1703.0.5 2022-11-01 EVP_PKEY-FFC(7ossl)