Clarify that SSL could mean TLS. Allow duck typing SSLContext. Allow missing run/stop/close functionality.

This commit is contained in:
Guido van Rossum 2013-10-24 08:37:55 -07:00
parent 9d74f7717b
commit 586b21034e
1 changed files with 32 additions and 28 deletions

View File

@ -176,7 +176,7 @@ The most common type of transport is a bidirectional stream transport.
It represents a pair of buffered streams (one in each direction) that It represents a pair of buffered streams (one in each direction) that
each transmit a sequence of bytes. The most common example of a each transmit a sequence of bytes. The most common example of a
bidirectional stream transport is probably a TCP connection. Another bidirectional stream transport is probably a TCP connection. Another
common example is an SSL connection. But there are some other things common example is an SSL/TLS connection. But there are some other things
that can be viewed this way, for example an SSH session or a pair of that can be viewed this way, for example an SSH session or a pair of
UNIX pipes. Typically there aren't many different transport UNIX pipes. Typically there aren't many different transport
implementations, and most of them come with the event loop implementations, and most of them come with the event loop
@ -302,7 +302,7 @@ concrete classes are defined:
``IocpProactor`` is created and used. (The ``IocpProactor`` class ``IocpProactor`` is created and used. (The ``IocpProactor`` class
is not specified by this PEP. Its inclusion in the standard library is not specified by this PEP. Its inclusion in the standard library
is not currently under consideration; it is just an implementation is not currently under consideration; it is just an implementation
detail of the ``ProactorEventLoop`` class. detail of the ``ProactorEventLoop`` class.)
Event Loop Methods Overview Event Loop Methods Overview
--------------------------- ---------------------------
@ -312,7 +312,9 @@ categories. A brief overview of the categories. The first set of
categories must be supported by all conforming event loop categories must be supported by all conforming event loop
implementations. (However, in some cases a partially-conforming implementations. (However, in some cases a partially-conforming
implementation may choose not to implement the internet/socket implementation may choose not to implement the internet/socket
methods, and still conform to the other methods.) methods, and still conform to the other methods. Also, it is possible
that a partially-conforming implementation has no way to create,
close, start, or stop a loop.)
- Miscellaneous: ``close()``, ``time()``. - Miscellaneous: ``close()``, ``time()``.
@ -564,21 +566,22 @@ use a different transport and protocol interface.
The <options> are all specified using optional keyword arguments: The <options> are all specified using optional keyword arguments:
- ``ssl``: Pass ``True`` to create an SSL transport (by default a - ``ssl``: Pass ``True`` to create an SSL/TLS transport (by default
plain TCP transport is created). Or pass an ``ssl.SSLContext`` a plain TCP transport is created). Or pass an ``ssl.SSLContext``
object to override the default SSL context object to be used. If object (or something else that implements the same interface) to
a default context is created it is up to the implementation to override the default SSL context object to be used. If a default
configure reasonable defaults. The reference implementation context is created it is up to the implementation to configure
currently uses ``PROTOCOL_SSLv23`` and sets the ``OP_NO_SSLv2`` reasonable defaults. The reference implementation currently uses
option, calls ``set_default_verify_paths()`` and sets verify_mode ``PROTOCOL_SSLv23`` and sets the ``OP_NO_SSLv2`` option, calls
to ``CERT_REQUIRED``. In addition, whenever the context (default ``set_default_verify_paths()`` and sets verify_mode to
or otherwise) specifies a verify_mode of ``CERT_REQUIRED``, if a ``CERT_REQUIRED``. In addition, whenever the context (default or
hostname is given, immediately after a successful handshake otherwise) specifies a verify_mode of ``CERT_REQUIRED`` or
``ss.ssl.match_hostname(peercert, hostname)`` is called, and if ``CERT_OPTIONAL``, if a hostname is given, immediately after a
this raises an exception the conection is closed. (To avoid this successful handshake ``ssl.match_hostname(peercert, hostname)`` is
behavior, pass in an context that doesn't have verify_mode set to called, and if this raises an exception the conection is closed.
``CERT_REQUIRED``. But this means you are not secure, and (To avoid this behavior, pass in an SSL context that ha
vulnerable to for example man-in-the-middle attacks.) verify_mode set to ``CERT_NONE``. But this means you are not
secure, and vulnerable to for example man-in-the-middle attacks.)
- ``family``, ``proto``, ``flags``: Address family, protocol and - ``family``, ``proto``, ``flags``: Address family, protocol and
flags to be passed through to ``getaddrinfo()``. These all flags to be passed through to ``getaddrinfo()``. These all
@ -620,10 +623,11 @@ use a different transport and protocol interface.
The <options> are all specified using optional keyword arguments: The <options> are all specified using optional keyword arguments:
- ``ssl``: Pass an ``ssl.SSLContext`` object to override the default - ``ssl``: Pass an ``ssl.SSLContext`` object (or an object with the
SSL context object to be used. (Unlike ``create_connection()``, same interface) to override the default SSL context object to be
passing ``True`` does not make sense -- the ``SSLContext`` object used. (Unlike ``create_connection()``, passing ``True`` does not
is required to specify the certificate and key.) make sense -- the ``SSLContext`` object is required to specify the
certificate and key.)
- ``backlog``: Backlog value to be passed to the ``listen()`` call. - ``backlog``: Backlog value to be passed to the ``listen()`` call.
Defaults to ``100``. Defaults to ``100``.
@ -1013,8 +1017,8 @@ Transports work in conjunction with protocols. Protocols are
typically written without knowing or caring about the exact type of typically written without knowing or caring about the exact type of
transport used, and transports can be used with a wide variety of transport used, and transports can be used with a wide variety of
protocols. For example, an HTTP client protocol implementation may be protocols. For example, an HTTP client protocol implementation may be
used with either a plain socket transport or an SSL transport. The used with either a plain socket transport or an SSL/TLS transport.
plain socket transport can be used with many different protocols The plain socket transport can be used with many different protocols
besides HTTP (e.g. SMTP, IMAP, POP, FTP, IRC, SPDY). besides HTTP (e.g. SMTP, IMAP, POP, FTP, IRC, SPDY).
The most common type of transport is a bidirectional stream transport. The most common type of transport is a bidirectional stream transport.
@ -1037,7 +1041,7 @@ Bidirectional Stream Transports
''''''''''''''''''''''''''''''' '''''''''''''''''''''''''''''''
A bidrectional stream transport is an abstraction on top of a socket A bidrectional stream transport is an abstraction on top of a socket
or something similar (for example, a pair of UNIX pipes or an SSL or something similar (for example, a pair of UNIX pipes or an SSL/TLS
connection). connection).
Most connections have an asymmetric nature: the client and server Most connections have an asymmetric nature: the client and server
@ -1092,7 +1096,7 @@ Bidirectional stream transports have the following public methods:
because some protocols need to change their behavior when because some protocols need to change their behavior when
``write_eof()`` is unavailable. For example, in HTTP, to send data ``write_eof()`` is unavailable. For example, in HTTP, to send data
whose size is not known ahead of time, the end of the data is whose size is not known ahead of time, the end of the data is
typically indicated using ``write_eof()``; however, SSL does not typically indicated using ``write_eof()``; however, SSL/TLS does not
support this, and an HTTP protocol implementation would have to use support this, and an HTTP protocol implementation would have to use
the "chunked" transfer encoding in this case. But if the data size the "chunked" transfer encoding in this case. But if the data size
is known ahead of time, the best approach in both cases is to use is known ahead of time, the best approach in both cases is to use
@ -1519,7 +1523,7 @@ Open Issues
users can write their own (it's not rocket science). users can write their own (it's not rocket science).
- We may need APIs to control various timeouts. E.g. we may want to - We may need APIs to control various timeouts. E.g. we may want to
limit the time spent in DNS resolution, connecting, ssl handshake, limit the time spent in DNS resolution, connecting, ssl/tls handshake,
idle connection, close/shutdown, even per session. Possibly it's idle connection, close/shutdown, even per session. Possibly it's
sufficient to add ``timeout`` keyword arguments to some methods, sufficient to add ``timeout`` keyword arguments to some methods,
and other timeouts can probably be implemented by clever use of and other timeouts can probably be implemented by clever use of