diff --git a/pep-3156.txt b/pep-3156.txt index 4add21e7b..26661294a 100644 --- a/pep-3156.txt +++ b/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 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 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