]> granicus.if.org Git - python/commitdiff
Merge 3.4
authorVictor Stinner <victor.stinner@gmail.com>
Fri, 10 Oct 2014 10:47:01 +0000 (12:47 +0200)
committerVictor Stinner <victor.stinner@gmail.com>
Fri, 10 Oct 2014 10:47:01 +0000 (12:47 +0200)
1  2 
Doc/library/ssl.rst

index b5195f6e0ed1e9edcb1d19f135c597f77faabd1b,095a83192952587750075816ad8899f4dda16101..9aa30211e8a94d947b443aa22f9375ca31b9dcb4
@@@ -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