bpo-43880: Show DeprecationWarnings for deprecated ssl module features (GH-25455)
* ssl.OP_NO_SSLv2
* ssl.OP_NO_SSLv3
* ssl.OP_NO_TLSv1
* ssl.OP_NO_TLSv1_1
* ssl.OP_NO_TLSv1_2
* ssl.OP_NO_TLSv1_3
* ssl.PROTOCOL_SSLv2
* ssl.PROTOCOL_SSLv3
* ssl.PROTOCOL_SSLv23 (alias for PROTOCOL_TLS)
* ssl.PROTOCOL_TLS
* ssl.PROTOCOL_TLSv1
* ssl.PROTOCOL_TLSv1_1
* ssl.PROTOCOL_TLSv1_2
* ssl.TLSVersion.SSLv3
* ssl.TLSVersion.TLSv1
* ssl.TLSVersion.TLSv1_1
* ssl.wrap_socket()
* ssl.RAND_pseudo_bytes()
* ssl.RAND_egd() (already removed since it's not supported by OpenSSL 1.1.1)
* ssl.SSLContext() without a protocol argument
* ssl.match_hostname()
* hashlib.pbkdf2_hmac() (pure Python implementation, fast OpenSSL
function will stay)
Signed-off-by: Christian Heimes <christian@python.org>
diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index 48c0bab..d77a2e5 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -266,6 +266,12 @@
Python implementation uses an inline version of :mod:`hmac`. It is about
three times slower and doesn't release the GIL.
+ .. deprecated:: 3.10
+
+ Slow Python implementation of *pbkdf2_hmac* is deprecated. In the
+ future the function will only be available when Python is compiled
+ with OpenSSL.
+
.. function:: scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)
The function provides scrypt password-based key derivation function as
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 8bac365..c954d9c 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -25,8 +25,8 @@
Some behavior may be platform dependent, since calls are made to the
operating system socket APIs. The installed version of OpenSSL may also
- cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with
- openssl version 1.0.1.
+ cause variations in behavior. For example, TLSv1.3 with OpenSSL version
+ 1.1.1.
.. warning::
Don't use this module without reading the :ref:`ssl-security`. Doing so
@@ -63,6 +63,8 @@
:pep:`644` has been implemented. The ssl module requires OpenSSL 1.1.1
or newer.
+ Use of deprecated constants and functions result in deprecation warnings.
+
Functions, Constants, and Exceptions
------------------------------------
@@ -136,8 +138,9 @@
:const:`None`, this function can choose to trust the system's default
CA certificates instead.
- The settings are: :data:`PROTOCOL_TLS`, :data:`OP_NO_SSLv2`, and
- :data:`OP_NO_SSLv3` with high encryption cipher suites without RC4 and
+ The settings are: :data:`PROTOCOL_TLS_CLIENT` or
+ :data:`PROTOCOL_TLS_SERVER`, :data:`OP_NO_SSLv2`, and :data:`OP_NO_SSLv3`
+ with high encryption cipher suites without RC4 and
without unauthenticated cipher suites. Passing :data:`~Purpose.SERVER_AUTH`
as *purpose* sets :data:`~SSLContext.verify_mode` to :data:`CERT_REQUIRED`
and either loads CA certificates (when at least one of *cafile*, *capath* or
@@ -185,6 +188,12 @@
Support for key logging to :envvar:`SSLKEYLOGFILE` was added.
+ .. versionchanged:: 3.10
+
+ The context now uses :data:`PROTOCOL_TLS_CLIENT` or
+ :data:`PROTOCOL_TLS_SERVER` protocol instead of generic
+ :data:`PROTOCOL_TLS`.
+
Exceptions
^^^^^^^^^^
@@ -417,7 +426,7 @@
previously. Return an integer (no fractions of a second in the
input format)
-.. function:: get_server_certificate(addr, ssl_version=PROTOCOL_TLS, ca_certs=None)
+.. function:: get_server_certificate(addr, ssl_version=PROTOCOL_TLS_CLIENT, ca_certs=None)
Given the address ``addr`` of an SSL-protected server, as a (*hostname*,
*port-number*) pair, fetches the server's certificate, and returns it as a
@@ -654,6 +663,8 @@
.. versionadded:: 3.6
+ .. deprecated:: 3.10
+
.. data:: PROTOCOL_TLS_CLIENT
Auto-negotiate the highest protocol version like :data:`PROTOCOL_TLS`,
@@ -707,7 +718,10 @@
.. deprecated:: 3.6
OpenSSL has deprecated all version specific protocols. Use the default
- protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead.
+ protocol :data:`PROTOCOL_TLS_SERVER` or :data:`PROTOCOL_TLS_CLIENT`
+ with :attr:`SSLContext.minimum_version` and
+ :attr:`SSLContext.maximum_version` instead.
+
.. data:: PROTOCOL_TLSv1
@@ -715,8 +729,7 @@
.. deprecated:: 3.6
- OpenSSL has deprecated all version specific protocols. Use the default
- protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead.
+ OpenSSL has deprecated all version specific protocols.
.. data:: PROTOCOL_TLSv1_1
@@ -727,8 +740,7 @@
.. deprecated:: 3.6
- OpenSSL has deprecated all version specific protocols. Use the default
- protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead.
+ OpenSSL has deprecated all version specific protocols.
.. data:: PROTOCOL_TLSv1_2
@@ -739,8 +751,7 @@
.. deprecated:: 3.6
- OpenSSL has deprecated all version specific protocols. Use the default
- protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead.
+ OpenSSL has deprecated all version specific protocols.
.. data:: OP_ALL
@@ -762,7 +773,6 @@
SSLv2 is deprecated
-
.. data:: OP_NO_SSLv3
Prevents an SSLv3 connection. This option is only applicable in
@@ -1068,6 +1078,11 @@
SSL 3.0 to TLS 1.3.
+ .. deprecated:: 3.10
+
+ All :class:`TLSVersion` members except :attr:`TLSVersion.TLSv1_2` and
+ :attr:`TLSVersion.TLSv1_3` are deprecated.
+
SSL Sockets
-----------
@@ -1423,7 +1438,7 @@
It also manages a cache of SSL sessions for server-side sockets, in order
to speed up repeated connections from the same clients.
-.. class:: SSLContext(protocol=PROTOCOL_TLS)
+.. class:: SSLContext(protocol=None)
Create a new SSL context. You may pass *protocol* which must be one
of the ``PROTOCOL_*`` constants defined in this module. The parameter
@@ -1472,6 +1487,12 @@
ciphers, no ``NULL`` ciphers and no ``MD5`` ciphers (except for
:data:`PROTOCOL_SSLv2`).
+ .. deprecated:: 3.10
+
+ :class:`SSLContext` without protocol argument is deprecated. The
+ context class will either require :data:`PROTOCOL_TLS_CLIENT` or
+ :data:`PROTOCOL_TLS_SERVER` protocol in the future.
+
:class:`SSLContext` objects have the following methods and attributes:
@@ -1934,7 +1955,7 @@
.. attribute:: SSLContext.num_tickets
Control the number of TLS 1.3 session tickets of a
- :attr:`TLS_PROTOCOL_SERVER` context. The setting has no impact on TLS
+ :attr:`PROTOCOL_TLS_SERVER` context. The setting has no impact on TLS
1.0 to 1.2 connections.
.. versionadded:: 3.8
@@ -1951,6 +1972,12 @@
>>> ssl.create_default_context().options # doctest: +SKIP
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>
+ .. deprecated:: 3.7
+
+ All ``OP_NO_SSL*`` and ``OP_NO_TLS*`` options have been deprecated since
+ Python 3.7. Use :attr:`SSLContext.minimum_version` and
+ :attr:`SSLContext.maximum_version` instead.
+
.. attribute:: SSLContext.post_handshake_auth
Enable TLS 1.3 post-handshake client authentication. Post-handshake auth
@@ -2623,8 +2650,8 @@
::
>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
- >>> client_context.options |= ssl.OP_NO_TLSv1
- >>> client_context.options |= ssl.OP_NO_TLSv1_1
+ >>> client_context.minimum_version = ssl.TLSVersion.TLSv1_3
+ >>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3
The SSL context created above will only allow TLSv1.2 and later (if