Document deprecation of version-specific SSL/TLS methods

[openssl.git] / doc / man3 / SSL_CTX_new.pod

diff --git a/doc/man3/SSL_CTX_new.pod b/doc/man3/SSL_CTX_new.pod
index 29be37b85a65451e58f71edab388f5efc538bdd7..6680496c16aed43673080633b37a8289027cd64a 100644 (file)
--- 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
 
@@ -190,6 +195,11 @@ SSL_CTX_up_ref() returns 1 for success and 0 for failure.
 
 =back
 
+=head1 SEE ALSO
+
+L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
+L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
+
 =head1 HISTORY
 
 Support for SSLv2 and the corresponding SSLv2_method(),
@@ -198,20 +208,15 @@ removed in OpenSSL 1.1.0.
 
 SSLv23_method(), SSLv23_server_method() and SSLv23_client_method()
 were deprecated and the preferred TLS_method(), TLS_server_method()
-and TLS_client_method() functions were introduced in OpenSSL 1.1.0.
+and TLS_client_method() functions were added in OpenSSL 1.1.0.
 
 All version-specific methods were deprecated in OpenSSL 1.1.0.
 
-=head1 SEE ALSO
-
-L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>,
-L<SSL_CTX_set_min_proto_version(3)>, L<ssl(7)>, L<SSL_set_connect_state(3)>
-
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.