From 851a6cc07107a67c4fc1365a75cf209926a4bda4 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 10 Oct 2014 12:04:15 +0200 Subject: [PATCH 1/4] Issue #22564: ssl doc: fix typos --- Doc/library/ssl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 5ab6c14d8ed..3c9c60ffe84 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -1005,7 +1005,7 @@ to speed up repeated connections from the same clients. :data:`CERT_NONE`. At least one of *cafile* or *capath* must be specified. This method can also load certification revocation lists (CRLs) in PEM or - or DER format. In order to make use of CRLs, :attr:`SSLContext.verify_flags` + DER format. In order to make use of CRLs, :attr:`SSLContext.verify_flags` must be configured properly. The *cafile* string, if present, is the path to a file of concatenated @@ -1671,7 +1671,7 @@ Manual settings Verifying certificates '''''''''''''''''''''' -When calling the the :class:`SSLContext` constructor directly, +When calling the :class:`SSLContext` constructor directly, :const:`CERT_NONE` is the default. Since it does not authenticate the other peer, it can be insecure, especially in client mode where most of time you would like to ensure the authenticity of the server you're talking to. From 41f92c2818a2ea63a82a444547c10d7f88a30f1a Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 10 Oct 2014 12:05:56 +0200 Subject: [PATCH 2/4] Issue #22564: ssl doc: document read(), write(), pending, server_side and server_hostname methods and attributes of SSLSocket. --- Doc/library/ssl.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 3c9c60ffe84..7d89ea68cbe 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -782,6 +782,41 @@ the specification of normal, OS-level sockets. See especially the SSL sockets also have the following additional methods and attributes: +.. method:: SSLSocket.read(len=0, buffer=None) + + Read up to *len* bytes of data from the SSL socket and return the result as + a ``bytes`` instance. If *buffer* is specified, then read into the buffer + instead, and return the number of bytes read. + + Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is + non-blocking and the read would block. + + As at any time a re-negotiation is possible, a call to :meth:`read` can also + cause write operations. + +.. method:: SSLSocket.write(buf) + + Write *buf* to the SSL socket and return the number of bytes written. The + *buf* argument must be an object supporting the buffer interface. + + Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is + non-blocking and the write would block. + + As at any time a re-negotiation is possible, a call to :meth:`write` can + also cause read operations. + +.. note:: + + The :meth:`~SSLSocket.read` and :meth:`~SSLSocket.write` methods are the + low-level methods that read and write unencrypted, application-level data + and and decrypt/encrypt it to encrypted, wire-level data. These methods + require an active SSL connection, i.e. the handshake was completed and + :meth:`SSLSocket.unwrap` was not called. + + Normally you should use the socket API methods like + :meth:`~socket.socket.recv` and :meth:`~socket.socket.send` instead of these + methods. + .. method:: SSLSocket.do_handshake() Perform the SSL setup handshake. @@ -904,6 +939,11 @@ SSL sockets also have the following additional methods and attributes: returned socket should always be used for further communication with the other side of the connection, rather than the original socket. +.. method:: SSLSocket.pending() + + Returns the number of already decrypted bytes available for read, pending on + the connection. + .. attribute:: SSLSocket.context The :class:`SSLContext` object this SSL socket is tied to. If the SSL @@ -913,6 +953,20 @@ SSL sockets also have the following additional methods and attributes: .. versionadded:: 3.2 +.. attribute:: SSLSocket.server_side + + A boolean which is ``True`` for server-side sockets and ``False`` for + client-side sockets. + + .. versionadded:: 3.2 + +.. attribute:: SSLSocket.server_hostname + + Hostname of the server: :class:`str` type, or ``None`` for server-side + socket or if the hostname was not specified in the constructor. + + .. versionadded:: 3.2 + SSL Contexts ------------ From 3c3d3c73f3f55383f2ce71aebf08a1cd8c8ac7b4 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 10 Oct 2014 12:06:51 +0200 Subject: [PATCH 3/4] Issue #22564: ssl doc: use "class" marker to document the SSLSocket class --- Doc/library/ssl.rst | 46 +++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 7d89ea68cbe..5f4a118225d 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -755,30 +755,32 @@ Constants SSL Sockets ----------- -SSL sockets provide the following methods of :ref:`socket-objects`: +.. class:: SSLSocket(socket.socket) -- :meth:`~socket.socket.accept()` -- :meth:`~socket.socket.bind()` -- :meth:`~socket.socket.close()` -- :meth:`~socket.socket.connect()` -- :meth:`~socket.socket.detach()` -- :meth:`~socket.socket.fileno()` -- :meth:`~socket.socket.getpeername()`, :meth:`~socket.socket.getsockname()` -- :meth:`~socket.socket.getsockopt()`, :meth:`~socket.socket.setsockopt()` -- :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`, - :meth:`~socket.socket.setblocking()` -- :meth:`~socket.socket.listen()` -- :meth:`~socket.socket.makefile()` -- :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()` - (but passing a non-zero ``flags`` argument is not allowed) -- :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with - the same limitation) -- :meth:`~socket.socket.shutdown()` + SSL sockets provide the following methods of :ref:`socket-objects`: -However, since the SSL (and TLS) protocol has its own framing atop -of TCP, the SSL sockets abstraction can, in certain respects, diverge from -the specification of normal, OS-level sockets. See especially the -:ref:`notes on non-blocking sockets `. + - :meth:`~socket.socket.accept()` + - :meth:`~socket.socket.bind()` + - :meth:`~socket.socket.close()` + - :meth:`~socket.socket.connect()` + - :meth:`~socket.socket.detach()` + - :meth:`~socket.socket.fileno()` + - :meth:`~socket.socket.getpeername()`, :meth:`~socket.socket.getsockname()` + - :meth:`~socket.socket.getsockopt()`, :meth:`~socket.socket.setsockopt()` + - :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`, + :meth:`~socket.socket.setblocking()` + - :meth:`~socket.socket.listen()` + - :meth:`~socket.socket.makefile()` + - :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()` + (but passing a non-zero ``flags`` argument is not allowed) + - :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with + the same limitation) + - :meth:`~socket.socket.shutdown()` + + However, since the SSL (and TLS) protocol has its own framing atop + of TCP, the SSL sockets abstraction can, in certain respects, diverge from + the specification of normal, OS-level sockets. See especially the + :ref:`notes on non-blocking sockets `. SSL sockets also have the following additional methods and attributes: From d28fe8c8f461c153b1d3252d52d7b0c494402a4e Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 10 Oct 2014 12:07:19 +0200 Subject: [PATCH 4/4] Issue #22564: ssl doc: mention how SSLSocket are usually created --- Doc/library/ssl.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 5f4a118225d..6489ecfc257 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -782,6 +782,9 @@ SSL Sockets the specification of normal, OS-level sockets. See especially the :ref:`notes on non-blocking sockets `. + Usually, :class:`SSLSocket` are not created directly, but using the + :func:`wrap_socket` function or the :meth:`SSLContext.wrap_socket` method. + SSL sockets also have the following additional methods and attributes: .. method:: SSLSocket.read(len=0, buffer=None)