Add documentation of the old names kept as alias macros

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15405)

CHANGES.md

@@ -104,6 +104,13 @@ breaking changes, and mappings for the large list of deprecated functions.
 
    *Shane Lontis*
 
+ * Many functions in the EVP_ namespace that are getters of values from
+   implementations or contexts were renamed to include get or get0 in their
+   names. Old names are provided as macro aliases for compatibility and
+   are not deprecated.
+
+   *Tomáš Mráz*
+
  * The EVP_PKEY_CTRL_PKCS7_ENCRYPT, EVP_PKEY_CTRL_PKCS7_DECRYPT,
    EVP_PKEY_CTRL_PKCS7_SIGN, EVP_PKEY_CTRL_CMS_ENCRYPT,
    EVP_PKEY_CTRL_CMS_DECRYPT, and EVP_PKEY_CTRL_CMS_SIGN control operations

doc/man3/EVP_DigestInit.pod

@@ -13,16 +13,18 @@ EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
 EVP_Q_digest, EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit,
 EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal,
 EVP_MD_is_a, EVP_MD_get0_name, EVP_MD_get0_description, EVP_MD_get_number,
-EVP_MD_names_do_all, EVP_MD_get0_provider,
+EVP_MD_names_do_all, EVP_MD_get0_provider, EVP_MD_get_type,
-EVP_MD_get_type, EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags,
+EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags,
-EVP_MD_CTX_get0_name,
+EVP_MD_CTX_get0_name, EVP_MD_CTX_md, EVP_MD_CTX_get0_md, EVP_MD_CTX_get1_md,
-EVP_MD_CTX_md, EVP_MD_CTX_get0_md, EVP_MD_CTX_get1_md,
 EVP_MD_CTX_get_type, EVP_MD_CTX_get_size, EVP_MD_CTX_get_block_size,
 EVP_MD_CTX_get0_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn,
 EVP_md_null,
 EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj,
 EVP_MD_CTX_get_pkey_ctx, EVP_MD_CTX_set_pkey_ctx,
-EVP_MD_do_all_provided
+EVP_MD_do_all_provided,
+EVP_MD_type, EVP_MD_nid, EVP_MD_name, EVP_MD_pkey_type, EVP_MD_size,
+EVP_MD_block_size, EVP_MD_flags, EVP_MD_CTX_size, EVP_MD_CTX_block_size,
+EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data
 - EVP digest routines
 
 =head1 SYNOPSIS
@@ -103,6 +105,19 @@ EVP_MD_do_all_provided
                              void (*fn)(EVP_MD *mac, void *arg),
                              void *arg);
 
+ #define EVP_MD_type EVP_MD_get_type
+ #define EVP_MD_nid EVP_MD_get_type
+ #define EVP_MD_name EVP_MD_get0_name
+ #define EVP_MD_pkey_type EVP_MD_get_pkey_type
+ #define EVP_MD_size EVP_MD_get_size
+ #define EVP_MD_block_size EVP_MD_get_block_size
+ #define EVP_MD_flags EVP_MD_get_flags
+ #define EVP_MD_CTX_size EVP_MD_CTX_get_size
+ #define EVP_MD_CTX_block_size EVP_MD_CTX_get_block_size
+ #define EVP_MD_CTX_type EVP_MD_CTX_get_type
+ #define EVP_MD_CTX_pkey_ctx EVP_MD_CTX_get_pkey_ctx
+ #define EVP_MD_CTX_md_data EVP_MD_CTX_get0_md_data
+
 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)>:
@@ -718,6 +733,13 @@ EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(),
 EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() and
 EVP_MD_CTX_gettable_params() functions were added in OpenSSL 3.0.
 
+The EVP_MD_type(), EVP_MD_nid(), EVP_MD_name(), EVP_MD_pkey_type(),
+EVP_MD_size(), EVP_MD_block_size(), EVP_MD_flags(), EVP_MD_CTX_size(),
+EVP_MD_CTX_block_size(), EVP_MD_CTX_type(), and EVP_MD_CTX_md_data()
+functions were renamed to include C<get> or C<get0> in their names in
+OpenSSL 3.0, respectively. The old names are kept as non-deprecated
+alias macros.
+
 The EVP_MD_CTX_md() function was deprecated in OpenSSL 3.0; use
 EVP_MD_CTX_get0_md() instead.
 EVP_MD_CTX_update_fn() and EVP_MD_CTX_set_update_fn() were deprecated

doc/man3/EVP_EncryptInit.pod

@@ -77,7 +77,24 @@ EVP_CIPHER_param_to_asn1,
 EVP_CIPHER_asn1_to_param,
 EVP_CIPHER_CTX_set_padding,
 EVP_enc_null,
-EVP_CIPHER_do_all_provided
+EVP_CIPHER_do_all_provided,
+EVP_CIPHER_nid,
+EVP_CIPHER_name,
+EVP_CIPHER_block_size,
+EVP_CIPHER_key_length,
+EVP_CIPHER_iv_length,
+EVP_CIPHER_flags,
+EVP_CIPHER_mode,
+EVP_CIPHER_type,
+EVP_CIPHER_CTX_encrypting,
+EVP_CIPHER_CTX_nid,
+EVP_CIPHER_CTX_block_size,
+EVP_CIPHER_CTX_key_length,
+EVP_CIPHER_CTX_iv_length,
+EVP_CIPHER_CTX_tag_length,
+EVP_CIPHER_CTX_num,
+EVP_CIPHER_CTX_type,
+EVP_CIPHER_CTX_mode
 - EVP cipher routines
 
 =head1 SYNOPSIS
@@ -196,6 +213,24 @@ EVP_CIPHER_do_all_provided
                                  void (*fn)(EVP_CIPHER *cipher, void *arg),
                                  void *arg);
 
+ #define EVP_CIPHER_nid EVP_CIPHER_get_nid
+ #define EVP_CIPHER_name EVP_CIPHER_get0_name
+ #define EVP_CIPHER_block_size EVP_CIPHER_get_block_size
+ #define EVP_CIPHER_key_length EVP_CIPHER_get_key_length
+ #define EVP_CIPHER_iv_length EVP_CIPHER_get_iv_length
+ #define EVP_CIPHER_flags EVP_CIPHER_get_flags
+ #define EVP_CIPHER_mode EVP_CIPHER_get_mode
+ #define EVP_CIPHER_type EVP_CIPHER_get_type
+ #define EVP_CIPHER_CTX_encrypting EVP_CIPHER_CTX_is_encrypting
+ #define EVP_CIPHER_CTX_nid EVP_CIPHER_CTX_get_nid
+ #define EVP_CIPHER_CTX_block_size EVP_CIPHER_CTX_get_block_size
+ #define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length
+ #define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length
+ #define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length
+ #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num
+ #define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type
+ #define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode
+
 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)>:
@@ -1615,6 +1650,20 @@ EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(),
 EVP_CIPHER_CTX_settable_params() and EVP_CIPHER_CTX_gettable_params()
 functions were added in 3.0.
 
+The EVP_CIPHER_nid(), EVP_CIPHER_name(), EVP_CIPHER_block_size(),
+EVP_CIPHER_key_length(), EVP_CIPHER_iv_length(), EVP_CIPHER_flags(),
+EVP_CIPHER_mode(), EVP_CIPHER_type(), EVP_CIPHER_CTX_nid(),
+EVP_CIPHER_CTX_block_size(), EVP_CIPHER_CTX_key_length(),
+EVP_CIPHER_CTX_iv_length(), EVP_CIPHER_CTX_tag_length(),
+EVP_CIPHER_CTX_num(), EVP_CIPHER_CTX_type(), and EVP_CIPHER_CTX_mode()
+functions were renamed to include C<get> or C<get0> in their names in
+OpenSSL 3.0, respectively. The old names are kept as non-deprecated
+alias macros.
+
+The EVP_CIPHER_CTX_encrypting() function was renamed to
+EVP_CIPHER_CTX_is_encrypting() in OpenSSL 3.0. The old name is kept as
+non-deprecated alias macro.
+
 The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.0.
 
 =head1 COPYRIGHT

doc/man3/EVP_PKEY_get_size.pod

@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-EVP_PKEY_get_size, EVP_PKEY_get_bits, EVP_PKEY_get_security_bits
+EVP_PKEY_get_size, EVP_PKEY_get_bits, EVP_PKEY_get_security_bits,
+EVP_PKEY_bits, EVP_PKEY_security_bits, EVP_PKEY_size
 - EVP_PKEY information functions
 
 =head1 SYNOPSIS
@@ -13,6 +14,10 @@ EVP_PKEY_get_size, EVP_PKEY_get_bits, EVP_PKEY_get_security_bits
  int EVP_PKEY_get_bits(const EVP_PKEY *pkey);
  int EVP_PKEY_get_security_bits(const EVP_PKEY *pkey);
 
+ #define EVP_PKEY_bits EVP_PKEY_get_bits
+ #define EVP_PKEY_security_bits EVP_PKEY_get_security_bits
+ #define EVP_PKEY_size EVP_PKEY_get_size
+
 =head1 DESCRIPTION
 
 EVP_PKEY_get_size() returns the maximum suitable size for the output
@@ -68,6 +73,12 @@ L<EVP_PKEY_encrypt(3)>,
 L<EVP_PKEY_decrypt(3)>,
 L<EVP_PKEY_derive(3)>
 
+=head1 HISTORY
+
+The EVP_PKEY_bits(), EVP_PKEY_security_bits(), and EVP_PKEY_size() functions
+were renamed to include C<get> in their names in OpenSSL 3.0, respectively.
+The old names are kept as non-deprecated alias macros.
+
 =head1 COPYRIGHT
 
 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.

doc/man3/EVP_PKEY_set1_RSA.pod

@@ -9,7 +9,8 @@ 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_get0, EVP_PKEY_type, EVP_PKEY_get_id, EVP_PKEY_get_base_id,
-EVP_PKEY_set1_engine, EVP_PKEY_get0_engine -
+EVP_PKEY_set1_engine, EVP_PKEY_get0_engine,
+EVP_PKEY_id, EVP_PKEY_base_id -
 EVP_PKEY assignment functions
 
 =head1 SYNOPSIS
@@ -20,6 +21,9 @@ EVP_PKEY assignment functions
  int EVP_PKEY_get_base_id(const EVP_PKEY *pkey);
  int EVP_PKEY_type(int type);
 
+ #define EVP_PKEY_id EVP_PKEY_get_id
+ #define EVP_PKEY_base_id EVP_PKEY_get_base_id
+
 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)>:
@@ -198,6 +202,10 @@ L<EVP_PKEY_new(3)>, L<SM2(7)>
 
 =head1 HISTORY
 
+The EVP_PKEY_id() and EVP_PKEY_base_id() functions were renamed to
+include C<get> in their names in OpenSSL 3.0, respectively. The old names
+are kept as non-deprecated alias macros.
+
 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,

util/other.syms

@@ -626,3 +626,37 @@ OSSL_TRACE9                             define
 TS_VERIFY_CTS_set_certs                 define deprecated 3.0.0
 EVP_PKEY_get1_tls_encodedpoint          define deprecated 3.0.0
 EVP_PKEY_set1_tls_encodedpoint          define deprecated 3.0.0
+EVP_MD_type                             define
+EVP_MD_nid                              define
+EVP_MD_name                             define
+EVP_MD_pkey_type                        define
+EVP_MD_size                             define
+EVP_MD_block_size                       define
+EVP_MD_flags                            define
+EVP_MD_CTX_size                         define
+EVP_MD_CTX_block_size                   define
+EVP_MD_CTX_type                         define
+EVP_MD_CTX_pkey_ctx                     define
+EVP_MD_CTX_md_data                      define
+EVP_CIPHER_nid                          define
+EVP_CIPHER_name                         define
+EVP_CIPHER_block_size                   define
+EVP_CIPHER_key_length                   define
+EVP_CIPHER_iv_length                    define
+EVP_CIPHER_flags                        define
+EVP_CIPHER_mode                         define
+EVP_CIPHER_type                         define
+EVP_CIPHER_CTX_encrypting               define
+EVP_CIPHER_CTX_nid                      define
+EVP_CIPHER_CTX_block_size               define
+EVP_CIPHER_CTX_key_length               define
+EVP_CIPHER_CTX_iv_length                define
+EVP_CIPHER_CTX_tag_length               define
+EVP_CIPHER_CTX_num                      define
+EVP_CIPHER_CTX_type                     define
+EVP_CIPHER_CTX_mode                     define
+EVP_PKEY_bits                           define
+EVP_PKEY_security_bits                  define
+EVP_PKEY_size                           define
+EVP_PKEY_id                             define
+EVP_PKEY_base_id                        define