Clarify that SSL could mean TLS. Allow duck typing SSLContext. Allow missing run/stop/close functionality.
This commit is contained in:
Guido van Rossum
parent
9d74f7717b
commit
586b21034e
60
pep-3156.txt
60
pep-3156.txt
|
|
@ -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
|
||||
each transmit a sequence of bytes. The most common example of a
|
||||
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
|
||||
UNIX pipes. Typically there aren't many different transport
|
||||
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
|
||||
is not specified by this PEP. Its inclusion in the standard library
|
||||
is not currently under consideration; it is just an implementation
|
||||
detail of the ``ProactorEventLoop`` class.
|
||||
detail of the ``ProactorEventLoop`` class.)
|
||||
|
||||
Event Loop Methods Overview
|
||||
---------------------------
|
||||
|
|
@ -310,9 +310,11 @@ Event Loop Methods Overview
|
|||
The methods of a conforming event loop are grouped into several
|
||||
categories. A brief overview of the categories. The first set of
|
||||
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
|
||||
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()``.
|
||||
|
||||
|
|
@ -564,21 +566,22 @@ use a different transport and protocol interface.
|
|||
|
||||
The <options> are all specified using optional keyword arguments:
|
||||
|
||||
- ``ssl``: Pass ``True`` to create an SSL transport (by default a
|
||||
plain TCP transport is created). Or pass an ``ssl.SSLContext``
|
||||
object to override the default SSL context object to be used. If
|
||||
a default context is created it is up to the implementation to
|
||||
configure reasonable defaults. The reference implementation
|
||||
currently uses ``PROTOCOL_SSLv23`` and sets the ``OP_NO_SSLv2``
|
||||
option, calls ``set_default_verify_paths()`` and sets verify_mode
|
||||
to ``CERT_REQUIRED``. In addition, whenever the context (default
|
||||
or otherwise) specifies a verify_mode of ``CERT_REQUIRED``, if a
|
||||
hostname is given, immediately after a successful handshake
|
||||
``ss.ssl.match_hostname(peercert, hostname)`` is called, and if
|
||||
this raises an exception the conection is closed. (To avoid this
|
||||
behavior, pass in an context that doesn't have verify_mode set to
|
||||
``CERT_REQUIRED``. But this means you are not secure, and
|
||||
vulnerable to for example man-in-the-middle attacks.)
|
||||
- ``ssl``: Pass ``True`` to create an SSL/TLS transport (by default
|
||||
a plain TCP transport is created). Or pass an ``ssl.SSLContext``
|
||||
object (or something else that implements the same interface) to
|
||||
override the default SSL context object to be used. If a default
|
||||
context is created it is up to the implementation to configure
|
||||
reasonable defaults. The reference implementation currently uses
|
||||
``PROTOCOL_SSLv23`` and sets the ``OP_NO_SSLv2`` option, calls
|
||||
``set_default_verify_paths()`` and sets verify_mode to
|
||||
``CERT_REQUIRED``. In addition, whenever the context (default or
|
||||
otherwise) specifies a verify_mode of ``CERT_REQUIRED`` or
|
||||
``CERT_OPTIONAL``, if a hostname is given, immediately after a
|
||||
successful handshake ``ssl.match_hostname(peercert, hostname)`` is
|
||||
called, and if this raises an exception the conection is closed.
|
||||
(To avoid this behavior, pass in an SSL context that ha
|
||||
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
|
||||
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:
|
||||
|
||||
- ``ssl``: Pass an ``ssl.SSLContext`` object to override the default
|
||||
SSL context object to be used. (Unlike ``create_connection()``,
|
||||
passing ``True`` does not make sense -- the ``SSLContext`` object
|
||||
is required to specify the certificate and key.)
|
||||
- ``ssl``: Pass an ``ssl.SSLContext`` object (or an object with the
|
||||
same interface) to override the default SSL context object to be
|
||||
used. (Unlike ``create_connection()``, passing ``True`` does not
|
||||
make sense -- the ``SSLContext`` object is required to specify the
|
||||
certificate and key.)
|
||||
|
||||
- ``backlog``: Backlog value to be passed to the ``listen()`` call.
|
||||
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
|
||||
transport used, and transports can be used with a wide variety of
|
||||
protocols. For example, an HTTP client protocol implementation may be
|
||||
used with either a plain socket transport or an SSL transport. The
|
||||
plain socket transport can be used with many different protocols
|
||||
used with either a plain socket transport or an SSL/TLS transport.
|
||||
The plain socket transport can be used with many different protocols
|
||||
besides HTTP (e.g. SMTP, IMAP, POP, FTP, IRC, SPDY).
|
||||
|
||||
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
|
||||
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).
|
||||
|
||||
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
|
||||
``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
|
||||
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
|
||||
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
|
||||
|
|
@ -1519,7 +1523,7 @@ Open Issues
|
|||
users can write their own (it's not rocket science).
|
||||
|
||||
- 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
|
||||
sufficient to add ``timeout`` keyword arguments to some methods,
|
||||
and other timeouts can probably be implemented by clever use of
|
||||
|
|
|
|||
Loading…
Reference in New Issue