Skip to content

gh-94199: Remove ssl.wrap_socket() documentation #99023

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vstinner merged 5 commits into from
Nov 3, 2022
Merged

gh-94199: Remove ssl.wrap_socket() documentation #99023

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5e11f40
gh-94199: Remove ssl.wrap_socket() documentation
vstinner Nov 2, 2022
bd07b05
Fix the doc
vstinner Nov 2, 2022
a0d3884
Clarify
vstinner Nov 2, 2022
e0b7e86
Update Doc/library/ssl.rst
vstinner Nov 3, 2022
ce7a34a
Update Doc/library/ssl.rst
vstinner Nov 3, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
gh-94199: Remove ssl.wrap_socket() documentation 
The function has been removed. In the ssl documentation, replace
references to the ssl.wrap_socket() function with references to the
ssl.SSLContext.wrap_socket() method.
  • Loading branch information
@vstinner
vstinner committed Nov 2, 2022
commit 5e11f40e041d050d73955ad3bc336ba0c1ea78d9
49 changes: 10 additions & 39 deletions Doc/library/ssl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,13 +74,11 @@ Functions, Constants, and Exceptions
Socket creation
^^^^^^^^^^^^^^^

Since Python 3.2 and 2.7.9, it is recommended to use the
Since Python 3.2, it is recommended to use the
:meth:`SSLContext.wrap_socket` of an :class:`SSLContext` instance to wrap
sockets as :class:`SSLSocket` objects. The helper functions
sockets as :class:`SSLSocket` objects. The helper function
:func:`create_default_context` returns a new context with secure default
settings. The old :func:`wrap_socket` function is deprecated since it is
both inefficient and has no support for server name indication (SNI) and
hostname matching.
settings.

Client socket example with default context and IPv4/IPv6 dual stack::

Expand Down Expand Up @@ -451,33 +449,6 @@ Certificate handling

.. versionadded:: 3.4

.. function:: wrap_socket(sock, keyfile=None, certfile=None, \
server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_TLS, \
ca_certs=None, do_handshake_on_connect=True, \
suppress_ragged_eofs=True, ciphers=None)

Takes an instance ``sock`` of :class:`socket.socket`, and returns an instance
of :class:`ssl.SSLSocket`, a subtype of :class:`socket.socket`, which wraps
the underlying socket in an SSL context. ``sock`` must be a
:data:`~socket.SOCK_STREAM` socket; other socket types are unsupported.

Internally, function creates a :class:`SSLContext` with protocol
*ssl_version* and :attr:`SSLContext.options` set to *cert_reqs*. If
parameters *keyfile*, *certfile*, *ca_certs* or *ciphers* are set, then
the values are passed to :meth:`SSLContext.load_cert_chain`,
:meth:`SSLContext.load_verify_locations`, and
:meth:`SSLContext.set_ciphers`.

The arguments *server_side*, *do_handshake_on_connect*, and
*suppress_ragged_eofs* have the same meaning as
:meth:`SSLContext.wrap_socket`.

.. deprecated:: 3.7

Since Python 3.2 and 2.7.9, it is recommended to use the
:meth:`SSLContext.wrap_socket` instead of :func:`wrap_socket`. The
top-level function is limited and creates an insecure client socket
without server name indication or hostname matching.

Constants
^^^^^^^^^
Expand All @@ -489,7 +460,7 @@ Constants
.. data:: CERT_NONE

Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
parameter to :func:`wrap_socket`. Except for :const:`PROTOCOL_TLS_CLIENT`,
parameter to :meth:`SSLContext.wrap_socket`. Except for :const:`PROTOCOL_TLS_CLIENT`,
Comment thread
vstinner marked this conversation as resolved.
Outdated
it is the default mode. With client-side sockets, just about any
cert is accepted. Validation errors, such as untrusted or expired cert,
are ignored and do not abort the TLS/SSL handshake.
Expand All @@ -502,7 +473,7 @@ Constants
.. data:: CERT_OPTIONAL

Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
parameter to :func:`wrap_socket`. In client mode, :const:`CERT_OPTIONAL`
parameter to :meth:`SSLContext.wrap_socket`. In client mode, :const:`CERT_OPTIONAL`
has the same meaning as :const:`CERT_REQUIRED`. It is recommended to
use :const:`CERT_REQUIRED` for client-side sockets instead.

Expand All @@ -514,12 +485,12 @@ Constants

Use of this setting requires a valid set of CA certificates to
be passed, either to :meth:`SSLContext.load_verify_locations` or as a
value of the ``ca_certs`` parameter to :func:`wrap_socket`.
value of the ``ca_certs`` parameter to :meth:`SSLContext.wrap_socket`.
Comment thread
vstinner marked this conversation as resolved.
Outdated

.. data:: CERT_REQUIRED

Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
parameter to :func:`wrap_socket`. In this mode, certificates are
parameter to :meth:`SSLContext.wrap_socket`. In this mode, certificates are
required from the other side of the socket connection; an :class:`SSLError`
will be raised if no certificate is provided, or if its validation fails.
This mode is **not** sufficient to verify a certificate in client mode as
Expand All @@ -534,7 +505,7 @@ Constants

Use of this setting requires a valid set of CA certificates to
be passed, either to :meth:`SSLContext.load_verify_locations` or as a
value of the ``ca_certs`` parameter to :func:`wrap_socket`.
value of the ``ca_certs`` parameter to :meth:`SSLContext.wrap_socket`.

.. class:: VerifyMode

Expand Down Expand Up @@ -1328,7 +1299,7 @@ SSL sockets also have the following additional methods and attributes:
.. attribute:: SSLSocket.context

The :class:`SSLContext` object this SSL socket is tied to. If the SSL
socket was created using the deprecated :func:`wrap_socket` function
socket was created using the deprecated :meth:`SSLContext.wrap_socket` function
(rather than :meth:`SSLContext.wrap_socket`), this is a custom context
object created for this SSL socket.

Expand Down Expand Up @@ -2086,7 +2057,7 @@ Combined key and certificate

Often the private key is stored in the same file as the certificate; in this
case, only the ``certfile`` parameter to :meth:`SSLContext.load_cert_chain`
and :func:`wrap_socket` needs to be passed. If the private key is stored
and :meth:`SSLContext.wrap_socket` needs to be passed. If the private key is stored
Copy link
Copy Markdown
Contributor

@illia-v illia-v Nov 3, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SSLContext.wrap_socket has no certfile parameter

Comment thread
vstinner marked this conversation as resolved.
Outdated
with the certificate, it should come before the first certificate in
the certificate chain::

Expand Down