1 files changed, 41 insertions, 20 deletions
diff --git a/doc/man3/EVP_PKEY_derive.pod b/doc/man3/EVP_PKEY_derive.pod
index 76b3c3986b1c..d61bb5512f62 100644
--- a/doc/man3/EVP_PKEY_derive.pod
+++ b/doc/man3/EVP_PKEY_derive.pod
@@ -2,45 +2,61 @@
 
 =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_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(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
+ int EVP_PKEY_derive_set_peer_ex(EVP_PKEY_CTX *ctx, EVP_PKEY *peer,
+                                 int validate_peer);
  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
-context using key B<pkey> for shared secret derivation.
+EVP_PKEY_derive_init() initializes a public key algorithm context I<ctx> for
+shared secret derivation using the algorithm given when the context was created
+using L<EVP_PKEY_CTX_new(3)> or variants thereof.  The algorithm is used to
+fetch a B<EVP_KEYEXCH> method implicitly, see L<provider(7)/Implicit fetch> for
+more information about implicit fetches.
 
-The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
-be a public key.
+EVP_PKEY_derive_init_ex() is the same as EVP_PKEY_derive_init() but additionally
+sets the passed parameters I<params> on the context before returning.
 
-The EVP_PKEY_derive() derives a shared secret using B<ctx>.
-If B<key> is B<NULL> then the maximum size of the output buffer is written to
-the B<keylen> parameter. If B<key> is not B<NULL> then before the call the
-B<keylen> parameter should contain the length of the B<key> buffer, if the call
-is successful the shared secret is written to B<key> and the amount of data
-written to B<keylen>.
+EVP_PKEY_derive_set_peer_ex() sets the peer key: this will normally
+be a public key. The I<validate_peer> will validate the public key if this value
+is non zero.
+
+EVP_PKEY_derive_set_peer() is similiar to EVP_PKEY_derive_set_peer_ex() with
+I<validate_peer> set to 1.
+
+EVP_PKEY_derive() derives a shared secret using I<ctx>.
+If I<key> is NULL then the maximum size of the output buffer is written to the
+I<keylen> parameter. If I<key> is not NULL then before the call the I<keylen>
+parameter should contain the length of the I<key> buffer, if the call is
+successful the shared secret is written to I<key> and the amount of data
+written to I<keylen>.
 
 =head1 NOTES
 
-After the call to EVP_PKEY_derive_init() algorithm specific control
-operations can be performed to set any appropriate parameters for the
-operation.
+After the call to EVP_PKEY_derive_init(), algorithm
+specific control operations can be performed to set any appropriate parameters
+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
-or a negative value for failure. In particular a return value of -2
-indicates the operation is not supported by the public key algorithm.
+EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1
+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 EXAMPLES
 
@@ -86,16 +102,21 @@ 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.
+The EVP_PKEY_derive_init(), EVP_PKEY_derive_set_peer() and EVP_PKEY_derive()
+functions were originally added in OpenSSL 1.0.0.
+
+The EVP_PKEY_derive_init_ex() and EVP_PKEY_derive_set_peer_ex() functions were
+added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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>.