Update core_names.h fields and document most fields.

Renamed some values in core_names i.e Some DH specific names were changed to use DH instead of FFC.
Added some strings values related to RSA keys.
Moved set_params related docs out of EVP_PKEY_CTX_ctrl.pod into its own file.
Updated Keyexchange and signature code and docs.
Moved some common DSA/DH docs into a shared EVP_PKEY-FFC.pod.
Moved Ed25519.pod into EVP_SIGNATURE-ED25519.pod and reworked it.

Added some usage examples. As a result of the usage examples the following change was also made:
ec allows OSSL_PKEY_PARAM_USE_COFACTOR_ECDH as a settable gen parameter.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11610)

23 files changed, 1260 insertions, 385 deletions

diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod
index 2d7fe49c16..bceee3f500 100644
--- a/doc/man3/EVP_KDF.pod
+++ b/doc/man3/EVP_KDF.pod
@@ -68,6 +68,9 @@ EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given
 a library context I<libctx> and a set of I<properties>.
 See L<provider(7)/Fetching algorithms> for further information.
 
+See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of
+algorithms supported by the default provider.
+
 The returned value must eventually be freed with
 L<EVP_KDF_free(3)>.
 
@@ -248,14 +251,7 @@ supported by the KDF algorithm.
 
 =head1 SEE ALSO
 
-L<EVP_KDF-SCRYPT(7)>
-L<EVP_KDF-TLS1_PRF(7)>
-L<EVP_KDF-PBKDF2(7)>
-L<EVP_KDF-HKDF(7)>
-L<EVP_KDF-SS(7)>
-L<EVP_KDF-SSHKDF(7)>
-L<EVP_KDF-X963(7)>
-L<EVP_KDF-X942(7)>
+L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)>
 
 =head1 HISTORY
 
diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index 1b961d4978..c98c8d873a 100644
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -82,6 +82,9 @@ EVP_MAC_fetch() fetches an implementation of a MAC I<algorithm>, given
 a library context I<libctx> and a set of I<properties>.
 See L<provider(7)/Fetching algorithms> for further information.
 
+See L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)> for the list
+of algorithms supported by the default provider.
+
 The returned value must eventually be freed with
 L<EVP_MAC_free(3)>.
 
diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index 039073cacf..db91f01038 100644
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -2,10 +2,6 @@
 
 =head1 NAME
 
-EVP_PKEY_CTX_get_params,
-EVP_PKEY_CTX_gettable_params,
-EVP_PKEY_CTX_set_params,
-EVP_PKEY_CTX_settable_params,
 EVP_PKEY_CTX_ctrl,
 EVP_PKEY_CTX_ctrl_str,
 EVP_PKEY_CTX_ctrl_uint64,
@@ -78,11 +74,6 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
 
  #include <openssl/evp.h>
 
- int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
- const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
- const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx);
-
  int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
                        int cmd, int p1, void *p2);
  int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype,
@@ -186,49 +177,6 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions get and
-send arbitrary parameters from and to the algorithm implementation respectively.
-Not all parameters may be supported by all providers.
-See L<OSSL_PROVIDER(3)> for more information on providers.
-See L<OSSL_PARAM(3)> for more information on parameters.
-These functions must only be called after the EVP_PKEY_CTX has been initialised
-for use in an operation.
-
-The parameters currently supported by the default provider are:
-
-=over 4
-
-=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
-
-Sets the DH padding mode.
-If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the  shared secret is padded with zeros
-up to the size of the DH prime I<p>.
-If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is
-performed.
-
-=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
-
-Gets and sets the name of the digest algorithm used for the input to the
-signature functions.
-
-=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
-
-Gets and sets the output size of the digest algorithm used for the input to the
-signature functions.
-The length of the "digest-size" parameter should not exceed that of a B<size_t>.
-The internal algorithm that supports this parameter is DSA.
-
-=back
-
-EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() gets a
-constant B<OSSL_PARAM> array that describes the  gettable and
-settable parameters for the current algorithm implementation, i.e. parameters
-that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params()
-respectively.
-See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
-These functions must only be called after the EVP_PKEY_CTX has been initialised
-for use in an operation.
-
 The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
 I<ctx>. The key type used must match I<keytype> if it is not -1. The parameter
 I<optype> is a mask indicating which operations the control can be applied to.
@@ -662,17 +610,13 @@ allocate adequate memory space for the I<id> before calling EVP_PKEY_CTX_get1_id
 
 =head1 RETURN VALUES
 
-EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise.
-EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on
-error.
-It may also return NULL if there are no settable parameters available.
-
 All other functions and macros described on this page return a positive value
 for success and 0 or a negative value for failure. In particular a return value
 of -2 indicates the operation is not supported by the public key algorithm.
 
 =head1 SEE ALSO
 
+L<EVP_PKEY_CTX_set_params(3)>,
 L<EVP_PKEY_CTX_new(3)>,
 L<EVP_PKEY_encrypt(3)>,
 L<EVP_PKEY_decrypt(3)>,
diff --git a/doc/man3/EVP_PKEY_CTX_set_params.pod b/doc/man3/EVP_PKEY_CTX_set_params.pod
new file mode 100644
index 0000000000..b4959c6f44
--- /dev/null
+++ b/doc/man3/EVP_PKEY_CTX_set_params.pod
@@ -0,0 +1,95 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_set_params,
+EVP_PKEY_CTX_settable_params,
+EVP_PKEY_CTX_get_params,
+EVP_PKEY_CTX_gettable_params
+- provider parameter passing operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
+ const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
+ const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions allow
+transfer of arbitrary key parameters to and from providers.
+Not all parameters may be supported by all providers.
+See L<OSSL_PROVIDER(3)> for more information on providers.
+See L<OSSL_PARAM(3)> for more information on parameters.
+These functions must only be called after the EVP_PKEY_CTX has been initialised
+for use in an operation.
+These methods replace the EVP_PKEY_CTX_ctrl() mechanism. (EVP_PKEY_CTX_ctrl now
+calls these methods internally to interact with providers).
+
+EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() get a
+constant B<OSSL_PARAM> array that describes the gettable and
+settable parameters for the current algorithm implementation, i.e. parameters
+that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params()
+respectively.
+See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
+These functions must only be called after the EVP_PKEY_CTX has been initialised
+for use in an operation.
+
+=head2 Parameters
+
+Examples of EVP_PKEY parameters include the following:
+
+L<provider-keymgmt(7)/Common parameters>
+L<provider-keyexch(7)/Key Exchange parameters>
+L<provider-signature(7)/Signature parameters>
+
+L<EVP_PKEY-RSA(7)/Common RSA parameters>
+L<EVP_PKEY-RSA(7)/RSA key generation parameters>
+L<EVP_PKEY-FFC(7)/FFC parameters>
+L<EVP_PKEY-FFC(7)/FFC key generation parameters>
+L<EVP_PKEY-DSA(7)/DSA parameters>
+L<EVP_PKEY-DSA(7)/DSA key generation parameters>
+L<EVP_PKEY-DH(7)/DH parameters>
+L<EVP_PKEY-DH(7)/DH key generation parameters>
+L<EVP_PKEY-EC(7)/Common EC parameters>
+L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>
+
+=head1 RETURN VALUES
+
+EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise.
+EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on
+error.
+It may also return NULL if there are no settable parameters available.
+
+All other functions and macros described on this page return a positive value
+for success and 0 or a negative value for failure. In particular a return value
+of -2 indicates the operation is not supported by the public key algorithm.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>,
+L<EVP_PKEY_keygen(3)>
+
+=head1 HISTORY
+
+All functions were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_KEYEXCH-DH.pod b/doc/man7/EVP_KEYEXCH-DH.pod
new file mode 100644
index 0000000000..9e9cee7dce
--- /dev/null
+++ b/doc/man7/EVP_KEYEXCH-DH.pod
@@ -0,0 +1,98 @@
+=pod
+
+=head1 NAME
+
+EVP_KEYEXCH-DH
+- DH Key Exchange algorithm support
+
+=head1 DESCRIPTION
+
+Key exchange support for the B<DH> key type.
+
+=head2 DH key exchange parameters
+
+=over 4
+
+=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
+
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
+
+=back
+
+=head1 EXAMPLES
+
+The examples assume a host and peer both generate keys using the same
+named group (or domain parameters). See L<EVP_PKEY-DH(7)/Examples>.
+Both the host and peer transfer their public key to each other.
+
+To convert the peer's generated key pair to a public key in DER format in order
+to transfer to the host:
+
+    EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */
+    unsigned char *peer_pub_der = NULL;
+    int peer_pub_der_len;
+
+    peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der);
+    ...
+    OPENSSL_free(peer_pub_der);
+
+To convert the received peer's public key from DER format on the host:
+
+    const unsigned char *pd = peer_pub_der;
+    EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len);
+    ...
+    EVP_PKEY_free(peer_pub_key);
+
+To derive a shared secret on the host using the host's key and the peer's public
+key:
+    /* It is assumed that the host_key and peer_pub_key are set up */
+    void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key)
+    {
+        unsigned int pad = 1;
+        OSSL_PARAM params[2];
+        unsigned char *secret = NULL;
+        size_t secret_len = 0;
+        EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
+
+        EVP_PKEY_derive_init(dctx);
+
+        /* Optionally set the padding */
+        params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
+        params[1] = OSSL_PARAM_construct_end();
+        EVP_PKEY_CTX_set_params(dctx, params);
+
+        EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
+
+        /* Get the size by passing NULL as the buffer */
+        EVP_PKEY_derive(dctx, NULL, &secret_len);
+        secret = OPENSSL_zalloc(secret_len);
+
+        EVP_PKEY_derive(dctx, secret, &secret_len);
+        ...
+        OPENSSL_clear_free(secret, secret_len);
+        EVP_PKEY_CTX_free(dctx);
+    }
+
+Very similar code can be used by the peer to derive the same shared secret
+using the host's public key and the peer's generated key pair.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY-DH(7)>,
+L<EVP_PKEY-FFC(7)>,
+L<EVP_PKEY(3)>,
+L<provider-keyexch(7)>,
+L<provider-keymgmt(7)>,
+L<OSSL_PROVIDER-default(7)>,
+L<OSSL_PROVIDER-FIPS(7)>,
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_KEYEXCH-ECDH.pod b/doc/man7/EVP_KEYEXCH-ECDH.pod
new file mode 100644
index 0000000000..1add4b7100
--- /dev/null
+++ b/doc/man7/EVP_KEYEXCH-ECDH.pod
@@ -0,0 +1,133 @@
+=pod
+
+=head1 NAME
+
+EVP_KEYEXCH-ECDH - ECDH Key Exchange algorithm support
+
+=head1 DESCRIPTION
+
+Key exchange support for the B<ECDH> key type.
+
+=head2 ECDH Key Exchange parameters
+
+=over 4
+
+=item "ecdh-cofactor-mode" (B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE>) <integer>
+
+Sets or gets the ECDH mode of operation for the associated key exchange ctx.
+
+In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter
+can be used to select between the plain Diffie-Hellman (DH) or Cofactor
+Diffie-Hellman (CDH) variants of the key exchange algorithm.
+
+When setting, the value should be 1, 0 or -1, respectively forcing cofactor mode
+on, off, or resetting it to the default for the private key associated with the
+given key exchange ctx.
+
+When getting, the value should be either 1 or 0, respectively signaling if the
+cofactor mode is on or off.
+
+See also L<provider-keymgmt(7)> for the related
+B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> parameter that can be set on a
+per-key basis.
+
+=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <utf8_string>
+
+Sets or gets the Key Derivation Function type to apply within the associated key
+exchange ctx.
+
+=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <utf8_string>
+
+Sets or gets the Digest algorithm to be used as part of the Key Derivation Function
+associated with the given key exchange ctx.
+
+=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <utf8_string>
+
+Sets properties to be used upon look up of the implementation for the selected
+Digest algorithm for the Key Derivation Function associated with the given key
+exchange ctx.
+
+=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <size_t>
+
+Sets or gets the desired size for the output of the chosen Key Derivation Function
+associated with the given key exchange ctx.
+
+=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string>
+
+Sets the User Key Material to be used as part of the selected Key Derivation
+Function associated with the given key exchange ctx.
+
+=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string_ptr>
+
+Gets a pointer to the User Key Material to be used as part of the selected
+Key Derivation Function associated with the given key exchange ctx.
+
+=item "kdf-ukm-len" (B<OSSL_EXCHANGE_PARAM_KDF_UKM_LEN>) <size_t>
+
+Gets the size of the User Key Material to be used as part of the selected
+Key Derivation Function associated with the given key exchange ctx.
+
+=back
+
+=head1 EXAMPLES
+
+Keys for the host and peer must be generated as shown in
+L<EVP_PKEY-EC(7)/Examples> using the same curve name.
+
+The code to generate a shared secret for the normal case is identical to
+L<EVP_KEYEXCH-DH(7)/Examples>. 
+
+To derive a shared secret on the host using the host's key and the peer's public
+key but also using X963KDF with a user key material:
+
+    /* It is assumed that the host_key, peer_pub_key and ukm are set up */
+    void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key,
+                       unsigned char *ukm, size_t ukm_len)
+    {
+        unsigned char secret[64];
+        size_t out_len = sizeof(secret);
+        size_t secret_len = out_len;
+        unsigned int pad = 1;
+        OSSL_PARAM params[6];
+        EVP_PKET_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
+
+        EVP_PKEY_derive_init(dctx);
+
+        params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
+        params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE,
+                                                     "X963KDF", 0);
+        params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST,
+                                                     "SHA1", 0);
+        params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN,
+                                                &out_len);
+        params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM,
+                                                      ukm, ukm_len);
+        params[5] = OSSL_PARAM_construct_end();
+        EVP_PKEY_CTX_set_params(dctx, params);
+
+        EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
+        EVP_PKEY_derive(dctx, secret, &secret_len);
+        ...
+        OPENSSL_clear_free(secret, secret_len);
+        EVP_PKEY_CTX_free(dctx);
+    }
+
+=head1 SEE ALSO
+
+L<EVP_PKEY-EC(7)>
+L<EVP_PKEY(3)>,
+L<provider-keyexch(7)>,
+L<provider-keymgmt(7)>,
+L<OSSL_PROVIDER-default(7)>,
+L<OSSL_PROVIDER-FIPS(7)>,
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_KEYEXCH-X25519.pod b/doc/man7/EVP_KEYEXCH-X25519.pod
new file mode 100644
index 0000000000..6140c56196
--- /dev/null
+++ b/doc/man7/EVP_KEYEXCH-X25519.pod
@@ -0,0 +1,50 @@
+=pod
+
+=head1 NAME
+
+EVP_KEYEXCH-X25519,
+EVP_KEYEXCH-X448
+- X25519 and X448 Key Exchange algorithm support
+
+=head1 DESCRIPTION
+
+Key exchange support for the B<X25519> and B<X448> key types.
+
+=head2 Key exchange parameters
+
+=over 4
+
+=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
+
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
+
+=back
+
+=head1 EXAMPLES
+
+Keys for the host and peer can be generated as shown in
+L<EVP_PKEY-X25519(7)/Examples>.
+
+The code to generate a shared secret is identical to
+L<EVP_KEYEXCH-DH(7)/Examples>.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY-FFC(7)>,
+L<EVP_PKEY-DH(7)>
+L<EVP_PKEY(3)>,
+L<provider-keyexch(7)>,
+L<provider-keymgmt(7)>,
+L<OSSL_PROVIDER-default(7)>,
+L<OSSL_PROVIDER-FIPS(7)>,
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod
new file mode 100644
index 0000000000..33b19a74f9
--- /dev/null
+++ b/doc/man7/EVP_PKEY-DH.pod
@@ -0,0 +1,229 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY-DH, EVP_KEYMGMT-DH - EVP_PKEY DH keytype and algorithm support
+
+=head1 DESCRIPTION
+
+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.
+
+See L<EVP_PKEY-FFC(7)> for more information about FFC keys.
+
+For 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. 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).
+
+=head2 DH parameters
+
+In addition to the common FCC parameters that all FFC keytypes should support
+(see L<EVP_PKEY-FFC(7)/FFC parameters>)) the B<DH> keytype
+implementation supports the following:
+
+=over 4
+
+=item "group" (B<OSSL_PKEY_PARAM_DH_GROUP>) <UTF8 string>
+
+Set or gets 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 OpenSSL's default and 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 OpenSSL's 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_DH_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 DH domain parameter / key generation parameters
+
+In addition to the common FCC key generation parameters that all FFC key types
+should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>)) the
+B<DH> keytype implementation supports the following:
+
+=over 4
+
+=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
+
+Sets the type of parameter generation. For B<DH> valid values are:
+
+=over 4
+
+=item "fips186_4"
+
+=item "default"
+
+=item "fips186_2"
+
+These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters>
+
+=item "group"
+
+This specifies that a named safe prime name will be chosen using the "pbits"
+type.
+
+=item "generator"
+
+A safe prime generator. See the "safeprime-generator" type above.
+
+=back
+
+=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 "fips186_2" this must be 1024.
+For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
+
+=item "priv_len" (B<OSSL_PKEY_PARAM_DH_PRIV_LEN>) <integer>
+
+An optional value to set the maximum length of the generated private key.
+The default valure used if this is not set is the maximum value of
+BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s.
+Where s is the security strength of the key which has values of
+112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.
+
+=back
+
+=head1 EXAMPLES
+
+An B<EVP_PKEY> context can be obtained by calling:
+
+    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
+
+An B<DH> key can be generated with a named safe prime group by calling:
+
+    int priv_len = 2 * 112;
+    OSSL_PARAM params[3];
+    EVP_PKEY *pkey = NULL;
+    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
+
+    params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0);
+    /* "priv_len" is optional */
+    params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len);
+    params[2] = OSSL_PARAM_construct_end();
+
+    EVP_PKEY_keygen_init(pctx);
+    EVP_PKEY_CTX_set_params(pctx, params);
+    EVP_PKEY_gen(pctx, &pkey);
+    ...
+    EVP_PKEY_free(key);
+    EVP_PKEY_CTX_free(pctx);
+
+Legacy B<DH> domain parameters can be generated by calling:
+    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;
+
+    pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
+    EVP_PKEY_paramgen_init(pctx);
+    
+    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);
+
+    EVP_PKEY_gen(pctx, &param_key);
+
+    EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
+    ...
+    EVP_PKEY_free(param_key);
+    EVP_PKEY_CTX_free(pctx);
+
+An B<DH> key can be generated using domain parameters by calling:
+
+    EVP_PKEY *key = NULL;
+    EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
+
+    EVP_PKEY_keygen_init(gctx);
+    EVP_PKEY_gen(gctx, &key);
+    EVP_PKEY_print_private(bio_out, key, 0, NULL);
+    ...
+    EVP_PKEY_free(key);
+    EVP_PKEY_CTX_free(gctx);
+
+=for comment TODO(3.0): To validate domain parameters, additional values used
+during generation may be required to be set into the key.
+
+=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
+
+=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
+
+L<EVP_PKEY-FFC(7)>,
+L<EVP_KEYEXCH-DH(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
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod
index ccb34a9f93..680717b140 100644
--- a/doc/man7/EVP_PKEY-DSA.pod
+++ b/doc/man7/EVP_PKEY-DSA.pod
@@ -2,240 +2,77 @@
 
 =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 grou