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.

阅读 create_default_context() 文档以及 Lib/ssl.py 中 697-703 行附近的相关逻辑，然后复现 issue 中所示的 Purpose.CLIENT_AUTH 和 Purpose.SERVER_AUTH 行为。明确客户端/服务器 purpose 的映射关系，并解释证书与协议选择之间的关系；如果 API 应当变更，则记录已接受的替代方案。