[Python-checkins] peps: Clarify that SSL could mean TLS. Allow duck typing SSLContext. Allow missing

[guido.van.rossum]

http://hg.python.org/peps/rev/f10b2ffcff9d
changeset:   5215:f10b2ffcff9d
user:        Guido van Rossum <guido at dropbox.com>
date:        Thu Oct 24 08:37:55 2013 -0700
summary:
  Clarify that SSL could mean TLS. Allow duck typing SSLContext. Allow missing run/stop/close functionality.

files:
  pep-3156.txt |  60 +++++++++++++++++++++------------------
  1 files changed, 32 insertions(+), 28 deletions(-)


diff --git a/pep-3156.txt b/pep-3156.txt
--- a/pep-3156.txt
+++ b/pep-3156.txt
@@ -176,7 +176,7 @@
 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 @@
   ``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 @@
 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 @@
 
   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 @@
 
   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 @@
 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 @@
 '''''''''''''''''''''''''''''''
 
 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 @@
   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 @@
   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

-- 
Repository URL: http://hg.python.org/peps