diff options
| author | Benjamin Peterson <benjamin@python.org> | 2014-11-23 17:42:45 (GMT) |
|---|---|---|
| committer | Benjamin Peterson <benjamin@python.org> | 2014-11-23 17:42:45 (GMT) |
| commit | fcfb18ee2b754368ff005a3fec8a9fe7930ccf7d (patch) | |
| tree | d0ec3069e6f10073b55fca4ebf710a8da6123b1f /Doc | |
| parent | 5f6b89bda3cc9797186c567b6be5c6d8feedb3ec (diff) | |
| download | cpython-fcfb18ee2b754368ff005a3fec8a9fe7930ccf7d.zip cpython-fcfb18ee2b754368ff005a3fec8a9fe7930ccf7d.tar.gz cpython-fcfb18ee2b754368ff005a3fec8a9fe7930ccf7d.tar.bz2 | |
allow passing cert/ssl information to urllib2.urlopen and httplib.HTTPSConnection
This is basically a backport of issues #9003 and #22366.
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/httplib.rst | 24 | ||||
| -rw-r--r-- | Doc/library/urllib2.rst | 32 |
2 files changed, 44 insertions, 12 deletions
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 @@ The module provides the following classes: *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 @@ The module provides the following classes: .. 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 @@ redirections, cookies and more. 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 :mod:`urllib2` module defines the following functions: 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 @@ The :mod:`urllib2` module defines the following functions: 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 @@ The following classes are provided: A class to handle opening of HTTP URLs. -.. class:: HTTPSHandler() +.. class:: HTTPSHandler([debuglevel[, context[, check_hostname]]]) + + A class to handle opening of HTTPS URLs. *context* and *check_hostname* have + the same meaning as for :class:`httplib.HTTPSConnection`. - A class to handle opening of HTTPS URLs. + .. versionchanged:: 2.7.9 + *context* and *check_hostname* were added. .. class:: FileHandler() |