[New-bugs-announce] [issue28124] Rework SSL module documentation
Christian Heimes
report at bugs.python.org
Tue Sep 13 06:34:00 EDT 2016
New submission from Christian Heimes:
The documentation of the SSL module needs a rework. It's confusing and hard to understand even for experienced developers. The documentation should start with basic use cases and easy-to-reuse best practices.
* The module starts with move ssl.wrap_socket() but it's no longer best practice. The section should be moved down and favor of a quick introduction of SSLContext.
* ssl.create_default_context() is the best way to create a SSLContext. Mention that purpose flags and that Purpose.SERVER_AUTH is the correct setting on the client side. It means: "Create a context to authenticate the certs of a TLS server." (correct also for ftp, imap, ldap, smtp and so on).
* The protocol table is confusing and does not mention the meaning of PROTOCOL_SSLv23 (aka PROTOCOL_TLS). It's auto-negotiation of the highest TLS protocol version and takes OP_NO_* SSLContext.options into account. PROTOCOL_TLS_CLIENT and PROTOCOL_TLS_SERVER are the recommended options nowadays.
* Don't confront users with CERT_OPTIONAL in the first section. It's a super special mode for client cert authentication on the server side. On the client side, CERT_REQUIRED is the right mode with CERT_NONE as workaround. On the server side CERT_NONE (default) is usually the right setting.
* check_hostname is a client-side option that should be enabled all the time.
* Explain that users can load the public key of a self-signed certificate like a CA cert to have cert validation even for self-signed certs.
----------
assignee: docs at python
components: Documentation
messages: 276238
nosy: christian.heimes, docs at python
priority: high
severity: normal
stage: needs patch
status: open
title: Rework SSL module documentation
type: enhancement
versions: Python 3.6, Python 3.7
_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue28124>
_______________________________________
More information about the New-bugs-announce
mailing list