summaryrefslogtreecommitdiffstats
path: root/Doc/library/ssl.rst
diff options
context:
space:
mode:
authorChristian Heimes <christian@python.org>2018-02-27 09:17:30 (GMT)
committerGitHub <noreply@github.com>2018-02-27 09:17:30 (GMT)
commit9d50ab563df6307cabbcc9883cb8c52c614b0f22 (patch)
treec3e294b7e97d43152f87b00255ff5b875635448b /Doc/library/ssl.rst
parent90f05a527c7d439f1d0cba80f2eb32e60ee20fc3 (diff)
downloadcpython-9d50ab563df6307cabbcc9883cb8c52c614b0f22.zip
cpython-9d50ab563df6307cabbcc9883cb8c52c614b0f22.tar.gz
cpython-9d50ab563df6307cabbcc9883cb8c52c614b0f22.tar.bz2
bpo-32951: Disable SSLSocket/SSLObject constructor (#5864)
Direct instantiation of SSLSocket and SSLObject objects is now prohibited. The constructors were never documented, tested, or designed as public constructors. The SSLSocket constructor had limitations. For example it was not possible to enabled hostname verification except was ssl_version=PROTOCOL_TLS_CLIENT with cert_reqs=CERT_REQUIRED. SSLContext.wrap_socket() and SSLContext.wrap_bio are the recommended API to construct SSLSocket and SSLObject instances. ssl.wrap_socket() is also deprecated. The only test case for direct instantiation was added a couple of days ago for IDNA testing. Signed-off-by: Christian Heimes <christian@python.org>
Diffstat (limited to 'Doc/library/ssl.rst')
-rw-r--r--Doc/library/ssl.rst24
1 files changed, 18 insertions, 6 deletions
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 4889a71..d18a505 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -998,7 +998,7 @@ SSL Sockets
the specification of normal, OS-level sockets. See especially the
:ref:`notes on non-blocking sockets <ssl-nonblocking>`.
- :class:`SSLSocket` are not created directly, but using the
+ Instances of :class:`SSLSocket` must be created using the
:meth:`SSLContext.wrap_socket` method.
.. versionchanged:: 3.5
@@ -1013,6 +1013,11 @@ SSL Sockets
It is deprecated to create a :class:`SSLSocket` instance directly, use
:meth:`SSLContext.wrap_socket` to wrap a socket.
+ .. versionchanged:: 3.7
+ :class:`SSLSocket` instances must to created with
+ :meth:`~SSLContext.wrap_socket`. In earlier versions, it was possible
+ to create instances directly. This was never documented or officially
+ supported.
SSL sockets also have the following additional methods and attributes:
@@ -2249,11 +2254,12 @@ provided.
but does not provide any network IO itself. IO needs to be performed through
separate "BIO" objects which are OpenSSL's IO abstraction layer.
- An :class:`SSLObject` instance can be created using the
- :meth:`~SSLContext.wrap_bio` method. This method will create the
- :class:`SSLObject` instance and bind it to a pair of BIOs. The *incoming*
- BIO is used to pass data from Python to the SSL protocol instance, while the
- *outgoing* BIO is used to pass data the other way around.
+ This class has no public constructor. An :class:`SSLObject` instance
+ must be created using the :meth:`~SSLContext.wrap_bio` method. This
+ method will create the :class:`SSLObject` instance and bind it to a
+ pair of BIOs. The *incoming* BIO is used to pass data from Python to the
+ SSL protocol instance, while the *outgoing* BIO is used to pass data the
+ other way around.
The following methods are available:
@@ -2305,6 +2311,12 @@ provided.
:meth:`~SSLContext.wrap_socket`. An :class:`SSLObject` is always created
via an :class:`SSLContext`.
+ .. versionchanged:: 3.7
+ :class:`SSLObject` instances must to created with
+ :meth:`~SSLContext.wrap_bio`. In earlier versions, it was possible to
+ create instances directly. This was never documented or officially
+ supported.
+
An SSLObject communicates with the outside world using memory buffers. The
class :class:`MemoryBIO` provides a memory buffer that can be used for this
purpose. It wraps an OpenSSL memory BIO (Basic IO) object: