Ensure the various legacy key EVP_PKEY getters/setters are deprecated

Most of these were already deprecated but a few have been missed. This
commit corrects that.

Fixes #14303
Fixes #14317

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14319)

1 files changed, 63 insertions, 34 deletions

diff --git a/doc/man3/EVP_PKEY_set1_RSA.pod b/doc/man3/EVP_PKEY_set1_RSA.pod
index d4ab126e0a..32b1e1b8d5 100644
--- a/doc/man3/EVP_PKEY_set1_RSA.pod
+++ b/doc/man3/EVP_PKEY_set1_RSA.pod
@@ -15,6 +15,16 @@ EVP_PKEY_set1_engine, EVP_PKEY_get0_engine - EVP_PKEY assignment functions
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_id(const EVP_PKEY *pkey);
+ int EVP_PKEY_base_id(const EVP_PKEY *pkey);
+ int EVP_PKEY_type(int type);
+
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
+ int EVP_PKEY_set_alias_type(EVP_PKEY *pkey, int type);
+
  int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
  int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
  int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
@@ -40,40 +50,11 @@ EVP_PKEY_set1_engine, EVP_PKEY_get0_engine - EVP_PKEY assignment functions
  int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
  int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
 
- int EVP_PKEY_id(const EVP_PKEY *pkey);
- int EVP_PKEY_base_id(const EVP_PKEY *pkey);
- int EVP_PKEY_type(int type);
-
  ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey);
  int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);
 
-Deprecated since OpenSSL 3.0, can be hidden entirely by defining
-B<OPENSSL_API_COMPAT> with a suitable version value, see
-L<openssl_user_macros(7)>:
-
- int EVP_PKEY_set_alias_type(EVP_PKEY *pkey, int type);
-
 =head1 DESCRIPTION
 
-EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
-EVP_PKEY_set1_EC_KEY() set the key referenced by I<pkey> to I<key>.
-
-EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
-EVP_PKEY_get1_EC_KEY() return the referenced key in I<pkey> or NULL if the
-key is not of the correct type.  The returned key must be freed after use.
-
-EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(),
-EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and
-EVP_PKEY_get0_EC_KEY() return the referenced key in I<pkey> or NULL if the
-key is not of the correct type but the reference count of the returned key
-is B<not> incremented and so must not be freed after use.
-
-EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
-EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and
-EVP_PKEY_assign_SIPHASH() set the referenced key to I<key> however these use
-the supplied I<key> internally and so I<key> will be freed when the parent
-I<pkey> is freed.
-
 EVP_PKEY_base_id() returns the type of I<pkey>. For example
 an RSA key will return B<EVP_PKEY_RSA>.
 
@@ -87,15 +68,56 @@ often seen in practice.
 EVP_PKEY_type() returns the underlying type of the NID I<type>. For example
 EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>.
 
-EVP_PKEY_get0_engine() returns a reference to the ENGINE handling I<pkey>.
+EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
+EVP_PKEY_set1_EC_KEY() set the key referenced by I<pkey> to I<key>. These
+functions are deprecated. Applications should instead use
+L<EVP_PKEY_fromdata(3)>.
+
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
+EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and
+EVP_PKEY_assign_SIPHASH() set the referenced key to I<key> however these use
+the supplied I<key> internally and so I<key> will be freed when the parent
+I<pkey> is freed. These macros are deprecated. Applications should instead read
+an EVP_PKEY directly using the OSSL_DECODER APIs (see
+L<OSSL_DECODER_CTX_new_for_pkey(3)>), or construct an EVP_PKEY from data using
+L<EVP_PKEY_fromdata(3)>.
+
+EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
+EVP_PKEY_get1_EC_KEY() return the referenced key in I<pkey> or NULL if the
+key is not of the correct type.  The returned key must be freed after use.
+These functions are deprecated. Applications should instead use the EVP_PKEY
+directly where possible. If access to the low level key parameters is required
+then applications should use L<EVP_PKEY_get_params(3)> and other similar
+functions. To write an EVP_PKEY out use the OSSL_ENCODER APIs (see
+L<OSSL_ENCODER_CTX_new_for_pkey(3)>).
+
+EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(),
+EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and
+EVP_PKEY_get0_EC_KEY() return the referenced key in I<pkey> or NULL if the
+key is not of the correct type but the reference count of the returned key
+is B<not> incremented and so must not be freed after use. These functions are
+deprecated. Applications should instead use the EVP_PKEY directly where
+possible. If access to the low level key parameters is required then
+applications should use L<EVP_PKEY_get_params(3)> and other similar functions.
+To write an EVP_PKEY out use the OSSL_ENCODER APIs (see
+L<OSSL_ENCODER_CTX_new_for_pkey(3)>).
+
+EVP_PKEY_get0_engine() returns a reference to the ENGINE handling I<pkey>. This
+function is deprecated. Applications should use providers instead of engines
+(see L<provider(7)> for details).
 
 EVP_PKEY_set1_engine() sets the ENGINE handling I<pkey> to I<engine>. It
 must be called after the key algorithm and components are set up.
 If I<engine> does not include an B<EVP_PKEY_METHOD> for I<pkey> an
-error occurs.
+error occurs. This function is deprecated. Applications should use providers
+instead of engines (see L<provider(7)> for details).
 
-EVP_PKEY_set_alias_type() allows modifying a EVP_PKEY to use a
-different set of algorithms than the default.
+EVP_PKEY_set_alias_type() allows modifying an EVP_PKEY to use a
+different set of algorithms than the default. This function is deprecated and
+was previously needed as a workaround to recognise SM2 keys. From OpenSSL 3.0,
+this key type is internally recognised so the workaround is no longer needed.
+Functionality is still retained as it is, but will only work with EVP_PKEYs
+with a legacy internal key.
 
 =head1 WARNINGS
 
@@ -170,7 +192,14 @@ L<EVP_PKEY_new(3)>, L<SM2(7)>
 
 =head1 HISTORY
 
-EVP_PKEY_set_alias_type() was deprecated in OpenSSL 3.0.
+EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
+EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
+EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
+EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
+EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH,
+EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash,
+EVP_PKEY_set_alias_type, EVP_PKEY_set1_engine and EVP_PKEY_get0_engine were
+deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT