Issue #9003: http.client.HTTPSConnection, urllib.request.HTTPSHandler and
urllib.request.urlopen now take optional arguments to allow for
server certificate checking, as recommended in public uses of HTTPS.
diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
index 6c96731..90e16a7 100644
--- a/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@ -50,19 +50,31 @@
*source_address* was added.
-.. class:: HTTPSConnection(host, port=None, key_file=None, cert_file=None, strict=None[, timeout[, source_address]])
+.. class:: HTTPSConnection(host, port=None, key_file=None, cert_file=None, strict=None[, timeout[, source_address]], *, context=None, check_hostname=None)
A subclass of :class:`HTTPConnection` that uses SSL for communication with
- secure servers. Default port is ``443``. *key_file* is the name of a PEM
- formatted file that contains your private key, and *cert_file* is a PEM
- formatted certificate chain file; both can be used for authenticating
- yourself against the server.
+ secure servers. Default port is ``443``. If *context* is specified, it
+ must be a :class:`ssl.SSLContext` instance describing the various SSL
+ options. If *context* is specified and has a :attr:`~ssl.SSLContext.verify_mode`
+ of either :data:`~ssl.CERT_OPTIONAL` or :data:`~ssl.CERT_REQUIRED`, then
+ by default *host* is matched against the host name(s) allowed by the
+ server's certificate. If you want to change that behaviour, you can
+ explicitly set *check_hostname* to False.
- .. warning::
- This does not do any verification of the server's certificate.
+ *key_file* and *cert_file* are deprecated, please use
+ :meth:`ssl.SSLContext.load_cert_chain` instead.
+
+ If you access arbitrary hosts on the Internet, it is recommended to
+ require certificate checking and feed the *context* with a set of
+ trusted CA certificates::
+
+ context = ssl.SSLContext(ssl.PROTOCOL_TLSv1)
+ context.verify_mode = ssl.CERT_REQUIRED
+ context.load_verify_locations('/etc/pki/tls/certs/ca-bundle.crt')
+ h = client.HTTPSConnection('svn.python.org', 443, context=context)
.. versionchanged:: 3.2
- *source_address* was added.
+ *source_address*, *context* and *check_hostname* were added.
.. class:: HTTPResponse(sock, debuglevel=0, strict=0, method=None, url=None)
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index a697bdd..21c1c2f 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -15,14 +15,11 @@
The :mod:`urllib.request` module defines the following functions:
-.. function:: urlopen(url, data=None[, timeout])
+.. function:: urlopen(url, data=None[, timeout], *, cafile=None, capath=None)
Open the URL *url*, which can be either a string or a
:class:`Request` object.
- .. warning::
- HTTPS requests do not do any verification of the server's certificate.
-
*data* may be a string specifying additional data to send to the
server, or ``None`` if no such data is needed. Currently HTTP
requests are the only ones that use *data*; the HTTP request will
@@ -38,6 +35,16 @@
the global default timeout setting will be used). This actually
only works for HTTP, HTTPS and FTP connections.
+ The optional *cafile* and *capath* parameters specify a set of trusted
+ CA certificates for HTTPS requests. *cafile* should point to a single
+ file containing a bundle of CA certificates, whereas *capath* should
+ point to a directory of hashed certificate files. More information can
+ be found in :meth:`ssl.SSLContext.load_verify_locations`.
+
+ .. warning::
+ If neither *cafile* nor *capath* is specified, an HTTPS request
+ will not do any verification of the server's certificate.
+
This function returns a file-like object with two additional methods from
the :mod:`urllib.response` module
@@ -62,6 +69,9 @@
Proxy handling, which was done by passing a dictionary parameter to
``urllib.urlopen``, can be obtained by using :class:`ProxyHandler` objects.
+ .. versionchanged:: 3.2
+ *cafile* and *capath* were added.
+
.. function:: install_opener(opener)
Install an :class:`OpenerDirector` instance as the default global opener.
@@ -421,9 +431,13 @@
A class to handle opening of HTTP URLs.
-.. class:: HTTPSHandler()
+.. class:: HTTPSHandler(debuglevel=0, context=None, check_hostname=None)
- A class to handle opening of HTTPS URLs.
+ A class to handle opening of HTTPS URLs. *context* and *check_hostname*
+ have the same meaning as in :class:`http.client.HTTPSConnection`.
+
+ .. versionchanged:: 3.2
+ *context* and *check_hostname* were added.
.. class:: FileHandler()