Document the new EVP_KEYEXCH type and related functions

Previous commits added the EVP_KEYEXCH type for representing key exchange
algorithms. They also added various functions for fetching and using them,
so we document all of those functions.

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9266)

CHANGES

@@ -9,6 +9,17 @@
 
  Changes between 1.1.1 and 3.0.0 [xx XXX xxxx]
 
+  *) A new type, EVP_KEYEXCH, has been introduced to represent key exchange
+     algorithms. An implementation of a key exchange algorithm can be obtained
+     by using the function EVP_KEYEXCH_fetch(). An EVP_KEYEXCH algorithm can be
+     used in a call to EVP_PKEY_derive_init_ex() which works in a similar way to
+     the older EVP_PKEY_derive_init() function. See the man pages for the new
+     functions for further details.
+     [Matt Caswell]
+
+  *) The EVP_PKEY_CTX_set_dh_pad() macro has now been converted to a function.
+     [Matt Caswell]
+
   *) Removed the function names from error messages and deprecated the
      xxx_F_xxx define's.
      [Rich Salz]

doc/man3/EVP_KEYEXCH_free.pod

@@ -0,0 +1,46 @@
+=pod
+
+=head1 NAME
+
+EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref
+- Functions to manage EVP_KEYEXCH algorithm objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ void EVP_KEYEXCH_free(EVP_KEYEXCH *exchange);
+ int EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange);
+
+=head1 DESCRIPTION
+
+EVP_KEYEXCH_free() decrements the reference count for the B<EVP_KEYEXCH>
+structure. Typically this structure will have been obtained from an earlier call
+to L<EVP_KEYEXCH_fetch(3)>. If the reference count drops to 0 then the
+structure is freed.
+
+EVP_KEYEXCH_up_ref() increments the reference count for an B<EVP_KEYEXCH>
+structure.
+
+=head1 RETURN VALUES
+
+EVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise.
+
+=head1 SEE ALSO
+
+L<EVP_KEYEXCH_fetch(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 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

doc/man3/EVP_MD_fetch.pod

@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-EVP_MD_fetch, EVP_CIPHER_fetch
+EVP_MD_fetch, EVP_CIPHER_fetch, EVP_KEYEXCH_fetch
 - Functions to explicitly fetch algorithm implementations
 
 =head1 SYNOPSIS
@@ -13,6 +13,8 @@ EVP_MD_fetch, EVP_CIPHER_fetch
                       const char *properties);
  EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
                               const char *properties);
+ EVP_KEYEXCH *EVP_KEYEXCH_fetch(OPENSSL_CTX *ctx, const char *algorithm,
+                                const char *properties);
 
 =head1 DESCRIPTION
 
@@ -38,6 +40,10 @@ Represents a Message Authentication Code algorithm.
 
 Represents a Key Derivation Function algorithm.
 
+=item B<EVP_KEYEXCH>
+
+Represents a Key Exchange algorithm.
+
 =back
 
 The algorithm objects may or may not have an associated algorithm
@@ -62,6 +68,12 @@ Typically, this will return an implementation of the appropriate algorithm from
 the default provider unless the default search criteria have been changed and/or
 different providers have been loaded.
 
+Implicit fetching can also occur with functions such as
+L<EVP_PKEY_CTX_derive_init_ex(3)> where a NULL algorithm parameter is supplied.
+In this case an algorithm implementation is implicitly fetched using default
+search criteria and an algorithm name that is consistent with the type of
+EVP_PKEY being used.
+
 =item Explicit Fetch
 
 With explicit fetch an application uses one of the "fetch" functions to obtain

doc/man3/EVP_PKEY_CTX_ctrl.pod

@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+EVP_PKEY_CTX_set_params,
 EVP_PKEY_CTX_ctrl,
 EVP_PKEY_CTX_ctrl_str,
 EVP_PKEY_CTX_ctrl_uint64,
@@ -62,6 +63,8 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
+
  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,
@@ -141,6 +144,25 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
 
 =head1 DESCRIPTION
 
+The EVP_PKEY_CTX_set_params() function sends arbitrary parameters to the
+algorithm implementation.
+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.
+The parameters currently supported by the default provider are:
+
+=over 4
+
+=item OSSL_EXCHANGE_PARAM_PAD (int type)
+
+Sets the DH padding mode.
+If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the  shared secret is padded with zeroes
+up to the size of the DH prime B<p>.
+If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is
+performed.
+
+=back
+
 The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
 B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter
 B<optype> is a mask indicating which operations the control can be applied to.
@@ -290,8 +312,9 @@ The EVP_PKEY_CTX_set_dh_paramgen_type() macro sets the key type for DH
 parameter generation. Use 0 for PKCS#3 DH and 1 for X9.42 DH.
 The default is 0.
 
-The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is
+The EVP_PKEY_CTX_set_dh_pad() function sets the DH padding mode.
-1 the shared secret is padded with zeroes up to the size of the DH prime B<p>.
+If B<pad> is 1 the shared secret is padded with zeroes up to the size of the DH
+prime B<p>.
 If B<pad> is zero (the default) then no padding is performed.
 
 EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to
@@ -458,6 +481,9 @@ The
 EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len()
 macros were added in 1.1.1, other functions were added in OpenSSL 1.0.0.
 
+EVP_PKEY_CTX_set_dh_pad() was a macro in OpenSSL 1.1.1 and below.
+From OpenSSL 3.0 it is a function.
+
 =head1 COPYRIGHT
 
 Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.

doc/man3/EVP_PKEY_derive.pod

@@ -2,20 +2,33 @@
 
 =head1 NAME
 
-EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret
+EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex, EVP_PKEY_derive_set_peer,
+EVP_PKEY_derive - derive public key algorithm shared secret
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, EVP_KEYEXCH *exchange);
  int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
  int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_derive_init() function initializes a public key algorithm
+The EVP_PKEY_derive_init_ex() function initializes a public key algorithm
-context using key B<pkey> for shared secret derivation.
+context for shared secret derivation using the key exchange algorithm
+B<exchange>.
+The key exchange algorithm B<exchange> should be fetched using a call to
+L<EVP_KEYEXCH_fetch(3)>.
+The EVP_PKEY object associated with B<ctx> must be compatible with that
+algorithm.
+B<exchange> may be NULL in which case the EVP_KEYEXCH algorithm is fetched
+implicitly based on the type of EVP_PKEY associated with B<ctx>.
+See L<EVP_KEYEXCH_fetch(3)> for more information about implict fetches.
+
+The EVP_PKEY_derive_init() function is the same as EVP_PKEY_derive() except that
+the EVP_KEYEXCH algorithm is always implicitly fetched.
 
 The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
 be a public key.
@@ -29,18 +42,19 @@ written to B<keylen>.
 
 =head1 NOTES
 
-After the call to EVP_PKEY_derive_init() algorithm specific control
+After the call to EVP_PKEY_derive_init() or EVP_PKEY_derive_init_ex() algorithm
-operations can be performed to set any appropriate parameters for the
+specific control operations can be performed to set any appropriate parameters
-operation.
+for the operation.
 
 The function EVP_PKEY_derive() can be called more than once on the same
 context if several operations are performed using the same parameters.
 
 =head1 RETURN VALUES
 
-EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
+EVP_PKEY_derive_init_ex(), EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1
-or a negative value for failure. In particular a return value of -2
+for success and 0 or a negative value for failure.
-indicates the operation is not supported by the public key algorithm.
+In particular a return value of -2 indicates the operation is not supported by
+the public key algorithm.
 
 =head1 EXAMPLE
 
@@ -86,10 +100,12 @@ L<EVP_PKEY_decrypt(3)>,
 L<EVP_PKEY_sign(3)>,
 L<EVP_PKEY_verify(3)>,
 L<EVP_PKEY_verify_recover(3)>,
+L<EVP_KEYEXCH_fetch(3)>
 
 =head1 HISTORY
 
-These functions were added in OpenSSL 1.0.0.
+These functions were added in OpenSSL 1.0.0. The EVP_PKEY_derive_init_ex()
+function was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT