Specify access to transport information

Use case: I would like to access the peer certificate sent by a TLS client within my ASGI app.

Issue: As far as I can tell, no information about the transport (including TLS session information) is available to the App.

In a fork of uvicorn, I have made a patch which exposes the full transport object as part of the scope passed to the app.

diff --git a/uvicorn/protocols/http/h11_impl.py b/uvicorn/protocols/http/h11_impl.py
index 240cb35..cf5fd67 100644
--- a/uvicorn/protocols/http/h11_impl.py
+++ b/uvicorn/protocols/http/h11_impl.py
@@ -191,6 +191,7 @@ class H11Protocol(asyncio.Protocol):
                     "raw_path": raw_path,
                     "query_string": query_string,
                     "headers": self.headers,
+                    "transport": self.transport,
                 }

Within my app code, I use scope['transport'].get_extra_info("ssl_object").getpeercert(binary_form=True) to access the relevant information.

Feature request: Specify a way for applications to fetch information about the transport they are communicating over.

See also: https://github.com/encode/uvicorn/issues/400

[Jon-Work]

Here’s a proposal, for TLS extensions to the connection scope for both HTTP and Websockets (and, potentially, for other protocols that use TLS):

• tls_used (bool) – True if this connection is over TLS, false otherwise. Optional; defaults to false.

• tls_client_cert_chain (Iterable[Unicode string]) – An iterable of Unicode strings, where each string is a PEM-encoded x509 certificate. The first certificate is the client certificate. Any subsequent certificates are part of the certificate chain sent by the client, with each certificate signing the preceeding one. Only applicable if the connection was over TLS; for non-TLS connections or if the client did not provide a client certificate then it will be an empty iterable. Some web server implementations may be unable to provide this (e.g. if TLS is terminated by a separate proxy or load balancer). Optional; defaults to empty list.

• tls_server_cert (Optional[Unicode string]) – The PEM-encoded x509 certificate sent by the server when establishing the TLS connection. Only applicable if the connection was over TLS; for non-TLS connections then it will be None. Some web server implementations may be unable to provide this (e.g. if TLS is terminated by a separate proxy or load balancer). Optional; defaults to None.

• tls_client_cert_error (Optional[Unicode string]) – None if a client certificate was provided and successfully verified, or was not provided. If a client certificate was provided but verification failed, this is a non-empty string containing an error message or error code indicating why validation failed; the details are web server specific. Most web server implementations will reject the connection if the client certificate verification failed, instead of setting this value. However, some may be configured to allow the connection anyway. This is especially useful when testing that client certificates are supported properly by the client - it allows a response containing an error message that can be presented to a human, instead of just refusing the connection. Optional; defaults to None.

• tls_version (Optional[int]) – The TLS version in use. This uses the version numbers as defined in the TLS specifications, which is an unsigned integer. Common values include 0x0303 for TLS 1.2 or 0x0304 for TLS 1.3. If TLS is not in use, set to None. Some web server implementations may be unable to provide this (e.g. if TLS is terminated by a separate proxy or load balancer); in that case set to None. Optional; defaults to None.

• tls_cipher_suite (Optional[Iterable[int, int]]) – The TLS cipher suite that is being used. This is a pair of unsigned integers specified in the relevant RFC, for example [0x13, 0x01] for TLS_AES_128_GCM_SHA256. If TLS is not in use, set to None. Some web server implementations may be unable to provide this (e.g. if TLS is terminated by a separate proxy or load balancer); in that case set to None. Optional; defaults to None.

[andrewgodwin]

This ticket is basically awaiting someone to sit down and fully write out the spec as a pull request, so we can get direct feedback on the format.