From 9e537cd2ad01b172f2700a670e9269075078a426 Mon Sep 17 00:00:00 2001 From: Shane Lontis Date: Thu, 16 Apr 2020 12:07:26 +1000 Subject: DOC: Extend EVP_PKEY-DSA(7) / EVP_PKEY_DH(7) with FFC information Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/11546) --- doc/man7/EVP_PKEY-DSA.pod | 213 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 207 insertions(+), 6 deletions(-) (limited to 'doc/man7') diff --git a/doc/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod index 307a46e019..ccb34a9f93 100644 --- a/doc/man7/EVP_PKEY-DSA.pod +++ b/doc/man7/EVP_PKEY-DSA.pod @@ -10,10 +10,61 @@ EVP_PKEY-DSA, EVP_KEYMGMT-DSA, EVP_PKEY-DH, EVP_KEYMGMT-DH The B and B keytypes are implemented in OpenSSL's default and FIPS providers. The implementations support the basic DSA and DH keys, containing the public -and private keys I and I as well as the three domain parameters +and private keys I and I as well as the three main domain parameters I

, I and I. -=head2 Common DSA / DH parameters +Finite field cryptography (FFC) is a method of implementing discrete logarithm +cryptography using finite field mathematics. DSA is an example of FFC and +Diffie-Hellman key establishment algorithms specified in SP800-56A can also be +implemented as FFC. + +For B FFC key agreement, two classes of domain parameters can be used: +"safe" domain parameters that are associated with approved named safe-prime +groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain +parameters should only be used for backward compatibility with existing +applications that cannot be upgraded to use the approved safe-prime groups. + +For B (and B that is not a named group) the FIPS186-4 standard +specifies that the values used for FFC parameter generation are also required +for parameter validation. +This means that optional FFC domain parameter values for I, I +and I may need to be stored for validation purposes. +For B the I and I can be stored in ASN1 data +(but the I is not). For B however, these fields are not stored in +the ASN1 data so they need to be stored externally if validation is required. + +=head2 Common DH parameters + +=over 4 + +=item "group" (B) + +A string that associates a B named safe prime group with known values for +I

, I and I. + +The following values can be used by the default and OpenSSL's FIPS providers: +"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192", +"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192". + +The following additional values can also be used by the default provider: +"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256". + +DH named groups can be easily validated since the parameters are well known. +For protocols that only transfer I

and I the value of I can also be +retrieved. + +=item "safeprime-generator" (B) + +Used for DH generation of safe primes using the old generator code. +It is recommended to use a named safe prime group instead, if domain parameter +validation is required. The default value is 2. + +These are not named safe prime groups so setting this value for the OpenSSL FIPS +provider will instead choose a named safe prime group based on the size of I

. + +=back + +=head2 Common DSA & DH parameters In addition to the common parameters that all keytypes should support (see L), the B and B keytype @@ -31,21 +82,171 @@ The private key value. =item "p" (B) -A DSA or Diffie-Hellman "p" value. +A DSA or Diffie-Hellman prime "p" value. =item "q" (B) -A DSA or Diffie-Hellman "q" value. +A DSA or Diffie-Hellman prime "q" value. =item "g" (B) -A DSA or Diffie-Hellman "g" value. +A DSA or Diffie-Hellman generator "g" value. + +=item "seed" (B) + +An optional domain parameter I value used during generation and validation +of I

, I and canonical I. +For validation this needs to set the I that was produced during generation. + +=item "gindex" (B) + +Sets the index to use for canonical generation and verification of the generator +I. +Set this to a positive value from 0..FF to use this mode. This I can +then be reused during key validation to verify the value of I. If this value +is not set or is -1 then unverifiable generation of the generator I will be +used. + +=item "pcounter" (B) + +An optional domain parameter I value that is output during generation +of I

. This value must be saved if domain parameter validation is required. + +=item "hindex" (B) + +For unverifiable generation of the generator I this value is output during +generation of I. Its value is the first integer larger than one that +satisfies g = h^j mod p (where g != 1 and "j" is the cofactor). + +=item "j" (B) + +An optional informational cofactor parameter that should equal (p - 1) / q. =back + +=head2 DSA / DH key generation (FFC) parameters + +The following Key Generation types are available for the built-in FFC algorithms: + +=over 4 + +=item "type" (B) + +Sets the type of parameter generation. For DH Valid values are: + +=over 4 + +=item "fips186_4" + +The current standard. This is the default value. + +=item "default" + +This is an alias to use the latest implemented standard. +It is currently set to "fips186_4". + +=item "group" + +This specifies that a named safe prime name will be chosen using the "pbits" +type. + +=item "fips186_2" + +The old standard that should only be used for legacy purposes. + +=item "generator" + +A safe prime generator. See the "safeprime-generator" type. + +=back + +For DSA valid values are one of "default", "fips186_4" or "fips186_2" as +described above. + +=item "pbits" (B) + +Sets the size (in bits) of the prime 'p'. + +For "fips186_4" this must be 2048 for DH, and either of 2048 or 3072 for DSA. +For "fips186_2" this must be 1024. +For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192. + +=item "qbits" (B) + +Sets the size (in bits) of the prime 'q'. + +For "fips186_4" this can be either 224 or 256. +For "fips186_2" this has a size of 160. + +=item "digest" (B) + +Sets the Digest algorithm to be used as part of the Key Generation Function +associated with the given Key Generation I. +This must also be set for key validation. + +=item "properties" (B) + +Sets properties to be used upon look up of the implementation for the selected +Digest algorithm for the Key Generation Function associated with the given key +generation I. This may also be set for key validation. + +=item "seed" (B) + +For "fips186_4" or "fips186_2" generation this sets the I data to use +instead of generating a random seed internally. This should be used for +testing purposes only. This will either produce fixed values for the generated +parameters OR it will fail if the seed did not generate valid primes. + +=item "group" (B) + +=item "safeprime-generator" (B) + +=item "gindex" (B) + +=item "pcounter" (B) + +=item "hindex" (B) + +These types are described above. + +=back + + =head1 CONFORMING TO -[TBA] +=over 4 + +=item RFC 7919 (TLS ffdhe named safe prime groups) + +=item RFC 3526 (IKE modp named safe prime groups) + +=item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224" + and "dh_2048_256"). + +=back + +The following sections of SP800-56Ar3: + +=over 4 + +=item 5.5.1.1 FFC Domain Parameter Selection/Generation + +=item Appendix D: FFC Safe-prime Groups + +=back + +The following sections of FIPS 186-4: + +=over 4 + +=item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function. + +=item A.2.3 Generation of canonical generator g. + +=item A.2.1 Unverifiable Generation of the Generator g. + +=back =head1 SEE ALSO -- cgit v1.2.3