bpo-44362: ssl: improve deprecation warnings and docs (GH-26646)
Signed-off-by: Christian Heimes <christian@python.org>
(cherry picked from commit e26014f1c47d26d6097ff7a0f25384bfbde714a9)
Co-authored-by: Christian Heimes <christian@python.org>
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index afa3d87..4902d34 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -681,19 +681,23 @@
.. deprecated:: 3.10
+ TLS clients and servers require different default settings for secure
+ communication. The generic TLS protocol constant is deprecated in
+ favor of :data:`PROTOCOL_TLS_CLIENT` and :data:`PROTOCOL_TLS_SERVER`.
+
.. data:: PROTOCOL_TLS_CLIENT
- Auto-negotiate the highest protocol version like :data:`PROTOCOL_TLS`,
- but only support client-side :class:`SSLSocket` connections. The protocol
- enables :data:`CERT_REQUIRED` and :attr:`~SSLContext.check_hostname` by
- default.
+ Auto-negotiate the highest protocol version that both the client and
+ server support, and configure the context client-side connections. The
+ protocol enables :data:`CERT_REQUIRED` and
+ :attr:`~SSLContext.check_hostname` by default.
.. versionadded:: 3.6
.. data:: PROTOCOL_TLS_SERVER
- Auto-negotiate the highest protocol version like :data:`PROTOCOL_TLS`,
- but only support server-side :class:`SSLSocket` connections.
+ Auto-negotiate the highest protocol version that both the client and
+ server support, and configure the context server-side connections.
.. versionadded:: 3.6
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index 5e29f93..530ffce 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -1214,18 +1214,11 @@
:issue:`43789`, and :issue:`43811`.)
Deprecated function and use of deprecated constants now result in
-a :exc:`DeprecationWarning`. The following features have been deprecated
-since Python 3.6, Python 3.7, or OpenSSL 1.1.0:
-:data:`~ssl.OP_NO_SSLv2`, :data:`~ssl.OP_NO_SSLv3`, :data:`~ssl.OP_NO_TLSv1`,
-:data:`~ssl.OP_NO_TLSv1_1`, :data:`~ssl.OP_NO_TLSv1_2`,
-:data:`~ssl.OP_NO_TLSv1_3`, :data:`~ssl.PROTOCOL_SSLv2`,
-:data:`~ssl.PROTOCOL_SSLv3`, :data:`~ssl.PROTOCOL_SSLv23`,
-:data:`~ssl.PROTOCOL_TLSv1`, :data:`~ssl.PROTOCOL_TLSv1_1`,
-:data:`~ssl.PROTOCOL_TLSv1_2`, :data:`~ssl.PROTOCOL_TLS`,
-:func:`~ssl.wrap_socket`, :func:`~ssl.match_hostname`,
-:func:`~ssl.RAND_pseudo_bytes`, :func:`~ssl.RAND_egd`,
-:meth:`ssl.SSLSocket.selected_npn_protocol`,
-:meth:`ssl.SSLContext.set_npn_protocols`.
+a :exc:`DeprecationWarning`. :attr:`ssl.SSLContext.options` has
+:data:`~ssl.OP_NO_SSLv2` and :data:`~ssl.OP_NO_SSLv3` set by default and
+therefore cannot warn about setting the flag again. The
+:ref:`deprecation section <whatsnew310-deprecated>` has a list of deprecated
+features.
(Contributed by Christian Heimes in :issue:`43880`.)
The ssl module now has more secure default settings. Ciphers without forward
@@ -1448,6 +1441,8 @@
readers or writers, just like its equivalent classes in :mod:`gzip` and
:mod:`lzma` have always been. (Contributed by Inada Naoki in :issue:`43785`).
+.. _whatsnew310-deprecated:
+
Deprecated
==========
@@ -1616,6 +1611,30 @@
* ``cgi.log()`` is deprecated and slated for removal in Python 3.12.
(Contributed by Inada Naoki in :issue:`41139`.)
+* The following :mod:`ssl` features have been deprecated since Python 3.6,
+ Python 3.7, or OpenSSL 1.1.0 and will be removed in 3.11:
+
+ * :data:`~ssl.OP_NO_SSLv2`, :data:`~ssl.OP_NO_SSLv3`, :data:`~ssl.OP_NO_TLSv1`,
+ :data:`~ssl.OP_NO_TLSv1_1`, :data:`~ssl.OP_NO_TLSv1_2`, and
+ :data:`~ssl.OP_NO_TLSv1_3` are replaced by
+ :attr:`sslSSLContext.minimum_version` and
+ :attr:`sslSSLContext.maximum_version`.
+
+ * :data:`~ssl.PROTOCOL_SSLv2`, :data:`~ssl.PROTOCOL_SSLv3`,
+ :data:`~ssl.PROTOCOL_SSLv23`, :data:`~ssl.PROTOCOL_TLSv1`,
+ :data:`~ssl.PROTOCOL_TLSv1_1`, :data:`~ssl.PROTOCOL_TLSv1_2`, and
+ :data:`~ssl.PROTOCOL_TLS` are deprecated in favor of
+ :data:`~ssl.PROTOCOL_TLS_CLIENT` and :data:`~ssl.PROTOCOL_TLS_SERVER`
+
+ * :func:`~ssl.wrap_socket` is replaced by :meth:`ssl.SSLContext.wrap_socket`
+
+ * :func:`~ssl.match_hostname`
+
+ * :func:`~ssl.RAND_pseudo_bytes`, :func:`~ssl.RAND_egd`
+
+ * NPN features like :meth:`ssl.SSLSocket.selected_npn_protocol` and
+ :meth:`ssl.SSLContext.set_npn_protocols` are replaced by ALPN.
+
.. _whatsnew310-removed:
Removed