Commit f7112c925c for openssl.org

commit f7112c925c0f3f6239bcab218cb32fa3e52bf621
Author: Mounir IDRASSI <mounir.idrassi@idrix.fr>
Date:   Sat Jul 18 11:11:26 2026 +0900

    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 fff102a769..9ded13de5d 100644
--- 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 5e624e8c61..6b46329793 100644
--- 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 1fb41f99f4..fda95c218e 100644
--- 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 1d5180ef6f..71daed31c0 100644
--- 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 10084d61c1..52682f2aa5 100644
--- 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