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() のドキュメントと、697-703 行付近の Lib/ssl.py にある関連ロジックを読み、issue に示されている Purpose.CLIENT_AUTH と Purpose.SERVER_AUTH の動作を再現してください。クライアントとサーバーの purpose の対応関係を明確にし、証明書とプロトコル選択がどのように関係するかを説明するか、API を変更すべき場合は受け入れられた代替案を文書化してください。