doc: update PKEY documentation to include the new init functions with params

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/14383)

7 files changed, 52 insertions, 18 deletions

diff --git a/doc/man3/EVP_PKEY_decapsulate.pod b/doc/man3/EVP_PKEY_decapsulate.pod
index 7dd47a1e58..36e8f9c9d4 100644
--- a/doc/man3/EVP_PKEY_decapsulate.pod
+++ b/doc/man3/EVP_PKEY_decapsulate.pod
@@ -9,7 +9,7 @@ EVP_PKEY_decapsulate_init, EVP_PKEY_decapsulate
 
  #include <openssl/evp.h>
 
- int EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_decapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
  int EVP_PKEY_decapsulate(EVP_PKEY_CTX *ctx,
                           unsigned char *secret, size_t *secretlen,
                           const unsigned char *wrapped, size_t wrappedlen);
@@ -17,7 +17,8 @@ EVP_PKEY_decapsulate_init, EVP_PKEY_decapsulate
 =head1 DESCRIPTION
 
 The EVP_PKEY_decapsulate_init() function initializes a private key algorithm
-context I<ctx> for a decapsulation operation.
+context I<ctx> for a decapsulation operation and then sets the I<params>
+on the context in the same way as calling L<EVP_PKEY_CTX_set_params(3)>.
 
 The EVP_PKEY_decapsulate() function performs a private key decapsulation
 operation using I<ctx>. The data to be decapsulated is specified using the
@@ -30,8 +31,7 @@ the amount of data written to I<secretlen>.
 =head1 NOTES
 
 After the call to EVP_PKEY_decapsulate_init() algorithm specific parameters
-for the operation may be set using L<EVP_PKEY_CTX_set_params(3)>. There are no
-settable parameters currently.
+for the operation may be set or modified using L<EVP_PKEY_CTX_set_params(3)>.
 
 =head1 RETURN VALUES
 
@@ -57,7 +57,7 @@ Decapsulate data using RSA:
  ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_priv_key, NULL);
  if (ctx = NULL)
      /* Error */
- if (EVP_PKEY_decapsulate_init(ctx) <= 0)
+ if (EVP_PKEY_decapsulate_init(ctx, NULL) <= 0)
      /* Error */
 
  /* Set the mode - only 'RSASVE' is currently supported */
diff --git a/doc/man3/EVP_PKEY_decrypt.pod b/doc/man3/EVP_PKEY_decrypt.pod
index a78c1ee8e4..f516489df4 100644
--- a/doc/man3/EVP_PKEY_decrypt.pod
+++ b/doc/man3/EVP_PKEY_decrypt.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm
+EVP_PKEY_decrypt_init, EVP_PKEY_decrypt_init_ex,
+EVP_PKEY_decrypt - decrypt using a public key algorithm
 
 =head1 SYNOPSIS
 
diff --git a/doc/man3/EVP_PKEY_derive.pod b/doc/man3/EVP_PKEY_derive.pod
index 5bfb316382..be5cf3945e 100644
--- a/doc/man3/EVP_PKEY_derive.pod
+++ b/doc/man3/EVP_PKEY_derive.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive
+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
@@ -10,6 +11,7 @@ EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive
  #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(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
  int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
 
@@ -21,6 +23,9 @@ 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.
 
+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.
+
 EVP_PKEY_derive_set_peer() sets the peer key: this will normally
 be a public key.
 
@@ -95,7 +100,10 @@ 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() function was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/EVP_PKEY_encapsulate.pod b/doc/man3/EVP_PKEY_encapsulate.pod
index 0e911f71cf..7547c7ae34 100644
--- a/doc/man3/EVP_PKEY_encapsulate.pod
+++ b/doc/man3/EVP_PKEY_encapsulate.pod
@@ -9,7 +9,7 @@ EVP_PKEY_encapsulate_init, EVP_PKEY_encapsulate
 
  #include <openssl/evp.h>
 
- int EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
  int EVP_PKEY_encapsulate(EVP_PKEY_CTX *ctx,
                           unsigned char *out, size_t *outlen,
                           unsigned char *genkey, size_t *genkeylen);
@@ -17,7 +17,8 @@ EVP_PKEY_encapsulate_init, EVP_PKEY_encapsulate
 =head1 DESCRIPTION
 
 The EVP_PKEY_encapsulate_init() function initializes a public key algorithm
-context I<ctx> for an encapsulation operation.
+context I<ctx> for an encapsulation operation and then sets the I<params>
+on the context in the same way as calling L<EVP_PKEY_CTX_set_params(3)>.
 
 The EVP_PKEY_encapsulate() function performs a public key encapsulation
 operation using I<ctx> with the name I<name>.
@@ -31,7 +32,7 @@ I<out> and its size is written to I<*outlen>.
 =head1 NOTES
 
 After the call to EVP_PKEY_encapsulate_init() algorithm specific parameters
-for the operation may be set using L<EVP_PKEY_CTX_set_params(3)>.
+for the operation may be set or modified using L<EVP_PKEY_CTX_set_params(3)>.
 
 =head1 RETURN VALUES
 
@@ -56,7 +57,7 @@ Encapsulate an RSASVE key (for RSA keys).
  ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_pub_key, NULL);
  if (ctx = NULL)
      /* Error */
- if (EVP_PKEY_encapsulate_init(ctx) <= 0)
+ if (EVP_PKEY_encapsulate_init(ctx, NULL) <= 0)
      /* Error */
 
  /* Set the mode - only 'RSASVE' is currently supported */
diff --git a/doc/man3/EVP_PKEY_sign.pod b/doc/man3/EVP_PKEY_sign.pod
index bd65bd9237..1e2f71862a 100644
--- a/doc/man3/EVP_PKEY_sign.pod
+++ b/doc/man3/EVP_PKEY_sign.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-EVP_PKEY_sign_init, EVP_PKEY_sign
+EVP_PKEY_sign_init, EVP_PKEY_sign_init_ex, EVP_PKEY_sign
 - sign using a public key algorithm
 
 =head1 SYNOPSIS
@@ -10,6 +10,7 @@ EVP_PKEY_sign_init, EVP_PKEY_sign
  #include <openssl/evp.h>
 
  int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_sign_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
  int EVP_PKEY_sign(EVP_PKEY_CTX *ctx,
                    unsigned char *sig, size_t *siglen,
                    const unsigned char *tbs, size_t tbslen);
@@ -22,6 +23,9 @@ using L<EVP_PKEY_CTX_new(3)> or variants thereof.  The algorithm is used to
 fetch a B<EVP_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch>
 for more information about implicit fetches.
 
+EVP_PKEY_sign_init_ex() is the same as EVP_PKEY_sign_init() but additionally
+sets the passed parameters I<params> on the context before returning.
+
 The EVP_PKEY_sign() function performs a public key signing operation
 using I<ctx>. The data to be signed is specified using the I<tbs> and
 I<tbslen> parameters. If I<sig> is NULL then the maximum size of the output
@@ -105,7 +109,10 @@ L<EVP_PKEY_derive(3)>
 
 =head1 HISTORY
 
-These functions were added in OpenSSL 1.0.0.
+The EVP_PKEY_sign_init() and EVP_PKEY_sign() functions were added in
+OpenSSL 1.0.0.
+
+The EVP_PKEY_sign_init_ex() function was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/EVP_PKEY_verify.pod b/doc/man3/EVP_PKEY_verify.pod
index c41525246a..972c5c54b9 100644
--- a/doc/man3/EVP_PKEY_verify.pod
+++ b/doc/man3/EVP_PKEY_verify.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-EVP_PKEY_verify_init, EVP_PKEY_verify
+EVP_PKEY_verify_init, EVP_PKEY_verify_init_ex, EVP_PKEY_verify
 - signature verification using a public key algorithm
 
 =head1 SYNOPSIS
@@ -10,6 +10,7 @@ EVP_PKEY_verify_init, EVP_PKEY_verify
  #include <openssl/evp.h>
 
  int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
  int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
                      const unsigned char *sig, size_t siglen,
                      const unsigned char *tbs, size_t tbslen);
@@ -22,6 +23,9 @@ using L<EVP_PKEY_CTX_new(3)> or variants thereof.  The algorithm is used to
 fetch a B<EVP_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch>
 for more information about implicit fetches.
 
+EVP_PKEY_verify_init_ex() is the same as EVP_PKEY_verify_init() but additionally
+sets the passed parameters I<params> on the context before returning.
+
 The EVP_PKEY_verify() function performs a public key verification operation
 using I<ctx>. The signature is specified using the I<sig> and
 I<siglen> parameters. The verified data (i.e. the data believed originally
@@ -93,7 +97,10 @@ L<EVP_PKEY_derive(3)>
 
 =head1 HISTORY
 
-These functions were added in OpenSSL 1.0.0.
+The EVP_PKEY_verify_init() and EVP_PKEY_verify() functions were added in
+OpenSSL 1.0.0.
+
+The EVP_PKEY_verify_init_ex() function was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/EVP_PKEY_verify_recover.pod b/doc/man3/EVP_PKEY_verify_recover.pod
index e8acd6ab8d..5b7535007c 100644
--- a/doc/man3/EVP_PKEY_verify_recover.pod
+++ b/doc/man3/EVP_PKEY_verify_recover.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover
+EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover_init_ex,
+EVP_PKEY_verify_recover
 - recover signature using a public key algorithm
 
 =head1 SYNOPSIS
@@ -10,6 +11,8 @@ EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover
  #include <openssl/evp.h>
 
  int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_verify_recover_init_ex(EVP_PKEY_CTX *ctx,
+                                     const OSSL_PARAM params[]);
  int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,
                              unsigned char *rout, size_t *routlen,
                              const unsigned char *sig, size_t siglen);
@@ -22,6 +25,10 @@ using L<EVP_PKEY_CTX_new(3)> or variants thereof.  The algorithm is used to
 fetch a B<EVP_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch>
 for more information about implicit fetches.
 
+EVP_PKEY_verify_recover_init_ex() is the same as
+EVP_PKEY_verify_recover_init() but additionally sets the passed parameters
+I<params> on the context before returning.
+
 The EVP_PKEY_verify_recover() function recovers signed data
 using I<ctx>. The signature is specified using the I<sig> and
 I<siglen> parameters. If I<rout> is NULL then the maximum size of the output
@@ -104,7 +111,10 @@ L<EVP_PKEY_derive(3)>
 
 =head1 HISTORY
 
-These functions were added in OpenSSL 1.0.0.
+The EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover()
+functions were added in OpenSSL 1.0.0.
+
+The EVP_PKEY_verify_recover_init_ex() function was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT