[New-bugs-announce] [issue43582] SSLContext.sni_callback docs inaccurately describe available handshake info

[Andrew Dailey]

New submission from Andrew Dailey <steveday168 at gmail.com>:

Hello,

The documentation for SSLContext.sni_callback [0] seems to incorrectly describe the information available at that stage of the TLS handshake.

According to the docs:
Due to the early negotiation phase of the TLS connection, only limited methods and attributes are usable like SSLSocket.selected_alpn_protocol() and SSLSocket.context. SSLSocket.getpeercert(), SSLSocket.getpeercert(), SSLSocket.cipher() and SSLSocket.compress() methods require that the TLS connection has progressed beyond the TLS Client Hello and therefore will not contain return meaningful values nor can they be called safely.

This paragraph claims that SSLSocket.selected_alpn_protocol() should be usable within sni_callback but I think this is inaccurate. Based on the OpenSSL docs [1] and my own testing, the servername callback occurs after ClientHello but _before_ the ALPN callback. This prevents accurate ALPN information from being available until later. I believe that any call to SSLSocket.selected_alpn_protocol() within an SSLContext.sni_callback will simply return None.

Excerpt from the OpenSSL docs:
Several callbacks are executed during ClientHello processing, including the ClientHello, ALPN, and servername callbacks. The ClientHello callback is executed first, then the servername callback, followed by the ALPN callback.

I think it'd be better to explain that the only "useful" thing you can do within sni_callback is to see what sni_name is desired an optionally swap out the context for one with a more appropriate cert chain. Any information about the selected ALPN protocol has to wait until later in the handshake.

[0] https://docs.python.org/3/library/ssl.html#ssl.SSLContext.sni_callback
[1] https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_tlsext_servername_callback.html

----------
assignee: docs at python
components: Documentation, SSL
messages: 389231
nosy: docs at python, theandrew168
priority: normal
severity: normal
status: open
title: SSLContext.sni_callback docs inaccurately describe available handshake info
type: enhancement
versions: Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue43582>
_______________________________________