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

Rework SSL module documentation #72311

Open
tiran opened this issue Sep 13, 2016 · 4 comments
Open

Rework SSL module documentation #72311

tiran opened this issue Sep 13, 2016 · 4 comments
Labels
3.8 docs expert-SSL type-feature

Comments

@tiran
Copy link
Member

@tiran tiran commented Sep 13, 2016

BPO 28124
Nosy @tiran, @csabella, @miss-islington
PRs
  • #5888
  • #5924
  • #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 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 label Sep 13, 2016
    @tiran tiran added 3.7 type-feature expert-SSL labels Sep 13, 2016
    @tiran tiran added the 3.8 label Feb 24, 2018
    @tiran
    Copy link
    Member Author

    @tiran 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

    @miss-islington miss-islington commented Feb 27, 2018

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

    @csabella
    Copy link
    Contributor

    @csabella csabella commented Mar 11, 2019

    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 and removed docs expert-SSL 3.8 labels Nov 4, 2021
    @erlend-aasland erlend-aasland added docs expert-SSL 3.8 and removed build 3.7 labels Nov 4, 2021
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.8 docs expert-SSL type-feature
    Projects
    None yet
    Development

    No branches or pull requests

    4 participants