From b5b8198fd1e872471f4523e0b450dfee33072242 Mon Sep 17 00:00:00 2001 From: Aaron Iles Date: Sun, 2 Feb 2014 20:14:05 +1100 Subject: [PATCH 1/3] Document requirements for SNI support on Python2 A section for Request's advanced usage guide on what Server Name Indication is, its purpose, and how to enable it on Python2. --- docs/user/advanced.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index f5e8e59f..9df9f9b1 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -179,6 +179,31 @@ If you specify a wrong path or an invalid cert:: >>> requests.get('https://kennethreitz.com', cert='/wrong_path/server.pem') SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib +Server Name Indication +---------------------- + +`Server Name Indication`_, or SNI, is an official extension to SSL where the +client tells the server what hostname it is contacting. This enables `virtual +hosting`_ on SSL protected sites. + +Python3's SSL module includes native support for SNI. This support has not been +back ported to Python2. However, Requests will enable SNI support on Python2 if +the following packages are installed: + +* `pyOpenSSL`_, a Python wrapper module around the OpenSSL library. +* `ndg-httpsclient`_, enhanced HTTPS support for httplib and urllib2. +* `pyasn1`_, ASN.1 types and codecs. + +When these packages are installed, Requests will automatically indicate to the +server what hostname is being contacted. This allows the server to return the +correct server certificate for SSL certificate verification. + +.. _`Server Name Indication`: https://en.wikipedia.org/wiki/Server_Name_Indication +.. _`virtual hosting`: https://en.wikipedia.org/wiki/Virtual_hosting +.. _`pyOpenSSL`: https://pypi.python.org/pypi/pyOpenSSL +.. _`ndg-httpsclient`: https://pypi.python.org/pypi/ndg-httpsclient +.. _`pyasn1`: https://pypi.python.org/pypi/pyasn1 + Body Content Workflow --------------------- From 8a0bae45c2efa8706c76d8af925d0dcd727cfc32 Mon Sep 17 00:00:00 2001 From: Aaron Iles Date: Sun, 2 Feb 2014 22:19:10 +1100 Subject: [PATCH 2/3] Move SNI documentation to FAQ Relocate documentation on Server-Name-Indication from the advanced section to the frequently asked questions. This is minus details on enabling SNI on Python2, which is instead captured by linking to Stack Overflow. --- docs/community/faq.rst | 22 ++++++++++++++++++++++ docs/user/advanced.rst | 27 ++------------------------- 2 files changed, 24 insertions(+), 25 deletions(-) diff --git a/docs/community/faq.rst b/docs/community/faq.rst index edbf9b70..84c6b80a 100644 --- a/docs/community/faq.rst +++ b/docs/community/faq.rst @@ -60,3 +60,25 @@ supported: * Python 3.2 * Python 3.3 * PyPy 1.9 + +What are "hostname doesn't match" errors? +----------------------------------------- + +These errors occur when :ref:`SSL certificate verification ` +fails to match the certificate the server responds with to the hostname +Requests thinks it's contacting. If you're certain the server's SSL setup is +correct (for example, because you can visit the site with your browser) a +possible explanation is Request's is lacking Server-Name-Indication. + +`Server-Name-Indication`_, or SNI, is an official extension to SSL where the +client tells the server what hostname it is contacting. This enables `virtual +hosting`_ on SSL protected sites, the server being to able to respond with a +certificate appropriate for the hostname the client is contacting. + +Python3's SSL module includes native support for SNI. This support has not been +back ported to Python2. For information on using SNI with Requests on Python2 +refer to this `Stack Overflow answer`_. + +.. _`Server-Name-Indication`: https://en.wikipedia.org/wiki/Server_Name_Indication +.. _`virtual hosting`: https://en.wikipedia.org/wiki/Virtual_hosting +.. _`Stack Overflow answer`: https://stackoverflow.com/questions/18578439/using-requests-with-tls-doesnt-give-sni-support/18579484#18579484 diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 9df9f9b1..80c1e6ae 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -145,6 +145,8 @@ applied, replace the call to :meth:`Request.prepare() print(resp.status_code) +.. _verification: + SSL Cert Verification --------------------- @@ -179,31 +181,6 @@ If you specify a wrong path or an invalid cert:: >>> requests.get('https://kennethreitz.com', cert='/wrong_path/server.pem') SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib -Server Name Indication ----------------------- - -`Server Name Indication`_, or SNI, is an official extension to SSL where the -client tells the server what hostname it is contacting. This enables `virtual -hosting`_ on SSL protected sites. - -Python3's SSL module includes native support for SNI. This support has not been -back ported to Python2. However, Requests will enable SNI support on Python2 if -the following packages are installed: - -* `pyOpenSSL`_, a Python wrapper module around the OpenSSL library. -* `ndg-httpsclient`_, enhanced HTTPS support for httplib and urllib2. -* `pyasn1`_, ASN.1 types and codecs. - -When these packages are installed, Requests will automatically indicate to the -server what hostname is being contacted. This allows the server to return the -correct server certificate for SSL certificate verification. - -.. _`Server Name Indication`: https://en.wikipedia.org/wiki/Server_Name_Indication -.. _`virtual hosting`: https://en.wikipedia.org/wiki/Virtual_hosting -.. _`pyOpenSSL`: https://pypi.python.org/pypi/pyOpenSSL -.. _`ndg-httpsclient`: https://pypi.python.org/pypi/ndg-httpsclient -.. _`pyasn1`: https://pypi.python.org/pypi/pyasn1 - Body Content Workflow --------------------- From 98b76f4b988145a98be7d865da407e150aadc165 Mon Sep 17 00:00:00 2001 From: Aaron Iles Date: Tue, 4 Feb 2014 21:08:11 +1100 Subject: [PATCH 3/3] State early in SNI discussion Python2 limitation Reference at the earliest opportunity that Server-Name-Indication is a limitation of Python 2.6 and 2.7. Avoid describing it as a Requests issue. --- docs/community/faq.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/community/faq.rst b/docs/community/faq.rst index 84c6b80a..4e792eca 100644 --- a/docs/community/faq.rst +++ b/docs/community/faq.rst @@ -67,8 +67,9 @@ What are "hostname doesn't match" errors? These errors occur when :ref:`SSL certificate verification ` fails to match the certificate the server responds with to the hostname Requests thinks it's contacting. If you're certain the server's SSL setup is -correct (for example, because you can visit the site with your browser) a -possible explanation is Request's is lacking Server-Name-Indication. +correct (for example, because you can visit the site with your browser) and +you're using Python 2.6 or 2.7, a possible explanation is that you need +Server-Name-Indication. `Server-Name-Indication`_, or SNI, is an official extension to SSL where the client tells the server what hostname it is contacting. This enables `virtual