docs: clarify EVP_PKEY context workflow and operation descriptions

Document that a generated key is returned separately from its generation
context and that a new key-bound context is needed for subsequent
operations. Correct the encrypt and decrypt initialization descriptions
and examples accordingly.

Correct two copy-and-paste errors in the verify-recover documentation:
describe its initializer as starting a verify-recover operation and refer
to EVP_PKEY_verify_recover() when discussing its input.

Fixes #31989

Assisted-by: Grok:Grok-4.5
Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
MergeDate: Thu Jul 23 08:29:24 2026
(Merged from https://github.com/openssl/openssl/pull/31995)

diff --git a/doc/man3/EVP_PKEY_CTX_new.pod b/doc/man3/EVP_PKEY_CTX_new.pod
index fff102a769ab8f0c22c6c41594d661a66ca3806d..9ded13de5df5c95736460e338ef26b20ab1241bd 100644 (file)
--- a/doc/man3/EVP_PKEY_CTX_new.pod
+++ b/doc/man3/EVP_PKEY_CTX_new.pod
@@ -48,6 +48,9 @@ EVP_PKEY_CTX_new_id() and EVP_PKEY_CTX_new_from_name() are normally
 used when no B<EVP_PKEY> structure is associated with the operations,
 for example during parameter generation or key generation for some
 algorithms.
+The key returned by L<EVP_PKEY_generate(3)> is not associated with the
+generation context.  To perform operations using that key, create a new context
+with L<EVP_PKEY_CTX_new_from_pkey(3)>.
 
 EVP_PKEY_CTX_dup() duplicates the context I<ctx>.
 It is not supported for a keygen operation.
@@ -125,7 +128,7 @@ added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2006-2025 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2026 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

diff --git a/doc/man3/EVP_PKEY_decrypt.pod b/doc/man3/EVP_PKEY_decrypt.pod
index 5e624e8c6117c1dc3871643d0bb6361d5a8dec4e..6b46329793730f6c524b883c17f81330dc5ad8fd 100644 (file)
--- a/doc/man3/EVP_PKEY_decrypt.pod
+++ b/doc/man3/EVP_PKEY_decrypt.pod
@@ -17,12 +17,13 @@ EVP_PKEY_decrypt - decrypt using a public key algorithm
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_decrypt_init() function initializes a public key algorithm
-context using key I<pkey> for a decryption operation.
+The EVP_PKEY_decrypt_init() function initializes the public key algorithm
+context I<ctx> for a decryption operation.  A key must already be associated
+with I<ctx>; this is normally done by creating it with
+L<EVP_PKEY_CTX_new(3)> or L<EVP_PKEY_CTX_new_from_pkey(3)>.
 
-The EVP_PKEY_decrypt_init_ex() function initializes a public key algorithm
-context using key I<pkey> for a decryption operation and sets the
-algorithm specific I<params>.
+The EVP_PKEY_decrypt_init_ex() function is the same as
+EVP_PKEY_decrypt_init() but additionally sets the algorithm-specific I<params>.
 
 The EVP_PKEY_decrypt() function performs a public key decryption operation
 using I<ctx>. The data to be decrypted is specified using the I<in> and
@@ -88,7 +89,7 @@ Decrypt data using OAEP (for RSA keys):
   * NB: assumes key, in, inlen are already set up
   * and that key is an RSA private key
   */
- ctx = EVP_PKEY_CTX_new(key, NULL);
+ ctx = EVP_PKEY_CTX_new_from_pkey(NULL, key, NULL);
  if (!ctx)
      /* Error occurred */
  if (EVP_PKEY_decrypt_init(ctx) <= 0)
@@ -125,7 +126,7 @@ These functions were added in OpenSSL 1.0.0.
 
 =head1 COPYRIGHT
 
-Copyright 2006-2025 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2026 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

diff --git a/doc/man3/EVP_PKEY_encrypt.pod b/doc/man3/EVP_PKEY_encrypt.pod
index 1fb41f99f428c6adef45ee393f9ca84013af227a..fda95c218e5d96b945310f4890e7a72c581918cc 100644 (file)
--- a/doc/man3/EVP_PKEY_encrypt.pod
+++ b/doc/man3/EVP_PKEY_encrypt.pod
@@ -17,12 +17,13 @@ EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_encrypt_init() function initializes a public key algorithm
-context using key B<pkey> for an encryption operation.
+The EVP_PKEY_encrypt_init() function initializes the public key algorithm
+context I<ctx> for an encryption operation.  A key must already be associated
+with I<ctx>; this is normally done by creating it with
+L<EVP_PKEY_CTX_new(3)> or L<EVP_PKEY_CTX_new_from_pkey(3)>.
 
-The EVP_PKEY_encrypt_init_ex() function initializes a public key algorithm
-context using key B<pkey> for an encryption operation and sets the
-algorithm specific B<params>.
+The EVP_PKEY_encrypt_init_ex() function is the same as
+EVP_PKEY_encrypt_init() but additionally sets the algorithm-specific I<params>.
 
 The EVP_PKEY_encrypt() function performs a public key encryption operation
 using B<ctx>. The data to be encrypted is specified using the B<in> and
@@ -66,7 +67,7 @@ L<d2i_X509(3)> for means to load a public key.
   * NB: assumes key, in, inlen are already set up,
   * and that key is an RSA public key
   */
- ctx = EVP_PKEY_CTX_new(key, NULL);
+ ctx = EVP_PKEY_CTX_new_from_pkey(NULL, key, NULL);
  if (!ctx)
      /* Error occurred */
  if (EVP_PKEY_encrypt_init(ctx) <= 0)
@@ -104,7 +105,7 @@ These functions were added in OpenSSL 1.0.0.
 
 =head1 COPYRIGHT
 
-Copyright 2006-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2026 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

diff --git a/doc/man3/EVP_PKEY_keygen.pod b/doc/man3/EVP_PKEY_keygen.pod
index 1d5180ef6f4bcbe9f95b535c83ac146e815a3a2e..71daed31c060650864deed84a9c3d76d53b0328a 100644 (file)
--- a/doc/man3/EVP_PKEY_keygen.pod
+++ b/doc/man3/EVP_PKEY_keygen.pod
@@ -66,6 +66,12 @@ parameters or key are written to I<*ppkey>.  If I<*ppkey> is NULL when this
 function is called, it will be allocated, and should be freed by the caller
 when no longer useful, using L<EVP_PKEY_free(3)>.
 
+When a key is generated, EVP_PKEY_generate() does not associate it with I<ctx>
+or change I<ctx> into a context for operations using that key.  To use the
+generated key, create a new context with L<EVP_PKEY_CTX_new_from_pkey(3)>,
+passing I<*ppkey>.  The generation context can be reused for further generation
+operations or freed.
+
 EVP_PKEY_paramgen() and EVP_PKEY_keygen() do exactly the same thing as
 EVP_PKEY_generate(), after checking that the corresponding EVP_PKEY_paramgen_init()
 or EVP_PKEY_keygen_init() was used to initialize I<ctx>.
@@ -153,7 +159,7 @@ in functions which require the use of a public key or parameters.
 
 =head1 EXAMPLES
 
-Generate a 2048 bit RSA key:
+Generate a 2048 bit RSA key, then initialize a context for encryption:
 
  #include <openssl/evp.h>
  #include <openssl/rsa.h>
@@ -161,7 +167,7 @@ Generate a 2048 bit RSA key:
  EVP_PKEY_CTX *ctx;
  EVP_PKEY *pkey = NULL;
 
- ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
+ ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
  if (!ctx)
      /* Error occurred */
  if (EVP_PKEY_keygen_init(ctx) <= 0)
@@ -170,7 +176,15 @@ Generate a 2048 bit RSA key:
      /* Error */
 
  /* Generate key */
- if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
+ if (EVP_PKEY_generate(ctx, &pkey) <= 0)
+     /* Error */
+
+ /* ctx is still a generation context; pkey contains the generated key */
+ EVP_PKEY_CTX_free(ctx);
+ ctx = EVP_PKEY_CTX_new_from_pkey(NULL, pkey, NULL);
+ if (!ctx)
+     /* Error occurred */
+ if (EVP_PKEY_encrypt_init(ctx) <= 0)
      /* Error */
 
 Generate a key from a set of parameters:

diff --git a/doc/man3/EVP_PKEY_verify_recover.pod b/doc/man3/EVP_PKEY_verify_recover.pod
index 10084d61c1add29a53c335757c9f61a28ad01a1d..52682f2aa5e3a8dbb3585551f71b0048d19badfe 100644 (file)
--- a/doc/man3/EVP_PKEY_verify_recover.pod
+++ b/doc/man3/EVP_PKEY_verify_recover.pod
@@ -22,10 +22,10 @@ EVP_PKEY_verify_recover_init_ex2, EVP_PKEY_verify_recover
 =head1 DESCRIPTION
 
 EVP_PKEY_verify_recover_init() initializes a public key algorithm context
-I<ctx> for signing 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_SIGNATURE> method implicitly, see L<provider(7)/Implicit fetch>
-for more information about implicit fetches.
+I<ctx> for a verify-recover operation 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_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
@@ -35,8 +35,8 @@ EVP_PKEY_verify_recover_init_ex2() is the same as EVP_PKEY_verify_recover_init_e
 but works with an explicitly fetched B<EVP_SIGNATURE> I<algo>.
 A context I<ctx> without a pre-loaded key cannot be used with this function.
 Depending on what algorithm was fetched, certain details revolving around the
-treatment of the input to EVP_PKEY_verify() may be pre-determined, and in that
-case, those details may normally not be changed.
+treatment of the input to EVP_PKEY_verify_recover() may be pre-determined, and
+in that case, those details may normally not be changed.
 See L</NOTES> below for a deeper explanation.
 
 The EVP_PKEY_verify_recover() function recovers signed data
@@ -132,7 +132,7 @@ The EVP_PKEY_verify_recover_init_ex() function was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2013-2024 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2013-2026 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