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)

41 files changed, 1375 insertions, 472 deletions

diff --git a/crypto/dh/dh_lib.c b/crypto/dh/dh_lib.c
index c3585f264f..3a523c3591 100644
--- a/crypto/dh/dh_lib.c
+++ b/crypto/dh/dh_lib.c
@@ -475,7 +475,7 @@ int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen)
                                  EVP_PKEY_CTRL_DH_PARAMGEN_GENERATOR, gen, NULL);
 #endif
 
-    *p++ = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_FFC_GENERATOR, &gen);
+    *p++ = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_DH_GENERATOR, &gen);
     *p++ = OSSL_PARAM_construct_end();
 
     return EVP_PKEY_CTX_set_params(ctx, params);
@@ -500,7 +500,7 @@ int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int gen)
     if (name == NULL)
         return 0;
 
-    *p++ = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_FFC_GROUP,
+    *p++ = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_DH_GROUP,
                                             (void *)name, 0);
     *p++ = OSSL_PARAM_construct_end();
     return EVP_PKEY_CTX_set_params(ctx, params);
@@ -531,7 +531,7 @@ int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid)
     if (name == NULL)
         return 0;
 
-    *p++ = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_FFC_GROUP,
+    *p++ = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_DH_GROUP,
                                             (void *)name, 0);
     *p++ = OSSL_PARAM_construct_end();
     return EVP_PKEY_CTX_set_params(ctx, params);
diff --git a/crypto/ec/ec_backend.c b/crypto/ec/ec_backend.c
index 98dd0ecf5d..fb6497b084 100644
--- a/crypto/ec/ec_backend.c
+++ b/crypto/ec/ec_backend.c
@@ -19,15 +19,10 @@
  * implementations alike.
  */
 
-int ec_set_param_ecdh_cofactor_mode(EC_KEY *ec, const OSSL_PARAM *p)
+int ec_set_ecdh_cofactor_mode(EC_KEY *ec, int mode)
 {
     const EC_GROUP *ecg = EC_KEY_get0_group(ec);
     const BIGNUM *cofactor;
-    int mode;
-
-    if (!OSSL_PARAM_get_int(p, &mode))
-        return 0;
-
     /*
      * mode can be only 0 for disable, or 1 for enable here.
      *
@@ -224,8 +219,12 @@ int ec_key_otherparams_fromdata(EC_KEY *ec, const OSSL_PARAM params[])
         return 0;
 
     p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_USE_COFACTOR_ECDH);
-    if (p != NULL && !ec_set_param_ecdh_cofactor_mode(ec, p))
-        return 0;
+    if (p != NULL) {
+        int mode;
 
+        if (!OSSL_PARAM_get_int(p, &mode)
+            || !ec_set_ecdh_cofactor_mode(ec, mode))
+            return 0;
+    }
     return 1;
 }
diff --git a/crypto/evp/pmeth_lib.c b/crypto/evp/pmeth_lib.c
index e4327b3a94..355565de63 100644
--- a/crypto/evp/pmeth_lib.c
+++ b/crypto/evp/pmeth_lib.c
@@ -1033,7 +1033,7 @@ static int legacy_ctrl_str_to_param(EVP_PKEY_CTX *ctx, const char *name,
 # endif
 # ifndef OPENSSL_NO_DH
     else if (strcmp(name, "dh_paramgen_generator") == 0)
-        name = OSSL_PKEY_PARAM_FFC_GENERATOR;
+        name = OSSL_PKEY_PARAM_DH_GENERATOR;
     else if (strcmp(name, "dh_paramgen_prime_len") == 0)
         name = OSSL_PKEY_PARAM_FFC_PBITS;
     else if (strcmp(name, "dh_paramgen_subprime_len") == 0)
@@ -1042,9 +1042,9 @@ static int legacy_ctrl_str_to_param(EVP_PKEY_CTX *ctx, const char *name,
         name = OSSL_PKEY_PARAM_FFC_TYPE;
         value = dh_gen_type_id2name(atoi(value));
     } else if (strcmp(name, "dh_param") == 0)
-        name = OSSL_PKEY_PARAM_FFC_GROUP;
+        name = OSSL_PKEY_PARAM_DH_GROUP;
     else if (strcmp(name, "dh_rfc5114") == 0) {
-        name = OSSL_PKEY_PARAM_FFC_GROUP;
+        name = OSSL_PKEY_PARAM_DH_GROUP;
         value = ffc_named_group_from_uid(atoi(value));
     } else if (strcmp(name, "dh_pad") == 0)
         name = OSSL_EXCHANGE_PARAM_PAD;
diff --git a/crypto/ffc/ffc_backend.c b/crypto/ffc/ffc_backend.c
index 1cfa427df6..c34e79bf4f 100644
--- a/crypto/ffc/ffc_backend.c
+++ b/crypto/ffc/ffc_backend.c
@@ -27,7 +27,7 @@ int ffc_params_fromdata(FFC_PARAMS *ffc, const OSSL_PARAM params[])
     if (ffc == NULL)
         return 0;
 
-    prm  = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_FFC_GROUP);
+    prm  = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_DH_GROUP);
     if (prm != NULL) {
         if (prm->data_type != OSSL_PARAM_UTF8_STRING)
             goto err;
diff --git a/crypto/ffc/ffc_params.c b/crypto/ffc/ffc_params.c
index efd7dc8920..a95a2fa12b 100644
--- a/crypto/ffc/ffc_params.c
+++ b/crypto/ffc/ffc_params.c
@@ -220,7 +220,7 @@ int ffc_params_todata(const FFC_PARAMS *ffc, OSSL_PARAM_BLD *bld,
 
         if (name == NULL
             || !ossl_param_build_set_utf8_string(bld, params,
-                                                 OSSL_PKEY_PARAM_FFC_GROUP,
+                                                 OSSL_PKEY_PARAM_DH_GROUP,
                                                  name))
             return 0;
 #else
diff --git a/crypto/provider_core.c b/crypto/provider_core.c
index 0c21660080..f8aa5721b4 100644
--- a/crypto/provider_core.c
+++ b/crypto/provider_core.c
@@ -841,8 +841,13 @@ int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
  * never knows.
  */
 static const OSSL_PARAM param_types[] = {
-    OSSL_PARAM_DEFN("openssl-version", OSSL_PARAM_UTF8_PTR, NULL, 0),
-    OSSL_PARAM_DEFN("provider-name", OSSL_PARAM_UTF8_PTR, NULL, 0),
+    OSSL_PARAM_DEFN(OSSL_PROV_PARAM_CORE_VERSION, OSSL_PARAM_UTF8_PTR, NULL, 0),
+    OSSL_PARAM_DEFN(OSSL_PROV_PARAM_CORE_PROV_NAME, OSSL_PARAM_UTF8_PTR,
+                    NULL, 0),
+#ifndef FIPS_MODULE
+    OSSL_PARAM_DEFN(OSSL_PROV_PARAM_CORE_MODULE_FILENAME, OSSL_PARAM_UTF8_PTR,
+                    NULL, 0),
+#endif
     OSSL_PARAM_END
 };
 
@@ -879,13 +884,14 @@ static int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[])
      */
     OSSL_PROVIDER *prov = (OSSL_PROVIDER *)handle;
 
-    if ((p = OSSL_PARAM_locate(params, "openssl-version")) != NULL)
+    if ((p = OSSL_PARAM_locate(params, OSSL_PROV_PARAM_CORE_VERSION)) != NULL)
         OSSL_PARAM_set_utf8_ptr(p, OPENSSL_VERSION_STR);
-    if ((p = OSSL_PARAM_locate(params, "provider-name")) != NULL)
+    if ((p = OSSL_PARAM_locate(params, OSSL_PROV_PARAM_CORE_PROV_NAME)) != NULL)
         OSSL_PARAM_set_utf8_ptr(p, prov->name);
 
 #ifndef FIPS_MODULE
-    if ((p = OSSL_PARAM_locate(params, OSSL_PROV_PARAM_MODULE_FILENAME)) != NULL)
+    if ((p = OSSL_PARAM_locate(params,
+                               OSSL_PROV_PARAM_CORE_MODULE_FILENAME)) != NULL)
         OSSL_PARAM_set_utf8_ptr(p, ossl_provider_module_path(prov));
 #endif
 
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.
+