Rework SSL module documentation

[tiran]

BPO	28124
Nosy	@tiran, @csabella, @miss-islington
PRs	bpo-28124: deprecate ssl.wrap_socket() #5888 [3.7] bpo-28124: deprecate ssl.wrap_socket() (GH-5888) #5924 bpo-28124: clarify the two wrap_socket() are different #5963

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2016-09-13.10:34:00.733>
labels = ['expert-SSL', 'type-feature', '3.8', 'docs']
title = 'Rework SSL module documentation'
updated_at = <Date 2021-11-04.14:20:39.182>
user = 'https://github.com/tiran'

bugs.python.org fields:

activity = <Date 2021-11-04.14:20:39.182>
actor = 'erlendaasland'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'SSL']
creation = <Date 2016-09-13.10:34:00.733>
creator = 'christian.heimes'
dependencies = []
files = []
hgrepos = []
issue_num = 28124
keywords = ['patch']
message_count = 4.0
messages = ['276238', '312981', '312990', '337707']
nosy_count = 4.0
nosy_names = ['christian.heimes', 'docs@python', 'cheryl.sabella', 'miss-islington']
pr_nums = ['5888', '5924', '5963']
priority = 'high'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue28124'
versions = ['Python 3.8']

[tiran]

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.

[tiran]

New changeset 90f05a5 by Christian Heimes in branch 'master':
bpo-28124: deprecate ssl.wrap_socket() (bpo-5888)
90f05a5

[miss-islington]

New changeset 102d520 by Miss Islington (bot) in branch '3.7':
bpo-28124: deprecate ssl.wrap_socket() (GH-5888)
102d520

[csabella]

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!

[furkanonder]

@csabella I agree with you. Issue should be closed.