[issue20913] Standard Library documentation needs SSL security best practices doc.

[Martin v. Löwis]

Martin v. Löwis added the comment:

I'm not so sure about the objection. The text currently says

CERT_NONE is the default. Since it does not authenticate the other peer, it can be insecure, especially in client mode where most of time you would like to ensure the authenticity of the server you’re talking to. Therefore, when in client mode, it is highly recommended to use CERT_REQUIRED. However, it is in itself not sufficient; you also have to check that the server certificate, which can be obtained by calling SSLSocket.getpeercert(), matches the desired service. For many protocols and applications, the service can be identified by the hostname; in this case, the match_hostname() function can be used. This common check is automatically performed when SSLContext.check_hostname is enabled.

So from that, you learn that
- check_hostname enables a common check (so you probably should enable it for that reason alone),
- the check involves verifying that the service you requested is the one identified by the hostname

If you are using the SSL module, you should be familiar with the terminology "hostname", "service","authenticate", and "peer", you should also know whether your specific protocol relies on hostnames to identify services. IMO, we *shouldn't* give an introduction to TLS in the Python documentation; that would be doomed as either being incomplete, or over the heads of most readers.

There might be other stuff that actually isn't explained at all, but check_hostname is (IMO) a bad example for that.

----------
nosy: +loewis

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue20913>
_______________________________________