From 5e11f40e041d050d73955ad3bc336ba0c1ea78d9 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 2 Nov 2022 20:05:37 +0100 Subject: [PATCH 1/5] 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. --- Doc/library/ssl.rst | 49 +++++++++------------------------------------ 1 file changed, 10 insertions(+), 39 deletions(-) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index f5d5a7c4d28205..f92b3012d1926e 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -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:: @@ -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 ^^^^^^^^^ @@ -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`, 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. @@ -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. @@ -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`. .. 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 @@ -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 @@ -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. @@ -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 with the certificate, it should come before the first certificate in the certificate chain:: From bd07b053f7a727d3264ad3ac0e2ef5d34757a786 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 2 Nov 2022 22:27:26 +0100 Subject: [PATCH 2/5] Fix the doc --- Doc/library/ssl.rst | 27 +++++++++++---------------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index f92b3012d1926e..5dcac3b72e35b5 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -367,9 +367,9 @@ 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 + same format as used for the *cafile* parameter in :meth:`SSLContext.wrap_socket`. 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 @@ -459,8 +459,8 @@ Constants .. data:: CERT_NONE - Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs`` - parameter to :meth:`SSLContext.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. @@ -472,8 +472,8 @@ Constants .. data:: CERT_OPTIONAL - Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs`` - parameter to :meth:`SSLContext.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. @@ -484,13 +484,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 :meth:`SSLContext.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 :meth:`SSLContext.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 @@ -504,8 +503,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 :meth:`SSLContext.wrap_socket`. + be passed to :meth:`SSLContext.load_verify_locations`. .. class:: VerifyMode @@ -1298,10 +1296,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 :meth:`SSLContext.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 From a0d388412c52add24b932caf600442097f20efc4 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 2 Nov 2022 22:30:59 +0100 Subject: [PATCH 3/5] Clarify --- Doc/library/ssl.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 5dcac3b72e35b5..ba8ef90e191f82 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -74,9 +74,8 @@ Functions, Constants, and Exceptions Socket creation ^^^^^^^^^^^^^^^ -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 function +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. From e0b7e862c22190203d6175f046c43cec76ddb41b Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 3 Nov 2022 12:33:24 +0100 Subject: [PATCH 4/5] Update Doc/library/ssl.rst Co-authored-by: Illia Volochii --- Doc/library/ssl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index ba8ef90e191f82..29468d863bd9a0 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -2051,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 :meth:`SSLContext.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:: From ce7a34a5c4ed74c8ae057da987b45aca5c2eca5e Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 3 Nov 2022 12:33:30 +0100 Subject: [PATCH 5/5] Update Doc/library/ssl.rst Co-authored-by: Illia Volochii --- Doc/library/ssl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 29468d863bd9a0..4e6d06dc38d80c 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -369,7 +369,7 @@ Certificate handling 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 *cafile* parameter in - :meth:`SSLContext.wrap_socket`. The call will attempt to validate the + :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.