allow passing cert/ssl information to urllib2.urlopen and httplib.HTTPSConnection
This is basically a backport of issues #9003 and #22366.
diff --git a/Doc/library/httplib.rst b/Doc/library/httplib.rst
index fcdfbc0..23b0e64 100644
--- a/Doc/library/httplib.rst
+++ b/Doc/library/httplib.rst
@@ -70,12 +70,25 @@
*source_address* was added.
-.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout[, source_address]]]]]])
+.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout[, source_address, context, check_hostname]]]]]])
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. *cert_file* is a PEM formatted
- certificate chain file.
+ secure servers. Default port is ``443``. If *context* is specified, it must
+ be a :class:`ssl.SSLContext` instance describing the various SSL options.
+
+ *key_file* and *cert_file* are deprecated, please use
+ :meth:`ssl.SSLContext.load_cert_chain` instead, or let
+ :func:`ssl.create_default_context` select the system's trusted CA
+ certificates for you.
+
+ Please read :ref:`ssl-security` for more information on best practices.
+
+ .. note::
+ 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.
@@ -88,6 +101,9 @@
.. versionchanged:: 2.7
*source_address* was added.
+ .. versionchanged:: 2.7.9
+ *context* and *check_hostname* was added.
+
.. class:: HTTPResponse(sock, debuglevel=0, strict=0)
diff --git a/Doc/library/urllib2.rst b/Doc/library/urllib2.rst
index 0411e18..65d11e1 100644
--- a/Doc/library/urllib2.rst
+++ b/Doc/library/urllib2.rst
@@ -22,13 +22,10 @@
The :mod:`urllib2` module defines the following functions:
-.. function:: urlopen(url[, data][, timeout])
+.. function:: urlopen(url[, data[, timeout[, cafile[, capath[, cadefault[, context]]]]])
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 be a POST instead of a GET when the
@@ -41,7 +38,19 @@
The optional *timeout* parameter specifies a timeout in seconds for blocking
operations like the connection attempt (if not specified, the global default
timeout setting will be used). This actually only works for HTTP, HTTPS and
- FTP connections.
+ FTP connections.
+
+ If *context* is specified, it must be a :class:`ssl.SSLContext` instance
+ describing the various SSL options. See :class:`~httplib.HTTPSConnection` for
+ more details.
+
+ 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`.
+
+ The *cadefault* parameter is ignored.
This function returns a file-like object with three additional methods:
@@ -66,7 +75,10 @@
handled through the proxy.
.. versionchanged:: 2.6
- *timeout* was added.
+ *timeout* was added.
+
+ .. versionchanged:: 2.7.9
+ *cafile*, *capath*, *cadefault*, and *context* were added.
.. function:: install_opener(opener)
@@ -280,9 +292,13 @@
A class to handle opening of HTTP URLs.
-.. class:: HTTPSHandler()
+.. class:: HTTPSHandler([debuglevel[, context[, check_hostname]]])
- 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 for :class:`httplib.HTTPSConnection`.
+
+ .. versionchanged:: 2.7.9
+ *context* and *check_hostname* were added.
.. class:: FileHandler()