This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Rework SSL module documentation
Type: enhancement Stage: patch review
Components: Documentation, SSL Versions: Python 3.8
Status: open Resolution:
Dependencies: Superseder:
Assigned To: 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 2022-04-11 14:58 by admin.

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)
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)
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!
Date User Action Args
2022-04-11 14:58:36adminsetgithub: 72311
2021-11-04 14:20:39erlendaaslandsetassignee: docs@python ->

nosy: + christian.heimes, docs@python, cheryl.sabella, miss-islington, - ahmedsayeed1982
components: + Documentation, SSL, - Build
versions: + Python 3.8, - Python 3.7
2021-11-04 14:18:35erlendaaslandsetmessages: - msg405713
2021-11-04 12:15:02ahmedsayeed1982setversions: - Python 3.6, Python 3.8
nosy: + ahmedsayeed1982, - christian.heimes, docs@python, cheryl.sabella, miss-islington

messages: + msg405713

components: + Build, - Documentation, SSL
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