Skip to content

[3.7] bpo-32008: Prefer client or TLSv1_2 in examples (GH-5797) #16026

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Sep 12, 2019
Merged

[3.7] bpo-32008: Prefer client or TLSv1_2 in examples (GH-5797) #16026

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions Doc/library/ssl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1873,13 +1873,15 @@ to speed up repeated connections from the same clients.
:meth:`~SSLContext.wrap_socket` in order to match the hostname. Enabling
hostname checking automatically sets :attr:`~SSLContext.verify_mode` from
:data:`CERT_NONE` to :data:`CERT_REQUIRED`. It cannot be set back to
:data:`CERT_NONE` as long as hostname checking is enabled.
:data:`CERT_NONE` as long as hostname checking is enabled. The
:data:`PROTOCOL_TLS_CLIENT` protocol enables hostname checking by default.
With other protocols, hostname checking must be enabled explicitly.

Example::

import socket, ssl

context = ssl.SSLContext()
context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
context.verify_mode = ssl.CERT_REQUIRED
context.check_hostname = True
context.load_default_certs()
Expand Down Expand Up @@ -2181,19 +2183,23 @@ If you prefer to tune security settings yourself, you might create
a context from scratch (but beware that you might not get the settings
right)::

>>> context = ssl.SSLContext()
>>> context.verify_mode = ssl.CERT_REQUIRED
>>> context.check_hostname = True
>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

(this snippet assumes your operating system places a bundle of all CA
certificates in ``/etc/ssl/certs/ca-bundle.crt``; if not, you'll get an
error and have to adjust the location)

The :data:`PROTOCOL_TLS_CLIENT` protocol configures the context for cert
validation and hostname verification. :attr:`~SSLContext.verify_mode` is
set to :data:`CERT_REQUIRED` and :attr:`~SSLContext.check_hostname` is set
to ``True``. All other protocols create SSL contexts with insecure defaults.

When you use the context to connect to a server, :const:`CERT_REQUIRED`
validates the server certificate: it ensures that the server certificate
was signed with one of the CA certificates, and checks the signature for
correctness::
and :attr:`~SSLContext.check_hostname` validate the server certificate: it
ensures that the server certificate was signed with one of the CA
certificates, checks the signature for correctness, and verifies other
properties like validity and identity of the hostname::

>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
... server_hostname="www.python.org")
Expand Down