classification
Title: Rework SSL module documentation
Type: enhancement Stage: patch review
Components: Documentation, SSL Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: christian.heimes, docs@python, miss-islington
Priority: high Keywords: patch

Created on 2016-09-13 10:34 by christian.heimes, last changed 2018-03-03 01:09 by python-dev.

Pull Requests
URL Status Linked Edit
PR 5888 open christian.heimes, 2018-02-25 15:36
PR 5924 merged miss-islington, 2018-02-27 08:22
PR 5963 closed python-dev, 2018-03-03 01:09
Messages (3)
msg276238 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2016-09-13 10:34
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.
msg312981 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2018-02-27 08:21
New changeset 90f05a527c7d439f1d0cba80f2eb32e60ee20fc3 by Christian Heimes in branch 'master':
bpo-28124: deprecate ssl.wrap_socket() (#5888)
https://github.com/python/cpython/commit/90f05a527c7d439f1d0cba80f2eb32e60ee20fc3
msg312990 - (view) Author: miss-islington (miss-islington) Date: 2018-02-27 09:45
New changeset 102d5204add249248d1a0fa1dd3f673e884b06b4 by Miss Islington (bot) in branch '3.7':
bpo-28124: deprecate ssl.wrap_socket() (GH-5888)
https://github.com/python/cpython/commit/102d5204add249248d1a0fa1dd3f673e884b06b4
History
Date User Action Args
2018-03-03 01:09:54python-devsetpull_requests: + pull_request5731
2018-02-27 09:45:33miss-islingtonsetnosy: + miss-islington
messages: + msg312990
2018-02-27 08:22:47miss-islingtonsetpull_requests: + pull_request5695
2018-02-27 08:21:36christian.heimessetmessages: + msg312981
2018-02-25 15:36:22christian.heimessetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request5660
2018-02-24 12:55:27christian.heimessetversions: + Python 3.8
2016-09-15 07:48:41christian.heimessetcomponents: + SSL
2016-09-13 10:34:00christian.heimescreate