PEP 748: A Unified TLS API for Python

[woodruffw]

Current pre-PEP discussion: https://discuss.python.org/t/pre-pep-discussion-revival-of-pep-543/51263

I'm leaving this in draft while @jvdprng and I clean it up a bit -- in particular, we need to copy the latest code examples over from https://github.com/trailofbits/tlslib.py and also make sure that we didn't miss anything while converting this over from our internal doc 🙂

---

📚 Documentation preview 📚: https://pep-previews--3853.org.readthedocs.build/

[woodruffw]

CC @jvdprng: this doesn't include your rendered diagrams, yet. We'll need to add those.

[hugovk]

You can use PEP number 748.

[hugovk]

When this ready, please open a new discussion and list it here.

You can either open the discussion just before merge and add it here, or remove this line for merge, then open the discussion, and open a new PR to list it here (and in the Post-History).

[ncoghlan]

Generally looks good to me, more specific comments in line.

When the Python code is added, it may be worth moving down to a dedicated Implementation section if having it inline makes the prose too hard to read.

[ncoghlan]

What is the expected behaviour of these two APIs if the socket was created from a client context?

[jvdprng]

I think it should probably raise a generic error, as I'm not aware of situations where a TLS client would be waiting for a TLS server to make the connection. The current MVP does not handle this properly, so I should fix that.

[ncoghlan]

Likely worth explicitly stating here that libraries and applications that need interoperability with legacy ciphersuites will need to continue to use the existing OpenSSL based TLS APIs.

[ncoghlan]

Or add a sentence referring to the acceptance of raw integers covered in more detail later

[ncoghlan]

This sentence is odd. This new module would be expected to follow the same compatibility rules as the rest of the standard library (the existing SSL module exception for updating to more secure defaults over time would apply)

[woodruffw]

Agreed; I think we took this verbatim from PEP 543, so this entire "future" section probably needs to be reworked.

[glyph]

Network Framework presents some unique challenges here and may require a higher-level standardization, something that hooks into asyncio and asks the operating system for something more like "please establish a connection to a peer with these connection parameters" if we want it to fit into a truly platform-integrated-but-cross-platform system for TLS

[glyph]

It seems like it would be worth mentioning that Network Framework precludes the implementation of either TLSBuffer or TLSSocket, since there is no way to parse bytes into or out of a bytes buffer, nor any way to cause send and recv to block, as the Network Framework versions of those functions take completion handlers and require a CoreFoundation runloop to already be running.

It's a little misleading to even call Network Framework a "system TLS library", which is why it seems "restricted". Personally I find its architecture very annoying, and badly done in a lot of ways, but in its model it considers TLS to be a the same sort of layer for applications as TCP. In the same way that you can't get raw sockets and then ask the operating system's ethernet driver to assemble connection data from segments in frames with BSD sockets, you cannot ask the operating system's TLS driver to assemble connection data from TCP streams into TLS records for you.