Rename OSSL_ENCODER_CTX_new_by_EVP_PKEY and OSSL_DECODER_CTX_new_by_EVP_PKEY

Additional renames done in encoder and decoder implementation
to follow the style.

Fixes #13622

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14155)

5 files changed, 28 insertions, 43 deletions

diff --git a/doc/man3/OSSL_DECODER.pod b/doc/man3/OSSL_DECODER.pod
index f87e693e09..9bc2a035ae 100644
--- a/doc/man3/OSSL_DECODER.pod
+++ b/doc/man3/OSSL_DECODER.pod
@@ -124,7 +124,7 @@ Text, because pod2xxx doesn't like empty sections
 =head1 SEE ALSO
 
 L<provider(7)>, L<OSSL_DECODER_CTX(3)>, L<OSSL_DECODER_from_bio(3)>,
-L<OSSL_DECODER_CTX_new_by_EVP_PKEY(3)>, L<OSSL_LIB_CTX(3)>
+L<OSSL_DECODER_CTX_new_for_pkey(3)>, L<OSSL_LIB_CTX(3)>
 
 =head1 HISTORY
 
diff --git a/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod
index 38425ae7dc..acb28f8306 100644
--- a/doc/man3/OSSL_DECODER_CTX_new_by_EVP_PKEY.pod
+++ b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-OSSL_DECODER_CTX_new_by_EVP_PKEY,
+OSSL_DECODER_CTX_new_for_pkey,
 OSSL_DECODER_CTX_set_passphrase,
 OSSL_DECODER_CTX_set_pem_password_cb,
 OSSL_DECODER_CTX_set_passphrase_ui,
@@ -14,11 +14,11 @@ OSSL_DECODER_CTX_set_passphrase_cb
  #include <openssl/decoder.h>
 
  OSSL_DECODER_CTX *
- OSSL_DECODER_CTX_new_by_EVP_PKEY(EVP_PKEY **pkey,
-                                  const char *input_type,
-                                  const char *input_struct,
-                                  const char *keytype, int selection,
-                                  OSSL_LIB_CTX *libctx, const char *propquery);
+ OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey,
+                               const char *input_type,
+                               const char *input_struct,
+                               const char *keytype, int selection,
+                               OSSL_LIB_CTX *libctx, const char *propquery);
 
  int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
                                      const unsigned char *kstr,
@@ -35,14 +35,17 @@ OSSL_DECODER_CTX_set_passphrase_cb
 
 =head1 DESCRIPTION
 
-OSSL_DECODER_CTX_new_by_EVP_PKEY() is a utility function that creates a
+OSSL_DECODER_CTX_new_for_pkey() is a utility function that creates a
 B<OSSL_DECODER_CTX>, finds all applicable decoder implementations and sets
 them up, so all the caller has to do next is call functions like
 L<OSSL_DECODER_from_bio(3)>.  The caller may use the optional I<input_type>,
 I<input_struct>, I<keytype> and I<selection> to specify what the input is
-expected to contain.
+expected to contain.  The I<pkey> must reference an B<EVP_PKEY *> variable
+that will be set to the newly created B<EVP_PKEY> on succesfull decoding.
+The referenced variable must be initialized to NULL before calling the
+function.
 
-Internally OSSL_DECODER_CTX_new_by_EVP_PKEY() searches for all available
+Internally OSSL_DECODER_CTX_new_for_pkey() searches for all available
 L<EVP_KEYMGMT(3)> implementations, and then builds a list of all potential
 decoder implementations that may be able to process the encoded input into
 data suitable for B<EVP_PKEY>s.  All these implementations are implicitly
@@ -62,7 +65,7 @@ NULL and zero are valid and signify that the decoder implementations will
 find out the keytype and key contents on their own from the input they get.
 
 If no suitable decoder implementation is found,
-OSSL_DECODER_CTX_new_by_EVP_PKEY() still creates a B<OSSL_DECODER_CTX>, but
+OSSL_DECODER_CTX_new_for_pkey() still creates a B<OSSL_DECODER_CTX>, but
 with no associated decoder (L<OSSL_DECODER_CTX_get_num_decoders(3)> returns
 zero).  This helps the caller to distinguish between an error when creating
 the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
@@ -107,7 +110,7 @@ encoded according to PKCS#1.
 
 =head1 RETURN VALUES
 
-OSSL_DECODER_CTX_new_by_EVP_PKEY() returns a pointer to a
+OSSL_DECODER_CTX_new_for_pkey() returns a pointer to a
 B<OSSL_DECODER_CTX>, or NULL if it couldn't be created.
 
 OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(),
@@ -115,15 +118,6 @@ OSSL_DECODER_CTX_set_passphrase_ui() and
 OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
 failure.
 
-=head1 NOTES
-
-Parts of the function names are made to match already existing OpenSSL
-names.
-
-B<EVP_PKEY> in OSSL_DECODER_CTX_new_by_EVP_PKEY() matches the type name,
-thus making for the naming pattern B<OSSL_DECODER_CTX_new_by_I<TYPE>>() when
-new types are handled.
-
 =head1 SEE ALSO
 
 L<provider(7)>, L<OSSL_DECODER(3)>, L<OSSL_DECODER_CTX(3)>
diff --git a/doc/man3/OSSL_ENCODER.pod b/doc/man3/OSSL_ENCODER.pod
index da1aa475dc..6952d850f4 100644
--- a/doc/man3/OSSL_ENCODER.pod
+++ b/doc/man3/OSSL_ENCODER.pod
@@ -117,7 +117,7 @@ Any other API that uses keys will typically do this.
 =head1 SEE ALSO
 
 L<provider(7)>, L<OSSL_ENCODER_CTX(3)>, L<OSSL_ENCODER_to_bio(3)>,
-L<OSSL_ENCODER_CTX_new_by_EVP_PKEY(3)>, L<OSSL_LIB_CTX(3)>
+L<OSSL_ENCODER_CTX_new_for_pkey(3)>, L<OSSL_LIB_CTX(3)>
 
 =head1 HISTORY
 
diff --git a/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod
index 403d7a00be..dec48804c6 100644
--- a/doc/man3/OSSL_ENCODER_CTX_new_by_EVP_PKEY.pod
+++ b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-OSSL_ENCODER_CTX_new_by_EVP_PKEY,
+OSSL_ENCODER_CTX_new_for_pkey,
 OSSL_ENCODER_CTX_set_cipher,
 OSSL_ENCODER_CTX_set_passphrase,
 OSSL_ENCODER_CTX_set_pem_password_cb,
@@ -15,10 +15,10 @@ OSSL_ENCODER_CTX_set_passphrase_ui
  #include <openssl/encoder.h>
 
  OSSL_ENCODER_CTX *
- OSSL_ENCODER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, int selection,
-                                  const char *output_type,
-                                  const char *output_structure,
-                                  const char *propquery);
+ OSSL_ENCODER_CTX_new_for_pkey(const EVP_PKEY *pkey, int selection,
+                               const char *output_type,
+                               const char *output_structure,
+                               const char *propquery);
 
  int OSSL_ENCODER_CTX_set_cipher(OSSL_ENCODER_CTX *ctx,
                                  const char *cipher_name,
@@ -37,7 +37,7 @@ OSSL_ENCODER_CTX_set_passphrase_ui
 
 =head1 DESCRIPTION
 
-OSSL_ENCODER_CTX_new_by_EVP_PKEY() is a utility function that creates a
+OSSL_ENCODER_CTX_new_for_pkey() is a utility function that creates a
 B<OSSL_ENCODER_CTX>, finds all applicable encoder implementations and sets
 them up, so almost all the caller has to do next is call functions like
 L<OSSL_ENCODER_to_bio(3)>.  I<output_type> determines the final output
@@ -46,7 +46,7 @@ should be included in the output.  I<output_type> is further discussed in
 L</Output types> below, and I<selection> is further described in
 L</Selections>.
 
-Internally, OSSL_ENCODER_CTX_new_by_EVP_PKEY() uses the names from the
+Internally, OSSL_ENCODER_CTX_new_for_pkey() uses the names from the
 L<EVP_KEYMGMT(3)> implementation associated with I<pkey> to build a list of
 applicable encoder implementations that are used to process the I<pkey> into
 the encoding named by I<output_type>, with the outermost structure named by
@@ -54,7 +54,7 @@ I<output_structure> if that's relevant.  All these implementations are
 implicitly fetched, with I<propquery> for finer selection.
 
 If no suitable encoder implementation is found,
-OSSL_ENCODER_CTX_new_by_EVP_PKEY() still creates a B<OSSL_ENCODER_CTX>, but
+OSSL_ENCODER_CTX_new_for_pkey() still creates a B<OSSL_ENCODER_CTX>, but
 with no associated encoder (L<OSSL_ENCODER_CTX_get_num_encoders(3)> returns
 zero).  This helps the caller to distinguish between an error when creating
 the B<OSSL_ENCODER_CTX> and missing encoder implementation, and allows it to
@@ -146,23 +146,14 @@ usually include the public key.
 
 =head1 RETURN VALUES
 
-OSSL_ENCODER_CTX_new_by_EVP_PKEY() returns a pointer to a
-B<OSSL_ENCODER_CTX>, or NULL if it couldn't be created.
+OSSL_ENCODER_CTX_new_for_pkey() returns a pointer to an B<OSSL_ENCODER_CTX>,
+or NULL if it couldn't be created.
 
 OSSL_ENCODER_CTX_set_cipher(), OSSL_ENCODER_CTX_set_passphrase(),
 OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui()
 and OSSL_ENCODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on
 failure.
 
-=head1 NOTES
-
-Parts of the function names are made to match already existing OpenSSL
-names.
-
-B<EVP_PKEY> in OSSL_ENCODER_CTX_new_by_EVP_PKEY() matches the type name,
-thus making for the naming pattern B<OSSL_ENCODER_CTX_new_by_I<TYPE>>() when
-new types are handled.
-
 =head1 SEE ALSO
 
 L<provider(7)>, L<OSSL_ENCODER(3)>, L<OSSL_ENCODER_CTX(3)>
diff --git a/doc/man3/d2i_RSAPrivateKey.pod b/doc/man3/d2i_RSAPrivateKey.pod
index 41e8e3cb6c..475c53ca1d 100644
--- a/doc/man3/d2i_RSAPrivateKey.pod
+++ b/doc/man3/d2i_RSAPrivateKey.pod
@@ -222,8 +222,8 @@ The following sample code does the rest of the work:
  unsigned char *p = buffer;     /* |buffer| is supplied by the caller */
  size_t len = buffer_size;      /* assumed be the size of |buffer| */
  OSSL_ENCODER_CTX *ctx =
-     OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, "DER", structure,
-                                      NULL, NULL);
+     OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure,
+                                   NULL, NULL);
  if (ctx == NULL) {
      /* fatal error handling */
  }