Confusing behavior of ssl.create_default_context()

https://github.com/python/cpython/blob/8563966be4f171ccf615105ef9d3a5aa65a1de68/Lib/ssl.py#L697-L703

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.

Read the create_default_context() documentation and the linked logic in Lib/ssl.py around lines 697-703, then reproduce the Purpose.CLIENT_AUTH and Purpose.SERVER_AUTH behavior shown in the issue. Clarify the client/server purpose mapping and explain how certificates and protocol selection relate, or document the accepted alternative if the API should change.