summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorAntoine Pitrou <solipsis@pitrou.net>2011-07-10 23:35:48 (GMT)
committerAntoine Pitrou <solipsis@pitrou.net>2011-07-10 23:35:48 (GMT)
commit6f5dcb1ee28f616602d73f22630c9f8e3660e671 (patch)
treef2134011e072f7b5cff1c7c1fd1fcdb509223556 /Doc/library
parentcdddf2b875e10f86af55eacb83e81025f1071b39 (diff)
downloadcpython-6f5dcb1ee28f616602d73f22630c9f8e3660e671.zip
cpython-6f5dcb1ee28f616602d73f22630c9f8e3660e671.tar.gz
cpython-6f5dcb1ee28f616602d73f22630c9f8e3660e671.tar.bz2
Issue #12343: Add some notes on behaviour of non-blocking SSL sockets.
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/ssl.rst61
1 files changed, 43 insertions, 18 deletions
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 09a2961..c0b9d4a 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -408,27 +408,16 @@ SSL sockets provide the following methods of :ref:`socket-objects`:
the same limitation)
- :meth:`~socket.socket.shutdown()`
-They also have the following additional methods and attributes:
+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-nonblocking>`.
+
+SSL sockets also have the following additional methods and attributes:
.. method:: SSLSocket.do_handshake()
- Performs the SSL setup handshake. If the socket is non-blocking, this method
- may raise :exc:`SSLError` with the value of the exception instance's
- ``args[0]`` being either :const:`SSL_ERROR_WANT_READ` or
- :const:`SSL_ERROR_WANT_WRITE`, and should be called again until it stops
- raising those exceptions. Here's an example of how to do that::
-
- while True:
- try:
- sock.do_handshake()
- break
- except ssl.SSLError as err:
- if err.args[0] == ssl.SSL_ERROR_WANT_READ:
- select.select([sock], [], [])
- elif err.args[0] == ssl.SSL_ERROR_WANT_WRITE:
- select.select([], [sock], [])
- else:
- raise
+ Performs the SSL setup handshake.
.. method:: SSLSocket.getpeercert(binary_form=False)
@@ -917,6 +906,42 @@ would probably handle each client connection in a separate thread, or put
the sockets in non-blocking mode and use an event loop).
+.. _ssl-nonblocking:
+
+Notes on non-blocking sockets
+-----------------------------
+
+When working with non-blocking sockets, there are several things you need
+to be aware of:
+
+- Calling :func:`~select.select` tells you that the OS-level socket can be
+ read from (or written to), but it does not imply that there is sufficient
+ data at the upper SSL layer. For example, only part of an SSL frame might
+ have arrived. Therefore, you must be ready to handle :meth:`SSLSocket.recv`
+ and :meth:`SSLSocket.send` failures, and retry after another call to
+ :func:`~select.select`.
+
+ (of course, similar provisions apply when using other primitives such as
+ :func:`~select.poll`)
+
+- The SSL handshake itself will be non-blocking: the
+ :meth:`SSLSocket.do_handshake` method has to be retried until it returns
+ successfully. Here is a synopsis using :func:`~select.select` to wait for
+ the socket's readiness::
+
+ while True:
+ try:
+ sock.do_handshake()
+ break
+ except ssl.SSLError as err:
+ if err.args[0] == ssl.SSL_ERROR_WANT_READ:
+ select.select([sock], [], [])
+ elif err.args[0] == ssl.SSL_ERROR_WANT_WRITE:
+ select.select([], [sock], [])
+ else:
+ raise
+
+
.. _ssl-security:
Security considerations