PEP 748 – A Unified TLS API for Python | peps.python.org

Following system colour scheme

Selected dark colour scheme

Selected light colour scheme

PEP 748 – A Unified TLS API for Python

PEP 748 – A Unified TLS API for Python

Author:<br>Joop van de Pol ,<br>William Woodruff<br>Sponsor:<br>Alyssa Coghlan<br>Discussions-To:<br>Discourse thread<br>Status:<br>Draft<br>Type:<br>Standards Track<br>Created:<br>27-Jun-2024<br>Python-Version:<br>3.14<br>Post-History:<br>17-Apr-2024<br>Replaces:<br>543

Table of Contents<br>Abstract

Rationale<br>Problems

Proposal<br>Interfaces<br>Configuration

Context

Socket

Buffer

Cipher Suites<br>OpenSSL

Network Framework

SChannel

Network Security Services (NSS)

Proposed Interface

Protocol Negotiation

TLS Versions

Errors

Certificates

Private Keys

Signing Chain

Trust Store

Runtime Access

Insecure Usage

Changes to the Standard Library<br>Migration of the ssl module

Future

Credits

Copyright

Abstract

This PEP defines a standard TLS interface in the form of a collection of<br>protocol classes. This interface will allow Python implementations and<br>third-party libraries to provide bindings to TLS libraries other than OpenSSL.

These bindings can be used by tools that expect the interface provided by the<br>Python standard library, with the goal of reducing the dependence of the Python<br>ecosystem on OpenSSL.

Rationale

It has become increasingly clear that robust and user-friendly TLS support is an<br>extremely important part of the ecosystem of any popular programming language.<br>For most of its lifetime, this role in the Python ecosystem has primarily been<br>served by the ssl module, which provides a Python API to the OpenSSL<br>library.

Because the ssl module is distributed with the Python standard library,<br>it has become the overwhelmingly most popular method for handling TLS in Python.<br>A majority of Python libraries, both in the standard library and<br>on the Python Package Index, rely on the ssl module for their TLS<br>connectivity.

Unfortunately, the preeminence of the ssl module has had a number of<br>tied the entire Python<br>ecosystem tightly to OpenSSL. This has forced Python users to use OpenSSL even<br>in situations where it may provide a worse user experience than alternative TLS<br>implementations, which imposes a cognitive burden and makes it hard to provide<br>“platform-native” experiences.

Problems

The fact that the ssl module is built into the standard library has meant<br>that all standard-library Python networking libraries are entirely reliant on<br>the OpenSSL that the Python implementation has been linked against. This leads<br>to the following issues:

It is difficult to take advantage of new, higher-security TLS without<br>recompiling Python to get a new OpenSSL. While there are third-party bindings<br>to OpenSSL (e.g. pyOpenSSL), these<br>need to be shimmed into a format that the standard library understands,<br>forcing projects that want to use them to maintain substantial compatibility<br>layers.

Windows distributions of Python need to be shipped with a copy of<br>OpenSSL. This puts the CPython development team in the position of being<br>OpenSSL redistributors, potentially needing to ship security updates to the<br>Windows Python distributions when OpenSSL vulnerabilities are released.

macOS distributions of Python need either to be shipped with a copy<br>of OpenSSL or linked against the system OpenSSL library. Apple has formally<br>deprecated linking against the system OpenSSL library, and even if they had<br>not, that library version has been unsupported by upstream for nearly one year<br>as of the time of writing. The CPython development team has started shipping<br>newer OpenSSLs with the Python available from python.org, but this has the<br>same problem as with Windows.

Users may wish to integrate with TLS libraries other than OpenSSL for other<br>reasons, such as maintenance burden versus a system-provided implementation,<br>or because OpenSSL is simply too large and unwieldy for their platform (e.g.<br>for embedded Python). Those users are left with the requirement to use<br>third-party networking libraries that can interact with their preferred TLS<br>library or to shim their preferred library into the OpenSSL-specific<br>ssl module API.

Additionally, the ssl module as implemented today limits the ability of<br>CPython itself to add support for alternative TLS implementations, or remove<br>OpenSSL support entirely, should either of these become necessary or useful. The<br>ssl module exposes too many OpenSSL-specific function calls and features<br>to easily map to an alternative TLS implementation.

Proposal

This PEP proposes to introduce a few new Protocol Classes in Python 3.14 to<br>provide TLS functionality that is not so strongly tied to OpenSSL. It also<br>proposes to update standard library modules to use only the interface exposed by<br>these protocol classes wherever possible. There are three goals here:

To provide a common API surface for both core and third-party developers to<br>target their TLS implementations to. This allows TLS developers to provide<br>interfaces that can be used by most Python code,...