Document deprecation of version-specific SSL/TLS methods

In commit 2b8fa1d56cd3 the version-specific SSL/TLS methods were
deprecated. This patch improves the documentation of that change
by stating the deprecation more prominently in the manual page
and explaining the reason for the deprecation.

Fixes #8989

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9001)

(cherry picked from commit f308fa2573b0320236cd2c2d73db37c49e3eb779)

1 files changed, 12 insertions, 7 deletions

diff --git a/doc/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod
index df25a6f657..a6c036c365 100644
--- a/doc/man3/SSL_CTX_new.pod
+++ b/doc/man3/SSL_CTX_new.pod
@@ -94,28 +94,31 @@ The actual protocol version used will be negotiated to the highest version
 mutually supported by the client and the server.
 The supported protocols are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3.
 Applications should use these methods, and avoid the version-specific
-methods described below.
+methods described below, which are deprecated.
 
 =item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method()
 
-Use of these functions is deprecated. They have been replaced with the above
-TLS_method(), TLS_server_method() and TLS_client_method() respectively. New
-code should use those functions instead.
+These functions do not exist anymore, they have been renamed to
+TLS_method(), TLS_server_method() and TLS_client_method() respectively.
+Currently, the old function calls are renamed to the corresponding new
+ones by preprocessor macros, to ensure that existing code which uses the
+old function names still compiles. However, using the old function names
+is deprecated and new code should call the new functions instead.
 
 =item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method()
 
 A TLS/SSL connection established with these methods will only understand the
-TLSv1.2 protocol.
+TLSv1.2 protocol. These methods are deprecated.
 
 =item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method()
 
 A TLS/SSL connection established with these methods will only understand the
-TLSv1.1 protocol.
+TLSv1.1 protocol.  These methods are deprecated.
 
 =item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method()
 
 A TLS/SSL connection established with these methods will only understand the
-TLSv1 protocol.
+TLSv1 protocol. These methods are deprecated.
 
 =item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method()
 
@@ -131,10 +134,12 @@ Currently supported protocols are DTLS 1.0 and DTLS 1.2.
 =item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method()
 
 These are the version-specific methods for DTLSv1.2.
+These methods are deprecated.
 
 =item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method()
 
 These are the version-specific methods for DTLSv1.
+These methods are deprecated.
 
 =back