Skip to content
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

Jump to bottom

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

Merged
merged 5 commits into from
Nov 3, 2022
Merged

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

Changes from all commits
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
67 changes: 16 additions & 51 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,10 @@ Functions, Constants, and Exceptions
Socket creation
^^^^^^^^^^^^^^^

Since Python 3.2 and 2.7.9, 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
Instances of :class:`SSLSocket` must be created using the
:meth:`SSLContext.wrap_socket` method. 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 @@ -369,10 +366,10 @@ Certificate handling
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
PEM-encoded string. If ``ssl_version`` is specified, uses that version of
the SSL protocol to attempt to connect to the server. If ``ca_certs`` is
the SSL protocol to attempt to connect to the server. If *ca_certs* is
specified, it should be a file containing a list of root certificates, the
same format as used for the same parameter in
:meth:`SSLContext.wrap_socket`. The call will attempt to validate the
same format as used for the *cafile* parameter in
:meth:`SSLContext.load_verify_locations`. The call will attempt to validate the
server certificate against that set of root certificates, and will fail
if the validation attempt fails. A timeout can be specified with the
``timeout`` parameter.
Expand Down Expand Up @@ -451,33 +448,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 @@ -488,8 +458,8 @@ 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`,
Possible value for :attr:`SSLContext.verify_mode`.
Except for :const:`PROTOCOL_TLS_CLIENT`,
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 @@ -501,8 +471,8 @@ 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`
Possible value for :attr:`SSLContext.verify_mode`.
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 @@ -513,13 +483,12 @@ Constants
the TLS handshake.

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`.
be passed to :meth:`SSLContext.load_verify_locations`.

.. data:: CERT_REQUIRED

Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
parameter to :func:`wrap_socket`. In this mode, certificates are
Possible value for :attr:`SSLContext.verify_mode`.
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 @@ -533,8 +502,7 @@ Constants
the client must provide a valid and trusted certificate.

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`.
be passed to :meth:`SSLContext.load_verify_locations`.

.. class:: VerifyMode

Expand Down Expand Up @@ -1327,10 +1295,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
(rather than :meth:`SSLContext.wrap_socket`), this is a custom context
object created for this SSL socket.
The :class:`SSLContext` object this SSL socket is tied to.

.. versionadded:: 3.2

Expand Down Expand Up @@ -2086,7 +2051,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
needs to be passed. If the private key is stored
with the certificate, it should come before the first certificate in
the certificate chain::

Expand Down