[issue28124] Rework SSL module documentation

[Erlend E. Aasland]

Change by Erlend E. Aasland :


--
assignee: docs@python -> 
components: +Documentation, SSL -Build
nosy: +cheryl.sabella, christian.heimes, docs@python, miss-islington 
-ahmedsayeed1982
versions: +Python 3.8 -Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[Erlend E. Aasland]

Change by Erlend E. Aasland :


--
Removed message: https://bugs.python.org/msg405713

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[Ahmed Sayeed]

Ahmed Sayeed  added the comment:

* 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).

http://www.compilatori.com/
* 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).

http://www.wearelondonmade.com/
* 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).

http://www.jopspeech.com/
* 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).

http://joerg.li/
* 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).

http://connstr.net/
* 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).

http://embermanchester.uk/
* 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).

http://www.slipstone.co.uk/
* 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).

http://www.logoarts.co.uk/
* 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).

http://www.acpirateradio.co.uk/
* 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).

https://waytowhatsnext.com/
* 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).

https://www.webb-dev.co.uk/
* 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).

http://www.iu-bloomington.com/
* 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).

http://www-look-4.com/
* 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).

https://komiya-dental.com/
* 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).

https://www.arborconsult.space/
* ssl.create_default_context() is the best way to create a SSLContext. Mention 
that pu

[issue28124] Rework SSL module documentation

[Cheryl Sabella]

Cheryl Sabella  added the comment:

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!

--
nosy: +cheryl.sabella

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[Roundup Robot]

Change by Roundup Robot :


--
pull_requests: +5731

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[miss-islington]

miss-islington  added the comment:


New changeset 102d5204add249248d1a0fa1dd3f673e884b06b4 by Miss Islington (bot) 
in branch '3.7':
bpo-28124: deprecate ssl.wrap_socket() (GH-5888)
https://github.com/python/cpython/commit/102d5204add249248d1a0fa1dd3f673e884b06b4


--
nosy: +miss-islington

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +5695

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[Christian Heimes]

Christian Heimes  added the comment:


New changeset 90f05a527c7d439f1d0cba80f2eb32e60ee20fc3 by Christian Heimes in 
branch 'master':
bpo-28124: deprecate ssl.wrap_socket() (#5888)
https://github.com/python/cpython/commit/90f05a527c7d439f1d0cba80f2eb32e60ee20fc3


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[Christian Heimes]

Change by Christian Heimes :


--
keywords: +patch
pull_requests: +5660
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[Christian Heimes]

Change by Christian Heimes :


--
versions: +Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[Christian Heimes]

Changes by Christian Heimes :


--
components: +SSL

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28124] Rework SSL module documentation

[Christian Heimes]

New submission from Christian Heimes:

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.

--
assignee: docs@python
components: Documentation
messages: 276238
nosy: christian.heimes, docs@python
priority: high
severity: normal
stage: needs patch
status: open
title: Rework SSL module documentation
type: enhancement
versions: Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com