Make debugging TLS errors easier for users

Something like this: ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Hostname mismatch, certificate is not valid for 'momoshop.com.tw'. (_ssl.c:1108) is not user friendly. If we can somehow wrap and reraise common errors with links to documentation and a slightly more helpful message would be easier for users and keep people from turning off TLS verification.

What are everyone’s thoughts on this? It’s definitely a moving target and more work on our side.

[sethmlarson]

It’d be great to capture some of the common scenarios that people run into when using an HTTP library:

• Unsupported TLS version / no cipher overlap.
• Self-signed certificate
• Certificate expired
• Certificate doesn’t have subjectAltName but does have commonName
• Certificate subjectAltName and hostname don’t match.
• Certificate isn’t in their trust store.

give the user a brief message about what happened and then point them our docs via URL. At the URL we give a lot more detail, it could honestly just be a FAQ section of our docs that has a bunch of sub-topics of common pitfalls / errors that we can hand the user. (Cuz this could be applicable to other things too like DNS, ConnectionErrors, ProtocolErrors, etc even if we just tell a user to turn on debugging and create an issue if they can’t figure it out)

Things that get people to not disable TLS or hostname verification are good, because in my experience when people hit a TLS error that they don’t understand they turn off verification because at the end of the day they’re just trying to make an HTTP request.

[florimondmanca]

So, given the recent improvements to our exception handling, and that making dealing with SSL errors more user-friendly is a task that’s pretty general to Python as a whole, so anything might as well come from a third-party package, I’m going to close this off for housekeeping purposes… But I’d still agree it’d be a really nice-to-have UX-wise. Just don’t see any particular action item at this point now.