=head1 NAME
-EVP_PKEY-DSA, EVP_KEYMGMT-DSA, EVP_PKEY-DH, EVP_KEYMGMT-DH
-- EVP_PKEY DSA and DH keytype and algorithm support
+EVP_PKEY-DSA, EVP_KEYMGMT-DSA - EVP_PKEY DSA keytype and algorithm support
=head1 DESCRIPTION
-The B<DSA> and B<DH> 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<pub> and I<priv> as well as the three main domain parameters
-I<p>, I<q> and I<g>.
-
-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<DH> 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<DSA> (and B<DH> 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.
+For B<DSA> 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<seed>, I<pcounter>
-and I<gindex> may need to be stored for validation purposes.
-For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
-(but the I<gindex> is not). For B<DSA> however, these fields are not stored in
-the ASN1 data so they need to be stored externally if validation is required.
+and I<gindex> may need to be stored for validation purposes. For B<DSA> these
+fields are not stored in the ASN1 data so they need to be stored externally if
+validation is required.
-=head2 Common DH parameters
+=head2 DSA parameters
-=over 4
-
-=item "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
-
-A string that associates a B<DH> named safe prime group with known values for
-I<p>, I<q> and I<g>.
-
-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<p> and I<g> the value of I<q> can also be
-retrieved.
-
-=item "safeprime-generator" (B<OSSL_PKEY_PARAM_FFC_GENERATOR>) <integer>
-
-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<p>.
-
-=back
-
-=head2 Common DSA & DH parameters
-
-In addition to the common parameters that all keytypes should support (see
-L<provider-keymgmt(7)/Common parameters>), the B<DSA> and B<DH> keytype
-implementations support the following.
-
-=over 4
-
-=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
-
-The public key value.
-
-=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
-
-The private key value.
-
-=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
+The B<DSA> key type supports the FFC parameters (see
+L<EVP_PKEY-FFC(7)/FFC parameters>).
-A DSA or Diffie-Hellman prime "p" value.
+=head2 DSA key generation parameters
-=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
+The B<DSA> key type supports the FFC key generation parameters (see
+L<EVP_PKEY-FFC(7)/FFC key generation parameters>
-A DSA or Diffie-Hellman prime "q" value.
-
-=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
-
-A DSA or Diffie-Hellman generator "g" value.
-
-=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
-
-An optional domain parameter I<seed> value used during generation and validation
-of I<p>, I<q> and canonical I<g>.
-For validation this needs to set the I<seed> that was produced during generation.
-
-=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
-
-Sets the index to use for canonical generation and verification of the generator
-I<g>.
-Set this to a positive value from 0..FF to use this mode. This I<gindex> can
-then be reused during key validation to verify the value of I<g>. If this value
-is not set or is -1 then unverifiable generation of the generator I<g> will be
-used.
-
-=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
-
-An optional domain parameter I<counter> value that is output during generation
-of I<p>. This value must be saved if domain parameter validation is required.
-
-=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
-
-For unverifiable generation of the generator I<g> this value is output during
-generation of I<g>. 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<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
-
-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
+The following restrictions apply to the "pbits" field:
-=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
-
-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<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
-
-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_4" this must be either 2048 or 3072.
For "fips186_2" this must be 1024.
For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
-=item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
+=head1 EXAMPLES
-Sets the size (in bits) of the prime 'q'.
+An B<EVP_PKEY> context can be obtained by calling:
-For "fips186_4" this can be either 224 or 256.
-For "fips186_2" this has a size of 160.
+ EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
-=item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <utf8_string>
+An B<DH> domain parameters key can be generated by calling:
-Sets the Digest algorithm to be used as part of the Key Generation Function
-associated with the given Key Generation I<ctx>.
-This must also be set for key validation.
+ unsigned int pbits = 2048;
+ unsigned int qbits = 256;
+ int gindex = 1;
+ OSSL_PARAM params[5];
+ EVP_PKEY *param_key = NULL;
+ EVP_PKEY_CTX *pctx = NULL;
-=item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string>
+ pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
+ EVP_PKEY_paramgen_init(pctx);
-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<ctx>. This may also be set for key validation.
+ params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
+ params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
+ params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
+ params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
+ params[4] = OSSL_PARAM_construct_end();
+ EVP_PKEY_CTX_set_params(pctx, params);
-=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
+ EVP_PKEY_gen(pctx, ¶m_key);
+ EVP_PKEY_CTX_free(pctx);
-For "fips186_4" or "fips186_2" generation this sets the I<seed> 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.
+ EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
-=item "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
+An B<DSA> key can be generated using domain parameters by calling:
-=item "safeprime-generator" (B<OSSL_PKEY_PARAM_FFC_GENERATOR>) <integer>
+ EVP_PKEY *key = NULL;
+ EVP_PKEY_CTX *gctx = NULL;
-=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
-
-=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
-
-=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
-
-These types are described above.
-
-=back
+ gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
+ EVP_PKEY_keygen_init(gctx);
+ EVP_PKEY_gen(gctx, &key);
+ EVP_PKEY_CTX_free(gctx);
+ EVP_PKEY_print_private(bio_out, key, 0, NULL);
=head1 CONFORMING TO
-=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
=head1 SEE ALSO
-L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
-L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-FIPS(7)>,
-L<EVP_SIGNATURE-DSA(7)>, L<EVP_KEYEXCH-DH(7)>
+L<EVP_PKEY-FFC(7)>,
+L<EVP_SIGNATURE-DSA(7)>
+L<EVP_PKEY(3)>,
+L<provider-keymgmt(7)>,
+L<EVP_KEYMGMT(3)>,
+L<OSSL_PROVIDER-default(7)>,
+L<OSSL_PROVIDER-FIPS(7)>
=head1 COPYRIGHT
projects / thirdparty / openssl.git / blobdiff