diff -r 588657f910ac Doc/library/ssl.rst --- a/Doc/library/ssl.rst Thu Oct 09 13:53:45 2014 +0200 +++ b/Doc/library/ssl.rst Thu Oct 09 14:49:31 2014 +0200 @@ -771,35 +771,41 @@ Constants SSL Sockets ----------- -SSL sockets provide the following methods of :ref:`socket-objects`: - -- :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.sendfile()` (but :mod:`os.sendfile` will be used - for plain-text sockets only, else :meth:`~socket.socket.send()` will be used) - - .. versionadded:: 3.5 - -- :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 `. +.. class:: SSLSocket(socket.socket) + + SSL sockets provide the following methods of :ref:`socket-objects`: + + - :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.sendfile()` (but :mod:`os.sendfile` will be used + for plain-text sockets only, else :meth:`~socket.socket.send()` will be used) + - :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 `. + + Usually, :class:`SSLSocket` are not created directly, by using the + :func:`wrap_socket` function or the :meth:`SSLContext.wrap_socket` method. + + .. versionchanged:: 3.5 + The :meth:`sendfile` method was added. + SSL sockets also have the following additional methods and attributes: @@ -809,11 +815,23 @@ SSL sockets also have the following addi 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 @@ -977,16 +995,14 @@ SSL sockets also have the following addi A boolean which is ``True`` for server-side sockets and ``False`` for client-side sockets. - .. versionadded:: 3.5 + .. versionadded:: 3.2 .. attribute:: SSLSocket.server_hostname - A ``bytes`` instance containing the ``'idna'`` encoded version of the - hostname specified in the *server_hostname* argument in - :meth:`SSLContext.wrap_socket`. If no *server_hostname* was specified, this - attribute will be ``None``. - - .. versionadded:: 3.5 + Hostname (:class:`str`) of the server: a string, or ``None`` for server-side + socket or if the hostname was not specified in the constructor. + + .. versionadded:: 3.2 SSL Contexts @@ -1253,6 +1269,16 @@ to speed up repeated connections from th *server_hostname* will also raise a :exc:`ValueError` if *server_side* is true. +.. 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`. + .. method:: SSLContext.session_stats() Get statistics about the SSL sessions created or managed by this context. @@ -1714,6 +1740,15 @@ thus several things you need to be aware 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 ------------------ @@ -1744,21 +1779,51 @@ provided. 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` + 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 :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. + +Some notes related to the use of :class:`SSLObject`: + +- All I/O 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. An SSLObject communicates with the outside world using memory buffers. The class :class:`MemoryBIO` provides a memory buffer that can be used for this @@ -1769,73 +1834,33 @@ purpose. It wraps an OpenSSL memory BIO 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. + .. 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. .. _ssl-security: