Issue #23857: Implement PEP 493

Adds a Python-2-only ssl module API and environment variable to
configure the default handling of SSL/TLS certificates for
HTTPS connections.

3 files changed, 79 insertions, 6 deletions

diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index c18d2a0..417cfff 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -280,6 +280,44 @@ purposes.
 
      RC4 was dropped from the default cipher string.
 
+.. function:: _https_verify_certificates(enable=True)
+
+   Specifies whether or not server certificates are verified when creating
+   client HTTPS connections without specifying a particular SSL context.
+
+   Starting with Python 2.7.9, :mod:`httplib` and modules which use it, such as
+   :mod:`urllib2` and :mod:`xmlrpclib`, default to verifying remote server
+   certificates received when establishing client HTTPS connections. This
+   default verification checks that the certificate is signed by a Certificate
+   Authority in the system trust store and that the Common Name (or Subject
+   Alternate Name) on the presented certificate matches the requested host.
+
+   Setting *enable* to :const:`True` ensures this default behaviour is in
+   effect.
+
+   Setting *enable* to :const:`False` reverts the default HTTPS certificate
+   handling to that of Python 2.7.8 and earlier, allowing connections to
+   servers using self-signed certificates, servers using certificates signed
+   by a Certicate Authority not present in the system trust store, and servers
+   where the hostname does not match the presented server certificate.
+
+   The leading underscore on this function denotes that it intentionally does
+   not exist in any implementation of Python 3 and may not be present in all
+   Python 2.7 implementations. The portable approach to bypassing certificate
+   checks or the system trust store when necessary is for tools to enable that
+   on a case-by-case basis by explicitly passing in a suitably configured SSL
+   context, rather than reverting the default behaviour of the standard library
+   client modules.
+
+   .. versionadded:: 2.7.12
+
+   .. seealso::
+
+      * `CVE-2014-9365 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-9365>`_
+        -- HTTPS man-in-the-middle attack against Python clients using default settings
+      * :pep:`476` -- Enabling certificate verification by default for HTTPS
+      * :pep:`493` -- HTTPS verification migration tools for Python 2.7
+
 
 Random generation
 ^^^^^^^^^^^^^^^^^
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 3f314b7..bcfcbd4 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -613,6 +613,17 @@ conflict.
    times.
 
 
+.. envvar:: PYTHONHTTPSVERIFY
+
+   If this environment variable is set specifically to ``0``, then it is
+   equivalent to implicitly calling :func:`ssl._https_verify_certificates` with
+   ``enable=False`` when :mod:`ssl` is first imported.
+
+   Refer to the documentation of :func:`ssl._https_verify_certificates` for
+   details.
+
+   .. versionadded:: 2.7.12
+
 Debug-mode variables
 ~~~~~~~~~~~~~~~~~~~~
 
diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
index e2560c7..f4b9148 100644
--- a/Doc/whatsnew/2.7.rst
+++ b/Doc/whatsnew/2.7.rst
@@ -2588,7 +2588,7 @@ PEP 477: Backport ensurepip (PEP 453) to Python 2.7
 
 :pep:`477` approves the inclusion of the :pep:`453` ensurepip module and the
 improved documentation that was enabled by it in the Python 2.7 maintenance
-releases, appearing first in the the Python 2.7.9 release.
+releases, appearing first in the Python 2.7.9 release.
 
 
 Bootstrapping pip By Default
@@ -2649,11 +2649,12 @@ and :ref:`distutils-index`.
 PEP 476: Enabling certificate verification by default for stdlib http clients
 -----------------------------------------------------------------------------
 
-:mod:`httplib` and modules which use it, such as :mod:`urllib2` and
-:mod:`xmlrpclib`, will now verify that the server presents a certificate
-which is signed by a CA in the platform trust store and whose hostname matches
-the hostname being requested by default, significantly improving security for
-many applications.
+:pep:`476` updated :mod:`httplib` and modules which use it, such as
+:mod:`urllib2` and :mod:`xmlrpclib`, to now verify that the server
+presents a certificate which is signed by a Certificate Authority in the
+platform trust store and whose hostname matches the hostname being requested
+by default, significantly improving security for many applications. This
+change was made in the Python 2.7.9 release.
 
 For applications which require the old previous behavior, they can pass an
 alternate context::
@@ -2670,6 +2671,29 @@ alternate context::
 
     urllib2.urlopen("https://invalid-cert", context=context)
 
+
+PEP 493: HTTPS verification migration tools for Python 2.7
+----------------------------------------------------------
+
+:pep:`493` provides additional migration tools to support a more incremental
+infrastructure upgrade process for environments containing applications and
+services relying on the historically permissive processing of server
+certificates when establishing client HTTPS connections.  These additions were
+made in the Python 2.7.12 release.
+
+These tools are intended for use in cases where affected applications and
+services can't be modified to explicitly pass a more permissive SSL context
+when establishing the connection.
+
+For applications and services which can't be modified at all, the new
+``PYTHONHTTPSVERIFY`` environment variable may be set to ``0`` to revert an
+entire Python process back to the default permissive behaviour of Python 2.7.8
+and earlier.
+
+For cases where the connection establishment code can't be modified, but the
+overall application can be, the new :func:`ssl._https_verify_certificates`
+function can be used to adjust the default behaviour at runtime.
+
 .. ======================================================================
 
 .. _acks27: