Navigation Menu

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

improve documentation of SSL deprecations #88528

Closed
graingert mannequin opened this issue Jun 9, 2021 · 8 comments
Closed

improve documentation of SSL deprecations #88528

graingert mannequin opened this issue Jun 9, 2021 · 8 comments
Labels
3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir topic-SSL type-feature A feature request or enhancement

Comments

@graingert
Copy link
Mannequin

graingert mannequin commented Jun 9, 2021

BPO 44362
Nosy @tiran, @alex, @graingert, @dstufft, @miss-islington, @jdevries3133
PRs
  • bpo-44362: ssl: improve deprecation warnings and docs (GH-26646) #26646
  • [3.10] bpo-44362: ssl: improve deprecation warnings and docs (GH-26646) #26665
    		•

    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 2021-06-09.09:02:28.288>
labels = ['expert-SSL', '3.11', 'type-feature', '3.10', 'docs']
title = 'improve documentation of SSL deprecations'
updated_at = <Date 2021-06-11.07:36:26.195>
user = 'https://github.com/graingert'

    bugs.python.org fields:

    activity = <Date 2021-06-11.07:36:26.195>
actor = 'miss-islington'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'SSL']
creation = <Date 2021-06-09.09:02:28.288>
creator = 'graingert'
dependencies = []
files = []
hgrepos = []
issue_num = 44362
keywords = ['patch']
message_count = 8.0
messages = ['395398', '395401', '395499', '395508', '395532', '395533', '395606', '395608']
nosy_count = 8.0
nosy_names = ['janssen', 'christian.heimes', 'alex', 'docs@python', 'graingert', 'dstufft', 'miss-islington', 'jack__d']
pr_nums = ['26646', '26665']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue44362'
versions = ['Python 3.10', 'Python 3.11']
    @graingert
    Copy link
    Mannequin Author

    graingert mannequin commented Jun 9, 2021

    I can see in the 3.10 release notes, that ssl.PROTOCOL_TLS becomes deprecated. Is there any further context explaining why, and what the preferred usage is instead, so that I (and anyone else) can understand this a bit more thoroughly?

    encode/httpx#1670 (comment)

    @graingert graingert mannequin added 3.10 only security fixes 3.11 only security fixes labels Jun 9, 2021
    @graingert
    Copy link
    Mannequin Author

    graingert mannequin commented Jun 9, 2021

    It's also confusing that other not deprecated flags are described in terms of this deprecated flag. These will need rewriting when the deprecated flag is removed

    @tiran tiran added docs Documentation in the Doc dir topic-SSL labels Jun 9, 2021
    @tiran tiran added type-feature A feature request or enhancement docs Documentation in the Doc dir topic-SSL labels Jun 9, 2021
    @tiran tiran added the type-feature A feature request or enhancement label Jun 9, 2021
    @jdevries3133
    Copy link
    Mannequin

    jdevries3133 mannequin commented Jun 10, 2021

    These changes are part of PEP-644; support for OpenSSL v1.1.1. The benefits are detailed in the PEP <https://www.python.org/dev/peps/pep-0644/#benefits>_.

    Later, the deprecation process began in bpo-43880 <https://bugs.python.org/issue43880>_. It seems like PROTOCOL_TLS is the only thing with a deprecation warning that does not have a suggested alternative.

    I'm confused as to how this can be deprecated; what will be the new mechanism for selecting a protocol? If someone can provide some brief clarification, I'd be more than happy to update the docs!

    @tiran
    Copy link
    Member

    tiran commented Jun 10, 2021

    You either use TLS_PROTOCOL_CLIENT for a client-side socket or TLS_PROTOCOL_SERVER for a server-side socket. TLS_PROTOCOL_CLIENT gives you a secure context for client connections with cert and hostname verification.

    @jdevries3133
    Copy link
    Mannequin

    jdevries3133 mannequin commented Jun 10, 2021

    Would you like me to submit a PR for this simple patch?

    jdevries3133@42d9bd7

    @graingert
    Copy link
    Mannequin Author

    graingert mannequin commented Jun 10, 2021

    Would you like me to submit a PR for this simple patch?

    jdevries3133@42d9bd7

    TLS_PROTOCOL_CLIENT and TLS_PROTOCOL_SERVER are defined in terms of the deprecated TLS_PROTOCOL, so now this makes the definition circular

    @tiran
    Copy link
    Member

    tiran commented Jun 11, 2021

    New changeset e26014f by Christian Heimes in branch 'main':
    bpo-44362: ssl: improve deprecation warnings and docs (GH-26646)
    e26014f

    @miss-islington
    Copy link
    Contributor

    New changeset d7930fb by Miss Islington (bot) in branch '3.10':
    bpo-44362: ssl: improve deprecation warnings and docs (GH-26646)
    d7930fb

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @slateny slateny closed this as completed May 15, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.10 only security fixes 3.11 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
    3 participants
    @tiran @miss-islington @slateny