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: cheryl.sabella, christian.heimes, docs@python, miss-islington
Priority: high Keywords: patch

Created on 2016-09-13 10:34 by christian.heimes, last changed 2019-03-11 22:50 by cheryl.sabella.

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 (4)
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
msg337707 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-03-11 22:50
Can this issue be closed as resolved?  It looks like the changes have been merged even though the first PR still has an 'open' status.  Thanks!
History
Date User Action Args
2019-03-11 22:50:37cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg337707
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