Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rework SSL module documentation #72311

Closed
tiran opened this issue Sep 13, 2016 · 5 comments
Closed

Rework SSL module documentation #72311

tiran opened this issue Sep 13, 2016 · 5 comments
Labels
3.8 only security fixes docs Documentation in the Doc dir topic-SSL type-feature A feature request or enhancement

Comments

@tiran
Copy link
Member

tiran commented Sep 13, 2016

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
    Copy link
    Member Author

    tiran commented Sep 13, 2016

    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 tiran added the docs Documentation in the Doc dir label Sep 13, 2016
    @tiran tiran added 3.7 (EOL) end of life type-feature A feature request or enhancement topic-SSL labels Sep 13, 2016
    @tiran tiran added the 3.8 only security fixes label Feb 24, 2018
    @tiran
    Copy link
    Member Author

    tiran commented Feb 27, 2018

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

    @miss-islington
    Copy link
    Contributor

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

    @csabella
    Copy link
    Contributor

    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!

    @ahmedsayeed1982 ahmedsayeed1982 mannequin added build The build process and cross-build and removed docs Documentation in the Doc dir topic-SSL 3.8 only security fixes labels Nov 4, 2021
    @erlend-aasland erlend-aasland added docs Documentation in the Doc dir topic-SSL 3.8 only security fixes and removed build The build process and cross-build 3.7 (EOL) end of life labels Nov 4, 2021
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @furkanonder
    Copy link
    Sponsor Contributor

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

    @zware zware closed this as completed May 8, 2023
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.8 only security fixes docs Documentation in the Doc dir topic-SSL type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    6 participants
    @tiran @zware @erlend-aasland @furkanonder @csabella @miss-islington