X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FEVP_PKEY_CTX_new.pod;h=327d09f348e45044c78846766730eef40ba50711;hp=7df650c12a68940ba46487236c5156d1e23b5691;hb=ccb47dbf47b36da849301aae38c32ed019e75a21;hpb=a07c17ef57da20b7c6d075b303a6506f625dcd4e

diff --git a/doc/man3/EVP_PKEY_CTX_new.pod b/doc/man3/EVP_PKEY_CTX_new.pod
index 7df650c12a..327d09f348 100644
--- a/doc/man3/EVP_PKEY_CTX_new.pod
+++ b/doc/man3/EVP_PKEY_CTX_new.pod
@@ -2,8 +2,8 @@
 
 =head1 NAME
 
-EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_new_provided,
-EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free
+EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_new_from_name,
+EVP_PKEY_CTX_new_from_pkey, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free
 - public key algorithm context functions
 
 =head1 SYNOPSIS
@@ -12,42 +12,87 @@ EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free
 
  EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
  EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
- EVP_PKEY_CTX *EVP_PKEY_CTX_new_provided(const char *name,
-                                         const char *propquery);
+ EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_name(OPENSSL_CTX *libctx,
+                                          const char *name,
+                                          const char *propquery);
+ EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_pkey(OPENSSL_CTX *libctx,
+                                          EVP_PKEY *pkey);
  EVP_PKEY_CTX *EVP_PKEY_CTX_dup(const EVP_PKEY_CTX *ctx);
  void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
 
 =head1 DESCRIPTION
 
 The EVP_PKEY_CTX_new() function allocates public key algorithm context using
-the algorithm specified in B<pkey> and ENGINE B<e>.
+the I<pkey> key type and ENGINE I<e>.
 
 The EVP_PKEY_CTX_new_id() function allocates public key algorithm context
-using the algorithm specified by B<id> and ENGINE B<e>.
-
-The EVP_PKEY_CTX_new_provided() function allocates a public key
-algorithm context using the algorithm specified by I<name> and the
-property query I<propquery>.  The strings aren't duplicated, so they
-must remain unchanged for the lifetime of the returned B<EVP_PKEY_CTX>
-or of any of its duplicates.
-
-EVP_PKEY_CTX_new_id() and EVP_PKEY_CTX_new_provided() are normally
+using the key type specified by I<id> and ENGINE I<e>.
+
+The EVP_PKEY_CTX_new_from_name() function allocates a public key algorithm
+context using the library context I<libctx> (see L<OPENSSL_CTX(3)>), the
+key type specified by I<name> and the property query I<propquery>.  None
+of the arguments are duplicated, so they  must remain unchanged for the
+lifetime of the returned B<EVP_PKEY_CTX> or of any of its duplicates.  Read
+further about the possible names in L</NOTES> below.
+
+The EVP_PKEY_CTX_new_from_pkey() function allocates a public key algorithm
+context using the library context I<libctx> (see L<OPENSSL_CTX(3)>) and the
+algorithm specified by I<pkey> and the property query I<propquery>. None of the
+arguments are duplicated, so they must remain unchanged for the lifetime of the
+returned B<EVP_PKEY_CTX> or any of its duplicates.
+
+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.
 
-EVP_PKEY_CTX_dup() duplicates the context B<ctx>.
+EVP_PKEY_CTX_dup() duplicates the context I<ctx>.
 
-EVP_PKEY_CTX_free() frees up the context B<ctx>.
-If B<ctx> is NULL, nothing is done.
+EVP_PKEY_CTX_free() frees up the context I<ctx>.
+If I<ctx> is NULL, nothing is done.
 
 =head1 NOTES
 
+=head2 On B<EVP_PKEY_CTX>
+
 The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used
 by the OpenSSL high level public key API. Contexts B<MUST NOT> be shared between
 threads: that is it is not permissible to use the same context simultaneously
 in two threads.
 
+=head2 On Key Types
+
+We mention "key type" in this manual, which is the same
+as "algorithm" in most cases, allowing either term to be used
+interchangeably.  There are algorithms where the I<key type> and the
+I<algorithm> of the operations that use the keys are not the same,
+such as EC keys being used for ECDSA and ECDH operations.
+
+Key types are given in two different manners:
+
+=over 4
+
+=item Legacy NID or EVP_PKEY type
+
+This is the I<id> used with EVP_PKEY_CTX_new_id().
+
+These are B<EVP_PKEY_RSA>, B<EVP_PKEY_RSA_PSS>, B<EVP_PKEY_DSA>,
+B<EVP_PKEY_DH>, B<EVP_PKEY_EC>, B<EVP_PKEY_SM2>, B<EVP_PKEY_X25519>,
+B<EVP_PKEY_X448>, and are used by legacy methods.
+
+=item Name strings
+
+This is the I<name> used with EVP_PKEY_CTX_new_from_name().
+
+These are names like "RSA", "DSA", and what's available depends on what
+providers are currently accessible.
+
+The OpenSSL providers offer a set of key types available this way, please
+see L<OSSL_PROVIDER-FIPS(7)> and L<OSSL_PROVIDER-default(7)> and related
+documentation for more information.
+
+=back
+
 =head1 RETURN VALUES
 
 EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() returns either
@@ -61,7 +106,11 @@ L<EVP_PKEY_new(3)>
 
 =head1 HISTORY
 
-These functions were added in OpenSSL 1.0.0.
+The EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() and
+EVP_PKEY_CTX_free() functions were added in OpenSSL 1.0.0.
+
+The EVP_PKEY_CTX_new_from_name() and EVP_PKEY_CTX_new_from_pkey() functions were
+added in OpenSSL 3.0.
 
 =head1 COPYRIGHT