[Python-checkins] peps: PEP 493: Clarify scope & deemphasise PEP 476 backport
nick.coghlan
python-checkins at python.org
Tue Dec 8 03:44:04 EST 2015
https://hg.python.org/peps/rev/17e0e36cbc19
changeset: 6139:17e0e36cbc19
user: Nick Coghlan <ncoghlan at gmail.com>
date: Tue Dec 08 18:43:52 2015 +1000
summary:
PEP 493: Clarify scope & deemphasise PEP 476 backport
* Scope limitations now have their own section, rather than being
part of the Rationale section
* reordered backport sections so PEP 493 backport is discussed
prior to the PEP 476 backport
* made it explicit that the PEP 476 section is aimed at "*IF* you
backport this feature, do it *this* way", so simply not implementing
that section at all is entirely PEP compliant
files:
pep-0493.txt | 402 ++++++++++++++++++++------------------
1 files changed, 207 insertions(+), 195 deletions(-)
diff --git a/pep-0493.txt b/pep-0493.txt
--- a/pep-0493.txt
+++ b/pep-0493.txt
@@ -76,17 +76,6 @@
recommendations to redistributors backporting these features to versions of
Python prior to Python 2.7.9.
-These designs are being proposed purely as tools for helping to manage the
-transition to the new default certificate handling behaviour in the context
-of Python 2.7. They are not being proposed as new features for Python 3, as
-it is expected that the vast majority of client applications affected by this
-problem without the ability to update the application itself will be Python 2
-applications.
-
-It would likely be desirable for a future version of Python 3 to allow default
-certificate handling for secure protocols to be configurable on a per-protocol
-basis, but that question is beyond the scope of this PEP.
-
Alternatives
------------
@@ -105,6 +94,21 @@
regardless of the formal status of the PEP
+Scope Limitations
+=================
+
+These changes are being proposed purely as tools for helping to manage the
+transition to the new default certificate handling behaviour in the context
+of Python 2.7. They are not being proposed as new features for Python 3, as
+it is expected that the vast majority of client applications affected by this
+problem without the ability to update the application itself will be Python 2
+applications.
+
+It would likely be desirable for a future version of Python 3 to allow the
+default certificate handling for secure protocols to be configurable on a
+per-protocol basis, but that question is beyond the scope of this PEP.
+
+
Requirements for capability detection
=====================================
@@ -124,6 +128,7 @@
migration process from the original Python 2.7 HTTPS handling to the new
default behaviour.
+
Feature: Configuration API
==========================
@@ -250,191 +255,13 @@
inside an activated Python virtual environment.
-Backporting PEP 476 to earlier Python versions
-==============================================
-
-Some redistributors, most notably Linux distributions, may choose to backport
-the PEP 476 HTTPS verification changes to modified Python versions based on
-earlier Python 2 maintenance releases. In these cases, a configuration
-mechanism is needed that provides:
-
-* an opt-in model that allows the decision to enable HTTPS certificate
- verification to be made independently of the decision to upgrade to the
- Python version where the feature was first backported
-* the ability for system administrators to set the default behaviour of Python
- applications and scripts run directly in the system Python installation
-* the ability for the redistributor to consider changing the default behaviour
- of *new* installations at some point in the future without impacting existing
- installations that have been explicitly configured to skip verifying HTTPS
- certificates by default
-
-As it only affects backports to earlier releases of Python 2.7, this change is
-not proposed for inclusion in upstream CPython, but rather is offered as
-guidance to redistributors to reduce the likelihood of multiple mutually
-incompatible approaches to backporting being adopted.
-
-This approach SHOULD NOT be used for any Python installation that advertises
-itself as providing Python 2.7.9 or later, as most Python users will have the
-reasonable expectation that all such environments will validate HTTPS
-certificates by default.
-
-
-Feature detection
------------------
-
-The marker attribute on the ``ssl`` module related to this feature is::
-
- _cert_verification_config = '<path to configuration file>'
-
-This not only makes it straightforward to detect the presence (or absence) of
-the capability, it also makes it possible to programmatically determine the
-relevant configuration file name.
-
-
-Recommended modifications to the Python standard library
---------------------------------------------------------
-
-The recommended approach to backporting the PEP 476 modifications to an earlier
-point release is to implement the following changes relative to the default
-PEP 476 behaviour implemented in Python 2.7.9+:
-
-* modify the ``ssl`` module to read a system wide configuration file when the
- module is first imported into a Python process
-* define a platform default behaviour (either verifying or not verifying HTTPS
- certificates) to be used if this configuration file is not present
-* support selection between the following three modes of operation:
-
- * ensure HTTPS certificate verification is enabled
- * ensure HTTPS certificate verification is disabled
- * delegate the decision to the redistributor providing this Python version
-
-* set the ``ssl._create_default_https_context`` function to be an alias for
- either ``ssl.create_default_context`` or ``ssl._create_unverified_context``
- based on the given configuration setting.
-
-
-Recommended file location
--------------------------
-
-As the PEP authors are not aware of any vendors providing long-term support
-releases targeting Windows, Mac OS X or \*BSD systems, this approach is
-currently only specifically defined for Linux system Python installations.
-
-The recommended configuration file name on Linux systems is
-``/etc/python/cert-verification.cfg``.
-
-The ``.cfg`` filename extension is recommended for consistency with the
-``pyvenv.cfg`` used by the ``venv`` module in Python 3's standard library.
-
-
-Recommended file format
------------------------
-
-The configuration file should use a ConfigParser ini-style format with a
-single section named ``[https]`` containing one required setting ``verify``.
-
-The suggested section name is taken from the "https" URL schema passed to
-affected client APIs.
-
-Permitted values for ``verify`` are:
-
-* ``enable``: ensure HTTPS certificate verification is enabled by default
-* ``disable``: ensure HTTPS certificate verification is disabled by default
-* ``platform_default``: delegate the decision to the redistributor providing
- this particular Python version
-
-If the ``[https]`` section or the ``verify`` setting are missing, or if the
-``verify`` setting is set to an unknown value, it should be treated as if the
-configuration file is not present.
-
-
-Example implementation
-----------------------
-
-::
-
- _cert_verification_config = '/etc/python/cert-verification.cfg'
-
- def _get_https_context_factory():
- # Check for a system-wide override of the default behaviour
- context_factories = {
- 'enable': create_default_context,
- 'disable': _create_unverified_context,
- 'platform_default': _create_unverified_context, # For now :)
- }
- import ConfigParser
- config = ConfigParser.RawConfigParser()
- config.read(_cert_verification_config)
- try:
- verify_mode = config.get('https', 'verify')
- except (ConfigParser.NoSectionError, ConfigParser.NoOptionError):
- verify_mode = 'platform_default'
- default_factory = context_factories.get('platform_default')
- return context_factories.get(verify_mode, default_factory)
-
- _create_default_https_context = _get_https_context_factory()
-
-
-Security Considerations
------------------------
-
-The specific recommendations for this backporting case are designed to work for
-privileged, security sensitive processes, even those being run in the following
-locked down configuration:
-
-* run from a locked down administrator controlled directory rather than a normal
- user directory (preventing ``sys.path[0]`` based privilege escalation attacks)
-* run using the ``-E`` switch (preventing ``PYTHON*`` environment variable based
- privilege escalation attacks)
-* run using the ``-s`` switch (preventing user site directory based privilege
- escalation attacks)
-* run using the ``-S`` switch (preventing ``sitecustomize`` based privilege
- escalation attacks)
-
-The intent is that the *only* reason HTTPS verification should be getting
-turned off system wide when using this approach is because:
-
-* an end user is running a redistributor provided version of CPython rather
- than running upstream CPython directly
-* that redistributor has decided to provide a smoother migration path to
- verifying HTTPS certificates by default than that being provided by the
- upstream project
-* either the redistributor or the local infrastructure administrator has
- determined that it is appropriate to override the default upstream behaviour
- (at least for the time being)
-
-Using an administrator controlled configuration file rather than an environment
-variable has the essential feature of providing a smoother migration path, even
-for applications being run with the ``-E`` switch.
-
-Interaction with Python virtual environments
---------------------------------------------
-
-This setting is scoped by the interpreter installation and affects all Python
-processes using that interpreter, regardless of whether or not the interpreter
-is being run inside an activated Python virtual environment.
-
-Origins of this recommendation
-------------------------------
-
-This recommendation is based on the backporting approach adopted for Red Hat
-Enterprise Linux 7.2, as published in the original July 2015 draft of this PEP
-and described in detail in `this KnowledgeBase article
-<https://access.redhat.com/articles/2039753>`__. Red Hat's patches implementing
-this backport for Python 2.7.5 can be found in the `CentOS git repository
-<https://git.centos.org/commit/rpms!python.git/refs!heads!c7>`__.
-
-
Backporting this PEP to earlier Python versions
===============================================
-The configuration file based backport described above is designed to cover
-backporting the PEP 476 changes to default certificate handling without the
-additional configuration mechanisms defined in this PEP.
-
-If this PEP is accepted, then an additional backporting option becomes
-available, which is to backport the per-process configuration mechanisms
-defined in this PEP, without backporting the ability to change the default behaviour of the overall Python installation.
+If this PEP is accepted, then commercial Python redistributors may choose to
+backport the per-process configuration mechanisms defined in this PEP to base
+versions older than Python 2.7.9, *without* also backporting PEP 476's change
+to the default behaviour of the overall Python installation.
Such a backport would differ from the mechanism proposed in this PEP solely in
the default behaviour when ``PYTHONHTTPSVERIFY`` was not set at all: it would
@@ -444,7 +271,6 @@
set to anything *other* than ``'0'``, then HTTPS certificate verification
should be enabled.
-
Feature detection
-----------------
@@ -506,12 +332,198 @@
inside an activated Python virtual environment.
+Backporting PEP 476 to earlier Python versions
+==============================================
+
+The backporting approach described above leaves the default HTTPS certificate
+verification behaviour of a Python 2.7 installation unmodified: verifying
+certificates still needs to be opted into on a per-connection or per-process
+basis.
+
+To allow the default behaviour of the entire installation to be modified
+without breaking backwards compatibility, Red Hat designed a configuration
+mechanism for the system Python 2.7 installation in Red Hat Enterprise Linux
+7.2+ that provides:
+
+* an opt-in model that allows the decision to enable HTTPS certificate
+ verification to be made independently of the decision to upgrade to the
+ operating system version where the feature was first backported
+* the ability for system administrators to set the default behaviour of Python
+ applications and scripts run directly in the system Python installation
+* the ability for the redistributor to consider changing the default behaviour
+ of *new* installations at some point in the future without impacting existing
+ installations that have been explicitly configured to skip verifying HTTPS
+ certificates by default
+
+As it only affects backports to earlier releases of Python 2.7, this change is
+not proposed for inclusion in upstream CPython, but rather is offered as
+a recommendation to other redistributors that choose to offer a similar feature
+to their users.
+
+This PEP doesn't take a position on whether or not this particular change is a
+good idea - rather, it suggests that *if* a redistributor chooses to go down
+the path of making the default behaviour configurable in a version of Python
+older than Python 2.7.9, then maintaining a consistent approach across
+redistributors would be beneficial for users.
+
+However, this approach SHOULD NOT be used for any Python installation that
+advertises itself as providing Python 2.7.9 or later, as most Python users
+will have the reasonable expectation that all such environments will verify
+HTTPS certificates by default.
+
+
+Feature detection
+-----------------
+
+The marker attribute on the ``ssl`` module related to this feature is::
+
+ _cert_verification_config = '<path to configuration file>'
+
+This not only makes it straightforward to detect the presence (or absence) of
+the capability, it also makes it possible to programmatically determine the
+relevant configuration file name.
+
+
+Recommended modifications to the Python standard library
+--------------------------------------------------------
+
+The recommended approach to backporting the PEP 476 modifications to an earlier
+point release is to implement the following changes relative to the default
+PEP 476 behaviour implemented in Python 2.7.9+:
+
+* modify the ``ssl`` module to read a system wide configuration file when the
+ module is first imported into a Python process
+* define a platform default behaviour (either verifying or not verifying HTTPS
+ certificates) to be used if this configuration file is not present
+* support selection between the following three modes of operation:
+
+ * ensure HTTPS certificate verification is enabled
+ * ensure HTTPS certificate verification is disabled
+ * delegate the decision to the redistributor providing this Python version
+
+* set the ``ssl._create_default_https_context`` function to be an alias for
+ either ``ssl.create_default_context`` or ``ssl._create_unverified_context``
+ based on the given configuration setting.
+
+
+Recommended file location
+-------------------------
+
+As the PEP authors are not aware of any vendors providing long-term support
+releases targeting Windows, Mac OS X or \*BSD systems, this approach is
+currently only specifically defined for Linux system Python installations.
+
+The recommended configuration file name on Linux systems is
+``/etc/python/cert-verification.cfg``.
+
+The ``.cfg`` filename extension is recommended for consistency with the
+``pyvenv.cfg`` used by the ``venv`` module in Python 3's standard library.
+
+
+Recommended file format
+-----------------------
+
+The configuration file should use a ConfigParser ini-style format with a
+single section named ``[https]`` containing one required setting ``verify``.
+
+The suggested section name is taken from the "https" URL schema passed to
+affected client APIs.
+
+Permitted values for ``verify`` are:
+
+* ``enable``: ensure HTTPS certificate verification is enabled by default
+* ``disable``: ensure HTTPS certificate verification is disabled by default
+* ``platform_default``: delegate the decision to the redistributor providing
+ this particular Python version
+
+If the ``[https]`` section or the ``verify`` setting are missing, or if the
+``verify`` setting is set to an unknown value, it should be treated as if the
+configuration file is not present.
+
+
+Example implementation
+----------------------
+
+::
+
+ _cert_verification_config = '/etc/python/cert-verification.cfg'
+
+ def _get_https_context_factory():
+ # Check for a system-wide override of the default behaviour
+ context_factories = {
+ 'enable': create_default_context,
+ 'disable': _create_unverified_context,
+ 'platform_default': _create_unverified_context, # For now :)
+ }
+ import ConfigParser
+ config = ConfigParser.RawConfigParser()
+ config.read(_cert_verification_config)
+ try:
+ verify_mode = config.get('https', 'verify')
+ except (ConfigParser.NoSectionError, ConfigParser.NoOptionError):
+ verify_mode = 'platform_default'
+ default_factory = context_factories.get('platform_default')
+ return context_factories.get(verify_mode, default_factory)
+
+ _create_default_https_context = _get_https_context_factory()
+
+
+Security Considerations
+-----------------------
+
+The specific recommendations for this backporting case are designed to work for
+privileged, security sensitive processes, even those being run in the following
+locked down configuration:
+
+* run from a locked down administrator controlled directory rather than a normal
+ user directory (preventing ``sys.path[0]`` based privilege escalation attacks)
+* run using the ``-E`` switch (preventing ``PYTHON*`` environment variable based
+ privilege escalation attacks)
+* run using the ``-s`` switch (preventing user site directory based privilege
+ escalation attacks)
+* run using the ``-S`` switch (preventing ``sitecustomize`` based privilege
+ escalation attacks)
+
+The intent is that the *only* reason HTTPS verification should be getting
+turned off installation wide when using this approach is because:
+
+* an end user is running a redistributor provided version of CPython rather
+ than running upstream CPython directly
+* that redistributor has decided to provide a smoother migration path to
+ verifying HTTPS certificates by default than that being provided by the
+ upstream project
+* either the redistributor or the local infrastructure administrator has
+ determined that it is appropriate to retaing the default pre-2.7.9 behaviour
+ (at least for the time being)
+
+Using an administrator controlled configuration file rather than an environment
+variable has the essential feature of providing a smoother migration path, even
+for applications being run with the ``-E`` switch.
+
+Interaction with Python virtual environments
+--------------------------------------------
+
+This setting is scoped by the interpreter installation and affects all Python
+processes using that interpreter, regardless of whether or not the interpreter
+is being run inside an activated Python virtual environment.
+
+Origins of this recommendation
+------------------------------
+
+This recommendation is based on the backporting approach adopted for Red Hat
+Enterprise Linux 7.2, as published in the original July 2015 draft of this PEP
+and described in detail in `this KnowledgeBase article
+<https://access.redhat.com/articles/2039753>`__. Red Hat's patches implementing
+this backport for Python 2.7.5 can be found in the `CentOS git repository
+<https://git.centos.org/commit/rpms!python.git/refs!heads!c7>`__.
+
+
Recommendation for combined feature backports
=============================================
If a redistributor chooses to backport the environment variable based
configuration setting from this PEP to a modified Python version that also
-implements the configuration file based PEP 476 , then the environment
+implements the configuration file based PEP 476 backport, then the environment
variable should take precedence over the system-wide configuration setting.
This allows the setting to be changed for a given user or application,
regardless of the installation-wide default behaviour.
--
Repository URL: https://hg.python.org/peps
More information about the Python-checkins
mailing list