From: Victor Stinner Date: Fri, 10 Oct 2014 10:47:01 +0000 (+0200) Subject: Merge 3.4 X-Git-Tag: v3.5.0a1~713 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9558e90315fce8c114662e4e6d72fbdad0da9cc6;p=python Merge 3.4 --- 9558e90315fce8c114662e4e6d72fbdad0da9cc6 diff --cc Doc/library/ssl.rst index b5195f6e0e,095a831929..9aa30211e8 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@@ -1729,131 -1691,15 +1729,139 @@@ thus several things you need to be awar except ssl.SSLWantWriteError: select.select([], [sock], []) + .. seealso:: + + The :mod:`asyncio` module supports non-blocking SSL sockets and provides a + higher level API. It polls for events using the :mod:`selectors` module and + handles :exc:`SSLWantWriteError`, :exc:`SSLWantReadError` and + :exc:`BlockingIOError` exceptions. It runs the SSL handshake asynchronously + as well. + +Memory BIO Support +------------------ + +.. versionadded:: 3.5 + +Ever since the SSL module was introduced in Python 2.6, the :class:`SSLSocket` +class has provided two related but distinct areas of functionality: + +- SSL protocol handling +- Network IO + +The network IO API is identical to that provided by :class:`socket.socket`, +from which :class:`SSLSocket` also inherits. This allows an SSL socket to be +used as a drop-in replacement for a regular socket, making it very easy to add +SSL support to an existing application. + +Combining SSL protocol handling and network IO usually works well, but there +are some cases where it doesn't. An example is async IO frameworks that want to +use a different IO multiplexing model than the "select/poll on a file +descriptor" (readiness based) model that is assumed by :class:`socket.socket` +and by the internal OpenSSL socket IO routines. This is mostly relevant for +platforms like Windows where this model is not efficient. For this purpose, a +reduced scope variant of :class:`SSLSocket` called :class:`SSLObject` is +provided. + +.. class:: SSLObject + + A reduced-scope variant of :class:`SSLSocket` representing an SSL protocol + instance that does not contain any network IO methods. + +The following methods are available from :class:`SSLSocket`: + +- :attr:`~SSLSocket.context` +- :attr:`~SSLSocket.server_side` +- :attr:`~SSLSocket.server_hostname` +- :meth:`~SSLSocket.read` +- :meth:`~SSLSocket.write` +- :meth:`~SSLSocket.getpeercert` +- :meth:`~SSLSocket.selected_npn_protocol` +- :meth:`~SSLSocket.cipher` +- :meth:`~SSLSocket.compression` +- :meth:`~SSLSocket.pending` +- :meth:`~SSLSocket.do_handshake` +- :meth:`~SSLSocket.unwrap` +- :meth:`~SSLSocket.get_channel_binding` + +An SSLObject communicates with the outside world using memory buffers. The +class :class:`MemoryBIO` provides a memory buffer that can be used for this +purpose. It wraps an OpenSSL memory BIO (Basic IO) object: + +.. class:: MemoryBIO + + A memory buffer that can be used to pass data between Python and an SSL + protocol instance. + +.. attribute:: MemoryBIO.pending + + Return the number of bytes currently in the memory buffer. + +.. attribute:: MemoryBIO.eof + + A boolean indicating whether the memory BIO is current at the end-of-file + position. + +.. method:: MemoryBIO.read(n=-1) + + Read up to *n* bytes from the memory buffer. If *n* is not specified or + negative, all bytes are returned. + +.. method:: MemoryBIO.write(buf) + + Write the bytes from *buf* to the memory BIO. The *buf* argument must be an + object supporting the buffer protocol. + + The return value is the number of bytes written, which is always equal to + the length of *buf*. + +.. method:: MemoryBIO.write_eof() + + Write an EOF marker to the memory BIO. After this method has been called, it + is illegal to call :meth:`~MemoryBIO.write`. The attribute :attr:`eof` will + become true after all data currently in the buffer has been read. + +An :class:`SSLObject` instance can be created using the +:meth:`~SSLContext.wrap_bio` method. This method will create the +:class:`SSLObject` instance and bind it to a pair of BIOs. The *incoming* BIO +is used to pass data from Python to the SSL protocol instance, while the +*outgoing* BIO is used to pass data the other way around. + +.. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \ + server_hostname=None) + + Create a new :class:`SSLObject` instance by wrapping the BIO objects + *incoming* and *outgoing*. The SSL routines will read input data from the + incoming BIO and write data to the outgoing BIO. + + The *server_side* and *server_hostname* parameters have the same meaning as + in :meth:`SSLContext.wrap_socket`. + +Some notes related to the use of :class:`SSLObject`: + +- All IO on an :class:`SSLObject` is non-blocking. This means that for example + :meth:`~SSLSocket.read` will raise an :exc:`SSLWantReadError` if it needs + more data than the incoming BIO has available. + +- There is no module-level ``wrap_bio`` call like there is for + :meth:`~SSLContext.wrap_socket`. An :class:`SSLObject` is always created via + an :class:`SSLContext`. + +- There is no *do_handshake_on_connect* machinery. You must always manually + call :meth:`~SSLSocket.do_handshake` to start the handshake. + +- There is no handling of *suppress_ragged_eofs*. All end-of-file conditions + that are in violation of the protocol are reported via the :exc:`SSLEOFError` + exception. + +- The method :meth:`~SSLSocket.unwrap` call does not return anything, unlike + for an SSL socket where it returns the underlying socket. + +- The *server_name_callback* callback passed to + :meth:`SSLContext.set_servername_callback` will get an :class:`SSLObject` + instance instead of a :class:`SSLSocket` instance as its first parameter. + + .. _ssl-security: Security considerations