Confusing behavior of ssl.create_default_context()

[piannucci]

cpython/Lib/ssl.py

Lines 697 to 703 in 8563966

	if purpose == Purpose.SERVER_AUTH:
	# verify certs and host name in client mode
	context = SSLContext(PROTOCOL_TLS_CLIENT)
	context.verify_mode = CERT_REQUIRED
	context.check_hostname = True
	elif purpose == Purpose.CLIENT_AUTH:
	context = SSLContext(PROTOCOL_TLS_SERVER)

Hello!

Got tripped up by this logic recently. It might merit clarification in the docs.

Here's what I read:

Security considerations

Best defaults

For client use, if you don’t have any special requirements for your security policy, it is highly recommended that you use the create_default_context() function to create your SSL context. It will load the system’s trusted CA certificates, enable certificate validation and hostname checking, and try to choose reasonably secure protocol and cipher settings.

Note that it suggests using create_default_context() without any arguments for client use. This is correct. It is also confusing, since the default value of purpose is Purpose.SERVER_AUTH. When I read on, this seems like the wrong option:

Changed in version 3.10: The context now uses PROTOCOL_TLS_CLIENT or PROTOCOL_TLS_SERVER protocol instead of generic PROTOCOL_TLS.

After reading this too quickly, I incorrectly assume:

• Whatever argument is passed to create_default_context() used to not matter but does matter now.
• Since I want to run PROTOCOL_TLS_CLIENT with client auth, I had better pass Purpose.CLIENT_AUTH.

In fact, CLIENT_AUTH sets PROTOCOL_TLS_SERVER and SERVER_AUTH sets PROTOCOL_TLS_CLIENT. This leads to the confusing error

>>> ssl.create_default_context(ssl.Purpose.CLIENT_AUTH).wrap_bio(ssl.MemoryBIO(), ssl.MemoryBIO())
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File ".../python3.10/ssl.py", line 527, in wrap_bio
    return self.sslobject_class._create(
  File ".../python3.10/ssl.py", line 866, in _create
    sslobj = context._wrap_bio(
ssl.SSLError: Cannot create a client socket with a PROTOCOL_TLS_SERVER context (_ssl.c:801)

Proposed resolution

I submit that it's fundamentally confusing to control protocol selection via an x509v3 extended key usage string. For instance, suppose that I anticipate two certificates with different purposes will be involved in my connection: a client certificate with CLIENT_AUTH and server certificate with SERVER_AUTH. How should I invoke ssl.create_default_context() if I am the client? If I am the server?

I submit that clearer arguments would be

• Will this context be used in a server? Default server_side=False, in accordance with the current default value of purpose.
• Will this context request and/or validate a certificate from the other party? Default cert_reqs=CERT_REQUIRED, because skipping certificate validation generally defeats the purpose of TLS.

[iritkatriel]

Please write a title that gives some idea which area of python this issue relates to.

[piannucci]

Thanks, good point.

[vadmium]

According to Git Hub issue #73996, there was a plan in 2017 to deprecate the purpose in favour of PROTOCOL_TLS_CLIENT/SERVER